API docs by Redocly

Flussonic Central API (24.11-292)

Download OpenAPI specification:Download

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

This is an API for Flussonic Central subsystem. Flussonic Central is the underlying technology behind Flussonic Watcher providing you with options for managing streams, events, and Agents in a cluster of several streamers (i.e. Flussonic Media Servers) through a single point of access.

Permanent download link to JSON schema file.

Flussonic Central does not include features for managing users and their permissions. This part is Watcher VMS subsystem or Cloud.

Watcher VMS addresses Flussonic Central when users manage cameras (streams), Agents, and events. However, you may use Flussonic Central for any streams, not only cameras.

Streamer 1
             Flussonic Central <-> Watcher VMS
Streamer N

You can install Flussonic Central subsystem on your local server.

Some methods in Flussonic Central API may look very similar to Flussonic Media Server API, but you should pay attention to some parameters that are different. For example, all streams are created manually in Watcher Core while streams with dynamic names are not supported so you will not find the named_by parameter in the stream config or the part parameter in the stream_save method. Do not rely on any undocumented parameters.

One of the components of the Central is Layouter - our development that manages the layout of streams and agents across streamers. For more details on how the layout can be controlled, see stream labels and streamer labels descriptions.

stream

List streams

This API method is one of the most important in whole API, because it gives the list of all streams, including:

  • configured (maybe not running at the moment)
  • running (including those that are created via template and do not have own disk configuration)
  • remote (available from other servers)
  • only recorded

You can pass any stream configuration options to the q query string for filtering, not only those specified in the select parameters.

This method, as well as stream_get, will return the effective stream configuration with all templates, defaults included into the response. It is not exactly what you can see in your disk config. If you have configured this stream in disk file, then the original disk configuration can be found in the config_on_disk field.

Thus, what you get from this API call may differ from what you write to stream_save which is another important method for managing streams.

Authorizations:
bearerAuth
query Parameters
select
string
Example: select=name,inputs,stats,dvr.root

Comma-separated list of fields (including nested) that will be returned.

Use parent.child notation to mention nested (child) fields.

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.

q
string
Example: q=somepattern

Search pattern for text fields like name, title, urls, etc.

scheme
string
Enum: "http" "https"
Example: scheme=http

Which protocol was requested by client. Central will use the param to try adjust "streaming_endpoint" in the response if it possible. For example, if there are no streamers with configured "http" listeners, we'll return "https://" for requested "http" scheme.

client_ip
string
Example: client_ip=192.168.20.31

client ip address which may be important for balancing

poll_timeout
integer <seconds>
Example: poll_timeout=30

Client may ask to delay a response if there are no streams matching the query yet. This parameter implements the long-polling mechanism, it defines the maximum waiting time in seconds until the request is completed.

Responses

Response samples

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

Get one stream

This method allows you to fetch a single stream. The data returned in this method are the same as for streams_list operation.

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: abc

Stream name

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "comment": "This is a test stream",
  • "title": "Hockey channel",
  • "position": 2,
  • "named_by": "config",
  • "srt_port_resolve": false,
  • "template": "sports-hd",
  • "recheck_secondary_inputs_interval": 120,
  • "static": true,
  • "disabled": false,
  • "inputs": [
    ],
  • "input_media_info": {
    },
  • "provider": "SportsTV",
  • "dvbocr": "replace",
  • "source_timeout": 10,
  • "video_timeout": 20,
  • "audio_timeout": 20,
  • "max_retry_timeout": 30,
  • "backup": {
    },
  • "epg_enabled": true,
  • "mpegts_ac3": "keep",
  • "clients_timeout": 485,
  • "retry_limit": 0,
  • "transcoder": {
    },
  • "thumbnails": {},
  • "jpeg_snapshot_sign_key": "string",
  • "dvr": {
    },
  • "on_play": {
    },
  • "on_publish": {
    },
  • "drm": {},
  • "protocols": {
    },
  • "prepush": false,
  • "segment_count": 4,
  • "segment_duration": 5000,
  • "chunk_duration": 200,
  • "url_prefix": false,
  • "hls_scte35": "scte35",
  • "add_audio_only": true,
  • "webrtc_abr": {
    },
  • "pushes": [
    ],
  • "mpegts_pids": {
    },
  • "labels": {
    },
  • "playback_headers": [
    ],
  • "meta": {
    },
  • "vision": {
    },
  • "srt_publish": {
    },
  • "srt2_publish": {
    },
  • "config_on_disk": {
    },
  • "stats": {
    },
  • "updated_at": 1637098611000,
  • "autogenerated_episodes_close_timeout": 0,
  • "layout": {
    },
  • "claims": {
    }
}

Save stream

Create or update a stream by its name. If the stream doesn't exists in the disk config, it will be created.

If you pass only a partial stream configuration, just the passed field(s) will be updated, not the whole stream.

To create a new stream the property name is required.

Pass the "$reset": true option to replace the stream configuration with the provided one.

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: abc

Stream name

Request Body schema: application/json

Partial stream configuration

comment
string

Human-readable description of the stream.

title
string

Human-readable title of the stream. Provided for SDT MPEG-TS table or SDP RTSP title parameter.

position
integer <sort_index>

Position of the stream in order of streams in the config file, if declared.

template
string <media_name>

Template of the stream.

recheck_secondary_inputs_interval
integer <seconds>

How often to re-check secondary inputs. If this option is not set than check is never performed.

static
boolean
Default: true

Whether a stream is static or not. If set to True the server will try to keep this stream running even if there are no viewers or errors encountered.

Streamer restarts all static streams even if any internal errors occur and the static streams crash.

disabled
boolean

Whether a stream is disabled. Disabled streams are inactive and do not run. Displayed only with the API calls.

Array of Demo source (object) or File (object) or H323 (object) or HLS (object) or RTMP (object) or RTSP (object) or SRT (object) or TSHTTP (object) or Mixer (object) or Mosaic (object) or M4F (object) or M4S (object) or RTP (object) or SHOUTcast (object) or Timeshift (object) or Playlist (object) or Copy source (object) or SPTS (object) or MPTS (object) or Publish (object) or V4L (object) or Decklink SDI (object) or DekTec SDI (object) or NDI (object) or SMPTE 2110 (object) or FRIP (object)

List of stream inputs. Important: A stream without any inputs can receive video frames only if backup file is specified.

object (input_media_info)

Use this option for fine-grained control over each input track.

You can select, rename, change name and title for each video, audio track.

provider
string
Deprecated Delete at: 25.03

Human-readable name of the content provider. Used, for example, for MPEG-TS.

Deprecated, use input_media_info.provider instead

"replace" (any) or "add" (any)

This parameter allows to manage subtitles in an output stream.

integer or boolean

If a connected source does not send any data within this timeout period (in seconds), the source connection is considered to be lost. This is a default configuration for a stream, can be modified for any input.

video_timeout
integer <seconds>

If a connected source does not send video data within this timeout period (in seconds), the source connection is considered to be lost. This is a default configuration for a stream, can be modified for any input.

audio_timeout
integer <seconds>

If a connected source does not send audio data within this timeout period (in seconds), the source connection is considered to be lost. This is a default configuration for a stream, can be modified for any input.

max_retry_timeout
integer <seconds> >= 1

The maximum time that Media Server will set for attempts to reconnect to sources when source problems occur. The time between attempts is not linear and may increase if source problems are not fixed. This parameter limits this value, but the time itself between attempts may be longer.

object

When all inputs are down, this can be used to show at least something to users. It is important to understand that backup video behaves differently, not as inputs. It is not a last input in the list. After any input stops sending frames, timer starts. After source_timeout seconds backup starts working, while all other inputs are still trying to connect and start working. So backup and all inputs are working in parallel.

epg_enabled
boolean

Whether to extract EPG from the input.

"system_b" (string) or "system_a" (string) or "keep" (string)

It allows to specify pack information about ac3 for outgoing MPEGTS-TS streams. The default value is system_b.

integer or boolean

Stream's lifetime after the last client was disconnected (can be expressed in seconds or set to False). Applicable to on-demand streams only.

retry_limit
integer

Number of attempts for the server to reconnect to a data source. Applicable to on-demand streams only. If not defined, server will constantly try to reconnect (unlimited number of retries). If the input does not become active after specified amount of attempts, stream shuts down till the next user request.

object

Configuration of the transcoder settings.

object

Configuration of thumbnails generator.

jpeg_snapshot_sign_key
string

A key to sign jpeg_snapshot requests

object (stream_dvr_spec)

DVR configuraton.

object

Configuration of authorization backend for play sessions.

Find more information about `on_play` and `on_publish` here.
object

Configuration of authorization backend for publish sessions.

any

Configuraton of Digital Rights Management system (DRM).

object

Configuration to allow/forbid playing the stream via various protocols.

  • If the whitelist option is set to 'true', the server allows a playback only for listed protocols;
  • If the whitelist option is set to 'false', the server forbids a playback for listed protocols;
  • Server allows a playback for all the protocols by default.
boolean or integer

The time (in seconds) that Media Server reserves for preloading the data, i. e. buffering. Prepush is always defined through GoP, but this option provides you with a more flexible way to configure the buffer size, e. g. a 1-3 or 7-10 seconds time interval.

The bigger the buffer size, the better the user experience is for the users with a bad internet connection. However, the latency also increases.

If set to False to remove the latency, the stream's start time increases. To decrease it, reduce the GoP size and make the bitrate higher or the video quality lower.

Find more information here
segment_count
integer

Number of segments stored in memory for the segment-based protocols, such as HLS and DASH. Added to HLS live manifest. Do not forget that one more segment is stored for stale clients that come too late, but the latest segment is not shown in the manifest.

segment_duration
integer <milliseconds> [ 1000 .. 15000 ]

The time of the segment duration. Used for the protocols like HLS or DASH. The disk config offers this value in seconds.

chunk_duration
integer <milliseconds>

Chunk duration in LL-HLS manifest to be used for tunning latency.

boolean or string

A string starting the addresses of separate segments within a segment-based playlists (HLS or DASH). Each sub-playlist is stored on Media Server.

If set to false, the configured value in a template will be disabled.

Find more information here
aws"aws" (any) or scte35"scte35" (any) or rfc8216"rfc8216" (any)

Whether to enable SCTE-35 ad insertion markers signaling in HLS manifest. Ad markers can be included in SCTE-35 (scte35), AWS (aws), EXT-X-DATERANGE (rfc8216) formats or not included (false).

Find more information here
add_audio_only
boolean

Whether to add an audio-only version of an HLS stream. Used to create App Store compliant HLS streams to deliver the content to Apple iOS devices.

Find more information here
object

WebRTC play configuration for a stream.

Array of RTMP (object) or Multicast MPEG-TS (object) or M4F (object) or M4S (object) or Decklink SDI (object) or Dektec SDI (object) or Dektec ASI (object) or HTTP MPEG-TS (object) or HLS (object) or SRT (object) or SMPTE 2110 (object)

A list of pushes. When a server initiates the connection and sends a stream to other server(s), it is called a push.

Find more information here
object

This parameter sets PIDs values for outgoing MPEG-TS streams. PID contains information about the TS package content and can be decoded according to special service tables. It is possible to set PID values for PMT, SDT, video, and audio tracks. Tracks are numbered starting from one. The code a1=123 sets a PID value for the first audio track. It is possible to set the base index for the tracks of a certain type using the 0 (zero) index. For example, t0=100 sets PID=101 for the first track, 102 for the second, and so on. Numbers can be given in decimal form (by default) or hexadecimal with 16# prefix.

object <= 10 items

Stream labels in key value format.

Array of objects (playback_headers) <= 10 items

This parameter sets playback HTTP headers for streams.

object
Deprecated Delete at: 23.12

The param is deprecated and now used only for onvif_url and onvif_profile options.

object

Video analytics parameters.

object (srt_config)

SRT publishing configuration for a stream.

object (srt_config)

SRT2 publishing configuration for a stream.

object (stream_config_stripped)

Part of the effective config from the configuration file.

autogenerated_episodes_close_timeout
integer <seconds> >= 0

This option has sense only for published streams. For all other behavior is undefined and unpredicted.

If the value is greater than 0, Central will generate episodes for the stream automatically based on the stream DVR ranges. Each range is considered an episode given that at least timeout seconds passed between these ranges.

An episode is created at the start of the publication and is closed after a timeout after the end of publication. If new publication started in less than timeout - two publications will be merged into one episode.

object (central_stream_layout)

Current layout of stream. Central will provide configuration to nodes based on this layout.

object

User-defined claims about the stream parameters. Set this field so that layouter can rely on this data when distributing streams.

Responses

Request samples

Content type
application/json
{
  • "comment": "This is a test stream",
  • "title": "Hockey channel",
  • "position": 2,
  • "template": "sports-hd",
  • "recheck_secondary_inputs_interval": 120,
  • "static": true,
  • "disabled": false,
  • "inputs": [
    ],
  • "input_media_info": {
    },
  • "provider": "SportsTV",
  • "dvbocr": "replace",
  • "source_timeout": 10,
  • "video_timeout": 20,
  • "audio_timeout": 20,
  • "max_retry_timeout": 30,
  • "backup": {
    },
  • "epg_enabled": true,
  • "mpegts_ac3": "keep",
  • "clients_timeout": 485,
  • "retry_limit": 0,
  • "transcoder": {
    },
  • "thumbnails": {},
  • "jpeg_snapshot_sign_key": "string",
  • "dvr": {
    },
  • "on_play": {
    },
  • "on_publish": {
    },
  • "drm": {},
  • "protocols": {
    },
  • "prepush": false,
  • "segment_count": 4,
  • "segment_duration": 5000,
  • "chunk_duration": 200,
  • "url_prefix": false,
  • "hls_scte35": "scte35",
  • "add_audio_only": true,
  • "webrtc_abr": {
    },
  • "pushes": [
    ],
  • "mpegts_pids": {
    },
  • "labels": {
    },
  • "playback_headers": [
    ],
  • "meta": {
    },
  • "vision": {
    },
  • "srt_publish": {
    },
  • "srt2_publish": {
    },
  • "config_on_disk": {
    },
  • "autogenerated_episodes_close_timeout": 0,
  • "layout": {
    },
  • "claims": {
    }
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "comment": "This is a test stream",
  • "title": "Hockey channel",
  • "position": 2,
  • "named_by": "config",
  • "srt_port_resolve": false,
  • "template": "sports-hd",
  • "recheck_secondary_inputs_interval": 120,
  • "static": true,
  • "disabled": false,
  • "inputs": [
    ],
  • "input_media_info": {
    },
  • "provider": "SportsTV",
  • "dvbocr": "replace",
  • "source_timeout": 10,
  • "video_timeout": 20,
  • "audio_timeout": 20,
  • "max_retry_timeout": 30,
  • "backup": {
    },
  • "epg_enabled": true,
  • "mpegts_ac3": "keep",
  • "clients_timeout": 485,
  • "retry_limit": 0,
  • "transcoder": {
    },
  • "thumbnails": {},
  • "jpeg_snapshot_sign_key": "string",
  • "dvr": {
    },
  • "on_play": {
    },
  • "on_publish": {
    },
  • "drm": {},
  • "protocols": {
    },
  • "prepush": false,
  • "segment_count": 4,
  • "segment_duration": 5000,
  • "chunk_duration": 200,
  • "url_prefix": false,
  • "hls_scte35": "scte35",
  • "add_audio_only": true,
  • "webrtc_abr": {
    },
  • "pushes": [
    ],
  • "mpegts_pids": {
    },
  • "labels": {
    },
  • "playback_headers": [
    ],
  • "meta": {
    },
  • "vision": {
    },
  • "srt_publish": {
    },
  • "srt2_publish": {
    },
  • "config_on_disk": {
    },
  • "stats": {
    },
  • "updated_at": 1637098611000,
  • "autogenerated_episodes_close_timeout": 0,
  • "layout": {
    },
  • "claims": {
    }
}

Delete stream

The stream will be permanently deleted from the project.

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: abc

Stream name

Responses

Dry run layouter for changed stream configuration

This method allows you to see how the overall layout will be changed due to changes into stream configuration. Note that if Layouter is disabled, this method will return an error.

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: abc

Stream name

Request Body schema: application/json

A changes into stream or streamer configuration

comment
string

Human-readable description of the stream.

title
string

Human-readable title of the stream. Provided for SDT MPEG-TS table or SDP RTSP title parameter.

position
integer <sort_index>

Position of the stream in order of streams in the config file, if declared.

template
string <media_name>

Template of the stream.

recheck_secondary_inputs_interval
integer <seconds>

How often to re-check secondary inputs. If this option is not set than check is never performed.

static
boolean
Default: true

Whether a stream is static or not. If set to True the server will try to keep this stream running even if there are no viewers or errors encountered.

Streamer restarts all static streams even if any internal errors occur and the static streams crash.

disabled
boolean

Whether a stream is disabled. Disabled streams are inactive and do not run. Displayed only with the API calls.

Array of Demo source (object) or File (object) or H323 (object) or HLS (object) or RTMP (object) or RTSP (object) or SRT (object) or TSHTTP (object) or Mixer (object) or Mosaic (object) or M4F (object) or M4S (object) or RTP (object) or SHOUTcast (object) or Timeshift (object) or Playlist (object) or Copy source (object) or SPTS (object) or MPTS (object) or Publish (object) or V4L (object) or Decklink SDI (object) or DekTec SDI (object) or NDI (object) or SMPTE 2110 (object) or FRIP (object)

List of stream inputs. Important: A stream without any inputs can receive video frames only if backup file is specified.

object (input_media_info)

Use this option for fine-grained control over each input track.

You can select, rename, change name and title for each video, audio track.

provider
string
Deprecated Delete at: 25.03

Human-readable name of the content provider. Used, for example, for MPEG-TS.

Deprecated, use input_media_info.provider instead

"replace" (any) or "add" (any)

This parameter allows to manage subtitles in an output stream.

integer or boolean

If a connected source does not send any data within this timeout period (in seconds), the source connection is considered to be lost. This is a default configuration for a stream, can be modified for any input.

video_timeout
integer <seconds>

If a connected source does not send video data within this timeout period (in seconds), the source connection is considered to be lost. This is a default configuration for a stream, can be modified for any input.

audio_timeout
integer <seconds>

If a connected source does not send audio data within this timeout period (in seconds), the source connection is considered to be lost. This is a default configuration for a stream, can be modified for any input.

max_retry_timeout
integer <seconds> >= 1

The maximum time that Media Server will set for attempts to reconnect to sources when source problems occur. The time between attempts is not linear and may increase if source problems are not fixed. This parameter limits this value, but the time itself between attempts may be longer.

object

When all inputs are down, this can be used to show at least something to users. It is important to understand that backup video behaves differently, not as inputs. It is not a last input in the list. After any input stops sending frames, timer starts. After source_timeout seconds backup starts working, while all other inputs are still trying to connect and start working. So backup and all inputs are working in parallel.

epg_enabled
boolean

Whether to extract EPG from the input.

"system_b" (string) or "system_a" (string) or "keep" (string)

It allows to specify pack information about ac3 for outgoing MPEGTS-TS streams. The default value is system_b.

integer or boolean

Stream's lifetime after the last client was disconnected (can be expressed in seconds or set to False). Applicable to on-demand streams only.

retry_limit
integer

Number of attempts for the server to reconnect to a data source. Applicable to on-demand streams only. If not defined, server will constantly try to reconnect (unlimited number of retries). If the input does not become active after specified amount of attempts, stream shuts down till the next user request.

object

Configuration of the transcoder settings.

object

Configuration of thumbnails generator.

jpeg_snapshot_sign_key
string

A key to sign jpeg_snapshot requests

object (stream_dvr_spec)

DVR configuraton.

object

Configuration of authorization backend for play sessions.

Find more information about `on_play` and `on_publish` here.
object

Configuration of authorization backend for publish sessions.

any

Configuraton of Digital Rights Management system (DRM).

object

Configuration to allow/forbid playing the stream via various protocols.

  • If the whitelist option is set to 'true', the server allows a playback only for listed protocols;
  • If the whitelist option is set to 'false', the server forbids a playback for listed protocols;
  • Server allows a playback for all the protocols by default.
boolean or integer

The time (in seconds) that Media Server reserves for preloading the data, i. e. buffering. Prepush is always defined through GoP, but this option provides you with a more flexible way to configure the buffer size, e. g. a 1-3 or 7-10 seconds time interval.

The bigger the buffer size, the better the user experience is for the users with a bad internet connection. However, the latency also increases.

If set to False to remove the latency, the stream's start time increases. To decrease it, reduce the GoP size and make the bitrate higher or the video quality lower.

Find more information here
segment_count
integer

Number of segments stored in memory for the segment-based protocols, such as HLS and DASH. Added to HLS live manifest. Do not forget that one more segment is stored for stale clients that come too late, but the latest segment is not shown in the manifest.

segment_duration
integer <milliseconds> [ 1000 .. 15000 ]

The time of the segment duration. Used for the protocols like HLS or DASH. The disk config offers this value in seconds.

chunk_duration
integer <milliseconds>

Chunk duration in LL-HLS manifest to be used for tunning latency.

boolean or string

A string starting the addresses of separate segments within a segment-based playlists (HLS or DASH). Each sub-playlist is stored on Media Server.

If set to false, the configured value in a template will be disabled.

Find more information here
aws"aws" (any) or scte35"scte35" (any) or rfc8216"rfc8216" (any)

Whether to enable SCTE-35 ad insertion markers signaling in HLS manifest. Ad markers can be included in SCTE-35 (scte35), AWS (aws), EXT-X-DATERANGE (rfc8216) formats or not included (false).

Find more information here
add_audio_only
boolean

Whether to add an audio-only version of an HLS stream. Used to create App Store compliant HLS streams to deliver the content to Apple iOS devices.

Find more information here
object

WebRTC play configuration for a stream.

Array of RTMP (object) or Multicast MPEG-TS (object) or M4F (object) or M4S (object) or Decklink SDI (object) or Dektec SDI (object) or Dektec ASI (object) or HTTP MPEG-TS (object) or HLS (object) or SRT (object) or SMPTE 2110 (object)

A list of pushes. When a server initiates the connection and sends a stream to other server(s), it is called a push.

Find more information here
object

This parameter sets PIDs values for outgoing MPEG-TS streams. PID contains information about the TS package content and can be decoded according to special service tables. It is possible to set PID values for PMT, SDT, video, and audio tracks. Tracks are numbered starting from one. The code a1=123 sets a PID value for the first audio track. It is possible to set the base index for the tracks of a certain type using the 0 (zero) index. For example, t0=100 sets PID=101 for the first track, 102 for the second, and so on. Numbers can be given in decimal form (by default) or hexadecimal with 16# prefix.

object <= 10 items

Stream labels in key value format.

Array of objects (playback_headers) <= 10 items

This parameter sets playback HTTP headers for streams.

object
Deprecated Delete at: 23.12

The param is deprecated and now used only for onvif_url and onvif_profile options.

object

Video analytics parameters.

object (srt_config)

SRT publishing configuration for a stream.

object (srt_config)

SRT2 publishing configuration for a stream.

object (stream_config_stripped)

Part of the effective config from the configuration file.

autogenerated_episodes_close_timeout
integer <seconds> >= 0

This option has sense only for published streams. For all other behavior is undefined and unpredicted.

If the value is greater than 0, Central will generate episodes for the stream automatically based on the stream DVR ranges. Each range is considered an episode given that at least timeout seconds passed between these ranges.

An episode is created at the start of the publication and is closed after a timeout after the end of publication. If new publication started in less than timeout - two publications will be merged into one episode.

object (central_stream_layout)

Current layout of stream. Central will provide configuration to nodes based on this layout.

object

User-defined claims about the stream parameters. Set this field so that layouter can rely on this data when distributing streams.

Responses

Request samples

Content type
application/json
{
  • "comment": "This is a test stream",
  • "title": "Hockey channel",
  • "position": 2,
  • "template": "sports-hd",
  • "recheck_secondary_inputs_interval": 120,
  • "static": true,
  • "disabled": false,
  • "inputs": [
    ],
  • "input_media_info": {
    },
  • "provider": "SportsTV",
  • "dvbocr": "replace",
  • "source_timeout": 10,
  • "video_timeout": 20,
  • "audio_timeout": 20,
  • "max_retry_timeout": 30,
  • "backup": {
    },
  • "epg_enabled": true,
  • "mpegts_ac3": "keep",
  • "clients_timeout": 485,
  • "retry_limit": 0,
  • "transcoder": {
    },
  • "thumbnails": {},
  • "jpeg_snapshot_sign_key": "string",
  • "dvr": {
    },
  • "on_play": {
    },
  • "on_publish": {
    },
  • "drm": {},
  • "protocols": {
    },
  • "prepush": false,
  • "segment_count": 4,
  • "segment_duration": 5000,
  • "chunk_duration": 200,
  • "url_prefix": false,
  • "hls_scte35": "scte35",
  • "add_audio_only": true,
  • "webrtc_abr": {
    },
  • "pushes": [
    ],
  • "mpegts_pids": {
    },
  • "labels": {
    },
  • "playback_headers": [
    ],
  • "meta": {
    },
  • "vision": {
    },
  • "srt_publish": {
    },
  • "srt2_publish": {
    },
  • "config_on_disk": {
    },
  • "autogenerated_episodes_close_timeout": 0,
  • "layout": {
    },
  • "claims": {
    }
}

Response samples

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

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": [
    ]
}

Get layouts of stream

This method allows you to fetch stream layouts list

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: abc

Stream name

query Parameters
created_at_gt
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]
Example: created_at_gt=1730844572000

Get layouts created after this timestamp

created_at_lt
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]
Example: created_at_lt=1730844572000

Get layouts created before this timestamp

limit
integer
Example: limit=5

Limit the number of returned layouts

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": { },
  • "layouts": [
    ]
}

agent

List Agents

The list of configured and provisioned Agents, i.e. Agents that connected to your server at least once.

Authorizations:
bearerAuth
query Parameters
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. 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.

q
string
Example: q=filtered

Full-text search for agents

stream
string

Filter agents by stream presence. If any stream has the agent in its inputs, the agent will not be returned with filter stream_is=null.

Responses

Response samples

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

Get one Agent

The method allows you to fetch a single Agent. The returned data are the same as for agents_list operation.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: abc

Agent identifier

Responses

Response samples

Content type
application/json
{
  • "id": "1234567",
  • "key": "string",
  • "stats": {
    },
  • "layout": {
    }
}

Save Agent

Save the Agent parameters by the Agent ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: abc

Agent identifier

Request Body schema: application/json

Partial agent configuration

id
string

Agent identifier

key
string

Agent authentication key.

object

Current layout of agent. This field will be ignored for agents with an existing stream on update, use stream.layout instead. Central will provide configuration to nodes based on this layout.

Responses

Request samples

Content type
application/json
{
  • "id": "1234567",
  • "key": "string",
  • "layout": {
    }
}

Response samples

Content type
application/json
{
  • "id": "1234567",
  • "key": "string",
  • "stats": {
    },
  • "layout": {
    }
}

Delete Agent

Agent and corresponding camera(s) will be permanently deleted from the system.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: abc

Agent identifier

Responses

Reboot Agent

Reboot the Agent by the Agent ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: abc

Agent identifier

Responses

Reset Agent

Reset the Agent by the Agent ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: abc

Agent identifier

Responses

Disconnect Agent

Disconnect the Agent by the Agent ID.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: abc

Agent identifier

Responses

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": [
    ]
}

Get logs from Agent

The method allows you to fetch logs from online Agent.

Authorizations:
bearerAuth
path Parameters
id
required
string
Example: abc

Agent identifier

Responses

Response samples

Content type
application/json
{
  • "status": "ok",
  • "version": "version",
  • "agent_id": "1234567",
  • "cid": "42195",
  • "mid": "3059",
  • "serial": "a3dccd69f53deb79723a2a7a5f2037e1",
  • "main_url": "http://example.com",
  • "meminfo": "806400",
  • "buffer_limit": 0,
  • "buffer_size": 0,
  • "a": "VDEVSvaNZZWeNOXqi7tA5Hm+KAqBjfHQKMzMl5aqRdYxHZkSnJ",
  • "b": "xglytWCTztsbTAUVBIhQymqik7nvzXi5VbJWEQNBHFCxw/NdvY6hdknh87/3gslKpER0hIaymR67Qo8zGKICFN=="
}

config

Get configuration and stats of Central

This method allows you to fetch Central configuration and stats

Authorizations:
bearerAuth
query Parameters
Openmetrics"openmetrics" (string)
Example: format=openmetrics

This parameter is used instead of the Accept header to select of non-JSON response content format.

Responses

Response samples

Content type
{
  • "database": {
    },
  • "redis": {
    },
  • "listeners": {
    },
  • "edit_auth": {
    },
  • "api_key": "api_key",
  • "api_url": "http://central.ru:9019/streamer/api/v3",
  • "cluster": {
    },
  • "loglevel": "error",
  • "log_requests": "false",
  • "opentelemetry_url": "http://jaeger-server:14268/v1/traces?service_name=some-name",
  • "stats": {
    },
  • "server_id": "820efca4-4a15-4ab7-82fc-9e76f6d61325",
  • "layouter_enabled": "false",
  • "layouter_sleeping_interval": 30000,
  • "config_external_reconciliation_interval": 5000,
  • "episodes_buffer_delay": 3000,
  • "episodes_buffer_limit": 100
}

Update central configuration

This method allows you to update central configuration. Calling this method will update config file but will not change the env.

Authorizations:
bearerAuth
Request Body schema: application/json

Update config configuration

object

Credentials for administrator access to the server.

api_key
required
string

API_KEY is used to access Central API

api_url
string <url>

API URL used for setting the hostname and port under which Central is accessible by Flussonic for CONFIG_EXTERNAL and http_proxy requests

object

Describes how Сentral interacts with nodes in the cluster

None"none" (string) or Debug"debug" (string) or Info"info" (string) or Notice"notice" (string) or Warning"warning" (string) or Error"error" (string) or Alert"alert" (string) or Critical"critical" (string)

Set logging level

log_requests
string
Default: "false"

Enables logging HTTP-requests

opentelemetry_url
string <url>

URL (agent or collector) that is used to collect traces and spans with configuration in query parameters. FORMAT: http://{JAEGER-URL}?service_name={CENTRAL_NAME} (The prefix “central” will be added to the service name)

layouter_enabled
string
Default: "false"
Enum: "true" "false"

Enables layouter

layouter_sleeping_interval
number <milliseconds>
Default: 30000

Interval in milliseconds between layouter runs

config_external_reconciliation_interval
number
Default: 5000

You can use the default value or increase it to reduce server load, but increase time for the streamer to receive changes.

episodes_buffer_delay
number <milliseconds>
Default: 1000

Delay in milliseconds after which episodes from the buffer will be inserted into the database. Set 0 to disable buffer accumulation before inserting episodes into the database.

episodes_buffer_limit
number
Default: 250

Limit on the number of episodes in the buffer. If the number of episodes in the buffer exceeds the limit, the insertion into the database will be done instantly, regardless of the limit. Set 0 to disable buffer accumulation before inserting episodes into the database.

Responses

Request samples

Content type
application/json
{
  • "edit_auth": {
    },
  • "api_key": "api_key",
  • "api_url": "http://central.ru:9019/streamer/api/v3",
  • "cluster": {
    },
  • "loglevel": "error",
  • "log_requests": "false",
  • "opentelemetry_url": "http://jaeger-server:14268/v1/traces?service_name=some-name",
  • "layouter_enabled": "false",
  • "layouter_sleeping_interval": 30000,
  • "config_external_reconciliation_interval": 5000,
  • "episodes_buffer_delay": 3000,
  • "episodes_buffer_limit": 100
}

Response samples

Content type
application/json
{
  • "database": {
    },
  • "redis": {
    },
  • "listeners": {
    },
  • "edit_auth": {
    },
  • "api_key": "api_key",
  • "api_url": "http://central.ru:9019/streamer/api/v3",
  • "cluster": {
    },
  • "loglevel": "error",
  • "log_requests": "false",
  • "opentelemetry_url": "http://jaeger-server:14268/v1/traces?service_name=some-name",
  • "stats": {
    },
  • "server_id": "820efca4-4a15-4ab7-82fc-9e76f6d61325",
  • "layouter_enabled": "false",
  • "layouter_sleeping_interval": 30000,
  • "config_external_reconciliation_interval": 5000,
  • "episodes_buffer_delay": 3000,
  • "episodes_buffer_limit": 100
}

List API tokens

Method allows to fetch configured API tokens

Authorizations:
bearerAuth

Responses

Response samples

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

Get one API Token

Method allows to fetch single API token by name

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: vision

API token name

Responses

Response samples

Content type
application/json
{
  • "key": "string",
  • "name": "string",
  • "auth_scopes": [
    ],
  • "permissions": [
    ]
}

streamer

List streamers

Returns the list of all streamers with main parameters and current metric values.

Authorizations:
bearerAuth

Responses

Response samples

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

Get the streamer

This method allows you to fetch the main parameters and current metrics of a single streamer

Authorizations:
bearerAuth
path Parameters
hostname
required
string
Example: abc

Streamer hostname

Responses

Response samples

Content type
application/json
Example
{
  • "role": "streamer",
  • "hostname": "peer.example.com",
  • "stats": {
    },
  • "api_url": "http://streamer.local:8080",
  • "fetch_timeout": 1000,
  • "stale_timeout": 1000,
  • "channel_limit": 5,
  • "cpu_limit": 10,
  • "cluster_key": "xS6i6Q3DCc5nEvnu",
  • "max_bitrate": 0,
  • "public_payload_url": "http://public.example.com",
  • "private_payload_url": "http://streamer.local",
  • "dvrs": [
    ],
  • "config": {
    },
  • "total_bandwidth": 1024,
  • "labels": {
    }
}

Save the streamer

This method will either create a new streamer (if there is no streamer with the hostname specified in the request), or update the existing streamer having the specified hostname.

Authorizations:
bearerAuth
path Parameters
hostname
required
string
Example: abc

Streamer hostname

query Parameters
checks_enable
boolean
Default: false
Example: checks_enable=true

This flag enables some checks before saving streamer. List of checks:

  • Central can reach the streamer (get its config);

If a request with checks_enable=true is sent, then if at least one of the checks fails, the streamer will not be saved.

Request Body schema: application/json

Partial streamer configuration

required
"streamer" (string) or "inference" (string) or "identification" (string)

Role of node

api_url
string <url>

The URL for provisioning of configuration from the managing server to the streamer. This URL does not have to be public but must be accessible from the managing server.

The API URL can also be used as Public and/or Private payload URL if they are not set. When used as Public payload URL, the API URL shall be public to allow playback from this streamer.

fetch_timeout
integer <milliseconds>

How often the peer will try to get the data from the remote server via internal API.

stale_timeout
integer <milliseconds>

The time after which deleted streams on this server are considered to be inactive and cannot be used in the cluster_ingest mechanism.

channel_limit
integer

Maximal number of streams.

cpu_limit
integer <percent>

CPU limit in percents.

cluster_key
required
string

The key for authorization for inter-Flussonic connections. All cluster peers should have the same cluster key.

max_bitrate
integer <speed>
Deprecated Delete at: 23.09

Maximal output bitrate of the peer.

public_payload_url
string <url>

The public address that is exposed to clients. It can also contain a port number. The client will be redirected to this URL and port when requesting for the stream captured on the peer even if other http port is set in the peer's own config.

private_payload_url
string <url>

The internal address for communication in a local network (by default, it is equal to API URL).

object

Flussonic Media Server configuration which will be provided to Streamer

total_bandwidth
integer <speed>

Server network bandwidth limit in kbit. This value is used to calculate the current network load status.

object (central_streamer_labels)

Streamer labels in key value format.

Responses

Request samples

Content type
application/json
Example
{
  • "role": "streamer",
  • "api_url": "http://streamer.local:8080",
  • "fetch_timeout": 1000,
  • "stale_timeout": 1000,
  • "channel_limit": 5,
  • "cpu_limit": 10,
  • "cluster_key": "xS6i6Q3DCc5nEvnu",
  • "max_bitrate": 0,
  • "public_payload_url": "http://public.example.com",
  • "private_payload_url": "http://streamer.local",
  • "config": {
    },
  • "total_bandwidth": 1024,
  • "labels": {
    }
}

Response samples

Content type
application/json
Example
{
  • "role": "streamer",
  • "hostname": "peer.example.com",
  • "stats": {
    },
  • "api_url": "http://streamer.local:8080",
  • "fetch_timeout": 1000,
  • "stale_timeout": 1000,
  • "channel_limit": 5,
  • "cpu_limit": 10,
  • "cluster_key": "xS6i6Q3DCc5nEvnu",
  • "max_bitrate": 0,
  • "public_payload_url": "http://public.example.com",
  • "private_payload_url": "http://streamer.local",
  • "dvrs": [
    ],
  • "config": {
    },
  • "total_bandwidth": 1024,
  • "labels": {
    }
}

Delete the streamer

Delete the streamer by its hostname.

Authorizations:
bearerAuth
path Parameters
hostname
required
string
Example: abc

Streamer hostname

Responses

Dry run layouter for changed streamer configuration

This method allows you to see how the overall layout will be changed due to changes into streamer configuration. Note that if Layouter is disabled, this method will return an error.

Authorizations:
bearerAuth
path Parameters
hostname
required
string
Example: abc

Streamer hostname

Request Body schema: application/json

A changes into stream or streamer configuration

required
"streamer" (string) or "inference" (string) or "identification" (string)

Role of node

api_url
string <url>

The URL for provisioning of configuration from the managing server to the streamer. This URL does not have to be public but must be accessible from the managing server.

The API URL can also be used as Public and/or Private payload URL if they are not set. When used as Public payload URL, the API URL shall be public to allow playback from this streamer.

fetch_timeout
integer <milliseconds>

How often the peer will try to get the data from the remote server via internal API.

stale_timeout
integer <milliseconds>

The time after which deleted streams on this server are considered to be inactive and cannot be used in the cluster_ingest mechanism.

channel_limit
integer

Maximal number of streams.

cpu_limit
integer <percent>

CPU limit in percents.

cluster_key
required
string

The key for authorization for inter-Flussonic connections. All cluster peers should have the same cluster key.

max_bitrate
integer <speed>
Deprecated Delete at: 23.09

Maximal output bitrate of the peer.

public_payload_url
string <url>

The public address that is exposed to clients. It can also contain a port number. The client will be redirected to this URL and port when requesting for the stream captured on the peer even if other http port is set in the peer's own config.

private_payload_url
string <url>

The internal address for communication in a local network (by default, it is equal to API URL).

object

Flussonic Media Server configuration which will be provided to Streamer

total_bandwidth
integer <speed>

Server network bandwidth limit in kbit. This value is used to calculate the current network load status.

object (central_streamer_labels)

Streamer labels in key value format.

Responses

Request samples

Content type
application/json
Example
{
  • "role": "streamer",
  • "api_url": "http://streamer.local:8080",
  • "fetch_timeout": 1000,
  • "stale_timeout": 1000,
  • "channel_limit": 5,
  • "cpu_limit": 10,
  • "cluster_key": "xS6i6Q3DCc5nEvnu",
  • "max_bitrate": 0,
  • "public_payload_url": "http://public.example.com",
  • "private_payload_url": "http://streamer.local",
  • "config": {
    },
  • "total_bandwidth": 1024,
  • "labels": {
    }
}

Response samples

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

episode

List episodes

This method allows you to fetch registered episodes

Authorizations:
bearerAuth
query Parameters
select
string
Example: select=episode_id,media,close_reason

Comma-separated list of fields (including nested) that will be returned.

limit
integer
Example: limit=100

Limit select count in collection to N elements.

cursor
string
Example: cursor=JTI0cG9zaXRpb25fZ3Q9MQ==

Properly encoded analog of offset, allowing to read next bunch of items. We do not offer common offset fields, use cursor for predictable fetching of quickly changing list of items. Learn more in Flussonic API design principles.

episode_type
string
Example: episode_type=motion

Episode type

media
string
Example: media=cam-045

Filter the collection by media name on which the episode is registered

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

Filter the collection by episode update time. This field is rather specific because it allows to have an update stream with new/updated episodes

poll_timeout
integer <seconds>
Example: poll_timeout=30

Client may ask to delay a response if there are no episodes to fetch. This should be used as a long-poll mechanism for lightweight fetching episodes from origin.

dvr_presence_check
boolean
Default: false
Example: dvr_presence_check=true

Enables check of DVR presence on streamer for the episode.

Responses

Response samples

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

Get the episode

This method allows you to fetch the episode by its identifier

Authorizations:
bearerAuth
path Parameters
episode_id
required
integer <snowflake_id>

Episode's identifier

query Parameters
dvr_presence_check
boolean
Default: false
Example: dvr_presence_check=true

Enables check of DVR presence on streamer for the episode.

Responses

Response samples

Content type
application/json
Example
{
  • "episode_id": 0,
  • "media": "string",
  • "close_reason": "timeout",
  • "opened_at": 1000000000000,
  • "started_at": 1000000000000,
  • "updated_at": 1000000000000,
  • "closed_at": 1000000000000,
  • "preview_timestamp": 1000000000000,
  • "preview": "string",
  • "originator": {
    },
  • "episode_appearance_timestamps": {
    },
  • "has_dvr": null,
  • "episode_type": "generic"
}

Save the Episode

This method allows you to create a new episode or update attributes of the existing one

Authorizations:
bearerAuth
path Parameters
episode_id
required
integer <snowflake_id>

Episode's identifier

Request Body schema: application/json

A set of episode's attributes

episode_id
required
integer <snowflake_id>

Unique identifier of the episode. Must be created by the system that first creates this episode.

Please, mention that it is assumed to be 64 bit length including time of creation in it (refer to snowflake), so you cannot handle it in javascript with simple JSON.parse(), you need to use parsed that will properly handle very long integers.

media
required
string <media_name>

Stream name on which this episode exists.

Timeout"timeout" (string)

The reason for closing the episode.

opened_at
required
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]

The time when this episode was created. Naming is standard for whole flussonic ecosystem. Usually this time will be the same as started_at, but can differ, refer to the description of that field.

The value of this field is copied into episode_id, so sorting by episode_id will give you the same sort as by opened_at

started_at
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]

This field can be used as indication of the fact that some system have checked and ensured that this episode has really started at some time, that may differ from opened_at.

For example video analytics will use this field for the time when this episode was confirmed as confident.

May be not relevant for television systems.

updated_at
required
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]

The time of last change of the episode.

System that processes episodes and can send them to other systems, MUST update this field on any changes in this episode.

This field MUST be updated strictly monotonical and increasing. The updater MUST guarantee that this updated_at can be used as a sort key for fetching fresh updates.

Consumer of the episodes can use updated_at in the following scenario:

  • fetch all exisiting episodes from the source
  • take biggest updated_at from this dataset, it will be T
  • ask source for all episodes with updated_at > T

This algorithm can be used for fetching update stream from the source.

closed_at
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]

Episode emitter can decide that episode considered closed and will not grow further. closed_at MUST NOT change, it must be emitted only once.

Episode can live without closed_at, in this case you should use updated_at as the last time of the episode.

preview_timestamp
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]

The time when the preview of this episode is available. Use it to request preview image via Mediaserver's DVR API (jpeg_preview_dvr).

Visit the Getting JPEGs from DVR by specific time article and JPEG thumbnail from DVR section of the Mediaserver's API Reference for details.

This field may not be present. If so, you may use the timestamp from the started_at field to request the preview image

preview
string <base64> <base64>

Small inline image for previewing in UI

object

This describes the way this episode was updated, whether via an inference node or an API. In the case of an inference node, its hostname will be provided.

object

The time when the episode appeared in the service relative to the server time.

episode_type
string

Generic stream episode

Value: "generic"

Responses

Request samples

Content type
application/json
Example
{
  • "episode_id": 0,
  • "media": "string",
  • "close_reason": "timeout",
  • "opened_at": 1000000000000,
  • "started_at": 1000000000000,
  • "updated_at": 1000000000000,
  • "closed_at": 1000000000000,
  • "preview_timestamp": 1000000000000,
  • "preview": "string",
  • "originator": {
    },
  • "episode_appearance_timestamps": {
    },
  • "episode_type": "generic"
}

Response samples

Content type
application/json
Example
{
  • "episode_id": 0,
  • "media": "string",
  • "close_reason": "timeout",
  • "opened_at": 1000000000000,
  • "started_at": 1000000000000,
  • "updated_at": 1000000000000,
  • "closed_at": 1000000000000,
  • "preview_timestamp": 1000000000000,
  • "preview": "string",
  • "originator": {
    },
  • "episode_appearance_timestamps": {
    },
  • "has_dvr": null,
  • "episode_type": "generic"
}

Delete the Episode

This method allows you to delete an episode

Authorizations:
bearerAuth
path Parameters
episode_id
required
integer <snowflake_id>

Episode's identifier

Responses

vision

List Persons

The list of registered videoanalytics persons

Authorizations:
bearerAuth
query Parameters
select
string
Example: select=person_id,external_id

Comma-separated list of fields (including nested) that will be returned.

limit
integer
Example: limit=100

Limit select count in collection to N elements.

cursor
string
Example: cursor=JTI0cG9zaXRpb25fZ3Q9MQ==

Properly encoded analog of offset, allowing to read next bunch of items. We do not offer common offset fields, use please cursor for predictable fetching of quickly changing list of items. Learn more in Flussonic API design principles.

Responses

Response samples

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

Get the Person

This method allows you to fetch the person by its identifier

Authorizations:
bearerAuth
path Parameters
person_id
required
integer <snowflake_id>

Person's identifier

Responses

Response samples

Content type
application/json
{
  • "person_id": 0,
  • "external_id": "string",
  • "originator": "api",
  • "updated_at": 1637034282845,
  • "deleted_at": 1637095014573,
  • "fingerprints": [
    ],
  • "photos": [
    ]
}

Save the Person

This method allows you to create a new person or update attributes of the existing one

Authorizations:
bearerAuth
path Parameters
person_id
required
integer <snowflake_id>

Person's identifier

Request Body schema: application/json

A set of person's attributes

external_id
string

Identifier of the person in the external system. Use it when supplying the recognition results further into the external system (e.g. for access level check) if the person identifiers in the external system are different from the ones in Flussonic Identification database.

This field may contain null when video analytics detects a new person which explicitly has no association in the external system (i.e. if originator=identification_service).

required
api"api" (string) or identification_service"identification_service" (string)

Indicates the way this person was created: manually via an api or automatically in the identification service.

updated_at
required
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]

When this person was last updated

deleted_at
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]

When this person was marked as deleted

Array of objects (vision_face_fingerprint)

Digital fingerprints of the person. Videoanalytics makes digital fingerprint of the person using uploaded photos or videostreams being processed

Array of objects (vision_image_attributes)

Person's photos. External system uploads images which are being processed by videoanalytics to get digital fingerprint of the person

Responses

Request samples

Content type
application/json
{
  • "external_id": "string",
  • "originator": "api",
  • "updated_at": 1637034282845,
  • "deleted_at": 1637095014573,
  • "fingerprints": [
    ],
  • "photos": [
    ]
}

Response samples

Content type
application/json
{
  • "person_id": 0,
  • "external_id": "string",
  • "originator": "api",
  • "updated_at": 1637034282845,
  • "deleted_at": 1637095014573,
  • "fingerprints": [
    ],
  • "photos": [
    ]
}

Delete the Person

This method allows you to delete the person by its identifier

Authorizations:
bearerAuth
path Parameters
person_id
required
integer <snowflake_id>

Person's identifier

Responses

dvr

List of DVR configurations

This method allows to get the whole list of global DVR congifurations.

Authorizations:
bearerAuth

Responses

Response samples

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

config-external

Get streams for streamer

Return list of configured streams for the streamer

Authorizations:
bearerAuth
path Parameters
hostname
required
string
Example: flussonic.example.com

Streamer hostname

query Parameters
select
string
Example: select=name,inputs,dvr.root

Comma-separated list of fields (including nested) that will be returned. Use parent.child notation to mention nested (child) fields.

sort
string
Example: sort=-dvr.root,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.

q
string
Example: q=somepattern

Search pattern for text fields like name, title, urls, etc.

Responses

Response samples

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

Get dynamic streams for streamer

This API method will be called to fetch list of streams configurations for newly requested by user streams.

If you do not send a configuration of any stream named in name query parameter, it will be considered as an unknown and terminated immediately

Authorizations:
bearerAuth
path Parameters
hostname
required
string
Example: streamer03.my.cdn

Hostname of the streamer server that is requesting the config. This parameter is mandatory, because streamer will send it and you can rely on it, but it is absolutely ok to create several paths for different servers and ignore this query string.

query Parameters
name
required
string
Example: name=s01,s02,s03

Comma-separated expicitly passed list of stream names. Used to get configuration for the streams that were not listed in previous request without name field

cursor
string
Example: cursor=JTI0cG9zaXRpb25fZ3Q9MQ==

Properly encoded analog of offset, allowing to read next bunch of items. We do not offer common offset fields, use please cursor for predictable fetching of quickly changing list of items. Learn more in Flussonic API design principles.

Responses

Response samples

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

Get update streams for streamer

This API method will be called to fetch list of streams configurations.

Streamer will send here list of streams that were not enumerated in streams_list response.

Use this to shutdown unknown streams or dynamically configure streams.

If you do not send a configuration of any stream named in name query parameter, it will be considered as an unknown and terminated immediately

Authorizations:
bearerAuth
path Parameters
hostname
required
string
Example: streamer03.my.cdn

Hostname of the streamer server that is requesting the config. This parameter is mandatory, because streamer will send it and you can rely on it, but it is absolutely ok to create several paths for different servers and ignore this query string.

query Parameters
name
required
string
Example: name=s01,s02,s03

Comma-separated exlpicitly passed list of stream names. Used to get configuration for the streams that were not listed in previous request without name field

cursor
string
Example: cursor=JTI0cG9zaXRpb25fZ3Q9MQ==

Properly encoded analog of offset, allowing to read next bunch of items. We do not offer common offset fields, use please cursor for predictable fetching of quickly changing list of items. Learn more in Flussonic API design principles.

Responses

Response samples

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

External episodes

This method will return episodes for selected streams that should be left on disk during DVR cleaning process.

Authorizations:
bearerAuth
path Parameters
hostname
required
string
Example: flussonic.example.com

Streamer hostname

query Parameters
media
required
string
Example: media=s01,s02,s03

Requested list of streams. If some stream is not returned, then all content for this will be erased.

If you cannot fetch this information for any reasons and not sure that you are ready to delete all old DVR for the requested stream, better fail with

opened_at_lt
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]
Example: opened_at_lt=1645012045000

If you want to fetch episodes earlier than 1 day ago, you need to skip all new episodes, so you need those episodes, whose opened_at is in past, i.e. less than = lt then 1 day ago.

The meaning of this parameter is following: all episodes with time =< opened_at (opposite to requested) are very new and not interesting for the requester. Only old enough episodes with opened_at far in the past can be interesting to us.

closed_at_gt
integer <utc_ms> [ 1000000000000 .. 10000000000000 ]
Example: closed_at_gt=1645012045000

Streamer may use this field to skip asking for dozens of very old episodes that were fetched some requests ago. For example: it may take sense to ask for episodes in the period from 2 days ago to 1 day ago. Everything older is not interesting and it takes too much time to fetch it.

Use this query option to fetch only required subset of episodes, reduce requested dataset to only required small amount.

Responses

Response samples

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

UDP port to stream name

This API method will be called to find stream name by the port which received srt connection.

SRT protocol has two modes: when no stream name is passed in protocol, or when it is passed, but only if passwords match on both sides.

So you cannot rely on a stream name, because it is either not passed, either is password protected.

When you build a cloud, you cannot offer the same password to all clients, because it is just the same like without password.

This method allows some dynamic configuration when you wait for a client on a pool of servers on a fixed UDP port. When connection comes (publish/ingress of play/egress), your configuration backend will be called for resolving this UDP port to a stream configuration. Streamer will find out what is the name of the stream, its password and all other settings.

Authorizations:
bearerAuth
path Parameters
hostname
required
string
Example: streamer03.my.cdn

Hostname of the streamer server

port
required
integer (network_port) [ 0 .. 65535 ]
Example: 3000

Srt port which has received the connection

query Parameters
mode
required
string
Enum: "play" "publish"
Example: mode=publish

Configured mode of the listener, play or publish.

As SRT doesn't have any mandatory signalling in protocol: is this a play or a publish request, the pool of UDP ports has a mandatory configuration option: is it a play or a publish port.

When any connection is made to one of these ports, this mode is fetched from a configuration.

Responses

Response samples

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

events

Get events of Central

This method allows to get the batch of events. Currently this method is not implemented yet. However, its schema can be used for understanding Central logging.

Authorizations:
bearerAuth

Responses

Response samples

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

auth

List auth backends

This method allows to get the list of all authorization backends configured in Flussonic.

Authorizations:
bearerAuth

Responses

Response samples

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

Get the auth backend

This method allows to get a single authorization backend.

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: middleware_auth

Authorization backend name.

Responses

Response samples

Content type
application/json
{
  • "name": "string",
  • "allow_tokens": [
    ],
  • "deny_tokens": [
    ],
  • "allow_ips": [
    ],
  • "deny_ips": [
    ],
  • "allow_countries": [
    ],
  • "deny_countries": [
    ],
  • "allow_uas": [
    ],
  • "deny_uas": [
    ],
  • "backends": [],
  • "allow_default": false
}

Save the auth backend

Create or update an authorization backend. If you pass only a partial configuration, only the passed fields will be updated.

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: middleware_auth

Authorization backend name.

Request Body schema: application/json

Partial authorization backend configuration.

allow_tokens
Array of strings

Explicit list of tokens that give access to the content without any other checks.

deny_tokens
Array of strings

Explicit list of tokens that deny access to the content and stop any other checks.

allow_ips
Array of strings

Explicit list of IP-addresses or subnet masks that have access to the content without any other checks.

deny_ips
Array of strings

Explicit list of IP-addresses or subnet masks that are banned from accessing the content.

allow_countries
Array of strings

Explicit list of countries (two-letter country codes according to ISO 3166-1) that have access to the content without any other checks. Flussonic uses the MaxMind GeoLite2 Country database to map a country to a block of IP addresses. New releases of GeoIP2 databases come out more often than the releases of Flussonic server, so sometimes the used database can become outdated. Therefore we recommend you to install a separate GeoIP2 library and set up Flussonic to use it.

Find more information here
deny_countries
Array of strings

Explicit list of countries (two-letter country codes according to ISO 3166-1) that are banned from accessing the content. Flussonic uses the MaxMind GeoLite2 Country database to map a country to a block of IP addresses. New releases of GeoIP2 databases come out more often than the releases of Flussonic server, so sometimes the used database can become outdated. Therefore we recommend you to install a separate GeoIP2 library and set up Flussonic to use it.

Find more information here
allow_uas
Array of strings

Explicit list of user agents (set-top boxes or browsers) that have access to the content without any other checks.

deny_uas
Array of strings

The list of user agents (set-top boxes or browsers) that are banned from accessing the content.

Array of objects (auth_backend_url)

URL(s) of the HTTP backend(s).

allow_default
boolean
Default: false

This option defines the default behavior when all backends are not responding (usually, because of errors in HTTP responses) and the session is not started yet. If this option is enabled, all clients or devices except those listed in deny option will have access to the content. If this option is disabled, all clients or devices except those listed in allow option will not have access to the content.

Find more information here

Responses

Request samples

Content type
application/json
{
  • "allow_tokens": [
    ],
  • "deny_tokens": [
    ],
  • "allow_ips": [
    ],
  • "deny_ips": [
    ],
  • "allow_countries": [
    ],
  • "deny_countries": [
    ],
  • "allow_uas": [
    ],
  • "deny_uas": [
    ],
  • "backends": [],
  • "allow_default": false
}

Response samples

Content type
application/json
{
  • "name": "string",
  • "allow_tokens": [
    ],
  • "deny_tokens": [
    ],
  • "allow_ips": [
    ],
  • "deny_ips": [
    ],
  • "allow_countries": [
    ],
  • "deny_countries": [
    ],
  • "allow_uas": [
    ],
  • "deny_uas": [
    ],
  • "backends": [],
  • "allow_default": false
}

Delete the auth backend

Delete the authorization backend by its name.

Authorizations:
bearerAuth
path Parameters
name
required
string
Example: middleware_auth

Authorization backend name.

Responses

Play session authorization

This method describes what Flussonic sends to an authorization backend for playing session and what it awaits as a response.

Authorizations:
bearerAuth
query Parameters
name
required
string
Example: name=fake

Stream or VOD file name for this session.

proto
required
string
Example: proto=hls

Protocol for this session.

ip
required
string
Example: ip=10.77.0.150

IP address of the media client who initiated this session.

request_type
required
string
Enum: "new_session" "update_session"
Example: request_type=new_session

Is it a request for a new session or an update request.

The value new_session is used for a start of a new session and update_session - for an existing session.

request_number
required
integer <bytes>
Example: request_number=1

Counter of auth requests for this session, starting from 0.

session_id
required
string <uuid>
Example: session_id=6217fd62-16da-4206-9da9-0173d7552a14

Unique session id. It will be the same for one session.

stream_clients
required
integer
Example: stream_clients=1

How many clients are currently watching this stream or VOD file.

total_clients
required
integer
Example: total_clients=2

How many clients are currently watching from this server.

token
string
Example: token=60334b207baa

User provided authorization token.

The token is generated automatically or received from a website.

duration
integer <seconds>
Example: duration=2

If it is an update request, then it will be the duration of this session in seconds.

bytes
integer <bytes>
Example: bytes=12345

How many bytes have been passed in this session.

qs
string
Example: qs=token=60334b207baa

Here may go initial query string that was passed by client. Use it for additional authorization.

dvr
boolean
Example: dvr=true

Is it a session for playing DVR archive.

user_agent
string
Example: user_agent=curl%2F7.68.0

Many protocols can signal a user agent. It will be provided in this field.

referer
string
Example: referer=hey.com

Referer HTTP header that identifies the address of the web page from which the request was made.

host
string
Example: host=streamer03.my.cdn

A value of Host HTTP Header.

Responses

Response samples

Content type
application/json
{
  • "ad_inject": {
    },
  • "allowed_dvr_ranges": [
    ]
}

cluster

Get current health of cluster

This method allows you to fetch cluster's health

Authorizations:
bearerAuth
query Parameters
Openmetrics"openmetrics" (string)
Example: format=openmetrics

This parameter is used instead of the Accept header to select of non-JSON response content format.

Responses

Response samples

Content type
{
  • "version": 240100023,
  • "server_id": "123e4567-e89b-12d3-a456-426655440000",
  • "collected_at": 1000000000000,
  • "stream_metrics_total": {
    },
  • "agent_metrics_total": {
    },
  • "streamer_metrics_total": {
    },
  • "streamer_bitrate_metrics_total": {
    },
  • "streamer_metrics": [
    ]
}

monitoring

Liveness probe

K8s liveness probe.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "server_version": "23.04",
  • "build": 0,
  • "now": 1000000000000,
  • "started_at": 1639337825
}

Readiness probe

K8s readiness probe.

Authorizations:
bearerAuth

Responses

Response samples

Content type
application/json
{
  • "server_version": "23.04",
  • "build": 0,
  • "now": 1000000000000,
  • "started_at": 1639337825
}