Player

Audio player component with cover art, waveform, and tracklist support.

Usage

Install from npm and import the component, then drop the element into your page. Provide a Client-Side API key and point it at a track or collection.

npm install @audiodn/components

import '@audiodn/components/player'

<audiodn-player
  api-key="YOUR_API_KEY"
  scope="collection"
  id="COLLECTION_ID"
  variants="hq,lq"
  size="regular"
></audiodn-player>

Prefer no build step? Load it straight from a CDN instead:

<script type="module" src="https://unpkg.com/@audiodn/components@latest/dist/player.js"></script>

Attributes

Attribute	Type	Default	Description
`api-key`	string	—	Client-Side API key (safe to use in front-end code). Either `api-key` or `play-session-id` is required. When set, the session is automatically renewed before it expires.
`play-session-id`	string	—	Server-provisioned play session ID. Either `play-session-id` or `api-key` is required. Use this when your server creates sessions on behalf of the client.
`scope`	string	—	`"track"` for a single track or `"collection"` for a playlist
`id`	string	—	Track or collection ID to play
`variants`	string	`""`	Comma-separated list of audio quality variants (e.g. `"hq,lq"`)
`size`	string	`"large"`	Player size: `"small"`, `"regular"`, or `"large"`
`theme`	string	`"auto"`	Color theme: `"dark"` (white text on a dark background), `"light"` (dark text on a soft light-gray background), or `"auto"`. `"auto"` follows the visitor's operating system / browser `prefers-color-scheme` setting and switches live when it changes. The accent color automatically uses the contrast-safe variant (`player_color_dark` or `player_color_light`) for the active theme. Individual CSS custom properties (see Themes) still override the palette.
`volume`	number	`0.7`	Initial volume level (0–1)
`autoplay`	boolean	`false`	When present, playback starts automatically as soon as the first track has loaded. Note that browser autoplay policies may still require a user interaction before audio can play with sound.
`downloadable`	boolean	`false`	When present, a download option is shown in the settings menu for each variant. This is only a request: the API key's `is_downloadable` setting is the authoritative gate. If the key does not allow downloads, the option still renders but the download is refused and a localized "This track isn't downloadable" message is shown. Set the key's download permission from the dashboard when creating a player API key.
`session-ttl`	number	`3600`	Session time-to-live in seconds (default 3600 = 1 hour, min 60, max 86400). When `api-key` is set the session is automatically renewed before it expires.
`waveform-*`	—	—	Any waveform component attribute can be passed with a `waveform-` prefix (e.g. `waveform-variant`, `waveform-height`, `waveform-line-width`) and is forwarded to the internal waveform.

Sizes

The size attribute controls cover art, typography, and play button scaling.

Small

<audiodn-player
  api-key="YOUR_API_KEY"
  scope="track"
  id="TRACK_ID"
  variants="hq,lq"
  size="small"
></audiodn-player>

Regular

<audiodn-player
  api-key="YOUR_API_KEY"
  scope="track"
  id="TRACK_ID"
  variants="hq,lq"
  size="regular"
></audiodn-player>

Large

<audiodn-player
  api-key="YOUR_API_KEY"
  scope="track"
  id="TRACK_ID"
  variants="hq,lq"
  size="large"
></audiodn-player>

Playlist

A collection with multiple tracks and a tracklist. Uses scope="collection".

<audiodn-player
  api-key="YOUR_API_KEY"
  scope="collection"
  id="COLLECTION_ID"
  variants="hq,lq"
  size="regular"
></audiodn-player>

Themes

The quickest way to switch light and dark is the theme attribute ("auto", "dark", or "light") documented above — "auto" follows the visitor's system preference and picks the contrast-safe accent variant for you. For finer control you can still override individual CSS custom properties on the host to restyle the player without touching internals.

Light / Dark (system preference)

.theme-lightdark {
  --adn-main-border: 1px solid light-dark(#ccc, #444);
  --adn-bg: light-dark(#fff, #111);
  --adn-bg-light: light-dark(#ddd, #333);
  --adn-color-font: light-dark(#222, #eee);
  --adn-color-font-muted: light-dark(#666, #aaa);
  --adn-color-accent: light-dark(#333, #eee);
  --adn-color-accent-alt: light-dark(#fff, #111);
  --adn-waveform-color-playhead: light-dark(#333, #eee);
  --adn-waveform-playhead-width: 2px;
  --adn-coverart-filter: grayscale(100%);
}

<audiodn-player
  class="theme-lightdark"
  api-key="YOUR_API_KEY"
  scope="collection"
  id="COLLECTION_ID"
  variants="hq,lq"
  size="regular"
></audiodn-player>

Midnight

.theme-midnight {
  --adn-bg: #1a1a2e;
  --adn-bg-light: #2a2a4e;
  --adn-color-font: #e0e0e0;
  --adn-color-font-muted: #8888aa;
  --adn-color-accent: #e94560;
  --adn-color-accent-rgb: 233, 69, 96;
  --adn-color-accent-alt: #fff;
  --adn-waveform-color-playhead: #e94560;
  --adn-waveform-playhead-width: 2px;
  --adn-radius: 12px;
  --adn-padding: 0.5rem;
  --adn-coverart-transform: none;
  --adn-coverart-radius: 8px;
  --adn-playbutton-radius: 8px;
}

<audiodn-player
  class="theme-midnight"
  api-key="YOUR_API_KEY"
  scope="collection"
  id="COLLECTION_ID"
  variants="hq,lq"
  size="regular"
></audiodn-player>

Electric (single track)

.theme-electric {
  --adn-bg: #0a0a0f;
  --adn-bg-light: #16161f;
  --adn-color-font: #e4e4f0;
  --adn-color-font-muted: #7878a0;
  --adn-color-accent: #00d4ff;
  --adn-color-accent-rgb: 0, 212, 255;
  --adn-color-accent-alt: #0a0a0f;
  --adn-radius: 4px;
  --adn-main-border: 1px solid #00d4ff33;
  --adn-box-shadow: 0 0 20px #00d4ff15;
  --adn-waveform-color-playhead: #00d4ff;
  --adn-waveform-playhead-width: 2px;
  --adn-coverart-transform: none;
  --adn-coverart-radius: 2px;
  --adn-playbutton-radius: 4px;
}

<audiodn-player
  class="theme-electric"
  api-key="YOUR_API_KEY"
  scope="track"
  id="TRACK_ID"
  variants="hq,lq"
  size="regular"
></audiodn-player>