Flussonic Media Server documentation

Contents

HTTP API to Flussonic Media Server

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.

URL: /flussonic/api/media

Parameters:  none

Reply: JSON like

[ //list of streams
  {
    "entry": "stream",
    "value": {
      "name": "euro", //stream name
      "urls": [ //list of sources
        {
          "value": "tshttp://192.168.1.2:6502", //source URL
          "options": [ //source switching options
            [
              "priority",
              "1"
            ],
            [
              "source_timeout",
              "30"
            ]
          ]
        }
      ],
      "stats": {
        "alive": true, //true if there are recent frames in the stream
        "bitrate": 3690, //biteate
        "bufferings": 0,
        "client_count": 0, //number of clients (viewers) of this stream
        "dash": true, //DASH enabled
        "hds": true, //HDS enabled
        "hls": true, //HLS enabled
        "input_error_rate": 0, //number of errors registered per second
        "last_access_at": 1493279230436,
        "media_info": { //stream content info
          "height": 576, //image height
          "streams": [
            {
              "bitrate": 191, //biteate
              "codec": "mp2a", //codec
              "content": "audio", //content type:audio
              "lang": "eng", //language
              "track_id": "a1" //track number
            },
            {
              "bitrate": 3256, //bitrate
              "codec": "mp2v", //codec
              "content": "video", //content type: video
              "size": "1024x576", //image size
              "track_id": "v1" //track number
            }
          ],
          "width": 1024 //image width
        },
        "out_bandwidth": 4002, //out bandwidth
        "push_stats": { //stream copy statistisc, bytes
          "tshttp://container4:8080/static1/mpegts": 2000918592
        },
        "remote": false, //the stream is not repeated from another Flussonic
        "retry_count": 0, //number of automatic retries
        "running": true, //stream is being broadcased, does not necessarily mean there are frames in the stream
        "start_running_at": 1493279194382,
        "ts_delay": 113, //milliseconds since the most recent frame in the stream 
        "url": "tshttp://192.168.1.2:6502" //URL of current source
      },
      "options": { //stream configuration
        "static": false, 
        "retry_limit": 10,
        "clients_timeout": 60,
        "source_timeout": 60,
        "pushes": [ 
          [
            "tshttp://container4:8080/static1/mpegts"
          ]
        ],
        "add_audio_only": false,
        "dash_off": false,
        "dvr_protected": false,
        "hds_off": false,
        "hls_off": false,
        "m4f_off": false,
        "m4s_off": false,
        "mpegts_off": false,
        "pulse_off": false,
        "rtmp_off": false,
        "rtsp_off": false,
        "webrtc_off": 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 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

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
        }
    ]
}

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


List of open sessions for a specific stream (sessions+stream_name)

A list of sessions that are open to 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)
        }
    ]
}

Close 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 (v19.06)

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 — list of files that starts from this name. You can just specify the beginning of the file name. (optional)
    Reply will not contain FirstName itself.
  • COUNT — maximum number of files in the query. (optional)
    If it is used with FirstName, a reply 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"}
    ]
}

Save 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


Update 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


Remove 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


Create and update 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


Reload configruation 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

Reply: true if the request was processed successfully

Example for curl: curl -u admin:pass0 http://flussonic:8080/flussonic/api/reload


Restart 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


Switch 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)


Enable DVR module (dvr_enable)

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


Disable DVR module (dvr_disable)

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 cluster (cluster_servers)

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