Skip to content
Arc XP

Customizing the Arc Audio Player

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.

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").

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:

<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:

<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>

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.
  • <koi-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.

<arc-audio-player> is an alias of the underlying koi-audio-player element, and <arc-video-player> is the video counterpart, so prefer the arc-* names.

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:

<koi-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;"
></koi-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):

<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:

<koi-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;"
></koi-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.

<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:

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>, <koi-card-audio-player>, or a wrapper element.

arc-audio-player, koi-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 */
  --koi-loading-background: #bec2d9;
  --koi-loading-color: #16162a;
  --koi-loading-track-color: rgba(22,22,42,0.15);
  --koi-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

  • --koi-loading-background: Loader background.
  • --koi-loading-color: Loader foreground/text.
  • --koi-loading-track-color: Spinner unfilled part.
  • --koi-loading-indicator-color: Spinner active/filled part.

Error state

  • --koi-error-background: Background of the error panel.
  • --koi-error-text: Error message text color.
  • --koi-error-icon-color: Error icon color.
  • --koi-error-icon-contrast: Error icon contrast color.

Further customization with Media Chrome

media-chrome 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.

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