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 live outgoing streams status

This method allows getting current status of outgoing streams for all supported protocols.
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
    • vcodec - video codec spec
    • acodec - audio code spec
    • protocol - protocol name
Request example:
curl -vvv http://127.0.0.1:8082/manage/rtmp_status
Response example:
[ 
   { 
      "app" : "live", 
      "streams" : [ 
         { 
            "acodec" : "mp4a.40.2", 
            "vcodec" : "avc1.42c01f", 
            "publish_time" : "1524060893", 
            "bandwidth" : "1697348", 
            "protocol" : "RTSP", 
            "resolution" : "1280x720", 
            "strm" : "stream_rtsp" 
         }, 
         { 
            "vcodec" : "avc1.42c01f", 
            "publish_time" : "1524060893", 
            "acodec" : "mp4a.40.2", 
            "strm" : "stream_rtmp", 
            "bandwidth" : "1698536", 
            "protocol" : "RTMP", 
            "resolution" : "1280x720" 
         }, 
         { 
            "vcodec" : "avc1.64001e", 
            "publish_time" : "1524060893", 
            "bandwidth" : "286200", 
            "resolution" : "640x360", 
            "protocol" : "ENCODER", 
            "strm" : "stream_360p" 
         } 
      ] 
   } 
]

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 incoming streams status

This method allows getting current status of MPEG-TS incoming streams (from "MPEGTS In" settings section).
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:
Depend on type of the stream, fields will be similar to other calls' fields.
Request example:
curl -vvv http://127.0.0.1:8082/manage/mpeg2ts_settings

Collapse this method

Get SRT sender and receiver statuses

These methods allow getting current sender and reciver statuses.
Request URL:
/manage/srt_sender_stats
/manage/srt_receiver_stats
Response parameters:
Returned fields are defined by SRT protocol spec.
Requests examples:
curl -vvv http://127.0.0.1:8082/manage/srt_sender_stats
curl -vvv http://127.0.0.1:8082/manage/srt_receiver_stats

Collapse this method

Get Icecast stream information

This API method allows getting information about existing Icecast stream. Response parameters are taken from Icecast metadata settings, most of which can be set up via WMSPanel UI.
Request URL:
/manage/icecast_stream_info/application_name/stream_name
Response parameters:

  • icy-name - channel name
  • icy-description - channel description
  • icy-genre - channel genre
  • icy-br - channel bitrate, Kbps
  • streamtitle - current track title embedded in Icecast stream metadata
Request example:
curl -vvv http://127.0.0.1:8082/manage/icecast_stream_info/live_radio/audio_stream
Response example:
{"icy-name":"Radio name","icy-description":"Radio description","icy-genre":"jazz", "icy-br":128, "streamtitle":"Song Name"}

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] from - clean only content recorded after the specified UTC timestamp, e.g. from=1507732548
  • [optional] to (older_than) - clean only content recorded prior to the specified UTC timestamp, e.g. to=1507732600

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

Reload SSL certificates

This POST method allows reloading SSL certificates.
Request URL:
/manage/reload_ssl_certificates
Request example:
curl -X POST http://127.0.0.1:8082/manage/reload_ssl_certificates

Collapse this method

Reload Nimble Streamer config

This POST method allows reloading Nimble Streamer config without without restarting server. Please notice that only rules.conf is reloaded.
Request URL:
/manage/reload_config
Request example:
curl -X POST http://127.0.0.1:8083/manage/reload_config

Collapse this method



WMSPanel API reference

This website or its third-party tools use cookies, which are necessary to its functioning and required to achieve the purposes illustrated in the Privacy Policy. If you want to know more or withdraw your consent to all or some of the cookies, please refer to the Privacy Policy.
By closing this banner, scrolling this page, clicking a link or continuing to browse otherwise, you agree to the use of cookies.