Web Audio API

Baseline Widely available *

This feature is well established and works across many devices and browser versions. Its been available across browsers since abril de 2021.

* Some parts of this feature may have varying levels of support.

Learn more
See full compatibility

La API de Audio Web provee un sistema poderoso y versatil para controlar audio en la Web, permitiendo a los desarrolladores escoger fuentes de audio, agregar efectos al audio, crear visualizaciones de audios, aplicar efectos espaciales (como paneo) y mucho ms.

Conceptos y uso de audio Web

La API de Audio Web involucra manejar operaciones de audio dentro de un contexto de audio, y ha sido diseada para permitir enrutamiento modular. Las operaciones de audio bsicas son realizadas con nodos de audio, que estn enlazados juntos para formar un grfico de enrutamiento de audio. Muchas fuentes con diferentes tipos de diseo de canales estn soportadas incluso dentro de un nico contexto. Este diseo modular provee flexibilidad para crear funciones de audio complejas con efectos dinmicos.

Los nodos de audio estn enlazados en cadenas y redes simples por sus entradas y salidas. stos tpicamente empiezan con una o ms fuentes. Las fuentes provee matrices de intensidades de sonidos (muestras) en segmentos de tiempo muy pequeos, a menudo decenas de miles de stos por segundo. stos podran ser calculados matemticamente (como OscillatorNode), o pueden ser grabaciones de archivos de audio o video (como AudioBufferSourceNode y MediaElementAudioSourceNode) y transmisiones de audio (MediaStreamAudioSourceNode). De hecho, los archivos de sonido son slo grabaciones de intensidades de sonido, que vienen desde micrfonos o instrumentos elctricos, y mezclados en una onda nica y complicada.

Los resultados de stos nodos podran ser enlazados a las entradas de otros, que mezclan o modifican estas transmisiones de muestras de audio en diferentes transmisiones. Una modificacin comn es multiplicar las muestras por un valor para hacerlas ms fuertes o silenciosas (como es el caso con GainNode). Una vez que el sonido ha sido lo suficientemente procesado por el efecto necesario, puede ser enlazados a la entrada de un destino(AudioContext.destination), que envi el sonido a los altavoces o auriculares. Esta ltima conexin slo es necesaria si el usuario debe escuchar el audio.

Un diagrama de flujo simple y tpico para el audio web se vera algo como esto:

Crear contexto de audio
Dentro del contexto, crear fuentes como <audio>, oscillator, stream
Crear nodos de efectos, tales como reverberacin, filtro biquad, panner, compresor
Escoge el destino final del audio, por ejemplo tu sistema de altavoces
Conecta las fuentes a los efectos, y los efectos al destino.

[A simple box diagram with an outer box labeled Audio context, and three inner boxes labeled Sources, Effects and Destination. The three inner boxes have arrow between them pointing from left to right, indicating the flow of audio information.]

El tiempo es controlado con alta precisin baja latencia, permitiendo a los desarrolladores escribir cdigo que responda con precisin a los eventos y sea capaz de apuntar a muestras especficas, incluso en una alta frecuencia de muestreo. Por lo tanto, las aplicaciones como las cajas de ritmos y los secuenciadores estn a su alcance.

El API de Audio Web tambin nos permite controlar cmo el audio es espacializado. Usando un sistema basado en un modelo fuente-oyente, esto permite controlar el modeo de paneo y que se ocupa de la atenuacin inducida por distancia o desplazamiento doppler inducido por una fuente en movimiento (o un oyente en movimiento).

Nota: Puedes leear sobre la teora del API de Audio Web con ms detalle en nuestro artculo Conceptos Bsicos detrs del API de Audio Web.

Interfaces del API de Audio Web

La API de Audio Web tiene un nmero de interfaces y eventos asociados, que han sido divididos en nueve categorias de funcionalidad.

Definicin general del grfico de audio

Contenedores y definiciones generales que dan forma a los grficos de audio en el uso de Web Audio API.

AudioContext: La interfaz AudioContext representa un grfico de procesamiento de audio construido de mdulos de audio enlazados juntos, cada uno representado por un AudioNode. Un contexto de audio controla la creacin de los nodos que contiene y la ejecucin del procesamiento del audio, or decoding. Necesitas crear un AudioContext antes de hacer cualquier cosa, ya que todo pasa dentro de un contexto de audio.
AudioNode: La interfaz AudioNode representa un mdulo de procesamiento de audio como una fuente de audio (por ejemplo un ejemplo HTML <audio> or <video>), destino de audio, mdulo de procesamiento intermedio (por ejemplo un filtro como BiquadFilterNode, o control de volumen como GainNode).
AudioParam: La interfaz AudioParam representa un parmetro relacionado al audio, como uno de un AudioNode. Esto puede ser establecido a un valor especfico o un cambio de valor, y puede ser agendado para que ocurra en un momento especfico y siguiendo un patrn especfico.
AudioParamMap: Provee una interfaz como para mapear a un grupo de interfaces AudioParam, lo que significa que proporciona los mtodos forEach(), get(), has(), keys(), y values(), como tambin una propiedad size.
BaseAudioContext: La interfaz BaseAudioContext acta como una definicin base para procesamiento de grficos de audio en y fuera de lnea, como lo representa AudioContext y OfflineAudioContext resepectivamente. No tendrs que usar BaseAudioContext directamente tendrs que usar sus caractersticas a travs de una de stas dos interfaces heredadas.
El evento ended: El evento ended es lanzado cuando la reproduccin se detiene porque se alcanz el fin del archivo de medio.

Definiendo fuentes de audio

Las interfaces que definen fuentes de audio para usar en la API de Web.

AudioScheduledSourceNode: La interfaz AudioScheduledSourceNode es una interfaz padre para muchos tipos de interfaces de nodos de fuentes de audio. Es un AudioNode.

OscillatorNode: La interfaz OscillatorNode representa una forma de onda peridica, como una onda sinusoidal o triangular. Es un mdulo de procesamiento de audio AudioNode que causa que se cree una frecuencia de onda determinada.
AudioBuffer: La interfaz AudioBuffer representa un recurso de audio corto que reside en la memoria, creado desde un archivo de audio usando el mtodo AudioContext.decodeAudioData(), o creado con datos sin procesar usando AudioContext.createBuffer(). Una vez decodificado en esta forma, el audio puede ser colocado en un AudioBufferSourceNode.
AudioBufferSourceNode: La interfaz AudioBufferSourceNode representa una fuente de audio que consiste en una datos de audio en la memoria, almacenada en un AudioBuffer. Es un AudioNode que acta como una fuente de audio.
MediaElementAudioSourceNode: La interfaz MediaElementAudioSourceNode representa una fuente de audio que consiste en un elemento <audio> o <video> de HTML5. Es un AudioNode que acta como una fuente de audio.
MediaStreamAudioSourceNode: La interfaz MediaStreamAudioSourceNode representa una fuente de audio que consiste en un MediaStream de WebRTC (como una cmara web, micrfono, o una transmisin siendo enviada a una computadora remota). Es un AudioNode que acta como una fuente de audio.

Definiendo filtros de efectos de audio

Interfaces para definir efectos que quieras aplicar a tus fuentes de audio.

BiquadFilterNode: La interfaz BiquadFilterNode representa una filtro de bajo orden sencillo. Es un AudioNode que puede representar diferentes tipos de filtros, dispositivos de control de tono, o ecualizadores grficos. Un BiquadFilterNode siempre tiene exactamente una entrada y una salida.
ConvolverNode: La interfaz ConvolverNode es un AudioNode que realiza una Convolucin Lineal en un AudioBuffer determinado, y es usado a menudo para lograr un efecto de reverberacin.
DelayNode: La interfaz DelayNode representa una lnea de detardo; un mdulo de procesamiento de audio de AudioNode que causa un retardo entre la llegada de una entrada de datos y su propagacin a la salida.
DynamicsCompressorNode: La intefaz DynamicsCompressorNode proporciona un efecto de compresin, que reduce el volumen de las partes ms ruidosas de la seal para ayudar a evitar el recorte y la distorsin que pueden ocurrir cuando se reproducen y multiplexan mltiples sonidos a la vez.
GainNode: La intefaz GainNode representa un cambio de volumen. Es un mdulo de procesamiento de audio de AudioNode que causa que una ganancia determinada para ser aplicada a la entrada de datos antes de su propacacin a la salida.
WaveShaperNode: La interfaz WaveShaperNode representa un la interfaz representa un distorsionador no lineal. Es un AudioNode que usa una curva para aplicar una distorsin en forma de onda a la seal. Adems de los obvios efectos de distorsin, a menudo se usa para agregar una sensacin clida a la seal.
PeriodicWave: Describe una forma de onda peridica que puede ser usada para dar forma a la salida de un OscillatorNode.
IIRFilterNode: Implementa un filtro de respuesta de pulso infinito (IIR) general; este tipo de filtro se puede usar para implementar dispositivos de control de tono y ecualizadores grficos tambin.

Definicin de destinos de audio

Una vez que haya terminado de procesar su audio, estas interfaces definen dnde emitirlo.

AudioDestinationNode: La interfaz AudioDestinationNode representa el destino final de una fuente de audio en contexto determinado usualmente los altavoces de tu dispositivo.
MediaStreamAudioDestinationNode: La interfaz MediaStreamAudioDestinationNode representa un destino de audio que consiste en un MediaStream de WebRTC con un AudioMediaStreamTrack sencillo, que puede ser usado de una manera similiar a un MediaStream obtenido desde getUserMedia(). Es un AudioNode que acta como un destino de audio.

Anlisis y visualizacin de datos

Si quieres extraer el tiempo, frecuencia, y otros datos de tu audio, AnalyserNode es lo que necesitas.

AnalyserNode: La interfaz AnalyserNode representa un nodo capz de proveer la frecuencia en tiempo real y la informacin del anlisis del dominio de tiempo, para propsitos de anlisis y visualizacin de datos.

Divisin y fusin de canales de audio

Para dividir y fusionar canales de audio, debers usar estas interfaces.

ChannelSplitterNode: La interfaz ChannelSplitterNode separa los diferentes canales de una fuente de audio enn un conjunto de salidas mono.
ChannelMergerNode: La interfaz ChannelMergerNode reune las diferentes salidas mono en una sola salida. Cada entrada deber ser usada para llenar un canal de la salida.

Espacializacin de audio

Estas interfaces te permiten agregar efectos de paneo de especializacin de audio a tus fuentes de audio.

AudioListener: La interfaz AudioListener representa la posicin y orientacin de la nica persona escuchando la escena de audio usada en la espacializacin de audio.
PannerNode: La interfaz PannerNode representa la posicin y comportamiento de una seal de fuente de audio en un espacio 3D, permitindote crear efectos de paneo complejos.
StereoPannerNode: La interfaz StereoPannerNode representa un nodo de panner estreo simple que se puede usar para panoramizar un flujo de audio hacia la izquierda o hacia la derecha.

Proccesamiento de audio en JavaScript

Usando worklets de audio (pequeas tareas), puedes definir nodos personalizados de audio escritos en JavaScript o WebAssembly. Los worklets de audios implementan la interfaz Worklet, una versin ligera de la interfaz Worker. A partir del enero de 2018, los worklets de audio estn disponibles en Chrome 64 detrs de un identificador.

AudioWorklet: La interfaz AudioWorklet est disponible a travs de BaseAudioContext.audioWorklet y te permite agregar nuevos mduloss al worklet de audio.
AudioWorkletNode: La intefaz AudioWorkletNode representa un AudioNode que est insertada en un grfico de audio y puede pasar mensajes a la AudioWorkletProcessor.
AudioWorkletProcessor: La interfaz AudioWorkletProcessor representa cdigo de procesamiento de audio que se ejecuta en un AudioWorkletGlobalScope que genera, procesa, o analiza audio directamente, y puede pasar mensajes al AudioWorkletNode.
AudioWorkletGlobalScope: La interfaz AudioWorkletGlobalScope es un objeto derivado de WorkletGlobalScope que representa un contexto del worker en el que se ejecuta un script de procesamiento de audio; est diseado para permitir la generacin, procesamiento, y anlisis de datos de audio directamente usando JavaScript en un hilo worklet.

Antes de que se definieran los worklets de audio, la API de Web Audio us ScriptProcessorNode para procesamiento de audio basado en JavaScript. Como el cdigo se ejecuta en el hilo principal, tuvo un mal rendimiento. ScriptProcessorNode se mantiene por razones histricas pero est marcada como obsoleta y ser removida en una versin futura de la especificacin.

ScriptProcessorNode: La interfaz ScriptProcessorNode permite la generacin, procesamiento, o anlisis de audio usando JavaScript. Es un mdulo de procesamiento de audio AudioNode que est enlazado a dos buffers, uno conteniendo la actual entrada, uno conteniendo la salida. Un evento, implementando la interfaz AudioProcessingEvent, es enviado al objeto cada vez que el buffer de entrada contiene nuevos datos, y el manejador del evento termina cuando ha llenado el buffer de salida con datos.
audioprocess (event): El evento audioprocess es lanzado cuando un buffer de entrada de un ScriptProcessorNode del API del Audio Web est listo para ser procesado.
AudioProcessingEvent: El evento AudioProcessingEvent del API de Audio Web representa los eventos que ocurren cuando un buffer de entrada ScriptProcessorNode est listo para ser procesado.

Procesamiento de audio offline/en segundo plano

Es posible procesar/renderizar un grfico de muy rpidamente en segundo plano renderizndolo en un AudioBuffer en lugar de hacerlo a los altavoces del equipo con lo siguiente.

OfflineAudioContext: La interfaz OfflineAudioContext es una interfaz AudioContext representando un grfico de procesamiento de audio construido a partir de varios AudioNode enlazados juntos. En contraste con un AudioContext estndar, un OfflineAudioContext realmente no procesa el audio sino que lo genera, lo ms rpido que puede, en un buffer.
complete (event): El evento complete es lanzado cuando el renderizado de un OfflineAudioContext est terminado.
OfflineAudioCompletionEvent: La interfaz OfflineAudioCompletionEvent representa los eventos que ocurren cuando procesamiento de un OfflineAudioContext is terminado. El evento complete implementa esta interfaz.

Interfaces obsoletas

Las siguientes interfaces fueron definidas en versiones antiguas de la especificacin del API de Audio Web, pero ahora estn obsoletas y han sido reemplazadas por otras interfaces.

JavaScriptNode: Usada para dirigir procesamiento de audio a travs de JavaScript. Esta interfaz est obsoleta, y ha sido reemplazada por ScriptProcessorNode.
WaveTableNode: Usada para definir una forma de onda peririca. Esta interfaz est obsoleta, y ha sido reemplazada por PeriodicWave.

Ejemplo

Este ejemplo muestra una amplia variedad de funciones del API de Audio Web siendo usadas. Puedes ver este cdigo en accin en la demostracin de Voice-change-o-matic (tambin revisa el cdigo completo en Github) este es un demo experimental de juguete cambiador de voz; manten tus parlantes en bajo volumen cuando lo uses Al menos al comenzar!

Las lneas del API de Audio Web estn resaltadas; si quieres saber ms sobre lo que hacen los diferentes mtodos, etc., busca en las pginas de referencia.

var audioCtx = new (window.AudioContext || window.webkitAudioContext)(); // definir contexto de audio
// los navegadores Webkit/blink necesitan prefijo, Safari no funcionar sin window.

var voiceSelect = document.getElementById("voice"); // caja de seleccin para la seleccin de opciones de efectos de voz
var visualSelect = document.getElementById("visual"); // caja de seleccin para la seleccin de opciones de visualizacin de audio
var mute = document.querySelector(".mute"); // botn de silencio
var drawVisual; // requestAnimationFrame

var analyser = audioCtx.createAnalyser();
var distortion = audioCtx.createWaveShaper();
var gainNode = audioCtx.createGain();
var biquadFilter = audioCtx.createBiquadFilter();

function makeDistortionCurve(amount) {
  // funcin para hacer que la forma de curva para distorsin / nodo modificador de onda para usar
  var k = typeof amount === "number" ? amount : 50,
    n_samples = 44100,
    curve = new Float32Array(n_samples),
    deg = Math.PI / 180,
    i = 0,
    x;
  for (; i < n_samples; ++i) {
    x = (i * 2) / n_samples - 1;
    curve[i] = ((3 + k) * x * 20 * deg) / (Math.PI + k * Math.abs(x));
  }
  return curve;
}

navigator.getUserMedia(
  // restricciones - solo el audio es necesario para esta aplicacin
  {
    audio: true,
  },

  // Retrollamada de xito
  function (stream) {
    source = audioCtx.createMediaStreamSource(stream);
    source.connect(analyser);
    analyser.connect(distortion);
    distortion.connect(biquadFilter);
    biquadFilter.connect(gainNode);
    gainNode.connect(audioCtx.destination); // conectando los diferentes nodos de grafo de audio juntos

    visualize(stream);
    voiceChange();
  },

  // Retrollamada de error
  function (err) {
    console.log("Se produjo el siguiente error gUM: " + err);
  },
);

function visualize(stream) {
  WIDTH = canvas.width;
  HEIGHT = canvas.height;

  var visualSetting = visualSelect.value;
  console.log(visualSetting);

  if (visualSetting == "sinewave") {
    analyser.fftSize = 2048;
    var bufferLength = analyser.frequencyBinCount; // la mitad del valor de FFT
    var dataArray = new Uint8Array(bufferLength); // crear una matriz para almacenar los datos

    canvasCtx.clearRect(0, 0, WIDTH, HEIGHT);

    function draw() {
      drawVisual = requestAnimationFrame(draw);

      analyser.getByteTimeDomainData(dataArray); // obtener datos de forma de onda y ponerlo en la matriz creada arriba

      canvasCtx.fillStyle = "rgb(200, 200, 200)"; // dibujar onda con canvas
      canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);

      canvasCtx.lineWidth = 2;
      canvasCtx.strokeStyle = "rgb(0, 0, 0)";

      canvasCtx.beginPath();

      var sliceWidth = (WIDTH * 1.0) / bufferLength;
      var x = 0;

      for (var i = 0; i < bufferLength; i++) {
        var v = dataArray[i] / 128.0;
        var y = (v * HEIGHT) / 2;

        if (i === 0) {
          canvasCtx.moveTo(x, y);
        } else {
          canvasCtx.lineTo(x, y);
        }

        x += sliceWidth;
      }

      canvasCtx.lineTo(canvas.width, canvas.height / 2);
      canvasCtx.stroke();
    }

    draw();
  } else if (visualSetting == "off") {
    canvasCtx.clearRect(0, 0, WIDTH, HEIGHT);
    canvasCtx.fillStyle = "red";
    canvasCtx.fillRect(0, 0, WIDTH, HEIGHT);
  }
}

function voiceChange() {
  distortion.curve = new Float32Array();
  biquadFilter.gain.value = 0; // restablecer los efectos cada vez que se ejecuta la funcin VoiceChange

  var voiceSetting = voiceSelect.value;
  console.log(voiceSetting);

  if (voiceSetting == "distortion") {
    distortion.curve = makeDistortionCurve(400); // aplicar distorsin al sonido usando el nodo waveshaper
  } else if (voiceSetting == "biquad") {
    biquadFilter.type = "lowshelf";
    biquadFilter.frequency.value = 1000;
    biquadFilter.gain.value = 25; // aplicar el filtro lowshelf a los sonidos usando biquad
  } else if (voiceSetting == "off") {
    console.log("Voice settings turned off"); // no hacer nada, ya que se eligi la opcin de apagado
  }
}

// oyentes de eventos para cambiar la visualizacin y la configuracin de voz

visualSelect.onchange = function () {
  window.cancelAnimationFrame(drawVisual);
  visualize(stream);
};

voiceSelect.onchange = function () {
  voiceChange();
};

mute.onclick = voiceMute;

function voiceMute() {
  // alternar para silenciar y activar el sonido
  if (mute.id == "") {
    gainNode.gain.value = 0; // ganancia establecida en 0 para silenciar el sonido
    mute.id = "activated";
    mute.innerHTML = "Unmute";
  } else {
    gainNode.gain.value = 1; // ganancia establecida en 1 para activar el sonido
    mute.id = "";
    mute.innerHTML = "Mute";
  }
}

Especificaciones

Specification
Web Audio API # AudioContext

Compatibilidad con navegadores

Tambin ver

Usando el API de Audio Web
Visualizaciones con el API de Audio Web
Voice-change-O-matic example
Violent Theremin example
Bases de la espacializacin de audio Web
Mixing Positional Audio and WebGL
Developing Game Audio with the Web Audio API
Porting webkitAudioContext code to standards based AudioContext
Tonos: Una sencilla librera para reproduccin de tonos/notas especficas usando el API de Audio Web.
howler.js: a JS audio library that defaults to Web Audio API and falls back to HTML5 Audio, as well as providing other useful features.
Mooog: jQuery-style chaining of AudioNodes, mixer-style sends/returns, and more.
OpenLang: HTML5 video language lab web application using the Web Audio API to record and combine video and audio from different sources into a single file (source on GitHub)

Help improve MDN

Was this page helpful to you?

Yes No

Learn how to contribute

This page was last modified on 17 dic 2024 by MDN contributors.

View this page on GitHub Report a problem with this content

Web Audio API

In this article

Help improve MDN