HTMLAudioElement — Schnittstelle · JavaScript-Referenz

Signatur

interface HTMLAudioElement extends HTMLMediaElement

Beschreibung

HTMLAudioElement ist die DOM-Schnittstelle für <audio>-Elemente. Sie selbst fügt kaum eigene Mitglieder hinzu. Fast die gesamte Funktionalität erbt sie von HTMLMediaElement: play(), pause(), load(), currentTime, duration, volume, muted, loop, playbackRate sowie Ereignisse wie ended, timeupdate oder canplaythrough.

Die wichtigste Ergänzung ist der Konstruktor new Audio(url). Damit erzeugst du ein Audio-Element direkt in JavaScript, ohne es ins DOM einzuhängen. Das eignet sich gut für Soundeffekte, Benachrichtigungstöne oder Vorschau-Player. Wenn du eine URL übergibst, wird preload automatisch auf "auto" gesetzt und das Laden beginnt sofort.

Setze HTMLAudioElement ein, wenn du einfache Wiedergabe mit eingebauten Bedienelementen (controls) oder ohne sichtbare Oberfläche brauchst. Für präzises Timing, Effekte, Analyse oder Mischen mehrerer Quellen ist die Web Audio API besser geeignet. Beide lassen sich über AudioContext.createMediaElementSource() kombinieren.

Parameter

Name	Typ	Default	Beschreibung
$url	string		Optionale Adresse der Audiodatei für den Konstruktor `new Audio(url)`. Wird sie angegeben, setzt der Konstruktor `src` und `preload="auto"`.

Rückgabewert

Typ

HTMLAudioElement

Beschreibung

new Audio() gibt ein neues, nicht ins DOM eingehängtes HTMLAudioElement zurück.

Beispiele

Soundeffekt per Konstruktor abspielen

const klick = new Audio('/sounds/klick.mp3');
klick.volume = 0.5;

document.querySelector('#senden').addEventListener('click', async () => {
  klick.currentTime = 0; // von vorn beginnen, auch wenn der Sound noch läuft
  try {
    await klick.play();
  } catch (err) {
    console.warn('Wiedergabe blockiert:', err.name);
  }
});

Vorhandenes <audio>-Element steuern

// HTML: <audio id="podcast" src="/folge-12.mp3" preload="metadata"></audio>
const audio = document.getElementById('podcast');

audio.addEventListener('loadedmetadata', () => {
  console.log(`Dauer: ${Math.round(audio.duration)} s`);
});

audio.addEventListener('timeupdate', () => {
  const prozent = (audio.currentTime / audio.duration) * 100;
  document.querySelector('#fortschritt').value = prozent;
});

document.querySelector('#toggle').addEventListener('click', () => {
  audio.paused ? audio.play() : audio.pause();
});

Dauer: 1834 s

Unterstütztes Format ermitteln

const audio = new Audio();
const formate = {
  ogg: 'audio/ogg; codecs="opus"',
  mp3: 'audio/mpeg',
  aac: 'audio/mp4; codecs="mp4a.40.2"'
};

for (const [name, typ] of Object.entries(formate)) {
  console.log(name, audio.canPlayType(typ) || 'nein');
}

ogg probably mp3 maybe aac probably

Mit der Web Audio API analysieren

const audio = new Audio('/musik.mp3');
audio.crossOrigin = 'anonymous';

const ctx = new AudioContext();
const quelle = ctx.createMediaElementSource(audio);
const analyser = ctx.createAnalyser();
quelle.connect(analyser).connect(ctx.destination);

document.querySelector('#start').addEventListener('click', async () => {
  await ctx.resume();
  await audio.play();
  const daten = new Uint8Array(analyser.frequencyBinCount);
  analyser.getByteFrequencyData(daten);
  console.log('Erster Frequenzwert:', daten[0]);
});

// Wichtig · Fallstricke

Autoplay-Richtlinien: Browser blockieren Wiedergabe mit Ton ohne vorherige Nutzerinteraktion. play() gibt ein Promise zurück, das dann mit NotAllowedError abgelehnt wird. Fange den Fehler immer ab.
Formate: Die Codec-Unterstützung ist je Browser unterschiedlich. Prüfe sie mit canPlayType() oder gib mehrere <source>-Elemente an.
Ein Element spielt immer nur eine Instanz gleichzeitig. Für überlappende Soundeffekte klonst du es mit audio.cloneNode() oder verwendest die Web Audio API.
duration ist vor loadedmetadata gleich NaN und bei Streams Infinity.
Auf iOS lässt sich volume nicht per Skript ändern. Der Wert ist dort immer 1.
Für createMediaElementSource() mit Dateien von fremden Domains brauchst du CORS-Header und crossOrigin. Sonst liefert der Analyser nur Stille.
Aus dem DOM entfernte Elemente können weiterspielen. Rufe vorher pause() auf.

Siehe auch

HTMLQuoteElement HTMLDivElement HTMLMediaElement HTMLVideoElement HTMLAnchorElement