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