videostream 1.5.5

Safe Rust bindings for VideoStream Library - zero-copy video frame management and distribution
Documentation

VideoStream Library for Rust

Safe Rust bindings for the VideoStream Library, providing zero-copy video frame management and distribution across processes and containers on embedded Linux.

The VideoStream Library enables efficient frame sharing through DMA buffers or shared-memory with signaling over UNIX Domain Sockets, optimized for edge AI and computer vision applications on resource-constrained embedded devices like NXP i.MX8M Plus.

Architecture

VideoStream uses a Host/Client pattern for inter-process communication:

  • Host: Publishes video frames to a UNIX socket
  • Clients: Subscribe to frames by connecting to the socket
  • Frames: Zero-copy shared memory (DmaBuf or POSIX shm) with metadata

Quick Start

Publishing Frames (Host)

use videostream::{host::Host, frame::Frame, Error};

fn publish_frames() -> Result<(), Error> {
    // Create host on UNIX socket
    let host = Host::new("/tmp/video.sock")?;
    
    // Create and allocate a frame
    let frame = Frame::new(1920, 1080, 1920 * 2, "YUYV")?;
    frame.alloc(None)?; // DmaBuf or shared memory
    
    // Frame is now ready to be posted to clients
    // (Posting requires additional host.post() - see host module)
    Ok(())
}
# publish_frames().ok();

Subscribing to Frames (Client)

use videostream::{client::Client, frame::Frame, Error};

fn subscribe_frames() -> Result<(), Error> {
    // Connect to host socket (auto-reconnect on disconnect)
    let client = Client::new("/tmp/video.sock", true)?;
    
    // Wait for next frame (blocking)
    let frame = Frame::wait(&client, 0)?;
    
    // Lock frame before accessing
    frame.trylock()?;
    println!("Frame: {}x{}", frame.width()?, frame.height()?);
    frame.unlock()?;
    
    Ok(())
}
# subscribe_frames().ok();

Camera Capture

use videostream::{camera::create_camera, fourcc::FourCC, Error};

fn capture_camera() -> Result<(), Error> {
    // Configure and open camera
    let cam = create_camera()
        .with_device("/dev/video0")
        .with_resolution(1920, 1080)
        .with_format(FourCC(*b"YUYV"))
        .open()?;
    
    cam.start()?;
    let buffer = cam.read()?;
    println!("Captured: {}", buffer);
    
    Ok(())
}
# capture_camera().ok();

Hardware Encoding

use videostream::{encoder::{Encoder, VSLEncoderProfileEnum}, Error};

fn encode_video() -> Result<(), Error> {
    // Create H.264 encoder (Hantro VPU on i.MX8)
    let encoder = Encoder::create(
        VSLEncoderProfileEnum::Kbps25000 as u32,
        u32::from_le_bytes(*b"H264"),
        30 // fps
    )?;
    
    // Source and destination frames required for encoding
    // (See encoder module for complete example)
    Ok(())
}
# encode_video().ok();

Features

  • Zero-copy sharing: DmaBuf or POSIX shared memory for minimal overhead
  • Hardware acceleration: G2D format conversion, VPU encoding/decoding
  • Multi-subscriber: One host can serve many clients simultaneously
  • V4L2 camera: Native Linux camera capture with DmaBuf export
  • Cross-process: UNIX sockets enable containerized applications

Platform Support

  • Primary: NXP i.MX8M Plus (full hardware acceleration)
  • Compatible: Any Linux system with V4L2 (software fallback)
  • Kernel: Linux 4.14+ (5.6+ recommended for DmaBuf heap)

Error Handling

All fallible operations return [Result<T, Error>]. The [Error] enum provides detailed error information including I/O errors (with errno), library loading failures, and type conversion errors.

Safety

This crate wraps unsafe C FFI calls with safe Rust abstractions. All public APIs are safe to use. Unsafe blocks are carefully isolated in the FFI layer.

Support