MediaStream.active — Eigenschaft · JavaScript-Referenz

Signatur

MediaStream.active

Beschreibung

Die schreibgeschützte Eigenschaft active eines MediaStream zeigt an, ob der Stream gerade aktiv ist. Ein Stream gilt als aktiv, wenn mindestens einer seiner MediaStreamTracks nicht den readyState "ended" hat. Sind alle Spuren beendet oder enthält der Stream keine Spuren, liefert active den Wert false.

In der Praxis brauchen Sie die Eigenschaft, um nach getUserMedia(), getDisplayMedia() oder bei WebRTC-Verbindungen zu prüfen, ob ein Stream noch Daten liefert – etwa bevor Sie ihn einem <video>-Element zuweisen, eine Aufnahme mit MediaRecorder starten oder die Oberfläche („Kamera an/aus“) aktualisieren.

Wichtig: active sagt nichts darüber aus, ob eine Spur stummgeschaltet (muted) oder deaktiviert (enabled = false) ist. Eine deaktivierte, aber nicht beendete Spur hält den Stream aktiv. Erst track.stop() oder das Beenden durch den Browser/Nutzer (z. B. Bildschirmfreigabe beenden) setzt die Spur auf "ended".

Rückgabewert

Typ

boolean

Beschreibung

true, wenn mindestens eine Spur nicht beendet ist; sonst false.

Beispiele

Kamera-Stream öffnen und Status prüfen

const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
console.log('Aktiv nach Start:', stream.active);

// Alle Spuren beenden
stream.getTracks().forEach((track) => track.stop());
console.log('Aktiv nach stop():', stream.active);

Aktiv nach Start: true Aktiv nach stop(): false

Vor dem Aufnehmen sicherstellen, dass der Stream lebt

const startRecording = (stream) => {
  if (!stream.active) {
    console.warn('Stream ist nicht mehr aktiv – Aufnahme abgebrochen.');
    return null;
  }
  const recorder = new MediaRecorder(stream);
  recorder.start();
  return recorder;
};

const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const recorder = startRecording(stream);
console.log(recorder?.state);

recording

Bildschirmfreigabe: Ende erkennen und UI aktualisieren

const button = document.querySelector('#share');
const stream = await navigator.mediaDevices.getDisplayMedia({ video: true });

const updateUi = () => {
  button.textContent = stream.active ? 'Freigabe läuft' : 'Freigabe starten';
};

// Nutzer beendet die Freigabe über die Browser-Leiste
stream.getVideoTracks()[0].addEventListener('ended', () => {
  updateUi();
  console.log('active:', stream.active);
});
updateUi();

active: false

enabled = false hält den Stream aktiv

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

mic.enabled = false; // nur stummschalten
console.log(stream.active); // weiterhin true

mic.stop(); // wirklich beenden
console.log(stream.active);

true false

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung wie stream.active = false wird ignoriert (im strikten Modus TypeError). Zum Beenden track.stop() auf allen Spuren aufrufen.
Nicht mit enabled/muted verwechseln: Stummgeschaltete oder deaktivierte Spuren zählen weiterhin als aktiv – die Kamera-LED kann also noch leuchten.
Kein Polling nötig: Statt active regelmäßig abzufragen, auf das ended-Ereignis der einzelnen Spuren hören. Die früheren Stream-Ereignisse active/inactive sind nicht standardisiert und nur in Chromium verfügbar – nicht darauf verlassen.
Ein leerer Stream (new MediaStream() ohne Spuren) ist false; durch addTrack() einer lebenden Spur wird er aktiv.
getUserMedia() funktioniert nur in sicheren Kontexten (HTTPS oder localhost) und erfordert eine Nutzerfreigabe.
Die ältere Eigenschaft MediaStream.ended ist veraltet und wurde durch active ersetzt.

Siehe auch

MediaStream.id MediaStreamTrack.id MediaStreamTrack.kind MediaStreamTrack.label MediaStreamTrack.muted