new Audio() — Methode · JavaScript-Referenz

Signatur

new Audio(url)

Beschreibung

Der Konstruktor Audio() ist eine Abkürzung für document.createElement("audio"). Er erzeugt ein HTMLAudioElement, dessen preload-Attribut auf "auto" gesetzt ist. Wird eine URL übergeben, setzt er zusätzlich src und der Browser beginnt sofort damit, die Datei zu laden.

Das Element muss nicht ins DOM eingehängt werden, damit man es abspielen kann. Das eignet sich gut für Soundeffekte, Benachrichtigungstöne oder Hintergrundmusik in Spielen und Web-Apps. Soll der Benutzer die Wiedergabe selbst steuern, hängt man das Element mit controls = true ins Dokument ein.

Abgespielt wird mit play(). Diese Methode gibt ein Promise zurück, das abgelehnt wird, wenn die Autoplay-Richtlinie des Browsers die Wiedergabe blockiert. Ob die Datei weit genug geladen ist, um sie ohne Unterbrechung abzuspielen, zeigt das Ereignis canplaythrough an.

Parameter

Name	Typ	Default	Beschreibung
$url	string		Optionale URL der Audiodatei. Wird sie angegeben, setzt der Konstruktor `src` und startet das Laden. Ohne Argument entsteht ein leeres Element, dessen `src` man später setzt.

Rückgabewert

Typ

HTMLAudioElement

Beschreibung

Ein neues HTMLAudioElement mit preload="auto". Falls eine URL übergeben wurde, ist auch src gesetzt.

Beispiele

Soundeffekt per Klick abspielen

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

document.querySelector('#button').addEventListener('click', async () => {
  klick.currentTime = 0; // bei schnellen Klicks von vorn beginnen
  try {
    await klick.play();
  } catch (err) {
    console.warn('Wiedergabe blockiert:', err.name);
  }
});

Auf ausreichende Pufferung warten

const musik = new Audio();
musik.src = '/audio/hintergrund.ogg';
musik.loop = true;
musik.volume = 0.4;

musik.addEventListener('canplaythrough', () => {
  console.log(`Bereit, Dauer: ${musik.duration.toFixed(1)} s`);
}, { once: true });

musik.addEventListener('error', () => {
  console.error('Ladefehler:', musik.error?.code);
});

Bereit, Dauer: 182.4 s

Formatunterstützung prüfen und Player ins DOM einfügen

const player = new Audio();
const quelle = player.canPlayType('audio/ogg; codecs="vorbis"')
  ? '/audio/podcast.ogg'
  : '/audio/podcast.mp3';

player.src = quelle;
player.controls = true;
document.body.append(player);
console.log(player instanceof HTMLAudioElement, player.preload);

true "auto"

Überlappende Sounds durch Klonen

const schuss = new Audio('/sounds/laser.wav');

const feuern = () => {
  // cloneNode erlaubt mehrere gleichzeitige Wiedergaben
  const instanz = schuss.cloneNode();
  instanz.volume = 0.6;
  instanz.play().catch(() => {});
};

window.addEventListener('keydown', (e) => {
  if (e.code === 'Space') feuern();
});

// Wichtig · Fallstricke

Autoplay-Richtlinien: Moderne Browser blockieren play() ohne vorherige Benutzerinteraktion wie einen Klick oder Tastendruck. Das Promise wird dann mit NotAllowedError abgelehnt. Fange diesen Fehler immer mit catch ab.
Kein new, kein Element: Audio() ohne new wirft einen TypeError.
Speicher: Elemente, die nicht im DOM hängen, bleiben während der Wiedergabe aktiv. Werden sehr viele Instanzen erzeugt, etwa pro Soundeffekt, kann das den Speicherverbrauch erhöhen. Für präzises Timing, niedrige Latenz oder viele parallele Sounds ist die Web Audio API besser geeignet.
Formate: Nicht jeder Browser unterstützt jedes Format. Ogg Vorbis wurde in Safari lange nicht unterstützt. Prüfe das vorher mit canPlayType(). MP3 und AAC werden praktisch überall unterstützt.
CORS: Für die Verarbeitung mit der Web Audio API (createMediaElementSource) brauchen Dateien von fremden Domains crossOrigin = "anonymous" und passende CORS-Header. Sonst wird nur Stille ausgegeben.
Mobilgeräte: iOS ignoriert volume, weil die Lautstärke hier über die Hardware gesteuert wird. Außerdem wird preload dort häufig nicht beachtet.

Siehe auch

HTMLAudioElement HTMLMediaElement HTMLMediaElement.prototype.play() HTMLMediaElement.prototype.pause() HTMLMediaElement.prototype.canPlayType() AudioContext