Nimble Streamer API reference

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. This requires real-time decisions about which server should process each incoming request. The best way to do it is to get status of each server. Having this status snapshot, the front-end can change the URL of the media streams on the website so any player would pick it up for playback.
The reference below describes the set of API methods provided by Nimble Streamer for obtaining real-time status of streaming. You may also read API-related articles to see other API use cases for both Nimble and WMSPanel.
The mentioned API can be used to build advanced streaming load balancing among Nimble Streamer instances.
WMSPanel web panel allows controlling routes of Nimble Streamer to perform setup of VOD streaming and re-streaming routes. Read Nimble Streamer routes control API article to see how you can do that.

Pull API usage

WMSPanel allows accessing data by making API calls.
Each call is a GET request via HTTP.
As a response you get JSON structure with required data.

Starting point: enable API access

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 API 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 = mypassword

Collapse this section

Option: 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 = "mypassword"; // the token specified in management_token parameter
$str2hash = $salt . "/". $key;
$md5raw = md5($str2hash, true);
$base64hash = base64_encode($md5raw);
$request_url = "http://127.0.0.1:8082/manage/server_status?salt=$salt&hash=$base64hash";
echo $request_url;
?>

Collapse this section

Get server basic status

This API method allows getting current number of connections 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}}

Collapse this method

Get RTMP connections status

This method allows getting current status of RTMP streaming.
Request URL:
/manage/rtmp_status
Response parameters:

  • app - name of application; if there are several applications, they will have their
  • streams - list of streams and their parameters
    • strm - stream name
    • bandwidth - transmission speed
    • resolution - video resolution
    • vcoded - video codec spec
    • acodec - audio code spec
Request example:
curl -vvv http://127.0.0.1:8082/manage/rtmp_status
Response example:
[{"app":"live","streams":[{"strm":"stream","bandwidth":"507882","resolution":"424x240","vcodec":"avc1.66.30","acodec":"mp4a.40.2"}]}]

Collapse this method

Get RTMP settings

This method allows getting settings of RTMP streaming.
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:
curl -vvv 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"}]}]}}

Collapse this method

Get MPEG-TS connections status

This method allows getting current status of MPEG-TS streaming.
Request URL:
/manage/mpeg2ts_status
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:
curl -vvv http://127.0.0.1:8082/manage/mpeg2ts_status
Response example:
{"CamerasHash":"1414986417897","Cameras":[{"id":"5456fab17d5c00547f000002","ip":"127.0.0.1","port":1234,"protocol":"udp"}]}

Collapse this method

Get MPEG-TS settings

This method allows getting current status of MPEG-TS streaming.
Request URL:
/manage/mpeg2ts_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:
curl -vvv http://127.0.0.1:8082/manage/mpeg2ts_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"}]}]}}

Collapse this method

Get DVR archives

This method allows getting list of DVR archives (or archive for specified stream) and their detailed info.
Request URL:
/manage/dvr_status[/application/stream]
Request parameters:

  • [optional] timeline - shows timeline of archives
  • [optional] application/stream - show information only for specified stream (e.g. /manage/dvr_status/live/stream will only return information for stream "live/steam")
Response parameters:
  • size - size of all segments of archive
  • bandwidth - size devided by duration
  • resolution - stream resolution
  • acodec - audio codec
  • vcodec - video codec
  • path - archive path
  • space_available - free space available for archive
  • periods - a number of sessions in archive (e.g. how many times it was pulled/pushed)
  • stream - stream name
  • duration - total duration of archive
  • timeline - set of pairs for duration and time for each session
Request example:
curl -vvv http://127.0.0.1:8082/manage/dvr_status?timeline=true
Response example:
[
   {
      "size" : 11333929,
      "bandwidth" : 1619128,
      "resolution" : "1080x608",
      "periods" : 1,
      "stream" : "live/stream1",
      "acodec" : "mp4a.40.2",
      "vcodec" : "avc1.4d401f",
      "path" : "/var/cache/nimble/dvr/live/stream1",
      "duration" : 56,
      "space_available" : 57962266624,
      "timeline" : [
         {
            "duration" : 56,
            "start" : 1470753122
         }
      ]
   },
   {
      "size" : 22041265,
      "bandwidth" : 1663488,
      "resolution" : "1080x608",
      "periods" : 2,
      "stream" : "live/stream2",
      "acodec" : "mp4a.40.2",
      "vcodec" : "avc1.4d401f",
      "space_available" : 57962266624,
      "path" : "/var/cache/nimble/dvr/live/stream2",
      "duration" : 106,
      "timeline" : [
         {
            "start" : 1470753194,
            "duration" : 53
         },
         {
            "duration" : 53,
            "start" : 1470753378
         }
      ]
   }
]

Collapse this method

Clean up DVR archive

This POST method allows cleaning the DVR archive for designated stream.
Request URL:
/manage/dvr/cleanup_archive/application/stream
Request parameters:

  • [optional] target_depth - preserve last N minutes of recording
  • [optional] older_than - clean only content recorded prior to specified UTC timestamp

Response parameters:
  • status - shows the result
Request example:
curl -X POST http://127.0.0.1:8082/manage/dvr/cleanup_archive/application/stream
Response example:
{"status": "Ok"} or {"status": "Not found"}

Collapse this method



WMSPanel API reference