Table of Contents

Class NDISourceSettings

Namespace
VisioForge.Core.Types.X.Sources
Assembly
VisioForge.Core.dll

NDI source settings.

public class NDISourceSettings : IVideoCaptureBaseVideoSourceSettings, IVideoMixerSource, IVideoSourceSettings, IMediaBlockSettings

Inheritance

Implements

Inherited Members

Properties

Bandwidth

Gets or sets the bandwidth setting.

public int Bandwidth { get; set; }

Property Value

int

Remarks

Round-3 MEDIUM #270: only the three NDI-defined values are valid (NDIlib_recv_bandwidth_e: -10 / 10 / 100). Setting any other value previously passed through to libndi which silently rejected or clamped it, producing confusing native-side behaviour. Reject the misconfiguration at the property setter so it surfaces at the call site.

Exceptions

ArgumentOutOfRangeException

Thrown when value is not -10, 10, or 100.

ColorFormat

Gets or sets the color format for receiving video.

public NDIRecvColorFormat ColorFormat { get; set; }

Property Value

NDIRecvColorFormat

ConnectTimeout

Gets or sets the connection timeout for initial connection attempts.

public TimeSpan ConnectTimeout { get; set; }

Property Value

TimeSpan

Remarks

Round-3 MEDIUM #269: see VisioForge.Core.Types.X.Sources.NDISourceSettings.Timeout for the validation rationale.

Exceptions

ArgumentOutOfRangeException

Thrown when value is negative or greater than 1 hour.

DoTimestamp

Gets or sets whether to apply timestamps to buffers.

public bool DoTimestamp { get; set; }

Property Value

bool

FallbackSwitch

Gets or sets the fallback switch settings for automatic failover. When configured, the source will automatically switch to a fallback (static text, image, or media) when the main NDI stream fails.

public FallbackSwitchSettings FallbackSwitch { get; set; }

Property Value

FallbackSwitchSettings

MaxPullFps

Optional cap on the rate at which the Android framesync loop pulls frames from libndi.

Platform note: This property only affects Android NDI receivers. On non-Android platforms (Windows, Linux, macOS) it has no effect because those platforms use a push-based receiver model where the source controls the frame delivery rate.

0 means uncapped — pull at the source frame rate. A non-zero value clamps the polling period to 1 / MaxPullFps seconds: the framesync still receives every source frame, but our consumer only pulls the latest one MaxPullFps times per second, halving the CPU cost of the poll loop on high-fps sources where the device cannot display every frame anyway. Default is 30 — appropriate for a 4K@60 NDI source feeding a typical 30 Hz display; raise to 0 (uncapped) for full source-rate playback when the device can keep up. 
public int MaxPullFps { get; set; }

Property Value

int

MaxQueueLength

Gets or sets the maximum receive queue length.

public int MaxQueueLength { get; set; }

Property Value

int

Remarks

Round-3 MEDIUM #271: changed from uint to int for CLS-compliance and consistent typing across the API surface (uint properties friction non-C# language consumers and confuse downstream serializers / XAML bindings). The single consumer (VisioForge.Core.GStreamer.Sources.NDISource.ApplySettings(VisioForge.Core.GStreamer.ContextX,Gst.Element,VisioForge.Core.Types.X.Sources.NDISourceSettings)) casts back to uint for the GLib property. Negative values are rejected by the setter.

Warning — value of 0: ndisrc treats max-queue-length=0 as "no buffering", which on a live link with any jitter will drop virtually every frame and surface deep inside the pipeline as silent "no video". Setting 0 is permitted (some specialised low-latency configurations genuinely want it), but is almost always a misconfiguration; the setter emits a one-line diagnostic so the choice is observable in logs.

Exceptions

ArgumentOutOfRangeException

Thrown when value is negative.

ProbeTimeoutMs

Gets or sets the Android-side probe timeout in milliseconds. Used by NDISourceBlock.BuildAndroid when probing the first frame to learn the source caps. Has no effect on desktop platforms (which use ndisrc's own state-change timeline).

public int ProbeTimeoutMs { get; set; }

Property Value

int

Remarks

Round-3 HIGH #45 / LOW #306: the previous BuildAndroid path hard-coded a 10-second probe timeout with no caller-visible knob. Slow / congested networks legitimately need longer; tightly-controlled local setups can fail-fast with a much shorter window. Exposing this as a Setting lets the caller pick the right value without forking the SDK.

Exceptions

ArgumentOutOfRangeException

Thrown when value is < 100 or > 60000.

ReceiverName

Gets or sets the name of the receiver.

public string ReceiverName { get; set; }

Property Value

string

SourceName

Gets or sets the name of the source.

public string SourceName { get; set; }

Property Value

string

Timeout

Gets or sets the receive timeout for detecting disconnected sources.

public TimeSpan Timeout { get; set; }

Property Value

TimeSpan

Remarks

Round-3 MEDIUM #269: validates the assigned value to prevent passing a negative or pathologically large duration to libndi. The native timeout property on ndisrc takes uint milliseconds, so a negative TimeSpan or one exceeding ~49.7 days would silently overflow on the cast site (VisioForge.Core.GStreamer.Sources.NDISource.ApplySettings(VisioForge.Core.GStreamer.ContextX,Gst.Element,VisioForge.Core.Types.X.Sources.NDISourceSettings)) and give the receiver a near-zero or zero timeout — manifesting as confusing instant disconnects. Accept only [0, 1 hour].

Exceptions

ArgumentOutOfRangeException

Thrown when value is negative or greater than 1 hour.

TimestampMode

Gets or sets the timestamp mode for synchronization.

public NDITimestampMode TimestampMode { get; set; }

Property Value

NDITimestampMode

URL

Gets or sets the URL.

public string URL { get; set; }

Property Value

string

VideoCodecHint

Gets or sets the video codec hint sent to the NDI sender after connection.

public NDIVideoCodecHint VideoCodecHint { get; set; }

Property Value

NDIVideoCodecHint

Remarks

Only effective on Android. On desktop the GStreamer ndisrc plugin manages codec negotiation internally.

Methods

CreateAsync(ContextX, NDISourceInfo)

Create as an asynchronous operation.

public static Task<NDISourceSettings> CreateAsync(ContextX context, NDISourceInfo info)

Parameters

context ContextX

The context.

info NDISourceInfo

The information. null is treated as a configuration error and surfaces as a logged error + null return, matching the sister overload's "log + null" contract.

Returns

Task<NDISourceSettings>

A Task<NDISourceSettings> representing the asynchronous operation.

CreateAsync(ContextX, string, string)

Create as an asynchronous operation.

public static Task<NDISourceSettings> CreateAsync(ContextX context, string sourceName, string url)

Parameters

context ContextX

The context.

sourceName string

Name of the source.

url string

The URL.

Returns

Task<NDISourceSettings>

A Task<NDISourceSettings> representing the asynchronous operation.

CreateBlock()

Creates the block.

public MediaBlock CreateBlock()

Returns

MediaBlock

MediaBlock.

GetInfo()

Gets the information.

public MediaFileInfo GetInfo()

Returns

MediaFileInfo

MediaFileInfo.

IsValid()

Checks whether these settings are valid.

public bool IsValid()

Returns

bool

true when the cached VisioForge.Core.Types.MediaInfo.MediaFileInfo reports at least one video or audio stream; otherwise, false.

Remarks

Returns true only when a cached VisioForge.Core.Types.MediaInfo.MediaFileInfo is available and contains at least one video or audio stream. This means a successful VisioForge.Core.Types.X.Sources.NDISourceSettings.CreateAsync(VisioForge.Core.GStreamer.ContextX,System.String,System.String) has probed the source, so true is a strong signal that the source is reachable AND has negotiated streams.

On Android, the native NDI SDK (libndi.so) is used instead of the GStreamer ndisrc plugin, but the contract is identical — VisioForge.Core.Types.X.Sources.NDISourceSettings.CreateAsync(VisioForge.Core.GStreamer.ContextX,System.String,System.String) creates a temporary NDI receiver to probe stream caps.