Crate videostream

Crate videostream 

Source
Expand description

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(())
}

§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(())
}

§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(())
}

§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(())
}

§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

Modules§

camera
V4L2 camera capture with DmaBuf support.
client
Client API for subscribing to video frames.
decoder
Hardware-accelerated video decoding (H.264/H.265).
encoder
Hardware-accelerated video encoding (H.264/H.265).
fourcc
FOURCC pixel format codes.
frame
Frame management for video data.
host
Host API for publishing video frames.

Macros§

vsl
Helper macro for calling C library functions safely.

Enums§

Error
Error type for VideoStream library operations

Functions§

timestamp
Returns the current monotonic timestamp in nanoseconds.
version
Returns the VideoStream Library version string.