July 25, 2013

Pay-per-view for Wowza Media Server

WMSPanel uses "agent approach" for accessing Wowza Media Server. This allows making a lot of advanced server control features. WMSPanel is already capable of server managementstreams control and recording and transcoder control. Another great feature set called WMSAuth allows restricting connections by various criteria and protects against hot-linking re-streaming.

A lot of our customers requested upgrading restriction capabilities into a per-user control feature set. So after a while we designed and implemented this approach. We call this a pay-per-view (PPV) feature set.

What are the use cases for this kind of functionality?

  • pay per view logic for streaming media providers as each viewer info has the fact of viewing;
  • pay per minute logic as it allows gathering view time per viewer;
  • re-streaming protection when 1 person pays for 1 account and provides access for group of people;
  • unique visitors statistics calculation (both customer-defined and WMSPanel-based);
  • education video management for per-student metrics;
  • you name it.

Let's see how it works and how you can use it.

Basic business logic

The main workflow is based on push API. WMSPanel agent sends (pushes) user data to customer, then customer decides what to do with each individual unique user and replies with the decision back to the agent. This works as follows:
  1. Customer implements API handler that is able to accept POST requests.
  2. Customer adds PPV info into existing media links.
  3. WMSPanel provides web UI for setting up handler URL and some other parameters.
  4. WMSPanel agent which works on Wowza server side sends request to handler on a periodical basis which is defined via web UI. Sync contains all users' IDs, IPs, view time and media names.
  5. Customer handler makes required decisions based on company business logic and sends response to agent. This response specifies which users must be blocked for watching media.
  6. Blocked users are shut down immediately, while others keep watching.
  7. WMSPanel agent may be installed on any number of Wowza servers. All agents will send sync-ups to the same single API handler.
WMSPanel pay-per-view for Wowza Media Server.
Here's the flow chart showing the basic scenario.

Pay-per-view framework basic workflow.
Let's go step by step. Please open WMSPanel API samples github repo to refer to the code. Please also read WMSAuth documentation because PPV shares the same URL modification and handling mechanics. Now follow these steps.

1. Create API handler

As already stated, WMSPanel uses push API and its agent 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 is 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 should 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 this very simple basic PHP example. It just takes incoming request, logs it and returns a couple of IDs to be blocked. You should also take a look at full XSD for agent request and handler response along with JSON request example.

2. Adding PPV info to media link

In order for agent to start sending this information, some changes must be made on your web server side. Media URL needs to be modified to include special hash that would contain required information. Please use this example from github to see how the hash must be made.
Two important things must be specified:

  • user ID defined by the customer and 
  • password which is going to be used on the next step.

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

You can also use these WMSAuth examples to see how this may be used with different players and protocols - but don't forget to replace IP with your own ID.

3. Create WMSAuth rule

As already mentioned, PPV control is based on WMSAuth mechanics. This means that you need to create WMSAuth group with at least one rule to describe what media assets must be protected. Please read this blog post to learn how to do it. Basically you must specify 2 things:
  • which stream or streams will be affected;
  • the password used for creating secure hash in the code presented further.
You can combine PPV and WMSAuth restriction rules. E.g. you can define IP range for people who can watch some stream without any limits and then set up separate rule to enable ID check for those who is "outside" of this IP range. The same applies for geo restrictions. Of course it might be done vice versa.

4. Set up API parameters for handler

Now we need to set up a link between the agent and the handler. Go to Control / API setup page and choose Push API tab.

Setting up pay-per-view handler.
Define the following:
  1. enter handler URL into PPV handler URL field;
  2. click on Enable pay per view check box;
  3. select Request format or leave default "JSON" value;
  4. 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.

API parameters also include Token field as well as Enable mutual authorization check box. Those should be used to extra security of data transfer and it's a subject for future separate article.

Send publish/unpublish parameters check box enables RTMP streams status notifications.

Handler settings may be cancelled any time by removing handler URL.

FAQ: What if WMSPanel becomes unavailable?

Network failures may happen leaving your Wowza server isolated from WMSPanel. Nothing bad happens in this case. No worries, the agent does not require constant connection to WMSPanel web service to serve pay-per-view. Once the agent parameters are set via web UI, the agent starts working accordingly. It still sends statistics sync-ups each 30 seconds to the central server but if network becomes unavailable between the agent and the panel, the PPV functionality is not affected.
If network fails between the Wowza agent and the handler, it's not a problem either. Agent will keep pinging the handler until it's available and will not block any IDs.

Please check FAQ and Troubleshooting section for other questions.

You can also read "The Paranoid’s Guide to Internet Video Streaming" by Thomas Gires to see real-life example of using pay-per-view feature set with Nimble Streamer as light-weight edge for HLS re-streaming and pay-per-view framework server.


At the moment, this is the most advanced feature set from customer perspective available at WMSPanel. It requires changes in customer business logic and proper set up at WMSPanel. This is why we're looking forward to seeing your feedback, questions, comments and concerns. Send us your code snippets so we could check them and possible share with other customers.

Contact us if you have anything to say regarding this feature set.

Related documentation

Paywall for WowzaRestriction solution for geo and IP range for WowzaWowza hotlinking re-publishing and re-streaming protectionDomain lock hot-linking protection, Connections, bandwidth and view time limitation for WowzaIntegrating WMSAuth to your websitegithub code samplesStreams publish/unpublish notificationsNimble StreamerReal-time stats pull APIDeep stats pull APIHotlinking protection with stream-based signature

No comments:

Post a Comment

If you face any specific issue or want to ask some question to our team,

This will give much faster and precise response.
Thank you.