Pay-per-view framework

Available for Nimble Streamer and Wowza Streaming Engine

Some businesses want to control their streaming process on per-user and per-stream level in addition to general protection methods like hot-link protection or geo restriction limitation. This is required especially for pay-per-view (PPV) systems where viewers pay for accessing the media.

What can we do?

We provide a framework which allows collecting detailed data for all connection and making decision to allow or deny each connecting user. This may be used for pay-per-view and pay-per-minute logic, calculating each user simultaneous connections, stats for unique visitors and much more.

These are the steps for a customer to integrate those capabilities into customer's workflow:

Having all that the general workflow would be as follows:

So let's go step by step to implement it.

1. Create PPV handler

WMSPanel uses push API. Nimble sends requests to customer's handler. This handler must be accessible via HTTP/HTTPS and it must be able to accept POST requests. Those requests may be formed via either JSON or XML, this can be set up in WMSPanel settings.
Handler needs to do a few things:

Handler needs to return list of all blocked IDs on every sync. If some ID is excluded from the list, it will be allowed to access.

Please check a basic handler example for PHP. It just takes incoming request, logs it and returns a couple of IDs to be blocked. You should take a look at full JSON request example and handler response sample as well.

2. Set up API parameters for handler

Now we need to set up a link between Nimble Streamer instances and the handler. Select Control / API setup menu and select Push API tab which is the one we are going to use now.

Define the following:

A few seconds after you click on Save, the first sync-up will be sent to your handler.

3. Make media URL PPV signature

In order for Nimble to start sending requests, some changes must be made on your web server side. Media URL needs to be modified to include special signature, that would contain required information.

For example, you have this URL for your live stream:
http://video.wmspanel.com:8081/live/stream/playlist.m3u8
The modified URL would be:
http://video.wmspanel.com:8081/live/stream/playlist.m3u8?wmsAuthSign=c2VydmVyX3RpbWU9MDMvMDEvMjAxOSAwNzozMTo0NCBBTSZoYXNoX3ZhbHVlPVZGOHBLUE44Z0ZTYUQrM0p5c0pNYlE9PSZ2YWxpZG1pbnV0ZXM9MTAmaWQ9SURfMQ==

To generate signature you need to modify your front-end source to include code snippet.

Click here to see the PHP source code to generate this signature.

<?php
$today = gmdate("n/j/Y g:i:s A");

// URL of media we want to handle with pay-per-view
$initial_url = "http://video.wmspanel.com:8081/live/stream/playlist.m3u8";
// client ID which is defined based on customer's database of users
$id = "5";
// A password entered in WMSAuth rule via web interface
$key = "defaultpassword";
// How long the link would be valid for playback (minutes)
$validminutes = 60;

$str2hash = $id . $key . $today . $validminutes;
$md5raw = md5($str2hash, true);
$base64hash = base64_encode($md5raw);
$urlsignature =
  'server_time=' . $today . '&hash_value=' . $base64hash .
  '&validminutes=' . $validminutes . '&id=' . $id;
$base64urlsignature = base64_encode($urlsignature);
$signedurlwithvalidinterval = $initial_url . "?wmsAuthSign=$base64urlsignature";

// New protected media URL
echo $signedurlwithvalidinterval;?>

The code is the same as the code used in hot-linking protection except for the IP which is replaced with ID here. You can find all samples in github repository and adapt them for your use case.

Two important things must be specified here:

The ID is any string value which is unique within customer's scope.

Q: How do I use both client ID and IP in my signature?

If you add "checkip=true" option and IP address to $urlsignature, Nimble Streamer will check both client IP and user ID.
The signature generation code from example above will need to be modified like this:
$str2hash = $ip. $id . $key . $today . $validminutes;
$md5raw = md5($str2hash, true);
$base64hash = base64_encode($md5raw);
$urlsignature = 'server_time=' . $today . '&hash_value=' . $base64hash . '&validminutes=' . $validminutes . '&id=' . $id .'&checkip=true';

4. Set up control panel settings

After the code is set on web server side, Nimble Streamer (or Wowza agent) must be notified about protection settings.
Go to top menu and select "Control" -> "WMSAuth paywall setup".

WMSAuth is a feature set which handles hotlink protection and other features like geo-lock and pay-per-view.

4.1 WMSAuth group

In WMSAuth, every restriction may be applied to a group of servers. So the first thing to do is to create a group and assign one or more servers to it.
Click on Add WMSAuth group to specify its name and proceed to further setup.

4.2 WMSAuth rule

Within a group, there may be several rules, each working with its set of Nimble Streamer or Wowza entities. Just click on "Add rule" to enter rule creation page.
Check this screenshot to see how you can specify application or stream regular expression.

The last thing to specify is a key, or password, which was inserted into the media signature on web server side in section "Make PPV signature" above.
After you save the rule, it will be applied to the server within a few seconds.

Time tolerance parameter means maximum time range that is allowed for web server and media server to be unsynchronized. It should be used when you can't arrange these times to match perfectly.

What's next

Now when the chain is set up you will be receiving updates on current streaming status. As response you can send back the blocked IDs list and so control your streaming workflow.

You may also combine this functionality with geo-location and IP ranges restriction and connections and bandwidth limitation..

Check playback authorization feature set which allows controlling playback connections with external handler.
Also, session control via Nimble native API allows controlling connections by making direct API calls to Nimble instance.

The Paranoid’s Guide to Internet Video Streaming by Thomas Gires is very useful to see real-life example of using pay-per-view feature set for HLS re-streaming via light-weight edge.

Q: Are there any debugging techniques available?

The debugging handler and interface allows receiving data from servers and viewing results via your browser. Use it to see what requests will come from your server instances to your own handler.

Q: How can I use mutual authorization with PPV?

Mutual authorization is the way your handler and your media server can make sure they interact with legit and authorized counterpart.

First you need to enable mutual authorization. Check the screenshot in Section 2 for "Enable mutual authorization" checkbox.

Once it's enabled, the designated media server will start sending additional parameters: "Signature" and "Puzzle" in addition to existing "ID".
"Signature" is what your handler need to check to make sure that is was your server who sent it.
Signature = BASE64(MD5(ID + Puzzle + Token))

Your handler response must contain "Solution" parameter, e.g.
{"Solution": "PjxTZXJ2ZXJBdXRob3JpemF0aW9uUHJvcGVydGllcz48U2Vydm"}
"Solution" parameter is checked by server (Nimble Streamer or Wowza) to make sure your handler knows the token.
Solution = BASE64(MD5(Puzzle + Token))

"Token" parameter is set up in WMSPanel as shown on the same PPV setup screenshot.

Questions or problems

Pay-per-view does not work? Check the troubleshooting FAQ.

What if WMSPanel is not accessible? Hot-linking protection works regardless of WMSPanel availability. If your server can't connect to WMSPanel for some reason, the protection will still work perfectly. Once the rules are set up, the control panel is not used anymore.