Nimble Streamer API reference

The reference below describes the set of native API methods provided by any Nimble Streamer instance. They can be used for obtaining real-time status of the instance and controling some of its parameters and features.
This API works directly with the instance without any delays.


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, POST or DELETE 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

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;
?>


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}}

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"
         }
      ]
   }
]

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"
          }
        ]
      }
    ]
  }
}

Get RTMP re-publishing status

This GET method allows getting current status of RTMP streams re-publishing.

Request URL:
/manage/rtmp/republish/stats
Response parameters: All are nested under "stats" node.

  • rule_id - unique RTMP republish rule ID for further usage.
  • state - is the stream connected or not.
  • session_duration - duration of session.
  • bandwidth - current bandwidth.
  • bytes_recv - quantity of bytes received.
  • bytes_sent - quantity of bytes sent.
  • owner - which side has set this rule: 0 is for WMSPanel, 1 is for Nimble API.
  • retry_count - number of retries of this re-publisher if there where session breaks.
  • src_app - source application name.
  • src_stream - source stream name. If not specified, then all streams from the source application are republished.
  • dest_addr - destination URL or IP address where the application stream/streams are published.
  • dest_port - destination port.
  • dest_app - name of destination streaming application.
  • dest_stream - destination stream name.
Another basic field is "status" to show current status of re-publisher.Request example:
curl -vvv http://127.0.0.1:8082/manage/rtmp/republish/stats
Response example:
{
 "stats" : [
    {
       "bandwidth" : 613564,
       "bytes_recv" : 3485,
       "bytes_sent" : 8166049,
       "dest_addr" : "127.0.0.1",
       "dest_app" : "live-re",
       "dest_port" : 1999,
       "dest_stream" : "dest_stream",
       "owner" : 1,
       "retry_count" : 1,
       "rule_id" : "1",
       "session_duration" : 102,
       "src_app" : "live",
       "src_stream" : "stream",
       "state" : "connected"
    }
 ],
 "status" : "Ok"
}

Get RTMP re-publishing rules list

This GET method allows getting list of RTMP streams re-publishing rules.

Request URL:
/manage/rtmp/republish
Response parameters:
All are nested under "rules" node, with each rule having its nested node. Another node is "status" which indicates the status of request.

  • id - unique RTMP republish rule ID for further usage.
  • src_app - source application name.
  • src_stream - source stream name. If not specified, then all streams from the source application are republished.
  • dest_addr - destination URL or IP address where the application stream/streams are published.
  • dest_port - destination port.
  • dest_app - name of destination streaming application.
  • dest_stream - destination stream name.
  • dest_app_params - special parameters for destination streaming application.
  • dest_stream_params - special parameters for destination stream.
  • auth_schema - authentication schema for destination. Can be "NONE", "NIMBLE", "AKAMAI", "LIMELIGHT" or "PERISCOPE".
  • dest_login - login for authentication on destination. Relevant for "NIMBLE", "AKAMAI" and "LIMELIGHT" authentication schemas.
  • dest_password - password for authentication on destination. Relevant for "NIMBLE", "AKAMAI" and "LIMELIGHT" authentication schemas.
  • keep_src_stream_params - indicates source stream parameters handling mode. Should be true to keep source stream parameters in destination stream. Default value is false.
  • ssl - indicates SSL usage. If not specified, then it's automatically set to false. If set to true, then correct SSL port should be specified (usually 443). Relevant for "NONE" and "NIMBLE" authentication schemas.
Request example:
curl -vvv http://127.0.0.1:8082/manage/rtmp/republish
Response example:
{
   "rules" : [
      {
         "auth_schema" : "NONE",
         "dest_addr" : "127.0.0.1",
         "dest_app" : "live-re",
         "dest_app_params" : "",
         "dest_login" : "",
         "dest_password" : "",
         "dest_port" : 1999,
         "dest_stream" : "stream1",
         "dest_stream_params" : "",
         "id" : "1",
         "keep_src_stream_params" : false,
         "src_app" : "live",
         "src_stream" : "stream",
         "ssl" : false
      },
      {
         "auth_schema" : "NONE",
         "dest_addr" : "127.0.0.1",
         "dest_app" : "live-re",
         "dest_app_params" : "",
         "dest_login" : "",
         "dest_password" : "",
         "dest_port" : 1999,
         "dest_stream" : "stream2",
         "dest_stream_params" : "",
         "id" : "2",
         "keep_src_stream_params" : false,
         "src_app" : "live",
         "src_stream" : "stream",
         "ssl" : false
      }
   ],
   "status" : "Ok"
}

Get RTMP re-publishing rule

This GET method allows getting certain RTMP stream re-publishing rule.

Request URL:
/manage/rtmp/republish/<id>
Request parameters:
All are nested under "rules" node, with each rule having its nested node. Another node is "status" which indicates the status of request.

  • src_app- source application name.
  • src_stream - source stream name. If not specified, then all streams from the source application are republished.
  • dest_addr - destination URL or IP address where the application stream/streams are published.
  • dest_port - destination port.
  • dest_app - name of destination streaming application.
  • dest_stream - destination stream name.
  • dest_app_params - special parameters for destination streaming application.
  • dest_stream_params - special parameters for destination stream.
  • auth_schema - authentication schema for destination. Can be "NONE", "NIMBLE", "AKAMAI", "LIMELIGHT" or "PERISCOPE".
  • dest_login - login for authentication on destination. Relevant for "NIMBLE", "AKAMAI" and "LIMELIGHT" authentication schemas.
  • dest_password - password for authentication on destination. Relevant for "NIMBLE", "AKAMAI" and "LIMELIGHT" authentication schemas.
  • keep_src_stream_params - indicates source stream parameters handling mode. Should be true to keep source stream parameters in destination stream. Default value is false.
  • ssl - indicates SSL usage. If not specified, then it's automatically set to false. If set to true, then correct SSL port should be specified (usually 443). Relevant for "NONE" and "NIMBLE" authentication schemas.
Request example:
curl -vvv http://127.0.0.1:8082/manage/rtmp/republish/1
Response example:
{
   "rules" : [
      {
         "auth_schema" : "NONE",
         "dest_addr" : "127.0.0.1",
         "dest_app" : "live-re",
         "dest_app_params" : "",
         "dest_login" : "",
         "dest_password" : "",
         "dest_port" : 1999,
         "dest_stream" : "stream1",
         "dest_stream_params" : "",
         "id" : "1",
         "keep_src_stream_params" : false,
         "src_app" : "live",
         "src_stream" : "stream",
         "ssl" : false
      }
   ],
   "status" : "Ok"
}

Create RTMP re-publishing rule

This POST method allows creating a new RTMP re-publishing rule.
Notice that re-publishing setting defined by this API call are not persistent and they are reset after Nimble Streamer re-load. If you'd like to keep them, you should use WMSPanel control API instead.

Request URL:
/manage/rtmp/republish
Request parameters:

  • src_app - source application name.
  • src_stream - source stream name. If not specified, then all streams from the source application are republished.
  • dest_addr - destination URL or IP address where the application stream/streams are published.
  • dest_port - destination port.
  • dest_app - name of destination streaming application.
  • dest_stream - destination stream name.
  • dest_app_params - special parameters for destination streaming application.
  • dest_stream_params - special parameters for destination stream.
  • auth_schema - authentication schema for destination. Can be "NONE", "NIMBLE", "AKAMAI", "LIMELIGHT" or "PERISCOPE".
  • dest_login - login for authentication on destination. Relevant for "NIMBLE", "AKAMAI" and "LIMELIGHT" authentication schemas.
  • dest_password - password for authentication on destination. Relevant for "NIMBLE", "AKAMAI" and "LIMELIGHT" authentication schemas.
  • keep_src_stream_params - indicates source stream parameters handling mode. Should be true to keep source stream parameters in destination stream. Default value is false.
  • ssl - indicates SSL usage. If not specified, then it's automatically set to false. If set to true, then correct SSL port should be specified (usually 443). Relevant for "NONE" and "NIMBLE" authentication schemas.
Response parameters will have same set of fields under "rules" node, plus "id" field to indicate what ID was assigned to this new rule. It'll also have "status" field to indicate the result of the call.

Request example:
curl -vX POST -H 'Content-Type: application/json' -d '{"src_app": "live", "src_stream": "stream", "dest_addr": "127.0.0.1", "dest_port":"1999", "dest_app": "live-re", "dest_stream": "dest_stream"}' http://127.0.0.1:8083/manage/rtmp/republish
Response example:
{
  "status": "Ok",
  "rule":{
    "id":"1",
    "dest_addr":"127.0.0.1",
    "dest_port":1999,
    "src_app":"live",
    "dest_app":"live-re",
    "src_stream":"stream",
    "dest_stream":"dest_stream",
    "dest_app_params":"",
    "dest_stream_params":"",
    "dest_login":"",
    "dest_password":"",
    "ssl":false,
    "keep_src_stream_params":false,
    "auth_schema":"NONE"
  }
}

Delete RTMP re-publishing setting

This DELETE method allows deleting specified setting of RTMP stream re-publishing.
Notice that re-publishing setting defined by this API call are not persistent and they are reset after Nimble Streamer re-load. If you'd like to keep them, you should use WMSPanel control API instead.

Request URL:
/manage/rtmp/republish/<id>
Response parameters: Response has "status" filed with either "Ok" or "NotFound".

Request example:
curl -X DELETE http://127.0.0.1:8082/manage/rtmp/republish/1
Response example:

{"status": "Ok"}
or
{"status": "NotFound"}

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"
    }
  ]
}

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

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

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"}

Insert Icecast metadata into RTMP stream

This POST method injects Icecast metadata into /<app>/<stream> RTMP stream.
Read Manual ingest of Icecast metadata into RTMP via API article for more details.
Request URL:
/manage/icecast_metadata/<app>/<stream>
Request example:
curl -vvv http://127.0.0.1:8083/manage/icecast_metadata/live/radio -d "{\"streamtitle\":\"title\", \"streamurl\":\"url\"}"
Response example:
{"status": "Ok"}

Insert SCTE-35 marker

This POST method triggers ads insertion for /<app>/<stream> if that stream is configured with "time_sync":"scte35" in Nimble Advertizer.
Read SCTE-35 marker insertion article and Nimble Advertizer spec for more details.
Request URL:
/manage/advertizer/scte35_out/<app>/<stream>
Request example:
curl -vX POST http://127.0.0.1:8083/manage/advertizer/scte35_out/live/stream
Response example:
{"status": "Ok"}

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.

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.

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:

  • timeline - shows timeline of archives
  • 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
         }
      ]
   }
]

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:

  • start - get content recorded after the specified UTC timestamp, e.g. from=1507732548
  • 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:
response body carries the entire result MP4 file.

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:

  • target_depth - preserve last N minutes of recording
  • from - clean only content recorded after the specified UTC timestamp, e.g. from=1507732548
  • 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"}

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

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

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


WMSPanel control HTTP API

WMSPanel web panel allows controlling Nimble Streamer and getting aggregated server statistics via HTTP API. The control API methods reflect all major control features accessible via web UI so this brings ability for streaming automation.
Please check WMSPanel API reference for more details.



Install Nimble Streamer now
Install now
Free trial of WMSPanel included

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.