videostream

Safe Rust bindings for the VideoStream Library - zero-copy video frame management and distribution for embedded Linux.

Overview

VideoStream provides inter-process video frame sharing with zero-copy transfers, making it ideal for embedded vision applications that need to distribute camera frames to multiple consumers efficiently.

Key Features

Zero-Copy Frame Sharing - Uses Linux DmaBuf and POSIX shared memory
Multi-Consumer Support - One producer, multiple concurrent consumers
Thread-Safe - Safe concurrent access to frame pools
Reference Counting - Automatic memory management
Hardware Acceleration - V4L2 camera capture and Hantro VPU encoding
GStreamer Integration - Pipeline-based video processing

Use Cases

Multi-Process Vision Pipelines - Share camera frames between detection, tracking, and display
Edge AI Applications - Distribute frames to multiple inference engines
Video Recording + Analysis - Simultaneously record and analyze camera streams
Low-Latency Streaming - Hardware-accelerated encoding with minimal overhead

Platform Support

NXP i.MX8M Plus - Full hardware acceleration (G2D, VPU, DmaBuf)
Generic ARM64/ARMv7 - Software fallback with shared memory
x86_64 - Development and testing support

Requirements

Runtime Dependencies

The VideoStream C library must be installed:

# Ubuntu/Debian
sudo apt-get install libvideostream1

# Or build from source
git clone https://github.com/EdgeFirstAI/videostream
cd videostream
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)
sudo cmake --install build

Build Dependencies

# Ubuntu/Debian
sudo apt-get install -y \
    build-essential \
    cmake \
    pkg-config \
    libgstreamer1.0-dev \
    libgstreamer-plugins-base1.0-dev

Quick Start

Add to your Cargo.toml:

[dependencies]
videostream = "1.5"

Host (Frame Producer)

use videostream::{Host, PixelFormat};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Create a host to share 1920x1080 RGB frames
    let mut host = Host::new(
        "/tmp/videostream.sock",
        1920,
        1080,
        PixelFormat::RGBX,
    )?;

    // Simulate frame production
    loop {
        // Get writable access to next frame buffer
        let mut frame = host.get_write_buffer()?;
        
        // Write frame data (e.g., from camera)
        let data = frame.data_mut();
        // ... fill data ...
        
        // Publish frame to all connected clients
        host.publish_frame(frame)?;
        
        std::thread::sleep(std::time::Duration::from_millis(33)); // ~30 fps
    }
}

Client (Frame Consumer)

use videostream::Client;
use std::time::Duration;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Connect to the host
    let mut client = Client::connect("/tmp/videostream.sock")?;

    loop {
        // Wait for next frame (with timeout)
        match client.wait_for_frame(Duration::from_secs(1))? {
            Some(frame) => {
                // Access frame data (zero-copy)
                let data = frame.data();
                let (width, height) = frame.dimensions();
                
                println!("Received {}x{} frame ({} bytes)", 
                         width, height, data.len());
                
                // Process frame...
            }
            None => {
                println!("No frame received (timeout)");
            }
        }
    }
}

Architecture

┌─────────────┐
│    Host     │  Frame Producer (1)
│  (Producer) │  - Allocates frame pool
└──────┬──────┘  - Publishes frames via IPC
       │
       │ UNIX Socket + DmaBuf FDs
       │
       ├─────────┬─────────┬─────────┐
       │         │         │         │
   ┌───▼───┐ ┌──▼────┐ ┌──▼────┐ ┌──▼────┐
   │Client │ │Client │ │Client │ │Client │  Frame Consumers (N)
   │   #1  │ │   #2  │ │   #3  │ │  ...  │  - Zero-copy access
   └───────┘ └───────┘ └───────┘ └───────┘  - Thread-safe

Performance

Benchmarks on NXP i.MX8M Plus (1080p@30fps):

Frame Latency: <3ms (DmaBuf), <10ms (shared memory)
CPU Overhead: <2% per client (frame distribution)
Memory: ~100KB per client (no frame copies)
Throughput: 60fps sustained with 3 concurrent clients

Safety

This crate provides safe wrappers around the unsafe FFI bindings in videostream-sys:

✅ Memory safety through RAII and lifetimes
✅ Thread safety with interior mutability patterns
✅ Null pointer checks and error handling
✅ Automatic resource cleanup (Drop implementations)

Examples

See the examples directory for complete applications:

host_basic.rs - Simple frame producer
client_basic.rs - Simple frame consumer
camera_capture.rs - V4L2 camera integration
multi_client.rs - Multiple consumers

Documentation

Contributing

Contributions are welcome! Please see CONTRIBUTING.md.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.

videostream 2.0.0