µStreamer

µStreamer is a high‑performance, lightweight HTTP server that streams MJPEG video directly from any V4L2 device to the network. Designed as a core component of PiKVM, it excels at delivering VGA/HDMI screencasts with maximum resolution and frame‑rate while remaining minimal in footprint. Unlike legacy tools such as mjpg-streamer, µStreamer implements multithreaded JPEG encoding, hardware acceleration on ARM platforms (e.g., Raspberry Pi), and graceful handling of device disconnects. It exposes a simple REST‑like HTTP interface for control, diagnostics, and optional file serving, making it ideal for embedding in larger automation stacks.

Key Features

• Multithreaded JPEG Encoding – Separate capture and encode threads keep CPU usage low while maintaining high FPS.
• Hardware Image Encoding – On supported Raspberry Pi models, the VideoCore IV encoder is leveraged for zero‑copy JPEG compression.
• DV‑Timings Support – Runtime resolution changes are detected via V4L2 DV timings, allowing a single instance to adapt to varying source signals.
• Frame‑Skipping – Optional --drop-same-frames reduces bandwidth for static sources (e.g., HDMI) by detecting identical frames with memcmp().
• Socket Activation & UNIX Domain Sockets – Systemd socket activation and local IPC provide low‑latency control paths.
• GPIO Signaling – libgpiod integration can toggle GPIO pins to signal stream state (e.g., live/standby).
• Built‑in HTTP Server – Serves static files and exposes a JSON API for camera controls (focus, exposure) and stream stats.

Technical Stack

• Language: C (C99), with optional OpenMP for multithreading.
• Libraries:
  • libv4l2 for device I/O and DV‑timings.
  • libjpeg-turbo or hardware JPEG encoder on Raspberry Pi.
  • libgpiod for GPIO signaling.
  • systemd socket activation APIs.
• Networking: POSIX sockets (TCP/UNIX) with non‑blocking I/O.
• Packaging: Debian/Ubuntu packages, Docker image available, source on GitHub.

Architecture

µStreamer follows a classic producer‑consumer pipeline:

1. Capture Thread reads frames from /dev/videoX using V4L2 VIDIOC_STREAMON.
2. Encoder Thread pulls frames from a lock‑free queue, performs JPEG compression (CPU or HW), and pushes the resulting buffer into a shared ring.
3. HTTP Thread serves the MJPEG stream by streaming JPEG frames over an HTTP multipart response; it also listens for control requests on a separate endpoint.

The design keeps the capture path fully asynchronous, ensuring that high‑resolution sources (e.g., 1920×1080 @ 60 fps) never stall the HTTP server. The optional frame‑drop logic runs in the encoder thread before encoding, saving bandwidth without affecting latency.

Deployment & Infrastructure

• Self‑Hosting: Runs as a native binary; requires root privileges only for V4L2 access and optional GPIO.
• Containerization: Dockerfile provided; the container mounts /dev/videoX and optionally GPIO device nodes. Systemd socket activation is not available in containers, but the HTTP port can be exposed directly.
• Scalability: A single µStreamer instance handles one camera. For multi‑camera deployments, orchestrate multiple instances behind a reverse proxy or use Kubernetes with DaemonSet to bind each pod to its local camera.

Integration & Extensibility

• API: JSON endpoints (/api/status, /api/control) expose camera parameters and stream statistics. Developers can poll or webhook‑trigger on state changes.
• Webhooks: Custom hooks (e.g., on disconnect) can be implemented via the HTTP API or by monitoring systemd socket activation events.
• Plugin System: While µStreamer currently ships with built‑in HTTP and JPEG plugins, the architecture allows swapping output modules (e.g., RTSP) with minimal code changes.
• Customization: Compile‑time flags enable or disable features (GPIO, frame‑drop), and runtime command‑line options adjust quality, resolution, and buffer sizes.

Developer Experience

• Documentation: Comprehensive README with feature matrix, command‑line options, and API reference. Inline comments in source code aid comprehension.
• Community: Active Discord channel for real‑time support; issue tracker accepts feature requests and bug reports.
• Licensing: MIT license encourages reuse in proprietary projects without copyleft constraints.

Use Cases

• Remote KVM: Deliver VGA/HDMI video to a browser for full‑screen control in data centers or lab environments.
• Home Surveillance: Low‑overhead MJPEG stream for quick monitoring via mobile browsers or VLC.
• IoT Edge Streaming: Run on Raspberry Pi to stream camera feeds to a cloud aggregator, leveraging hardware JPEG for battery‑powered devices.
• Testing & Benchmarking: Use the API to programmatically adjust camera settings and capture performance metrics for research.

Advantages Over Alternatives

• Performance: Multithreaded encoding and hardware acceleration keep CPU usage low while supporting 60 fps at 1080p.
• Robustness: Graceful handling of device disconnects and DV‑timings avoids stream stalls common in legacy tools.
• Bandwidth Efficiency: Frame‑skipping dramatically reduces traffic for static sources without impacting latency.
• Ease of Integration: RESTful API and socket activation