Building with Modules Part 1: What They Are and Why They Matter
The following blog post is Part 1 of a two-part series on extending Wowza Streaming Engine using custom server-side Java modules. Part 1 explains what are modules and how to use them. Part 2 provides common examples of building with modules.
Most streaming workflows are fairly simple, but as the saying goes, the devil is in the details. While 90 percent of the process can be standardized, there is always that 10 percent that simply can't be done out of the box—and that's where server-side Java modules come into play.
The extensibility of Wowza Streaming Engine software helps developers meet the most exacting requirements of their video ingest and deployment pipeline, and server-side Java modules plays a major role in providing this extensibility. The following blog post will give you an intro on how to build modules and why they are a key component for complete control over your audio and video assets.
Background
Wowza Streaming Engine is built using Java technology (not to be confused with JavaScript). Java is a programming language used to build a wide range of applications, for both server and client roles. The primary benefit of Java is that the Java Runtime Environment (or JRE) is available on a wide range of operating systems, including nearly every flavor of *nix, Windows, and Mac. This means you only need to write your Java code once, and you can run the same code consistently with very few changes from one system to the next.
If you have performed your own installation of Wowza Streaming Engine, you may have noticed a “lib” folder which contains files ending with the .jar extension. JAR (pronounced just like the word “jar”) stands for Java ARchive, and is a compressed collection of Java resource files. The Wowza Streaming Engine functionality is described by the JAR files you’ll find in the lib folder, as shown below.
To extend the features of the Wowza Streaming Engine core functionality, you create your own JAR file(s) that include all the Java code necessary for your customizations, and add the JAR file(s) to the lib folder of your Wowza Streaming Engine installation. In order to create a JAR you will need to use a Java Integrated Development Environment, or IDE, such as Eclipse to write your Java class files. This will encapsulate into a JAR file.
It is beyond the scope of this blog post to teach you the basics of Java programming, but you will learn how modules work and what you can do to start exploring Java development with Wowza Streaming Engine.
What Exactly Can Modules Do?
There are number of Wowza Streaming Engine extensions. The most common are application modules, server listeners and HTTP providers. Here is a quick summary of each:
Application Modules
By far the most widely utilized module extension type, application modules are loaded when an application starts in Wowza Streaming Engine. In Java, this extension type extends the ModuleBase class. By default, applications start whenever a first connection is made to an application. There are two applications automatically created in a standard Wowza Streaming Engine installation: live and on-demand (named “live” and “vod,” respectively).
The Application.xml file found in the conf/live directory specifies the attributes of the live application, and the Application.xml found in the conf/vod directory specifies those of the vod application. Near the end of the Application.xml file, you’ll find the modules that are loaded into memory for each of these applications listed in the <Modules> node. For example, the modules commonly found are:
<Modules>
<Module>
<Name>base</Name>
<Description>Base</Description>
<Class>com.wowza.wms.module.ModuleCore</Class>
</Module>
<Module>
<Name>logging</Name>
<Description>Client Logging</Description>
<Class>com.wowza.wms.module.ModuleClientLogging</Class>
</Module>
<Module>
<Name>flvplayback</Name>
<Description>FLVPlayback</Description>
<Class>com.wowza.wms.module.ModuleFLVPlayback</Class>
</Module>
</Modules>
These stock modules enable the basic functionality needed by applications in order to stream content. You can add new <Module> entries to this list to expand the capabilities of the application. You can also use the Wowza Streaming Engine Manager to access and modify these entries by following these steps:
- Click the Applications button in the main top navigation menu of the manager.
- Select an application on the left navigation panel.
- Choose the Modules tab in the main content area. Below is an example image.
Note: You must enable “Allow access to advanced properties and features” on your user account on the Wowza Streaming Engine installation in order to see the Modules tab. Click “Server” (main top menu), “Users” (left panel), “Edit” (pencil icon) to access this preference.
So what can custom application modules do? If there’s a feature in a Wowza Streaming Engine application that you’d like to make more dynamic or flexible, modules will likely be the answer. Application modules make it possible to:
- Customize the handling of the Wowza Transcoder beyond the controls offered by the XML templates. For example, you may want to process a higher-resolution incoming stream differently than a lower-resolution incoming stream.
- Load scheduled events from a separate web/data service into an application space to start and stop the recording of a live stream at a specific time.
- Detect publish/unpublish events on live streams, and perform secondary actions, such as injecting video-on-demand (VOD) clips into a live stream when a stream unpublishes.
- … and much more. (Check out Part 2 in our series for more examples.)
Server Listeners
A server listener loads when Wowza Streaming Engine starts. You would employ this type of extension when you need a global behavior across one or more Wowza applications. One of the most popular Wowza add-ons is a basic stream scheduler, which queues on-demand content to play at a specific time into a live stream, just like a TV broadcast of pre-recorded content. In Java, a server listener implements the Wowza native IServerNotify interface, which lets you specify handlers for server initialization, creation and shutdown.
HTTP Provider
Wowza Streaming Engine ships with several default HTTP providers that return information or data to the requestor. This type of extension, which typically extends the Wowza native HTTP2Provider class, intercepts HTTP requests sent to a Wowza URL.
HTTP providers are configured in the VHost.xml file located in the conf directory of the Wowza Streaming Engine installation. An HTTP provider is mapped to a specific request filter so that Wowza Streaming Engine knows to direct requests to a specific implementation. The VHost.xml has two groupings of HTTP providers: one for the default port 1935 (and typically port 80 as well), and another grouping for SSL port 443.
The list of providers is a prioritized list. Each HTTP request that does not map to a default HTTP streaming packetizer (ex. http://wowza.mycompany.com/live/myStream/playlist.m3u8) will be checked against the list of HTTP providers in the VHost.xml, starting at the top of the list and proceeding until it finds a match.
If you open the VHost.xml file in a text editor, you’ll see that the very last HTTPProvider node in the first HostPort grouping shows:
<HTTPProvider>
<BaseClass>com.wowza.wms.http.HTTPServerVersion</BaseClass>
<RequestFilters>*</RequestFilters>
<AuthenticationMethod>none</AuthenticationMethod>
</HTTPProvider>
This provider, HTTPServerVersion, returns the current version of the Wowza Streaming Engine installation. When you navigate a browser to the base URL of a Wowza Streaming Engine installation (ex. http://origin.cdn.councilcast.ca), you’ll see the version number returned as text (see image below).
There is also an optional HTTP provider that returns sidecar caption files for HTTP URLs that end with *.ttml, *.srt, *.scc, or *.vtt. For example, the URL http://wowza.mycompany.com/vod/_definst_/captions/introduction.srt would serve an SRT caption file stored in a directory named “captions” in the content folder specified for the vod application.
You can choose to disable any of the default HTTP providers in the VHost.xml simply by commenting out or deleting its <HTTPProvider> node from the list.
In my own work, I’ve built HTTP providers that return JSONP payloads to web video players, providing extended viewing data about content being delivered by Wowza Streaming Engine. For example, if you load the following URL in a browser:
http://hosted.videorx.com/streamconnections.js?id=IM8MT
… you will see JSONP data showing the latitude and longitude of anyone viewing a sample movie trailer hosted on the Wowza server. If no one is watching the video, the HTTP provider returns an empty JavaScript array:
var rxViewerLocations = [];
However, if you load the sample movie trailer in a web browser:
http://s3.videorx.com/player/embed.html?id=IM8MT
… and then reload the previous URL with the JSONP data return, you will see your own geo IP information included in the JavaScript array.
This custom HTTP provider that I wrote is second-to-last in the HTTPProviders list in that server’s VHost.xml, just above the HTTPServerVersion provider.
Note: You should never insert an HTTP provider after the version provider module, as it’s the final wildcard (*) in the prioritized list.
<HTTPProvider>
<BaseClass>com.videorx.wms.modules.HTTPStreamIPConnectionsJavaScript</BaseClass> <RequestFilters>*streamconnections.js</RequestFilters>
<AuthenticationMethod>none</AuthenticationMethod>
<Properties>
<Property>
<Name>maxMindUserId</Name>
<Value>00000</Value>
<Type>String</Type>
</Property>
<Property>
<Name>maxMindLicKey</Name>
<Value>0000000</Value>
<Type>String</Type>
</Property>
<Property>
<Name>omitLastOctet</Name>
<Value>false</Value>
<Type>Boolean</Type>
</Property>
</Properties>
</HTTPProvider>
The RequestFilters for this provider entry instruct Wowza to pass all requests that end with “streamconnections.js”, not including any query parameters, to the HTTPStreamIPConnectionsJavaScript class that I wrote in Java. This HTTP provider was built to also accept parameters specified as Property nodes. The Java code for the module can access these values to allow easier modification of these values outside of the module.
Where to Go from Here?
Now that you have learned about the basics of Wowza modules, what do you do next? If you’re already familiar with the Java programming language, it’s just a matter of downloading the Wowza IDE and learning the specific APIs you need for your custom functionality. You can learn more about the Wowza IDE at: https://www.wowza.com/docs/how-to-extend-wowza-streaming-engine-using-the-wowza-ide
The Wowza engineering team has also made many extra extensions available for your use, without requiring you to learn the Java to do it! (I also find that their examples are a great way to learn how to use the Wowza APIs.) You can find all of their latest contributions on GitHub at: https://github.com/wowzamediasystems