HTMLMediaElement: play — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("play", handler)

Beschreibung

Das play-Ereignis eines <audio>- oder <video>-Elements tritt auf, sobald die Eigenschaft paused von true auf false wechselt. Auslöser sind ein Aufruf von HTMLMediaElement.play(), das autoplay-Attribut oder die eingebauten Bedienelemente (controls).

Wichtig: play heißt nur, dass die Wiedergabe angefordert wurde. Ob tatsächlich schon Bild oder Ton ausgegeben wird, ist damit noch nicht gesagt. Wenn noch nicht genug Daten geladen sind, folgt zunächst waiting. Sobald die Wiedergabe wirklich läuft, feuert playing. Für UI-Zustände wie einen „Pause“-Button reicht play. Für Ladeanzeigen oder Zeitmessungen ist playing die bessere Wahl.

Das Ereignis ist nicht abbrechbar (cancelable: false) und steigt im DOM nicht auf (bubbles: false). Registrieren kannst du es per addEventListener("play", …) oder über die Eigenschaft onplay. Wenn du alle Medienelemente einer Seite zentral überwachen willst, brauchst du dafür die Capture-Phase ({ capture: true }).

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"play"`.
$handler Pflicht	(event: Event) => void		Callback, der ein einfaches `Event`-Objekt erhält. `event.target` ist das Medienelement.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `once`, `capture`, `signal` oder `passive`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein Event (keine speziellen Zusatz-Eigenschaften).

Beispiele

Wiedergabestart mit addEventListener erfassen

const video = document.querySelector('video');
const button = document.querySelector('#toggle');

video.addEventListener('play', () => {
  button.textContent = 'Pause';
  console.log(`Wiedergabe gestartet bei ${video.currentTime.toFixed(1)} s`);
});

video.addEventListener('pause', () => {
  button.textContent = 'Abspielen';
});

button.addEventListener('click', () => {
  video.paused ? video.play() : video.pause();
});

Wiedergabe gestartet bei 0.0 s

onplay-Eigenschaft und removeEventListener

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

// Variante 1: on-Property (überschreibt einen vorherigen Handler)
audio.onplay = () => console.log('Audio läuft');

// Variante 2: benannter Handler, der später wieder entfernt wird
const trackFirstPlay = () => {
  console.log('Erster Start – Analytics-Event senden');
  audio.removeEventListener('play', trackFirstPlay);
};
audio.addEventListener('play', trackFirstPlay);
// Alternativ: audio.addEventListener('play', trackFirstPlay, { once: true });

Audio läuft Erster Start – Analytics-Event senden

Nur ein Medium gleichzeitig abspielen (Capture-Phase)

// play steigt nicht auf, deshalb in der Capture-Phase lauschen
document.addEventListener('play', (event) => {
  document.querySelectorAll('audio, video').forEach((media) => {
    if (media !== event.target && !media.paused) {
      media.pause();
    }
  });
}, { capture: true });

play-Event vs. abgelehntes play()-Promise

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

video.addEventListener('play', () => console.log('play-Event'));
video.addEventListener('playing', () => console.log('playing-Event: läuft wirklich'));

const start = async () => {
  try {
    await video.play();
    console.log('Promise erfüllt');
  } catch (err) {
    // z. B. NotAllowedError durch Autoplay-Sperre
    console.warn(`Start fehlgeschlagen: ${err.name}`);
  }
};
start();

play-Event playing-Event: läuft wirklich Promise erfüllt

// Wichtig · Fallstricke

Nicht mit playing verwechseln: play feuert schon beim Wechsel des paused-Zustands, auch wenn noch gepuffert wird. Die tatsächliche Wiedergabe meldet playing.
Kein Bubbling: Event-Delegation auf einem Elternelement funktioniert nur mit { capture: true }.
Autoplay-Richtlinien: Moderne Browser blockieren Autoplay mit Ton ohne Nutzerinteraktion. Dann wird das Promise von play() mit NotAllowedError abgelehnt und paused bleibt true. Ein play-Event feuert in diesem Fall nicht. Stummgeschaltetes Autoplay (muted) ist meist erlaubt.
Rufst du play() auf einem Element auf, das bereits läuft, wird kein weiteres play-Event ausgelöst.
onplay nimmt nur einen einzigen Handler auf. Für mehrere Listener nutzt du addEventListener.
Browser-Kompatibilität: Das Ereignis wird von allen modernen Browsern unterstützt (Baseline). Das Promise als Rückgabewert von play() fehlt allerdings in sehr alten Browsern.

Siehe auch

HTMLMediaElement.play() HTMLMediaElement.paused HTMLMediaElement HTMLDialogElement: close HTMLMediaElement: canplay