CKTIS / JavaScript
AudioContext: analizar y reproducir el sonido de un elemento multimedia
Envía el sonido de un elemento de audio o vídeo a la salida mediante un analizador y controla el grafo por separado de la reproducción del medio.
Versión: ECMAScript 2024 and the current web platform; runtime support varies
Sintaxis
const ctx = new AudioContext();
const analyser = ctx.createAnalyser();
const source = ctx.createMediaElementSource(mediaElement); // HTMLMediaElement
source.connect(analyser);
analyser.connect(ctx.destination);
// In an async handler for a user action:
await Promise.all([ctx.resume(), mediaElement.play()]);
const state = ctx.state;Llama a los métodos sobre una instancia de AudioContext, no sobre el constructor. La instancia hereda createAnalyser(), state y destination de BaseAudioContext. createAnalyser() no recibe argumentos y devuelve un AnalyserNode que ofrece la forma de onda y el espectro sin alterar la señal que deja pasar. Para las muestras de la forma de onda, usa un Uint8Array de longitud fftSize; frequencyBinCount cuenta los intervalos del espectro y vale la mitad de fftSize.
createMediaElementSource(element) recibe un HTMLMediaElement existente (audio o video), no una URL. Devuelve un MediaElementAudioSourceNode y desvía el sonido del elemento al grafo. Conecta la fuente al analizador y este a ctx.destination: esta propiedad de solo lectura devuelve el AudioDestinationNode, la salida final del contexto en tiempo real. El analizador puede medir sin conexión de salida, pero esa ruta no será audible. Reutiliza el nodo fuente: volver a vincular el mismo elemento lanza InvalidStateError, y desconectar el nodo no elimina la asociación.
resume() no recibe argumentos y reanuda el reloj y el procesamiento del grafo, no la reproducción del elemento. Devuelve una Promise que se cumple al reanudarse el contexto y se rechaza si está cerrado. OfflineAudioContext.resume() es otro método, para reanudar el renderizado sin conexión a la salida en tiempo real. En el manejador de un clic real, llama a resume() y element.play() antes del primer await; gestiona rechazos como NotAllowedError de play(). Usa element.pause() para pausar el medio.
La propiedad de solo lectura state describe el contexto: running indica procesamiento, suspended indica una pausa (también por la política de reproducción automática), closed es definitivo e interrupted señala una interrupción externa cuyo tratamiento varía según el navegador. Observa statechange; running no garantiza sonido audible. El nodo fuente emite silencio si el medio se carga desde otro origen sin autorización CORS. Para un archivo público de otro origen, configura element.crossOrigin = 'anonymous' antes de src y los encabezados CORS en el servidor. Estas API son de la plataforma web, no de ECMAScript 2024; su disponibilidad depende del entorno. Cuando ya no necesites el contexto, close() libera sus recursos de audio del sistema.
Ejemplos
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Play and analyse</title>
</head>
<body>
<button id="play" type="button">Play and analyse</button>
<script>
(() => {
function makeTone() {
const rate = 8000;
const wav = new Uint8Array(44 + rate);
const view = new DataView(wav.buffer);
const text = (offset, value) => wav.set(new TextEncoder().encode(value), offset);
// One second of mono, unsigned 8-bit PCM in a WAV container.
text(0, 'RIFF');
view.setUint32(4, 36 + rate, true);
text(8, 'WAVEfmt ');
view.setUint32(16, 16, true);
view.setUint16(20, 1, true);
view.setUint16(22, 1, true);
view.setUint32(24, rate, true);
view.setUint32(28, rate, true);
view.setUint16(32, 1, true);
view.setUint16(34, 8, true);
text(36, 'data');
view.setUint32(40, rate, true);
for (let i = 0; i < rate; i++) {
wav[44 + i] = 128 + Math.round(12 * Math.sin(2 * Math.PI * 440 * i / rate));
}
return new Blob([wav], { type: 'audio/wav' });
}
const button = document.getElementById('play');
button.addEventListener('click', async () => {
button.disabled = true;
const media = new Audio();
let ctx;
let url;
try {
ctx = new AudioContext();
const analyser = ctx.createAnalyser();
analyser.fftSize = 1024;
const source = ctx.createMediaElementSource(media);
source.connect(analyser);
analyser.connect(ctx.destination);
const finished = new Promise((resolve) => {
media.onended = () => resolve(true);
media.onerror = () => resolve(false);
});
url = URL.createObjectURL(makeTone());
media.src = url;
await Promise.all([ctx.resume(), media.play()]);
const samples = new Uint8Array(analyser.fftSize);
analyser.getByteTimeDomainData(samples);
console.log(`state=${ctx.state}; samples=${samples.length}`);
if (!(await finished)) throw new Error('Media failed during playback');
} catch (error) {
console.error(error);
} finally {
media.pause();
media.removeAttribute('src');
media.load();
if (url !== undefined) URL.revokeObjectURL(url);
if (ctx && ctx.state !== 'closed') {
await ctx.close().catch((error) => console.error(error));
}
}
}, { once: true });
})();
</script>
</body>
</html>Resultado
state=running; samples=1024
Guarda el ejemplo como `index.html` y ábrelo en el navegador a través de un servidor HTTP local. Abre la consola de desarrollo y haz clic en `Play and analyse` en la página. Si hay compatibilidad con Web Audio y WAV PCM, la reproducción está permitida y no hay interrupciones, se espera un tono breve y `state=running; samples=1024`. El WAV se genera localmente. El número indica la longitud del array, no cuántas muestras son distintas de cero. Recarga para repetir.
Lecciones relacionadas
- JavaScript · Lección 34 · Avanzado · Versión: 4
Fuentes
- BaseAudioContext: createAnalyser() method
- AudioContext: createMediaElementSource() method
- AudioContext: resume() method
- BaseAudioContext: state property
- BaseAudioContext: destination property
- AnalyserNode
- AnalyserNode: getByteTimeDomainData() method
- OfflineAudioContext: resume() method
- AudioContext: close() method
- Using the Web Audio API
- HTML Living Standard — Media elements: play()
- ECMAScript 2024 Language Specification — Promise.all