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

Constructors

NDISourceSettings()

Initializes a new instance of the VisioForge.Core.Types.X.Sources.NDISourceSettings class without probing an NDI source. This is the JSON persistence path: VisioForge.Core.Types.X.Sources.NDISourceSettings.SourceName and VisioForge.Core.Types.X.Sources.NDISourceSettings.URL are set from the document payload afterwards. Unlike VisioForge.Core.Types.X.Sources.NDISourceSettings.CreateAsync(VisioForge.Core.GStreamer.ContextX,System.String,System.String) it never contacts the sender, so VisioForge.Core.Types.X.Sources.NDISourceSettings.GetInfo returns null and VisioForge.Core.Types.X.Sources.NDISourceSettings.IsValid reports false until VisioForge.Core.Types.X.Sources.NDISourceSettings.ReadInfoAsync(VisioForge.Core.GStreamer.ContextX) runs - which VisioForge.Core.MediaBlocks.MediaBlocksPipeline.StartAsync(System.Boolean) does for you through VisioForge.Core.MediaBlocks.IMediaBlockAsyncPrepare. Use VisioForge.Core.Types.X.Sources.NDISourceSettings.CreateAsync(VisioForge.Core.GStreamer.ContextX,System.String,System.String) when the sender is reachable and its media information should be probed up front, or when the pipeline is started with the synchronous VisioForge.Core.MediaBlocks.MediaBlocksPipeline.Start(System.Boolean), which has no place to await a probe.

public NDISourceSettings()

Properties

Bandwidth

Gets or sets the bandwidth setting.

public int Bandwidth { get; set; }

Property Value

int

Remarks

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

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

Remarks

Applied by VideoCaptureCoreX (the source settings are wrapped with a fallback switch automatically) and by an explicit VisioForge.Core.MediaBlocks.Sources.FallbackSwitchSourceBlock. A bare VisioForge.Core.MediaBlocks.Sources.NDISourceBlock (and the Windows-only NDISourceXBlock) does not apply it; enabling it there logs a warning and playback proceeds without failover.

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

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 how long a probe waits for the sender, in milliseconds. It bounds NDISourceBlock.BuildAndroid waiting for the first frame, and the ndisrc probe pipeline behind VisioForge.Core.Types.X.Sources.NDISourceSettings.ReadInfoAsync(VisioForge.Core.GStreamer.ContextX) on macOS and Linux. It does not reach the Windows path: there the NDI SDK reader keeps its own 5 s deadline, and its loop waits for video AND audio, so a longer one would slow every video-only sender rather than give a slow sender more room. It does not bound ndisrc's own state-change timeline once the block is built and running either.

public int ProbeTimeoutMs { get; set; }

Property Value

int

Remarks

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

Remarks

Assigning a different sender drops the cached VisioForge.Core.Types.MediaInfo.MediaFileInfo: a probe describes one sender, and NDISource.Init creates its converters from the probed stream counts, so a stale one would build the graph for the previous sender - a failure that is silent rather than loud.

Timeout

Gets or sets the receive timeout for detecting disconnected sources.

public TimeSpan Timeout { get; set; }

Property Value

TimeSpan

Remarks

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

Remarks

Assigning a different endpoint drops the cached VisioForge.Core.Types.MediaInfo.MediaFileInfo, for the reason given on VisioForge.Core.Types.X.Sources.NDISourceSettings.SourceName.

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.

ReadInfoAsync(ContextX)

Probes the NDI sender and caches its media information, so VisioForge.Core.Types.X.Sources.NDISourceSettings.GetInfo can serve settings that were configured by hand or restored from a pipeline document rather than built by VisioForge.Core.Types.X.Sources.NDISourceSettings.CreateAsync(VisioForge.Core.GStreamer.ContextX,System.String,System.String).

public Task<MediaFileInfo> ReadInfoAsync(ContextX context)

Parameters

context ContextX

The context used for logging. May be null.

Returns

Task<MediaFileInfo>

The cached media information, or null when the sender is not reachable or reports no streams. A cached result is returned without contacting the sender.

ReadInfoAsync(ContextX, CancellationToken)

Probes the NDI sender and caches its media information, giving up when the token is cancelled instead of running out VisioForge.Core.Types.X.Sources.NDISourceSettings.ProbeTimeoutMs.

public Task<MediaFileInfo> ReadInfoAsync(ContextX context, CancellationToken cancellationToken)

Parameters

context ContextX

The context used for logging. May be null.

cancellationToken CancellationToken

Cancelled by a stop or a dispose arriving mid-probe.

Returns

Task<MediaFileInfo>

The cached media information, or null when the sender is not reachable, reports no streams, or the probe was cancelled.