API docs by Redocly

Flussonic Central Layouter API (24.03)

Download OpenAPI specification:Download

Support team: support@flussonic.com URL: https://flussonic.com/

Introduction

Layouter is our development that manages the layout of streams and agents across streamers. This API describes how Layouter interacts with Central and based on which data it performs streams and agents layouts.

Permanent download link to JSON schema file.

Layout of stream or agent describes on which nodes the stream or agent is being captured:

  • layout.ingest field contains hostname of streamer where the stream is being captured.

  • layout.inference field contains the hostname of the Vision Inference node on which stream analytics is running.

  • layout.dvr_backups field contains an array of streamer hostnames that will contain a copy of the DVR archive.

  • Similarly with stream, the agent's layout.ingest field contains hostname of streamer where the stream is being captured.

Layouter runs with interval specified by layouter_sleeping_interval between its iterations, ensuring that the layout is up-to-date with the latest cluster state.

Data model

The state of the cluster is described by the following entities:

  • Streamer

    Configuration of the streamer including its stats. If there stats are null, the streamer is considered offline. Depending on the streamer's role, it will be used to set layout.ingest or layout.inference fields for the stream. Streamers with role Identification are ignored by layouter. Layouter operates with labels and channel_limit fields of streamer.

  • Stream

    If no streamer is online, the layout of the streams will not be changed. Based on the current layout for a particular stream, the layouter decides if the layout needs to be updated.

    Also layouter sends long-polling 'streams_list' requests to fetch streams with empty layout.ingest and updated_at greater than the maximum updated_at among the same request's streams. Layouter processes these streams immediately.

  • Agent

    Agent without its corresponding stream. This means that there is no stream that uses the agent as input.

Operation flow

Layouter fetches data using streams_list, agents_list and streamers_list operations and processes the current state of the cluster from Central. After processing, if necessary, it updates the layout of the streams and agents using batch_update_streams_layouts and batch_update_agents_layouts operations if necessary.

Data Processing

The situation of overloading the streamer is considered first. That is when the number of streams with ingest equal to hostname exceeds channel_limit of this streamer. If such a situation is detected, the layout will be changed for N = channel_limit - online_streams streams of this streamer.

After that, the need to change the layout for streams that were not processed in the first step is checked. Thus, if a stream already has layout.ingest set, it will not be redistributed.

Agents are processed in a similar way. If layout.ingest is set and this streamer is online, the agent will not be redistributed.

stream

List streams

This API method is used by layouter to fetch all streams in the cluster.

Layouter will use this method along with the query parameters limit and cursor. It is therefore necessary that the system supports them.

Authorizations:
bearerAuth
query Parameters
sort
string
Example: sort=-stats.bitrate,name

Composite sort direction. Specify field name(s) using comma , as a separator.

Default sorting order is alphabetical by name.

Place - before the field name to sort in reverse alphabetical order or descending.

limit
integer
Example: limit=100

Limit the number of records in the selected collection to N elements. Default value is 100

cursor
string
Example: cursor=JTI0cG9zaXRpb25fZ3Q9MQ==

A properly encoded equivalent of offset allowing you to read the next bunch of items. We do not offer common offset fields, so please use cursor for predictable fetching of quickly changing list of items.

poll_timeout
integer <seconds>
Example: poll_timeout=30

This parameter implements the long-polling mechanism, it defines the maximum waiting time in seconds until the request is completed. It is used for receiving new streams by the Layouter immediately after they are saved in the system.

updated_at_gt
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]
Example: updated_at_gt=1637094994000

Filter the collection by stream update time.

layout.ingest_is
string

Filter the collection by empty layout.ingest field. Used by layouter to filter new streams with updated_at_gt parameter: updated_at_gt=...&layout.ingest_is=null.

Responses

Response samples

Content type
application/json
{
  • "estimated_count": 5,
  • "next": "JTI0cG9zaXRpb25fZ3Q9MA==",
  • "prev": "JTI0cG9zaXRpb25fbHQ9MSYlMjRyZXZlcnNlZD10cnVl",
  • "timing": { },
  • "streams": [
    ]
}

Batch update layouts of streams

Batch update layouts of streams. This operation does everything or nothing. If at least one stream has an invalid configuration or can't be processed, the request will fail.

Authorizations:
bearerAuth
Request Body schema: application/json

List of new layouts for streams

Array of objects (central_stream_layout_list_item)

List of streams layouts

Responses

Request samples

Content type
application/json
{
  • "layouts": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "error": "string"
}

streamer

List streamers

This API method is used by layouter to fetch all streamers of the cluster

Authorizations:
bearerAuth
query Parameters
"inference" (string) or "streamer" (string)
Examples: role=inference role=streamer

Role of the streamer

Responses

Response samples

Content type
application/json
{
  • "estimated_count": 5,
  • "next": "JTI0cG9zaXRpb25fZ3Q9MA==",
  • "prev": "JTI0cG9zaXRpb25fbHQ9MSYlMjRyZXZlcnNlZD10cnVl",
  • "timing": { },
  • "streamers": [
    ]
}

agent

List Agents

This API method is used by layouter to fetch agents without their corresponding stream.

By agent without its corresponding stream is meant that no stream has the agent in its inputs field.

Layouter will use this method along with the query parameters limit, cursor and stream_is. It is therefore necessary that the system supports them.

Authorizations:
bearerAuth
query Parameters
stream_is
required
string

Filter agents by stream presence.

Value: "null"
sort
string
Example: sort=-id

Composite sort direction. Specify field name(s) using comma , as a separator. Default sorting order is reverse alphabetical by id. Place - before the field name to sort in reverse alphabetical order or descending.

limit
integer
Example: limit=100

Limit the number of records in the selected collection to N elements.

cursor
string
Example: cursor=JTI0cG9zaXRpb25fZ3Q9MQ==

A properly encoded equivalent of offset allowing you to read the next bunch of items. We do not offer common offset fields, so please use cursor for predictable fetching of quickly changing list of items.

Responses

Response samples

Content type
application/json
{
  • "estimated_count": 5,
  • "next": "JTI0cG9zaXRpb25fZ3Q9MA==",
  • "prev": "JTI0cG9zaXRpb25fbHQ9MSYlMjRyZXZlcnNlZD10cnVl",
  • "timing": { },
  • "agents": [
    ]
}

Batch update layouts of agents

Batch update layouts of agents. This operation does everything or nothing. Only agents without streams will be processed, other ones would be ignored. If at least one agent has an invalid configuration or can't be processed, the request will fail.

Authorizations:
bearerAuth
Request Body schema: application/json

List of new layouts for agents

Array of objects (central_agent_layout_list_item)

List of agent layouts

Responses

Request samples

Content type
application/json
{
  • "layouts": [
    ]
}

Response samples

Content type
application/json
{
  • "errors": [
    ],
  • "error": "string"
}