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 HTTP API can be used to build advanced streaming load balancing among Nimble Streamer instances.

Nimble Streamer HTTP API

Nimble Streamer accepts HTTP calls to control its behavior and to get some stats and other data.
Each call is a GET or POST request via HTTP.
As a response you get JSON structure with required data or raw data in case of MP4 archive.

Pre-setup

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

API usage


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 the 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 stats

These methods allow getting current sender and receiver stats.
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

Publish control: Get published streams status

This method allows gets the status of published streams as part of publish control framework for RTMP and RTSP published streams.
Request URL:
/manage/publish_control/status
Response parameters:

  • key - session key;
  • id - publisher ID within your business logic;
  • ip - the IP address of the publisher;
  • stream - the URI of the stream which is being published.
Request example:
curl -vvv http://127.0.0.1:8082/manage/publish_control/status
Response example:
{
  "PublishControlStatus":
  [
    {"key":"1", "id":"ID_1", "ip":"192.168.1.1","stream":"live/stream1"}, 
    {"key":"2", "id":"ID_2", "ip":"192.168.1.2","stream":"live/stream2"}
  ]
}

Please refer to publish control framework description for more details.

Collapse this method

Publish control: Send the list of denied IDs

This method sends to Nimble Streamer a list of blocked sessions. It's a POST request.
This is part of publish control framework for RTMP and RTSP published streams.
Request URL:
/manage/publish_control/deny
Request parameters:

  • PublishControlDenyRequest - array of blocked IDs;
Response parameters:
  • status - shows if IDs have been denied;
Request example:
curl -v -X POST -d '{"PublishControlDenyRequest":["1", "2"]}' http://127.0.0.1:8082/manage/publish_control/deny
Response example:
{"PublishControlDenyResponse":{"status":"success"}}

Please refer to publish control framework description for more details.

Collapse this method

Get DVR archives

This method allows getting list of the 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

Export DVR archive content to MP4

This method allows getting MP4 file for DVR archive for specified stream.
Request URL:
/manage/dvr/export_mp4/application/stream[?start=&end=]
Request parameters:

  • [optional] start - get content recorded after the specified UTC timestamp, e.g. from=1507732548
  • [optional] end - get only content recorded prior to the specified UTC timestamp, e.g. to=1507732600
Request example:
curl -o archive.mp4 -v "http://127.0.0.1:8082/manage/dvr/export_mp4/live/stream?start=1542708934&end=1542712534"
Response:
The response body carries the entire result MP4 file.

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

Re-sync Nimble Streamer with WMSPanel

This POST method forces Nimble Streamer to reload config from WMSPanel.
Request URL:
/manage/sync_panel_settings
Request example:
curl -X POST http://127.0.0.1:8083/manage/sync_panel_settings

Collapse this method

Reload Nimble Streamer config

This POST method allows reloading Nimble Streamer config 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 stats/control/WMSAuth HTTP API

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.
Please check WMSPanel API reference for more details.

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.