new RTCEncodedAudioFrame() — Methode · JavaScript-Referenz

Signatur

new RTCEncodedAudioFrame(originalFrame, options)

Beschreibung

Der Konstruktor RTCEncodedAudioFrame() gehört zur WebRTC Encoded Transform API. Er erstellt aus einem vorhandenen kodierten Audio-Frame ein neues Objekt. Die Nutzdaten (data) und die Metadaten werden dabei kopiert. Die Kopie ist also vollständig unabhängig: Wird das Original verändert oder übertragen (transferiert), wirkt sich das nicht auf die Kopie aus – und umgekehrt.

Gebraucht wird das vor allem in Transform-Pipelines, die über RTCRtpScriptTransform in einem Worker laufen. Typische Fälle: Man will einen Frame duplizieren, zum Beispiel für Redundanz, Aufzeichnung oder Analyse, ohne den Frame zu verändern, der gerade in den Stream geschrieben wird. Oder man baut einen Frame mit angepassten Metadaten neu, etwa mit einem geänderten rtpTimestamp.

Über den optionalen Parameter options.metadata kannst du Metadaten der Kopie überschreiben. Felder, die du nicht angibst, übernimmt die Kopie aus dem Original, das heißt aus dem Ergebnis von originalFrame.getMetadata().

Parameter

Name	Typ	Default	Beschreibung
$originalFrame Pflicht	RTCEncodedAudioFrame		Der vorhandene kodierte Audio-Frame, von dem Daten und Metadaten kopiert werden.
$options	Object	{}	Optionales Konfigurationsobjekt.
$options.metadata	RTCEncodedAudioFrameMetadata		Metadaten, die die Werte des Originals überschreiben, z. B. `rtpTimestamp`, `synchronizationSource`, `contributingSources` oder `payloadType`. Nicht angegebene Felder übernimmt die Kopie vom Original.

Rückgabewert

Typ

RTCEncodedAudioFrame

Beschreibung

Ein neuer, unabhängiger RTCEncodedAudioFrame mit kopiertem data-Puffer und den gegebenenfalls angepassten Metadaten.

Beispiele

Frame im Worker klonen und Kopie separat auswerten

// worker.js – eingebunden über new RTCRtpScriptTransform(worker, { side: 'sender' })
addEventListener('rtctransform', (event) => {
  const { readable, writable } = event.transformer;

  const transform = new TransformStream({
    transform(frame, controller) {
      // Unabhängige Kopie für die Analyse anlegen
      const copy = new RTCEncodedAudioFrame(frame);
      console.log('Bytes:', copy.data.byteLength,
                  'SSRC:', copy.getMetadata().synchronizationSource);

      // Das Original unverändert weiterreichen
      controller.enqueue(frame);
    }
  });

  readable.pipeThrough(transform).pipeTo(writable);
});

Bytes: 83 SSRC: 2748391022

Kopie mit überschriebenem RTP-Zeitstempel erstellen

addEventListener('rtctransform', (event) => {
  const { readable, writable } = event.transformer;
  const offset = 960; // 20 ms bei 48 kHz

  readable
    .pipeThrough(new TransformStream({
      transform(frame, controller) {
        const meta = frame.getMetadata();
        const shifted = new RTCEncodedAudioFrame(frame, {
          metadata: { rtpTimestamp: (meta.rtpTimestamp + offset) >>> 0 }
        });
        controller.enqueue(shifted);
      }
    }))
    .pipeTo(writable);
});

Hauptthread: Transform an einen Sender hängen

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

const worker = new Worker('worker.js');
sender.transform = new RTCRtpScriptTransform(worker, { side: 'sender' });
console.log('Transform aktiv:', sender.transform instanceof RTCRtpScriptTransform);

Transform aktiv: true

// Wichtig · Fallstricke

Kompatibilität: Der Konstruktor ist deutlich jünger als RTCEncodedAudioFrame selbst und wird nur von neueren Browserversionen unterstützt. Vorab prüfen, zum Beispiel mit typeof RTCEncodedAudioFrame === 'function' und einem try/catch um den Aufruf.
Die Kopie verdoppelt den Speicherbedarf pro Frame. Bei 50 Frames pro Sekunde und mehreren Spuren summiert sich das, deshalb nur kopieren, wenn es nötig ist.
Überschriebene Metadaten müssen gültig sein, sonst wirft der Konstruktor eine Ausnahme, typischerweise InvalidModificationError. rtpTimestamp ist ein 32-Bit-Wert ohne Vorzeichen; mit >>> 0 bleibt er im gültigen Bereich.
Den Frame nur einmal in den Controller einreihen. Wird ein Frame nach dem enqueue() weiterverwendet oder mehrfach geschrieben, kann das zu Fehlern führen. Die Kopie ist dafür der sichere Weg.
Die API steht vor allem in Dedicated Workern zur Verfügung, die über RTCRtpScriptTransform eingebunden sind. Die ältere, nur in Chromium verfügbare Variante createEncodedStreams() ist nicht standardisiert.

Siehe auch

RTCEncodedAudioFrame RTCEncodedAudioFrame.getMetadata() RTCRtpScriptTransform new FileReader() new RTCEncodedVideoFrame()