Flussonic Media Server Documentation

HTTP API to Flussonic Media Server

On this page:

Authentication and authorization

With Flussonic API you can retrieve data and manage certain Flussonic features over HTTP.

Requests for information can be protected by using the view_auth user password; directive in the configuration file /etc/flussonic/flussonic.conf.

Requests for modification of a state and settings can be protected by using the edit_auth user password; directive in the configuration file.

To access the HTTP API, with authentication active you need to use a login and password in HTTP Basic Auth format.


Server information (server)

Information about Flussonic server.

URL: /flussonic/api/server

Example: http://example.flussonic.com:8080/flussonic/api/server

Parameters: none

Response: JSON like

{
    "version": "4.6.1", // Flussonic server version
    "hostname": "streamer.example.com", // hostname
    "uptime": 43373, // Current Flussonic uptime in seconds
    "total_clients": 1592, // Total clients number
    "total_streams": 100, // Total streams number
    "online_streams": 95, // Total active streams number
    "input_kbit": 1234, // Current inbound speed
    "output_kbit": 123456 // Current outbound speed
}

The list of streams, their clients and state (media)

State and configuration of streams, number of clients.

You can request all streams or specify only some streams separated by comma.

To get the list of all streams:

URL: /flussonic/api/media

Parameters:  none

To get the list of specified streams only:

URL: /flussonic/api/media?name=STREAMNAME

URL: /flussonic/api/media?name=STREAMNAME1,STREAMNAME2

Parameters:

  • name=STREAMNAME — stream name. Optional parameter

Response: JSON like

[
    {
        "entry": "stream",
        "value": {
            "name": "bunny",
            "urls": [
                {
                    "value": "file://vod/bunny.mp4",
                    "options": []
                }
            ],
            "stats": {
                "alive": true,
                "bitrate": 140,
                "bufferings": 0,
                "bytes_in": 13885409,
                "bytes_out": 0,
                "client_count": 0,
                "dvr_enabled": false,
                "input_error_rate": 0,
                "input_media_info": {
                    "title": "bunny",
                    "tracks": [
                        {
                            "bitrate": 96,
                            "codec": "h264",
                            "content": "video",
                            "fps": 24,
                            "gop_size": 41,
                            "height": 160,
                            "lang": "eng",
                            "last_gop": 48,
                            "level": "3.0",
                            "pix_fmt": "yuv420p",
                            "pixel_height": 160,
                            "pixel_width": 240,
                            "profile": "Baseline",
                            "sar_height": 1,
                            "sar_width": 1,
                            "track_id": "v1",
                            "width": 240
                        },
                        {
                            "bitrate": 55,
                            "channels": 2,
                            "codec": "aac",
                            "content": "audio",
                            "gop_size": 0,
                            "lang": "eng",
                            "last_gop": 0,
                            "sample_rate": 48000,
                            "track_id": "a1"
                        }
                    ]
                },
                "last_access_at": 1596712205723,
                "last_dts": 1596712226498.0117,
                "last_dts_at": 1596712226500,
                "lifetime": 510430.01171875,
                "media_info": {
                    "title": "bunny",
                    "tracks": [
                        {
                            "bitrate": 84,
                            "codec": "h264",
                            "content": "video",
                            "fps": 24,
                            "gop_size": 39,
                            "height": 160,
                            "lang": "eng",
                            "last_gop": 48,
                            "level": "3.0",
                            "pix_fmt": "yuv420p",
                            "pixel_height": 160,
                            "pixel_width": 240,
                            "profile": "Baseline",
                            "sar_height": 1,
                            "sar_width": 1,
                            "track_id": "v1",
                            "width": 240
                        },
                        {
                            "bitrate": 56,
                            "channels": 2,
                            "codec": "aac",
                            "content": "audio",
                            "gop_size": 0,
                            "lang": "eng",
                            "last_gop": 0,
                            "sample_rate": 48000,
                            "track_id": "a1"
                        }
                    ]
                },
                "out_bandwidth": 0,
                "remote": false,
                "retry_count": 0,
                "running": true,
                "running_transcoder": false,
                "start_running_at": 1596711716042,
                "ts_delay": 648,
                "url": "file://vod/bunny.mp4"
            },
            "options": {
                "disabled": false,
                "static": true,
                "title": "bunny",
                "add_audio_only": false,
                "retry_limit": 10,
                "clients_timeout": 60,
                "source_timeout": 60,
                "dvr_locked_write": false,
                "dvr_offline": false,
                "dvr_protected": false,
                "epg_enabled": false,
                "groups": [],
                "motion_detector_enabled": false,
                "no_index": false,
                "pulse_off": false,
                "thumbnails_enabled": false,
                "vision_enabled": false
            }
        }
    }
]


Stream information (media_info)

Information about specific stream: width, height, tracks.

URL: /flussonic/api/media_info/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name. (required)

Response: JSON like

{
    "width":1024,   //image width
    "height":576,   //image height
    "streams":[   //list of elements of this stream
        {
            "content":"video",   //content type is video
            "codec":"h264",   //codec is h264
            "track_id":1   //track number. elements are sorted on this field
        },
        {
            "content":"audio",   //content type is audio
            "codec":"aac",   //codec is AAC
            "lang":"ukr",   //language is Ukrainian
            "track_id":2   //track number
        },
        {
            "content":"audio",   //content type is audio
            "codec":"aac",   //codec is AAC
            "lang":"rus",   //language is Russian
            "track_id":3   //track number
        }
    ]
}

Clients authorized to watch a stream can request its info:

curl http://192.168.2.3:8080/ort/media_info.json

{"width":320,"height":240,"streams":[{"size":"320x240","content":"video","codec":"h264","bitrate":115,"track_id":1,"fps":25.0,"width":320,"height":240,"pixel_width":320,"pixel_height":240,"sar_width":1,"sar_height":1,"length_size":4,"profile":"Baseline","level":"2.1"},{"content":"audio","codec":"aac","bitrate":25,"track_id":2}]}

Information about the original stream (input_media_info)

Information about the original incoming stream before it is transcoded.

URL: /flussonic/api/input_media_info/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name. (required)

Response: JSON like

{
    "height": 240,
    "streams": [
        {
            "codec": "h264",
            "content": "video",
            "fps": 25,
            "height": 240,
            "length_size": 4,
            "level": "2.1",
            "pixel_height": 240,
            "pixel_width": 320,
            "profile": "Baseline",
            "sar_height": 1,
            "sar_width": 1,
            "size": "320x240",
            "track_id": "v1",
            "width": 320
        },
        {
            "bitrate": 25,
            "codec": "aac",
            "content": "audio",
            "lang": "eng",
            "track_id": "a1"
        }
    ],
    "width": 320
}

If no transcoding is performed then API responds with an error:

{
    "error": "no_transcoder"
}

Stream quality and stream health (stream_health)

The HTTP status code in the response indicates when recent frames were registered in the stream.

URL: /flussonic/api/stream_health/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name (required)

Response:

  • HTTP 200 — STREAM_NAME exists and the last frame in it is relatively recent (less than one second ago)
  • HTTP 424 — stream exists but there are no recent frames.

URL is useful for monit, for example:

check process flussonic
start program = "/etc/init.d/flussonic start"
stop  program = "/etc/init.d/flussonic stop"
if failed host localhost port 8080
protocol HTTP request "/flussonic/api/stream_health/cam0" then restart
if 5 restarts within 5 cycles then timeout

The list of active files (files)

A list of currently active files and the number of clients that watch them.

URL: /flussonic/api/files

Parameters:  none

Response: JSON like

{
    "files":[   //list of files that are currently active
        {
            "name":"vod/ir.mp4",    //internal identifier with a prefix
            "worker_count":1, //number of reading streams
            "client_count":1,    //number of clients (viewers)
            "url":"priv/ir.mp4",    //path on HDD or an external storage
            "bytes_out":1792522,    //number of transmitted bytes
            "bytes_in":1792522,    //number of read bytes
            "prefix":"vod"    //prefix of this file
        }
    ]
}

The number of open sessions (sessions)

Number of open sessions, that is, connections between clients and server.
If client pauses playback or automatic video playback start (autoplay) is disabled, then after a while the session will be closed.

URL: /flussonic/api/sessions

Parameters:  none

Response: JSON like

{
    "sessions":[
        {
            "id":"3100c9414a8666450a47246520a921076f4738e5",
            //session identifier (it is NOT unique!)
            "session_id":
            "3100c9414a8666450a47246520a921076f4738e5-1396588629135",
            //unique session identifier
            "ip":"127.0.0.1",    //client IP
            "name":"vod/ir.mp4",    //internal identifier with a prefix
            "created_at":1396588629135,    //session start time
            "duration":5109,    //session duration
            "type":"hds",    //stream type
            "bytes_sent":828010,    //the number of transmitted bytes
            "country":"NONE",    //GeoIP location of a current user (viewer)
        }
    ]
}

If you want to display a list of connections for a single file, you may

add a name of this stream to a query string: /flussonic/api/sessions?name=vod/ir.mp4


The list of open sessions for a specific stream (sessions+stream_name)

A list of sessions that are open for the specified stream.

URL: /flussonic/api/sessions?name=STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name. (required)

Response: JSON like

{
    "name":"euro",    //stream name
    "sessions":[    //list of sessions
        {
            "id":"e927bf4dca1ea90622318d4b4a0a60ab650bc6d9",
            //session identifier (it is NOT unique!)
            "session_id":
            "e927bf4dca1ea90622318d4b4a0a60ab650bc6d9-1396867792624",
            //unique session identifier
            "ip":"127.0.0.1",    //client IP
            "name":"euro",    //stream name
            "created_at":1396867792624,    //session start time
            "duration":30614,    //session duration
            "type":"hls",    //type of this stream
            "bytes_sent":5712330,    //the number of transmitted bytes
            "country":"NONE"    //GeoIP location of a current user (viewer)
        }
    ]
}

Closing a session (session_close)

To close several active sessions, you need to pass a list of their identifiers as POST request body. Use \n as delimiter.

URL: /flussonic/api/close_sessions

Parameters: 

  • HTTP request payload — list of session identifiers joined by \n (required)

Response: code 200

Playlist status information

You can request information about the state of a server-side playlist of the specified stream.

URL: /flussonic/api/playlist/STREAM_NAME

Example: http://example.flussonic.com:8080/flussonic/api/playlist/example_stream

Parameters: 

  • STREAM_NAME — the name of a stream that contains the playlist (required)

Response: JSON like

{
    "current_entry":"vod/ir.mp4",   //The currently played item
    "current_type":"file",   //The type of the currently played item
    "duration":null,   //Duration of the current item, in milliseconds('null' stands for 'undefined')
    "position":5.22e4   //Currently played position inside the current item, in milliseconds
}

Recordings map (dvr_status)

DVR recording map for a particular day, consisting of segmengs and seconds.

URL: /flussonic/api/dvr_status/YEAR/MONTH/DAY/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name. (required)
  • YEAR — year (required)
  • MONTH — month (required)
  • DAY — day (required)

Response: JSON like

[   //list of blocks
    {
        "timestamp":1396864800,    //timestamp of a block
        "path":"2014/04/07/10/00",    //path of recording on hdd
        "bitrate":2052,    //Битрейт
        "segments":[
            {
                "second":1,    //starting from this second after beginning of a block
                "utc":1396864801,    //segment timestamp
                "duration":5357,    //segment duration
                "size":1383868,    //size in bytes
                "bitrate":2066,    //bitrate
                "jpeg":"2014/04/07/10/00/01.jpg"    //screenshot of a current segment
            },

            {"second":6,"utc":1396864806,"duration":7211,
            "size":1842964,"bitrate":2044,
            "jpeg":"2014/04/07/10/00/06.jpg"},

            {"second":13,"utc":1396864813,"duration":7109,
            "size":1739188,"bitrate":1957,
            "jpeg":"2014/04/07/10/00/13.jpg"}
        ]
    }
    {"timestamp":1396865400,"path":"2014/04/07/10/10","bitrate":1964,
    "segments":[ {"second":0,"utc":1396865400,"duration":7194,
    "size":1800664, "bitrate":2002,"jpeg":"2014/04/07/10/10/00.jpg"}]}
]

Deleting fragments of a DVR archive

This call enables you to forcibly delete a part of a DVR archive. Locked intervals are also deleted by this call.

This call supports both local and cloud DVR storages. If the specified interval is a part of the archive that was copied to a remote storage (Amazon S3) with copy=[REMOTE PATH], it is downloaded to Flussonic to delete appropriate segments and then is copied back to the remote storage.

URL: /flussonic/api/dvr/delete

POST request parameters:

  • stream — stream name.
  • from — time in UTC of the beginning of the interval that you want to delete.
  • duration — the duration of the interval that you want to delete, in seconds.

Usage example:

curl -u USER:PASS --data '{"stream":"ort","from":1483971680,"duration":1000}' http://FLUSSONIC-IP/flussonic/api/dvr/delete

The list of VOD files (list_files)

List of available files for a specific prefix and path.

URL: /flussonic/api/list_files?prefix=VOD_LOCATION&path=VOD_ROOT&subpath=SUB_PATH_IN_VOD_ROOT&from=FirstName&limit=COUNT

Parameters:

  • VOD_LOCATION — VOD prefix. (required)
    Web interface: the list of prefixes is displayed on the main page in Files (VOD) section.
    Configuration file: file vod {...};.
  • VOD_ROOT — VOD root. (required)
    Web interface: The list of sources (storages) for a prefix is displayed in corresponding tab of Files (VOD) section. New source can be added in New Path field.
    Configuration file: "path" elements in file vod { path priv };.
    VOD root can be an address of swift storage and start with swift://.
  • SUB_PATH_IN_VOD_ROOT — location inside VOD_ROOT. (required)
    For root of a storage it equals /
  • FirstName — the list of files that start from this name. You can just specify the beginning of the file name. (optional)
    The response will not contain FirstName itself.
  • COUNT — the maximum number of files in the query. (optional)
    If it is used with FirstName, the response will contain COUNT files starting with FirstName (excluding FirstName itself).

Response: JSON like

{
    "files":[   //list of files
        {
            "name":"0.fla",   //file name
            "type":"file",   //type of the file ("file" or "directory")
            "prefix":"vod"   //prefix
        },
        {"name":"1.fla","type":"file","prefix":"vod"},
        {"name":"10.fla","type":"file","prefix":"vod"}
    ]
}

Saving a new configuration file (save_config)

To update the Flussonic configuration, you need to pass the text of the new configuration file as a POST request body.

An important difference from update_config is that the new configuration is not only applied to a running server, but also replaces the existing configuration file /etc/flussonic/flussonic.conf.

URL: /flussonic/api/save_config

Parameters:

  • HTTP request payload — the text of the new configuration file (required).
    For example, for curl, this parameter is --data-binary:
    curl ... --data-binary '# Global settings:\nhttp 80;\nrtsp 554;\nrtmp 1935;\npulsedb /var/run/flussonic;'

Response: true if the request was processed successfully


Updating the configuration file (update_config)

To update the Flussonic configuration, you need to pass the text of the new configuration file as a POST request body.

An important difference from save_config is that the new configuration is applied to a running server, but the configuration file on disk does not change.

URL: /flussonic/api/update_config

Parameters:

  • HTTP request payload — the text of a new configuration file (required)
    For example, for curl, this parameter is --data-binary:
    curl ... --data-binary '# Global settings:\nhttp 80;\nrtsp 554;\nrtmp 1935;\npulsedb /var/run/flussonic;'

Response: true if the request was processed successfully


Removing a stream (config/stream_delete)

To delete a stream, you need to pass its name as the POST request body.

URL: /flussonic/api/config/stream_delete

Parameters:

  • HTTP request payload — stream name (required) For example, for curl, this parameter is --data-binary: curl ... --data-binary 'mystream'

Response: {"success":true} if the request was processed successfully


Creating and updating a stream (config/stream_create)

To update stream configuration, you need to pass the text with the stream settings as POST request body. It is exacly the same text you would use to add a new stream to the configuration file.
Warning: At the moment there is no separate config / stream_update command, so the existing stream can be updated with theconfig / stream_create query.

URL: /flussonic/api/config/stream_create

Parameters:

  • HTTP request payload — text of a stream configuration (required) For example, for curl, this parameter is --data-binary:
    curl ... --data-binary 'stream mystream { url hls://myvideo.com/mystream; dvr /storage 1d 1G; }'

Response: {"success":true} if the request was processed successfully


Reloading the configuration file (reload)

You must perform this query to apply the new configuration to a running server if you have made changes to the configuration file /etc/flussonic/flussonic.conf.

URL: /flussonic/api/reload

Parameters: none

Response: true if the request was processed successfully

Example that uses curl to run the call: curl -u admin:pass0 http://flussonic:8080/flussonic/api/reload


Restarting a stream (stream_restart)

Full restart of a specific stream. May be useful in a case of broken source.

URL: /flussonic/api/stream_restart/STREAM_NAME

Parameters:

  • STREAM_NAME — stream identifier (required)

Response: true if the request was processed successfully


Switching stream source (stream_switch_source)

Use new source for the stream.

URL: /flussonic/api/stream_switch_source/STREAM_NAME?url=SOURCE_URL

Parameters:

  • STREAM_NAME — stream identifier. (required)

  • SOURCE_URL — New source URL. Must be present among configured sources of the stream. (required)


Enabling the DVR module (dvr_enable)

Pre-requisite: the option dvr or dvr_offline must be specified in stream settings.

URL: /flussonic/api/dvr_enable/STREAM_NAME

Parameters:

  • STREAM_NAME — stream identifier (required)

Response: true if the request was processed successfully


Disabling the DVR module (dvr_disable)

Stops writing a stream into archive.

URL: /flussonic/api/dvr_disable/STREAM_NAME

Parameters:

  • STREAM_NAME — stream identifier (required)

Response: true if the request was processed successfully


Information about servers in a cluster (cluster_servers)

Gets the information about Flussonic servers in a cluster.

URL: /flussonic/api/cluster_servers

Parameters: none

Response: JSON like

{
    "streamer-2": //streamer name
        {
            "client_count":0, //current count of clients
            "config2":true,
            "cpu_usage":1, //CPU usage value in percentage
            "fetch_delay":0,
            "id":"91a25b1a-22f0-414b-858f-4abc727d0de2",
            "is_peer":true,
            "is_source":false,
            "key":"WzkF7f9VYndoH6G3VOVz6iSNlOh4h8CF", //Cluster key
            "memory_usage":26, //Memory usage value in percentage
            "output_bitrate":0, //Summary output bitrate
            "persistent":true,
            "ports":{ //list of streaming ports
                "http":80,
                "rtmp":1935
                },
            "stream_count":0, //current count of active streams
            "uptime":251908, //uptime in seconds
            "version":"4.7.3" //verson of Flussonic
        }
}

Using deprecated API calls

Important. If you use deprecated calls such as 'get_config' or 'config/stream_list', then please enable the environmental variable FLUSSONIC_OLD_CONFIG:

  1. Edit Flussonic service unit file (/lib/systemd/system/flussonic.service) — do it by using the systemd's override mechanism.

    # systemctl edit flussonic
    

    This command opens a text editor (nano by default).

  2. Add these lines:

    [Service]
    Environment=FLUSSONIC_OLD_CONFIG=true
    

    Press Ctrl-X, then Y to save and exit.

  3. Restart Flussonic:

    # /etc/init.d/flussonic restart