MediaStreamTrack.enabled — Eigenschaft · JavaScript-Referenz

Signatur

MediaStreamTrack.enabled

Beschreibung

Mit enabled schaltet man einen Audio- oder Videotrack vorübergehend „stumm“, ohne ihn zu beenden. Ist der Wert false, liefert ein Audiotrack nur Stille und ein Videotrack nur schwarze Frames. Der Track bleibt aber aktiv (readyState bleibt "live") und lässt sich jederzeit durch Zurücksetzen auf true wieder einschalten.

Typische Einsatzfälle sind die Mikrofon-Stummschaltung und der Button „Kamera aus“ in Videokonferenzen mit WebRTC. Die Änderung wirkt sich auf alle Stellen aus, die den Track nutzen, also z. B. auf ein lokales <video>-Element und auf die über eine RTCPeerConnection gesendeten Daten. Die Gegenstelle erhält dann Stille bzw. schwarze Bilder.

Wichtig ist die Abgrenzung zu muted: muted ist schreibgeschützt und zeigt an, dass die Quelle gerade keine Daten liefern kann (z. B. durch das Betriebssystem oder ein Netzwerkproblem). enabled dagegen setzt die Anwendung selbst. Wer einen Track dauerhaft nicht mehr braucht, ruft stop() auf. Erst dann wird die Hardware freigegeben.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn der Track Medieninhalte weitergibt, sonst false. Die Eigenschaft ist les- und schreibbar. Der Standardwert eines neuen Tracks ist true.

Beispiele

Mikrofon stumm- und wieder einschalten

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

const muteButton = document.querySelector('#mute');
muteButton.addEventListener('click', () => {
  audioTrack.enabled = !audioTrack.enabled;
  muteButton.textContent = audioTrack.enabled ? 'Stummschalten' : 'Ton an';
  console.log('Mikrofon aktiv:', audioTrack.enabled);
});

Mikrofon aktiv: false

„Kamera aus“ in einer Videokonferenz

const localVideo = document.querySelector('#local');
const stream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });
localVideo.srcObject = stream;

const setCamera = (on) => {
  stream.getVideoTracks().forEach((track) => {
    track.enabled = on; // Gegenstelle sieht bei false schwarze Frames
  });
};

setCamera(false);
console.log(stream.getVideoTracks()[0].enabled, stream.getVideoTracks()[0].readyState);

false live

enabled vs. stop(): Hardware wirklich freigeben

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

track.enabled = false;           // Pausieren, Wiedereinschalten möglich
console.log(track.readyState);   // "live"

track.stop();                    // Endgültig beenden, Kamera wird freigegeben
console.log(track.readyState);   // "ended"

live ended

// Wichtig · Fallstricke

Kamera-LED: Bei enabled = false bleibt das Gerät geöffnet. Einige Browser (z. B. Firefox, neuere Chrome-Versionen) schalten die Kamera-LED nach einer kurzen Zeit aus, andere nicht. Möchte man die Privatsphäre zuverlässig schützen, beendet man den Track mit stop() und fordert ihn später neu an.
Kein Event: Eine Änderung an enabled löst kein Event aus. Die Ereignisse mute und unmute gehören zu muted und werden von der Quelle ausgelöst, nicht von der Anwendung.
Geklonte Tracks: Ein mit clone() erzeugter Track hat einen eigenen enabled-Zustand. Ändert man diesen, hat das keinen Einfluss auf das Original.
Beendete Tracks: Bei einem Track mit dem Zustand readyState === "ended" kann man den Wert zwar setzen, das hat aber keine Wirkung mehr.
Signalisierung: Die Gegenstelle einer WebRTC-Verbindung erfährt nicht direkt, dass der Track deaktiviert wurde. Sie empfängt lediglich Stille bzw. schwarze Frames. Den Status „stumm“ in der Oberfläche sollte man deshalb über einen eigenen Kanal übermitteln, z. B. über einen RTCDataChannel.
Browser-Unterstützung: Die Eigenschaft wird in allen modernen Browsern unterstützt. getUserMedia funktioniert nur in sicheren Kontexten (HTTPS).

Siehe auch

CanvasCaptureMediaStreamTrack.canvas MediaStreamTrack.label MediaStreamTrack.muted MediaStreamTrack.id MediaStreamTrack.kind