feat(rtc)!: move the WebRTC transport from aiortc to the Rust Video SDK

.github/actions/python-uv-setup/action.yml

@@ -13,9 +13,34 @@ inputs:
     description: Directory to run in
     required: false
     default: "."
+  build-extension:
+    description: Build getstream-rtc (the Rust extension) into the environment; "false" installs everything else
+    required: false
+    default: "true"
 runs:
   using: composite
   steps:
+    - name: Install the native build dependencies
+      if: ${{ inputs.build-extension == 'true' }}
+      shell: bash
+      # libvpx is linked from the system; bindgen needs libclang to generate its bindings.
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y --no-install-recommends libvpx-dev libclang-dev
+
+    - name: Install the Rust toolchain
+      if: ${{ inputs.build-extension == 'true' }}
+      shell: bash
+      working-directory: ${{ inputs.working-directory }}/getstream-rtc
+      # Installs the toolchain pinned in getstream-rtc/rust-toolchain.toml.
+      run: rustup toolchain install
+
+    - name: Cache the Rust build
+      if: ${{ inputs.build-extension == 'true' }}
+      uses: Swatinem/rust-cache@v2
+      with:
+        workspaces: ${{ inputs.working-directory }}/getstream-rtc
+
     - name: Install the latest version of uv
       id: setup_uv
       uses: astral-sh/setup-uv@v7
@@ -38,5 +63,4 @@ runs:
     - name: Install the project dependencies
       shell: bash
       working-directory: ${{ inputs.working-directory }}
-      run: uv sync ${{ inputs.sync-flags }}
-
+      run: uv sync ${{ inputs.sync-flags }} ${{ inputs.build-extension != 'true' && '--no-install-package getstream-rtc' || '' }}

.github/workflows/run_integration.yml

@@ -31,10 +31,13 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+        with:
+          persist-credentials: false
       - name: Install dependencies
         uses: ./.github/actions/python-uv-setup
         with:
           python-version: ${{ matrix.python-version }}
+          build-extension: "false"
       - name: Run integration tests
         env:
           STREAM_API_KEY: ${{ vars.STREAM_CHAT_API_KEY }}
@@ -55,6 +58,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+        with:
+          persist-credentials: false
       - name: Install dependencies
         uses: ./.github/actions/python-uv-setup
         with:

.github/workflows/run_tests.yml

@@ -23,8 +23,12 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+        with:
+          persist-credentials: false
       - name: Install dependencies
         uses: ./.github/actions/python-uv-setup
+        with:
+          build-extension: "false"
       - name: Run linter
         run: make lint
 
@@ -34,11 +38,49 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+        with:
+          persist-credentials: false
       - name: Install dependencies
         uses: ./.github/actions/python-uv-setup
+        # ty reads getstream_rtc from getstream-rtc/ (see make typecheck), not the built extension.
+        with:
+          build-extension: "false"
       - name: Run type checker
         run: make typecheck
 
+  rust:
+    name: 🦀 Rust
+    runs-on: ubuntu-latest
+    env:
+      # The same interpreter for clippy and the tests, so the PyO3 build is reused.
+      PYO3_PYTHON: /usr/bin/python3
+    defaults:
+      run:
+        # rustup reads the toolchain from the current directory.
+        working-directory: getstream-rtc
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          persist-credentials: false
+      - name: Install the native build dependencies
+        # The tests link libpython of the system Python.
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y --no-install-recommends libvpx-dev libclang-dev python3-dev
+      - name: Install the Rust toolchain
+        run: rustup toolchain install
+      - name: Cache the Rust build
+        uses: Swatinem/rust-cache@v2
+        with:
+          workspaces: getstream-rtc
+      - name: Check formatting
+        run: cargo fmt --check
+      - name: Run clippy
+        run: cargo clippy --all-targets -- -D warnings
+      - name: Run the unit tests
+        run: cargo test --lib
+
   # ── Non-video tests (chat, feeds, etc.) ────────────────────────────
   # Uses STREAM_CHAT_* credentials which do NOT have video enabled.
   # Video paths and manual test paths are defined in the Makefile.
@@ -53,10 +95,13 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+        with:
+          persist-credentials: false
       - name: Install dependencies
         uses: ./.github/actions/python-uv-setup
         with:
           python-version: ${{ matrix.python-version }}
+          build-extension: "false"
       - name: Run tests
         run: make test
 
@@ -73,6 +118,8 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v5
+        with:
+          persist-credentials: false
       - name: Install dependencies
         uses: ./.github/actions/python-uv-setup
         with:

.gitignore

@@ -22,5 +22,10 @@ build/
 __pycache__/
 *.py[cod]
 *$py.class
-\n+# Local protocol folder (handled by generate_webrtc.sh)
+
+# Rust build artifacts
+target/
+getstream-rtc/getstream_rtc/*.so
+getstream-rtc/getstream_rtc/*.pyd
+# Local protocol folder (handled by generate_webrtc.sh)
 protocol/

AGENTS.md

@@ -1,9 +1,10 @@
 ## Project setup
 
 1. This project uses `uv`,  `pyproject.toml` and venv to manage dependencies
-2. Never use pip directly, use `uv add` to add dependencies and `uv sync --dev --all-packages` to install the dependency
+2. Never use pip directly, use `uv add` to add dependencies and `uv sync --dev --all-packages --all-extras` to install the dependency (without `--all-extras` the sync removes the packages of the optional dependency groups, for example `aiortc`, `av` and `numpy`)
 3. Do not change code generated python code, `./generate.sh` is the script responsible of rebuilding all API endpoints and API models
-4. **WebRTC Dependencies**: All dependencies related to WebRTC, audio, video processing (like `aiortc`, `numpy`, `torch`, `torchaudio`, `soundfile`, `scipy`, `deepgram-sdk`, `elevenlabs`, etc.) are organized under the `webrtc` optional dependencies group. Plugins that work with audio, video, or WebRTC functionality should depend on `getstream[webrtc]` instead of just `getstream`.
+4. **WebRTC Dependencies**: The dependencies of `getstream.video.rtc` (`getstream-rtc`, `aiortc`, `av`, `numpy`, and `twirp`, `protobuf` and `aiohttp` for the generated SFU code) are organized under the `webrtc` optional dependencies group. Plugins that work with audio, video, or WebRTC functionality should depend on `getstream[webrtc]` instead of just `getstream`, and declare every other package they import themselves.
+5. **Rust bindings**: `getstream-rtc` (directory `getstream-rtc/`) is a separate distribution and a member of the uv workspace. Its package `getstream_rtc` contains the PyO3 extension `getstream_rtc._bindings`, which maturin builds from `getstream-rtc/Cargo.toml` (sources in `getstream-rtc/rustsrc/`), and exports every class at its root. It wraps the Rust SDK (`getstream` crate from https://github.com/GetStream/stream-video-rust). It does not depend on `getstream`; stream-py code imports `getstream_rtc` as a separate package, and only the `webrtc` extra installs it. Its version is independent of the `getstream` version and is only in `getstream-rtc/pyproject.toml` (the crate has no version). `uv sync` compiles it when it installs the `webrtc` extra or all workspace packages; this needs the Rust toolchain pinned in `getstream-rtc/rust-toolchain.toml`, a C compiler, `cmake`, `pkg-config`, `libvpx`, and libclang for bindgen (macOS: `brew install libvpx cmake pkg-config`, libclang comes with Xcode; Debian/Ubuntu: `apt install libvpx-dev libclang-dev cmake pkg-config build-essential`). After Rust changes, run `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings` and `cargo test --lib` in `getstream-rtc/`; rustup selects the toolchain from the current directory, not from `--manifest-path`.
 
 ## Python testing
 
@@ -17,3 +18,92 @@
 8. tests that rely on file assets should always rely on files inside the `tests/assets/` folder, new files should be added there and existing ones used if possible. Do not use files larger than 256 kilobytes.
 9. do not use mocks or mock things in general unless you are asked to do that directly
 10. always run tests using `uv run pytest` from the root of the project, dont cd into folders to run tests
+
+
+## Rust and async expectations
+
+- Ensure [rust-skills](https://github.com/leonardomso/rust-skills) is available
+  before coding or review. Install or refresh it with
+  `npx add-skill leonardomso/rust-skills`, then apply the relevant rules rather
+  than loading unrelated categories.
+- Prefer typed errors and `Result`; avoid panics and `unwrap` in library code.
+- Do not circumvent borrow checker with .clone() for no reason.
+- Keep queues and buffers bounded. Make background-task cancellation and cleanup
+  deterministic, and do not hold synchronous locks across `.await` points.
+- Preserve compatibility with the Rust version declared in
+  `getstream-rtc/Cargo.toml`.
+
+## Rust wrapper: GIL, locks and deadlocks
+
+Python threads and tokio worker threads use SDK locks (`std::sync::Mutex`,
+tokio locks and channels) and the GIL. A deadlock needs a thread that holds an
+SDK lock and waits for the GIL while another thread holds the GIL and waits for
+that lock. Before you add or change a binding, read the SDK functions it calls
+and find the locks they take. Keep both halves impossible:
+
+- A Python thread must not hold the GIL while it waits for an SDK lock. Release
+  the GIL with `py.detach` in every synchronous method that reads or changes SDK
+  state (for example `Call.participants()`, `LocalAudioTrack.flush()`). A method
+  whose locks no other thread can hold yet needs no `py.detach` (`Client.call`
+  creates the call it locks).
+- A thread that holds an SDK lock must never wait for the GIL. Callbacks given
+  to the SDK (for example `on_track`) must not call `Python::attach` or drop
+  Python objects; they hand data over through a bounded channel.
+- `future_into_py` futures run on tokio without the GIL. Do not call
+  `Python::attach` in them; return the value and let pyo3-async-runtimes convert
+  it.
+- Never call Python from a `tracing` layer or a `log` logger. Records go
+  through the bounded queue in `getstream-rtc/rustsrc/logging.rs`. The Python
+  thread `getstream-logging` (`getstream-rtc/getstream_rtc/logging.py`) takes
+  them with `_next_logs()`, which waits without the GIL; Rust never calls
+  Python to log.
+- Python destructors drop the SDK objects they own with the GIL held. When you
+  update the SDK, check that these drops (`Call`, `RemoteTrack`,
+  `VideoFrameStream`, local tracks, tracks in the track queue) still take no
+  lock that another thread can hold.
+- While the GIL is released, do not read memory that Python owns (for example a
+  numpy buffer); copy it first.
+
+### Calling Python from Rust
+
+- Do not call Python code from Rust (`py.import(...)`, `call_method`, `call1`,
+  `getattr` of a Python object) unless the user agreed to it first. It makes the
+  code more complex and slower, so it is always a developer decision.
+- Return values that PyO3 converts by itself (`bool`, integers, `f64`, `String`,
+  `Vec`, `Option`, pyclasses) and let the Python caller convert them further,
+  for example a Unix time in seconds to a `datetime`.
+
+### Logging in the wrapper
+
+- Log with the `tracing` macros (`tracing::debug!` and the others). Do not use
+  `println!`, the `log` macros, or Python `logging` through `Python::attach`.
+- Use the default target. Records of the wrapper (`_bindings::…`) and of the SDK
+  (`getstream::…`) use the `level` of `configure_logging`; records of other
+  crates use `third_party_level`. A record reaches the configured logger's
+  child, for example `getstream._bindings.call` for
+  `getstream-rtc/rustsrc/call.rs` and `getstream.rtc.join` for the SDK's
+  `getstream::rtc::join`.
+- The message is an event name in the SDK style, `stream.<area>.<event>`. Put
+  values in fields, not in the message:
+  `tracing::debug!(dropped_samples = n, "stream.rtc.audio.pcm_queue_overflow")`.
+- Each field becomes an attribute of the Python `LogRecord`. Dots in field names
+  become `_`, a name that `LogRecord` already has gets the prefix `rust_`, and
+  `rust_target` holds the Rust target. Booleans, integers, floats and strings
+  keep their type; other values become strings (`?value` for `Debug`, `%value`
+  for `Display`). An error field includes its source chain.
+- Levels map to Python as ERROR 40, WARN 30, INFO 20, DEBUG 10, TRACE 5.
+- A log call never blocks and never takes the GIL, so it is safe while a lock or
+  the GIL is held. When the queue (1024 records) is full, records are dropped and
+  counted; a `stream.rust.log_records_dropped` warning with `dropped` comes with
+  the next batch that the Python thread takes, before its records.
+- Nothing is forwarded until `configure_logging` sets a logger. Disabled
+  records are filtered before their fields are formatted. `configure_logging`
+  returns at once. In a process forked after the logging thread started,
+  `configure_logging` with a logger raises `RuntimeError`.
+- Never log secrets or tokens.
+- To assert on records in tests, including DEBUG ones, use the `sdk_logs`
+  fixture in `getstream-rtc/tests/conftest.py`, and call
+  `getstream_rtc.logging._flush()` before you assert: it returns after the
+  records queued before the call are delivered. Do not call it on a thread
+  that a handler waits for, such as an event loop that a handler runs
+  coroutines on; there, use `await asyncio.to_thread(getstream_rtc.logging._flush)`.

Makefile

@@ -11,9 +11,8 @@ MARKER ?= not integration
 VIDEO_PATHS := \
 	getstream/video \
 	tests/rtc \
+	getstream-rtc/tests \
 	tests/test_audio_stream_track.py \
-	tests/test_connection_utils.py \
-	tests/test_signaling.py \
 	tests/test_video_examples.py \
 	tests/test_video_integration.py \
 	tests/test_video_openai.py \
@@ -66,7 +65,7 @@ test-video:
 
 ## Run all tests (non-video + video), excluding manual tests
 test-all:
-	uv run pytest -m "$(MARKER)" tests/ getstream/ $(MANUAL_IGNORE)
+	uv run pytest -m "$(MARKER)" tests/ getstream/ getstream-rtc/tests $(MANUAL_IGNORE)
 
 ## Run integration tests for both groups
 test-integration:
@@ -93,7 +92,7 @@ format:
 
 ## Run ty type checker
 typecheck:
-	uvx ty@0.0.24 check getstream/ $(TY_EXCLUDES)
+	uvx ty@0.0.24 check getstream/ --extra-search-path getstream-rtc $(TY_EXCLUDES)
 
 ## Run full check: lint + typecheck + non-video tests
 check: lint typecheck test