HTMLMediaElement.play() — Methode · JavaScript-Referenz

Signatur

HTMLMediaElement.prototype.play()

Beschreibung

Mit play() startet man die Wiedergabe eines Medienelements, also eines <audio>- oder <video>-Elements, per Skript. Ist das Medium pausiert oder beendet, läuft es ab der aktuellen Position (currentTime) weiter. Nach dem Ende beginnt es wieder von vorn, sofern loop nicht gesetzt ist. Die Eigenschaft paused wird sofort auf false gesetzt, und das Event play wird ausgelöst. Sobald genug Daten da sind und die Wiedergabe wirklich läuft, folgt das Event playing.

Moderne Browser geben ein Promise zurück. Es wird erfüllt, wenn die Wiedergabe erfolgreich gestartet ist. Kann sie nicht starten, wird es abgelehnt. Die häufigsten Gründe:

NotAllowedError: Die Autoplay-Richtlinie des Browsers blockiert die Wiedergabe, meist weil Ton an ist und der Nutzer noch nicht mit der Seite interagiert hat.
NotSupportedError: Die Medienquelle fehlt oder hat ein Format, das der Browser nicht unterstützt.
AbortError: Die Wiedergabe wurde vor dem Start unterbrochen, zum Beispiel durch pause() oder eine neue Quelle (src).

Behandle das Promise deshalb immer mit await und try/catch oder mit .catch(). So kannst du bei blockiertem Autoplay zum Beispiel einen Play-Button anzeigen oder das Medium stummgeschaltet starten.

Rückgabewert

Typ

Promise<void>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald die Wiedergabe gestartet ist. Kann sie nicht starten, wird es mit einer DOMException abgelehnt (NotAllowedError, NotSupportedError oder AbortError). Sehr alte Browser geben undefined zurück.

Beispiele

Wiedergabe per Button starten, mit Fehlerbehandlung

const video = document.querySelector('#intro');
const button = document.querySelector('#play-btn');

button.addEventListener('click', async () => {
  try {
    await video.play();
    console.log('Wiedergabe läuft');
  } catch (err) {
    console.error(`Wiedergabe fehlgeschlagen: ${err.name}`);
  }
});

Wiedergabe läuft

Autoplay mit Rückfall auf stummgeschaltete Wiedergabe

const video = document.querySelector('video');

const startAutoplay = async () => {
  try {
    await video.play();
  } catch (err) {
    if (err.name === 'NotAllowedError') {
      // Stummgeschaltetes Autoplay erlauben die meisten Browser
      video.muted = true;
      await video.play();
      console.log('Stumm gestartet – Nutzer kann Ton aktivieren');
    } else {
      throw err;
    }
  }
};

startAutoplay();

Stumm gestartet – Nutzer kann Ton aktivieren

Play/Pause-Umschalter ohne AbortError-Warnungen

const audio = new Audio('/sounds/podcast.mp3');
const toggle = document.querySelector('#toggle');

toggle.addEventListener('click', () => {
  if (audio.paused) {
    audio.play().catch((err) => {
      // AbortError entsteht, wenn pause() vor dem Start kommt – harmlos
      if (err.name !== 'AbortError') console.error(err);
    });
  } else {
    audio.pause();
  }
});

audio.addEventListener('playing', () => { toggle.textContent = 'Pause'; });
audio.addEventListener('pause', () => { toggle.textContent = 'Abspielen'; });

// Wichtig · Fallstricke

Autoplay-Richtlinien: Chrome, Safari und Firefox blockieren Wiedergabe mit Ton, wenn der Nutzer noch nicht mit der Seite interagiert hat (Klick, Tastendruck). Stummgeschaltete Medien (muted) dürfen meist automatisch starten. Rufe play() deshalb am besten direkt in einem Klick- oder Tastatur-Handler auf.
Nicht behandelte Ablehnungen: Ohne .catch() landet jeder Fehler als Uncaught (in promise) in der Konsole. Auch der harmlose AbortError erscheint dort, wenn pause() kurz nach play() aufgerufen wird.
Zeitpunkt: Das Promise wird erst erfüllt, wenn die Wiedergabe wirklich läuft. Bei langsamem Netz kann das dauern. Für Lade-Anzeigen eignen sich die Events waiting und playing.
iOS Safari: Damit Videos nicht automatisch im Vollbild starten, braucht das Element zusätzlich das Attribut playsinline.
Kompatibilität: Sehr alte Browser (vor ca. Chrome 50, Firefox 53, Safari 10) geben kein Promise zurück. Wer sie noch unterstützen muss, prüft den Rückgabewert vor .then() auf undefined.

Siehe auch

HTMLSelectElement.item() HTMLMediaElement.load() HTMLMediaElement.pause() HTMLMediaElement.canPlayType() HTMLMediaElement.fastSeek()