MediaStream.getVideoTracks() — Methode · JavaScript-Referenz

Signatur

MediaStream.prototype.getVideoTracks()

Beschreibung

getVideoTracks() liefert alle Videospuren eines MediaStream als gewöhnliches Array von MediaStreamTrack-Objekten. Es werden nur Spuren berücksichtigt, deren Eigenschaft kind den Wert "video" hat. Audiospuren bekommt man über getAudioTracks(), alle Spuren zusammen über getTracks().

Gebraucht wird die Methode vor allem bei Kamera- und Bildschirmaufnahmen (getUserMedia(), getDisplayMedia()) sowie bei WebRTC. Typische Aufgaben sind: die Kamera ausschalten (track.enabled = false), die Kamera ganz freigeben (track.stop()), die tatsächliche Auflösung mit track.getSettings() abfragen oder mit applyConstraints() nachträglich ändern und eine Spur per RTCRtpSender.replaceTrack() austauschen.

Das Array ist eine Momentaufnahme: Kommen später mit addTrack() Spuren hinzu oder werden welche mit removeTrack() entfernt, ändert sich ein bereits zurückgegebenes Array nicht. Die Reihenfolge der Spuren ist laut Spezifikation nicht festgelegt und kann sich zwischen Aufrufen ändern. Wenn der Stream keine Videospuren enthält, ist das Array leer.

Rückgabewert

Typ

MediaStreamTrack[]

Beschreibung

Ein Array mit allen Videospuren des Streams. Enthält der Stream keine Videospuren, ist das Array leer. Es ist kein Live-Objekt, sondern eine Momentaufnahme.

Beispiele

Kamera starten und Auflösung auslesen

const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: 1280, height: 720 },
  audio: true
});

const [videoTrack] = stream.getVideoTracks();
console.log(videoTrack.label);
const { width, height, frameRate } = videoTrack.getSettings();
console.log(`${width}x${height} @ ${frameRate} fps`);

FaceTime HD Camera 1280x720 @ 30 fps

Kamera ein- und ausschalten (Stumm-Button)

const toggleButton = document.querySelector('#camera-toggle');
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
document.querySelector('video').srcObject = stream;

toggleButton.addEventListener('click', () => {
  for (const track of stream.getVideoTracks()) {
    track.enabled = !track.enabled; // schwarzes Bild, Kamera bleibt belegt
  }
  toggleButton.textContent = stream.getVideoTracks()[0].enabled
    ? 'Kamera aus'
    : 'Kamera an';
});

Kamera vollständig freigeben

const stopCamera = (stream) => {
  stream.getVideoTracks().forEach((track) => {
    track.stop(); // die Kamera-LED geht aus
    stream.removeTrack(track);
  });
  console.log('Verbleibende Videospuren:', stream.getVideoTracks().length);
};

const stream = await navigator.mediaDevices.getUserMedia({ video: true });
stopCamera(stream);

Verbleibende Videospuren: 0

Bildschirmfreigabe in einem WebRTC-Anruf

// pc ist eine bestehende RTCPeerConnection mit Kamera-Spur
const shareScreen = async (pc) => {
  const screen = await navigator.mediaDevices.getDisplayMedia({ video: true });
  const [screenTrack] = screen.getVideoTracks();

  const sender = pc.getSenders().find((s) => s.track?.kind === 'video');
  await sender.replaceTrack(screenTrack);

  // wenn der Nutzer die Freigabe über die Browser-Leiste beendet
  screenTrack.addEventListener('ended', () => {
    console.log('Bildschirmfreigabe beendet');
  });
};

// Wichtig · Fallstricke

Momentaufnahme: Das zurückgegebene Array wird nicht automatisch aktualisiert. Nach addTrack()/removeTrack() oder nach den Events addtrack/removetrack die Methode erneut aufrufen.
Die Reihenfolge ist nicht garantiert. Bei mehreren Videospuren nicht auf den Index verlassen, sondern Spuren über id oder label erkennen.
Auf ein leeres Array prüfen: stream.getVideoTracks()[0] kann undefined sein, zum Beispiel bei reinen Audio-Streams oder bei Streams einer RTCPeerConnection, deren Gegenseite (noch) kein Video sendet.
enabled = false gibt die Kamera nicht frei, die Kamera-LED bleibt also an. Erst stop() gibt die Hardware frei. Eine gestoppte Spur lässt sich nicht wieder starten, dafür ist ein neuer getUserMedia()-Aufruf nötig.
Datenschutz: label ist erst dann gefüllt, wenn der Nutzer den Zugriff auf Kamera bzw. Mikrofon erlaubt hat.
Kompatibilität: Wird von allen modernen Browsern unterstützt. getUserMedia() funktioniert nur in einem sicheren Kontext (HTTPS oder localhost).

Siehe auch

MediaStream.getAudioTracks() MediaStream.getTracks() MediaStream.removeTrack() MediaStream.addTrack() MediaStream.getTrackById()