Table of Contents

Class RTSPSourceSettings

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

RTSP source settings.

public class RTSPSourceSettings : IMediaPlayerBaseSourceSettings, IVideoCaptureBaseVideoSourceSettings, IVideoMixerSource, IVideoSourceSettings, IMediaBlockSettings

Inheritance

Implements

Inherited Members

Constructors

RTSPSourceSettings()

Initializes a new instance of the VisioForge.Core.Types.X.Sources.RTSPSourceSettings class with the default protocol set and no endpoint. This is the JSON persistence path: VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Uri, VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Login, VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Password and VisioForge.Core.Types.X.Sources.RTSPSourceSettings.AudioEnabled are set from the document payload afterwards. Unlike VisioForge.Core.Types.X.Sources.RTSPSourceSettings.CreateAsync(System.Uri,System.String,System.String,System.Boolean,System.Boolean,VisioForge.Core.BaseContext,System.Threading.CancellationToken) it never contacts the camera, so VisioForge.Core.Types.X.Sources.RTSPSourceSettings.CompatibilityMode starts enabled and the stream information is read when the block opens. Use VisioForge.Core.Types.X.Sources.RTSPSourceSettings.CreateAsync(System.Uri,System.String,System.String,System.Boolean,System.Boolean,VisioForge.Core.BaseContext,System.Threading.CancellationToken) when the camera is reachable and its media information should be probed up front.

One consequence: an ONVIF device-service URL is not resolved to a media URL here, as VisioForge.Core.Types.X.Sources.RTSPSourceSettings.CreateAsync(System.Uri,System.String,System.String,System.Boolean,System.Boolean,VisioForge.Core.BaseContext,System.Threading.CancellationToken) does. It is resolved when the source starts: by MediaPlayerCoreX and VideoCaptureCoreX, and by VisioForge.Core.MediaBlocks.Sources.RTSPSourceBlock and VisioForge.Core.MediaBlocks.Sources.FallbackSwitchSourceBlock when the pipeline is started with StartAsync. A failed lookup is reported as an error. VisioForge.Core.MediaBlocks.Sources.RTSPSourceBlock then does not start; VisioForge.Core.MediaBlocks.Sources.FallbackSwitchSourceBlock plays its fallback until the pipeline is restarted, and with an ONVIF address the fallback appears only once the lookup has given up. Call VisioForge.Core.Types.X.Sources.RTSPSourceSettings.GetVideoURLByONVIFAsync after setting VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Uri, VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Login and VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Password to resolve it up front. 

public RTSPSourceSettings()

Properties

AddReferenceTimestampMeta

Gets or sets a value indicating whether to stamp each frame with the camera's own NTP wall-clock time, derived from its RTCP Sender Reports and read as VisioForge.Core.Types.X.VideoFrameX.SenderNTPTime in the frame events. Independent of VisioForge.Core.Types.X.Sources.RTSPSourceSettings.NTPSync: pipeline timestamps do not change. Default is false.

public bool AddReferenceTimestampMeta { get; set; }

Property Value

bool

Remarks

Camera-dependent: the time is null until the first Sender Report arrives, and for the whole session when the camera sends none or the reports are lost (RTCP blocked over UDP - try VisioForge.Core.Types.X.Sources.RTSPSourceProtocol.TCP). A warning is logged once per session when none arrives within 10 seconds. A video mixer creates new frames, so the time does not pass through VideoMixerBlock. Supported by RTSPSourceBlock, not by FallbackSwitchSourceBlock. Needs GStreamer 1.22 or newer.

AllowedProtocols

Gets or sets the allowed protocols.

public RTSPSourceProtocol AllowedProtocols { get; set; }

Property Value

RTSPSourceProtocol

AudioEnabled

Gets or sets a value indicating whether audio stream is enabled.

public bool AudioEnabled { get; set; }

Property Value

bool

BufferMode

Gets or sets the buffer mode for the jitter buffer. Controls how incoming RTP packets are buffered and reordered. Applied to rtspsrc on open. When VisioForge.Core.Types.X.Sources.RTSPSourceSettings.LowLatencyMode is enabled, the low-latency preset (None) overrides this value.

public RTSPBufferMode BufferMode { get; set; }

Property Value

RTSPBufferMode

CompatibilityMode

Gets or sets a value indicating whether to use compatibility mode. In compatibility mode, the SDK will not try to read camera information, but will still try to open and play the stream inside the RTSPSourceBlock.

public bool CompatibilityMode { get; set; }

Property Value

bool

CustomVideoDecoder

Gets or sets the custom video decoder to use.

public string CustomVideoDecoder { get; set; }

Property Value

string

DoRTCP

Gets or sets a value indicating whether to send RTCP receiver reports. Default is true. Cameras and servers commonly use these reports to tell that the client is still alive, and drop the session without them. Disable only for an old server that cannot handle RTCP.

public bool DoRTCP { get; set; }

Property Value

bool

DropOnLatency

Gets or sets a value indicating whether to drop frames that arrive later than the configured latency. When true, late frames are dropped to maintain the target latency. Applied to rtspsrc on open. When VisioForge.Core.Types.X.Sources.RTSPSourceSettings.LowLatencyMode is enabled, the low-latency preset (false) overrides this value.

public bool DropOnLatency { get; set; }

Property Value

bool

EnableRAWVideoAudioEvents

Gets or sets a value indicating whether to enable RAW audio/video events.

public bool EnableRAWVideoAudioEvents { 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 RTSP 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.RTSPSourceBlock does not apply it; enabling it there logs a warning and playback proceeds without failover.

ForceCustomKeepAlive

Gets or sets a value indicating whether to replace the default RTSP keep-alive with a GET_PARAMETER request every 30 seconds. Default is false. Use only if the camera drops the session under the built-in keep-alive.

public bool ForceCustomKeepAlive { get; set; }

Property Value

bool

Latency

Gets or sets the latency (buffer size). Default is 500 ms. For low latency, enable VisioForge.Core.Types.X.Sources.RTSPSourceSettings.LowLatencyMode or set this to 150 ms or less.

public TimeSpan Latency { get; set; }

Property Value

TimeSpan

Login

Gets or sets IP camera login, if required.

public string Login { get; set; }

Property Value

string

Remarks

The value is stored and used verbatim (no URL-encoding). It is passed as-is to the rtspsrc "user-id" property and to the Basic/Digest auth builders, which expect the literal credential.

LowLatencyMode

Gets or sets a value indicating whether to enable low latency mode. When enabled, configures the RTSP source for minimal buffering and latency: buffer-mode is forced to None and drop-on-latency stays disabled to avoid unnecessary frame drops on jittery live streams. Latency is set to 150 ms unless VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Latency has already been changed from its 500 ms default. Set VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Latency to 150 ms or less to go lower than the preset.

public bool LowLatencyMode { get; set; }

Property Value

bool

NTPSync

Gets or sets a value indicating whether to synchronize RTP timestamps with NTP timestamps. Improves timestamp accuracy for synchronized multi-stream playback. Default is false.

public bool NTPSync { get; set; }

Property Value

bool

NTPTimeSource

Gets or sets the NTP time source for timestamp synchronization. Only used when NTPSync is enabled. Default is NTP.

public RTSPNTPTimeSource NTPTimeSource { get; set; }

Property Value

RTSPNTPTimeSource

Password

Gets or sets IP camera password, if required.

public string Password { get; set; }

Property Value

string

Remarks

The value is stored and used verbatim (no URL-encoding). It is passed as-is to the rtspsrc "user-pw" property and to the Basic/Digest auth builders, which expect the literal credential.

RTPBlockSize

Gets or sets the size of the RTP block.

public int RTPBlockSize { get; set; }

Property Value

int

UDPBufferSize

Gets or sets the size of the UDP buffer.

public int UDPBufferSize { get; set; }

Property Value

int

Uri

Gets or sets the URI.

public Uri Uri { get; set; }

Property Value

Uri

UseGPUDecoder

Gets or sets a value indicating whether to use GPU decoder.

public bool UseGPUDecoder { get; set; }

Property Value

bool

Methods

CreateAsync(Uri, string, string, bool, bool, BaseContext, CancellationToken)

Create as an asynchronous operation.

public static Task<RTSPSourceSettings> CreateAsync(Uri uri, string login, string password, bool audioEnabled, bool readInfo = true, BaseContext context = null, CancellationToken cancellationToken = default)

Parameters

uri Uri

The URI.

login string

The login.

password string

The password.

audioEnabled bool

if set to true audio is enabled.

readInfo bool

if set to true to read information. Disable only if you have some issues.

context BaseContext

Optional context for error logging and diagnostics.

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<RTSPSourceSettings>

A Task<RTSPSourceSettings> representing the asynchronous operation.

Remarks

An ONVIF device-service URL (http://<camera>/onvif/device_service; any http or https URL is taken as one) is resolved to the RTSP URL of one of the camera's media profiles, chosen by its video stream as VisioForge.Core.Types.X.Sources.RTSPSourceSettings.GetVideoURLByONVIFAsync describes. To stream a specific profile, use the overload that takes an ONVIF profile token or name.

CreateAsync(Uri, string, string, bool, string, bool, BaseContext, CancellationToken)

Create as an asynchronous operation, streaming the named profile of an ONVIF camera.

public static Task<RTSPSourceSettings> CreateAsync(Uri uri, string login, string password, bool audioEnabled, string onvifProfile, bool readInfo = true, BaseContext context = null, CancellationToken cancellationToken = default)

Parameters

uri Uri

The URI.

login string

The login.

password string

The password.

audioEnabled bool

if set to true audio is enabled.

onvifProfile string

The token or name of the ONVIF profile to stream from, or null to pick the profile by its video stream.

readInfo bool

if set to true to read information. Disable only if you have some issues.

context BaseContext

Optional context for error logging and diagnostics.

cancellationToken CancellationToken

A token to observe while waiting for the task to complete.

Returns

Task<RTSPSourceSettings>

A Task<RTSPSourceSettings> representing the asynchronous operation.

Remarks

onvifProfile applies when uri is an ONVIF device-service URL (http://<camera>/onvif/device_service; any http or https URL is taken as one); an RTSP URL is used as given. It is matched against the profile tokens first and the profile names second, over the camera's ONVIF Media 2.0 service when it offers one and over Media 1.0 when it does not, when Media 2.0 does not list the profile, or when a Media 2.0 request fails. The tokens and names VisioForge.Core.ONVIFX.ONVIFClientX.GetProfilesAsync reports (Profile.token, Profile.Name) work either way. When the camera has no such profile, a warning lists the profiles it does have and the URL stays unresolved. null, an empty string or white space picks the profile by its video stream, as the overload without this parameter does.

CreateBlock()

Creates the block.

public MediaBlock CreateBlock()

Returns

MediaBlock

MediaBlock.

GetInfo()

Gets the information. Call the ReadInfoAsync method to get the information first.

public MediaFileInfo GetInfo()

Returns

MediaFileInfo

MediaFileInfo.

GetVideoURLByONVIFAsync()

Resolves the ONVIF device-service URL in VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Uri to the RTSP URL of one of the camera's media profiles.

public Task<bool> GetVideoURLByONVIFAsync()

Returns

Task<bool>

true when VisioForge.Core.Types.X.Sources.RTSPSourceSettings.Uri now holds the profile's RTSP URL; false when it is unchanged.

Remarks

The profile is the one named by the onvifProfile argument of VisioForge.Core.Types.X.Sources.RTSPSourceSettings.CreateAsync(System.Uri,System.String,System.String,System.Boolean,System.String,System.Boolean,VisioForge.Core.BaseContext,System.Threading.CancellationToken), otherwise it is chosen by its video stream, because ONVIF does not order profiles by quality and several vendors list a MJPEG or low-resolution profile first. The codec decides first: H.264 and H.265 rank together above MPEG-4, which ranks above JPEG. Within a codec rank the larger frame wins, then the higher frame rate limit, and on a full tie H.264 is preferred to H.265. Only the profiles on the same video source (input) as the camera's first profile are considered, so an encoder, NVR or multi-sensor camera stays on its first input; when none of them describes a video encoder, the first profile is used.

The profiles are read from the ONVIF Media 2.0 service when the camera offers it, which is the only one that reports H.265, and from Media 1.0 otherwise or when Media 2.0 fails. Media 1.0 knows JPEG, MPEG-4 and H.264 only, so on a camera without Media 2.0 an H.265-only profile is not recognized as such. H.265 ranks with H.264 only when this process has an H.265 decoder (the VisioForge Libav redist, or a GPU decoder the hardware provides); otherwise it ranks below every other codec, since an undecodable stream shows nothing. The profile used is logged at Info and the others at Debug.

IsAudioAvailable()

Determines whether audio available.

public bool IsAudioAvailable()

Returns

bool

true if audio available; otherwise, false.

IsVideoAvailable()

Determines whether video available.

public bool IsVideoAvailable()

Returns

bool

true if video available; otherwise, false.

ReadInfoAsync()

Reads the information asynchronous.

public Task<MediaFileInfo> ReadInfoAsync()

Returns

Task<MediaFileInfo>

Task<MediaFileInfo>.

ReadInfoAsync(CancellationToken)

Reads the information asynchronous.

public Task<MediaFileInfo> ReadInfoAsync(CancellationToken cancellationToken)

Parameters

cancellationToken CancellationToken

The cancellation token.

Returns

Task<MediaFileInfo>

Task<MediaFileInfo>.