Python binding

Status: ✅ verified — the mediaway package in mediaway/ is real (pure-Python ctypes over the C ABI) and the examples in examples/ run against the native libraries: mux/demux roundtrip, real H.264 encode, real camera + mic capture. This README is the DX contract the package implements: context managers, exceptions, Rational-second timestamps, bytes for buffers.

See the C binding README for the underlying C ABI contract (status enums, ownership, thread confinement) — the Python package translates that ABI into idiomatic Python.

The native library behind that ABI is 100% Rust — no libav*/GPL codec dependencies, memory-safe by construction on the native side. This package is a thin ctypes wrapper, not a reimplementation.

Platforms: Windows x64 is the fully hardware-verified platform (device/pipeline capture and encode). Linux x64 is container-verified (mux/demux); device/pipeline capability on Linux is untested here.

What Mediaway is (the capabilities)

A streaming-first media stack. The C ABI currently covers three capabilities (full detail in ../c/README.md and docs/spec/c-ffi.md):

1. Container — mux + demux, all 8 mediaway-container formats: MP4/WebM share Muxer/Demuxer (format=ContainerFormat.MP4/.WEBM, typestated Open→Live via begin(), never touches files — the caller owns byte I/O). Ogg/ADTS/FLV/MPEG-TS/MP3 get dedicated classes (OggMuxer/OggDemuxer, AdtsMuxer/AdtsDemuxer, FlvMuxer/FlvDemuxer, TsMuxer/TsDemuxer, Mp3Muxer/Mp3Demuxer) reflecting each format's own C ABI shape — see each module's (_container_*.py) top comment. WAV is mux-only (WavMuxer, consuming finish()); demux is the one-shot wav_parse() function, not a class at all. These 6 formats use RawPacket (ABI-native integer pts/dts, not Rational seconds) since none of them have MP4's per-track time base to convert against. Fully real, all formats run-verified. Replay ring + MP4 payload placements (ABI 8, adr/container/0009): ReplayRing(anchor_stream_id, anchor_time_base, window) keeps the last N seconds of Packets and clip_last(span) cuts a ReplayClip at a keyframe, in decode order, with timestamps rebased to zero — up to one keyframe interval earlier than asked, never later. A clip is an owned snapshot: it stays valid after further push calls and after the ring is closed, and entry.payload is a copy. Write it by pushing entry.to_packet() through a Muxer (there is deliberately no one-shot "save clip" call; track ids must match the ring's stream ids). payload="stored" rings hold only StoredPayload(file, offset, length) for a caller that already writes packets to a file, fed from Muxer.create_with_placements() → LiveMuxer.poll_placements(). Limit: the C ABI has no video-packet source — EncodeSession muxes its encoder's packets internally — so feed the ring packets from a Demuxer, from AudioEncoder, or from an encoder you drive yourself. Ring failures are UnknownStreamError and OutOfOrderPacketError (the packet was not added; drop it and carry on).
2. Pipeline — auto video encode → fMP4, plus decode: one call picks the best available OS/GPU encoder for a config, wires it into an internal MP4 muxer; finish() returns complete MP4 bytes. The audio encoder is separate (ABI v2, adr/0003): AudioEncoder.open() streams AAC (or Opus) packets for the caller's own muxer. Decode is the mirror shape (adr/0004, adr/pipeline/0006): DecodeSession wraps the best available video decoder (CPU output only; Windows/WMF today), AudioDecodeSession decodes Opus (software, identical on every host) or AAC (codec=Codec.AAC, extra_data=<AudioSpecificConfig>; adr/pipeline/0007) — both single-step handles (the handle IS the decoder), NO_BACKEND raises DecoderUnavailableError gracefully. AAC is the OS's own decoder (Media Foundation on Windows, AudioToolbox on Apple; unavailable elsewhere), so its samples can differ between hosts; the AudioSpecificConfig is required and only raw AAC is accepted (de-header ADTS first). The Apple arm is compile-checked but has not been run. EncodeSession.poll_bytes() streams the fMP4 out during a long recording (memory bounded by the poll cadence); finish() then returns only the unpolled tail. encoder_support(codec, width, height) / decoder_support(codec) probe what works on this machine before opening a session — both are costly (they open throwaway sessions), and encoder support depends on resolution.
3. Device — capture: camera (CPU frames), microphone/loopback (PCM), hotplug. AudioCapture.open(source="process_loopback", process_id=…, include_target_process_tree=…) records that process tree, or with False everything the desktop renders except it — Windows has no "target process alone" mode. Screen capture is real (GPU-backed, DXGI Desktop Duplication) via the GpuDevice factory (adr/0007-gpu-device-factory.md) — VideoCapture.open(source= "screen") builds one internally, or share your own with an encoder. There is no CPU pixel readback path for Screen frames; real pixels only ever move through EncodeSession.write_frame_from_desktop_capture (adr/pipeline/0005). Window capture is real on Windows (WGC, adr/device/0005): VideoCapture.open(source= "window", window=<HWND>, ...) takes the same GpuDevice, plus cursor="included", border="hidden" (read the outcome from capture.border_hidden), dimensions="even_cropped" and region=(x, y, w, h). A region away from the window's origin is one GPU copy per frame — not Zero-Copy — and a window that shrinks below it raises RegionOutOfBoundsError. DXGI Screen capture cannot draw the pointer or crop, so cursor="included" / region= on source="screen" raise CaptureUnsupportedError. Other platforms raise CaptureUnsupportedError for Window.

The real ABI beneath (what the wrapper wraps)

DLLs: mediaway_ffi, mediaway_ffi, mediaway_ffi (built for x86_64-pc-windows-gnu, see the C README's build recipe). Headers crates/mediaway-*-ffi/include/mediaway/{container,pipeline,device}.h are the authoritative layout.

• Opaque handles, all thread-confined (no concurrent calls on one handle).
• Every status is a per-crate enum, OK = 0; a caught Rust panic poisons the handle. NO_BACKEND / UNSUPPORTED are expected outcomes, not errors.
• Ownership: borrowed inputs valid for the call only (the wrapper must copy in); owned outputs (poll_bytes buffers, demuxed packets/stream info, encode finish buffers, polled device frames) must be released via the matching _free — the wrapper's job is to make this automatic (context managers / finalizers).
• Handle-consumption traps the wrapper MUST hide: mediaway_encode_session_open consumes the encoder unconditionally; mediaway_encode_session_finish consumes the session. Python can hide this by folding open into EncodeSession construction and making finish terminal.

Ideal API — the DX contract

A single mediaway package, pure-Python ctypes glue + idiomatic wrappers. snake_case everywhere (Python convention beats the C names): Rational, VideoStreamInfo, AudioStreamInfo, Packet, Codec (enum), VideoFrame; classes Muxer, Demuxer, EncodeSession, AutoVideoEncoder, VideoCapture, AudioCapture, GpuDevice.

• Context managers: with Muxer() as m:, with Demuxer() as d:, with EncodeSession(...) as s: — __exit__ closes the underlying handle (and, for capture sessions, joins the backend worker thread). This is the primary lifecycle shape; explicit .close() exists for non-with users.
• Exceptions: a MediawayError base carrying the raw status code, with subclasses for the expected outcomes (EncoderUnavailableError, DeviceUnavailableError, CaptureUnsupportedError) so examples can catch-and-continue rather than crash on missing hardware. No status-code checking in example bodies.
• Typestate as two classes (mirrors C++): Muxer (Open: add_video_track / add_audio_track) → .begin() returns LiveMuxer (push_packet / flush / poll_bytes). Calling track registration on a LiveMuxer is impossible, matching the ABI's INVALID_STATE.
• bytes for byte buffers: poll_bytes() -> bytes; push_bytes(bytes); packet.payload -> bytes; frame.data -> bytes (NV12/BGRA8). The wrapper copies out of borrowed/owned native buffers — no memoryview leaking into the API.
• Rational(num, den) as a small dataclass(frozen=True); info structs as dataclasses.
• EncodeSession(encoder) takes ownership of the encoder object; finish() -> bytes is terminal (no close() after it).

Example scenarios

examples/ mirrors the Rust examples/ layout — sector subfolders, one file per scenario (English comments only; each file's header comment states real vs. aspirational):

Rules

• English comments only.
• Map existing Rust surfaces; do not invent capabilities the Rust side doesn't have.
• Wrap the ABI fully: no ctypes types or raw handles visible in examples.
• Not part of the Cargo workspace; durable API changes require an ADR (ADR-0004).