Module recorder 

Built-in MP4 recorder: independent capture-to-file with Python/env/REST control. Built-in MP4 recorder: an independent pipeline that captures the desktop to a ready-to-play fragmented MP4 without needing any connected client.

One implementation serves three control surfaces — the Python module functions (start_recording / stop_recording / recording_status), the PIXELFLUX_RECORD* environment variables (record from process start), and the record_start / record_stop / record_status endpoints on the Computer Use HTTP server — so their behavior cannot drift.

The recorder is a consumer of the existing capture machinery, never a hook inside an encoder:

• X11: it always runs its own crate::x11::run_capture instance against the root window (a second capture of the same root is independent of any streaming session), with the encoded frames delivered straight into the recorder’s queue.
• Wayland: the compositor lives in this process and allows one capture per output, so the recorder attaches at the delivery layer. When the output is already being captured for a streaming client it taps that stream (and paces recovery keyframes through the standard RequestIdr command); when the output is idle it starts its own capture with no Python callback and taps the identical delivery point.

Frames cross into the recorder through one bounded queue, mirroring the Unix-socket sink’s isolation contract: the delivery thread only clones an Arc and try_sends, an overflowing queue drops frames (never blocks the pipeline), and all muxing happens on the recorder’s own writer thread. Timestamps are wall-clock, so the damage-driven, variable-rate frame flow lands at its true times in the MP4.

Modules

mp4

Pure-Rust fragmented-MP4 (fMP4) muxer for the built-in recorder.

Structs

RecordOptions

Resolved recording parameters. Environment variables provide the defaults; explicit Python/REST arguments override them.

RecordingStatus

Point-in-time view of the recorder, identical across the Python, env and REST surfaces.

Enums

PreferredBackend

Which capture system feeds the recording.

Functions

autostart_from_env

PIXELFLUX_RECORD=<path>: record from process start. X11 (via DISPLAY) starts immediately; otherwise a background thread waits for the in-process Wayland compositor to come up and then starts. Retries transient failures until the deadline.

finalize_on_exit

Finalize any active recording at interpreter shutdown so the MP4’s last buffered sample is flushed. Best-effort; the fragmented layout keeps even an unflushed file playable.

start

Start a recording. Exactly one may be active per process; returns the initial status.

status

The current status: the live recording when one is active, otherwise the last finished one; None when the process has never recorded.

status_to_json

Serialize a status into the JSON shape shared by the REST endpoints.

stop

Stop the active recording, finalize the MP4, and return the final status. Errors when no recording is active or when nothing recordable was ever received.