Flussonic Media Server documentation

Flussonic API

Authentication and authorization Anchor Anchor x2

Flussonic provides the option to receive information and manage certain functionality over HTTP.

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

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

With authentication active you need to use login and password in HTTP Basic Auth format to access HTTP API.


Server information (server) Anchor Anchor x2

Information about Flussonic server.

URL: /flussonic/api/server

Parameters: none

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

List of streams, their clients and state (media) Anchor Anchor x2

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
        "dvr_enabled": false, //archive recording disabled
        "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"
          ]
        ],
        "publish_enabled": false,
        "add_audio_only": false,
        "dash_off": false,
        "dvr_protected": false,
        "hds_off": false,
        "hls_off": false,
        "m4s_off": false,
        "mpegts_off": false,
        "pulse_off": false,
        "rtmp_off": false,
        "rtsp_off": false,
        "webrtc_off": false
      }
    }
  },
  ...
]

Stream information (media_info) Anchor Anchor x2

Information about specific stream: width, height, tracks.

URL: /flussonic/api/media_info/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name. (required)

Reply: 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) Anchor Anchor x2

Information about the original incoming stream before it is transcoded.

URL: /flussonic/api/input_media_info/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name. (required)

Reply: 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 quiality (stream_health) Anchor Anchor x2

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

URL: /flussonic/api/stream_health/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name (required)

Reply:

  • 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, eg:

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) Anchor Anchor x2

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

URL: /flussonic/api/files

Parameters:  none

Reply: 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) Anchor Anchor x2

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

Reply: 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) Anchor Anchor x2

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

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

Parameters: 

  • STREAM_NAME — stream name. (required)

Reply: 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) Anchor Anchor x2

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)

Reply: code 200

Playlist state info (playlist) Anchor Anchor x2

Information about the state of the playlist of the specified stream.

URL: /flussonic/api/playlist/STREAM_NAME

Parameters: 

  • STREAM_NAME — stream name (required)

Reply: JSON like

{
    "current_entry":"vod/ir.mp4",   //identifer of a current stream
    "current_type":"file",   //stream type
    "duration":null,   //duration (null stands for undefined)
    "position":5.22e4   //position in the stream
}

Recordings map (dvr_status) Anchor Anchor x2

Recordings map for 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)

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

List of VOD files (list_files) Anchor Anchor x2

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

Reply: 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 new configuration file (save_config) Anchor Anchor x2

To update configuration, you need to pass the text of the new configuration file as 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 at /etc/flussonic/flussonic.conf.

URL: /flussonic/api/save_config

Parameters:

  • HTTP request payload — 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;'

Reply: true if the request was processed successfully


Update configuration file (update_config) Anchor Anchor x2

To update configuration, you need to pass the text of the new configuration file as POST request body. An important difference from save_config in 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 — 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;'

Reply: true if the request was processed successfully


Remove a stream (config/stream_delete) Anchor Anchor x2

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'

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


Create and update a stream (config/stream_create) Anchor Anchor x2

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

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


Reload configruation file (reload) Anchor Anchor x2

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) Anchor Anchor x2

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)

Reply: true if the request was processed successfully


Switch stream source (stream_switch_source) Anchor Anchor x2

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) Anchor Anchor x2

Option dvr or dvr_offline must be specified in stream settings.

URL: /flussonic/api/dvr_enable/STREAM_NAME

Parameters:

  • STREAM_NAME — stream identifier (required)

Reply: true if the request was processed successfully


Disable DVR module (dvr_disable) Anchor Anchor x2

URL: /flussonic/api/dvr_disable/STREAM_NAME

Parameters:

  • STREAM_NAME — stream identifier (required)

Reply: true if the request was processed successfully