# Composant Waveform | Docs AudioDN

> Composant autonome de visualisation de forme d

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

---

# Waveform

Vous construisez un lecteur personnalisé mais voulez une visualisation de forme d’onde prête pour la production ? La forme d’onde est disponible comme composant autonome — chargez uniquement ce dont vous avez besoin, stylisez-la comme vous voulez, et branchez-la dans votre propre logique de lecture.

## Utilisation

Installez depuis npm et importez le composant waveform autonome, puis définissez la propriété `levels` avec les données d’amplitude de la réponse API de la session de lecture à `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>
```

Vous préférez sans étape de build ? Chargez-le directement depuis un CDN à la place :

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

### Attributs

| Attribut | Type | Défaut | Description |
| --- | --- | --- | --- |
| `levels` | number\[\] | `[]` | Tableau de valeurs d’amplitude 0–1 (défini via propriété JS) |
| `variant` | string | `”vertical”` | Style de rendu : barres `“vertical”`, courbes `“wavy”`, ou barres `“reflection”` avec une réflexion miroir inclinée |
| `height` | number | `120` | Hauteur du canvas en pixels |
| `line-width` | number | `2` | Largeur de chaque barre de forme d’onde ou du trait de l’onde |
| `line-color` | string | `”#888888”` | Couleur du trait (remplacée par la variable CSS `—adn-waveform-color-fg`) |
| `gap` | number | `3` | Espacement entre les barres dans la variante verticale |
| `scale-strength` | number | `0.4` | Contrôle la mise à l’échelle de l’amplitude — des valeurs plus basses compressent la plage calme/forte |
| `reflection-angle` | number | `45` | `reflection` uniquement : inclinaison max de la réflexion en degrés, atteinte à 0 % / 100 % de progression |
| `reflection-size` | number | `0.25` | `reflection` uniquement : hauteur de la réflexion comme fraction de la hauteur de la forme d’onde principale |
| `reflection-opacity` | number | `0.55` | `reflection` uniquement : opacité de la réflexion à la ligne de base (s’estompe vers 0 vers le bas) |
| `progress` | number | `0` | Position de progression de la lecture (0–1) |
| `duration` | number | `0` | Durée de la piste en secondes |

## Vertical

Style de barres verticales par défaut. `line-width`, `gap` et `height` configurables via attributs.

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

Style d’onde courbe lisse avec `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

Barres à fond plat avec une image miroir plus courte et estompée en dessous, définies avec `variant=“reflection”`. La réflexion s’incline selon `progress` — elle balaye de droite à gauche à mesure que la lecture passe du début (0) à la fin (1), donnant à la forme d’onde une subtile sensation de mouvement. Réglez-la avec `reflection-angle`, `reflection-size` et `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;
```

## Lignes fines

Barres étroites avec espacement serré : `line-width=“1”`, `gap=“1”`. Pas de `progress` défini — la forme d’onde s’affiche à mi-opacité sans tête de lecture.

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

## Wavy épais

Courbes ondulées larges avec espacement généreux : `line-width=“4”`, `gap=“6”`. Pas de `progress` défini — la forme d’onde s’affiche à mi-opacité sans tête de lecture.

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

## Tête de lecture

Affiche une position de tête de lecture à 40 % avec une superposition de surbrillance.

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

## Thèmes

Remplacez les propriétés CSS personnalisées sur l’hôte pour restyler la forme d’onde. Toutes les propriétés utilisent le préfixe `—adn-waveform-*`, avec `—adn-color-accent` comme repli partagé pour la couleur de ligne.

### Clair / Sombre (préférence système)

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