Group Settings¶

Stream groups¶

If a stream is created / recreated with a group or stream linked/unlinked 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 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 or link/unlink request 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:

{
    "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:

"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:

"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:

"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:

{
    "stream_settings": {
        "location": {"city": "city_1", "street": "street_1"},
        "data": {"fps": 60}
    }
}

If these settings are not specified in stream creation request, they are inherited from the group as-is:

"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:

"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) will be applied:
"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:

# 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

For example:

group1 and group2 have been created
stream has been created
stream has been linked to group1 then to group2

# `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
with enriched=1 query parameter.
To make sure that stream settings and analytics specified during creation equal expected, using get stream request

with enriched=0 query parameter.

To make sure that group settings and analytics equal expected using get group request.