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,
