MediaStreamTrack.readyState — Eigenschaft · JavaScript-Referenz

Signatur

MediaStreamTrack.readyState

Beschreibung

Die schreibgeschützte Eigenschaft readyState eines MediaStreamTrack zeigt an, ob der Track noch mit seiner Quelle (Kamera, Mikrofon, Bildschirmfreigabe, Remote-Peer usw.) verbunden ist. Es gibt genau zwei mögliche Werte:

"live": Der Track ist mit einer Eingabequelle verbunden und liefert Mediendaten, soweit die Quelle das kann. Ein stummgeschalteter (muted) oder deaktivierter (enabled = false) Track bleibt trotzdem "live".
"ended": Der Track ist dauerhaft beendet und liefert keine Daten mehr. Das passiert, wenn stop() aufgerufen wurde, der Nutzer die Berechtigung entzieht, das Gerät getrennt wird, die Bildschirmfreigabe über die Browser-Oberfläche beendet wird oder der Remote-Peer den Track schließt.

Die Eigenschaft ist nützlich, wenn man vor dem Weiterverwenden eines Tracks prüfen will, ob er noch gültig ist, z. B. bevor man ihn per RTCRtpSender.replaceTrack() einer Peer-Verbindung hinzufügt, einen Screenshot mit ImageCapture macht oder Constraints ändert. Wer auf Zustandsänderungen reagieren will, sollte statt Polling lieber das ended-Event abonnieren.

Der Übergang ist nur in eine Richtung möglich: Ein beendeter Track kann nicht wieder auf "live" wechseln. Um erneut Medien zu bekommen, muss man über getUserMedia() oder getDisplayMedia() einen neuen Track anfordern.

Rückgabewert

Typ

"live" | "ended"

Beschreibung

Eine Zeichenkette: "live", solange der Track mit seiner Quelle verbunden ist, oder "ended", wenn er dauerhaft beendet ist.

Beispiele

Status vor und nach stop() abfragen

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [track] = stream.getAudioTracks();

console.log(track.readyState);

track.stop();
console.log(track.readyState);

live ended

Auf Ende der Bildschirmfreigabe reagieren

const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });
const [videoTrack] = stream.getVideoTracks();

// Wird ausgelöst, wenn der Nutzer z. B. auf „Freigabe beenden“ klickt
videoTrack.addEventListener('ended', () => {
  console.log('Freigabe beendet, Status:', videoTrack.readyState);
  document.querySelector('#share-button').disabled = false;
});

Freigabe beendet, Status: ended

Beendete Tracks vor der Wiederverwendung ersetzen

const ensureLiveTrack = async (track, constraints = { video: true }) => {
  if (track && track.readyState === 'live') {
    return track;
  }
  // Beendete Tracks lassen sich nicht reaktivieren → neu anfordern
  const stream = await navigator.mediaDevices.getUserMedia(constraints);
  return stream.getVideoTracks()[0];
};

const sender = peerConnection.getSenders().find((s) => s.track?.kind === 'video');
const liveTrack = await ensureLiveTrack(sender.track);
if (liveTrack !== sender.track) {
  await sender.replaceTrack(liveTrack);
  console.log('Track ersetzt');
}

Track ersetzt

Alle Tracks eines Streams prüfen

const isStreamActive = (stream) =>
  stream.getTracks().some((t) => t.readyState === 'live');

const stream = await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
console.log(isStreamActive(stream));
stream.getTracks().forEach((t) => t.stop());
console.log(isStreamActive(stream));

true false

// Wichtig · Fallstricke

Nicht mit muted/enabled verwechseln: Ein stummgeschalteter oder deaktivierter Track ist weiterhin "live". Nur "ended" bedeutet, dass er endgültig beendet ist.
Kein ended-Event bei stop(): Ruft man track.stop() selbst auf, wechselt readyState sofort auf "ended", das ended-Event wird dabei aber nicht ausgelöst. Das Event kommt nur, wenn das Ende von außen verursacht wird (Gerät getrennt, Berechtigung entzogen, Peer beendet usw.).
Nicht umkehrbar: Ein beendeter Track bleibt beendet. Man braucht einen neuen Track von getUserMedia() bzw. getDisplayMedia().
Geräte freigeben: Solange ein Track "live" ist, bleibt die Kamera- oder Mikrofonanzeige des Browsers aktiv. Nicht mehr benötigte Tracks deshalb immer mit stop() beenden.
Kompatibilität: Wird in allen modernen Browsern unterstützt. Der Zugriff auf Mediengeräte funktioniert nur in sicheren Kontexten (HTTPS oder localhost).

Siehe auch

MediaStreamTrack MediaStreamTrack.stop() MediaStreamTrack.muted MediaStreamTrack.enabled MediaDevices.getUserMedia() MediaStream.active