MediaStream.getTracks() — Methode · JavaScript-Referenz

Signatur

MediaStream.prototype.getTracks()

Beschreibung

getTracks() liefert eine Momentaufnahme aller Spuren (MediaStreamTrack) eines MediaStream als gewöhnliches Array. Anders als getAudioTracks() und getVideoTracks() wird nicht nach Art gefiltert: Audio- und Videospuren stehen gemeinsam im Ergebnis.

Am häufigsten braucht man die Methode, um Kamera und Mikrofon sauber freizugeben. Dazu ruft man auf jeder Spur track.stop() auf. Erst wenn alle Spuren gestoppt sind, geht die Aufnahme-Anzeige des Browsers aus. Auch bei WebRTC ist die Methode üblich: Mit RTCPeerConnection.addTrack() fügt man jede Spur des lokalen Streams der Verbindung hinzu.

Das zurückgegebene Array ist nicht live. Kommen später Spuren per addTrack() hinzu oder werden welche per removeTrack() entfernt, ändert sich ein vorher geholtes Array nicht. Rufen Sie getTracks() deshalb bei Bedarf neu auf oder reagieren Sie auf die Events addtrack und removetrack. Die Reihenfolge der Spuren ist nicht festgelegt und kann je nach Browser unterschiedlich sein.

Rückgabewert

Typ

MediaStreamTrack[]

Beschreibung

Ein Array mit allen Spuren des Streams. Hat der Stream keine Spuren, ist es leer. Das Array ist eine Momentaufnahme und aktualisiert sich nicht.

Beispiele

Kamera und Mikrofon vollständig freigeben

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

// Später: alle Spuren beenden, damit die Aufnahme-Anzeige erlischt
const stopStream = (s) => {
  s.getTracks().forEach((track) => track.stop());
  video.srcObject = null;
};

document.querySelector('#stop').addEventListener('click', () => stopStream(stream));

Spuren auflisten und Infos ausgeben

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

for (const track of stream.getTracks()) {
  console.log(`${track.kind}: ${track.label} (${track.readyState})`);
}

audio: Internes Mikrofon (live) video: FaceTime HD Camera (live)

Lokale Spuren an eine WebRTC-Verbindung übergeben

const pc = new RTCPeerConnection();
const localStream = await navigator.mediaDevices.getUserMedia({ video: true, audio: true });

// Jede Spur einzeln hinzufügen, der Stream wird als Zuordnung mitgegeben
localStream.getTracks().forEach((track) => pc.addTrack(track, localStream));

console.log(pc.getSenders().length);

2

Das Array ist nicht live

const stream = new MediaStream();
const tracks = stream.getTracks();

const canvas = document.createElement('canvas');
const [videoTrack] = canvas.captureStream().getVideoTracks();
stream.addTrack(videoTrack);

console.log(tracks.length);               // alte Momentaufnahme
console.log(stream.getTracks().length);   // neu abgefragt

0 1

// Wichtig · Fallstricke

Es wird eine Momentaufnahme zurückgegeben: Das Array aktualisiert sich nicht, wenn Spuren hinzugefügt oder entfernt werden. Fragen Sie es neu ab oder nutzen Sie die Events addtrack und removetrack.
Beendete Spuren sind weiterhin enthalten: Auch nach track.stop() bleiben Spuren im Stream, dann mit readyState === "ended". Um sie herauszunehmen, brauchen Sie removeTrack().
Die Reihenfolge ist nicht garantiert: Verlassen Sie sich nicht darauf, dass Audio vor Video steht. Filtern Sie über track.kind oder verwenden Sie getAudioTracks() bzw. getVideoTracks().
Das Gerät wird nur freigegeben, wenn alle Spuren gestoppt sind: Wird ein Track geklont (clone()) oder mehrfach genutzt, muss jede Kopie gestoppt werden. Sonst bleibt die Kamera aktiv.
Browserunterstützung: Die Methode wird in allen modernen Browsern unterstützt. getUserMedia() funktioniert allerdings nur in sicheren Kontexten (HTTPS oder localhost).

Siehe auch

MediaStream.getAudioTracks() MediaStream.getVideoTracks() MediaStream.getTrackById() MediaStream.addTrack() MediaStream.removeTrack() MediaStreamTrack.stop() MediaDevices.getUserMedia() MediaStreamTrack