API docs by Redocly

Flussonic Configuration Backend API (22.12.1)

Download OpenAPI specification:Download

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

Intro

This API describes how Flussonic streaming server fetches runtime stream configuration from backend written by user. So, this it not an API to Flussonic, this is an API, that Flussonic is using to connect to other system.

Permanent download link to JSON schema file.

What can you do with this API?

You can make full control over streams in Flussonic without modifying config file. This is a preferrable way to integrate streaming server into complex systems.

You can launch static streams that will work without client requests and you can dynamically control each request to the stream that is not known to server.

This API was designed with the idea in mind that you may have hundreds and thousands of streaming server and have millions of streams in your database. None of the streaming servers can even know the full amount of streams, but each of them can have access to any stream if required.

How does it work?

  1. You implement your own configuration backend that responds with a list of streams that must be launched on Flussonic Media Server with their configuration.
  2. Flussonic each several seconds make a request to get all streams that must be running on this server in static mode, i.e. without any user requests
  3. After this Flussonic will take all streams that were not listed in #2 and will send another several requests with name query string (comma-joined stream names) to check streams. If you do not respond with their configuration, they will be closed.
  4. When user requests to play or publish to an unknown stream, Flussonic will make another request with name in query string.

Scenarios examples

Transcoder load balancing

You can monitor server load and store it in centralized database. This information cancan be used to distribute streams across streaming servers.

Publish transcoding load balancing

You have several servers that can be used for accepting incoming publishing.

Use transcoder usage statistics to push incoming published streams to least loaded transcoder.

Failover configuration

Use some fault-tolerant system like etcd for keeping streams information and launch copy of your backend near each Flussonic.

It is impossible to configure more than one configuration backend to Flussonic and will not be. Use local copy of database for failure resistency.

Performatnce requirements

Your configuration backend must be fast, consider targeting 100 ms on whole response. Use ram database, optimized JSON generation, etc.

If you have 10 flussonic instances and you have configured single configuration backend, then you will have more than 3 requests per second. If you have configured single core for this responses and you use more than 300 ms (real life examples), then Flussonics will start delaying in receiving new updates.

stream

Static streams

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

Your system must responce to this call to be able to dynamically configure streaming server in runtime, add streams, reconfigure them or remove.

Authorizations:
bearerAuth
query Parameters
host
required
string
Example: host=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.

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

Update streams

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
query Parameters
host
required
string
Example: host=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.

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

Dynamic streams

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
query Parameters
host
required
string
Example: host=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.

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

srt

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
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.

host
required
string
Example: host=streamer03.my.cdn

Hostname of the streamer server

Responses

Response samples

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

dvr

External episodes

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

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