RTCRtpScriptTransformer: generateKeyFrame()

rid Optional

A string containing the "restriction identifier" ("RID") of the stream/encoder that must generate the new key frame.

The value must have between 1 and 255 characters (inclusive), and contain only the alphanumeric characters, underscore, and hyphen (A-Z, a-z, 0-9, -, _). RIDs are case sensitive and must be unique for the peer communication channel.

The first encoder that matches the specified rid is used. If no encoder matches the rid then the first encoder is used, and rid is set to the encoder's restrictions.

A Promise that fulfills with the timestamp of the frame, or rejects with an exception value.

InvalidStateError

The encoder is not processing video frames, or is undefined.

TypeError

The provided rid but does not conform to the grammar requirements.

NotFoundError

There are no video encoders. This might be raised if the corresponding RTCRtpSender is not active or its track is ended.

This method can be called by a transformer that is processing outgoing encoded video frames to force a new complete (key) frame to be sent. It might be needed by a WebRTC Encoded Transform that encrypts frames, to ensure that if a new encryption key is added, a key frame encrypted with that key is sent as soon as possible.

The sender can specify a RID (also referred to as a "restriction identifier" or "RTP stream ID") to control what codec generates the new key frame. A stream might contain (simulcast) multiple versions of the same source, each with different properties such as resolution and frame rate. The RID is used to indicate a specific RTP stream, and hence the encoder that needs to generate a new frame. Note that the available RID values are set when the transceiver used by the connection is created. The RID values being used can be queried by calling RTCRtpSender.getParameters() and inspecting the encodings property of the returned value.

The promise returned by the method will resolve just before enqueuing the corresponding key frame in a RTCRtpScriptTransformer readable.

The example below shows how the main thread might pass an encryption key to a sender transform, and trigger the codec to generate a key frame.

Note that the main thread doesn't have direct access to the RTCRtpScriptTransformer object, so it needs to pass the key and RID to the worker. Here we do that with a MessageChannel, transferring the second port to the transformer code running in the worker. The code assumes there is already a peer connection, and videoSender is an RTCRtpSender.

const worker = new Worker("worker.js");
const channel = new MessageChannel();

videoSender.transform = new RTCRtpScriptTransform(
  worker,
  { name: "senderTransform", port: channel.port2 },
  [channel.port2],
);

// Post RID and new key to the sender
channel.port1.start();
channel.port1.postMessage({
  rid: "1",
  key: "93ae0927a4f8e527f1gce6d10bc6ab6c",
});

The rtctransform event handler in the worker gets the port and uses it to listen for message events. If an event is received it gets the rid and key, and then calls generateKeyFrame().

event.transformer.options.port.onmessage = (event) => {
  const { rid, key } = event.data;
  // key is used by the transformer to encrypt frames (not shown)

  // Get codec to generate a new key frame using the rid
  // Here 'rcEvent' is the rtctransform event.
  rcEvent.transformer.generateKeyFrame(rid);
};

• Using WebRTC Encoded Transforms