Skip to content
Arc XP

Customizing the Koi Player for Audio

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

Requirements

  • Your audio content is published and you have:
    • a valid audio media-id
    • your organization ID (orgId)
    • your Arc XP API token (arc-token)
  • The environment for playback ("prod" or "sandbox").

Use the koi-card-audio-player element as shown below, with all required authentication and configuration attributes.

<koi-card-audio-player
  media-id="YOUR_AUDIO_CLIP_ID"
  config='{"orgId":"YOUR_ORG_ID","env":"prod"}'
  arc-token="YOUR_API_TOKEN"
  show-waveform
  style="width:120px;height:120px;"
/>
  • media-id — The unique ID for your audio clip.
  • config — JSON string (required). Must contain at least your orgId and env (use "prod" for production).
  • arc-token — Your Arc XP API token.
  • show-waveform — Enables the native waveform display (recommended for best UX).
  • style — Controls the widget size.

Customization and Theming

You can style the player with CSS variables:

koi-card-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 Koi players and their waveforms using these CSS custom properties, set directly on <koi-card-audio-player>, <koi-player>, or a wrapper element.

koi-card-audio-player, koi-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-background-color — Waveform background fill.
  • --waveform-center-line-color — Line color through waveform center.
  • --waveform-played-color — Elapsed (played) portion.
  • --waveform-unplayed-color — Remaining (unplayed) portion.
  • --waveform-bar-thickness — Thickness of each waveform bar (e.g., 0.5).
  • --waveform-aspect-ratio — Waveform aspect ratio (e.g., 4).
  • --waveform-play-button-background — Play button background when overlayed.

Card and Player General

  • --border-radius — Border radius for player UI containers.
  • --media-icon-color — Icon color for player controls.

Loading State

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

Further Customization with Media Chrome

Koi is built atop media-chrome, which exposes additional CSS variables for theming controls, sliders, time displays, and more. For an extensive list and usage examples, see Media Chrome — Styling with CSS Variables.

Additional Tips

  • The player will display waveform data if available (and show-waveform is set).
  • All other player features — scrubbing, play/pause, volume — are enabled by default.
  • The config attribute takes precedence and will override separate attributes like org-id and env.
  • Analytics are enabled when you include correct config and arc-token values.

References