Hello Wowza - Module Dev Tutorial

One of the best features of Wowza Streaming Engine® is that it comes with a powerful server side API, that allows you to implement your custom modules and add any special feature or behaviour that you need. Wowza server side modules can be written in Java and it's not a big deal to learn it up to the level that you need to write your first Wowza module. In this tutorial I would like to help beginners setting up the environment for Wowza module development. (Check out this if you are interested in debugging)

Installing Eclipse

Eclipse is a general purpose IDE (integrated development environment) that allows you to effectively develop Java applications. Wowza created a custom plugin that adds some nice features to it, which makes developing Wowza modules a lot easier for you. To use this, first you need to install Eclipse on your computer.

In practice Eclipse installation means downloading the zip file from their download area. Please make sure you download the package with the right bit version and OS. For using Wowza plugins, you need version 3.5+. When this article was written, the latest version was 4.4

Extract the contents of the downloaded zip file to your hard drive, e.g. c:\eclipse. You can start Eclipse by running the contained eclipse.exe file.

When Eclipse is first launched, you'll be asked to select a workspace location. A workspace is a directory, where you can put your separate projects into, think about each Eclipse project being one Wowza module for now. Eclipse is going to put different settings here into its .metadata folder.

Eclipse Workspace Selection

This is what you'll see after selecting your workspace

Eclipse Welcome Screen

Installing Wowza Eclipse plugin

Choose Help > Install new software

Install new software

Eclipse plugins are installed from so called "update sites". Wowza has one, that you need to add by specifying an arbitrary name and the repository url. Click on the "Add Site" button on the below dialog.

Add Wowza update site

Fill in the following details:

Add Wowza update site

Name: wowza URL: http://wowza.com/wowzaide2

After adding the new update site, you can choose this site on the "Available Software" dialog and the Wowza IDE 2 plugin should show up as an option:

Install Wowza IDE 2 plugin

Hit Next, accept the terms and that's it, you have successfully installed Wowza IDE plugin and you are ready to create your first Wowza module.

Creating your first Wowza Module

Go to File menu and choose New > Other

New Wowza Module

Choose "Media Server Project" from the list

New Media Server Project"

Fill in the dialog as follows:

New Wowza module settings

One key field here is the Wowza Media Server > Location. Here you need to browse the right folder where you have installed Wowza. Choose the root directory which contains bin, lib, and the others.

The location is needed as the Java libraries (jar files) needed for compilation will be added to the classpath from the lib folder. The new project will contain an Ant buildfile (build.xml) which will automatically copy your latest compiled module into that lib folder in order to be loaded into Wowza automatically.

On the next screen you are asked to specify the details for the Wowza module class that is going to be auto-generated for you.

Wowza module class settings

The package name can be arbitrary, it is used to keep your classes in a tidy hierarchy. The Java convention is using a reversed domain (which guarantees uniqueness more or less). The name field will be the name of the actual Java class that will extend the ModuleBase Wowza class which serves as the parent of all Wowza modules. The dialog allows you to predefine the API methods that you want to have in your module. We'll use onAppStart in this tutorial.

Having finished all this, you should see something like this, with the BUILD SUCCESSFUL message. As you can see I have made minor edits in the onAppStart method.

Wowza module build successful

Whenever you edit the sources a previously configured Eclipse builder invokes the generated build script (build.xml ant file), which packs the class files that are compiled by the Eclipse compiler into a jar file under your Wowza installation's lib dir. This is very handy for beginners, as you don't have to bother with deploying your module.

Now let's try our module in action. For that, we are going to use the live application that ships with Wowza by default. Create a folder called live under your Wowza installation's application folder, in my particular case it is w:\wowza-4.0.3\applications\live.

Create the same folder under conf, e.g. w:\wowza-4.1.2\conf\live and copy the Application.xml file from conf to conf\live.

Add your module to the live application by editing the Application.xml. Add a new <Module> tag under <Modules>

  <Modules>
   ...
   <Module>
    <Name>HelloWowza</Name>
    <Description>Wowza Module Tutorial</Description>
    <Class>com.wowzatoolbox.tutorial.HelloWowza</Class>
   </Module>
 </Modules>

The <Name> tag can be anything, the important thing is the <Class> really, you need to specify the so called "fully qualified name" of your module class, which is the package name you gave previously plus the name of the class, separated by a dot.

Start Wowza and test the module

Now it's time to start up your Wowza Streaming Engine® and trigger the start of the live application too. You can do this for example by pushing a stream into the application from Flash Media Live Encoder, or by connecting with a player to the application. Most probably you know how to do it.

In the Wowza logs, in my case it's on the console output, you should see the greeting from your first custom Wowza module:

INFO server comment - Wowza Streaming Engine is started!
INFO server comment - onAppStart: live/_definst_ 
INFO server comment - Hello Wowza by streamtoolbox.com
INFO application app-start _definst_ live/_definst_
INFO session connect-pending 127.0.0.1 -
INFO server comment - onConnect: 1314455843
INFO session connect 127.0.0.1 -

That's it. This article is the beginning of a series about Wowza module development. Stay tuned for the next episodes and check out my other module development articles. The next article to read is:

Any comments, questions and suggestions are welcome.

Comments

Hi, thanks for a great tutorial.

I found one typo in the xml that you may want to correct:
com.wowzatoolbox.tutorial.HelloWowzwa

many thanks, Lee

God Bless You!
I never developed in Java. Sometimes it is inevitable to compile something for wowza. Was lost in a forrest of Eclipse. Your tutorial is great.
Regards

Thank you, good to see you find it useful! :-)