websockets_mode

WebSockets streaming mode: the service that pairs pixelflux capture with WebSocket clients.

Owns the data WebSocket plane for the websockets transport: per-client connection handling (auth/roles, input dispatch, settings), the per-display pixelflux video captures with their bounded per-client relays, the shared pcmflux Opus audio fan-out (with the all-clients Opus+RED gate), microphone forwarding, clipboard/cursor delivery, stats collection, and the display layout/reconfiguration engine shared conceptually with the WebRTC transport (parity between the two transports, and between X11 and Wayland, is a design requirement).

Threading model: one asyncio event loop runs everything control-plane. pixelflux/pcmflux deliver frames from their own native threads; those callbacks never touch asyncio state directly — they hand zero-copy items to the loop via call_soon_threadsafe. Per-client video delivery is bounded by _VideoRelay (drop-and-resync past a byte budget) and audio by a fixed queue, so one slow client can never back pressure the shared pipeline. Blocking native calls (capture start/stop, geometry reads) run on executor threads. The Wayland path is subprocess-free by design: compositor output management, DPI-as-output-scale, and cursor sizing all go through the in-process pixelflux handle, never through forked tools.

Wire framing: text frames carry the control verbs; binary frames are typed by their first byte — 0x01 Opus audio (pcmflux's native header, sent as-is), 0x03 JPEG and 0x04 video stripes from pixelflux, 0x02 client mic PCM, WS_OPCODE_WEBCAM a webcam frame for the virtual camera, 0x05 a gzip wrapped control text, and WS_OPCODE_PADDING padding toward a page that sent _pad,1, which drops it unread (PathProbe). A client that sends _gz,1 can inflate gzip: control text at or above WS_GZIP_MIN_BYTES then goes out as 0x05 frames (small, latency-critical messages such as input stay raw), and the server echoes the verb so the client gzips its own large sends, which the handler inflates back into text before dispatch. Video chunks carry a uint16 frame id that the display's owning client acknowledges (CLIENT_FRAME_ACK); the ack cadence sizes that display's backpressure window and the matched send stamps feed its smoothed RTT. An unchanged id is repeated as a heartbeat, so a client that has nothing new to ack is still told apart from one that has gone silent (_run_frame_backpressure_logic).