Waveform

Building a custom player but want production-ready waveform visualization? The waveform is available as a standalone component — load only what you need, style it however you want, and wire it into your own playback logic.

Usage

Load the standalone waveform component via CDN, then set the levels property with amplitude data from the play session API response at first_track.levels.

<script type="module" src="https://components.audiodelivery.net/waveform.js"></script>

<audiodn-waveform
  variant="vertical"
  height="100"
  line-width="2"
  gap="3"
  progress="0.6"
></audiodn-waveform>

// Fetch level data from the play session API
const res = await fetch('/v1/play-session/track/TRACK_ID', {
  headers: { 'Authorization': 'Bearer YOUR_API_KEY' }
});
const { first_track } = await res.json();

const waveform = document.querySelector('audiodn-waveform');
waveform.levels = first_track.levels.levels;

Attributes

Attribute	Type	Default	Description
`levels`	number[]	`[]`	Array of 0–1 amplitude values (set via JS property)
`variant`	string	`"vertical"`	Render style: `"vertical"` bars or `"wave"` line
`height`	number	`120`	Canvas height in pixels
`line-width`	number	`2`	Width of each waveform bar or the wave stroke
`line-color`	string	`"#888888"`	Stroke color (overridden by CSS variable `--adn-waveform-color-fg`)
`gap`	number	`3`	Spacing between bars in the vertical variant
`scale-strength`	number	`0.4`	Controls amplitude scaling — lower values compress quiet/loud range
`progress`	number	`0`	Playback progress position (0–1)
`duration`	number	`0`	Track duration in seconds

Vertical

Default vertical bar style. Configurable line-width, gap, and height via attributes.

<audiodn-waveform
  variant="vertical"
  height="100"
  line-width="2"
  gap="3"
  progress="0.6"
></audiodn-waveform>

// Level data is returned by the play session API:
// GET /v1/play-session/:scope/:id
// Response: { first_track: { levels: { levels: [...], min, max, avg } } }

const { levels } = response.first_track;

const waveform = document.querySelector('audiodn-waveform');
waveform.levels = levels.levels; // array of 0–1 amplitude values

// Frameworks with property bindings (Vue, React, Svelte, Angular, etc.)
// can pass levels directly — no querySelector needed:
//   Vue:    <audiodn-waveform :levels="levels.levels" />
//   React:  <audiodn-waveform ref={r => r && (r.levels = data)} />

Wavy

Smooth curved wave style using variant="wavy".

<audiodn-waveform
  variant="wavy"
  height="100"
  line-width="2"
  gap="3"
  progress="0.35"
></audiodn-waveform>

const { levels } = response.first_track;

const waveform = document.querySelector('audiodn-waveform');
waveform.levels = levels.levels;

Thin Lines

Narrow bars with tight spacing: line-width="1", gap="1". No progress set — the waveform renders at half opacity with no playhead.

<audiodn-waveform
  variant="vertical"
  height="80"
  line-width="1"
  gap="1"
></audiodn-waveform>

Thick Wavy

Wide wavy curves with generous spacing: line-width="4", gap="6". No progress set — the waveform renders at half opacity with no playhead.

<audiodn-waveform
  variant="wavy"
  height="80"
  line-width="4"
  gap="6"
></audiodn-waveform>

Playhead

Shows a playhead position at 40% with highlight overlay.

<audiodn-waveform
  variant="vertical"
  height="100"
  line-width="2"
  gap="3"
  progress="0.4"
></audiodn-waveform>

Themes

Override CSS custom properties on the host to restyle the waveform. All properties use the --adn-waveform-* prefix, with --adn-color-accent as a shared fallback for the line color.

Light / Dark (system preference)

.theme-wf-lightdark {
  --adn-waveform-color-fg: light-dark(#333, #ccc);
  --adn-waveform-color-playhead: light-dark(#333, #eee);
  --adn-waveform-playhead-width: 2px;
  --adn-waveform-bg: light-dark(#f5f5f5, #1a1a1a);
  --adn-waveform-border: 1px solid light-dark(#ddd, #333);
  --adn-waveform-radius: 8px;
  --adn-waveform-padding: 8px;
}

Midnight

.theme-wf-midnight {
  --adn-waveform-color-fg: #7c3aed;
  --adn-waveform-color-playhead: #a78bfa;
  --adn-waveform-playhead-width: 2px;
  --adn-waveform-bg: #1a1a2e;
  --adn-waveform-border: 1px solid #3a3a5e;
  --adn-waveform-radius: 12px;
  --adn-waveform-padding: 12px;
}

Electric

.theme-wf-electric {
  --adn-waveform-color-fg: #00d4ff;
  --adn-waveform-color-playhead: #e040fb;
  --adn-waveform-playhead-width: 3px;
  --adn-waveform-bg: #0a0a0f;
  --adn-waveform-border: 1px solid #00d4ff33;
  --adn-waveform-radius: 4px;
  --adn-waveform-padding: 8px;
}