Web Audio API
Baseline Widely available
This feature is well established and works across many devices and browser versions. It’s been available across browsers since April 2021.
La Web Audio API propose un système puissant et flexible pour contrôler les données audio sur internet. Elle permet notamment de sélectionner des sources audio (microphone, flux media), d'y ajouter des effets, de créer des visualisations, d'appliquer des effets de spatialisation (comme la balance), etc.
Concepts et usages
La Web Audio API effectue des opérations dans un contexte audio; elle a été conçue pour supporter le routing modulaire. Les opérations audio basiques sont réalisées via des noeuds audio reliés entre eux pour former un graphe de routage audio. Plusieurs sources - avec différents types d'agencements de canaux - peuvent être supportées, même dans un seul contexte. Ce design modulaire et flexible permet de créer des fonctions audio complexes avec des effets dynamiques.
Les noeuds audio sont reliés au niveau de leurs entrées et sorties, formant des chaînes ou des réseaux simples. Il peut y avoir une ou plusieurs sources. Les sources fournissent des tableaux d'intensités sonores (échantillons), souvent plusieurs dizaines de milliers par seconde. Ceux-ci peuvent être calculées mathématiquement (avec un OscillatorNode
), ou peuvent provenir de fichiers sons ou vidéos (comme AudioBufferSourceNode
ou MediaElementAudioSourceNode
) ou de flux audio (MediaStreamAudioSourceNode
). En réalité, les fichiers sons sont eux-même des enregistrements d'intensités sonores, qui viennent de microphones ou d'instruments électriques, et sont mixés dans une seule onde complexe.
Les sorties de ces noeuds peuvent être liées aux entrées d'autres noeuds, qui mixent ces flux d'échantillons sonores ou les séparent en différents 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 dernière connexion n'est utile que si le son doit être entendu.
Un processus de développement typique avec web audio ressemble à ceci :
- Création d'un contexte audio
- Dans ce contexte, création des sources — comme
<audio>
, oscillator, stream - Création de noeuds d'effets, comme la réverbération, les filtres biquad, la balance, le compresseur
- Choix de la sortie audio (appelée destination), par exemple les enceintes du système
- Connection des sources aux effets, et des effets à la destination
Le timing est contrôlé avec une grande précision et une latence faible, ce qui permet aux développeurs d'écrire un code qui réagit précisément aux événements et qui est capable de traiter des échantillons précis, même avec un taux d'échantillonnage élevé. Cela permet d'envisager des applications telles que des boîtes à rythme ou des séquenceurs.
La Web Audio API permet également de contrôler la spatialisation du son. En utilisant un système basé sur le modèle émetteur - récepteur, elle permet le contrôle de la balance ainsi que la gestion de l'atténuation du son en fonction de la distance, ou effet doppler, induite par un déplacement de la source sonore (ou de l'auditeur).
Note : Vous pouvez lire davantage de détails 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 événements associés, classés selon leur fonction en 9 catégories.
Définition du graphe audio
Conteneurs et définitions qui donnent sa forme au graphe audio
AudioContext
-
Un objet
AudioContext
désigne un graphe de traitement audio construit à partir de modules reliés entre eux, chacun représenté par un noeud audio (AudioNode
). Le contexte audio contrôle la création des noeuds qu'il contient, ainsi que l'exécution du traitement audio, et du décodage. Il est nécessaire de créer unAudioContext
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 élément HTML<audio>
ou<video>
), une destination audio, un module de traitement intermédiaire (par exemple un filtreBiquadFilterNode
), ou un contrôle du volumeGainNode
). AudioParam
-
Un objet
AudioParam
est un paramètre audio, qui est lié à unAudioNode
. On peut lui assigner une valeur ou un changement de valeur, que l'on peut programmer à un moment spécifique et/ou selon un motif particulier. ended
(event)-
L'évènement
ended
est diffusé lorsque la lecture s'arrête en arrivant à la fin d'un media.
Définition des sources audio
OscillatorNode
-
Un objet
OscillatorNode
est un module de traitement audio qui génère la création d'une onde sinusoïdale d'une certaine fréquence. AudioBuffer
-
Un objet
AudioBuffer
est un petit morceau de contenu audio monté en mémoire. Il peut être créé à partir d'un fichier audio avec la méthodeAudioContext.decodeAudioData()
, ou à partir de données brutes en utilisantAudioContext.createBuffer()
. Une fois décodé sous cette forme, la source audio peut être placée dans unAudioBufferSourceNode
. AudioBufferSourceNode
-
Un objet
AudioBufferSourceNode
est une source audio composée de données audio montées en mémoire dans unAudioBuffer
. C'est unAudioNode
qui se comporte comme une source audio. MediaElementAudioSourceNode
-
Un objet
MediaElementAudio.SourceNode
est une source audio composée d'un élément HTML5<audio>
ou<video>
. C'est unAudioNode
qui se comporte comme une source audio. MediaStreamAudioSourceNode
-
Un objet
MediaStreamAudio.SourceNode
est une source audio composée d'un WebRTCMediaStream
(tel qu'une webcam ou un microphone). C'est unAudioNode
qui se comporte comme une source audio.
Définition des filtres d'effets audio
BiquadFilterNode
-
Un objet
BiquadFilterNode
est un simple filtre de bas niveau. Il peut s'agir de différents types de filtres, contrôle du volume ou égaliseurs graphiques. UnBiquadFilterNode
a toujours exactement une entrée et une sortie. ConvolverNode
-
Un objet
Convolver.Node
est unAudioNode
qui exécute une circonvolution linéaire sur un AudioBuffer donné, souvent utilisé pour créer un effet de réverbération. DelayNode
-
Un objet
DelayNode
est une ligne à retard numérique, c'est-à-dire un module de traitement automatique qui provoque un délai entre l'arrivée du son en entrée et sa propagation en sortie. DynamicsCompressorNode
-
Un objet
DynamicsCompressorNode
permet un effet de compression, qui réduit le volume des parties les plus fortes du signal de façon à éviter les effets de clipping et la distortion qui peuvent se produire lorsque des sons multiples sont diffusés simultanément. GainNode
-
Un objet
GainNode
représente une modification du volume sonore. C'est un module de traitement audio qui provoque l'application d'un gain aux données récupérées en entrée avant leur propagation vers la sortie. WaveShaperNode
-
Un objet
WaveShaperNode
représente une distortion non linéaire. C'est unAudioNode
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 caractère plus chaleureux au son. PeriodicWave
-
Un objet
PeriodicWave
est utilisé pour définir une forme d'onde périodique qui peut être utilisée pour façonner la sortie d'unOscillatorNode
.
Définition des destinations audio
Une fois que le signal audio a été traité, ces interfaces définissent sa destination.
AudioDestinationNode
-
Un noeud
AudioDestinationNode
représente la destination finale d'une source audio source dans un contexte donné — en général les enceintes du matériel. MediaStreamAudioDestinationNode
-
Un noeud
MediaStreamAudio.DestinationNode
représente une destination audio constituée d'unMediaStream
WebRTC à une seule pisteAudioMediaStreamTrack
; il peut être utilisé de façon similaire à unMediaStream
obtenu avecNavigator.getUserMedia
. C'est unAudioNode
qui se comporte comme une destination audio.
Analyse des données et visualisation
AnalyserNode
-
Un objet
AnalyserNode
fournit en temps réel des informations concernant la fréquence et le temps, afin de les analyser et les visualiser.
Division et fusion des pistes audio
ChannelSplitterNode
-
Un noeud
ChannelSplitterNode
prend en entrée une source audio et sépare ses différentes pistes en une série de sorties mono. ChannelMergerNode
-
Un noeud
ChannelMergerNode
réunit différentes entrées mono en une seule sortie. Chaque entrée devient une des pistes de la sortie unique.
Spatialisation audio
AudioListener
-
Un objet
AudioListener
représente la position et l'orientation de l'unique personne écoutant la scene audio utilisée dans la spatialisation audio. PannerNode
-
Un noeud
PannerNode
représente le comportement d'un signal dans l'espace. C'est un module de traitement audio qui décrit sa position avec des coordonnées cartésiennes fondées sur la règle de la main droite; ses mouvements utilisent un vecteur de vélocité et sa directionnalité un cône de direction.
Traitement audio avec JavaScript
Note : Au jour de la publication de la spécification Web Audio API le 29 août 2014, ces fonctionnalités sont dépréciées, et seront bientôt remplacées par Audio_Workers.
ScriptProcessorNode
-
Un noeud
ScriptProcessorNode
permet de générer, traiter ou analyser du son avec JavaScript. C'est un module de traitement audio qui est lié à deux buffers, l'un en entrée, et l'autre en sortie. Un évènement implémentantAudioProcessingEvent
est envoyé à l'objet à chaque fois que le buffer d'entrée reçoit de nouvelles données, et le gestionnaire d'évènement prend fin lorsque les nouvelles données ont été communiquées au buffer de sortie. audioprocess
(event)-
L'évènement
audioprocess
est émis lorsque le buffer d'entrée d'unScriptProcessorNode
de la Web Audio API est prêt à être traité. AudioProcessingEvent
-
L'objet
AudioProcessingEvent
est envoyé aux fonctions de rappel (callback) qui écoutent l'évènementaudioprocess
.
Traitement audio hors ligne ou en tâche de fond
Il est possible de traiter et exporter un graphe audio très rapidement en tâche de fond — en l'exportant dans un AudioBuffer
plutôt que sur les enceintes du matériel — grâce aux objets suivants.
OfflineAudioContext
-
Un objet
OfflineAudioContext
est une interfaceAudioContext
qui représente un graphe de traitement audio construit à partir de nœuds audio. À la différence d'une interfaceAudioContext
standard, une interfaceOfflineAudioContext
n'exporte pas vraiment le son, mais le génère aussi vite que possible dans un buffer. complete
(event)-
Un évènement
complete
est émis lorsque le rendu d'unOfflineAudioContext
est terminé. OfflineAudioCompletionEvent
-
The
OfflineAudioCompletionEvent
est envoyé aux fonctions de callback qui écoutent l'évènementcomplete
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 implémentés par aucun navigateur. Lorsqu'ils seront implémentés, ils remplaceront ScriptProcessorNode
, et les autres fonctionnalités mentionnées dans la section Traitement audio avec JavaScript ci-avant.
AudioWorkerNode
-
Un objet AudioWorkerNode représente un
AudioNode
qui interagit avec le thread d'un worker pour générer, traiter, ou analyse le son directement. AudioWorkerGlobalScope
-
Un objet
AudioWorkerGlobalScope
est un objet dérivé d'un objetDedicatedWorkerGlobalScope
. Il représente le contexte d'un worker dans lequel un script de traitement audio est lancé; il est conçu pour permettre la génération, le traitement, et l'analyse de données audio directement avec JavaScript dans le thread d'un worker. AudioProcessEvent
-
UN objet
Event
est transmis aux objetsAudioWorkerGlobalScope
pour effectuer un traitement audio.
Objets obsolètes
Les objets suivants étaient définis dans les versions précédentes de la spécification, mais sont maintenant obsolètes et ont été remplacés.
JavaScriptNode
-
Utilisé pour le traitement du son directement en Javascript. Cet objet est obsolète, et a été remplacé par
ScriptProcessorNode
. WaveTableNode
-
Utilisé pour définir une forme d'onde périodique. Cet objet est obsolète, et a été remplacé par
PeriodicWave
.
Exemples
Vous pouvez trouver différents exemples dans le dépôt webaudio-example sur GitHub.
Spécifications
Specification |
---|
Web Audio API # AudioContext |
Compatibilité des navigateurs
BCD tables only load in the browser
Voir aussi
- Utiliser la Web Audio API
- Visualizations with Web Audio API
- Voice-change-O-matic example
- Violent Theremin example
- Web audio spatialisation basics
- Mixing Positional Audio and WebGL
- Developing Game Audio with the Web Audio API
- Porting webkitAudioContext code to standards based AudioContext
- Tones: a simple library for playing specific tones/notes using the Web Audio API.
- 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.
Guides
Démos
API
AnalyserNode
AudioBuffer
AudioBufferSourceNode
AudioContext
AudioDestinationNode
AudioListener
AudioNode
AudioParam
audioprocess
(event)AudioProcessingEvent
BiquadFilterNode
ChannelMergerNode
ChannelSplitterNode
complete
(event)ConvolverNode
DelayNode
DynamicsCompressorNode
ended
(event)GainNode
MediaElementAudioSourceNode
MediaStreamAudioDestinationNode
MediaStreamAudioSourceNode
OfflineAudioCompletionEvent
OfflineAudioContext
OscillatorNode
PannerNode
PeriodicWave
ScriptProcessorNode
WaveShaperNode