MediaStreamTrack: ended — Ereignis · JavaScript-Referenz

Signatur

track.addEventListener("ended", handler)

Beschreibung

Das Ereignis ended tritt ein, wenn eine Medienspur (Audio oder Video) dauerhaft beendet ist, weil ihre Quelle keine Daten mehr liefert. Die Eigenschaft track.readyState steht dann auf "ended". Eine beendete Spur lässt sich nicht wieder starten. Man muss eine neue anfordern, zum Beispiel über getUserMedia().

Typische Auslöser sind:

Die Person beendet die Bildschirmfreigabe über die Bedienelemente des Browsers, etwa „Freigabe beenden“.
Eine Kamera oder ein Mikrofon wird abgesteckt oder das Gerät verschwindet auf andere Weise.
Die Berechtigung für Kamera oder Mikrofon wird entzogen.
Bei WebRTC beendet die Gegenstelle das Senden oder die Verbindung wird geschlossen.

Den Handler registriert man mit track.addEventListener("ended", handler) oder über die Eigenschaft track.onended. Das Ereignis ist ein einfaches Event. Es steigt nicht im DOM auf (kein Bubbling) und lässt sich nicht abbrechen. Am häufigsten nutzt man es, um die Oberfläche aufzuräumen, wenn die Bildschirmfreigabe endet oder ein Gerät wegfällt, zum Beispiel Schaltflächen zurücksetzen, die Vorschau ausblenden oder einen Neustart anbieten.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"ended"`.
$handler Pflicht	(event: Event) => void		Callback, der ein einfaches `Event` erhält. `event.target` ist die beendete `MediaStreamTrack`.
$options	boolean \| AddEventListenerOptions	false	Optionen wie bei `addEventListener`, z. B. `{ once: true }` oder `{ signal }`.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Die Eigenschaft track.onended enthält den Handler oder null.

Beispiele

Ende der Bildschirmfreigabe über die Browser-Leiste erkennen

const startButton = document.querySelector('#share');
const preview = document.querySelector('video');

startButton.addEventListener('click', async () => {
  const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
  const [videoTrack] = stream.getVideoTracks();
  preview.srcObject = stream;
  startButton.disabled = true;

  // Wird ausgelöst, wenn die Person im Browser auf „Freigabe beenden“ klickt
  videoTrack.addEventListener('ended', () => {
    console.log('Bildschirmfreigabe beendet:', videoTrack.readyState);
    preview.srcObject = null;
    startButton.disabled = false;
  }, { once: true });
});

Bildschirmfreigabe beendet: ended

Abgesteckte Kamera per onended behandeln

const startCamera = async () => {
  const stream = await navigator.mediaDevices.getUserMedia({ video: true });
  const [track] = stream.getVideoTracks();

  track.onended = () => {
    console.warn(`Kamera "${track.label}" nicht mehr verfügbar.`);
    // Neue Spur anfordern – eine beendete Spur kann nicht neu starten
    setTimeout(() => startCamera().catch(console.error), 1000);
  };

  document.querySelector('video').srcObject = stream;
};

startCamera().catch(console.error);

Kamera "FaceTime HD Camera" nicht mehr verfügbar.

Remote-Spur bei WebRTC überwachen und Listener entfernen

const pc = new RTCPeerConnection();
const controller = new AbortController();

pc.addEventListener('track', ({ track }) => {
  track.addEventListener('ended', () => {
    console.log(`Remote-${track.kind}-Spur beendet`);
  }, { signal: controller.signal });
});

// Beim Verlassen der Seite alle ended-Listener auf einmal entfernen
const cleanup = () => {
  controller.abort();
  pc.close();
};
window.addEventListener('pagehide', cleanup);

Remote-video-Spur beendet

// Wichtig · Fallstricke

Wichtigster Fallstrick: Ruft die Seite selbst track.stop() auf, wird ended nicht ausgelöst. Den Aufräum-Code sollte man deshalb direkt beim Aufruf von stop() ausführen. Dafür bietet sich eine gemeinsame Funktion an, die sowohl der Handler als auch der eigene Stopp-Code aufruft.

Verwechslungsgefahr: ended ist ein anderes Ereignis als mute. mute und unmute melden eine vorübergehende Unterbrechung. ended ist endgültig.
Verwechslungsgefahr: Das Ereignis ended von HTMLMediaElement gibt es ebenfalls, es ist aber ein anderes. Es meldet das Ende der Wiedergabe in einem <video>- oder <audio>-Element.
Den aktuellen Zustand prüft man mit track.readyState === "ended". Das ist sinnvoll, wenn der Listener erst spät registriert wird.
Bei WebRTC-Remote-Spuren feuern die Browser ended unterschiedlich zuverlässig, etwa bei removeTrack() der Gegenstelle. Zusätzlich sollte man connectionstatechange von RTCPeerConnection beobachten.
Browser-Kompatibilität: Das Ereignis wird seit Langem von allen modernen Browsern unterstützt. Die Medienerfassung funktioniert aber nur in einem sicheren Kontext (HTTPS oder localhost).

Siehe auch

AudioScheduledSourceNode: ended MediaStreamTrack: mute MediaStreamTrack: unmute MediaStream: addtrack MediaRecorder: error