# 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`](../models/events.md#webrtc.models.events.RTCTransformEvent)], [`object`](https://docs.python.org/3/builtins/functions.html#object)]

### webrtc.interfaces.rtc_rtp_script_transform.EncodedFrame

An encoded video or audio frame

alias of [`RTCEncodedVideoFrame`](../models/rtc_encoded_frame.md#webrtc.models.rtc_encoded_frame.RTCEncodedVideoFrame) | [`RTCEncodedAudioFrame`](../models/rtc_encoded_frame.md#webrtc.models.rtc_encoded_frame.RTCEncodedAudioFrame)

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

The worker of an [`RTCRtpScriptTransform`](#webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransform) and the kind of frames it outputs.

* **Parameters:**
  * **worker** ([`callable`](https://docs.python.org/3/builtins/functions.html#callable)) – Called with the `rtctransform` event. A coroutine function runs as a task.
  * **type** ([`webrtc.RTCRtpScriptTransformType`](../enums.md#webrtc.enums.RTCRtpScriptTransformType), optional) – `'sframe'` if the worker outputs
    SFrame-encrypted frames. [`RTCRtpScriptTransform`](#webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransform) doesn’t support it, because the native engine
    has no SFrame packetization of RTP.
* **Raises:**
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the worker isn’t callable.
  * [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError) – If the type isn’t a member of [`webrtc.RTCRtpScriptTransformType`](../enums.md#webrtc.enums.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`](#webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransform).

The worker gets it as the `transformer` of the `rtctransform` event. Frames read from [`readable`](#webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransformer.readable) and
written to [`writable`](#webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransformer.writable) go on to the packetizer or the decoder, whether they were changed or not. Frames
that aren’t written are dropped. Up to 60 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](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpScriptTransformer).

* **Events:**
  **keyframerequest** ([`webrtc.KeyFrameRequestEvent`](../models/events.md#webrtc.models.events.KeyFrameRequestEvent)) – The remote peer asked for a key frame.

### Events

- `keyframerequest`: [`Event`](../models/events.md#webrtc.models.events.Event)

Handlers are registered with [`on()`](../events.md#webrtc.utils.events.UniformEventTarget.on).

#### *property* readable *: [ReadableStream](../streams.md#webrtc.streams.ReadableStream)[[RTCEncodedVideoFrame](../models/rtc_encoded_frame.md#webrtc.models.rtc_encoded_frame.RTCEncodedVideoFrame) | [RTCEncodedAudioFrame](../models/rtc_encoded_frame.md#webrtc.models.rtc_encoded_frame.RTCEncodedAudioFrame)]*

The incoming encoded frames, video or audio.

See [MDN: RTCRtpScriptTransformer/readable](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpScriptTransformer/readable).

* **Type:**
  [`webrtc.ReadableStream`](../streams.md#webrtc.streams.ReadableStream)

#### *property* writable *: [WritableStream](../streams.md#webrtc.streams.WritableStream)[[RTCEncodedVideoFrame](../models/rtc_encoded_frame.md#webrtc.models.rtc_encoded_frame.RTCEncodedVideoFrame) | [RTCEncodedAudioFrame](../models/rtc_encoded_frame.md#webrtc.models.rtc_encoded_frame.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`](https://docs.python.org/3/builtins/exceptions.html#TypeError).

See [MDN: RTCRtpScriptTransformer/writable](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpScriptTransformer/writable).

* **Type:**
  [`webrtc.WritableStream`](../streams.md#webrtc.streams.WritableStream)

#### *property* options *: [object](https://docs.python.org/3/builtins/functions.html#object)*

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

See [MDN: RTCRtpScriptTransformer/options](https://developer.mozilla.org/en-US/docs/Web/API/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`](#webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransformer.readable).

See [MDN: RTCRtpScriptTransformer/generateKeyFrame](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpScriptTransformer/generateKeyFrame).

* **Parameters:**
  **rid** ([`str`](https://docs.python.org/3/builtins/stdtypes.html#str), optional) – The simulcast layer. [`None`](https://docs.python.org/3/builtins/constants.html#None) asks every layer and returns with the
  first key frame.
* **Raises:**
  * [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.InvalidStateError) – If the transform isn’t of a video sender, or is removed.
  * [**webrtc.NotAllowedError**](../exceptions.md#webrtc.exceptions.NotAllowedError) – If the rid isn’t alphanumeric or is longer than 255 characters.
  * [**webrtc.NotFoundError**](../exceptions.md#webrtc.exceptions.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](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpScriptTransformer/sendKeyFrameRequest).

* **Raises:**
  [**webrtc.InvalidStateError**](../exceptions.md#webrtc.exceptions.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`](../models/events.md#webrtc.models.events.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](https://developer.mozilla.org/en-US/docs/Web/API/RTCRtpScriptTransform).

* **Parameters:**
  * **worker_or_worker_and_parameters** ([`callable`](https://docs.python.org/3/builtins/functions.html#callable) or [`WorkerAndParameters`](#webrtc.interfaces.rtc_rtp_script_transform.WorkerAndParameters)) – The worker.
  * **options** (*optional*) – Any value, available as [`RTCRtpScriptTransformer.options`](#webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransformer.options).
  * **transfer** ([`list`](https://docs.python.org/3/builtins/stdtypes.html#list), optional) – Objects to transfer. Nothing is detached, and the objects are only
    checked to be listed once.
* **Raises:**
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the worker isn’t callable or `transfer` isn’t a sequence.
  * [**webrtc.NotSupportedError**](../exceptions.md#webrtc.exceptions.NotSupportedError) – If the type of the worker is `'sframe'`.
  * [**webrtc.DataCloneError**](../exceptions.md#webrtc.exceptions.DataCloneError) – If an object is in `transfer` more than once.
  * [**RuntimeError**](https://docs.python.org/3/builtins/exceptions.html#RuntimeError) – If called outside of a running event loop.

Example:

```default
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)
```