Skip to content

feat(examples): stream WebM via media tracks or intact byte streams - #839

Draft
AmitMY wants to merge 5 commits into
livekit:mainfrom
AmitMY:codex/python-webm-streaming
Draft

AmitMY wants to merge 5 commits into
livekit:mainfrom
AmitMY:codex/python-webm-streaming

Conversation

@AmitMY

@AmitMY AmitMY commented Sep 30, 2026 •

Copy link
Copy Markdown

Depends on #838 for pre-encoded media-track publishing. Incremental diff. Both upstream PRs target main because GitHub cannot use a fork's parent branch as an upstream PR base.

Add two examples for streaming WebM through LiveKit:

  • Intact WebM, including transparency: forward file or HTTP response chunks through the existing byte-stream API with video/webm metadata. The original container, timestamps, color, and alpha data remain byte-for-byte unchanged. There is no demuxing, decoding, re-encoding, or custom media format. This example uses existing APIs and does not itself depend on feat(rtc): expose pre-encoded video publishing in Python #838.
  • Opaque video as a media track: incrementally demux VP8/VP9 WebM into feat(rtc): expose pre-encoded video publishing in Python #838's pre-encoded source, preserve compressed video bytes, and pace by presentation timestamps. Reject alpha and BlockAdditional instead of silently discarding them. Retain the starting keyframe through native encoder initialization and keep the publication alive at EOF until cancellation.

A standard VP9 RTP media track transports codec frames, not WebM container elements. Preserving the complete WebM container therefore uses LiveKit's existing byte transport. The byte-stream example requires a prepared recipient and forwards chunks incrementally with awaited writes. Read failure or cancellation closes the writer with an error reason. Reliable delivery can increase latency under packet loss, and late joiners need a new stream from a suitable initialization segment/keyframe.

Client playback is deferred. A future handler could feed compatible WebM into native streaming playback, but browser/MSE alpha support, mobile support, buffering, and latency have not been validated. This PR does not claim that an ordinary LiveKit video-track attachment can play a WebM byte stream.

Validation:

  • All 27 targeted tests pass against a local LiveKit 1.13.7 server using Python FFI 0.12.80 and PyAV 16.1.
  • The native byte-stream test receives data before the sender produces the rest, then verifies exact equality of the complete WebM and all 12 packets' alpha side data.
  • Tests also cover file and HTTP byte forwarding before EOF, failure/cancellation closure, media-track compressed bytes/timestamps, pipe/HTTP demux before EOF, encoder startup, and cleanup.
  • Ruff and the full offline test suite pass. CI runs the optional PyAV examples on supported Python versions; the SDK remains compatible with Python 3.9.

@AmitMY AmitMY changed the title feat(examples): stream WebM and prototype single-track alpha transport feat(examples): stream WebM via media tracks or intact byte streams Sep 30, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant