Group Settings ============== Stream groups ------------- If a stream is `created <_static/api.html#operation/createStream>`_ / `recreated <_static/api.html#operation/putStream>`_ with a group or stream `linked/unlinked <_static/api.html#operation/streamsGroupLinker>`_ to/from group(s), then the groups' `stream_settings` and `analytics` will be merged with the stream's settings according to the following rules: .. note:: - if group has no `stream_settings` it will not take part in settings merging - if group has no `analytics` it will not take part in analytics merging - if stream has no `stream_setting` specified during creation, stream settings will be taken from group(s) - if stream has no `analytics` specified during creation, stream analytics will be taken from group(s) - if stream has no `analytics` and groups linked to stream have no `analytics`, the stream creation/link is impossible - if stream and group(s) linked to stream has `stream_settings` which have conflicts (for example, different `orientation_strategy` and `rotation` parameters, the stream creation/link is impossible - if part of merged stream settings can be fulfill with the defaults it will fulfill using defaults (the same ones as presented at `stream creation request <_static/api.html#operation/createStream>`_ in the case when stream in not linked to group) .. note:: Each time stream successfully linked to group or unlinked from group during `stream creation request <_static/api.html#operation/createStream>`_ or `link/unlink request <_static/api.html#operation/streamsGroupLinker>`_ in the case when `stream_update` parameter is specified as `1`: - stream version will be updated - stream settings will be refreshed according to the rules described below - stream analytics will be refreshed according to the rules described below: - if streams analytics set will not changed after this refresh, stream processing will be continued by the same agent as it was (if stream processing has already been started) - if streams analytics set will changed after this refresh, stream processing will be continued by another agent (if there is suitable agent at the moment - it will happens as fast as agent get stream to process, otherwise stream processing will be started when suitable agent appears) Analytics merging rules ^^^^^^^^^^^^^^^^^^^^^^^ Suppose a group was created: .. code-block:: { "analytics": [ {"analytic_name": "analytics_1", "parameters": {"param_1": "value_1", "droi": "droi_1"}, "label": "label_1"}, {"analytic_name": "analytics_2", "parameters": {"param_2": "value_2", "droi": "droi_2"}, "label": "label_2"} ] } - If no analytics are specified for the stream, all analytics from the analytics from group are inherited as-is: .. code-block:: "analytics": [] -> "analytics": [ {"analytic_name": "analytics_1", "parameters": {"param_1": "value_1", "droi": "droi_1"}, "label": "label_1"}, {"analytic_name": "analytics_2", "parameters": {"param_2": "value_2", "droi": "droi_2"}, "label": "label_2"} ] - If the stream's analytics list contains a label that exists in the group, then parameters are overridden. The parameters specified in the stream take priority over the group's parameters for the corresponding *label*: .. code-block:: "analytics": [ { "analytic_name": "analytics_1", "label": "label_2", "parameters": {"droi": "droi_3"} } ] -> "analytics": [ {"analytic_name": "analytics_1", "parameters": {"param_1": "value_1", "droi": "droi_1"}, "label": "label_1"}, {"analytic_name": "analytics_2", "parameters": {"param_2": "value_2", "droi": "droi_3"}, "label": "label_2"} ] - If the stream's analytics list contains analytics without a *label*, such analytics are not associated with the group's analytics and are simply added as new entries: .. code-block:: "analytics": [ {"analytic_name": "analytics_1", "parameters": {"droi": "droi_1"}} ] -> "analytics": [ {"analytic_name": "analytics_1", "parameters": {"param_1": "value_1", "droi": "droi_1"}, "label": "label_1"}, {"analytic_name": "analytics_2", "parameters": {"param_2": "value_2", "droi": "droi_2"}, "label": "label_2"} {"analytic_name": "analytics_1", "parameters": {"droi": "droi_1"}} ] Stream settings merging rules ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Suppose a group was created: .. code-block:: { "stream_settings": { "location": {"city": "city_1", "street": "street_1"}, "data": {"fps": 60} } } - If these settings are not specified in `stream creation request <_static/api.html#operation/createStream>`_, they are inherited from the group as-is: .. code-block:: "data": { "type": "stream", "reference": "rtsp://...", } -> { "data": { "type": "stream", "reference": "rtsp://...", "fps": 60 }, "location": {"city": "city_1", "street": "street_1"}, } - If the stream specifies a setting that also exists in the group, the parameters are merged and overridden. Parameters defined in the stream take priority over the group's parameters: .. code-block:: "data": { "type": "stream", "reference": "rtsp://...", "fps": 55 }, "location": {"city": "city_2"}, -> { "data": { "type": "stream", "reference": "rtsp://..." "fps": 55 }, "location": {"city": "city_2", "street": "street_1"}, } - Defaults. If some required parameter is not present in the group settings and not present in stream settings, the default one (described in `stream creation request <_static/api.html#operation/createStream>`_) will be applied: .. code-block:: "data": {"type": "stream", "reference": "rtsp://..."} -> { "data": {"type": "stream", "reference": "rtsp://...", "timeout": 3000, ...} } Lists merging rules ^^^^^^^^^^^^^^^^^^^ Stream and analytics settings specified as lists will no be merged at the moment and will be replaced in the same order as the another ones: .. code-block:: # group settings { "notification_policy": { "enable": 1, "stream_callbacks": [ { "type": "http", "enable": 1, "authorization": {}, "url": "http://callback.url", "params": {} } ] } } # stream settings "data": { "type": "stream", "reference": "rtsp://...", "notification_policy": { "enable": 1, "stream_callbacks": [ { "type": "telegram", "enable": 1, "token": "1111111111:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "chat_id": 111111111, "params": { "timeout": 60 } } ] } } -> { "data": {"type": "stream", "reference": "rtsp://...", "notification_policy": { "enable": 1, "stream_callbacks": [ { "type": "telegram", "enable": 1, "token": "1111111111:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", "chat_id": 111111111, "params": { "timeout": 60 } } ] } } } Multipie groups merging rules ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ In the case when stream is linked to more than one group, settings and analytics will be merged in the following order: settings from first linked group -> settings from second linked group -> ... -> settings from `stream creation request <_static/api.html#operation/createStream>`_ For example: - `group1` and `group2` have been created - stream has been created - stream has been linked to `group1` then to `group2` .. code-block:: # `group1` creation request content {"group_name": "group1", "stream_settings": {"data": {"fps": 1, "timeout": 12345}} # `group2` creation request content {"group_name": "group2", "stream_settings": {"data": {"fps": 2}} # stream creation request content {"data": {"type": "stream", "reference": "rtsp://..."} # `get stream` response {..., "data": {..., "fps": 2, "timeout": 12345}} # another stream creation request {"data": {"type": "stream", "reference": "rtsp://...", "fps": 3} # `get stream` response {..., "data": {..., "fps": 3, "timeout": 12345}} Troubleshooting ^^^^^^^^^^^^^^^ - To make sure that stream settings and analytics equal expected settings and analytics using `get stream request <_static/api.html#operationtag/streams/operation/getStream>`_ with *enriched=1* query parameter. - To make sure that stream settings and analytics specified during creation equal expected, using `get stream request <_static/api.html#operationtag/streams/operation/getStream>`_ with *enriched=0* query parameter. - To make sure that group settings and analytics equal expected using `get group request <_static/api.html#tag/groups/operation/getGroup>`_.