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

Install from npm and import the standalone waveform component, then set the levels property with amplitude data from the play session API response at first_track.levels.

npm install @audiodn/components

import '@audiodn/components/waveform'

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

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

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

// Create a play session; its response includes the first track's level data.
const res = await fetch('https://api.audiodelivery.net/v1/play_session/track', {
method: 'POST',
headers: {
  'Authorization': 'Bearer YOUR_API_KEY',
  'Content-Type': 'application/json'
},
body: JSON.stringify({ track_id: 'TRACK_ID' })
});
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, `“wavy”` curves, or `“reflection”` bars with a leaning mirrored reflection
`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
`reflection-angle`	number	`45`	`reflection` only: max lean of the reflection in degrees, reached at 0% / 100% progress
`reflection-size`	number	`0.25`	`reflection` only: reflection height as a fraction of the main waveform height
`reflection-opacity`	number	`0.55`	`reflection` only: opacity of the reflection at the baseline (fades to 0 downward)
`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:
// POST /v1/play_session/:scope
// 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;

Reflection

Flat-bottomed bars with a shorter, faded mirror image beneath, set with variant=“reflection”. The reflection leans according to progress — it sweeps from right to left as playback moves from start (0) to end (1), giving the waveform a subtle sense of motion. Tune it with reflection-angle, reflection-size, and reflection-opacity.

<audiodn-waveform
variant="reflection"
height="100"
line-width="2"
gap="3"
progress="0.3"
reflection-angle="45"
reflection-size="0.25"
reflection-opacity="0.55"
></audiodn-waveform>

const { levels } = response.first_track;

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

// Update progress as the track plays — the reflection leans with it:
waveform.progress = currentTime / duration;

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