Wellenform

Sie bauen einen eigenen Player, möchten aber eine produktionsreife Wellenform-Visualisierung? Die Wellenform ist als eigenständige Komponente verfügbar — laden Sie nur, was Sie brauchen, gestalten Sie sie ganz nach Ihren Wünschen und binden Sie sie in Ihre eigene Wiedergabelogik ein.

Verwendung

Installieren Sie das Paket über npm, importieren Sie die eigenständige Waveform-Komponente und setzen Sie anschließend die Eigenschaft levels mit den Amplitudendaten aus der API-Antwort der Wiedergabesession unter 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>

Lieber ohne Build-Schritt? Laden Sie die Komponente stattdessen direkt von einem CDN:

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

Attribute

Attribut	Typ	Standard	Beschreibung
`levels`	number[]	`[]`	Array von Amplitudenwerten zwischen 0 und 1 (wird per JS-Eigenschaft gesetzt)
`variant`	string	`”vertical”`	Darstellungsstil: `“vertical”`-Balken, `“wavy”`-Kurven oder `“reflection”`-Balken mit geneigter Spiegelreflexion
`height`	number	`120`	Höhe des Canvas in Pixeln
`line-width`	number	`2`	Breite jedes Wellenform-Balkens bzw. der Wellenlinie
`line-color`	string	`”#888888”`	Linienfarbe (wird durch die CSS-Variable `—adn-waveform-color-fg` überschrieben)
`gap`	number	`3`	Abstand zwischen den Balken in der vertikalen Variante
`scale-strength`	number	`0.4`	Steuert die Amplitudenskalierung — niedrigere Werte stauchen den leisen/lauten Bereich
`reflection-angle`	number	`45`	Nur `reflection`: maximale Neigung der Reflexion in Grad, erreicht bei 0 % / 100 % Fortschritt
`reflection-size`	number	`0.25`	Nur `reflection`: Höhe der Reflexion als Anteil der Hauptwellenform-Höhe
`reflection-opacity`	number	`0.55`	Nur `reflection`: Deckkraft der Reflexion an der Grundlinie (nimmt nach unten hin auf 0 ab)
`progress`	number	`0`	Wiedergabefortschritt (0–1)
`duration`	number	`0`	Track-Dauer in Sekunden

Vertikal

Standardmäßiger vertikaler Balkenstil. line-width, gap und height lassen sich über Attribute konfigurieren.

<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

Sanft geschwungener Wellenstil mit 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

Balken mit flachem Fuß und einem kürzeren, verblassenden Spiegelbild darunter, festgelegt mit variant=“reflection”. Die Reflexion neigt sich abhängig von progress — sie schwenkt von rechts nach links, während die Wiedergabe vom Anfang (0) zum Ende (1) fortschreitet, was der Wellenform ein subtiles Gefühl von Bewegung verleiht. Feinabstimmung erfolgt über reflection-angle, reflection-size und 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;

Dünne Linien

Schmale Balken mit engem Abstand: line-width=“1”, gap=“1”. Kein progress gesetzt — die Wellenform wird mit halber Deckkraft ohne Abspielposition dargestellt.

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

Dickes Wavy

Breite wellenförmige Kurven mit großzügigem Abstand: line-width=“4”, gap=“6”. Kein progress gesetzt — die Wellenform wird mit halber Deckkraft ohne Abspielposition dargestellt.

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

Abspielposition

Zeigt eine Abspielposition bei 40 % mit einer Hervorhebungs-Überlagerung.

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

Themes

Überschreiben Sie CSS-Custom-Properties am Host-Element, um die Wellenform neu zu gestalten. Alle Eigenschaften verwenden das Präfix —adn-waveform-*, mit —adn-color-accent als gemeinsamem Fallback für die Linienfarbe.

Hell / Dunkel (Systemeinstellung)

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