# Customizing the Arc Audio Player

Source: https://dev.arcxp.com/audio-center/tutorials/configuring-the-audio-player/

Embed and customize the Arc Audio Player for accessible, modern audio playback with built-in waveform support.

This tutorial explains how to embed and customize the **Arc Audio Player** for high-quality, accessible audio playback, including built-in waveform support: no third-party components needed.

> **Note:**
> 
> This guide assumes you have already created an audio clip and have access to your Arc XP organization’s API token, as shown in [Creating an Audio Clip](https://dev.arcxp.com/audio-center/tutorials/creating-an-audio-clip/).

## Requirements

- You have published your audio content and have:  
  - a valid audio `media-id`
  - your organization ID (`org-id`)
  - your Arc XP API token (`arc-token`)
- The environment for playback (`env`: `"prod"` or `"sandbox"`).

## Recommended usage

Use the `<arc-audio-player>` element, which renders the full player: play and pause, scrubbing, volume, and time display. Pass your authentication and configuration as individual attributes:

```html
<arc-audio-player
  media-id="YOUR_AUDIO_CLIP_ID"
  org-id="YOUR_ORG_ID"
  env="prod"
  arc-token="YOUR_API_TOKEN"
  show-waveform
></arc-audio-player>
```

- `media-id`: The unique ID for your audio clip.
- `org-id`: Your Arc XP organization ID.
- `env`: The playback environment: `"prod"` (the default) or `"sandbox"`.
- `arc-token`: Your Arc XP API token, used to authenticate the request that loads the clip.
- `show-waveform`: Enables the native waveform display (recommended for best UX).

You can also supply `org-id` and `env` inside a single `config` JSON attribute. The `config` attribute is optional; when present, it overrides the individual attributes:

```html
<arc-audio-player
  media-id="YOUR_AUDIO_CLIP_ID"
  config='{"orgId":"YOUR_ORG_ID","env":"prod"}'
  arc-token="YOUR_API_TOKEN"
  show-waveform
></arc-audio-player>
```

> **Caution:**
> 
> Do not set both `media-id` and `stream` at the same time. Prefer `media-id`, and give a valid `arc-token` for authentication whenever you use it — `stream` playback doesn’t call the Audio Center API and doesn’t need one.

## Choose a player element

- `<arc-audio-player>`: the standard player with the full control bar (play/pause, seek, volume, time display). Recommended for most embeds.
- `<arc-card-audio-player>`: a compact, artwork-style card showing a single play button over the waveform; seek by clicking the waveform. Give it a fixed `style` size.

The card player takes the same core attributes as the standard player (`media-id`, `org-id`, `env`, `arc-token`), plus a fixed `style` size. It renders a single play button over the waveform and does not have a control bar, so `hide` has no effect on it:

```html
<arc-card-audio-player
  media-id="YOUR_AUDIO_CLIP_ID"
  org-id="YOUR_ORG_ID"
  env="prod"
  arc-token="YOUR_API_TOKEN"
  show-waveform
  style="width:120px;height:120px;"
></arc-card-audio-player>
```

## Hide controls

To remove individual controls from the standard player, list them in a comma-separated `hide` attribute (or a `hideOptions` array inside `config`):

```html
<arc-audio-player media-id="YOUR_AUDIO_CLIP_ID" org-id="YOUR_ORG_ID" arc-token="YOUR_API_TOKEN" hide="VolumeRange,PlaybackRate"></arc-audio-player>
```

Valid control names: `PlayButton`, `TimeDisplay`, `CaptionsButton`, `TimeRange`, `PlaybackRate`, `MuteButton`, `VolumeRange`, `FullScreen`, `LiveIndicator`, `SeekForward`, `SeekBackward`.

## Thumbnail artwork on the card player

The card player accepts a `thumbnail-url` attribute to show cover art as the card background:

```html
<arc-card-audio-player
  media-id="YOUR_AUDIO_CLIP_ID"
  org-id="YOUR_ORG_ID"
  arc-token="YOUR_API_TOKEN"
  thumbnail-url="https://example.com/cover.jpg"
  style="width:120px;height:120px;"
></arc-card-audio-player>
```

When you set `thumbnail-url`, it takes precedence over the waveform: the player shows the artwork instead of the waveform even if `show-waveform` is present.

## Play a direct stream

Instead of a `media-id`, you can point the player at a direct audio URL with the `stream` attribute. Direct-stream playback bypasses the Audio Center API entirely and skips analytics recording; `stream` and `media-id` are mutually exclusive.

```html
<arc-audio-player stream="https://example.com/audio.mp3"></arc-audio-player>
```

To draw the scrubber for a direct stream, supply pre-computed waveform data as a JSON `waveform` attribute.

## Customization and theming

You can style the player with CSS variables:

```css
arc-audio-player {
  --border-radius: 8px;
  --waveform-background-color: #18181b;
  --waveform-center-line-color: #313131;
  --waveform-played-color: #51e9c2;
}
```

Add more styles as needed to match your brand.

## Full list of CSS variables

You can customize the look and feel of the audio players and their waveforms by using these CSS custom properties, set directly on `<arc-audio-player>`, `<arc-card-audio-player>`, or a wrapper element.

```css
arc-audio-player, arc-card-audio-player {
  --border-radius: 10px;
  --waveform-background-color: #758ef0;
  --waveform-center-line-color: #313131;
  --waveform-played-color: #48bb78;
  --waveform-unplayed-color: #ccc;
  --waveform-bar-thickness: 0.7;
  --waveform-aspect-ratio: 4;
  --waveform-play-button-background: rgba(255,255,255,0.2);
  --media-icon-color: #fff;
  /* Loading and general UI */
  --arc-player-loading-background: #bec2d9;
  --arc-player-loading-color: #16162a;
  --arc-player-loading-track-color: rgba(22,22,42,0.15);
  --arc-player-loading-indicator-color: #16162a;
}
```

### Waveform colors

- `--waveform-background-color`: Waveform background fill.
- `--waveform-center-line-color`: Line color through waveform center.
- `--waveform-played-color`: Elapsed (played) part.
- `--waveform-unplayed-color`: Remaining (unplayed) part.
- `--waveform-play-button-background`: Play button background when overlaid. Card player only; has no effect on `<arc-audio-player>`.

### Waveform sizing

- `--waveform-bar-thickness`: Thickness of each waveform bar (e.g., `0.5`).
- `--waveform-aspect-ratio`: Waveform aspect ratio (e.g., `4`).
- `--waveform-width` / `--waveform-height`: Explicit waveform dimensions (default `100%`).

### Card and player general

- `--border-radius`: Border radius for player UI containers.
- `--media-icon-color`: Icon color for player controls.
- `--div-background-color`: Card background tint on the card player (default `rgba(0, 0, 0, 0.4)`).

### Loader

- `--arc-player-loading-background`: Loader background.
- `--arc-player-loading-color`: Loader foreground/text.
- `--arc-player-loading-track-color`: Spinner unfilled part.
- `--arc-player-loading-indicator-color`: Spinner active/filled part.

### Error state

- `--arc-player-error-background`: Background of the error panel.
- `--arc-player-error-text`: Error message text color.
- `--arc-player-error-icon-color`: Error icon color.
- `--arc-player-error-icon-contrast`: Error icon contrast color.

### Further customization with Media Chrome

[media-chrome](https://media-chrome.org/) powers the Arc Audio Player, exposing CSS variables for theming controls, sliders, time displays, and more. For an extensive list and usage examples, see [Media Chrome: Styling with CSS Variables](https://www.media-chrome.org/docs/en/styling#styling-with-css-variables).

## Tips

- The player will display waveform data if available (and you set `show-waveform`).
- The `config` attribute takes precedence and will override separate attributes such as `org-id` and `env`.
- Playback analytics run automatically when the player loads a clip by `media-id` (which also requires `org-id`). They do **not** run for direct `stream` playback. To opt out and configure custom analytics tracking instead, add the `disable-default-analytics` attribute. Note that `arc-token` only authenticates the clip request; it does not control analytics.

## References

- [Creating an Audio Clip](https://dev.arcxp.com/audio-center/tutorials/creating-an-audio-clip/)