Nimble Streamer status API

Nimble Streamer is being used in a variety of streaming use cases and scenarios. Many customers use multiple instances for load balancing and robustness purposes. The majority of balancing techniques use geo-location approach or just round-robin balancing to split the incoming requests equally between edges. However this does not guarantee that edge servers will have equal load as some viewers many disconnect from some edges while other edge users will keep watching.

So system administrators who use Nimble Streamer need a way to get status of each server to make real-time decisions about which servers should be processing current incoming requests. Usually this means changing the URL of the media streams on the website so any player would pick it up for playback. This is the most reliable way to make balancing happen regardless of the players' implementations.

This is why we extended common WMSPanel API by adding a pull API to Nimble Streamer itself. A customer may now launch a request to any Nimble instance and get its status and live streaming settings.

Enable API for Nimble Streamer instance

To make Nimble Streamer responding to API requests, the API settings must be set up in /etc/nimble/nimble.conf configuration file. You may check config description to get details about other parameters.

All parameters mentioned below are excluded from config by default.

management_listen_interfaces
This parameter specifies which IP addresses will be used for accepting AI requests. If it's not set, the API requests are not accepted.
Examples:
management_listen_interfaces = *  - all available interfaces are used
management_listen_interfaces = 127.0.0.1, 192.168.0.1

management_port
This one specifies which port is used to listen to API requests. If it's missing, the 8082 port is used.
Example:
management_port = 8086

management_token
This parameters specifies the token (i.e. password) which is used for authorizing API requests. See Making authorized requests section below for details.
If this parameter is missing, there will be no authorization made and anyone will be able to get information.
Example:
management_token = anypassword

Making authorized requests

This is an optional step for the cases when you use management_token parameter for authorizing requests. To make authorized requests you need to make MD5 hash based on the specified token. Please refer to this code sample to see how you can generate this hash.

<?php
$salt= rand(0, 1000000);
$key = "anypassword"; // the token specified in management_token parameter
$str2hash = $salt . "/". $key;
$md5raw = md5($str2hash, true);
$base64hash = base64_encode($md5raw);
$requiest_url = "http://127.0.0.1:8082/manage/server_status?salt=$salt&hash=$base64hash"
echo $request_url;
?>

Get server basic status

This API method allows getting current number of connection and bandwidth (transmission speed) level.

Request URL
/manage/server_status

Response parameters
Connections - number of active connections
OutRate - current transmission speed, bits per seconds

ap - Available processors
scl - System CPU load
tpms - Total physical memory size
fpms - Free physical memory size
tsss - Total swap space size
fsss - Free swap space size

Request example

curl -vvv http://127.0.0.1:8082/manage/server_status

Response example
{"Connections": 10, "OutRate": 5120000, "SysInfo": {"ap":2,"scl":0,"tpms":2098434048,"fpms":775127040,"tsss":2145382400,"fsss":1707151360}}

Get RTMP connections status

Request URL
/manage/live_streams_status

Note: /manage/rtmp_status is considered deprecated.

Response parameters

• app - name of application; if there are several applications, they will have their separate sections.
• streams - list of streams and their parameters
• strm - stream name
• publish_time - The value returned generally represents the number of seconds since 00:00 hours, Jan 1, 1970 UTC
• bandwidth - encoding bandwidth
• resolution - video resolution
• vcoded - video codec spec
• acodec - audio code spec
• publisher_ip -  publisher's source IP  in case RTMP/RTSP/SRT streams are pushed into Nimble instance
• publisher_port - publisher's source PORT  in case RTMP/RTSP streams are pushed into  Nimble instance

Request example
http://127.0.0.1:8082/manage/live_streams_status

Response example

 [

  {

    "app": "larix",

    "streams": [

      {

        "strm": "srt",

        "publish_time": "1706701873",

        "bandwidth": "0",

        "resolution": "1280x720",

        "vcodec": "avc1.42001f",

        "protocol": "MPEGTS",

        "publisher_ip": "192.168.0.95"

      }

    ]

  },

  {

    "app": "rtmp",

    "streams": [

      {

        "strm": "stream",

        "publish_time": "1706701540",

        "bandwidth": "11711170",

        "resolution": "1920x1080",

        "vcodec": "avc1.64002a",

        "acodec": "mp4a.40.2",

        "protocol": "RTMP",

        "publisher_ip": "192.168.0.95",

        "publisher_port": 60349

      }

    ]

  }

]

Get RTMP settings

Request URL
/manage/rtmp_settings

Response parameters
They are nested under RtmpSettings node.

• hash - response hash
• interfaces - which interfaces are set to process RTMP streaming
• login - login for RTMP publishing
• password - password for RTMP publishing
• duration - default chunk duration
• protocols - which protocols' streams are generated as output
• apps - specific applications' settings
• abr - individual ABR streams settings
• app - application name
• stream - stream name
• streams - single bitrate streams included into the ABR, each having its app and stream names

Request example
http://127.0.0.1:8082/manage/rtmp_settings

Response example
{"RtmpSettings":{"hash":"1414983917310","interfaces":[{"ip":"*","port":1936}],"login":"","password":"","duration":6,"protocols":["HLS"],"apps":[],"abr":[{"app":"nimble_live_abr","stream":"abrstream","streams":[{"app":"live","stream":"stream"}]}]}}

Get MPEG-TS connections status 

Request URL
/manage/mpeg2ts_status

Response parameters
They are nested under Cameras node. Each stream has entries for

• id - stream ID
• st - the stream status
• tr - processed traffic delta
• bw - current bandwidth 
• pmts - processes details

Request example
http://127.0.0.1:8082/manage/mpeg2ts_status

Response example
{"Cameras":[{"id":"5456fab17d5c00547f000002","st":"online","tr":"0","bw":"440623","pmts":[{"id":4096,"pids":[{"pid":256,"t":27},{"pid":257,"t":15}]}]}]}

Get MPEG-TS settings

Request URL
/manage/mpeg2ts_settings

Response parameters

• CamerasHash - response hash
• Cameras - information about each stream
• id - source stream ID
• ip - IP of the source stream
• port - source stream port
• protocol - whether UDP or HTTP is used.

Request example
http://127.0.0.1:8082/manage/mpeg2ts_settings

Response example
{"CamerasHash":"1414986417897","Cameras":[{"id":"5456fab17d5c00547f000002","ip":"127.0.0.1","port":1234,"protocol":"udp"}]}

This set of APIs is the first step to building reliable and robust load balancing. If you have any questions or further use cases which you'd like to cover, let us know about it, any feedback is appreciated. Check also a full Nimble Streamer API reference.

Update: You may also find useful the Nimble Streamer routes control API and RTMP streaming API which allows controlling Nimble behavior.

Related documentation

Nimble Streamer, Nimble Streamer API reference, Nimble Streamer routes control API, RTMP and MPEG-TS streaming, WMSPanel API reference, RTMP playback and streaming via Nimble,