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:
- Implement PPV API handler which is able to accept POST requests.
- Set up handler parameters within WMSPanel.
- Add PPV signature to media links (streams' URLs).
- Enable PPV signature process via WMSPanel.
Having all that the general workflow would be as follows:
- A media server (Nimble Streamer or Wowza agent) sends request to handler on a periodical basis. The sync contains all users' IDs, IPs, delta of view time between sync-ups and media names.
- Customer handler makes required decisions based on company business logic and sends response to media server. This response specifies which users must be blocked from watching media.
- Blocked users are shut down immediately, while others keep watching.
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:
- parse incoming request (e.g. decode JSON document);
- make query to internal users database to append consumption updates and make decision about who may keep accessing the media (e.g. watch video);
- return encoded response which contains users' IDs that must be blocked from accessing the media.
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:
- Enter handler URL into PPV handler URL field;
- Click on Enable pay per view check box;
- Select Request format or leave default "JSON" value;
- Enter Sync interval or leave default 30 seconds.
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:
The modified URL would be:
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.
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:
- user ID defined by the customer;
- key, or password, which is going to be used on the next step.
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.
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" 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.