Signatur
Beschreibung
Mit addTrack() fügt man einem bestehenden MediaStream eine Spur vom Typ MediaStreamTrack hinzu. So lassen sich Spuren aus verschiedenen Quellen in einem Stream zusammenfassen, zum Beispiel das Bild einer Bildschirmfreigabe (getDisplayMedia()) mit dem Ton des Mikrofons (getUserMedia()) oder das Bild eines <canvas>-Elements mit einer Audiospur für die Aufnahme per MediaRecorder.
Ist die Spur schon Teil des Streams, passiert nichts: Die Methode wirft keinen Fehler und legt kein Duplikat an. Ein Stream kann mehrere Spuren derselben Art enthalten, also etwa mehrere Audiospuren. Wer den Stream abspielt oder weiterverarbeitet, entscheidet selbst, welche Spur er nutzt.
Die Spur wird nicht kopiert, sondern als Referenz eingehängt. Dasselbe MediaStreamTrack-Objekt kann deshalb gleichzeitig zu mehreren Streams gehören. Ruft man track.stop() auf, endet die Spur in allen Streams, in denen sie steckt. Eine unabhängige Kopie bekommt man mit track.clone().
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $track Pflicht | MediaStreamTrack | Die Spur, die dem Stream hinzugefügt wird (Audio oder Video). Ist sie bereits im Stream enthalten, bleibt der Aufruf ohne Wirkung. |
Rückgabewert
undefined).Beispiele
Bildschirmfreigabe mit Mikrofon-Ton kombinieren
const startCapture = async () => {
const screen = await navigator.mediaDevices.getDisplayMedia({ video: true });
const mic = await navigator.mediaDevices.getUserMedia({ audio: true });
// Mikrofon-Spur in den Bildschirm-Stream einhängen
mic.getAudioTracks().forEach((track) => screen.addTrack(track));
console.log(screen.getTracks().map((t) => t.kind));
return screen;
};
startCapture();Canvas-Animation mit Audiospur per MediaRecorder aufnehmen
const canvas = document.querySelector('canvas');
const canvasStream = canvas.captureStream(30); // 30 fps
const audioCtx = new AudioContext();
const osc = audioCtx.createOscillator();
const dest = audioCtx.createMediaStreamDestination();
osc.connect(dest);
osc.start();
// Ton aus der Web Audio API zum Canvas-Stream hinzufügen
canvasStream.addTrack(dest.stream.getAudioTracks()[0]);
const recorder = new MediaRecorder(canvasStream);
const chunks = [];
recorder.ondataavailable = (e) => chunks.push(e.data);
recorder.onstop = () => {
const blob = new Blob(chunks, { type: recorder.mimeType });
console.log('Aufnahme fertig:', blob.size, 'Bytes');
};
recorder.start();
setTimeout(() => recorder.stop(), 3000);Doppeltes Hinzufügen und leerer Stream
const run = async () => {
const cam = await navigator.mediaDevices.getUserMedia({ video: true });
const [videoTrack] = cam.getVideoTracks();
const combined = new MediaStream();
combined.addTrack(videoTrack);
combined.addTrack(videoTrack); // ohne Wirkung, kein Duplikat
console.log(combined.getTracks().length);
document.querySelector('video').srcObject = combined;
};
run();// Wichtig · Fallstricke
- Geteilte Referenz: Die Spur wird nicht kopiert.
track.stop()beendet sie in allen Streams, in denen sie steckt. Für unabhängige Streams vorhertrack.clone()aufrufen. - MediaRecorder: Spuren, die nach
recorder.start()hinzugefügt werden, werden in den meisten Browsern nicht mitaufgenommen, oder die Aufnahme bricht ab. Stellen Sie den Stream deshalb vollständig zusammen, bevor die Aufnahme beginnt. - WebRTC:
MediaStream.addTrack()sendet die Spur nicht an die Gegenstelle. Dafür braucht esRTCPeerConnection.addTrack(track, stream), bei laufender Verbindung eventuell mit neuer Aushandlung. - Ereignisse: Wenn man
addTrack()selbst aufruft, wird keinaddtrack-Event ausgelöst. Dieses Event feuert nur, wenn der Browser eine Spur hinzufügt, etwa bei WebRTC. - Wird ein Stream schon in einem
<video>-Element abgespielt, übernehmen nicht alle Browser neue Spuren zuverlässig. Im ZweifelsrcObjectneu setzen. - Kompatibilität: wird von allen modernen Browsern unterstützt (Chrome, Firefox, Safari, Edge). Der Zugriff auf Kamera, Mikrofon oder Bildschirm funktioniert nur in einem sicheren Kontext (HTTPS).