Merge pull request #1269 from prominenceai/v0.30.b.alpha

v0.30.b.alpha
prominenceai · Aug 24, 2024 · d2055c4 · d2055c4
2 parents 68d749d + 494791c
commit d2055c4
Show file tree

Hide file tree

Showing 30 changed files with 1,543 additions and 622 deletions.
diff --git a/Makefile b/Makefile
@@ -39,7 +39,7 @@ else
 endif
 
 CXX_VERSION:=c++17
-DSL_VERSION:='L"v0.30.a.alpha"'
+DSL_VERSION:='L"v0.30.b.alpha"'
 GLIB_VERSION:=2.0
 
 GSTREAMER_VERSION:=1.0

diff --git a/Release Notes/dsl-releases.md b/Release Notes/dsl-releases.md
@@ -1,15 +1,16 @@
 # DSL Release Notes
 
-| Release                                             | Date        |
-| --------------------------------------------------- | ----------- |
+| Release                                                     | Date        |
+| ----------------------------------------------------------- | ----------- |
+| [v0.30.b.alpha (patch)](/Release%20Notes/v0.30.b.alpha.md)  | 08/28/2024  |
 | [v0.30.a.alpha (patch)](/Release%20Notes/v0.30.a.alpha.md)  | 07/14/2024  |
-| [v0.30.alpha](/Release%20Notes/v0.30.alpha.md)      | 05/28/2024  |
-| [v0.29.alpha](/Release%20Notes/v0.29.alpha.md)      | 03/23/2024  |
-| [v0.28.alpha](/Release%20Notes/v0.28.alpha.md)      | 01/29/2024  |
+| [v0.30.alpha](/Release%20Notes/v0.30.alpha.md)              | 05/28/2024  |
+| [v0.29.alpha](/Release%20Notes/v0.29.alpha.md)              | 03/23/2024  |
+| [v0.28.alpha](/Release%20Notes/v0.28.alpha.md)              | 01/29/2024  |
 | [v0.27.b.alpha (patch)](/Release%20Notes/v0.27.b.alpha.md)  | 11/08/2023  |
 | [v0.27.a.alpha (patch)](/Release%20Notes/v0.27.a.alpha.md)  | 10/24/2023  |
-| [v0.27.alpha](/Release%20Notes/v0.27.alpha.md)      | 09/13/2023  |
-| [v0.26.a.alpha](/Release%20Notes/v0.26.a.alpha.md)  | 06/07/2023  |
-| [v0.26.alpha](/Release%20Notes/v0.26.alpha.md)      | 05/03/2023  |
+| [v0.27.alpha](/Release%20Notes/v0.27.alpha.md)              | 09/13/2023  |
+| [v0.26.a.alpha](/Release%20Notes/v0.26.a.alpha.md)          | 06/07/2023  |
+| [v0.26.alpha](/Release%20Notes/v0.26.alpha.md)              | 05/03/2023  |
 
 Previous releases were documented on the [Releases](https://github.com/prominenceai/deepstream-services-library/releases) page directly.
diff --git a/Release Notes/v0.30.b.alpha.md b/Release Notes/v0.30.b.alpha.md
@@ -0,0 +1,21 @@
+# v0.30.b.alpha (patch) Release Notes
+**Important!**
+* `v0.30.b.alpha` is a **patch** release (patch `b` for the `v0.30.alpha` release).
+* All updates in this release address issues discoverd with Smart Recording, with both the Record Tap and Record Sink.
+* No other components or areas of functionality have changed
+
+## Issues closed in this release
+* Issue with video recording duration in DSL's Record Tap and Record Sink. [#1263](https://github.com/prominenceai/deepstream-services-library/issues/1263)
+* Implement new dsl_tap_record_max_size_get/set and dsl_sink_record_max_size_get/set services [#1264](https://github.com/prominenceai/deepstream-services-library/issues/1264)
+*  Call to NVIDIA's NvDsSRDestroy function blocks indefinately if Pipeline stoped while recording in progress. (NVIDIA Bug) [#1265](https://github.com/prominenceai/deepstream-services-library/issues/1265)
+*  Update smart-record examples to set cache-size and max-size (new) based on start and duration parameters. [#1266](https://github.com/prominenceai/deepstream-services-library/issues/1265)
+
+## Examples updated in this release
+* [smart_record_sink_start_session_on_ode_occurrence.py](/examples/python/smart_record_sink_start_session_on_ode_occurrence.py)
+* [smart_record_sink_start_session_on_user_demand.py](/examples/python/smart_record_sink_start_session_on_user_demand.py)
+* [smart_record_tap_start_session_on_ode_occurrence.py](/examples/python/smart_record_tap_start_session_on_ode_occurrence.py)
+* [smart_record_tap_start_session_on_user_demand.py](/examples/python/smart_record_tap_start_session_on_user_demand.py)
+* [smart_record_sink_start_session_on_ode_occurrence.cpp](/examples/cpp/smart_record_sink_start_session_on_ode_occurrence.cpp)
+* [smart_record_sink_start_session_on_user_demand.cpp](/examples/cpp/smart_record_sink_start_session_on_user_demand.cpp)
+* [smart_record_tap_start_session_on_ode_occurrence.cpp](/examples/cpp/smart_record_tap_start_session_on_ode_occurrence.cpp)
+* [smart_record_tap_start_session_on_user_demand.cpp](/examples/cpp/smart_record_tap_start_session_on_user_demand.cpp)
diff --git a/docs/api-reference-list.md b/docs/api-reference-list.md
@@ -254,6 +254,8 @@
 * [`dsl_tap_record_outdir_set`](/docs/api-tap.md#dsl_tap_record_outdir_set)
 * [`dsl_tap_record_container_get`](/docs/api-tap.md#dsl_tap_record_container_get)
 * [`dsl_tap_record_container_set`](/docs/api-tap.md#dsl_tap_record_container_set)
+* [`dsl_tap_record_max_size_get`](/docs/api-tap.md#dsl_tap_record_max_size_get)
+* [`dsl_tap_record_max_size_set`](/docs/api-tap.md#dsl_tap_record_max_size_set)
 * [`dsl_tap_record_cache_size_get`](/docs/api-tap.md#dsl_tap_record_cache_size_get)
 * [`dsl_tap_record_cache_size_set`](/docs/api-tap.md#dsl_tap_record_cache_size_set)
 * [`dsl_tap_record_dimensions_get`](/docs/api-tap.md#dsl_tap_record_dimensions_get)
@@ -475,6 +477,8 @@
 * [`dsl_sink_record_outdir_set`](/docs/api-sink.md#dsl_sink_record_outdir_set)
 * [`dsl_sink_record_container_get`](/docs/api-sink.md#dsl_sink_record_container_get)
 * [`dsl_sink_record_container_set`](/docs/api-sink.md#dsl_sink_record_container_set)
+* [`dsl_sink_record_max_size_get`](/docs/api-sink.md#dsl_sink_record_max_size_get)
+* [`dsl_sink_record_max_size_set`](/docs/api-sink.md#dsl_sink_record_max_size_set)
 * [`dsl_sink_record_cache_size_get`](/docs/api-sink.md#dsl_sink_record_cache_size_get)
 * [`dsl_sink_record_cache_size_set`](/docs/api-sink.md#dsl_sink_record_cache_size_set)
 * [`dsl_sink_record_dimensions_get`](/docs/api-sink.md#dsl_sink_record_dimensions_get)

diff --git a/docs/api-sink.md b/docs/api-sink.md
@@ -14,11 +14,11 @@ DSL supports fifteen (15) different types of Sinks:
 * [V4L2 Sink](#dsl_sink_v4l2_new) - streams video to a V4L2 device or [v4l2loopback](https://github.com/umlaeute/v4l2loopback).
 * [File Sink](#dsl_sink_file_new) - encodes video to a media container file
 * [Record Sink](#dsl_sink_record_new) - similar to the File sink but with Start/Stop/Duration control and a cache for pre-start buffering.
-* [RTMP Sink](#dsl_sink_record_new) - streams encoded video using the Real-time Messaging Protocol (RTMP) to social media networks, live streaming platforms, and media servers.
+* [RTMP Sink](#dsl_sink_rtmp_new) - streams encoded video using the Real-time Messaging Protocol (RTMP) to social media networks, live streaming platforms, and media servers.
 * [RTSP Client Sink](#dsl_sink_rtsp_client_new) - streams encoded video using the Real-time Streaming Protocol (RTSP) as a client of a media server. 
 * [RTSP Server Sink](#dsl_sink_rtsp_server_new) - streams encoded video via an RTSP (UDP) Server on a specified port.
 * [WebRTC Sink](#dsl_sink_webrtc_new) - streams encoded video to a web browser or mobile application. **(Requires GStreamer 1.18 or later)**
-* [Message Sink](dsl_sink_message_new) - converts Object Detection Event (ODE) metadata into a message payload and sends it to the server using a specified communication protocol.
+* [Message Sink](#dsl_sink_message_new) - converts Object Detection Event (ODE) metadata into a message payload and sends it to the server using a specified communication protocol.
 * [Application Sink](#dsl_sink_app_new) - allows the application to receive buffers or samples from a DSL Pipeline.
 * [Interpipe Sink](#dsl_sink_interpipe_new) -  allows pipeline buffers and events to flow to other independent pipelines, each with an [Interpipe Source](/docs/api-source.md#dsl_source_interpipe_new). Disabled by default, requires additional [install/build steps](/docs/installing-dependencies.md).
 * [Multi-Image Sink](#dsl_sink_image_multi_new) - encodes and saves video frames to JPEG files at specified dimensions and frame-rate.
@@ -195,6 +195,8 @@ You can use the following GStreamer launch command to test the loopback device w
 * [`dsl_sink_record_outdir_set`](#dsl_sink_record_outdir_set)
 * [`dsl_sink_record_container_get`](#dsl_sink_record_container_get)
 * [`dsl_sink_record_container_set`](#dsl_sink_record_container_set)
+* [`dsl_sink_record_max_size_get`](#dsl_sink_record_max_size_get)
+* [`dsl_sink_record_max_size_set`](#dsl_sink_record_max_size_set)
 * [`dsl_sink_record_cache_size_get`](#dsl_sink_record_cache_size_get)
 * [`dsl_sink_record_cache_size_set`](#dsl_sink_record_cache_size_set)
 * [`dsl_sink_record_dimensions_get`](#dsl_sink_record_dimensions_get)
@@ -304,6 +306,12 @@ The following video container types are used by the File Sink API
 #define DSL_CONTAINER_MK4                                           1
 ```
 
+## Recording Defaults
+```C
+#define DSL_DEFAULT_VIDEO_RECORD_MAX_SIZE_IN_SEC                    600
+#define DSL_DEFAULT_VIDEO_RECORD_CACHE_SIZE_IN_SEC                  60
+```
+
 ## Smart Recording Events
 ```C
 #define DSL_RECORDING_EVENT_START                                   0
@@ -1972,12 +1980,22 @@ retval = dsl_sink_encode_dimensions_set('my-rtsp-server-sink', 1280, 720)
 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
+This service starts a new recording session for the named Record Sink. There are two parameters that control the amount of video recorded
+1. `start`: the number of seconds before the current time -- i.e.the amount of cache/history to include.
+2. `duration`: the number of seconds after the current time -- i.e. the amount of time to record after session start is called.
+
+Therefore, a total of `start` + `duration` seconds of data will be recorded as long as the default values are not exceeded.
+
+**IMPORTANT!** 
+1. The default `max_size` for all Smart Recordings is set to 600 seconds. The recording will be truncated if `start` + `duration` is greater than (>)`max_size` See [dsl_sink_record_max_size_set](#dsl_sink_record_max_size_set) to update `max_size`. 
+2. The default `cache-size` for all recordings is set to 60 seconds. The recording will be truncated if `start` is greater than (>) `cache_size`. See [dsl_sink_record_cache_size_set](#dsl_sink_record_cache_size_set) to update  `cache_size`.
+
+Warning messages will be logged if either of the above conditions are not met. See the [Recording Defaults](#recording-defaults) above.
 
 **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.
+ * `duration` [in] duration of time to record in seconds including the `start` time. 
  * `client_data` [in] opaque pointer to client data returned on callback to the client listener function provided on Sink creation.
 
 **Returns**
@@ -2089,11 +2107,58 @@ retval = dsl_sink_record_container_set('my-record-sink', DSL_CONTAINER_MP4)
 
 <br>
 
+### *dsl_sink_record_max_size_get*
+```C++
+DslReturnType dsl_sink_record_max_size_get(const wchar_t* name, uint* max_size);
+```
+This service returns the video recording max size in units of seconds for the named Record Sink. The default max size is set to [`DSL_DEFAULT_VIDEO_RECORD_MAX_IN_SEC`](#recording-defaults).
+
+**IMPORTANT!** The `max_size` must be greater than `start` + `duration` when starting a recording. See [dsl_sink_record_session_start](#dsl_sink_record_session_start).
+
+**Parameters**
+ * `name` [in] name of the Record Sink to query.
+ * `max_size` [out] current cache size setting in units of seconds.
+
+**Returns**
+* `DSL_RESULT_SUCCESS` on successful Query. One of the [Return Values](#return-values) defined above on failure.
+
+**Python Example**
+```Python
+retval, max_size = dsl_sink_record_cache_size_get('my-record-sink')
+```
+
+<br>
+
+### *dsl_sink_record_max_size_set*
+```C++
+DslReturnType dsl_sink_record_max_size_set(const wchar_t* name, uint cache_size);
+```
+This service sets the video recording max size in units of seconds for the named Record Sink. The default max size is set to [`DSL_DEFAULT_VIDEO_RECORD_MAX_IN_SEC`](#recording-defaults).
+
+**IMPORTANT!** The `max_size` must be greater than `start` + `duration` when starting a recording. See [dsl_sink_record_session_start](#dsl_sink_record_session_start).
+
+**Parameters**
+ * `name` [in] name of the Record Sink to query.
+ * `max_size` [in] new cache size setting in units of seconds.
+
+**Returns**
+* `DSL_RESULT_SUCCESS` on successful update. One of the [Return Values](#return-values) defined above on failure.
+
+**Python Example**
+```Python
+retval = dsl_sink_record_max_size_set('my-record-sink', 1200)
+```
+
+<br>
+
 ### *dsl_sink_record_cache_size_get*
 ```C++
 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.
+This service returns the video recording cache size in units of seconds for the named Record Sink. The default cache size is set to [`DSL_DEFAULT_VIDEO_RECORD_CACHE_IN_SEC`](#recording-defaults).
+
+**IMPORTANT!** The `cache_size` must be greater than `start` when starting a recording. See [dsl_sink_record_session_start](#dsl_sink_record_session_start).
+
 
 **Parameters**
  * `name` [in] name of the Record Sink to query.
@@ -2113,7 +2178,9 @@ retval, cache_size = dsl_sink_record_cache_size_get('my-record-sink')
 ```C++
 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.
+This service sets the video recording cache size in units of seconds for the named Record Sink. The default cache size is set to [`DSL_DEFAULT_VIDEO_RECORD_CACHE_IN_SEC`](#recording-defaults).
+
+**IMPORTANT!** The `cache_size` must be greater than `start` when starting a recording. See [dsl_sink_record_session_start](#dsl_sink_record_session_start).
 
 **Parameters**
  * `name` [in] name of the Record Sink to query.

diff --git a/docs/api-tap.md b/docs/api-tap.md
@@ -27,6 +27,8 @@ Note: Adding a Tap component to a Pipeline or Branch directly will fail.
 * [`dsl_tap_record_outdir_set`](#dsl_tap_record_outdir_set)
 * [`dsl_tap_record_container_get`](#dsl_tap_record_container_get)
 * [`dsl_tap_record_container_set`](#dsl_tap_record_container_set)
+* [`dsl_tap_record_max_size_get`](#dsl_tap_record_max_size_get)
+* [`dsl_tap_record_max_size_set`](#dsl_tap_record_max_size_set)
 * [`dsl_tap_record_cache_size_get`](#dsl_tap_record_cache_size_get)
 * [`dsl_tap_record_cache_size_set`](#dsl_tap_record_cache_size_set)
 * [`dsl_tap_record_dimensions_get`](#dsl_tap_record_dimensions_get)
@@ -59,13 +61,20 @@ The following return codes are used by the Tap API
 
 ## Video Container Types
 The following video container types are used by the Record Tap API
-```C++
+```C
 #define DSL_CONTAINER_MPEG4                                         0
 #define DSL_CONTAINER_MK4                                           1
 ```
+
+## Recording Defaults
+```C
+#define DSL_DEFAULT_VIDEO_RECORD_MAX_SIZE_IN_SEC                    600
+#define DSL_DEFAULT_VIDEO_RECORD_CACHE_SIZE_IN_SEC                  60
+```
+
 ## Recording Events
 The following Event Type identifiers are used by the Recording Tap API
-```C++
+```C
 #define DSL_RECORDING_EVENT_START                                   0
 #define DSL_RECORDING_EVENT_END                                     1
 ```
@@ -174,7 +183,9 @@ As with all Pipeline components, Taps are deleted by calling [dsl_component_dele
 DslReturnType dsl_tap_record_session_start(const wchar_t* name, uint* session,
     uint start, uint duration, void* client_data);
 ```
-This services starts a new recording session for the named Record Tap
+This services starts a new recording session for the named Record Tap.
+
+**IMPORTANT!** The `max-size` must be greater than `start` + `duration`, and `cache-size` must be greater than `start`. See [dsl_tap_record_max_size_set](#dsl_tap_record_max_size_set) and [dsl_tap_record_cache_size_set](#dsl_tap_record_cache_size_set).
 
 **Parameters**
  * `name` [in] unique of the Record Tap to start the session
@@ -292,15 +303,57 @@ retval = dsl_tap_record_container_set('my-record-tap', DSL_CONTAINER_MP4)
 
 <br>
 
+### *dsl_tap_record_max_size_get*
+```C++
+DslReturnType dsl_tap_record_max_size_get(const wchar_t* name, uint* max_size);
+```
+This service returns the video recording max size in units of seconds for the named Record Tap. The default max size is set to [`DSL_DEFAULT_VIDEO_RECORD_MAX_IN_SEC`](#recording-defaults).
+
+**IMPORTANT!** The `max_size` must be greater than `start` + `duration` when starting a recording. See [dsl_tap_record_session_start](#dsl_tap_record_session_start).
+
+**Parameters**
+ * `name` [in] name of the Record Tap to query.
+ * `max_size` [out] current max size setting in units of seconds.
+
+**Returns**
+* `DSL_RESULT_SUCCESS` on successful Query. One of the [Return Values](#return-values) defined above on failure
+
+**Python Example**
+```Python
+retval, max_size = dsl_tap_record_max_size_get('my-record-tap')
+```
+
+<br>
+
+### *dsl_tap_record_max_size_set*
+```C++
+DslReturnType dsl_tap_record_max_size_set(const wchar_t* name, uint max_size);
+```
+This service sets the video recording max size in units of seconds for the named Record Tap. The default max size is set to [`DSL_DEFAULT_VIDEO_RECORD_MAX_IN_SEC`](#recording-defaults).
+
+**IMPORTANT!** The `max-size` must be greater than `start` + `duration` when starting a recording. See [dsl_tap_record_session_start](#dsl_tap_record_session_start).
+
+**Returns**
+* `DSL_RESULT_SUCCESS` on successful update. One of the [Return Values](#return-values) defined above on failure
+
+**Python Example**
+```Python
+retval = dsl_tap_record_max_size_set('my-record-tap', 1200)
+```
+
+<br>
+
 ### *dsl_tap_record_cache_size_get*
 ```C++
 DslReturnType dsl_tap_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.
+This service returns the video recording cache size in units of seconds for the named Record Tap. The default cache size is set to [`DSL_DEFAULT_VIDEO_RECORD_CACHE_IN_SEC`](#recording-defaults).
+
+**IMPORTANT!** The `cache_size` must be greater than `start` when starting a recording. See [dsl_tap_record_session_start](#dsl_tap_record_session_start).
 
 **Parameters**
- * `name` [in] name of the Record Tap to query
- * `cache_size` [out] current cache size setting
+ * `name` [in] name of the Record Tap to query.
+ * `cache_size` [out] current cache size setting in units of seconds.
 
 **Returns**
 * `DSL_RESULT_SUCCESS` on successful Query. One of the [Return Values](#return-values) defined above on failure
@@ -316,11 +369,13 @@ retval, cache_size = dsl_tap_record_cache_size_get('my-record-tap')
 ```C++
 DslReturnType dsl_tap_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
+This service sets the video recording cache size in units of seconds for the named Record Tap. The default cache size is set to [`DSL_DEFAULT_VIDEO_RECORD_CACHE_IN_SEC`](#recording-defaults).
+
+**IMPORTANT!** The `cache-size` must be greater than `start` when starting a recording. See [dsl_tap_record_session_start](#dsl_tap_record_session_start).
 
 **Parameters**
  * `name` [in] name of the Record Tap to query
- * `cache_size` [in] new cache size setting to use on Pipeline play
+ * `cache_size` [in] new cache size setting in units of seconds.
 
 **Returns**
 * `DSL_RESULT_SUCCESS` on successful update. One of the [Return Values](#return-values) defined above on failure
@@ -336,7 +391,7 @@ retval = dsl_tap_record_cache_size_set('my-record-tap', 15)
 ```C++
 DslReturnType dsl_tap_record_dimensions_get(const wchar_t* name, uint* width, uint* height);
 ```
-This service returns the dimensions, width and height, used for the video recordings
+This service returns the dimensions, width and height, used for the video recordings 
 
 **Parameters**
  * `name`[in] name of the Record Tap to query