RTCRtpScriptTransform

Script transforms of WebRTC Encoded Transform, which process the encoded frames of a sender or receiver in Python.

There are no Workers. The worker of a transform is a Python callable run on the event loop that created the transform.

webrtc.interfaces.rtc_rtp_script_transform.Worker

The callable a transform runs with its rtctransform event, either a plain or a coroutine function

alias of Callable[[RTCTransformEvent], object]

webrtc.interfaces.rtc_rtp_script_transform.EncodedFrame

An encoded video or audio frame

alias of RTCEncodedVideoFrame | RTCEncodedAudioFrame

class webrtc.interfaces.rtc_rtp_script_transform.WorkerAndParameters(worker, type=None)

The worker of an RTCRtpScriptTransform and the kind of frames it outputs.

Parameters:

worker (callable) – Called with the rtctransform event. A coroutine function runs as a task.
type (webrtc.RTCRtpScriptTransformType, optional) – 'sframe' if the worker outputs SFrame-encrypted frames. RTCRtpScriptTransform doesn’t support it, because the native engine has no SFrame packetization of RTP.

Raises:

TypeError – If the worker isn’t callable.
ValueError – If the type isn’t a member of webrtc.RTCRtpScriptTransformType.

class webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransformer(transform, options)

A pair of streams with the encoded frames of the sender or receiver of an RTCRtpScriptTransform.

The worker gets it as the transformer of the rtctransform event. Frames read from readable and written to writable go on to the packetizer or the decoder, whether they were changed or not. Frames that aren’t written are dropped. Up to 120 unread frames are queued, and after that the oldest is dropped. Both streams end once the transform is removed from its sender or receiver.

See MDN: RTCRtpScriptTransformer.

Events:: keyframerequest (webrtc.KeyFrameRequestEvent) – The remote peer asked for a key frame.

Events

keyframerequest: Event

Handlers are registered with on().

property readable: ReadableStream[RTCEncodedVideoFrame | RTCEncodedAudioFrame]

The incoming encoded frames, video or audio.

See MDN: RTCRtpScriptTransformer/readable.

Type:: webrtc.ReadableStream

property writable: WritableStream[RTCEncodedVideoFrame | RTCEncodedAudioFrame]

Takes the frames that were read, so they can be sent or decoded.

It drops frames of another transformer, constructed copies, and frames written out of order or twice. Writing anything other than an encoded frame errors the stream with TypeError.

See MDN: RTCRtpScriptTransformer/writable.

Type:: webrtc.WritableStream

property options: object

The options given to the transform. This is the same object, so no copy is made.

See MDN: RTCRtpScriptTransformer/options.

async generate_key_frame(rid=None)

Asks the encoder of the sender for a key frame and returns once one is read from readable.

See MDN: RTCRtpScriptTransformer/generateKeyFrame.

Parameters:

rid (str, optional) – The simulcast layer. None asks every layer and returns with the first key frame.

Raises:

webrtc.InvalidStateError – If the transform isn’t of a video sender, or is removed.
webrtc.NotAllowedError – If the rid isn’t alphanumeric or is longer than 255 characters.
webrtc.NotFoundError – If the sender has no layer of that rid.

async send_key_frame_request()

Asks the remote sender for a key frame by sending a picture loss indication.

See MDN: RTCRtpScriptTransformer/sendKeyFrameRequest.

Raises:: webrtc.InvalidStateError – If the transform isn’t of a video receiver.

class webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransform(worker_or_worker_and_parameters, options=None, transfer=None)

Processes the encoded frames of a sender or receiver in Python, once set as its transform.

Soon after construction, the worker is called on the current event loop with an webrtc.RTCTransformEvent whose transformer reads and writes the frames. A coroutine function runs as a task of that loop, and an exception it raises goes to the exception handler of the loop. A transform serves only one sender or receiver.

See MDN: RTCRtpScriptTransform.

Parameters:

worker_or_worker_and_parameters (callable or WorkerAndParameters) – The worker.
options (optional) – Any value, available as RTCRtpScriptTransformer.options.
transfer (list, optional) – Objects to transfer. Nothing is detached, and the objects are only checked to be listed once.

Raises:

TypeError – If the worker isn’t callable or transfer isn’t a sequence.
webrtc.NotSupportedError – If the type of the worker is 'sframe'.
webrtc.DataCloneError – If an object is in transfer more than once.
RuntimeError – If called outside of a running event loop.

Example:

async def worker(event):
    transformer = event.transformer
    writer = transformer.writable.get_writer()
    async for frame in transformer.readable:
        frame.data = encrypt(frame.data)
        await writer.write(frame)


sender.transform = webrtc.RTCRtpScriptTransform(worker)