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)
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
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
This is what you'll see after selecting your workspace
Installing Wowza Eclipse plugin
Choose Help > 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.
Fill in the following details:
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:
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
Choose "Media Server Project" from the list
Fill in the dialog as follows:
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
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.
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
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
Create the same folder under
w:\wowza-4.1.2\conf\live and copy the
Application.xml file from
Add your module to the
live application by editing the
Application.xml. Add a new
<Module> tag under
<Modules> ... <Module> <Name>HelloWowza</Name> <Description>Wowza Module Tutorial</Description> <Class>com.wowzatoolbox.tutorial.HelloWowza</Class> </Module> </Modules>
<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 -
- How to debug a Wowza module from Eclipse
- Brief description of the API modules of
Any comments, questions and suggestions are welcome.