Struct Receiver 

pub struct Receiver<M: ReceiverMode = RawCapture> { /* private fields */ }

An owned NDI receiver. The default mode permits all raw capture kinds. FrameSync privately changes the mode while retaining the same resource core.

Implementations

impl Receiver

pub fn new(ndi: &NDI, create: &ReceiverOptions) -> Result<Self>

pub fn video(&self) -> Capture<'_, VideoKind>

Capture video frames from this receiver.

Returns a Capture view whose verbs cover the three capture styles:

• capture — reliable owned capture that retries across the NDI SDK’s initial-sync warm-up.
• try_capture — a single owned poll, Ok(None) when no frame is ready.
• try_capture_ref — a single zero-copy poll borrowing the SDK buffer in place.

Video frames may carry per-row padding (e.g. RGBX/BGRX); see VideoFrame for how to read them correctly.

Examples

// Reliable owned capture
let frame = receiver.video().capture(Duration::from_secs(5))?;
println!("{}x{}", frame.width(), frame.height());

// Zero-copy borrow
if let Some(frame) = receiver.video().try_capture_ref(Duration::from_secs(1))? {
    for plane in frame.planes() {
        for row in plane.rows() {
            println!("{} active bytes in place", row.len());
        }
    }
}

impl<M: ReceiverMode> Receiver<M>

pub fn set_tally(&self, tally: &Tally) -> bool

Publish this receiver’s program/preview tally upstream.

Returns the SDK’s status flag unchanged. SDK implementations may report success while disconnected; use Self::is_connected to check the connection. The SDK retains tally state for future connections.

pub fn send_metadata(&self, metadata: &MetadataFrame) -> bool

Send metadata upstream and return the SDK’s status flag unchanged.

This flag is not a connection query; use Self::is_connected for that.

pub fn ptz_is_supported(&self) -> bool

Return whether the connected source supports PTZ commands.

pub fn ptz_recall_preset(&self, preset: u32, speed: f32) -> Result<()>

Recall preset 0..=99 at a finite speed within 0.0..=1.0.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_zoom(&self, zoom_value: f32) -> Result<()>

Set absolute zoom to a finite value within 0.0..=1.0. Zero is zoomed in; one is zoomed out.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_zoom_speed(&self, zoom_speed: f32) -> Result<()>

Set zoom speed within -1.0..=1.0 (finite). Negative moves outward; positive moves inward.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_pan_tilt(&self, pan_value: f32, tilt_value: f32) -> Result<()>

Set finite pan and tilt positions within -1.0..=1.0. Pan increases from left to right; tilt increases from bottom to top.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_pan_tilt_speed(&self, pan_speed: f32, tilt_speed: f32) -> Result<()>

Set finite pan and tilt speeds within -1.0..=1.0. Positive pan moves left; positive tilt moves up. Zero stops motion.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_store_preset(&self, preset_no: i32) -> Result<()>

Store the current camera settings as preset 0..=99.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_auto_focus(&self) -> Result<()>

Enable automatic focus.

Errors

Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_focus(&self, focus_value: f32) -> Result<()>

Set finite absolute focus within 0.0..=1.0. Zero focuses at infinity; one focuses as close as possible.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_focus_speed(&self, focus_speed: f32) -> Result<()>

Set finite focus speed within -1.0..=1.0. Negative focuses outward; positive focuses inward.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_white_balance_auto(&self) -> Result<()>

Enable automatic white balance.

Errors

Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_white_balance_indoor(&self) -> Result<()>

Select the indoor white-balance preset.

Errors

Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_white_balance_outdoor(&self) -> Result<()>

Select the outdoor white-balance preset.

Errors

Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_white_balance_oneshot(&self) -> Result<()>

Set white balance from the current image.

Errors

Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_white_balance_manual(&self, red: f32, blue: f32) -> Result<()>

Set finite red and blue white-balance levels within 0.0..=1.0.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_exposure_auto(&self) -> Result<()>

Enable automatic exposure.

Errors

Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_exposure_manual(&self, exposure_level: f32) -> Result<()>

Set finite exposure within 0.0..=1.0, from dark to light.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn ptz_exposure_manual_v2( &self, iris: f32, gain: f32, shutter_speed: f32, ) -> Result<()>

Set finite iris, gain, and shutter-speed levels within 0.0..=1.0. Iris and gain increase from dark to light; shutter speed increases from slow to fast.

Errors

Returns Error::InvalidConfiguration for out-of-range or non-finite parameters, before issuing an SDK command. Returns Error::PtzCommandFailed if the SDK rejects the command.

pub fn audio(&self) -> Capture<'_, AudioKind>

Capture audio frames from this receiver.

Returns a Capture view; see Receiver::video for the three capture verbs it exposes (capture, try_capture, try_capture_ref).

Examples

if let Some(audio) = receiver.audio().try_capture_ref(Duration::from_secs(1))? {
    println!("{} channels, {} samples", audio.num_channels(), audio.num_samples());
}

pub fn metadata(&self) -> Capture<'_, MetadataKind>

Capture metadata frames from this receiver.

Returns a Capture view; see Receiver::video for the three capture verbs it exposes (capture, try_capture, try_capture_ref).

Examples

if let Some(meta) = receiver.metadata().try_capture(Duration::from_millis(100))? {
    println!("metadata: {}", meta.data());
}

pub fn is_connected(&self) -> bool

Check if the receiver is still connected to its source.

Returns true if there is at least one active connection to the source, false otherwise. This can be used to detect when a source goes offline or becomes unavailable.

Examples

if receiver.is_connected() {
    println!("Still connected to source");
} else {
    println!("Lost connection to source");
}

pub fn reconnect(&self) -> Result<()>

Re-establish this receiver’s connection to its original source, in place.

Re-points the existing NDI receiver instance at the Source it was created for without destroying and recreating the receiver. This is intended for mid-session recovery: when a source’s feed has gone silent (for example an encoder-bound NDI|HX camera that dropped its proxy stream under load), a reconnect forces a fresh connection attempt while avoiding the source-rediscovery round trip — and the discovery race — that tearing down and rebuilding the receiver would incur.

Liveness can be observed via Self::is_connected and Self::connection_stats (video_frames_received resuming its climb indicates frames are flowing again).

Thread safety

NDIlib_recv_connect is the one receive call the SDK does not make safe to run concurrently with NDIlib_recv_capture_v3 on the same instance. This method therefore takes the receiver’s capture guard exclusively: it blocks until every in-flight capture on this receiver returns, and holds off any capture that starts while it runs. Captures on the same receiver still run concurrently with each other; only a reconnect is exclusive. Because it can block for as long as a capture’s timeout, prefer short capture timeouts on receivers you intend to recover, and call it off the async runtime — AsyncReceiver::reconnect does this for you.

Errors

Returns an error only if the stored Source cannot be re-marshalled to its FFI representation; NDIlib_recv_connect itself reports no status, so a returned Ok means the reconnect was issued, not that the feed has recovered — confirm recovery via Self::connection_stats.

pub fn source(&self) -> &Source

Get the source this receiver is connected to.

Returns a reference to the Source that was specified when creating this receiver. This is useful for identifying which source a receiver is associated with when managing multiple receivers.

Examples

let source = receiver.source();
println!("Connected to: {name}", name = source.name);

pub fn connection_stats(&self) -> ConnectionStats

Get connection and performance statistics for this receiver.

Provides detailed statistics including:

• Number of active connections
• Total frames received (video, audio, metadata)
• Dropped frames (video, audio, metadata)
• Queued frames waiting to be processed

This is useful for monitoring receiver health and diagnosing performance issues in production applications.

Examples

let stats = receiver.connection_stats();
println!("Connections: {connections}", connections = stats.connections);
println!("Video frames: {received} (dropped: {dropped})",
         received = stats.video_frames_received,
         dropped = stats.video_frames_dropped);
println!("Frame drop rate: {rate:.2}%",
         rate = stats.video_drop_percentage());

pub fn poll_status_change( &self, timeout: Duration, ) -> Result<Option<ReceiverStatus>>

Poll for SDK receiver status changes, including notifications consumed by media capture.

Multiple unobserved notifications can coalesce. Concurrent status pollers compete to consume them; this is not a broadcast or event history. A pending notification avoids waiting, but publication cannot interrupt an SDK wait already in progress. Notifications are rechecked after lock/SDK waits.

Arguments

• timeout - Maximum time to wait for status change. Must not exceed crate::MAX_TIMEOUT (~49.7 days).

Returns

• Some(ReceiverStatus) - Status has changed
• None - Timeout occurred with no status change, including when a reconnect holds the capture lock for the remaining budget.

Errors

Returns Error::InvalidConfiguration if timeout exceeds crate::MAX_TIMEOUT, or Error::CaptureFailed if the SDK reports a lost connection. The budget includes lock contention; SDK calls may overshoot it.