$ show pikvm/ustreamer
uStreamer is a lightweight, high-performance MJPEG-HTTP video streaming server designed primarily for PiKVM (IP-KVM over HDMI). It captures video from V4L2 devices (USB cameras, HDMI capture cards) and streams it as MJPEG over HTTP with sub-second latency, while also supporting H.264 streaming via WebRTC through a Janus plugin. The system is a single, multithreaded C daemon with pluggable JPEG encoders (CPU via libjpeg-turbo, hardware passthrough, and V4L2 M2M acceleration) and includes a worker pool for parallel encoding. It integrates tightly with Linux multimedia subsystems (V4L2, ALSA, DRM) and provides additional features like audio capture/playback with Opus encoding, GPIO control, systemd socket activation, and shared memory IPC for zero-copy frame access by other processes (e.g., Janus, Python bindings, dump tool). The codebase is production-grade, extensively tested in the PiKVM ecosystem, and packaged for multiple Linux distributions and container environments. The architecture separates concerns into clean modules: capture (V4L2 buffer management with DMA export), encoding (abstraction over CPU/HW/M2M), HTTP server (libevent-based, serving MJPEG streams, snapshots, and static assets), and a generic worker thread pool for parallel JPEG compression. Shared memory sinks (memsink) enable efficient frame transfer to external consumers like the Janus WebRTC plugin or the standalone dump utility. The project also includes a full-featured Janus plugin for H.264/Opus streaming with NTP timestamping and PLI handling, a Python C extension for shared memory client access, and a separate V4 passthrough tool for the PiKVM V4 Plus hardware. Build configuration uses Makefiles with numerous feature flags (WITH_GPIO, WITH_JANUS, WITH_SYSTEMD, etc.), permitting a modular build. Overall, uStreamer exemplifies careful engineering of real-time video pipelines on embedded Linux, with a focus on minimal latency, hardware offload, and robust IPC.
The LLM identified 5 files worth highlighting for reuse:
Implements a versioned shared memory sink protocol (memsink) for zero-copy frame transfer between processes. Provides a server (publishes frames to a file-backed shared memory region with metadata and lock-based synchronization) and a client (reads frames by ID or sequentially). The design includes a magic number, versioning, and support for JPEG, raw, and H.264 formats. Reusable as a general purpose low-latency IPC mechanism for any application needing to share large binary frames between producers and consumers.
A lock-free, single-producer single-consumer ring buffer for passing frame pointers or data between threads. Uses atomic operations and a power-of-two capacity without dynamic allocation. The implementation is minimal, correct, and well-documented, making it easily extractable for any producer-consumer pattern in C or embedded systems.
Generic thread worker pool dispatcher that maintains a pool of pthreads and a job queue. Jobs are function pointer + argument pairs, executed in FIFO order. Used for parallel JPEG encoding in uStreamer but completely decoupled from video logic; can be extracted for any CPU-bound parallel work in C porjects.
A lightweight header-only utility to calculate and report frames per second (FPS) with metadata (resolution, online state). Uses a simple sliding window of timestamps. Reusable in any video or sensor monitoring application that needs a compact FPS metric.
Clean implementation of base64 encode and decode functions for arbitrary binary data. Handles line breaks, returns allocated strings. Self-contained with no dependencies beyond standard C. Useful in any project requiring base64 conversion without pulling in large libraries.