# Componente Waveform | Docs de AudioDN

> Componente independiente de visualización de forma de onda con varios estilos de dibujo, incluyendo barras verticales, curvas onduladas, reflexiones inclinadas e indicadores de playhead.

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

---

# Waveform

¿Estás construyendo un player personalizado pero quieres una visualización de forma de onda lista para producción? La forma de onda está disponible como componente independiente — carga solo lo que necesitas, estilízala como quieras y conéctala a tu propia lógica de reproducción.

## Uso

Instálalo desde npm e importa el componente waveform independiente, luego establece la propiedad `levels` con los datos de amplitud de la respuesta de la API de sesión de reproducción en `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>
```

¿Prefieres sin paso de build? Cárgalo directamente desde un 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;
```

### Atributos

| Atributo | Tipo | Predeterminado | Descripción |
| --- | --- | --- | --- |
| `levels` | number\[\] | `[]` | Array de valores de amplitud 0–1 (se establece vía propiedad JS) |
| `variant` | string | `”vertical”` | Estilo de renderizado: barras `“vertical”`, curvas `“wavy”` o barras `“reflection”` con una reflexión espejada inclinada |
| `height` | number | `120` | Alto del canvas en píxeles |
| `line-width` | number | `2` | Ancho de cada barra de forma de onda o del trazo de la onda |
| `line-color` | string | `”#888888”` | Color del trazo (sobrescrito por la variable CSS `—adn-waveform-color-fg`) |
| `gap` | number | `3` | Espaciado entre barras en la variante vertical |
| `scale-strength` | number | `0.4` | Controla el escalado de amplitud — valores más bajos comprimen el rango quieto/fuerte |
| `reflection-angle` | number | `45` | Solo `reflection`: inclinación máxima de la reflexión en grados, alcanzada al 0% / 100% de progreso |
| `reflection-size` | number | `0.25` | Solo `reflection`: alto de la reflexión como fracción del alto de la forma de onda principal |
| `reflection-opacity` | number | `0.55` | Solo `reflection`: opacidad de la reflexión en la línea base (se desvanece a 0 hacia abajo) |
| `progress` | number | `0` | Posición de progreso de reproducción (0–1) |
| `duration` | number | `0` | Duración de la pista en segundos |

## Vertical

Estilo predeterminado de barras verticales. `line-width`, `gap` y `height` configurables vía atributos.

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

Estilo de onda curva suave usando `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

Barras con base plana y una imagen espejo más corta y desvanecida debajo, con `variant=“reflection”`. La reflexión se inclina según `progress` — barre de derecha a izquierda a medida que la reproducción avanza del inicio (0) al final (1), dando a la forma de onda una sutil sensación de movimiento. Ajústala con `reflection-angle`, `reflection-size` y `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;
```

## Líneas finas

Barras estrechas con espaciado ajustado: `line-width=“1”`, `gap=“1”`. Sin `progress` — la forma de onda se renderiza a media opacidad sin playhead.

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

## Wavy grueso

Curvas onduladas anchas con espaciado generoso: `line-width=“4”`, `gap=“6”`. Sin `progress` — la forma de onda se renderiza a media opacidad sin playhead.

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

## Playhead

Muestra una posición de playhead al 40% con overlay de resaltado.

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

## Temas

Sobrescribe propiedades CSS personalizadas en el host para restilizar la forma de onda. Todas las propiedades usan el prefijo `—adn-waveform-*`, con `—adn-color-accent` como fallback compartido para el color de línea.

### Light / Dark (preferencia del sistema)

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