# Waveform-Komponente | AudioDN Docs

> Eigenständige Wellenform-Visualisierungskomponente mit mehreren Zeichenstilen, darunter vertikale Balken, wellenförmige Kurven, geneigte Reflexionen und Abspielpositions-Indikatoren.

Source: https://audiodeliverynetwork.com/de/docs/components/waveform/

---

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