Signatur
Beschreibung
Der Konstruktor MediaStreamTrackEvent() legt ein neues Ereignisobjekt vom Typ MediaStreamTrackEvent an. Browser lösen solche Ereignisse selbst aus, als addtrack bzw. removetrack auf einem MediaStream, zum Beispiel wenn bei einer WebRTC-Verbindung die Gegenseite eine Spur hinzufügt oder entfernt.
Selbst ruft man den Konstruktor vor allem in Tests, Mocks und bei eigenen Abstraktionen auf. Damit lässt sich Code, der auf addtrack/removetrack hört, prüfen, ohne dass eine echte Peer-Verbindung nötig ist. Das erzeugte Ereignis schickt man mit dispatchEvent() an einen MediaStream oder an ein anderes EventTarget.
Anders als bei vielen anderen Ereignis-Konstruktoren ist das Init-Objekt hier Pflicht: Es muss die Eigenschaft track mit einem gültigen MediaStreamTrack enthalten. Danach steht die Spur über die schreibgeschützte Eigenschaft event.track zur Verfügung.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $type Pflicht | string | Name des Ereignisses, groß/klein-sensitiv. Der Browser verwendet "addtrack" und "removetrack". |
|
| $eventInitDict Pflicht | object | Init-Objekt (MediaStreamTrackEventInit). Pflichtfeld track: der betroffene MediaStreamTrack. Dazu kommen optional die EventInit-Felder bubbles, cancelable und composed (Standard jeweils false). |
|
| $eventInitDict.track Pflicht | MediaStreamTrack | Die Spur, die hinzugefügt oder entfernt wurde. Sie ist danach über event.track erreichbar. |
Rückgabewert
MediaStreamTrackEvent-Objekt, dessen Eigenschaft track auf die übergebene Spur zeigt.Beispiele
Ereignis mit einer Canvas-Spur erzeugen
// Canvas liefert ohne Kamerazugriff einen echten MediaStreamTrack
const canvas = document.createElement('canvas');
const [videoTrack] = canvas.captureStream(30).getVideoTracks();
const event = new MediaStreamTrackEvent('addtrack', { track: videoTrack });
console.log(event.type);
console.log(event.track.kind);
console.log(event.track === videoTrack);addtrack-Handler ohne WebRTC testen
const stream = new MediaStream();
stream.addEventListener('addtrack', (e) => {
console.log(`Neue ${e.track.kind}-Spur: ${e.track.label || e.track.id}`);
});
// Tonspur synthetisch erzeugen
const audioCtx = new AudioContext();
const dest = audioCtx.createMediaStreamDestination();
const [audioTrack] = dest.stream.getAudioTracks();
// Achtung: addTrack() löst KEIN addtrack aus, deshalb manuell dispatchen
stream.addTrack(audioTrack);
stream.dispatchEvent(new MediaStreamTrackEvent('addtrack', { track: audioTrack }));removetrack über die on-Property simulieren
const canvas = document.createElement('canvas');
const stream = canvas.captureStream();
const [track] = stream.getVideoTracks();
stream.onremovetrack = (e) => {
console.log('Entfernt:', e.track.kind);
e.track.stop(); // Ressourcen freigeben
};
stream.removeTrack(track);
stream.dispatchEvent(new MediaStreamTrackEvent('removetrack', { track }));// Wichtig · Fallstricke
- Init-Objekt ist Pflicht:
new MediaStreamTrackEvent('addtrack')oder ein Objekt ohnetrackwirft einenTypeError. Auchtrackmuss ein echterMediaStreamTracksein; ein einfaches Objekt als Attrappe wird abgelehnt. - Keine automatischen Ereignisse bei eigenen Aufrufen:
MediaStream.addTrack()undremoveTrack()lösen keinaddtrack/removetrackaus. Das tut der Browser nur bei Änderungen, die er selbst verursacht (z. B. über WebRTC). Wer eigene Änderungen melden möchte, muss das Ereignis selbst erzeugen und dispatchen. - Selbst dispatchte Ereignisse haben
isTrusted === false. - Für WebRTC-Spuren sollte man auf
RTCPeerConnectionmeist besser das Ereignistrack(RTCTrackEvent) verwenden. - Kompatibilität: Der Konstruktor wird von Chrome, Edge, Firefox und Safari unterstützt, in Node.js gibt es ihn nicht. Echte Spuren von
getUserMedia()gibt es nur in einem sicheren Kontext (HTTPS) und nach Zustimmung des Nutzers. Für Tests eignen sichcanvas.captureStream()oderAudioContext.createMediaStreamDestination().