Signatur
Beschreibung
Die Eigenschaft options eines RTCRtpScriptTransformer enthält das Objekt, das beim Erzeugen des zugehörigen RTCRtpScriptTransform im Hauptthread optional als zweites Argument übergeben wurde. Der Transformer selbst existiert nur im Worker. Man bekommt ihn über das Event rtctransform als event.transformer.
Wofür das gut ist: Ein Worker kann für mehrere Transformationen zuständig sein, zum Beispiel für Sender (encode) und Empfänger (decode) oder für Audio- und Videospuren. Über options teilt der Hauptthread dem Worker mit, welche Rolle eine bestimmte Transformation hat. Typische Inhalte sind ein Feld wie operation: "encode", eine Schlüssel-ID für Ende-zu-Ende-Verschlüsselung oder ein MessagePort, über den der Worker später weitere Daten bekommt.
Das Objekt wird per Structured Clone in den Worker kopiert. Im Worker liegt also eine Kopie vor und kein Verweis auf das Original. Wenn Sie nach der Erzeugung Werte im Hauptthread ändern, sieht der Worker davon nichts. Übertragbare Objekte wie MessagePort müssen Sie zusätzlich im dritten Argument (transfer) des Konstruktors angeben.
Rückgabewert
RTCRtpScriptTransform. Wurden keine Optionen übergeben, ist der Wert undefined.Beispiele
Hauptthread: Transformationen mit Optionen anlegen
const worker = new Worker('e2ee-worker.js');
const pc = new RTCPeerConnection();
const stream = await navigator.mediaDevices.getUserMedia({ video: true });
const [track] = stream.getVideoTracks();
const sender = pc.addTrack(track, stream);
// Sender: Worker soll Frames verschlüsseln
sender.transform = new RTCRtpScriptTransform(worker, {
operation: 'encode',
keyId: 1
});
// Empfänger: Worker soll Frames entschlüsseln
pc.addEventListener('track', ({ receiver }) => {
receiver.transform = new RTCRtpScriptTransform(worker, {
operation: 'decode',
keyId: 1
});
});Worker: options auswerten und passende Transformation wählen
// e2ee-worker.js
const xorFrame = (keyId) => new TransformStream({
transform(frame, controller) {
const data = new Uint8Array(frame.data);
for (let i = 0; i < data.length; i++) data[i] ^= keyId;
frame.data = data.buffer;
controller.enqueue(frame);
}
});
addEventListener('rtctransform', (event) => {
const { transformer } = event;
const { operation, keyId } = transformer.options ?? {};
console.log(`Neue Transformation: ${operation}, Schlüssel ${keyId}`);
// XOR ist symmetrisch, echte E2EE würde je nach operation
// verschlüsseln oder entschlüsseln
transformer.readable
.pipeThrough(xorFrame(keyId))
.pipeTo(transformer.writable);
});MessagePort über options und transfer übergeben
// Hauptthread
const worker = new Worker('worker.js');
const { port1, port2 } = new MessageChannel();
sender.transform = new RTCRtpScriptTransform(
worker,
{ operation: 'encode', port: port2 },
[port2] // Port wird übertragen, nicht kopiert
);
// Später einen neuen Schlüssel schicken
port1.postMessage({ newKeyId: 7 });
// worker.js
let currentKey = 0;
addEventListener('rtctransform', ({ transformer }) => {
const { port } = transformer.options;
port.onmessage = ({ data }) => {
currentKey = data.newKeyId;
console.log('Schlüssel gewechselt auf', currentKey);
};
});// Wichtig · Fallstricke
- Nur im Worker verfügbar:
RTCRtpScriptTransformergibt es nur im Worker-Kontext. Im Hauptthread existiert nurRTCRtpScriptTransform, das selbst keineoptions-Eigenschaft hat. - Kopie statt Verweis: Die Optionen werden per Structured Clone übertragen. Funktionen, DOM-Knoten und andere nicht klonbare Werte lösen beim Konstruktor eine
DataCloneError-Ausnahme aus. - Übertragbare Objekte:
MessagePort,ArrayBufferund Ähnliches müssen zusätzlich imtransfer-Array stehen. Sonst werden sie kopiert oder die Übergabe schlägt fehl. undefinedeinplanen: Ohne zweites Argument istoptionsundefined. Destrukturieren Sie deshalb mit Fallback, z. B.transformer.options ?? {}.- Schreibgeschützt: Die Eigenschaft lässt sich nicht neu zuweisen. Änderungen zur Laufzeit gehen über einen
MessagePortoder überpostMessagean den Worker. - Browser-Unterstützung: Firefox und Safari unterstützen die API seit einiger Zeit. Chromium hatte lange nur die ältere, nicht standardisierte Methode
createEncodedStreams(). Prüfen Sie die Unterstützung mit'RTCRtpScriptTransform' in window. - Sicherheit: Legen Sie in
optionskeine geheimen Schlüssel im Klartext ab, wenn der Worker aus einer nicht vertrauenswürdigen Quelle stammt. Das Skript eines Workers hat vollen Zugriff auf die Mediendaten.