Red5 Media Server Development Setup Tutorial

This tutorial was written in November, 2008 and covers one way of setting up the Red5 Flash Media Server in a Windows development environment. The intended audience is users that are familiar with Red5 and are interested in developing a custom application. If you just want to test red5, dont follow this tutorial. Instead grab one of the official releases at: http://www.osflash.org/red5

Software Tools

1. Java SE Development Kit (JDK): http://java.sun.com/javase/downloads/index.jsp
2. Apache Ant: http://ant.apache.org/
3. Subversion: http://subversion.tigris.org/
4. Adobe Flash Player: http://www.adobe.com/products/flashplayer/

Before We Start:

Over a year ago I started working with Red5 which ultimately caused me to have to learn Flash development as well. If you are new to Red5 and new to Flash, its possible you will find this tutorial extremely frustrating as I probably would have a year ago. Your best bet of getting started with red5 is the flashextensions video tutorials. I understand that all the acronyms that come along with Java and flash are frustrating when trying to learn. Just stick with it, and you'll be a proffessional before you know it.

Step 1 - Install The Java Development Kit

Red5 runs and is built on Java, the first step of setting up a development environment is getting the latest Java Development Kit. Java is notorious for using confusing acronyms in their product names. Currently the Java Development Kit goes by Java SE Development Kit. Just look for the download that contains the words “Development Kit” You can install the Java Development Kit (JDK) wherever you want, but you will need to know the exact path to the installation folder in later steps. I had an old version of the JDK on my computer, so I un-installed it and started with the newest version.

Step 2 - Set Windows Environment Variables for Java

After you have installed the JDK, the first thing to do is edit your Windows environment variables. Regardless if using Linux or Windows, the JAVA_HOME environment variable always needs to be set in order to ensure that other applications can see that java is installed. In all versions of Windows that I am familiar with , Environment Variables can be accessed via accessing the "My Computer" or "Computer" properties, then going to the "Advanced" tab / pannel. It should be noted that I am using Windows XP as a reference. Once in the Environment Variables dialog box, under the "System variables" list, click on the "New" button. For "Variable Name" put in JAVA_HOME. For "Variable Value" put in the exact OS specific path to the installation directory of the Java JDK. As an example, I made my Variable value: G:\java\jdk1.6.0_10

Step 3 - Install Apache Ant

This is the question I asked when I first had to use this tool. Apache Ant is a build tool for Java applications. It basically allows several java applications to be compiled at once. Its like a Windows batch script or a C++ makefile. The method of development with Red5 that I am showing uses Apache Ant in order to build the server and its associated applications using only one command and a build script.
When you go to the Ant website, get the .zip version of Ant and simply unzip it to a place on your hard drive. Just like the JDK, you need to know the exact path to Ant and specifically its bin directory.

Step 4 - Set Windows Environment Variables for Ant

Just like Java, Ant also requires Environment Variables to be set in order to ensure proper operation. Ant requires two variables. Just like Java, under the System variables section in Environment Variables, you should create a New variable. This time give it the Variable name "ANT_HOME" and a value of the directory it is installed (unzipped) in.

The second modification for ant is to add its bin directory to the "Path" System variable. If you scroll down under the "System variables" section you will see a variable named "Path" click on it and click "Edit". For Variable value, you will see several operating system directory paths separated by semicolons. You need to add the path to ants bin folder to this list.

For example, an exerpt from my Path Variable values reads: To add Ant to it, I would modify it to look like: In my case, Ant's bin directory is located at: G:\java\apache-ant-1.7.1\bin

Step 5 - Test Ant and Java at the Command Line

In order to make sure that we have installed the Java JDK and Ant correctly, open a command prompt window by going to start, run, and type cmd.
In the command prompt window first type "java" and you should see a whole bunch of usage parameters get listed. This means Java is installed correctly.
The next thing to type is "ant". You should see some dialog like "build.xml does not exist". This means ant is installed properly as well.
If for some reason, the java or ant commands aren't responding properly it probably means that you made an error while configuring the Environment Variables.

Step 6 - Install Subversion (SVN)

What is Subversion?
Subversion is a code version tool that allows multiple programmers to work on a project at the same time. Typically whoever is in charge of the project looks over the various code versions, the commits the best version to the "trunk" or main version of the application. If you see people talking about the Red5 "trunk", it means it is the main working version of the code.
We need subversion installed in order to get the latest main working version of the Red5 code. If you get a binary version of subversion that doesn't have an installer, make sure to add it to your Environment Variables so that it can be accessed from the command line.
There are various ways of getting subversion and I am not going to cover them in this tutorial, I hope not to your detriment.

Step 7 - Get the Trunk of Red5 from the Google Code Repository

Assuming that you have subversion installed; create a directory, that you want all the code from Red5 to go into. Open up the Windows command prompt; start, run, cmd. And change directories to the folder you just created. Also open up an Internet browser and navigate to the googlecode Red5 project page. (As of 2008, Red5's source is housed using googlecode)
Under the "Source" tab on the googlecode page, you'll find the subversion command line command to "checkout" or get the source code of the latest trunk of Red5. Reverberating the command on the googlecode page:

When you run the command, you should see a list of files scroll down the screen as they are downloaded. You'll also notice the folder you ran the above command in start to become populated with files and directories.

Step 8 - Try to compile and run Red5 using Ant

Assuming all of the previous steps have worked, you are first entitled to a bit of congratulations. Now we get to move onto the fun stuff.
Open a command prompt and change directories to the folder that you just used svn to download all of the code into. You should see in the base red5 directory a file called "build.xml". This is the Ant build script for compiling Red5.
In order to compile the server, make sure your command prompt is at the location of the same directory that build.xml is located in. Simply run the command:

and you will see the build process start. You should see a large list of Google dependencies scroll by, some of which may be downloaded on the spot. During this process you may get firewall prompts from Java. Allow exceptions in your firewall. If all goes well you will continue to see things fly by in the console window until all the output stops and the last prompt will read. "Startup done in ", then it lists the milliseconds. As long as you leave this command prompt window open, Red5 will be running.

Step 9 - Test and Run Red5

Assuming Red5 has started correctly, open an internet browser again and type in:






You should be presented with a Red5 webpage which has various links. If this doesnt work, we can still run the tests directly from their folders which I will explain shortly. A little ways down the page, you will see a message that says "Most of the demos must be installed first, click here to select the demos you want to install". This is different from the past, as the demos used to always come bundled with the code. In any case, click on the link to open the installer. If you didnt get anything when trying the localhost link mentioned above and you are certain red5 has compiled and is running, the swf for the demo application installer is located in: red5 code directory/webapps/installer

Step 10 - Install a Demo Application For Further Testing

When the installer first opens, just click on "Connect". The installer should connect and list all of the demo applications available. I would suggest that you install oflaDemo by simply highlighting its name and clicking Install. After the installation, if you look in the red5 install folder/webapps/ you should notice that a new folder "oflaDemo" has been created. The webapps folder is where all of the source code for Red5 applications is placed. When we run the ant build process, applications are compiled and copied from webapps to the dist folder.

After the installer is finished, it would be a good idea to stop Red5 and build it again. So in the command prompt window, make sure it has window focus and hit:

This will kill the Red5 server. Re-build the server simply by typing:

Assuming everything went well, you should be able to again navigate to:

This time click on the first link which talks about running Red5 demos. Click on the "view demo" link for OFLA Demo. If for some reason you cant get the web browser page again, the swf for OFLA Demo is located in webapps/root/demos

When you first try and connect locally to your running Red5 server, you may get a Flash Player Security settings dialog that wont allow you to connect to localhost. If this occurs, then you have to go to the online Flash Player Global Security Settings panel and allow permissions to connect to your local red5 directory. If you are able to connect to the oflaDemo application, you should see the red5 console window acknowledge a connection then see a list of movie trailers you can stream. Click on a trailer name to stream it.

Step 11 - Solving Common Errors

Below I will list a few of the common errors I have seen recently and provide links to resources about fixing them. If none of these work for you, then please just be patient and stick with it. Red5 is a really fun tool to work with once you know how it works.

1. When trying to run the demo applications, you cant connect and the console window says "Closing RTMPMinaConnection from 127.0.0.1: to localhost with id ##### due to long handshake"

If you get the above error, its likely that you haven't installed the server instance of the demo application you are trying to connect to! Make sure you have used the installer to install the specific application you are trying to demo. Although the demos page lists and has all of the flash programs for the samples, the server doesn't come pre-installed with them if you download the source code version.

2. When trying to run the command "ant server" for the first time, you have problems with the googlecode dependencies and the build process fails.

As far as I understand, Red5 uses what is called "Ivy" to check for dependencies. I have had luck in the past clearing my ivy cache then trying to build the server again. Some of the details on this can be found in http://www.nabble.com/Groboutils-missing-again-td20095601.html Simply put, you can try and run the command:
then

which should make you start downloading .jar files again. I think this mainly happens when you have run previous versions of Red5 in the past on the same machine.

3. When trying to run any "ant" commands, you get the message ANT_HOME is set incorrectly or ant could not be located. Please set ANT_HOME.

In this instance it means you have installed java correctly, but ant isnt setup correctly. Make sure you set both the ANT_HOME environment variable and also added the path to ant's bin folder to your system path.