Struct VideoFrame 

pub struct VideoFrame { /* private fields */ }

An owned video frame with validated dimensions, format, stride, and buffer size.

Received frames retain their SDK stride and padding. Encoding processes only active pixels. Use Self::builder for tightly packed outbound storage.

Implementations

impl VideoFrame

pub fn width(&self) -> i32

Get the frame width in pixels.

pub fn height(&self) -> i32

Get the frame height in pixels.

pub fn pixel_format(&self) -> PixelFormat

Get the supported pixel format.

pub fn frame_rate_n(&self) -> i32

Get the frame rate numerator.

pub fn frame_rate_d(&self) -> i32

Get the frame rate denominator.

pub fn picture_aspect_ratio(&self) -> f32

Get the picture aspect ratio.

pub fn scan_type(&self) -> ScanType

Get the scan type.

pub fn timecode(&self) -> i64

Get the timecode in 100 ns units.

Defaults to the SDK’s synthesized-timecode sentinel. An explicit zero is passed through as a literal timecode.

pub fn set_timecode(&mut self, timecode: i64)

Set the frame timecode in 100 ns units without reallocating its pixels. Use the SDK synthesized-timecode sentinel to request SDK clocking.

pub fn set_scan_type(&mut self, scan_type: ScanType)

Set the scan type without changing the frame’s validated layout.

pub fn set_timestamp(&mut self, timestamp: i64)

Set the timestamp in 100 ns units. The SDK fills receive timestamps; outgoing timestamp values are passed through unchanged.

pub fn timestamp(&self) -> i64

Get the receive timestamp in 100 ns units since the Unix epoch.

On receive the SDK supplies this value, or its undefined-timestamp sentinel when unavailable. Outbound values are passed through unchanged; the SDK defines this field for receiving.

pub fn line_stride_or_size(&self) -> LineStrideOrSize

Get the validated line stride or data size union field.

pub fn data(&self) -> &[u8]

Get the frame data.

pub fn data_mut(&mut self) -> &mut [u8]

Get mutable access to the frame data without changing the validated layout.

pub fn replace_data(&mut self, data: Vec<u8>) -> Result<()>

Replace the owned frame data while preserving the validated layout.

Errors

Returns Error::InvalidFrame if data is not exactly the validated layout size.

pub fn metadata(&self) -> Option<&str>

Get frame metadata as UTF-8 text, if present.

pub fn set_metadata<S: Into<String>>( &mut self, metadata: Option<S>, ) -> Result<()>

Replace frame metadata.

Errors

Returns Error::InvalidCString if metadata contains an interior NUL byte, or Error::InvalidFrame if the emitted C string would exceed the metadata size cap.

pub fn set_frame_rate(&mut self, numerator: i32, denominator: i32) -> Result<()>

Set the frame rate.

Errors

Returns Error::InvalidFrame if the numerator or denominator is not positive.

pub fn set_picture_aspect_ratio(&mut self, ratio: f32) -> Result<()>

Set the picture aspect ratio.

Errors

Returns Error::InvalidFrame if ratio is not finite and positive.

pub fn encode_png(&self) -> Result<Vec<u8>>

Encode the video frame as PNG bytes.

This method encodes the frame to PNG format, automatically handling color format conversion from the NDI frame format (BGRA/RGBA/etc.) to PNG-compatible RGBA.

Supported Formats

• RGBA: Direct active-row encoding without a pixel copy
• BGRA: Swaps red and blue channels and preserves alpha
• RGBX: Treats the fourth byte as padding and writes opaque alpha
• BGRX: Swaps red/blue and writes opaque alpha
• Other formats: Returns an error (unsupported for now)

Stride Handling

This method consumes active pixels row-by-row according to the frame’s validated line stride. Valid row padding is skipped. RGBA rows borrow directly; other supported formats reuse at most width * 4 scratch bytes. Codec buffers and encoded output require additional memory.

Errors

Returns an error if:

• The frame format is not RGBA/RGBX/BGRA/BGRX
• The frame uses data-size layout instead of line-stride layout
• The backing data length does not match the validated layout
• PNG encoding fails

Example

let video_frame = receiver.video().capture(Duration::from_secs(5))?;
let png_bytes = video_frame.encode_png()?;
std::fs::write("frame.png", &png_bytes)?;

pub fn encode_jpeg(&self, quality: u8) -> Result<Vec<u8>>

Encode the video frame as JPEG bytes with the specified quality.

This method encodes the frame to JPEG format, automatically handling color format conversion from the NDI frame format into codec component rows without a full-frame RGB staging buffer. Codec/output storage is additional.

Arguments

• quality - JPEG quality from 1 (lowest) to 100 (highest). Typical values are 80-95.

Supported Formats

• RGBA / RGBX: Emits RGB
• BGRA / BGRX: Swaps red/blue and emits RGB
• Other formats: Returns an error (unsupported for now)

Errors

Returns an error if:

• The frame format is not RGBA/RGBX/BGRA/BGRX
• The frame uses data-size layout instead of line-stride layout
• The backing data length does not match the validated layout
• The quality is outside 1..=100
• The dimensions exceed JPEG’s u16 width/height range
• JPEG encoding fails

Example

let video_frame = receiver.video().capture(Duration::from_secs(5))?;
let jpeg_bytes = video_frame.encode_jpeg(85)?;
std::fs::write("frame.jpg", &jpeg_bytes)?;

pub fn encode_data_url(&self, format: ImageFormat) -> Result<String>

Encode the video frame as a base64 data URL for embedding in HTML/JSON.

This produces a string in the format: data:image/png;base64,... or data:image/jpeg;base64,... that can be directly used in HTML <img> tags or stored in JSON.

Arguments

• format - The image format to use (PNG or JPEG with quality)

Example

let video_frame = receiver.video().capture(Duration::from_secs(5))?;

// As PNG
let data_url = video_frame.encode_data_url(ImageFormat::Png)?;
println!("<img src=\"{}\">", data_url);

// As JPEG with quality 90
let data_url = video_frame.encode_data_url(ImageFormat::Jpeg(90))?;

pub unsafe fn from_raw(c_frame: &NDIlib_video_frame_v2_t) -> Result<VideoFrame>

Creates a VideoFrame from a raw NDI video frame with owned data.

Safety

The descriptor must refer to one live allocation covering its SDK plane layout. All active row bytes must be initialized and remain immutable throughout this call; row padding may be uninitialized. Non-null metadata must satisfy the SDK’s readable, NUL-terminated string contract. Only active pixels are copied, so the tightly packed result can outlive the source allocation.

pub fn builder() -> VideoFrameBuilder

Create a builder for configuring a video frame

Trait Implementations

impl Debug for VideoFrame

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for VideoFrame

fn default() -> Self

Returns the “default value” for a type.

impl Drop for VideoFrame

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.

impl<'buf> From<&'buf VideoFrame> for BorrowedVideoFrame<'buf>

fn from(frame: &'buf VideoFrame) -> Self

Converts to this type from the input type.