Skip to content

Redesign the README and docs homepage #235

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
MarshalX merged 1 commit into from
Oct 11, 2026
+342 −147
Merged

Redesign the README and docs homepage #235

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 94 additions & 4 deletions CHANGES.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,18 @@

## Version 0.0.1

**XX.XX.2026**
**11.10.2026**

**🔌 The whole WebRTC API is bound. Every interface, every method, every dictionary: all 154 binding issues of the [tracker](https://github.com/users/MarshalX/projects/1/views/1) are done, and the API goes beyond them**

**🎞 Media processing that not every browser ships yet: `MediaStreamTrackProcessor`, `VideoTrackGenerator` and `MediaStreamTrackGenerator`, with the `VideoFrame` and `AudioData` of WebCodecs**

**🔐 WebRTC Encoded Transform: the encoded frames of senders and receivers in Python with `RTCRtpScriptTransform`, and end-to-end encryption with SFrame**

**🎥 H.264 without bundling it: VideoToolbox on macOS, offered by default, and Cisco's OpenH264 binary on request elsewhere**

**🚀 Field trials and WARP: DTLS 1.3, SNAP and SPED cut round trips off connection setup**

**⚡ libwebrtc M152, pre-built wheels for Linux (x86_64 and aarch64), macOS and Windows, CPython 3.9 – 3.15, free-threaded 3.14t and 3.15t too**

**🧪 The public API follows the WebIDL of the specifications and runs the original web-platform-tests**
Expand Down Expand Up @@ -38,10 +42,17 @@ In numbers: 229 public classes, 50 enums with the string values of the specifica
* Align WebIDL dictionaries with the spec as typed models by [@MarshalX](https://github.com/MarshalX) in [#212](https://github.com/MarshalX/python-webrtc/pull/212)
* Align the public API with the WPT WebIDL by [@MarshalX](https://github.com/MarshalX) in [#214](https://github.com/MarshalX/python-webrtc/pull/214)
* Type event handlers per event, add listener management methods by [@MarshalX](https://github.com/MarshalX) in [#215](https://github.com/MarshalX/python-webrtc/pull/215)
* Add H.264 through Cisco's OpenH264 binary, downloaded on request by [@MarshalX](https://github.com/MarshalX) in [#218](https://github.com/MarshalX/python-webrtc/pull/218)
* Add H.264 on macOS through VideoToolbox, offered by default by [@MarshalX](https://github.com/MarshalX) in [#219](https://github.com/MarshalX/python-webrtc/pull/219)
* Encode H.264 with our own VideoToolbox session: AutoLevel, no rate freeze, High for Chrome by [@MarshalX](https://github.com/MarshalX) in [#233](https://github.com/MarshalX/python-webrtc/pull/233)
* Match browsers on SDP munging, connection states, `setParameters` and close by [@MarshalX](https://github.com/MarshalX) in [#227](https://github.com/MarshalX/python-webrtc/pull/227)
* Replace `to_async` with `call_native`, drop its timeout by [@MarshalX](https://github.com/MarshalX) in [#206](https://github.com/MarshalX/python-webrtc/pull/206)
* Add the OpenAI GPT-Live voice chat example by [@MarshalX](https://github.com/MarshalX) in [#198](https://github.com/MarshalX/python-webrtc/pull/198)
* Add field trials, connect the GPT-Live example with WARP, skip loopback candidates by [@MarshalX](https://github.com/MarshalX)
* Add field trials, connect the GPT-Live example with WARP, skip loopback candidates by [@MarshalX](https://github.com/MarshalX) in [#225](https://github.com/MarshalX/python-webrtc/pull/225)
* Add the Janus streaming example by [@MarshalX](https://github.com/MarshalX) in [#205](https://github.com/MarshalX/python-webrtc/pull/205)
* Play Janus streams in stereo by munging the Opus answer by [@MarshalX](https://github.com/MarshalX) in [#234](https://github.com/MarshalX/python-webrtc/pull/234)
* Rework the docs website with guides, examples and the API reference by [@MarshalX](https://github.com/MarshalX) in [#217](https://github.com/MarshalX/python-webrtc/pull/217)
* Rewrite the API docs with MDN links by [@MarshalX](https://github.com/MarshalX) in [#221](https://github.com/MarshalX/python-webrtc/pull/221)
* Run original web-platform-tests through a PythonMonkey shim by [@MarshalX](https://github.com/MarshalX) in [#193](https://github.com/MarshalX/python-webrtc/pull/193)
* Sync tests with web-platform-tests by [@MarshalX](https://github.com/MarshalX) in [#192](https://github.com/MarshalX/python-webrtc/pull/192)
* Compare the public API with the WPT WebIDL by [@MarshalX](https://github.com/MarshalX) in [#211](https://github.com/MarshalX/python-webrtc/pull/211)
Expand All @@ -50,12 +61,91 @@ In numbers: 229 public classes, 50 enums with the string values of the specifica
* Enable all ruff rules, fix findings by [@MarshalX](https://github.com/MarshalX) in [#210](https://github.com/MarshalX/python-webrtc/pull/210)
* Type check with Pyrefly at full strictness, fix findings by [@MarshalX](https://github.com/MarshalX) in [#213](https://github.com/MarshalX/python-webrtc/pull/213)
* Run tests on GitHub Actions by [@MarshalX](https://github.com/MarshalX) in [#187](https://github.com/MarshalX/python-webrtc/pull/187)
* Build on Ubuntu 22.04 in CI by [@MarshalX](https://github.com/MarshalX) in [#189](https://github.com/MarshalX/python-webrtc/pull/189)
* Make CI wheel builds and PyPI publish safe to retry by [@MarshalX](https://github.com/MarshalX) in [#226](https://github.com/MarshalX/python-webrtc/pull/226)
* Retry and cache CI downloads, build the sdist in each wheel job by [@MarshalX](https://github.com/MarshalX) in [#230](https://github.com/MarshalX/python-webrtc/pull/230)
* Run isolated tests as functions instead of code strings by [@MarshalX](https://github.com/MarshalX) in [#228](https://github.com/MarshalX/python-webrtc/pull/228)
* Add an unattended bug hunt with stacks, crash triage and C++/Python coverage by [@MarshalX](https://github.com/MarshalX) in [#231](https://github.com/MarshalX/python-webrtc/pull/231)
* Update the licence holder and headers, rebuild third-party licences for M152 by [@MarshalX](https://github.com/MarshalX) in [#220](https://github.com/MarshalX/python-webrtc/pull/220)
* Fix wrapper ownership: shared_ptr lifetimes, no factory leaks or dangling observers by [@MarshalX](https://github.com/MarshalX) in [#194](https://github.com/MarshalX/python-webrtc/pull/194)
* Fix the GC deadlock by releasing wrappers off libwebrtc threads by [@MarshalX](https://github.com/MarshalX) in [#199](https://github.com/MarshalX/python-webrtc/pull/199)
* Fix deadlocks, leaks and crashes found by sanitizers and chaos tests by [@MarshalX](https://github.com/MarshalX) in [#200](https://github.com/MarshalX/python-webrtc/pull/200)
* Fix `set_parameters` hanging when libwebrtc drops the callback by [@MarshalX](https://github.com/MarshalX) in [#208](https://github.com/MarshalX/python-webrtc/pull/208)
* Fix sender and receiver leaks by releasing handlers of ended tracks by [@MarshalX](https://github.com/MarshalX) in [#216](https://github.com/MarshalX/python-webrtc/pull/216)
* Fix spec bugs found by a stricter WPT by [@MarshalX](https://github.com/MarshalX) in [#222](https://github.com/MarshalX/python-webrtc/pull/222)
* Fix callback crashes, exit hangs and thread churn in the native layer by [@MarshalX](https://github.com/MarshalX) in [#223](https://github.com/MarshalX/python-webrtc/pull/223)
* Fix stream, track and event-loop bugs, and a wrapper deadlock by [@MarshalX](https://github.com/MarshalX) in [#224](https://github.com/MarshalX/python-webrtc/pull/224)
* Release tasks stranded by a closed test loop by [@MarshalX](https://github.com/MarshalX) in [#229](https://github.com/MarshalX/python-webrtc/pull/229)
* Rebuild object lifetime: unreferenced connections, channels and live tracks stay alive while they have handlers or pending work, native threads never run Python, wrappers take no attributes by [@MarshalX](https://github.com/MarshalX) in [#232](https://github.com/MarshalX/python-webrtc/pull/232)
* Fire `ended` on remote tracks when a connection closes, keep a failed `RTCIceTransport` for an ICE restart by [@MarshalX](https://github.com/MarshalX) in [#232](https://github.com/MarshalX/python-webrtc/pull/232)
* Fix a cancelled operation of a connection breaking the operations queued before and after it by [@MarshalX](https://github.com/MarshalX)
* Fix the docs build with the current `sphinx-favicon` by [@MarshalX](https://github.com/MarshalX), closes [#186](https://github.com/MarshalX/python-webrtc/issues/186)
* Fix a cancelled operation of a connection breaking the operations queued before and after it by [@MarshalX](https://github.com/MarshalX) in [#217](https://github.com/MarshalX/python-webrtc/pull/217)
* Fix the docs build with the current `sphinx-favicon` by [@MarshalX](https://github.com/MarshalX) in [#217](https://github.com/MarshalX/python-webrtc/pull/217), closes [#186](https://github.com/MarshalX/python-webrtc/issues/186)

## Version 0.0.0.dev9

**03.03.2022**

* Add `RTCDtlsTransport` and `RTCPeerConnection.add_transceiver`, with `RtpEncodingParameters`, `RtpTransceiverInit` and `MediaType`
* `transport` of `RTCRtpSender` and `RTCRtpReceiver`
* `MediaStreamTrack.kind` is a `MediaType`

## Version 0.0.0.dev8

**02.03.2022**

* Add `RTCRtpTransceiver`, `RTCRtpReceiver` and `RTCIceTransport`
* `get_transceivers`, `get_senders` and `get_receivers` of `RTCPeerConnection`
* Unified Plan is the default SDP semantics

## Version 0.0.0.dev7

**26.02.2022**

* Fix a segfault of the `MediaStream` from `get_user_media`
* Compare Python wrappers by their native objects
* Add the test suite with pytest

## Version 0.0.0.dev6

**10.02.2022**

* Bind `RTCError`, `SdpParseError` and the common exceptions; failed async calls raise them
* Fix a segfault in `RTCPeerConnection.close`
* Add the security policy

## Version 0.0.0.dev5

**09.02.2022**

* Fix a segfault of `RTCSessionDescription` (double destruction)
* Publish the sdist, include third-party licences in the package

## Version 0.0.0.dev4

**06.02.2022**

* Keep one Python wrapper per native object, which fixes many segfaults and bus errors
* Fix `MediaStream` pointers and the creation of `RTCRtpSender`
* Docs: favicons, OpenGraph, keyboard navigation and mobile layout

## Version 0.0.0.dev3

**03.02.2022**

* Docs on Read the Docs, a README with the logo

## Version 0.0.0.dev2

**03.02.2022**

* `RTCPeerConnection` with `create_offer`, `create_answer`, `set_local_description`, `set_remote_description`, `add_track` and `close`
* `MediaStream`, `MediaStreamTrack` and `get_user_media`
* `RTCRtpSender`, and `RTCAudioSource` to send PCM from Python
* The pure Python `webrtc` module over the native `wrtc`, with docs
* Wheels for Linux, macOS (Intel and Apple Silicon) and Windows

## Version 0.0.0.dev1

**03.01.2022**

* The first upload: the package skeleton
46 changes: 46 additions & 0 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,46 @@
# Contributing

Contributions of any size are welcome. For bugs and features, [open an issue](https://github.com/MarshalX/python-webrtc/issues/new);
for questions, [start a discussion](https://github.com/MarshalX/python-webrtc/discussions/new).

## Development

Requires [uv](https://docs.astral.sh/uv/).

``` bash
make dev # editable install into .venv, C++ is rebuilt on import when changed
make test # run the test suite
make lint # ruff
make stub # regenerate type stubs of the native module
make wheels # build wheels for the current platform the same way CI does
```

## Building from sources (sdist)

- CMake 3.26 or higher
- A C++20 compiler: Clang on Linux (libwebrtc there is built against Chromium's libc++), Apple Clang on macOS, MSVC on Windows
- ~150 MB of free disk space

Nothing else has to be installed or configured manually: a prebuilt static libwebrtc for the target platform
(from [libwebrtc-bin](https://github.com/crow-misia/libwebrtc-bin)) is downloaded once, verified and unpacked
into a shared cache (`~/.cache/python-webrtc`, `%LOCALAPPDATA%\python-webrtc` on Windows or `$WRTC_CACHE_DIR`).
Only the headers in use are extracted and debug info is stripped, so it takes ~60 MB per platform.
Pass `-Ccmake.define.LIBWEBRTC_ROOT=/path/to/libwebrtc` to use your own libwebrtc build instead.

## Releasing

1. Bump `version` in `pyproject.toml` and run `uv lock`.
2. Push a `v<version>` tag. CI builds the sdist and wheels for every platform and publishes them to PyPI.

Publishing uses [trusted publishing](https://docs.pypi.org/trusted-publishers/): the PyPI project needs a
trusted publisher for this repository's `ci.yml` workflow, and the repository a `pypi` environment. No tokens needed.

## Updating WebRTC

The libwebrtc version and archive hashes are pinned in `cmake/libwebrtc.cmake`:

1. Set `LIBWEBRTC_VERSION` to a [libwebrtc-bin release](https://github.com/crow-misia/libwebrtc-bin/releases)
and update the `LIBWEBRTC_SHA256_*` values (the release page lists a SHA256 digest per asset).
2. Refresh the Linux libc++ pins as described in [`cmake/libcxx/README.md`](cmake/libcxx/README.md).
3. Build and run the tests. On Linux, check whether `cmake/libwebrtc_linux_fixups.cpp` is still needed:
remove it and see whether the module imports (it is linked with `-z now`, so missing symbols fail on import).
Loading
Loading