Web Audio API

Baseline

Large disponibilit

Cette fonctionnalit est bien tablie et fonctionne sur de nombreux appareils et versions de navigateurs. Elle est disponible sur tous les navigateurs depuis avril 2021.

* Certaines parties de cette fonctionnalit peuvent bnficier de prise en charge variables.

Voir la compatibilit complte
En savoir plus

La Web Audio API propose un systme puissant et flexible pour contrler les donnes audio sur internet. Elle permet notamment de slectionner des sources audio (microphone, flux media), d'y ajouter des effets, de crer des visualisations, d'appliquer des effets de spatialisation (comme la balance), etc.

Concepts et usages

La Web Audio API effectue des oprations dans un contexte audio; elle a t conue pour supporter le routing modulaire. Les oprations audio basiques sont ralises via des noeuds audio relis entre eux pour former un graphe de routage audio. Plusieurs sources - avec diffrents types d'agencements de canaux - peuvent tre supportes, mme dans un seul contexte. Ce design modulaire et flexible permet de crer des fonctions audio complexes avec des effets dynamiques.

Les noeuds audio sont relis au niveau de leurs entres et sorties, formant des chanes ou des rseaux simples. Il peut y avoir une ou plusieurs sources. Les sources fournissent des tableaux d'intensits sonores (chantillons), souvent plusieurs dizaines de milliers par seconde. Ceux-ci peuvent tre calcules mathmatiquement (avec un OscillatorNode), ou peuvent provenir de fichiers sons ou vidos (comme AudioBufferSourceNode ou MediaElementAudioSourceNode) ou de flux audio (MediaStreamAudioSourceNode). En ralit, les fichiers sons sont eux-mme des enregistrements d'intensits sonores, qui viennent de microphones ou d'instruments lectriques, et sont mixs dans une seule onde complexe.

Les sorties de ces noeuds peuvent tre lies aux entres d'autres noeuds, qui mixent ces flux d'chantillons sonores ou les sparent en diffrents flux. Une modification courante est la multiplications des chantillons par une valeur afin d'en augmenter ou diminuer le volume sonore (comme c'est le cas pour le GainNode). Le son est ensuite li une destination (AudioContext.destination), qui l'envoie aux enceintes ou au casque audio. Cette dernire connexion n'est utile que si le son doit tre entendu.

Un processus de dveloppement typique avec web audio ressemble ceci :

Cration d'un contexte audio
Dans ce contexte, cration des sources comme <audio>, oscillator, stream
Cration de noeuds d'effets, comme la rverbration, les filtres biquad, la balance, le compresseur
Choix de la sortie audio (appele destination), par exemple les enceintes du systme
Connection des sources aux effets, et des effets la destination

[Un diagramme de bote avec une bote extrieure intitule contexte audio et trois botes l'intrieur intitules source, effets et destination. Les trois botes intrieures ont des flches qui pointent de la gauche vers la droite, indiquant le sens du flux de l'information audio.]

Le timing est contrl avec une grande prcision et une latence faible, ce qui permet aux dveloppeurs d'crire un code qui ragit prcisment aux vnements et qui est capable de traiter des chantillons prcis, mme avec un taux d'chantillonnage lev. Cela permet d'envisager des applications telles que des botes rythme ou des squenceurs.

La Web Audio API permet galement de contrler la spatialisation du son. En utilisant un systme bas sur le modle metteur - rcepteur, elle permet le contrle de la balance ainsi que la gestion de l'attnuation du son en fonction de la distance, ou effet doppler, induite par un dplacement de la source sonore (ou de l'auditeur).

Note : Vous pouvez lire davantage de dtails sur l'API Web Audio en vous rendant sur notre article Les concepts de base de l'API Web Audio.

Interface de la Web Audio API

La Web Audio API expose 28 interfaces avec des vnements associs, classs selon leur fonction en 9 catgories.

Dfinition du graphe audio

Conteneurs et dfinitions qui donnent sa forme au graphe audio

AudioContext: Un objet AudioContext dsigne un graphe de traitement audio construit partir de modules relis entre eux, chacun reprsent par un noeud audio (AudioNode). Le contexte audio contrle la cration des noeuds qu'il contient, ainsi que l'excution du traitement audio, et du dcodage. Il est ncessaire de crer un AudioContext avant de faire quoi que ce soit d'autre, puisque tout se passe dans un contexte.
AudioNode: Un objet AudioNode est un module de traitement audio, tel qu'une source audio (c'est--dire un lment HTML <audio> ou <video>), une destination audio, un module de traitement intermdiaire (par exemple un filtre BiquadFilterNode), ou un contrle du volume GainNode).
AudioParam: Un objet AudioParam est un paramtre audio, qui est li un AudioNode. On peut lui assigner une valeur ou un changement de valeur, que l'on peut programmer un moment spcifique et/ou selon un motif particulier.
ended (event): L'vnement ended est diffus lorsque la lecture s'arrte en arrivant la fin d'un media.

Dfinition des sources audio

OscillatorNode: Un objet OscillatorNode est un module de traitement audio qui gnre la cration d'une onde sinusodale d'une certaine frquence.
AudioBuffer: Un objet AudioBuffer est un petit morceau de contenu audio mont en mmoire. Il peut tre cr partir d'un fichier audio avec la mthode AudioContext.decodeAudioData(), ou partir de donnes brutes en utilisant AudioContext.createBuffer(). Une fois dcod sous cette forme, la source audio peut tre place dans un AudioBufferSourceNode.
AudioBufferSourceNode: Un objet AudioBufferSourceNode est une source audio compose de donnes audio montes en mmoire dans un AudioBuffer. C'est un AudioNode qui se comporte comme une source audio.
MediaElementAudioSourceNode: Un objet MediaElementAudio.SourceNode est une source audio compose d'un lment HTML5 <audio> ou <video>. C'est un AudioNode qui se comporte comme une source audio.
MediaStreamAudioSourceNode: Un objet MediaStreamAudio.SourceNode est une source audio compose d'un WebRTC MediaStream (tel qu'une webcam ou un microphone). C'est un AudioNode qui se comporte comme une source audio.

Dfinition des filtres d'effets audio

BiquadFilterNode: Un objet BiquadFilterNode est un simple filtre de bas niveau. Il peut s'agir de diffrents types de filtres, contrle du volume ou galiseurs graphiques. Un BiquadFilterNode a toujours exactement une entre et une sortie.
ConvolverNode: Un objet Convolver.Node est un AudioNode qui excute une circonvolution linaire sur un AudioBuffer donn, souvent utilis pour crer un effet de rverbration.
DelayNode: Un objet DelayNode est une ligne retard numrique, c'est--dire un module de traitement automatique qui provoque un dlai entre l'arrive du son en entre et sa propagation en sortie.
DynamicsCompressorNode: Un objet DynamicsCompressorNode permet un effet de compression, qui rduit le volume des parties les plus fortes du signal de faon viter les effets de clipping et la distortion qui peuvent se produire lorsque des sons multiples sont diffuss simultanment.
GainNode: Un objet GainNode reprsente une modification du volume sonore. C'est un module de traitement audio qui provoque l'application d'un gain aux donnes rcupres en entre avant leur propagation vers la sortie.
WaveShaperNode: Un objet WaveShaperNode reprsente une distortion non linaire. C'est un AudioNode qui utilise une courbe pour appliquer au signal une distortion de mise en forme des ondes. En dehors de l'effet de distortion vident, il est souvent utilis pour donner un caractre plus chaleureux au son.
PeriodicWave: Un objet PeriodicWave est utilis pour dfinir une forme d'onde priodique qui peut tre utilise pour faonner la sortie d'un OscillatorNode.

Dfinition des destinations audio

Une fois que le signal audio a t trait, ces interfaces dfinissent sa destination.

AudioDestinationNode: Un noeud AudioDestinationNode reprsente la destination finale d'une source audio source dans un contexte donn en gnral les enceintes du matriel.
MediaStreamAudioDestinationNode: Un noeud MediaStreamAudio.DestinationNode reprsente une destination audio constitue d'un MediaStream WebRTC une seule piste AudioMediaStreamTrack; il peut tre utilis de faon similaire un MediaStream obtenu avec Navigator.getUserMedia. C'est un AudioNode qui se comporte comme une destination audio.

Analyse des donnes et visualisation

AnalyserNode: Un objet AnalyserNode fournit en temps rel des informations concernant la frquence et le temps, afin de les analyser et les visualiser.

Division et fusion des pistes audio

ChannelSplitterNode: Un noeud ChannelSplitterNode prend en entre une source audio et spare ses diffrentes pistes en une srie de sorties mono.
ChannelMergerNode: Un noeud ChannelMergerNode runit diffrentes entres mono en une seule sortie. Chaque entre devient une des pistes de la sortie unique.

Spatialisation audio

AudioListener: Un objet AudioListener reprsente la position et l'orientation de l'unique personne coutant la scene audio utilise dans la spatialisation audio.
PannerNode: Un noeud PannerNode reprsente le comportement d'un signal dans l'espace. C'est un module de traitement audio qui dcrit sa position avec des coordonnes cartsiennes fondes sur la rgle de la main droite; ses mouvements utilisent un vecteur de vlocit et sa directionnalit un cne de direction.

Traitement audio avec JavaScript

Note : Au jour de la publication de la spcification Web Audio API le 29 aot 2014, ces fonctionnalits sont dprcies, et seront bientt remplaces par Audio_Workers.

ScriptProcessorNode: Un noeud ScriptProcessorNode permet de gnrer, traiter ou analyser du son avec JavaScript. C'est un module de traitement audio qui est li deux buffers, l'un en entre, et l'autre en sortie. Un vnement implmentant AudioProcessingEvent est envoy l'objet chaque fois que le buffer d'entre reoit de nouvelles donnes, et le gestionnaire d'vnement prend fin lorsque les nouvelles donnes ont t communiques au buffer de sortie.
audioprocess (event): L'vnement audioprocess est mis lorsque le buffer d'entre d'un ScriptProcessorNode de la Web Audio API est prt tre trait.
AudioProcessingEvent: L'objet AudioProcessingEvent est envoy aux fonctions de rappel (callback) qui coutent l'vnement audioprocess.

Traitement audio hors ligne ou en tche de fond

Il est possible de traiter et exporter un graphe audio trs rapidement en tche de fond en l'exportant dans un AudioBuffer plutt que sur les enceintes du matriel grce aux objets suivants.

OfflineAudioContext: Un objet OfflineAudioContext est une interface AudioContext qui reprsente un graphe de traitement audio construit partir de nuds audio. la diffrence d'une interface AudioContext standard, une interface OfflineAudioContext n'exporte pas vraiment le son, mais le gnre aussi vite que possible dans un buffer.
complete (event): Un vnement complete est mis lorsque le rendu d'un OfflineAudioContext est termin.
OfflineAudioCompletionEvent: The OfflineAudioCompletionEvent est envoy aux fonctions de callback qui coutent l'vnement complete event implements this interface.

Audio Workers

Les Audio workers offrent la possibilit de traiter le son directement dans le contexte d'un web worker. En date du 29 August 2014, ils ne sont encore implments par aucun navigateur. Lorsqu'ils seront implments, ils remplaceront ScriptProcessorNode, et les autres fonctionnalits mentionnes dans la section Traitement audio avec JavaScript ci-avant.

AudioWorkerNode: Un objet AudioWorkerNode reprsente un AudioNode qui interagit avec le thread d'un worker pour gnrer, traiter, ou analyse le son directement.
AudioWorkerGlobalScope: Un objet AudioWorkerGlobalScope est un objet driv d'un objet DedicatedWorkerGlobalScope. Il reprsente le contexte d'un worker dans lequel un script de traitement audio est lanc; il est conu pour permettre la gnration, le traitement, et l'analyse de donnes audio directement avec JavaScript dans le thread d'un worker.
AudioProcessEvent: UN objet Event est transmis aux objets AudioWorkerGlobalScope pour effectuer un traitement audio.

Objets obsoltes

Les objets suivants taient dfinis dans les versions prcdentes de la spcification, mais sont maintenant obsoltes et ont t remplacs.

JavaScriptNode: Utilis pour le traitement du son directement en Javascript. Cet objet est obsolte, et a t remplac par ScriptProcessorNode.
WaveTableNode: Utilis pour dfinir une forme d'onde priodique. Cet objet est obsolte, et a t remplac par PeriodicWave.