# Player Component | AudioDN Docs

> Audio player component with cover art, waveform visualization, and tracklist support. Explore sizes, playlists, and theme customization.

Source: https://audiodeliverynetwork.com/docs/components/player/

---

# 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](/docs/components/waveform#waveform-usage) 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>
```