MediaStreamTrack.clone() — Methode · JavaScript-Referenz

Signatur

MediaStreamTrack.prototype.clone()

Beschreibung

clone() liefert einen neuen MediaStreamTrack, der an dieselbe Quelle gebunden ist wie das Original, also etwa an dieselbe Kamera, dasselbe Mikrofon oder dieselbe Bildschirmfreigabe. Die Kopie bekommt eine neue, eindeutige id. Eigenschaften wie kind, label, enabled und readyState übernimmt sie vom Original, ebenso die aktuellen Constraints.

Nach dem Klonen sind beide Tracks unabhängig voneinander. Man kann die Kopie deaktivieren (enabled = false), ihr mit applyConstraints() eine andere Auflösung oder Bildrate geben oder sie mit stop() beenden. Das Original bleibt davon unberührt. Das Gerät selbst wird erst freigegeben, wenn alle Tracks gestoppt sind, die an ihm hängen.

Typische Anwendungsfälle:

Dasselbe Kamerabild in zwei Qualitätsstufen weiterverarbeiten, z. B. eine lokale Vorschau in niedriger Auflösung und eine Aufnahme in voller Auflösung.
Einen Track an eine RTCPeerConnection übergeben und gleichzeitig eine Kopie lokal stummschalten oder aufnehmen.
Einen Track an mehrere Programmteile weitergeben, die ihn jeweils selbst beenden dürfen, ohne sich gegenseitig zu stören.

Rückgabewert

Typ

MediaStreamTrack

Beschreibung

Ein neuer MediaStreamTrack mit eigener id, der an dieselbe Medienquelle gebunden ist und die aktuellen Einstellungen des Originals übernimmt.

Beispiele

Track klonen und Unabhängigkeit prüfen

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

console.log(original.id === kopie.id);   // unterschiedliche IDs
console.log(kopie.kind, kopie.readyState);

// Kopie stoppen – das Original läuft weiter
kopie.stop();
console.log(original.readyState, kopie.readyState);

false video live live ended

Vorschau in niedriger Auflösung, Aufnahme in voller Qualität

const stream = await navigator.mediaDevices.getUserMedia({
  video: { width: 1920, height: 1080 }
});
const [hdTrack] = stream.getVideoTracks();

// Kopie für die Vorschau mit reduzierter Auflösung
const vorschauTrack = hdTrack.clone();
await vorschauTrack.applyConstraints({ width: 320, height: 180 });

document.querySelector('#vorschau').srcObject = new MediaStream([vorschauTrack]);

const recorder = new MediaRecorder(new MediaStream([hdTrack]));
recorder.start();

console.log(vorschauTrack.getSettings().width, hdTrack.getSettings().width);

320 1920

Lokal stummschalten, Sendung per WebRTC bleibt aktiv

const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const [micTrack] = stream.getAudioTracks();

// Original an die Gegenstelle senden
pc.addTrack(micTrack, stream);

// Kopie für eine lokale Pegelanzeige, die sich separat abschalten lässt
const lokalerTrack = micTrack.clone();
const ctx = new AudioContext();
const quelle = ctx.createMediaStreamSource(new MediaStream([lokalerTrack]));
const analyser = ctx.createAnalyser();
quelle.connect(analyser);

// Pegelanzeige pausieren, ohne die Übertragung zu beeinflussen
lokalerTrack.enabled = false;
console.log(micTrack.enabled, lokalerTrack.enabled);

true false

// Wichtig · Fallstricke

Gerätefreigabe: Kamera oder Mikrofon bleiben aktiv, bis jeder Klon mit stop() beendet wurde. Das Kontrolllicht der Kamera leuchtet also weiter, wenn man einen Klon vergisst. Beim Aufräumen deshalb immer alle Tracks stoppen.
Zustand wird übernommen: Klont man einen deaktivierten Track (enabled = false), ist auch die Kopie deaktiviert. Klont man einen beendeten Track (readyState === "ended"), ist auch die Kopie sofort beendet.
Event-Listener werden nicht übernommen: Handler wie onended oder onmute muss man für den Klon neu registrieren.
MediaStream.prototype.clone() klont alle Tracks eines Streams auf einmal. Für den ganzen Stream ist das meist bequemer, als jeden Track einzeln zu klonen.
Constraints: Mehrere Klone mit unterschiedlichen Constraints funktionieren nicht überall gleich. Manche Browser skalieren das Bild intern herunter, andere lehnen widersprüchliche Einstellungen ab (OverconstrainedError). Mit getSettings() lässt sich prüfen, was tatsächlich eingestellt wurde.
Browser-Kompatibilität: Wird von allen modernen Browsern unterstützt. getUserMedia braucht einen sicheren Kontext (HTTPS oder localhost).

Siehe auch

MediaStreamTrack MediaStreamTrack.stop() MediaStreamTrack.applyConstraints() MediaStream.clone() MediaDevices.getUserMedia() MediaStreamTrack.enabled CanvasCaptureMediaStreamTrack.requestFrame()