<audio> : l'élément audio embarqué

Exemple interactif

<figure>
  <figcaption>Écoutez le T-Rex&nbsp;:</figcaption>
  <audio controls src="/shared-assets/audio/t-rex-roar.mp3"></audio>
  <a href="/shared-assets/audio/t-rex-roar.mp3"> Télécharger l'audio </a>
</figure>

figure {
  margin: 0;
}

L'exemple qui précède illustre le fonctionnement simple de l'élément <audio>. De façon similaire à l'élément <img>, on inclut un chemin vers la ressource à intégrer dans l'attribut src ; on peut ajouter d'autres attributs pour indiquer, par exemple, si l'on souhaite la lecture automatique, la lecture en boucle, l'affichage des contrôles audio par défaut du navigateur, etc.

Le contenu présent à l'intérieur des balises <audio></audio> est affiché comme contenu de repli dans les navigateurs qui ne prennent pas en charge l'élément.

Attributs

Cet élément inclut les attributs universels.

autoplay

Un attribut booléen : si défini, l'audio commencera automatiquement la lecture dès qu'il le peut, sans attendre la fin du téléchargement du fichier audio.

Note : Les sites qui lancent automatiquement de l'audio (ou des vidéos avec une piste audio) peuvent être désagréables pour les utilisateur·ices et doivent donc être évités dans la mesure du possible. Si vous devez proposer une fonctionnalité de lecture automatique, rendez-la optionnelle (l'utilisateur·ice doit l'activer explicitement). Cependant, cela peut être utile lors de la création d'éléments médias dont la source sera définie ultérieurement, sous le contrôle de l'utilisateur·ice. Consultez notre guide sur la lecture automatique pour obtenir des informations supplémentaires sur la manière d'utiliser correctement la fonction autoplay.

controls

Si cet attribut est présent, le navigateur affichera des contrôles permettant à l'utilisateur·ice de contrôler la lecture audio, y compris le volume, la navigation et la mise en pause/reprise de la lecture.

controlslist

L'attribut controlslist ^(angl.), si l'attribut controlslist est défini, aide le navigateur à déterminer quels contrôles afficher pour l'élément audio chaque fois que le navigateur affiche ses propres contrôles (c'est-à-dire si l'attribut controls est défini).

Les valeurs autorisées sont nodownload, nofullscreen et noremoteplayback.

crossorigin

Cet attribut enumerated indique s'il faut utiliser CORS pour récupérer le fichier audio associé. Les ressources compatibles CORS peuvent être réutilisées dans l'élément <canvas> sans être contaminées. Les valeurs autorisées sont :

anonymous

Envoie une requête cross-origin sans information d'identification. Autrement dit, il envoie l'en-tête HTTP Origin: sans cookie, certificat X.509 ou authentification HTTP Basic. Si le serveur ne fournit pas d'identifiants au site d'origine (en ne définissant pas l'en-tête HTTP Access-Control-Allow-Origin:), la ressource sera contaminées et son utilisation sera restreinte.

use-credentials

Envoie une requête cross-origin avec information d'identification. Autrement dit, il envoie l'en-tête HTTP Origin: avec un cookie, un certificat ou une authentification HTTP Basic. Si le serveur ne fournit pas d'identifiants au site d'origine (via l'en-tête HTTP Access-Control-Allow-Credentials:), la ressource sera contaminées et son utilisation sera restreinte.

Si l'attribut n'est pas présent, la ressource est récupérée sans requête CORS (c'est-à-dire sans envoyer l'en-tête HTTP Origin:), ce qui empêche son utilisation non contaminée dans les éléments <canvas>. Si la valeur est invalide, elle est traitée comme si le mot-clé énuméré anonymous était utilisé. Voir attributs de configuration CORS pour plus d'informations.

disableremoteplayback

Un attribut booléen utilisé pour désactiver la capacité de lecture à distance sur les appareils connectés via des technologies filaires (HDMI, DVI, etc.) ou sans fil (Miracast, Chromecast, DLNA, AirPlay, etc.). Voir la spécification de l'API Remote Playback ^(angl.) pour plus d'informations.

Avec Safari, vous pouvez utiliser x-webkit-airplay="deny" ^(angl.) comme solution de repli.

loop

Un attribut booléen : s'il est défini, la lecture recommence automatiquement depuis le début lorsque la fin est atteinte.

muted

Un attribut booléen qui indique si l'audio sera initialement coupé. Sa valeur par défaut est false.

preload

Cet attribut énuméré sert à donner une indication au navigateur sur ce que l'auteur·ice pense être la meilleure expérience utilisateur. Il peut prendre l'une des valeurs suivantes :

• none : Indique que l'audio ne doit pas être préchargé.
• metadata : Indique que seules les métadonnées audio (par exemple, la durée) sont récupérées.
• auto : Indique que l'ensemble du fichier audio peut être téléchargé, même si l'utilisateur·ice n'est pas censé·e l'utiliser.
• chaîne de caractères vide : Synonyme de la valeur auto.

La valeur par défaut varie selon le navigateur. La spécification recommande de la définir à metadata.

Note :

• L'attribut autoplay a priorité sur preload. Si autoplay est défini, le navigateur devra évidemment commencer à télécharger l'audio pour la lecture.
• Le navigateur n'est pas obligé par la spécification de suivre la valeur de cet attribut ; il s'agit d'une simple indication.

src

L'URL de l'audio à intégrer. Cela est soumis aux contrôles d'accès HTTP. Cet attribut est optionnel ; vous pouvez à la place utiliser l'élément <source> à l'intérieur du bloc audio pour définir l'audio à intégrer.

Évènements

audioprocess Obsolète

La mémoire tampon en entrée d'un ScriptProcessorNode est prête à être traitée.

canplay

Le navigateur peut lire le média, mais estime que trop peu de données ont été chargées pour lire le média jusqu'à la fin sans devoir s'arrêter pour un chargement en mémoire tampon.

canplaythrough

Le navigateur estime qu'il peut lire le média jusqu'à la fin sans s'arrêter pour un chargement en mémoire tampon.

complete

Le rendu d'un objet OfflineAudioContext est terminé.

durationchange

L'attribut duration a été mis à jour.

emptied

Le média est devenu vide ; par exemple, cet évènement est envoyé si le média a déjà été chargé (ou partiellement chargé) et que la méthode HTMLMediaElement.load est appelée pour le recharger.

ended

La lecture a été interrompue car la fin du média a été atteinte.

loadeddata

La première image (frame en anglais) du média a été chargée.

loadedmetadata

Les métadonnées ont été chargées.

loadstart

Déclenché lorsque le navigateur commence à charger la ressource.

pause

La lecture a été mise en pause.

play

La lecture a commencé.

playing

La lecture est prête à démarrer après avoir été mise en pause ou retardée par manque de données.

ratechange

La vitesse de lecture a changé.

seeked

Une opération de déplacement du curseur de lecture (seek en anglais) est terminée.

seeking

Une opération de déplacement du curseur de lecture (seek en anglais) a commencé.

stalled

L'agent utilisateur tente de récupérer les données du média, mais les données n'arrivent pas comme prévu.

suspend

Le chargement des données du média a été suspendu.

timeupdate

Le temps indiqué par l'attribut currentTime a été mis à jour.

volumechange

Le volume a changé.

waiting

La lecture a été interrompue en raison d'un manque temporaire de données.

Notes d'utilisation

Les navigateurs ne prennent pas tous en charge les mêmes types de fichiers et codecs audio ; vous pouvez fournir plusieurs sources à l'intérieur d'éléments <source> imbriqués, et le navigateur utilisera alors la première qu'il comprend :

<audio controls>
  <source src="monAudio.mp3" type="audio/mpeg" />
  <source src="monAudio.ogg" type="audio/ogg" />
  <p>
    Télécharger l'audio
    <a href="monAudio.mp3" download="monAudio.mp3">MP3</a> ou
    <a href="monAudio.ogg" download="monAudio.ogg">OGG</a>.
  </p>
</audio>

La source audio peut être définie sur n'importe quelle URL valide, y compris des URL HTTP(S) et des URLs de données. Lorsque vous utilisez des URL HTTP(S), sachez que le comportement de mise en cache du navigateur influera sur la fréquence à laquelle le fichier est demandé au serveur. Les URLs de données intègrent directement les données audio dans le HTML, ce qui peut être utile pour de petits fichiers audio mais n'est pas recommandé pour les fichiers volumineux car cela augmente la taille du fichier HTML.

Lorsque vous utilisez des éléments <source>, le navigateur tente de charger chaque source séquentiellement. Si une source échoue (par exemple, à cause d'une URL invalide ou d'un format non pris en charge), la suivante est essayée, et ainsi de suite. Un évènement error est déclenché sur l'élément <audio> après l'échec de toutes les sources ; les évènements error ne sont pas déclenchés sur chaque élément <source> individuellement.

Vous pouvez également utiliser l'API Web Audio pour générer et manipuler directement des flux audio à partir du code JavaScript, plutôt que de diffuser des fichiers audio préexistants. Vous pouvez définir srcObject en JavaScript sur un objet MediaStream. Cela est couramment utilisé pour des flux audio en direct ou du traitement audio en temps réel.

const audioElement = document.querySelector("audio");
navigator.mediaDevices
  .getUserMedia({ audio: true })
  .then((stream) => {
    audioElement.srcObject = stream;
  })
  .catch((error) => {
    console.error("Erreur lors de l'accès au microphone", error);
  });

Notez que les sources MediaStream présentent des limitations : elles ne sont pas consultables et ne prennent en charge qu'un ensemble limité de codecs.

Nous proposons un guide substantiel et complet des types de fichiers médias et des codecs audio qui peuvent être utilisés en leur sein. Est également disponible un guide des codecs supportés pour la vidéo.

Autres notes d'utilisation :

• Si vous ne définissez pas l'attribut controls, le lecteur audio n'inclura pas les contrôles par défaut du navigateur. Vous pouvez toutefois créer vos propres contrôles personnalisés en utilisant JavaScript et l'API HTMLMediaElement.
• Pour permettre un contrôle précis de votre contenu audio, les HTMLMediaElement déclenchent de nombreux évènements différents. Cela fournit également un moyen de surveiller le processus de récupération de l'audio afin que vous puissiez surveiller les erreurs ou détecter quand suffisamment de ressources sont disponibles pour commencer à les lire ou à les manipuler.
• Les éléments <audio> ne peuvent pas avoir de sous-titres ou de légendes associés de la même manière que les éléments <video>. Voir WebVTT et Audio ^(angl.) par Ian Devlin pour des informations utiles et des solutions de contournement.
• Pour tester le contenu de repli sur des navigateurs qui prennent en charge l'élément, vous pouvez remplacer <audio> par un élément inexistant comme <notanaudio>.

Une bonne source générale d'informations sur l'utilisation de <audio> en HTML est le tutoriel Contenu vidéo et audio.

Mise en forme avec CSS

L'élément <audio> n'a pas d'affichage visuel intrinsèque, sauf si l'attribut controls est défini, auquel cas les contrôles par défaut du navigateur sont affichés.

Les contrôles par défaut ont une valeur display de inline par défaut, et il est souvent conseillé de la définir à block pour améliorer le contrôle du positionnement et de la mise en page, sauf si vous souhaitez l'intégrer dans un bloc de texte ou similaire.

Vous pouvez mettre en forme les contrôles par défaut avec des propriétés qui affectent le bloc comme une seule unité, par exemple vous pouvez leur donner une border et une border-radius, padding, margin, etc. Il n'est cependant pas possible de mettre en forme les composants individuels à l'intérieur du lecteur audio (par exemple, changer la taille des boutons ou des icônes, changer la police, etc.), et les contrôles diffèrent selon les navigateurs.

Pour obtenir une apparence cohérente sur tous les navigateurs, il faut créer des contrôles personnalisés ; ceux-ci peuvent être balisés et mis en forme comme vous le souhaitez, puis reliés à leurs fonctionnalités via JavaScript et l'API HTMLMediaElement.

Les bases de la mise en forme des lecteurs vidéo présente quelques techniques utiles de mise en forme — il est rédigé dans le contexte de <video>, mais la plupart s'appliquent aussi à <audio>.

Détecter l'ajout et la suppression de pistes

Vous pouvez détecter quand des pistes sont ajoutées à ou supprimées d'un élément <audio> en utilisant les évènements addtrack et removetrack. Cependant, ces évènements ne sont pas envoyés directement à l'élément <audio> lui-même. Ils sont envoyés à l'objet liste de pistes à l'intérieur du HTMLMediaElement de l'élément <audio>, qui correspond au type de piste ajouté à l'élément :

HTMLMediaElement.audioTracks

Un objet AudioTrackList contenant toutes les pistes audio de l'élément média. Vous pouvez ajouter un écouteur addtrack à cet objet pour être averti·e lorsque de nouvelles pistes audio sont ajoutées à l'élément.

HTMLMediaElement.videoTracks

Ajoutez un écouteur addtrack à cet objet VideoTrackList pour être informé·e lorsque des pistes vidéo sont ajoutées à l'élément.

HTMLMediaElement.textTracks

Ajoutez un écouteur d'évènement addtrack à cet objet TextTrackList pour être averti·e lorsque de nouvelles pistes de texte sont ajoutées à l'élément.

Par exemple, pour détecter quand des pistes audio sont ajoutées à ou supprimées d'un élément <audio>, vous pouvez utiliser un code comme celui-ci :

const elem = document.querySelector("audio");

elem.audioTrackList.onaddtrack = (event) => {
  trackEditor.addTrack(event.track);
};

elem.audioTrackList.onremovetrack = (event) => {
  trackEditor.removeTrack(event.track);
};

Ce code surveille l'ajout et la suppression de pistes audio sur l'élément, et appelle une fonction hypothétique sur un éditeur de pistes pour enregistrer et retirer la piste de la liste des pistes disponibles de l'éditeur.

Vous pouvez aussi utiliser addEventListener() pour écouter les évènements addtrack et removetrack.

Accessibilité

Les éléments audio contenant des dialogues parlés doivent fournir des sous-titres et des transcriptions qui décrivent précisément le contenu. Les sous-titres, qui sont spécifiés à l'aide de WebVTT, ils permettent aux personnes souffrant de troubles auditifs ou ne pouvant pas utiliser le son de l'appareil de lire le fichier. Les transcriptions permettent aux personnes ayant besoin de plus de temps pour lire le contenu d'utiliser un format plus adéquat.

Si un service de sous-titre automatique est utilisé, il est nécessaire de vérifier le contenu généré afin de s'assurer qu'il correspond correctement à la source audio.

L'élément <audio> ne prend pas directement en charge le WebVTT. Vous devrez trouver une bibliothèque ou un framework qui vous offre cette capacité, ou écrire le code pour afficher les sous-titres vous-même. Une option consiste à lire votre audio à l'aide d'un élément <video>, qui prend en charge WebVTT.

En plus des dialogues parlés, les sous-titres et les transcriptions doivent également identifier la musique et les effets sonores qui communiquent des informations importantes. Cela inclut l'émotion et le ton. Par exemple, dans le WebVTT ci-dessous, notez l'utilisation de crochets pour donner un ton et un aperçu émotionnel au spectateur ; cela peut aider à établir l'ambiance autrement fournie par la musique, les sons non verbaux et les effets sonores cruciaux, et ainsi de suite.

1
00:00:00 --> 00:00:45
[Musique avec des trompettes sonnantes]

2
00:00:46 --> 00:00:51
Elle est où la poulette ?

16
00:00:52 --> 00:01:02
[sur un ton énervé] Vous rendez la poulette ou c'est plus vous qui donnez à manger aux lapins ?

Une autre bonne pratique consiste à fournir du contenu comme un lien de téléchargement comme méthode alternative pour les personnes qui utilisent un navigateur qui ne prend pas en charge <audio> :

<audio controls>
  <source src="monAudio.mp3" type="audio/mpeg" />
  <source src="monAudio.ogg" type="audio/ogg" />
  <p>
    Votre navigateur ne prend pas charge l'audio HTML. Voici
    <a href="monAudio.mp3">un lien de téléchargement</a> à la place.
  </p>
</audio>

• Format des pistes de texte vidéo Web (WebVTT)
• WebAIM : Sous-titres, transcriptions et descriptions audio ^(angl.)
• MDN Explications du critère WCAG, explications du critère 1.2
• Comprendre le critère de succès 1.2.1 | W3C Understanding WCAG 2.0 ^(angl.)
• Comprendre le critère de succès 1.2.2 | W3C Understanding WCAG 2.0 ^(angl.)

Exemples

Utilisation simple

L'exemple suivant montre l'utilisation basique de l'élément <audio> pour lire un fichier OGG. Il sera lu automatiquement grâce à l'attribut autoplay — si la page y est autorisée — et inclut également un contenu de repli.

<!-- Simple lecture audio -->
<audio src="AudioTest.ogg" autoplay>
  <a href="AudioTest.ogg" download="AudioTest.ogg">Télécharger l'audio OGG</a>.
</audio>

Pour savoir quand l'autoplay fonctionne, comment obtenir la permission d'utiliser l'autoplay, et comment et quand il est approprié d'utiliser l'autoplay, consultez notre guide sur l'autoplay.

Utilisation de l'élément <source>

Cet exemple précise quelle piste audio intégrer en utilisant l'attribut src sur un élément <source> imbriqué plutôt que directement sur l'élément <audio>. Il est toujours utile d'inclure le type MIME du fichier à l'intérieur de l'attribut type, car le navigateur est capable de dire instantanément s'il peut lire ce fichier, et de ne pas perdre de temps dessus dans le cas contraire.

<audio controls>
  <source src="toto.wav" type="audio/wav" />
  <a href="toto.wav" download="toto.wav">Télécharger l'audio WAV</a>.
</audio>

Utilisation de plusieurs éléments <source>

Dans l'exemple qui suit, le navigateur essaiera de jouer le premier fichier correspondant au premier élément (celui avec le codec Opus) : s'il peut le lire, il n'interprète pas les suivants ; s'il ne peut pas le lire, il tente de lire le deuxième puis, si ce n'est toujours pas possible, le troisième (au format MP3) :

<audio controls>
  <source src="toto.opus" type="audio/ogg; codecs=opus" />
  <source src="toto.ogg" type="audio/ogg; codecs=vorbis" />
  <source src="toto.mp3" type="audio/mpeg" />
</audio>

Résumé technique

Spécifications

Compatibilité des navigateurs

Voir aussi

• Technologies média Web
  • Formats des conteneurs médias (types de fichiers)
  • Guide des codecs audio utilisés sur le web
• L'API Web Audio
• L'interface HTMLAudioElement
• L'élément <source>
• L'élément <video>
• Apprendre : Contenu vidéo et audio
• Les bases de l'audio multi-navigateur