Skip to content

Latest commit

 

History

History
1975 lines (1536 loc) · 76.2 KB

api-sink.md

File metadata and controls

1975 lines (1536 loc) · 76.2 KB

Sink API Reference

Sinks are the end components for all DSL GStreamer Pipelines. A Pipeline must have at least one sink in use, along with other certain components, to reach a state of Ready. DSL supports ten (12) different types of Sinks:

  • Overlay Sink - renders/overlays video on a Parent display (Jetson Platform Only)
  • Window Sink - renders/overlays video on a Parent XWindow
  • File Sink - encodes video to a media container file
  • Record Sink - similar to the File sink but with Start/Stop/Duration control and a cache for pre-start buffering.
  • RTSP Sink - streams encoded video on a specified port
  • WebRTC Sink - streams encoded video to a web browser or mobile application. (Requires GStreamer 1.18 or later)
  • Message Sink - converts Object Detection Event (ODE) metadata into a message payload and sends it to the server using a specified communication protocol.
  • Application Sink - allows the application to receive buffers or samples from a DSL Pipeline.
  • Interpipe Sink - allows pipeline buffers and events to flow to other independent pipelines, each with an Interpipe Source. Disabled by default, requires additional install/build steps.
  • Multi-Image Sink - encodes and saves video frames to JPEG files at specified dimensions and frame-rate.
  • Frame-Capture Sink - encodes and saves video frames to JPEG files on application/user demand. Disabled by default, requires additional install/build steps.
  • Fake Sink - consumes/drops all data.

Sink Construction and Destruction

Sinks are created by calling one of the type-specific constructors. As with all components, Sinks must be uniquely named from all other components created.

Sinks are added to a Pipeline by calling dsl_pipeline_component_add or dsl_pipeline_component_add_many and removed with dsl_pipeline_component_remove, dsl_pipeline_component_remove_many, or dsl_pipeline_component_remove_all.

The relationship between Pipelines and Sinks is one-to-many. Once added to a Pipeline, a Sink must be removed before it can be used with another. Sinks are deleted by calling dsl_component_delete, dsl_component_delete_many, or dsl_component_delete_all

Sink API

Types:

Callback Types:

Constructors:

Sink Methods

App Sink Methods

Render Sink Methods

Window Sink Methods

Encode Sink Methods

Smart-Record Sink Methods

RTSP Sink Methods

WebRTC Sink Methods

IOT Message Converter Sink Methods

Interpipe Sink Methods

Multi-Image Sink Methods

Frame-Capture Sink Methods

Return Values

The following return codes are used by the Sink API

#define DSL_RESULT_SINK_RESULT                                      0x00040000
#define DSL_RESULT_SINK_NAME_NOT_UNIQUE                             0x00040001
#define DSL_RESULT_SINK_NAME_NOT_FOUND                              0x00040002
#define DSL_RESULT_SINK_NAME_BAD_FORMAT                             0x00040003
#define DSL_RESULT_SINK_THREW_EXCEPTION                             0x00040004
#define DSL_RESULT_SINK_FILE_PATH_NOT_FOUND                         0x00040005
#define DSL_RESULT_SINK_IS_IN_USE                                   0x00040007
#define DSL_RESULT_SINK_SET_FAILED                                  0x00040008
#define DSL_RESULT_SINK_CODEC_VALUE_INVALID                         0x00040009
#define DSL_RESULT_SINK_CONTAINER_VALUE_INVALID                     0x0004000A
#define DSL_RESULT_SINK_COMPONENT_IS_NOT_SINK                       0x0004000B
#define DSL_RESULT_SINK_COMPONENT_IS_NOT_ENCODE_SINK                0x0004000C
#define DSL_RESULT_SINK_COMPONENT_IS_NOT_RENDER_SINK                0x0004000D
#define DSL_RESULT_SINK_OBJECT_CAPTURE_CLASS_ADD_FAILED             0x0004000E
#define DSL_RESULT_SINK_OBJECT_CAPTURE_CLASS_REMOVE_FAILED          0x0004000F
#define DSL_RESULT_SINK_HANDLER_ADD_FAILED                          0x00040010
#define DSL_RESULT_SINK_HANDLER_REMOVE_FAILED                       0x00040011
#define DSL_RESULT_SINK_PLAYER_ADD_FAILED                           0x00040012
#define DSL_RESULT_SINK_PLAYER_REMOVE_FAILED                        0x00040013
#define DSL_RESULT_SINK_MAILER_ADD_FAILED                           0x00040014
#define DSL_RESULT_SINK_MAILER_REMOVE_FAILED                        0x00040015
#define DSL_RESULT_SINK_OVERLAY_NOT_SUPPORTED                       0x00040016
#define DSL_RESULT_SINK_WEBRTC_CLIENT_LISTENER_ADD_FAILED           0x00040017
#define DSL_RESULT_SINK_WEBRTC_CLIENT_LISTENER_REMOVE_FAILED        0x00040018
#define DSL_RESULT_SINK_WEBRTC_CONNECTION_CLOSED_FAILED             0x00040019
#define DSL_RESULT_SINK_MESSAGE_CONFIG_FILE_NOT_FOUND               0x00040020
#define DSL_RESULT_SINK_COMPONENT_IS_NOT_MESSAGE_SINK               0x00040021

Codec Types

The following codec types are used by the Sink API

#define DSL_CODEC_H264                                              0
#define DSL_CODEC_H265                                              1

Video Container Types

The following video container types are used by the File Sink API

#define DSL_CONTAINER_MPEG4                                         0
#define DSL_CONTAINER_MK4                                           1

Smart Recording Events

#define DSL_RECORDING_EVENT_START                                   0
#define DSL_RECORDING_EVENT_END                                     1

Valid return values for the dsl_sink_app_new_data_handler_cb

#define DSL_FLOW_OK                                                 0
#define DSL_FLOW_EOS                                                1
#define DSL_FLOW_ERROR                                              2

Data types provided by the APP Sink

#define DSL_SINK_APP_DATA_TYPE_SAMPLE                               0
#define DSL_SINK_APP_DATA_TYPE_BUFFER                               1

WebRTC Connection States

Used by the WebRTC Sink to communicate its current state to listening clients

#define DSL_SOCKET_CONNECTION_STATE_CLOSED                          0
#define DSL_SOCKET_CONNECTION_STATE_INITIATED                       1
#define DSL_SOCKET_CONNECTION_STATE_OPENED                          2
#define DSL_SOCKET_CONNECTION_STATE_FAILED                          3

Message Converter Payload Schema Types

Defines the Payload schema types that can be used with the Message Sink

#define DSL_MSG_PAYLOAD_DEEPSTREAM                                  0
#define DSL_MSG_PAYLOAD_DEEPSTREAM_MINIMAL                          1

NVIDIA Installed Protocol Adapter Paths

The following -D flags are defined in the DSL Makefile

-DNVDS_AZURE_PROTO_LIB='L"$(LIB_INSTALL_DIR)/libnvds_azure_proto.so"' \
-DNVDS_AZURE_EDGE_PROTO_LIB='L"$(LIB_INSTALL_DIR)/libnvds_azure_edge_proto.so \
-DNVDS_AMQP_PROTO_LIB='L"$(LIB_INSTALL_DIR)/libnvds_amqp_proto.so \
-DNVDS_KAFKA_PROTO_LIB='L"$(LIB_INSTALL_DIR)/libnvds_kafka_proto.so \
-DNVDS_REDIS_PROTO_LIB='L"$(LIB_INSTALL_DIR)/libnvds_redis_edge_proto.so

Types:

dsl_recording_info

typedef struct dsl_recording_info
{
    uint recording_event;
    uint sessionId;
    const wchar_t* filename;
    const wchar_t* dirpath;
    uint64_t duration;
    uint containerType;
    uint width;
    uint height;
} dsl_recording_info;

Structure typedef used to provide recording session information provided to the client on callback

Fields

  • recording_event - specifies which recording event has occurred. One of DSL_RECORDING_EVENT_START or DSL_RECORDING_EVENT_END
  • sessionId - the unique sessions id assigned on record start
  • filename - filename generated for the completed recording. Null on recording start.
  • directory - path for the completed recording. Null on recording start.
  • duration - duration of the recording in milliseconds. 0 on recording start.
  • containerType - DSL_CONTAINER_MP4 or DSL_CONTAINER_MP4
  • width - width of the recording in pixels
  • height - height of the recording in pixels

Python Example

##
# Function to be called on recording start and complete
##
def recording_event_listener(session_info_ptr, client_data):
    print(' ***  Recording Event  *** ')
   
    session_info = session_info_ptr.contents
    print('event type: ', session_info.recording_event)
    print('session_id: ', session_info.session_id)
    print('filename:   ', session_info.filename)
    print('dirpath:    ', session_info.dirpath)
    print('duration:   ', session_info.duration)
    print('container:  ', session_info.container_type)
    print('width:      ', session_info.width)
    print('height:     ', session_info.height)

dsl_webrtc_connection_data

typedef struct _dsl_webrtc_connection_data
{
    uint current_state;

} dsl_webrtc_connection_data;

A structure typedef used to provide connection date for a given WebRTC Sink

Fields

  • current_state - the current state of the WebRTC Sink's WebSocket connection, one of the defined WebRTC Connection States.

Callback Types:

dsl_sink_app_new_data_handler_cb

typedef uint (*dsl_sink_app_new_data_handler_cb)(uint data_type, 
    void* data, void* client_data);

Callback typedef for the App Sink Component. The function is registered when the App Sink is created with dsl_sink_app_new. Once the Pipeline is playing, the function will be called when new data is available to process. The type of data is specified with the App Sink constructor.

Parameters

  • data_type [in] either DSL_SINK_APP_DATA_TYPE_SAMPLE or DSL_SINK_APP_DATA_TYPE_BUFFER. See App Sink data-types.
  • client_data [in] opaque pointer to client's user data, provided by the client.

Returns


dsl_record_client_listener_cb

typedef void* (*dsl_record_client_listener_cb)(void* info, void* user_data);

Callback typedef for clients to listen for a notification that a Recording Session has started or ended.

Parameters

  • info [in] opaque pointer to the connection info, see... see dsl_capture_info.
  • client_data [in] opaque pointer to client's user data, provided by the client.

dsl_sink_webrtc_client_listener_cb

typedef void (*dsl_sink_webrtc_client_listener_cb)(dsl_webrtc_connection_data* data,
    void* client_data);

Callback typedef for a client to listen for WebRTC Sink connection events.

IMPORTANT: The WebRTC Sink implementation requires GStreamer 1.18 or later.

Parameters

  • info [in] opaque pointer to the session info, see dsl_webrtc_connection_data.
  • client_data [in] opaque pointer to client's user data, provided by the client.

Constructors

dsl_sink_app_new

DslReturnType dsl_sink_app_new(const wchar_t* name, uint data_type,
    dsl_sink_app_new_data_handler_cb client_handler, void* client_data);

The constructor creates a new, uniquely named App Sink component. Construction will fail if the name is currently in use.

Hierarchy

component
 ╰── sink
    ╰── app sink

Parameters

  • name - [in] unique name for the App Sink to create.
  • data_type - [in] either DSL_SINK_APP_DATA_TYPE_SAMPLE or DSL_SINK_APP_DATA_TYPE_BUFFER. See App Sink data-types.
  • client_handler - [in] client callback function to be called with each new buffer received.
  • client_data [in] opaque pointer to client data returned on callback to the client_handler function.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_app_new('my-app-sink', DSL_SINK_APP_DATA_TYPE_BUFFER,
    my_data_handler, NULL)

dsl_sink_overlay_new

DslReturnType dsl_sink_overlay_new(const wchar_t* name, uint display_id,
    uint depth, uint offset_x, uint offset_y, uint width, uint height);

The constructor creates a uniquely named Overlay Sink with given offsets and dimensions. Construction will fail if the name is currently in use.

IMPORTANT: The Overlay Sink is only available on the Jetson platform.

Hierarchy

component
 ╰── sink
    ╰── render sink
       ╰── overlay sink

Parameters

  • name - [in] unique name for the Overlay Sink to create.
  • display_id - [in] display Id to overlay, 0 = main display.
  • depth - [in] depth of the overlay for the given display Id.
  • x_offset - [in] offset in the X direction from the upper left corner of the display in pixels.
  • y_offset - [in] offset in the Y direction from the upper left corner of the display in pixels.
  • width - [in] width of the Overlay Sink in pixels.
  • height - [in] height of the Overlay Sink in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_overlay_new('my-overlay-sink', 0, 0, 200, 100, 1280, 720)

dsl_sink_window_new

DslReturnType dsl_sink_window_new(const wchar_t* name,
    uint x_offset, uint y_offset, uint width, uint height);

The constructor creates a uniquely named Window Sink with given offsets and dimensions. Construction will fail if the name is currently in use. Window Sinks are used to render video onto an XWindows. See Pipeline XWindow Support for more information.

Hierarchy

component
 ╰── sink
    ╰── render sink
       ╰── window sink

Parameters

  • name - [in] unique name for the Window Sink to create.
  • x_offset - [out] offset in the X direction in pixels from the upper left most corner of the parent XWindow.
  • y_offset - [out] offset in the Y direction in pixels from the upper left most corner of the parent XWindow.
  • width - [in] width of the Window Sink in pixels.
  • height - [in] height of the Window Sink in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_window_new('my-window-sink', 0, 0, 1280, 720)

dsl_sink_file_new

DslReturnType dsl_sink_file_new(const wchar_t* name, const wchar_t* filepath,
     uint codec, uint container, uint bit_rate, uint interval);

The constructor creates a uniquely named File Sink. Construction will fail if the name is currently in use. There are two Codec formats - H.264 and H.265 - and two video container types - MPEG4 and MK4 - supported.

Hierarchy

component
 ╰── sink
    ╰── encode sink
       ╰── file sink

Parameters

  • name - [in] unique name for the File Sink to create.
  • filepath - [in] absolute or relative filespec for the media file to write to.
  • codec - [in] one of the Codec Types defined above.
  • container - [in] one of the Video Container Types defined above.
  • bitrate - [in] bitrate at which to encode the video. Set to 0 to use the encoder's default (4Mbps).
  • interval - [in] frame interval at which to code the video. Set to 0 to code every frame.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_file_new('my-file-sink', './my-video.mp4', DSL_CODEC_H264, DSL_CONTAINER_MPEG, 0, 0)

dsl_sink_record_new

DslReturnType dsl_sink_record_new(const wchar_t* name, const wchar_t* outdir, uint codec,
    uint container, uint bitrate, uint interval, dsl_record_client_listener_cb  client_listener);

The constructor creates a uniquely named Record Sink. Construction will fail if the name is currently in use. There are two Codec formats - H.264 and H.265 - and two video container types - MPEG4 and MK4 - supported.

Note: the Sink name is used as the filename prefix, followed by session id and NTP time.

Hierarchy

component
 ╰── sink
    ╰── encode sink
       ╰── record sink

Parameters

  • name - [in] unique name for the Record Sink to create.
  • outdir - [in] absolute or relative pathspec for the directory to save the recorded video streams.
  • codec - [in] one of the Codec Types defined above.
  • container - [in] one of the Video Container Types defined above.
  • bitrate - [in] bitrate at which to encode the video. Set to 0 to use the encoder's default (4Mbps).
  • interval - [in] frame interval at which to encode the video. Set to 0 to code every frame.
  • client_listener - [in] client callback function of type dsl_record_client_listener_cb to be called when a [Recording Event}(#smart-recording-events) occurs.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_new('my-record-sink',
    './', DSL_CODEC_H265, DSL_CONTAINER_MPEG, 0, 0, my-client-recording-event-cb)

dsl_sink_rtsp_new

DslReturnType dsl_sink_rtsp_new(const wchar_t* name, const wchar_t* host,
     uint udp_port, uint rtmp_port, uint codec, uint bitrate, uint interval);

The constructor creates a uniquely named RTSP Sink. Construction will fail if the name is currently in use. There are two Codec formats - H.264 and H.265 - supported. The RTSP server is configured when the Pipeline is called to Play. The server is then started and attached to the g-main-loop context once dsl_main_loop_run is called. Once attached, the server can accept connections.

Important Note: the URI is derived from the device identification, rtmp_port, and server mount point which is derived from the unique RTSP Sink name,

When the client and DSL application are both running locally:

rtsp://<device-name>.local:<rtmp-port-number>/<rtsp-sink-name>

for example:

rtsp://my-jetson-device.local:8554/my-rtsp-sink

When the client is running remotely from the DSL application:

rtsp://<user-name>:<password>@<ip-address>:<rtmp-port-number>/<rtsp-sink-name>

for example:

rtsp://admin:[email protected]:8554/my-rtsp-sink

Hierarchy

component
 ╰── sink
    ╰── encode sink
       ╰── rtsp sink

Parameters

  • name - [in] unique name for the File Sink to create.
  • host - [in] host name
  • udp_port - [in] UDP port setting for the RTSP server.
  • rtsp_port - [in] RTSP port setting for the server.
  • codec - [in] one of the Codec Types defined above.
  • bitrate - [in] bitrate at which to encode the video. Set to 0 to use the encoder's default (4Mbps).
  • interval - [in] frame interval at which to encode the video. Set to 0 to code every frame.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

 retVal = dsl_sink_rtsp_new('rtsp-sink', host_uri, 5400, 8554, DSL_CODEC_H264, 4000000,0)

dsl_sink_webrtc_new

DslReturnType dsl_sink_webrtc_new(const wchar_t* name, const wchar_t* stun_server,
    const wchar_t* turn_server, uint codec, uint bitrate, uint interval);

The constructor creates a uniquely named WebRTC Sink. Construction will fail if the name is currently in use. There are two Codec formats - H.264 and H.265. The WebRTC Sink Implements a Signaling Transceiver which is automatically added and removed from the WebSocket Server when added and removed from a Pipeline or Branch. Refer to the WebSocket Server API Reference for more information.

IMPORTANT: The WebRTC Sink implementation requires GStreamer 1.18 or later.

Hierarchy

component
 ╰── sink
    ╰── encode sink
       ╰── webrtc sink

Parameters

  • name - [in] unique name for the WebRTC Sink to create.
  • stun_server - [in] STUN server to use - of the form stun://hostname:port. Set to NULL to omit if using TURN server(s).
  • turn_server - [in] TURN server(s) to use - of the form turn(s)://username:password@host:port. Set to NULL to omit if using a STUN server.
  • codec - [in] one of the Codec Types defined above.
  • bitrate - [in] bitrate at which to encode the video. Set to 0 to use the encoder's default (4Mbps).
  • interval - [in] frame interval at which to encode the video. Set to 0 to code every frame.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

STUN_SERVER = "stun://stun.l.google.com:19302"
retval = dsl_sink_webrtc_new('my-webrtc-sink', STUN_SERVER, DSL_CODEC_H264, 0, 0)

dsl_sink_message_new

DslReturnType dsl_sink_message_new(const wchar_t* name,
    const wchar_t* converter_config_file, uint payload_type,
    const wchar_t* broker_config_file, const wchar_t* protocol_lib,
    const wchar_t* connection_string, const wchar_t* topic);

The constructor creates a uniquely named Message Sink. Construction will fail if the name is currently in use. The Message Sink converts ODE metadata -- generated by an Add Message Meta ODE Action -- into a message payload and sends it to the server using a specified communication protocol.

Important: refer to the DeepStream Plugin Guide for information on the Message Converter and Message Broker, and for information on configuration and use of the different Protocol Adapters.

Note: refer to DSL Message Broker API reference and DSL - Azure MQTT Protocol Adapter Libraries for additional information.

Hierarchy

component
 ╰── sink
    ╰── message sink

Parameters

  • name - [in] unique name for the Message Sink to create.
  • converter_config_file - [in] absolute or relative path to a message-converter configuration file of type text or csv.
  • payload_type - [in] one of the Message Converter payload schema type constants defined above.
  • broker_config_file - [in] broker_config_file absolute or relative path to a message-broker configuration file required by nvds_msgapi_* interface.
  • protocol_lib - [in] absolute or relative path to the protocol adapter that implements the nvds_msgapi_* interface. See the NVIDIA Installed Protocol Adapter Paths defined above.
  • connection_string - [in] endpoint for communication with server of the format <name>;<port>;<specifier>
  • topic - [in] (optional) message topic for each message sent to the server.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

CONNECTION_STRING = 'HostName=my-hub.azure-devices.net;DeviceId=nano-1;SharedAccessKey=abcd1234EFGH5678ijkl'
retval = dsl_sink_message_new('my-message-sink', converter_config_file, DSL_MSG_PAYLOAD_DEEPSTREAM,
    broker_config_file, NVDS_AZURE_PROTO_LIB, CONNECTION_STRING, '/ode/data')

dsl_sink_interpipe_new

DslReturnType dsl_sink_interpipe_new(const wchar_t* name,
    boolean forward_eos, boolean forward_events);

The constructor creates a new, uniquely named Inter-Pipe Sink component. Construction will fail if the name is currently in use.

Important! The Interpipe Services are disabled by default and require additional install/build steps.

Refer to the Interpipe Services overview for more information.

Hierarchy

component
 ╰── sink
    ╰── interpipe sink

Parameters

  • name - [in] unique name for the Interpipe Sink to create.
  • forward_eos - [in] set to true to forward the EOS event to all listeners. False to not forward.
  • forward_events - [in] set to true to forward downstream events to all listeners (except for EOS). False to not forward.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

retVal = dsl_sink_interpipe_new('my-interpipe-sink',
    True, True)

dsl_sink_image_multi_new

DslReturnType dsl_sink_image_multi_new(const wchar_t* name, 
    const wchar_t* file_path, uint width, uint height,
    uint fps_n, uint fps_d);

The constructor creates a new, uniquely named Multi-Image Sink. Construction will fail if the name is currently in use.

The Sink Encodes each frame into a JPEG image and saves it to a file specified by a given folder/filename-pattern. The size can be scaled by setting the width and height to non-zero values. The rate can be controlled by setting the fps_n and fps_d to non-zero values as well. The maximum rate at which the sink can encode and save is hardware/platform dependent. It is up to the user to manage the maximum setting. Exceeding the limit may lead to corrupted files.

Hierarchy

component
 ╰── sink
    ╰── multi-image sink

Parameters

  • name - [in] unique name for the Multi-Image Sink to create.
  • file_path - [in] use the printf style %d in the absolute or relative path. Example: "./my_images/image.%04d.jpg", will create files in "./my_images/" named "image.0000.jpg", "image.0001.jpg", "image.0002.jpg" etc.
  • width - [in] width of the images to save in pixels. Set to 0 for no transcode.
  • height - [in] height of the images to save in pixels. Set to 0 for no transcode.
  • fps_n - [in] fps_n frames/second fraction numerator. Set to 0 for no rate-change.
  • fps_d - [in] fps_d frames/second fraction denominator. Set to 0 for no rate-change.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

retVal = dsl_sink_image_multi_new('my-multi-image-sink',
    './frame_%04d.jpg', 640, 360, 1, 10)

dsl_sink_frame_capture_new

DslReturnType dsl_sink_frame_capture_new(const wchar_t* name, 
    const wchar_t* frame_capture_action);

The constructor creates a new, uniquely named Frame-Capture Sink. Construction will fail if the name is currently in use. The Sink is created with an ODE Frame-Capture Action which performs the image encoding and saving. All captured frames are copied and buffered in the Sink's processing thread. The encoding and saving of each buffered frame is done in the g-idle-thread context.

The Application initiates a frame-capture by calling dsl_sink_frame_capture_initiate.

Capture-complete-listeners (to notify on completion), Image Players (to auto-play the new image) and SMTP Mailers (to mail the new image) can be added to the Capture Action as well.

Important! The Frame-Captre Sink Services are disabled by default and require additional install/build steps to use.

Note: The first capture may cause a noticeable short pause to the stream while cuda dependencies are loaded and cached.

Hierarchy

component
 ╰── sink
    ╰── frame-capture sink

Parameters

  • name - [in] unique name for the Frame-Capture Sink to create.
  • frame_capture_action - [in] unique name of the ODE Frame-Capture Action to use.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

retVal = dsl_sink_frame_capture_new('my-frame-capture-sink',
    'my-frame-capture-action')

dsl_sink_fake_new

DslReturnType dsl_sink_fake_new(const wchar_t* name);

The constructor creates a uniquely named Fake Sink. Construction will fail if the name is currently in use.

Hierarchy

component
 ╰── sink
    ╰── fake sink

Parameters

  • name - [in] unique name for the Fake Sink to create.

Returns

  • DSL_RESULT_SUCCESS on successful creation. One of the Return Values defined above on failure.

Python Example

retVal = dsl_sink_fake_new('my-fake-sink')

Destructors

As with all Pipeline components, Sinks are deleted by calling dsl_component_delete, dsl_component_delete_many, or dsl_component_delete_all.


Sink Methods

dsl_sink_sync_enabled_get

DslReturnType dsl_sink_sync_enabled_get(const wchar_t* name, boolean* enabled);

This service gets the current sync enabled setting in use by the named Sink.

Parameters

  • name - [in] unique name of the Sink to query.
  • enabled - [out] true if the sync setting for the name Sink is enabled, false otherwise.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, enabled = dsl_sink_sync_enabled_get('my-overlay-sink')

dsl_sink_sync_enabled_set

DslReturnType dsl_sink_sync_enabled_set(const wchar_t* name, boolean enabled);

This service sets the sync enabled setting in for the named Sink.

Parameters

  • name - [in] unique name of the Message Sink to update.
  • enabled - [in] set to true to enable the sync setting, false to disable.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_sync_enabled_set('my-overlay-sink', false)

dsl_sink_pph_add

DslReturnType dsl_sink_pph_add(const wchar_t* name, const wchar_t* handler);

This service adds a Pad-Probe-Handler (PPH) to the sink pad of the Named Sink component. The PPH will be invoked on every buffer-ready event for the sink pad. More than one PPH can be added to a single Sink Component.

Parameters

  • name [in] unique name of the Tee to update.
  • handler [in] unique name of the PPH to add.

Returns

  • DSL_RESULT_SUCCESS on successful add. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_pph_add('my-window-sink', 'my-meter-pph')

dsl_sink_pph_remove

DslReturnType dsl_sink_pph_remove(const wchar_t* name, const wchar_t* handler);

This service removes a Pad-Probe-Handler from a named Sink

Parameters

  • name [in] unique name of the Sink to update.
  • handler [in] unique name of the Pad probe handler to remove.

Returns

  • DSL_RESULT_SUCCESS on successful remove. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_pph_remove('my-window-sink', 'my-meter-pph')

dsl_sink_app_data_type_get

DslReturnType dsl_sink_app_data_type_get(const wchar_t* name, uint* data_type);

This service gets the current data-type setting in use by a named App Sink Component.

Parameters

  • name - [in] unique name of the App Sink to query.
  • data_type - [out] either DSL_SINK_APP_DATA_TYPE_SAMPLE or DSL_SINK_APP_DATA_TYPE_BUFFER. See App Sink data-types.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, data_type = dsl_sink_app_data_type_get('my-app-sink')

App Sink Methods

dsl_sink_app_data_type_set

DslReturnType dsl_sink_app_data_type_set(const wchar_t* name, uint data_type);

This service sets the data-type setting for the named App Sink Component to use.

Parameters

  • name - [in] unique name of the App Sink to update.
  • data_type - [in] either DSL_SINK_APP_DATA_TYPE_SAMPLE or DSL_SINK_APP_DATA_TYPE_BUFFER. See App Sink data-types.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_app_data_type_set('my-app-sink', DSL_SINK_APP_DATA_TYPE_BUFFER)

Render Sink Methods

dsl_sink_render_offsets_get

DslReturnType dsl_sink_render_offsets_get(const wchar_t* name,
    uint* x_offset, uint* y_offsetY);

This service returns the current X and Y offsets for the named Render Sink; Overlay or Window.

Parameters

  • name - [in] unique name of the Render Sink to query.
  • x_offset - [out] offset in the X direction in pixels from the upper left most corner of the sink's parent.
  • y_offset - [out] offset in the Y direction in pixels from the upper left most corner of the sink's parent.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, x_offset, y_offset = dsl_sink_render_offsets_get('my-overlay-sink')

dsl_sink_render_offsets_set

DslReturnType dsl_sink_render_offsets_set(const wchar_t* name,
    uint x_offset, uint y_offset);

This service updates the X and Y offsets of a named Render Sink; Overlay or Window. Note: this service will fail if the Sink is currently linked.

Parameters

  • name - [in] unique name of the Render Sink to update.
  • x_offset - [in] new offset in the X direction in pixels from the upper left most corner of the sink's parent.
  • y_offset - [in] new offset in the Y direction in pixels from the upper left most corner of the sink's parent.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_render_offests_set('my-overlay-sink', 100, 100)

dsl_sink_render_dimensions_get

DslReturnType dsl_sink_render_dimensions_get(const wchar_t* name,
    uint* width, uint* height);

This service returns the current dimensions for the named Render Sink; Overlay or Window

Parameters

  • name - [in] unique name of the Render Sink to query.
  • width - [out] current width of the Render Sink in pixels.
  • height - [out] current height of the Render Sink in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure

Python Example

retval, width, height = dsl_sink_render_dimensions_get('my-overlay-sink')

dsl_sink_render_dimensions_set

DslReturnType dsl_sink_render_dimensions_set(const wchar_t* name,
    uint width, uint height);

This service updates the dimensions of a named Render Sink; Overlay or Window. This service will fail if the Sink is currently linked.

Parameters

  • name - [in] unique name of the Overlay Sink to update.
  • width - [in] new width setting for the Render Sink in pixels.
  • height - [in] new height setting for the Render Sink in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_render_dimensions_set('my-overlay-sink', 1280, 720)

Window Sink Methods

dsl_sink_window_force_aspect_ratio_get

DslReturnType dsl_sink_window_force_aspect_ratio_get(const wchar_t* name,
    boolean* force);

This service returns the force-aspect-ratio property setting for the named Window Sink. The Sink's aspect ratio will be maintained on Window resize if set.

Parameters

  • name - [in] unique name of the Window Sink to query.
  • force - [out] true if the property is set, false otherwise.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, force = dsl_sink_window_force_aspect_ratio_get('my-window-sink')

dsl_sink_window_force_aspect_ratio_set

DslReturnType dsl_sink_window_force_aspect_ratio_set(const wchar_t* name,
    boolean force);

This service sets the force-aspect-ratio property for the named Window Sink. The Sink's aspect ratio will be maintained on Window resize if set. This service will fail if the Sink is currently linked.

Parameters

  • name - [in] unique name of the Window Sink to update.
  • force - [in] set true to force the aspect ratio on window resize., false otherwise.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_window_force_aspect_ratio_get('my-window-sink', True)

Encode Sink Methods

dsl_sink_encode_settings_get

DslReturnType dsl_sink_encode_settings_get(const wchar_t* name,
    uint* codec, uint* bitrate, uint* interval);

This service returns the current bitrate and interval settings for the named Encode Sink; File, Record, RTSP OR WebRTC.

Parameters

  • name - [in] unique name of the Encode Sink to query.
  • codec - [out] current codec in use, one of the Codec Types defined above.
  • bitrate - [out] current bit rate at which to code the video.
  • interval - [out] current frame interval at which to encode the video. 0 equals code every frame

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, bitrate, interval = dsl_sink_encode_settings_get('my-file-sink')

dsl_sink_encode_settings_set

DslReturnType dsl_sink_encode_settings_set(const wchar_t* name,
    uint codec, uint bitrate, uint interval);

This service sets the bitrate and interval settings for the named Encode Sink; File, Record, RTSP OR WebRTC. The service will fail if the Encode Sink is currently linked.

Parameters

  • name - [in] unique name of the Encode Sink to update.
  • codec - [in] new codec to use, one of the Codec Types defined above.
  • bitrate - [in] bitrate at which to encode the video. Set to 0 to use the encoder's default (4Mbps).
  • interval - [in] new frame interval at which to encode the video. Set to 0 to code every frame.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_encode_settings_set('my-file-sink', 4000000, 1)

dsl_sink_encode_dimensions_get

DslReturnType dsl_sink_encode_dimensions_get(const wchar_t* name, 
    uint* width, uint* height);

This service gets the current input dimensions for the named Encode Sink; File, Smart-Record, RTSP, or WebRTC. Values of 0 indicate NO scaling.

The dimensions, if non-zero, are used to scale the video input into the Sinks's encoder element.

Parameters

  • name - [in] unique name of the Encode Sink to query.
  • width - [out] current width of the Encode Sink input in pixels.
  • height - [out] current height of the Encode Sink input pixels.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure

Python Example

retval, width, height = dsl_sink_encode_dimensions_get('my-rtsp-sink')

dsl_sink_encode_dimensions_set

DslReturnType dsl_sink_encode_dimensions_set(const wchar_t* name, 
    uint width, uint height);

This service updates the dimensions of a named Encode Sink; File, Smart-Record, RTSP, or WebRTC. Set the values to 0 to indicate NO scaling.

Parameters

  • name - [in] unique name of the Overlay Sink to update.
  • width - [in] new width setting for the Encode Sink in pixels.
  • height - [in] new height setting for the Encode Sink in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_encode_dimensions_set('my-rtsp-sink', 1280, 720)

Smart-Record Sink Methods

dsl_sink_record_session_start

DslReturnType dsl_sink_record_session_start(const wchar_t* name,
    uint start, uint duration, void* client_data);

This service starts a new recording session for the named Record Sink

Parameters

  • name [in] unique name of the Record Sink to start the session.
  • start [in] start time in seconds before the current time should be less than the video cache size.
  • duration [in] in seconds from the current time to record.
  • client_data [in] opaque pointer to client data returned on callback to the client listener function provided on Sink creation.

Returns

  • DSL_RESULT_SUCCESS on successful start. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_session_start('my-record-sink', 15, 900, None)

dsl_sink_record_session_stop

DslReturnType dsl_sink_record_session_stop(const wchar_t* name);

This service stops a current recording in session.

Parameters

  • name [in] unique name of the Record Sink to stop.

Returns

  • DSL_RESULT_SUCCESS on successful Stop. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_session_stop('my-record-sink')

dsl_sink_record_outdir_get

DslReturnType dsl_sink_record_outdir_get(const wchar_t* name, const wchar_t** outdir);

This service returns the video recording output directory.

Parameters

  • name [in] name of the Record Sink to query.
  • outdir - [out] absolute pathspec for the directory to save the recorded video streams.

Returns

  • DSL_RESULT_SUCCESS on successful Query. One of the Return Values defined above on failure.

Python Example

retval, outdir = dsl_sink_record_outdir_get('my-record-sink')

dsl_sink_record_outdir_set

DslReturnType dsl_sink_record_outdir_set(const wchar_t* name, const wchar_t* outdir);

This service sets the video recording output directory.

Parameters

  • name [in] name of the Record Sink to update.
  • outdir - [in] absolute or relative pathspec for the directory to save the recorded video streams.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_outdir_set('my-record-sink', './recordings')

dsl_sink_record_container_get

DslReturnType dsl_sink_record_container_get(const wchar_t* name, uint* container);

This service returns the media container type used when recording.

Parameters

  • name [in] name of the Record Sink to query.
  • container - [out] one of the Video Container Types defined above.

Returns

  • DSL_RESULT_SUCCESS on successful Query. One of the Return Values defined above on failure.

Python Example

retval, container_type = dsl_sink_record_container_get('my-record-sink')

dsl_sink_record_container_set

DslReturnType dsl_sink_record_container_set(const wchar_t* name,  uint container);

This service sets the media container type to use when recording.

Parameters

  • name [in] name of the Record Sink to update.
  • container - [in] on of the Video Container Types defined above.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_container_set('my-record-sink', DSL_CONTAINER_MP4)

dsl_sink_record_cache_size_get

DslReturnType dsl_sink_record_cache_size_get(const wchar_t* name, uint* cache_size);

This service returns the video recording cache size in units of seconds. A fixed size cache is created when the Pipeline is linked and played. The default cache size is set to DSL_DEFAULT_VIDEO_RECORD_CACHE_IN_SEC.

Parameters

  • name [in] name of the Record Sink to query.
  • cache_size [out] current cache size setting.

Returns

  • DSL_RESULT_SUCCESS on successful Query. One of the Return Values defined above on failure.

Python Example

retval, cache_size = dsl_sink_record_cache_size_get('my-record-sink')

dsl_sink_record_cache_size_set

DslReturnType dsl_sink_record_cache_size_set(const wchar_t* name, uint cache_size);

This service sets the video recording cache size in units of seconds. A fixed size cache is created when the Pipeline is linked and played. The default cache size is set to DSL_DEFAULT_VIDEO_RECORD_CACHE_IN_SEC.

Parameters

  • name [in] name of the Record Sink to query.
  • cache_size [in] new cache size setting to use on Pipeline play.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_cache_size_set('my-record-sink', 15)

dsl_sink_record_dimensions_get

DslReturnType dsl_sink_record_dimensions_get(const wchar_t* name, uint* width, uint* height);

This service returns the dimensions, width and height, used for the video recordings. Values of zero (default) indicate no-transcode.

Parameters

  • name[in] name of the Record Sink to query.
  • width[out] current width of the video recording in pixels.
  • height [out] current height of the video recording in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, width, height = dsl_sink_record_dimensions_get('my-record-sink')

dsl_sink_record_dimensions_set

DslReturnType dsl_sink_record_dimensions_set(const wchar_t* name, uint width, uint height);

This service sets the dimensions, width and height, for the video recordings created. Values of zero (default) indicate no-transcode.

Parameters

  • name [in] name of the Record Sink to update.
  • width [in] width to set the video recording in pixels.
  • height [in] height to set the video in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_dimensions_set('my-record-sink', 1280, 720)

dsl_sink_record_is_on_get

DslReturnType dsl_sink_record_is_on_get(const wchar_t* name, boolean* is_on);

This service returns the current recording state of the Record Sink.

Parameters

  • name [in] name of the Record Sink to query.
  • is_on [out] true if the Record Sink is currently recording a session, false otherwise.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, is_on = dsl_sink_record_is_on_get('my-record-sink')

dsl_sink_record_reset_done_get

DslReturnType dsl_sink_record_reset_done_get(const wchar_t* name, boolean* reset_done);

This service returns the current state of the Reset Done flag.

Parameters

  • name [in] name of the Record Sink to query.
  • reset_done [out] true if Reset has been done, false otherwise.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, reset_done = dsl_sink_record_reset_done_get('my-record-sink')

dsl_sink_record_video_player_add

DslReturnType dsl_sink_record_video_player_add(const wchar_t* name,
    const wchar_t* player)

This service adds a Video Player, Render or RTSP type, to a named Recording Sink. Once added, each recorded video's file_path will be added (or queued) with the Video Player to be played according to the Players settings.

Parameters

  • name [in] name of the Record Sink to update.
  • player [in] name of the Video Player to add.

Returns

  • DSL_RESULT_SUCCESS on successful add. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_video_player_add('my-record-sink, 'my-video-render-player')

dsl_sink_record_video_player_remove

DslReturnType dsl_sink_record_video_player_remove(const wchar_t* name,
    const wchar_t* player)

This service removes a Video Player, Render or RTSP type, from a named Recording Sink.

Parameters

  • name [in] name of the Record Sink to update
  • player [in] player name of the Video Player to remove

Returns

  • DSL_RESULT_SUCCESS on successful remove. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_video_player_remove('my-record-sink', 'my-video-render-player'

dsl_sink_record_mailer_add

DslReturnType dsl_sink_record_mailer_add(const wchar_t* name,
    const wchar_t* mailer, const wchar_t* subject);

This service adds a Mailer to a named Recording Sink. Once added, the file_name, location, and specifics of each recorded video will be emailed by the Mailer according to its current settings.

Parameters

  • name [in] name of the Record Sink to update.
  • mailer [in] name of the Mailer to add.
  • subject [in] subject line to use for all outgoing mail.

Returns

  • DSL_RESULT_SUCCESS on successful add. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_mailer_add('my-record-sink, 'my-mailer', "New Recording Complete!")

dsl_sink_record_mailer_remove

DslReturnType dsl_sink_record_mailer_remove(const wchar_t* name,
    const wchar_t* mailer)

This service removes a Mailer from a named Recording Sink.

Parameters

  • name [in] name of the Record Sink to update.
  • mailer [in] name of the Mailer to remove.

Returns

  • DSL_RESULT_SUCCESS on successful remove. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_record_mailer_remove('my-record-sink', 'my-mailer')

RTSP Sink Methods

dsl_sink_rtsp_server_settings_get

This service returns the current RTSP video codec and Port settings for the named RTSP Sink.

DslReturnType dsl_sink_rtsp_server_settings_get(const wchar_t* name,
    uint* udp_port, uint* rtsp_port);

Parameters

  • name - [in] unique name of the RTSP Sink to query.
  • udp_port - [out] the current UDP Port number in use.
  • rtsp_port - [out] the current RTSP Port number in use.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, udp_port, rtsp_port = dsl_sink_rtsp_server_settings_get('my-rtsp-sink')

WebRTC Sink Methods

dsl_sink_webrtc_connection_close

DslReturnType dsl_sink_webrtc_connection_close(const wchar_t* name);

This service closes a currently open WebSocket connection for the named WebRTC Sink.

IMPORTANT: The WebRTC Sink implementation requires GStreamer 1.18 or later.

Parameters

  • name [in] unique name of the WebRTC Sink to update.

Returns DSL_RESULT_SUCCESS on successful close. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_webrtc_connection_close('my-webrtc-sink')

dsl_sink_webrtc_servers_get

DslReturnType dsl_sink_webrtc_servers_get(const wchar_t* name,
    const wchar_t** stun_server, const wchar_t** turn_server);

This service queries a named WebRTC Sink component for its current STUN or TURN server(s) in use.

IMPORTANT: The WebRTC Sink implementation requires DS 1.18.0 or later.

Parameters

  • name [in] unique name of the WebRTC Sink to query.
  • stun_server [out] current STUN server in use, NULL if omitted.
  • turn_server [out] current TURN server in use, NULL if omitted.

Returns DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, stun_server, turn_server = dsl_sink_webrtc_servers_get('my-webrtc-sink')

dsl_sink_webrtc_servers_set

DslReturnType dsl_sink_webrtc_servers_set(const wchar_t* name,
    const wchar_t* stun_server, const wchar_t* turn_server);

This service updates a named WebRTC Sink component with either a new STUN or TURN server(s) to use.

IMPORTANT: The WebRTC Sink implementation requires GStreamer 1.18 or later.

Parameters

  • name [in] unique name of the WebRTC Sink to query.
  • stun_server - [in] STUN server to use - of the form stun://hostname:port. Set to NULL to omit if using TURN server(s).
  • turn_server - [in] TURN server(s) to use - of the form turn(s)://username:password@host:port. Set to NULL to omit if using a STUN server.

Returns DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_webrtc_servers_get('my-webrtc-sink', NULL, turn_server)

dsl_sink_webrtc_client_listener_add

DslReturnType dsl_sink_webrtc_client_listener_add(const wchar_t* name,
    dsl_sink_webrtc_client_listener_cb listener, void* client_data);

This service adds a callback function of type dsl_sink_webrtc_client_listener_cb to the WebRTC Sink. The function will be called on all changes of WebSocket connection state. Multiple callback functions can be added to the WebRTC Sink.

IMPORTANT: The WebRTC Sink implementation requires GStreamer 1.18 or later.

Parameters

  • name [in] unique name of the WebRTC Sink to update.
  • listener - [in] listener callback function to add.
  • client_data - [in] opaque pointer to user data, returned to the listener on call back

Returns DSL_RESULT_SUCCESS on successful add. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_webrtc_client_listener_add('my-webrtc-sink', client_listener_cb, None)

dsl_sink_webrtc_client_listener_remove

DslReturnType dsl_sink_webrtc_client_listener_remove(const wchar_t* name,
    dsl_sink_webrtc_client_listener_cb listener);

This service removes a callback function of type dsl_sink_webrtc_client_listener_cb from the WebRTC Sink.

IMPORTANT: The WebRTC Sink implementation requires GStreamer 1.18 or later.

Parameters

  • name [in] unique name of the WebRTC Sink to update.
  • listener - [in] listener callback function to remove.

Returns

  • DSL_RESULT_SUCCESS on successful removal. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_webrtc_client_listener_remove('my-webrtc-sink', client_listener_cb)

IOT Message Converter Sink Methods

dsl_sink_message_converter_settings_get

DslReturnType dsl_sink_message_converter_settings_get(const wchar_t* name,
    const wchar_t** converter_config_file, uint* payload_type);

This service gets the current Message Converter settings in use by the named Message Sink.

Important refer to the Deepstream Plugin Guide for information on the Message Converter configuration file settings.

Parameters

  • name - [in] unique name of the Encode Sink to query.
  • converter_config_file - [out] absolute file-path to the current Message Converter config file in use.
  • payload_type - [out] the current payload schema type in use, one of the Message Converter payload schema type constants defined above.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, converter_config_file, payload_type = dsl_sink_message_converter_settings_get('my-message-sink')

dsl_sink_message_converter_settings_set

DslReturnType dsl_sink_message_converter_settings_set(const wchar_t* name,
    const wchar_t* converter_config_file, uint payload_type);

This service sets the Message Converter settings to be used by the named Message Sink.

Important refer to the DeepStream Plugin Guide for information on the Message Converter configuration file settings.

Parameters

  • name - [in] unique name of the Encode Sink to update.
  • converter_config_file - [in] relative or absolute file-path to a Message Converter config file to use.
  • payload_type - [in] the current payload schema type in use, one of the Message Converter payload schema type constants defined above.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_message_converter_settings_get('my-message-sink',
    converter_config_file, DSL_MSG_PAYLOAD_DEEPSTREAM)

dsl_sink_message_broker_settings_get

DslReturnType dsl_sink_message_broker_settings_get(const wchar_t* name,
    const wchar_t** broker_config_file, const wchar_t** protocol_lib,
    const wchar_t** connection_string, const wchar_t** topic);

This service gets the current Message Broker settings in use by the named Message Sink.

Important refer to the DeepStream Plugin Guide for information on the Message Broker configuration file and connection string, and for information on configuration and use of the different Protocol Adapters.

Parameters

  • name - [in] unique name of the Message Sink to query.
  • broker_config_file - [out] absolute file-path to the current Message Broker config file in use.
  • protocol_lib - [out] absolute file-path to the current protocol adapter library in use.
  • connection_string - [out] current connection string in use.
  • topic - [out] (optional) current message topic in use.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, broker_config_file, protocol_lib, connection_string, topic =
        dsl_sink_message_broker_settings_get('my-message-sink')

dsl_sink_message_broker_settings_set

DslReturnType dsl_sink_message_broker_settings_set(const wchar_t* name,
    const wchar_t* broker_config_file, const wchar_t* protocol_lib,
    const wchar_t* connection_string, const wchar_t* topic);

This service sets the Message Broker settings to be used by the named Message Sink.

Important refer to the DeepStream Plugin Guide for information on the Message Broker configuration file and connection string, and for information on configuration and use of the different Protocol Adapters.

Parameters

  • name - [in] unique name of the Message Sink to update.
  • broker_config_file - [in] absolute or relative file-path to a new Message Broker config file to use.
  • protocol_lib - [in] absolute or relative file-path to a new protocol adapter library to use.
  • connection_string - [in] new connection string to use.
  • topic - [in] (optional) new message topic to use for all messages sent.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_message_broker_settings_get('my-message-sink',
    broker_config_file, protocol_lib, connection_string, new_topic)

Interpipe Sink Methods

dsl_sink_interpipe_forward_settings_get

DslReturnType dsl_sink_interpipe_forward_settings_get(const wchar_t* name,
    boolean* forward_eos, boolean* forward_events);

This service gets the current forward settings in use for the named Interpipe Sink component.

Parameters

  • name - [in] unique name of the Interpipe Sink to query.
  • forward_eos - [out] if true, the EOS event will be forwarded to all listeners. False otherwise.
  • forward_events - [out] if true, all downstream events will be forwarded to all the listeners (except for EOS). False otherwise.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, forward_eos, forward_events = dsl_sink_interpipe_forward_settings_get(
    'my-interpipe-sink')

dsl_sink_interpipe_forward_settings_set

DslReturnType dsl_sink_interpipe_forward_settings_set(const wchar_t* name,
    boolean forward_eos, boolean forward_events);

This service sets the forward settings for named Interpipe Sink component.

Parameters

  • name - [in] unique name of the Interpipe Sink to update.
  • forward_eos - [in] set to true to forward the EOS event to all listeners. False to not forward.
  • forward_events - [in] set to true to forward downstream events to all listeners (except for EOS). False to not forward.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_interpipe_forward_settings_set('my-interpipe-sink',
    True, True)

dsl_sink_interpipe_num_listeners_get

DslReturnType dsl_sink_interpipe_num_listeners_get(const wchar_t* name,
    uint* num_listeners);

This service gets the current number of Interpipe Sources listening to the named Interpipe Sink component.

Parameters

  • name - [in] unique name of the Interpipe Sink to query.
  • num_listeners - [out] current number of Interpipe Sources listening.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, num_listeners = dsl_sink_interpipe_num_listeners_get('my-interpipe-sink')

Multi-Image Sink Methods

dsl_sink_image_multi_file_path_get

DslReturnType dsl_sink_image_multi_file_path_get(const wchar_t* name, 
    const wchar_t** file_path);

This service gets the current output file-path in use by the named Multi-Image Sink component.

Parameters

  • name - [in] unique name of the Interpipe Sink to query.
  • file_path - [out] current file-path in use by the Multi-Image Sink.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, file_path = dsl_sink_image_multi_file_path_get('my-multi-image-sink')

dsl_sink_image_multi_file_path_set

DslReturnType dsl_sink_image_multi_file_path_set(const wchar_t* name, 
    const wchar_t* file_path);

This service sets the output file-path for the named Multi-Image Sink to use.

Parameters

  • name - [in] unique name of the Multi-Image Sink to update.
  • file_path - [in] use the printf style %d in the absolute or relative path. Example: "./my_images/image.%04d.jpg", will create files in "./my_images/" named "image.0000.jpg", "image.0001.jpg", "image.0002.jpg" etc.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_image_multi_file_path_set('my-multi-image-sink',
    "./my_images/image.%04d.jpg")

dsl_sink_image_multi_dimensions_get

DslReturnType dsl_sink_image_multi_dimensions_get(const wchar_t* name, 
    uint* width, uint* height);

This service gets the current dimensions in use by the named Multi-Image Sink component. Values of 0 indicate no transcode.

Parameters

  • name - [in] unique name of the Interpipe Sink to query.
  • width - [out] current width to save images in pixels.
  • height - [out] current height to save images in pixels.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, width, height = dsl_sink_image_multi_dimensions_get(
    'my-multi-image-sink')

dsl_sink_image_multi_dimensions_set

DslReturnType dsl_sink_image_multi_dimensions_set(const wchar_t* name, 
    uint width, uint height);

This service sets the dimensions for the named Multi-Image Sink to use.

Parameters

  • name - [in] unique name of the Multi-Image Sink to update.
  • width - [in] new width setting in units of pixels. Set to 0 for no transcode.
  • height - [in] new width setting in units of pixels. Set to 0 for no transcode.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_image_multi_dimensions_set('my-multi-image-sink',
    640, 360)

dsl_sink_image_multi_frame_rate_get

DslReturnType dsl_sink_image_multi_frame_rate_get(const wchar_t* name, 
    uint* fps_n, uint* fps_d);

This service gets the current frame-rate in use by the named Multi-Image Sink component. Values of 0 indicate no rate-change.

Parameters

  • name - [in] unique name of the Interpipe Sink to query.
  • fps_n - [out] current frames per second numerator.
  • fps_d - [out] current frames per second denominator.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, fps_n, fps_d = dsl_sink_image_multi_frame_rate_get(
    'my-multi-image-sink')

dsl_sink_image_multi_frame_rate_set

DslReturnType dsl_sink_image_multi_frame_rate_set(const wchar_t* name, 
    uint fps_n, uint fps_d);

This service sets the frame-rate for the named Multi-Image Sink to use.

Parameters

  • name - [in] unique name of the Multi-Image Sink to update.
  • fps_n - [in] new frames per second numerator. Set to 0 for no rate-change.
  • fps_d - [in] new frames per second denominator. Set to 0 for no rate-change.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_image_multi_frame_rate_set(my-multi-image-sink',
    1, 30)

dsl_sink_image_multi_file_max_get

DslReturnType dsl_sink_image_multi_file_max_get(const wchar_t* name, 
    uint* max);

This service gets the current max-file setting in use by the named Multi-Image Sink component. Once the maximum is reached, old files start to be deleted to make room for new ones. Default = 0 - no max.

Parameters

  • name - [in] unique name of the Interpipe Sink to query.
  • max - [out] current max-file setting in use.

Returns

  • DSL_RESULT_SUCCESS on successful query. One of the Return Values defined above on failure.

Python Example

retval, max = dsl_sink_image_multi_file_max_get(
    'my-multi-image-sink')

dsl_sink_image_multi_file_max_set

DslReturnType dsl_sink_image_multi_file_max_set(const wchar_t* name, 
    uint max);

This service sets the max-file setting for named Multi-Image Sink to use. Once the maximum is reached, old files start to be deleted to make room for new ones. Default = 0 - no max.

Parameters

  • name - [in] unique name of the Multi-Image Sink to update.
  • max - [in] new max-files setting to use. Set to 0 for no maximum.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_image_multi_file_max_set('my-multi-image-sink', 100)

Frame-Capture Sink Methods

dsl_sink_frame_capture_initiate

DslReturnType dsl_sink_frame_capture_initiate(const wchar_t* name);

This service initiates a "frame-capture" action to capture the next buffer processed by the named Frame-Capture Sink.

All captured frames are copied and buffered in the Sink's processing thread. The encoding and saving of each buffered frame is done in the g-idle-thread context.

Note: The first capture may cause a noticeable short pause to the stream while cuda dependencies are loaded and cached.

Parameters

  • name - [in] unique name of the Frame-Capture Sink to update.

Returns

  • DSL_RESULT_SUCCESS on successful update. One of the Return Values defined above on failure.

Python Example

retval = dsl_sink_frame_capture_initiate('my-frame-capture-sink')

API Reference