Parameter identifiers

The parameter identifiers are constant strings declared in the include files.



- the 1st column is the name of the identifier that can be passed as parameter from the IdatasteadRtspSourceConfig interface

- the 2nd column is the name of the IdatasteadRtspSourceConfig's function that accepts this parameter

- the 3rd column is the name of this parameter. If it exist it can be passed alternatively at the end of the URL (instead of using IdatasteadRtspSourceConfig)
E.g. rtsp://192.168.0.25/axis-media/media.amp?videocodec=h264&audio=1>recordingfilename=c:\folder\test.mp4



parameter string identifier for the IdatasteadRtspSourceConfig interface

associated interface function

parameter identifier (if set at the end of the the RTSP URL)

description




ACTIONS

RTSP_Action_OpenURL

Action()


Set the URL and connects the filter synchronously


This function must be invoked while configuring the filter, at last, after setting all the optional parameters, if needed.

Returns S_OK upon success


RTSP_Action_OpenURLAsync

Action()


Set the URL and initiates the connection, but returns immediately without waiting for the connection to complete.
The filter is connecting in the background and will notify when the connection complete through the ImediaEventEx notification or a callback function (see below).
Note that invoking OpenURLAsync EXITS IMMEDIATELY without waiting for the connection to complete. So you must wait for callback before trying to render the pins, because the pin formats are not available until the filter connection is completed.


This function must be invoked while configuring the filter, at last, after setting all the optional parameters, if needed.

The function initiates the connection and returns S_OK if the URL syntax is correct.


Then, when the filter completes the connection, the application can get notified in 2 ways:


1) the EC_RTSPNOTIFY (param1, param2) graph event occurs with:
param1 = EC_RTSP_PARAM1_OPENURLASYNC_CONNECTION_RESULT

param2 = 1 if the connection succeeds, 0 if the connection fails.
For sample code earch for "HandleGraphEvent()" in Form1.cs of the C# demo project


2) if OpenURLAsyncCompletionCB has been configured with SetAsyncOpenURLCallback, the callback occurs and the Result parameter returns S_OK upon success, or an error code upon failure


RTSP_Action_RecordToNewFileNow

Action()


Close the current file being written and starts writing to a new file specified as parameter. The new file must have the same extension than the previous one.


- if no file name is specified as parameter, the current file is closed, reopened and overwritten.


- to temporarily suspend the recording without sopping the graph, pass a file name having the same extension and "nul" as name, e.g. if recording in MP4, pass nul.mp4 as parameter (as is, without file path). The recording remains suspended until you pass a new valid file name to resume the recording.

Note: this action applies only while the graph is running and recording.
To start a new recording graph:
- first set the recording file name with SetStr (RTSP_Source_RecordingFileName_str, filename)
- then invoke Action (RTSP_Action_OpenURL, URL) or Action (RTSP_Action_OpenURLAsync, URL)

RTSP_Action_CancelPendingConnection

Action()


Cancels a pending URL connection, previously initiated by RTSP_Action_OpenURLAsync
It can be invoked e.g. when exiting the application, just before clearing the graph, to ensure any pending connection is cancelled immediately.


RTSP_Action_PauseURL

Action()


Pauses the URL


RTSP_Action_ResumeURL

Action()


Resumes the URL


RTSP_Action_PauseRecording

Action()


Pauses the recording of the current file, while the preview keeps running.

RTSP_Action_ResumeRecording

Action()


Resumes the recording of the current file.

RTSP_Action_CaptureFrame

Action()


Captures a frame as snapshot. The format of the captured frame depends on the Option parameter:


- file name:
the next frame is captured in the format specified by the extension. The supported formats are: BMP, TIFF, PNG, JPG
E.g. to capture a JPEG image:
DatasteadRTSPSourceConfig.Action (RTSP_Action_CaptureFrame, "c:\folder\nextimage.jpg")

- HBITMAP (keyword):
the next frame is captured to a bitmap handle, and this bitmap handle is returned by an EC_RTSPNOTIFY (EC_RTSP_PARAM1_FRAME_CAPTURE_SUCCEEDED, BitmapHandle) notification event sent to the filter graph.
E.g.:
DatasteadRTSPSourceConfig.Action (RTSP_Action_CaptureFrame, "HBITMAP")

note: do not delete the bitmap handle, it may be reused for the next capture and will be released by the filter




SOURCE URL

RTSP_Source_IsURLConnected_bool

GetBool()


Returns true if the URL is connected.
It returns false if:
- the URL is not yet connected
- the URL is reconnecting when AutoReconnect is enabled

RTSP_Source_Format_str

SetStr()

GetStr()

srcformat

Used to specify the input format for some HTTP URLs if the filter does not detect them properly.
The possible values are:

"mjpeg": IP camera, HTTP in JPG or MJPEG mode

"mxg": IP camera, HTTP in MXPEG mode

"jpeg:WidthxHeight": specifies the image dimensions when the RTSP stream is a MJPEG stream and the size is not properly detected by the filter

RTSP_Source_RecordingFileName_str

SetStr()

GetStr()

recordingfilename

Sets the recording file name. Setting this property enables the recording of the RTSP stream to a file. The extension determines the format of the recording.


The formats supported by the current version are:

mp4, flv, mov, avi, mkv


Examples:
c:\folder\recfile.mp4

c:\folder\recfile.flv

c:\folder\recfile.mov

c:\folder\recfile.avi

c:\folder\recfile.mkv


To configure the filter in recording mode without starting immediately the recording, set a nul file name without path with the desired extension, e.g.:

nul.mp4
Then, once the filter is running, when you want to really start the recording, just invoke:

Action (RTSP_Action_RecordToNewFileNow, c:\folder\realfilename.mp4)

to start writing to the file.


Remarks:

- the filter does not include an H264 encoder, it just saves the native H264 samples to the recording file.


- if the audio recording is enabled, it encodes the audio stream to PCM, MP3 or AAC depending on the recording format selected.

- if the recording file name is set while the filter is running, this closes the current file being recorded and starts saving to a new file on the fly.


RTSP_Source_RecordingBacktimedStartSeconds_int

SetInt()
GetInt()

backtimedstart

see #10.Backtimed recording

RTSP_Source_Recording_Title_str

SetStr()
GetStr()

tilte

Sets a title for the video clip (for containers that support this feature, like MP4)


RTSP_Source_PlayableWhileRecording_int

SetInt()
GetInt()

playablewhilerecording

0: the clip is not playable while recording (default)
1: the clip is playable while recording if the container supports this possibility (like MP4 or ASF)
2 : idem, different mode

RTSP_Source_ContinuousRecording_bool

SetBool()
GetBool()

continuousrecording

When enabled, the recording does not stop when the graph is stopped / restarted. The recording stops only when the graph is destroyed (default: disabled)

RTSP_Source_AutoReconnect_bool

SetBool()

GetBool()

autoreconnect

Enables/disables the automatic reconnection of the filter.

Default: enabled


RTSP_Source_MaxAnalyzeDuration_int

SetInt()
GetInt()

maxanalyzeduration

Maximum duration of the anaysis of the stream during the initial connection, expressed in milliseconds, e.g.:
>maxanalyzeduration=1000

RTSP_Source_DeviceLostTimeOut_int

SetInt()
GetInt()

devicelosttimeout

If no frame is received after this timeout (expressed in milliseconds, default = 10000) the auto reconnection (if autoreonnect=1) or device lost event (if autoreconnect=0) occurs (see the Auto reconnection chapter)
Default: 10 sec. (10000)


RTSP_Source_BufferDuration_int

SetInt()
GetInt()

buffer

Specifies the buffering duration in milliseconds.

Default: 0 if no audio, 1000 milliseconds if audio

RTSP_Source_ConnectionTimeOut_int

SetInt()
GetInt()

timeout

Connection timeout in milliseconds

Default: 20000 (20 seconds)

RTSP_Source_RTSPTransport_int

SetInt()
GetInt()

rtsptransport

RTSP transport mode:
0: automatic

1: tcp

2: udp

3: http

4: udp_multicast

RTSP_Source_RTSPRange_str

SetStr()

GetStr()

rtsprange

Optional Rtsp range specification (e.g. to start playing a clip stored on the RTSP source at the specified date/time). E.g.:
clock=20150217T153000Z-

RTSP_Source_AuthUser_str

SetStr()


User name, if required

RTSP_Source_AuthPassword_str

SetStr()


Password, if required

RTSP_Source_StartTime_int

SetInt()
GetInt()

starttime

If the source URL supports seeking, you can specify the start time expressed in milliseconds.
E.g. if the start time should be 2 min 30 sec → 2x60 + 30 = 150 seconds = 150000 milliseconds, invoke SetInt ("Source_StartTime_int", 150000)

RTSP_Source_Threads_int

SetInt()
GetInt()

threads

Number of threads assigned to the decoding (and eventually encoding) of the source.
Default: 1
0: auto

RTSP_Source_GetAudioDevices_str

GetStr()


Retrieves the list of the DirectShow audio capture devices (microphone, line input, webcam mic., etc...) currently available on the PC.
It is returned as an array of strings separated by a "\n" (line feed or chr(10) character), e.g.:
Microphone (Realtek High Definition Audio)\nMicrophone (HD Webcam C525\nDecklink Audio Capture

RTSP_Source_SetAudioDevice_str

SetStr()


Sets the name of the audio capture device to use. The name must be one of the names returned by GetStr (RTSP_Source_GetAudioDevices_str,...)
Setting this property invalidates the audio of the RTSP source or IP camera (if any), and selects the use of the specified audio capture device instead.

RTSP_Source_LowDelay_int

SetInt()
GetInt()

lowdelay

Used to enable/disable the low delay mode.
Enabling the low delay mode may help to reduce the latency.
However, when enabled, in some rare cases the video may appear jerky. In this case this setting must be kept disabled to avoid the jerkiness.
-1 : auto
0: disabled
1: enabled

RTSP_Source_FrameRate_double

SetDouble()

GetDouble()

srcframerate

Used to specify the native frame rate of the video stream in the case it would not be properly detected (this has been reported with some video streams configured in Variable Bit Rate mode (VBR))

E.g. to specify 30 fps:


- programmatically:
DatasteadRTSPSourceConfig.Action (RTSP_Source_FrameRate_double, 30.0)


- at the end of the URL:
>srcframerate=30.0




VIDEO OUTPUT PIN

RTSP_VideoStream_Enabled_bool

SetBool()

GetBool()

videostreamenabled

Enables/disables the video decompression and the rendering of the video pin
Default: true

RTSP_VideoStream_PinFormat_str

SetStr()
GetStr()

videopinformat

By default the video pin can connect in RGB32 or RGB24 format.
This property allows to force one of the following pin formats (not case-sensitive):
RGB32
RGB24
RGB565
RGB555
NV12
UYVY
I420

RTSP_VideoStream_Recorded_bool

SetBool()

GetBool()


If the recording is enabled (by setting Source_RecordingFileName_str) and the RTSP URL outputs audio and video, allows record audio only by disabling the recording of the video stream.

Default: true

RTSP_VideoStream_ConfigureTextOverlay_str

SetStr()
GetStr()

textoverlay

Enables a text overlay
To enable more than one overlay, invoke the function more than one time with a different overlay ID.
Note: the overlay(s) must be enabled before loading the URL. If they must not be displayed immediately, set an empty string, then update it while the filter is running.
See the Text overlay chapter above for the syntax.

RTSP_VideoStream_ConfigureHueBrightSat_str

SetStr()
GetStr()

brighthuesat

Enables the brightness/hue/saturation adjustment.
Note: must be enabled before loading the URL. If they must not be applied immediately, set the default values (b=0,h=0,s=1), then update them while the filter is running.
See the Brightness/Hue/Saturation chapter for the syntax.

RTSP_VideoStream_HWAcceleration_int

SetInt()

GetInt()

hwaccel

Enables hardware-accelerated decoding:
0: no hardware acceleration
1: dxva2 acceleration
2: Intel QuickSync acceleration
3: NVidia CUVID acceleration

RTSP_VideoStream_Index_int

SetInt()
GetInt()

videostreamindex

If the RTSP URL outputs more than 1 video stream, you can specify the index of the video stream to use (in the 0..n-1 range)
Default: 0

RTSP_VideoStream_Deinterlacing_int

SetInt()
GetInt()

deint

Enables the deinterlacing:
0: no deinterlacing (default)
1: yadif deinterlacing
2: w3fdif deinterlacing (consumes more CPU)

RTSP_VideoStream_Width_int

SetInt()
GetInt()

width

Used to specify a non-default frame width for the video pin

note: when the URL is connected, GetInt (RTSP_VideoStream_Width_int, Value) returns the video width of the decoded video stream

RTSP_VideoStream_Height_int

SetInt()
GetInt()

height

Used to specify a non-default frame height for the video pin

note: when the URL is connected, GetInt (RTSP_VideoStream_Height_int, Value) returns the video height of the decoded video stream

RTSP_VideoStream_FrameRateMax_double

SetDouble()
GetDouble()

maxframerate

Used to specify the frame rate of the video pin
Default: native frame rate of the video stream

Note: passing -1 as value let enable the keyframe-only decoding mode, only the key frames are decoded. In this case the frame rate depend on the key frame spacing of the IP camera or RTSP / RTMP source.

RTSP_VideoStream_Synchronized_bool

SetBool()
GetBool()

vidsync

If disabled, the filter removes the sample times, so the samples are rendered as fast as possible (the samples are not scheduled for rendering)
Default: true

RTSP_VideoStream_Filter_str

SetStr()

videofilter

Specifies a Ffmpeg video filter to use, e.g. hflip for an horizontal flipping, vflip for a top-down image
Note: depending on the context, some filters may not be useable




FRAME CAPTURE

RTSP_FrameCapture_Width_int

SetInt()
GetInt()

framecapturewidth

Specifies a non-default width for the next captured frame

RTSP_FrameCapture_Height_int

SetInt()
GetInt()

framecaptureheight

Specifies a non-default height for the next captured frame

RTSP_FrameCapture_Time_int

SetInt()
GetInt()

framecapturetime

Schedules the sream time the next frame will be captured, expressed in milliseconds

RTSP_FrameCapture_FileName_str

SetStr()
GetStr()

framecapturefilename

Specifies the full path and file name of the next frame to capture.
The extension specifies the format, the supported formats are: BMP, JPG, PNG, TIFF
E.g.:
DatasteadRTSPSourceConfig.SetStr (RTSP_FrameCapture_FileName_str, "c:\folder\nextframe.png")




AUDIO OUTPUT PIN

RTSP_AudioStream_BitRate_int

SetInt()
GetInt()

audiobitrate

Specifies the encoding bit rate for the audio codec (PCM, MP3 or AAC)

RTSP_AudioStream_Enabled_bool

SetBool()

GetBool()

audiostreamenabled

Enables/disables the audio decompression and the rendering of the audio pin
Default: true

RTSP_AudioStream_Recorded_bool

SetBool()

GetBool()


If the recording is enabled (by setting Source_RecordingFileName_str) and the RTSP URL outputs audio and video, allows record video only by disabling the recording of the audio stream.

Default: true

RTSP_AudioStream_Index_int

SetInt()
GetInt()

audiostreamindex

If the RTSP URL outputs more than 1 audio stream, you can specify the index of the audio stream to use (in the 0..n-1 range)
Default: 0

RTSP_AudioStream_Filter_str

SetStr()

GetStr()

audiofilter

Specifies a Ffmpeg audio filter to use
Note: depending on the context, some filters may not be useable

RTSP_AudioStream_Volume_int

SetInt()
GetInt()

audiovolume

audio volume adjustment.
65535 = default volume

0 = muted
< 65535: reduces the volume
> 65535: increases the volume




RESTREAMING: DESTINATION URL AND ENCODING

RTSP_Dest_URL_str

SetStr()


GetStr()

desturl

Sets the re-streaming URL.

Examples (at the end of the RTSP URL)


RTSP server on port 6000 (the IP address is the address of a network card on the PC running the filter)

>desturl=rtspsrv://192.168.0.25:6000


UDP unicast on port 5000 (the IP address is the IP address of the client PC

>desturl=udp://192.168.0.200:5000


UDP multicast on port 4000
>desturl=udp://239.255.0.10:4000


Programmatical example:
DatasteadRTSPSourceConfig.SetStr ("RTSP_Dest_URL_str", "rtspsrv://192.168.0.25:6000")

RTSP_Dest_Video_BitRate

SetInt()
GetInt()

destvideobitrate

Sets the re-streaming video bit rate expressed in kb/s

RTSP_Dest_Video_Quality

SetInt()
GetInt()

destvideoquality

Sets the re-streaming video quality in the 0..31 range
(-1 = disabled, 0 = best quality, other values decrease the quality)
Note: setting a value enables the VBR encoding mode

RTSP_Dest_Video_KeyFrameInterval

SetInt()
GetInt()

destvideokeyframeinterval

Sets the key frame spacing (default 30)




READ-ONLY PROPERTIES

RTSP_Source_StreamInfo_str

GetStr()


Retrieves information about the streams
Note: this is a multi-line string, each line is separated by CHR(13) + CHR(10).

RTSP_Source_GetState_int

GetInt()


returns the current source state. Possible values include:
state_disconnected, state_connecting_async, state_connecting_sync, state_reconnecting, state_connected, state_previewing, state_recording_paused, state_recording_active

RTSP_CurrentRecorded_FileName_str

GetStr()


Returns the file name of the current recording

RTSP_CurrentRecording_FileSizeKb_int

GetInt()


Returns the file size in Kb of the current recording

RTSP_CurrentRecording_ClipDurationMs_int

GetInt()


Returns the duration In milliseconds of the current recording

RTSP_CurrentRecording_VideoFrameCount_int

GetInt()


Returns the video frame count of the current recording

RTSP_LastRecorded_FileName_str

GetStr()


Returns the name of the last file recorded

RTSP_LastRecording_FileSizeKb_int

GetInt()


Returns the file size in Kb of the last file recorded

RTSP_LastRecording_ClipDurationMs_int

GetInt()


Returns the duration In milliseconds of the last file recorded

RTSP_LastRecording_VideoFrameCount_int

GetInt()


Returns the video frame count of the last file recorded

RTSP_Filter_Version_int

SetInt()
GetInt()


Retuns the filter version number (READ ONLY)

RTSP_Filter_Build_int

SetInt()
GetInt()


Retuns the filter build number (READ ONLY)


43