Flussonic Streaming API (22.01.1-344)

Download OpenAPI specification:Download

This document describes possible URLs that can be accessed by a player for playing video streams and files by various protocols.

It is worth noting that parameter {name} used in this schema may be multi-segment, i.e.: /part1/part2/part3/index.m3u8 and name here will be /part1/part2/part3.

Authentication

tokenAuth

Token in query string just as defined in https://flussonic.com/doc/authorization/

Security Scheme Type API Key
Query parameter name: token

hls

HLS playback

HLS live and VOD

Main HLS URL that allows to play a live stream or a VOD file. This URL responds with master playlist.

Exact version of HLS is not defined here, it may vary according to different settings.

Authorizations:
path Parameters
name
required
string
Examples:
  • clock - Stream name example
  • vod/movies/bunny.mp4 - VOD file name example

The name of a stream or a VOD file. It may be multi-segment, i.e. /part1/part2/part3.

For a VOD file, it consists of the VOD storage name and a path to the file within the storage.

query Parameters
separate_audio
boolean
Example: separate_audio=true

Whether audio tracks are specified separately in the playlist.

This option is used for some players like Samsung TV or browsers supporting MSE that cannot switch between multiple audio tracks (for instance, for different languages) and, as a result, do not display such audio tracks. For such cases, Flussonic can create a playlist with separate audio.

thumbnails
integer
Example: thumbnails=100

This parameter is applicaple for a VOD file only (for a live stream, it is ignored).

If it is specified, the thumbnail playlist is added to the primary playlist. Example of the thumbnail playlist:

#EXT-X-IMAGE-STREAM-INF:BANDWIDTH=10000,RESOLUTION=320x180,CODECS="jpeg",URI="images-320x180/tpl-0-34-100.m3u8"

This value defines how many thumbnail links will be added to the thumbnail playlist to cover the file duration. The player will add the thumbnail links to the progress bar at regular intervals. The duration of the interval between thumbnails is the whole duration of the file divided by this value.

NOTE: This option requires the parameters thumbnails enabled=ondemand and size included in the VOD location settings. For example, thumbnails enabled=ondemand size=320x240;.

Responses

Response samples

Content type
No sample

HLS rewind

Nice combination of live and DVR HLS playlists.

This request gives something like HLS live playlist, but with lot of segments.

If the player understands that there are too many segments for a plain live playlist, it allows to rewind back into DVR window.

We recommend to take a look at Clappr player that supports this feature out of the box.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

ago
required
integer
Example: 7200

DVR window size in seconds. It is a duration of an HLS manifest in seconds, so your clients will be able to pause the stream up to this period or rewind it, for example, to the start of a TV show.

query Parameters
separate_audio
boolean
Example: separate_audio=true

Whether audio tracks are specified separately in the playlist.

This option is used for some players like Samsung TV or browsers supporting MSE that cannot switch between multiple audio tracks (for instance, for different languages) and, as a result, do not display such audio tracks. For such cases, Flussonic can create a playlist with separate audio.

Responses

Response samples

Content type
No sample

HLS DVR

If your stream is already recorded on the server with DVR, you can use this URL to play a specified DVR window, for example, you can play a telecast if you know its beginning and end from EPG.

This URL works in two modes: file and event. If depth is specified as now, this url will respond with a growing playlist for playing an event.

If depth is an exact positive number, then the server will respond with playlist, having this requested amount of seconds of video as a file.

Note the following rules:

  • The first segment in this playlist will not start earlier than from.
  • The last segment in this playlist will not start later than from + depth.

For example, two playlists: archive-1600000000-3600.m3u8 and archive-1600003600-3600.m3u8 will give the same result as archive-1600000000-7200.m3u8.

This URL is a recommended way to play DVR, because it allows pausing. If a player can seamlessly switch between different URLs, you can make seamless DVR playback with non-overlapping HLS DVR requests.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

from
required
integer
Example: 1641045644

The start time of the DVR window in UTC seconds.

required
integer or string

The duration of the DVR window in seconds. You also can specify now for a DVR window till current time.

query Parameters
separate_audio
boolean
Example: separate_audio=true

Whether audio tracks are specified separately in the playlist.

This option is used for some players like Samsung TV or browsers supporting MSE that cannot switch between multiple audio tracks (for instance, for different languages) and, as a result, do not display such audio tracks. For such cases, Flussonic can create a playlist with separate audio.

thumbnails
integer
Example: thumbnails=100

If this parameter is specified, the thumbnail playlist is added to the primary playlist.

Example of the thumbnail playlist:

#EXT-X-IMAGE-STREAM-INF:BANDWIDTH=10000,RESOLUTION=320x240,CODECS="jpeg",URI="images-320x240/tpl-1644304617-60-100.m3u8"

This value defines how many thumbnail links will be added to the thumbnail playlist to cover the requested duration of the DVR window. The player will add the thumbnail links to the progress bar at regular intervals. The duration of the interval between thumbnails is the whole duration of the DVR window divided by this value.

NOTE: This option requires the parameters thumbnails enabled=ondemand and size included in the stream settings. For example, thumbnails enabled=ondemand size=320x240;.

Responses

Response samples

Content type
No sample

HLS absolute timeshift

If your stream is already recorded on the server with DVR, you can use this URL to play the recorded stream by HLS starting at a specified moment of time. For example, you can use it for old STBs or viewing recoreded shows with EPG.

Please note that when you use the same timeshift URL several times, any additional requests use the same existing session. Therefore the time is not pure "absolute" and is still related to the current session. Therefore every time you request the same time, you get different part of the video. To solve this problem, you can change the token parameter in every new request to start a new session. For example:

  • http://FLUSSONIC-IP:80/CHANNEL-NAME/timeshift_abs-1430227800.m3u8?token=123 - the first request,
  • http://FLUSSONIC-IP:80/CHANNEL-NAME/timeshift_abs-1430227800.m3u8?token=124 - the second request, and so on.
Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

from
required
integer
Example: 1641045644

Start time of playing the DVR archive in UTC seconds.

query Parameters
separate_audio
boolean
Example: separate_audio=true

Whether audio tracks are specified separately in the playlist.

This option is used for some players like Samsung TV or browsers supporting MSE that cannot switch between multiple audio tracks (for instance, for different languages) and, as a result, do not display such audio tracks. For such cases, Flussonic can create a playlist with separate audio.

Responses

Response samples

Content type
No sample

HLS relative timeshift

If your stream is being recorded on the server with DVR, you can use this URL to play the recorded stream by HLS with a specified delay. This can be useful, for example, for TV broadcasting in different time zones, so that people in a different time zone watch morning broadcasts in the morning, and not late at night.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e., /part1/part2/part3.

ago
required
integer
Example: 7200

Delay in seconds.

For example, if it is 7200, the stream will be played with a two-hours (7200 seconds) delay.

query Parameters
separate_audio
boolean
Example: separate_audio=true

Whether audio tracks are specified separately in the playlist.

This option is used for some players like Samsung TV or browsers supporting MSE that cannot switch between multiple audio tracks (for instance, for different languages) and, as a result, do not display such audio tracks. For such cases, Flussonic can create a playlist with separate audio.

Responses

Response samples

Content type
No sample

HLS live and VOD tracks

Use this URL to play specified tracks of a live stream or a VOD file. It results in HLS media playlist as a list of segments. Each segment contains the specified tracks only.

Authorizations:
path Parameters
name
required
string
Examples:
  • clock - Stream name example
  • vod/movies/bunny.mp4 - VOD file name example

Media name. It may be multi-segment, i.e. /part1/part2/part3.

For live stream, it is the name of the stream. For VOD file, it consists of the VOD storage name and a path to the file within the storage.

tracks
required
string
Example: v1a1

Requested tracks

Responses

Response samples

Content type
No sample

Export MP4

This URL is a recommended way to export a fragment of a DVR archive to a local computer as an MP4 file.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

from
required
integer
Example: 1641045644

The start time of the DVR window in UTC seconds.

required
integer or string

The duration of the DVR window in seconds. You also can specify now for a DVR window till current time.

Responses

dash

DASH playback

DASH live and VOD

Main DASH URL that allows to play a live stream or a VOD file.

Authorizations:
path Parameters
name
required
string
Examples:
  • clock - Stream name example
  • vod/movies/bunny.mp4 - VOD file name example

The name of a stream or a VOD file. It may be multi-segment, i.e. /part1/part2/part3.

For a VOD file, it consists of the VOD storage name and a path to the file within the storage.

query Parameters
thumbnails
integer
Example: thumbnails=100

This parameter is applicaple for a VOD file only (for a live stream, it is ignored).

If it is specified, the thumbnail playlist is added to the primary playlist.

Example of the thumbnail playlist:

  <AdaptationSet id="3" mimeType="image/jpeg" contentType="image">
         <SegmentTemplate media="$RepresentationID$/seg-0-$Time$.m4v.jpg" duration="8"></SegmentTemplate>
         <Representation bandwidth="10000" id="images-320x180" width="320" height="180">
            <EssentialProperty schemeIdUri="http://dashif.org/guidelines/thumbnail_tile" value="1x1"/>
         </Representation>
  </AdaptationSet>

This value defines how many thumbnail links will be added to the thumbnail playlist to cover the file duration. The player will add the thumbnail links to the progress bar at regular intervals. The duration of the interval between thumbnails is the whole duration of the file divided by this value.

NOTE: This option requires the parameters thumbnails enabled=ondemand and size included in the VOD location settings. For example, thumbnails enabled=ondemand size=320x240;.

Responses

DASH rewind manifest

Nice combination of live and DVR DASH playlists.

This request gives a playlist with a wide sliding window that allows you to rewind DASH streams and pause them for many hours.

For example, the playlist "rewind-7200.mpd" allows your clients to pause the stream for up to 2 hours or rewind to the start of a TV show without using catchup URLs.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

ago
required
integer
Example: 7200

DVR window size in seconds. It is a duration of a DASH manifest in seconds, so your clients will be able to pause the stream up to this period or rewind it, for example, to the start of a TV show.

query Parameters
thumbnails
integer
Example: thumbnails=100

If this parameter is specified, the thumbnail playlist is added to the primary playlist.

Example of the thumbnail playlist:

 <AdaptationSet id="3" mimeType="image/jpeg" contentType="image">
         <SegmentTemplate media="$RepresentationID$/dvr-1648098000-$Time$.m4v.jpg" duration="72"></SegmentTemplate>
         <Representation bandwidth="10000" id="images-320x240" width="320" height="240">
            <EssentialProperty schemeIdUri="http://dashif.org/guidelines/thumbnail_tile" value="1x1"/>
         </Representation>
  </AdaptationSet>

This value defines how many thumbnail links will be added to the thumbnail playlist to cover the requested duration of the DVR window. The player will add the thumbnail links to the progress bar at regular intervals. The duration of the interval between thumbnails is the whole duration of the DVR window divided by this value.

NOTE: This option requires the parameters thumbnails enabled=ondemand and size included in the stream settings. For example, thumbnails enabled=ondemand size=320x240;.

Responses

DASH DVR

If your stream is already recorded on the server with DVR, you can use this URL to play a specified DVR window, for example, you can play a telecast if you know its beginning and end from EPG.

This URL works in two modes: file and event. If depth is specified as now, this url will respond with a growing playlist for playing an event.

If depth is an exact positive number, then the server will respond with playlist, having this requested amount of seconds of video as a file.

Note the following rules:

  • The first segment in this playlist will not start earlier than from.
  • The last segment in this playlist will not start later than from + depth.
Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

from
required
integer
Example: 1641045644

The start time of the DVR window in UTC seconds.

required
integer or string

The duration of the DVR window in seconds.

You also can specify now for a growing playlist till current time.

If from+depth is in the future, the playlist will grow as well until it reaches the specified moment.

query Parameters
period
string
Value: "mono"

Flussonic can create DASH manifest of two types: with multiple periods and with a single period.

By default, Flussonic creates a multi-period manifest. If there is a gap in playing a stream (for example, when the stream is restarted) or video quality changes, Flussonic starts a new period of playing, so there are multiple continuous periods in the resulting playlist.

However, such a manifest is incompatible with a wide range of devices and TV sets. In such cases you can specify period=mono option, i.e. http://FLUSSONIC-IP/STREAMNAME/archive-TIME-DURATION.mpd?period=mono. As a result, Flussonic will recalculate timestamps of all frames and join the parts of the interrupted video together into a single period.

Please note that this option should not work in the event mode because Flussonic cannot join a period in future.

thumbnails
integer
Example: thumbnails=100

If this parameter is specified, the thumbnail playlist is added to the primary playlist.

Example of the thumbnail playlist:

 <AdaptationSet id="3" mimeType="image/jpeg" contentType="image">
         <SegmentTemplate media="$RepresentationID$/dvr-1648098000-$Time$.m4v.jpg" duration="771"></SegmentTemplate>
         <Representation bandwidth="10000" id="images-320x240" width="320" height="240">
            <EssentialProperty schemeIdUri="http://dashif.org/guidelines/thumbnail_tile" value="1x1"/>
         </Representation>
  </AdaptationSet>

This value defines how many thumbnail links will be added to the thumbnail playlist to cover the requested duration of the DVR window. The player will add the thumbnail links to the progress bar at regular intervals. The duration of the interval between thumbnails is the whole duration of the DVR window divided by this value.

NOTE: This option requires the parameters thumbnails enabled=ondemand and size included in the stream settings. For example, thumbnails enabled=ondemand size=320x240;.

Responses

DASH absolute timeshift

If your stream is already recorded on the server with DVR, you can use this URL to play the recorded stream by DASH starting at a specified moment of time. For example, you can use it for old STBs or viewing recoreded shows with EPG.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

from
required
integer
Example: 1641045644

Start time of playing the DVR archive in UTC seconds.

query Parameters
thumbnails
integer
Example: thumbnails=100

If this parameter is specified, the thumbnail playlist is added to the primary playlist.

Example of the thumbnail playlist:

 <AdaptationSet id="3" mimeType="image/jpeg" contentType="image">
         <SegmentTemplate media="$RepresentationID$/dvr-1648098000-$Time$.m4v.jpg" duration="775"></SegmentTemplate>
         <Representation bandwidth="10000" id="images-320x240" width="320" height="240">
            <EssentialProperty schemeIdUri="http://dashif.org/guidelines/thumbnail_tile" value="1x1"/>
         </Representation>
  </AdaptationSet>

This value defines how many thumbnail links will be added to the thumbnail playlist to cover the requested duration of the DVR window. The player will add the thumbnail links to the progress bar at regular intervals. The duration of the interval between thumbnails is the whole duration of the DVR window divided by this value.

NOTE: This option requires the parameters thumbnails enabled=ondemand and size included in the stream settings. For example, thumbnails enabled=ondemand size=320x240;.

Responses

ll-hls

Apple Low-Latency HLS playback

LL-HLS live manifest

Use this URL to play a stream via Apple Low-Latency HLS.

To play a stream via this protocol, you should enable CMAF in the stream settings. CMAF is a standard that is used to create MP4 fragments compliant with the Low-Latency HLS specification.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

Responses

radio

Playing audio streams

SHOUTcast playlist

Use this URL to play audio streams via SHOUTcast protocol which is used for streaming audio over an HTTP connection.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

Responses

mpegts

Playing and publishing HTTP MPEG-TS video

HTTP-MPEGTS playback

Use this URL to play a stream via HTTP-MPEGTS protocol.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e., /part1/part2/part3.

Responses

HTTP-MPEGTS publishing

Use this URL to publish an HTTP MPEG-TS stream.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e. /part1/part2/part3.

Request Body schema: video/mpeg

Published HTTP-MPEGTS chunked transfer live stream.

string

Responses

HTTP-MPEGTS absolute timeshift

If your stream is being recorded on the server with DVR, you can use this URL to play the recorded stream by HTTP-MPEGTS starting at a specified moment of time. For example, you can use it for old STBs or viewing recoreded shows with EPG.

Authorizations:
path Parameters
name
required
string
Example: clock

Stream name. It may be multi-segment, i.e., /part1/part2/part3.

from
required
integer
Example: 1641045644

Start time of playing the DVR archive in UTC seconds.

Responses

HTTP-MPEGTS relative timeshift

If your stream is being recorded on the server with DVR, you can use this URL to play the recorded stream by HTTP-MPEGTS with a specified delay. This can be useful, for example, for TV broadcasting in different time zones, so that people in a different time zone watch morning broadcasts in the morning, and not late at night.