RTCRtpScriptTransformer: sendKeyFrameRequest() method

This feature is not Baseline because it does not work in some of the most widely-used browsers.

ThesendKeyFrameRequest() method of theRTCRtpScriptTransformer interface may be called by aWebRTC Encoded Transform that is processing incoming encoded video frames, in order to request a key frame from the sender.

The method may only be called when receivingvideo (not audio) frames and if, for whatever reason, a recipient will not be able to decode the video without a new key frame.Note that the user agent can decide that the request for a key frame is not necessary, in which case the returned promise will fulfill even though the request was not actually sent.

Note:It might be called, for example, if a new user joins a WebRTC conference, in order to reduce the time before they receive a key frame and can hence start displaying video.For more information seeTriggering a key frame in Using WebRTC Encoded Transforms.

Syntax

sendKeyFrameRequest()

Parameters

None.

Return value

APromise that fulfills withundefined once the request is sent, or the user agent decides that it does not need to.

Exceptions

InvalidStateError: The de-packetizer is not processing video packets, or isundefined.

Examples

The example below shows how the main thread of a WebRTC application that is receiving encoded video might pass a decryption key to a receiver transform, and request the sender emit a key frame.

Note that the main thread doesn't have direct access to theRTCRtpScriptTransformer object, so it needs to pass the key to the worker.Here we do that with aMessageChannel, transferring the second port to the transformer code running in the worker.The code assumes there is already a peer connection, andvideoReceiver is anRTCRtpReceiver.

const worker = new Worker("worker.js");const channel = new MessageChannel();videoReceiver.transform = new RTCRtpScriptTransform(  worker,  { name: "receiverTransform", port: channel.port2 },  [channel.port2],);// Post new key to the receiverchannel.port1.start();channel.port1.postMessage({  key: "93ae0927a4f8e527f1gce6d10bc6ab6c",});

Thertctransform event handler in the worker gets the port asevent.transformer.options.port.The code snippet below shows how that is used to listen formessage events on the channel.If an event is received the handler gets thekey, and then callssendKeyFrameRequest() on the transformer.

event.transformer.options.port.onmessage = (event) => {  const { key } = event.data;  // key is used by the transformer to decrypt frames (not shown)  // Request sender to emit a key frame.  // Here 'rcEvent' is the rtctransform event.  rcEvent.transformer.sendKeyFrameRequest();};