# SFrame transforms

SFrame transforms of WebRTC Encoded Transform, which encrypt encoded frames end to end with SFrame (RFC 9605).

A key is given as the raw bytes of the RFC 9605 base key together with a key id, in place of a `CryptoKey`. Whole
frames are encrypted (“per-frame”). Video negotiates raw RTP packetization, so every codec works; with a peer that
doesn’t support it, H.264 and AV1 can’t be used, and VP8 may recover from a lost key frame slowly.

### webrtc.interfaces.sframe_transform.SFrameInput

A chunk the SFrame streams take, which is an encoded frame or any buffer

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) | [`Buffer`](https://docs.python.org/3/library/collections.abc.html#collections.abc.Buffer)

### webrtc.interfaces.sframe_transform.SFrameChunk

A chunk the SFrame streams output, which is the encoded frame written or [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) for a buffer

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) | [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes)

### *class* webrtc.interfaces.sframe_transform.RTCRtpSFrameEncryptor(options)

Encrypts the frames of a sender with SFrame, once set as its `transform`.

Frames are encrypted natively, off the event loop. Until a key is set, frames are dropped so none go out in
clear.

* **Parameters:**
  **options** ([`webrtc.RTCRtpSFrameEncryptorOptions`](../models/sframe_transform_options.md#webrtc.models.sframe_transform_options.RTCRtpSFrameEncryptorOptions)) – The cipher suite and SFrame type.
* **Raises:**
  * [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the options aren’t [`webrtc.SFrameTransformOptions`](../models/sframe_transform_options.md#webrtc.models.sframe_transform_options.SFrameTransformOptions).
  * [**webrtc.NotSupportedError**](../exceptions.md#webrtc.exceptions.NotSupportedError) – For the `'per-packet'` type, because SFrame RTP packetization isn’t available.

Example:

```default
encryptor = webrtc.RTCRtpSFrameEncryptor(webrtc.RTCRtpSFrameEncryptorOptions('AES_128_GCM_SHA256_128'))
await encryptor.set_encryption_key(key, 1)
sender.transform = encryptor
```

### *class* webrtc.interfaces.sframe_transform.RTCRtpSFrameDecryptor(options)

Decrypts the SFrame frames of a receiver, once set as its `transform`.

Frames are decrypted natively, off the event loop. A frame that fails to decrypt is dropped and reported by an
`error` event.

* **Parameters:**
  **options** ([`webrtc.SFrameTransformOptions`](../models/sframe_transform_options.md#webrtc.models.sframe_transform_options.SFrameTransformOptions)) – The cipher suite.
* **Raises:**
  [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the options aren’t [`webrtc.SFrameTransformOptions`](../models/sframe_transform_options.md#webrtc.models.sframe_transform_options.SFrameTransformOptions).
* **Events:**
  **error** ([`webrtc.SFrameTransformErrorEvent`](../models/events.md#webrtc.models.events.SFrameTransformErrorEvent)) – A frame didn’t decrypt.

### Events

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

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

### *class* webrtc.interfaces.sframe_transform.SFrameEncryptorStream(options)

A transform stream that encrypts the frames or buffers written to it with SFrame.

It has `readable` and `writable` like a [`webrtc.TransformStream`](../streams.md#webrtc.streams.TransformStream), so it can be piped through in
the worker of an [`webrtc.RTCRtpScriptTransform`](rtc_rtp_script_transform.md#webrtc.interfaces.rtc_rtp_script_transform.RTCRtpScriptTransform). A frame comes out with its data encrypted, and a buffer
comes out as the [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) of the ciphertext. Until a key is set, chunks are dropped. The type parameter is
the output type. It’s encoded frames by default, and `SFrameEncryptorStream[bytes]` handles buffers.

* **Parameters:**
  **options** ([`webrtc.SFrameTransformOptions`](../models/sframe_transform_options.md#webrtc.models.sframe_transform_options.SFrameTransformOptions)) – The cipher suite.
* **Raises:**
  [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the options aren’t [`webrtc.SFrameTransformOptions`](../models/sframe_transform_options.md#webrtc.models.sframe_transform_options.SFrameTransformOptions).

Example:

```default
async def worker(event):
    encryptor = webrtc.SFrameEncryptorStream(webrtc.SFrameTransformOptions('AES_128_GCM_SHA256_128'))
    await encryptor.set_encryption_key(key, 1)
    transformer = event.transformer
    await transformer.readable.pipe_through(encryptor).pipe_to(transformer.writable)
```

### *class* webrtc.interfaces.sframe_transform.SFrameDecryptorStream(options)

A transform stream that decrypts the SFrame frames or buffers written to it.

It has `readable` and `writable` like a [`webrtc.TransformStream`](../streams.md#webrtc.streams.TransformStream). A frame comes out with its
data decrypted, and a buffer comes out as the [`bytes`](https://docs.python.org/3/builtins/stdtypes.html#bytes) of the plaintext. A chunk that fails to decrypt is
dropped and reported by an `error` event. The type parameter is the output type. It’s encoded frames by
default, and `SFrameDecryptorStream[bytes]` handles buffers.

* **Parameters:**
  **options** ([`webrtc.SFrameTransformOptions`](../models/sframe_transform_options.md#webrtc.models.sframe_transform_options.SFrameTransformOptions)) – The cipher suite.
* **Raises:**
  [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError) – If the options aren’t [`webrtc.SFrameTransformOptions`](../models/sframe_transform_options.md#webrtc.models.sframe_transform_options.SFrameTransformOptions).
* **Events:**
  **error** ([`webrtc.SFrameTransformErrorEvent`](../models/events.md#webrtc.models.events.SFrameTransformErrorEvent)) – A chunk didn’t decrypt.

### Events

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

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