HTMLMediaElement.ended — Eigenschaft · JavaScript-Referenz

Signatur

HTMLMediaElement.ended

Beschreibung

Die schreibgeschützte Eigenschaft ended eines <audio>- oder <video>-Elements gibt einen booleschen Wert zurück. Er ist true, wenn die aktuelle Wiedergabeposition (currentTime) das Ende der Medienressource erreicht hat, die Wiedergaberichtung vorwärts ist und das Element nicht im Schleifenmodus (loop) läuft.

Typische Einsatzfälle sind: den Zustand eines Wiedergabe-Buttons bestimmen (Abspielen vs. Neu starten), in einer Playlist prüfen, ob das nächste Element geladen werden soll, oder beim Wiederherstellen eines UI-Zustands abfragen, ob ein Video bereits vollständig angesehen wurde.

Für eine Reaktion auf das Ende der Wiedergabe ist das Ereignis ended meist besser geeignet als ein wiederholtes Abfragen der Eigenschaft. Die Eigenschaft eignet sich vor allem für die punktuelle Zustandsabfrage, etwa in einem Klick-Handler.

Bei Livestreams (z. B. MediaStream über srcObject) liefert ended in der Regel false, da kein definiertes Ende existiert.

Beispiele

Wiedergabestatus einfach abfragen

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

console.log(video.ended); // vor dem Abspielen

video.addEventListener('ended', () => {
  console.log('Beendet?', video.ended);
});

false Beendet? true

Play-Button: Abspielen oder neu starten

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

button.addEventListener('click', async () => {
  if (video.ended) {
    // Nach dem Ende von vorne beginnen
    video.currentTime = 0;
  }
  try {
    await video.play();
  } catch (err) {
    console.warn('Wiedergabe blockiert:', err.name);
  }
});

video.addEventListener('ended', () => {
  button.textContent = 'Nochmal ansehen';
});
video.addEventListener('play', () => {
  button.textContent = 'Abspielen';
});

Einfache Audio-Playlist

const tracks = ['intro.mp3', 'kapitel1.mp3', 'kapitel2.mp3'];
let index = 0;
const audio = new Audio(tracks[index]);

audio.addEventListener('ended', () => {
  console.log(`Track ${index + 1} fertig:`, audio.ended);
  index += 1;
  if (index < tracks.length) {
    audio.src = tracks[index];
    audio.play();
  } else {
    console.log('Playlist beendet');
  }
});

audio.play();

Track 1 fertig: true Track 2 fertig: true Track 3 fertig: true Playlist beendet

Wirkung von loop

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

// Mit loop=true wird ended nie true und das Ereignis 'ended' feuert nicht
video.addEventListener('timeupdate', () => {
  if (video.currentTime >= video.duration - 0.25) {
    console.log('Kurz vor Schleifenende, ended =', video.ended);
  }
});

Kurz vor Schleifenende, ended = false

// Wichtig · Fallstricke

Schreibgeschützt: Zuweisungen wie video.ended = true werden ignoriert (im Strict Mode TypeError).
loop: Ist loop gesetzt, wird ended nie true und das ended-Ereignis wird nicht ausgelöst.
Zurücksetzen: Sobald currentTime verändert, load() aufgerufen oder eine neue src gesetzt wird, ist ended wieder false. Ein erneutes play() nach dem Ende springt automatisch an den Anfang.
Rückwärtswiedergabe: Bei negativer playbackRate (kaum unterstützt) gilt das Erreichen des Anfangs laut Spezifikation nicht als „beendet“ im Sinne dieser Eigenschaft.
Kein Ersatz für Ereignisse: Statt ended in einem Intervall abzufragen, lieber auf das ended-Ereignis hören.
Kompatibilität: In allen modernen Browsern seit Jahren unterstützt; Unterschiede gibt es höchstens bei Streams (MSE/HLS), wo ein Ende erst nach MediaSource.endOfStream() erkannt wird.

Siehe auch

HTMLMediaElement.paused HTMLMediaElement.loop HTMLMediaElement.currentTime HTMLMediaElement.duration HTMLMediaElement.play() HTMLMediaElement