Stream availability push API notification

Nimble Streamer provides a variety of APIs and frameworks, including Publish control, Pay-per-view and playback authorization framework, along with other solutions.

Now this tool set has event notifications for incoming live streams' availability, like RTMP and RTSP publish/unpublish events, MPEG-TS streams, Icecast pulled streams and also Live Transcoder output. Nimble Streamer can inform you about the start of stream ingestion and stop of incoming stream.

Why we implemented this as a push API which notifies your handler about all live streams; behavior.

If you want to use the notifications API, the major steps for usage are as follows:

1. Create a processing script on your web site.
2. Specify a processing script URL via WMSPanel UI.
3. Test the solution.

After that, your script will be automatically called each time your Nimble Streamer instances gets proper events.

Let's go step by step to see what you need to do.

1. Create a processing script

Nimble Streamer uses POST request to call your URL. Your script MUST get request body first.

Request body will look differently for different types of calls. Here are examples, with additional formatting, the fields are described below.

RTMP is published into Nimble:
{"ID":"c581b1c2-686a-8140-8deb-f44031fa393f",
  "Signature": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTg",
  "Puzzle": "42342-33434-343434-34343",
  "publish":[{
      "stream":"live\/4k",
      "protocol":"RTMP",
      "time":1569999976249,
      "type":"push",
      "remote_ip":"127.0.0.1"
    }]}

Nimble started receiving output from Live Transcoder:
{"ID":"c581b1c2-686a-8140-8deb-f44031fa393f",
  "publish":[{
      "stream":"live\/4k_ao_aac",
      "protocol":"ENCODER",
      "time":1569999976374,
      "type":"pull"
    }]}

Icecast stream is not pulled anymore:
{"ID":"c581b1c2-686a-8140-8deb-f44031fa393f",
  "unpublish":[{
      "stream":"live\/4k",
      "protocol":"ICECAST",
      "time":1570000823258
    }]}

Two major types of calls are available:

• "publish" means that the incoming live stream has appeared in Nimble Streamer input.
• "unpublish" means the stream is not in the input of Nimble Streamer anymore.

The following fields are used:

• "stream" shows application and stream name in the call.
• "protocol" is one of the following values: RTMP, RTSP, ICECAST, MPEG-TS (which covers MPEGTS and also pulled HLS) and ENCODER (output stream of Nimble Live Transcoder)
• "time" is publish/unpublish event epoch time in milliseconds.
• "remote_ip" is provided in case the stream is a published, it shows the IP of the publisher.

"Signature" and "Token" is what your script MAY check to make sure that it was Nimble Streamer who sent it.

Signature = BASE64(MD5(ID + Puzzle + Token))

You can find a small PHP sample of processing the incoming request in out github samples repo.

2. Set up API in WMSPanel

2.a Global setting

Go to Control / API Settings and choose Global push API tab.

Here you need to use two fields:

1. Enter handler URL into Streams (un)publish handler URL field;
2. Click on Enable publish/unpublish notifications checkbox.

After you click Save, the first sync-up will be sent to your handler within several seconds.

API parameters also include Token field as well as Enable mutual authorization check box. Those should be used if you'd like to use signature as described in section 1 above.

2.b Server instance setting

You may also make per-server setup. Just click on Servers push API tab to be able to define same settings for each individual server.

3. Test the complete solution

Now you can set up a testing stream or use existing one to try this feature. Just publish that stream to and get notified by the panel via the script. In the github example above you'll get a new log entry.

WMSPanel provides a test handler you can use for trying your calls. You'll be able to debug your scrip real-time.

Once you test it, you can use it in production together with other API features and frameworks.

Related documentation

Nimble Streamer, RTMP streaming in Nimble, WMSPanel API reference, github API code samples