Red5 Documentation

Create a Red5 Pro Server Application

Overview

In this tutorial, we will walk through the steps to creating your first Red5 Pro Server Application using maven as our build/dependency management tool. In the process you will learn how to create the project structure, configure the application, handle application lifecycle related events, package/deploy as well as test your new application.

Download the Red5 Pro Server Download the latest Red5 Pro Server!

Register A Red5 Pro Account

If you have not done so already, register for an account at https://account.red5.net.

* A Trial Account allows for up to 10 concurrent connections, while the Professional license has no connection limit.


Requirements

The following are required to setup the Red5 Pro Server and to follow along with this tutorial:

The Red5 Pro server requires Java 1.7+ or higher. Install Java 1.7+ or higher if not already installed on your machine.


Red Pro Server Installation

  1. Download the Red5 Pro server from the downloads section of the Red5 Pro Accounts site.
  2. Unzip into a location on your local system. For the purposes of this tutorial, we will unzip the Red5 Pro server to: /Users/red5pro-user/red5pro on OSX or /home/red5pro-user/red5pro on Linux.
  3. Start the Red5 Pro server:
    •  On OSX & Linux: Open Terminal, cd into your Red5 Pro install directory and issue this command: ./red5.sh
    •  On Windows: Navigate to the Red5 Pro install directory in a File Browser and double-click on red5.bat
  4. After the server has started, open a web browser and navigate to http://localhost:5080
  5. If the server has started successfully, you should see the default landing page for the Red5 Pro server install
    •  The landing page can be found at /webapps/root/index.jsp of your Red5 Pro installation. You can modify or remove it as desired. For now, we will use it to navigate around and demonstrate what the Red5 Pro server can do!

Eclipse IDE

Watch a demonstration of the current section

For the examples, we will be demonstrating how to set up the project in the Eclipse IDE. The steps for setup should be transferrable to the IDE of your choice, as it is the code and method of deployment that we will be more focused on.

Source Code

The source for this example can be checked out from the following Github repository:
https://github.com/red5pro/red5pro-dev-series.git

Video Walk-Through

This documentation has an accompanying video walk through that you can follow as you are developing.

Create a Red5 Pro Application


Create Project

When the Red5 Pro Server is run, applications are accessible using a web browser from the default port of 5080. If you have the Red5 Pro Server currently running on your machine, you can visit http://localhost:5080 to see the default landing page.

The default landing page and any other web accesible applications are stored in the /webapp directory of the Red5 Pro server. In this section, we will be creating a new application to be deployed to this directory. We will utilize the /webapp/live shipped with the Red5 Pro Server distribution and create our first Red5 Pro server application.

Watch a demonstration of the current section
  1. From the main menu of the Eclipse IDE, select File > New > Other…
  2. Expand the Maven folder
  3. Select Maven Project
  4. Click Next
  5. Leave the default options
    Red5 Pro Application
  6. Click Next
  7. Type “webapp” in the Filter text input field
  8. Select the maven-archetype-webapp from the filtered results
    Red5 Pro Application
  9. Click Next
  10. Using Reverse domain name conventions, set your Group Id
  11. Type “example” in the Artifact Id text input field
  12. Click Finish
    Red5 Pro Application
  13. Verify that your workspace is similar to the following:
    Red5 Pro Application

Configure Project Dependencies

Watch a demonstration of the current section
  1. Double Click the pom.xml file
  2. Select the pom.xml tab from the bottom of the pom editor
    Red5 Pro Application
  3. Add the following three dependencies under the junit dependency. These dependencies add the Servlet and Red5 dependencies which are required for our project to build properly.
          <!-- https://mvnrepository.com/artifact/org.apache.tomcat/tomcat-servlet-api -->
          <dependency>
              <groupId>org.apache.tomcat</groupId>
              <artifactId>tomcat-servlet-api</artifactId>
              <version>8.5.11</version>
              <scope>provided</scope>
          </dependency>

          <dependency>
              <groupId>org.red5</groupId>
              <artifactId>red5-parent</artifactId>
              <version>1.0.10-M9</version>
              <type>pom</type>
          </dependency>

          <dependency>
              <groupId>org.red5</groupId>
              <artifactId>tomcatplugin</artifactId>
              <version>2.0.9</version>
          </dependency>

          <!-- https://mvnrepository.com/artifact/org.red5/red5-server -->
          <dependency>
              <groupId>org.red5</groupId>
              <artifactId>red5-server</artifactId>
              <version>1.0.10-M9</version>
              <type>jar</type>
              <scope>provided</scope>
          </dependency>
  1. Add the following properties below the build tag like so:
      <build>
        <finalName>example</finalName>

        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <version>3.5.1</version>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>

            <plugin>
                <groupId>org.apache.felix</groupId>
                <artifactId>maven-bundle-plugin</artifactId>
                <extensions>true</extensions>
            </plugin>

        </plugins>
      </build>
      <properties>
        <maven.compiler.target>1.8</maven.compiler.target>
        <maven.compiler.source>1.8</maven.compiler.source>
      </properties>
  1. From the main menu of the Eclipse IDE, select File > Save
  2. Right-Click the example project from the Project Explorer view
  3. Select Maven > Update Project…
  4. Verify that your build errors are no longer present

Setup Source Folder

Watch a demonstration of the current section
  1. Create the Java source folder by expanding the src > main folders
  2. Right-Click on the main folder and select New > Folder
    Red5 Pro Application
  3. Enter “java” in the Folder Name text field
  4. Click Finish. The java folder will automatically be added as a source folder in your project.

Setup Spring Configurations

Watch a demonstration of the current section
  1. We will now add the Red5 Pro context files to our project by locating the live application that is included with the Red5 Pro Server distribution.
  2. Select and Copy the WEB-INF folder
    Red5 Pro Application
  3. From Eclipse, right-click the src > main > webapp folder in the Project Explorer view
  4. Paste the previously copied WEB-INF folder
  5. Click the Overwrite All button
  6. Delete the classes directory inside of src > main > webapp > WEB-INF
  7. Expand back into src > main > webapp > WEB-INF and open red5-web.properties
  8. Modify the webapp.contextPath property to be /example
    Red5 Pro Application
  9. Expand src > main > webapp > WEB-INF and open the red5-web.xml file
  10. Edit the web.handler bean and set the class to com.red5pro.example.ExampleApplication (substitute the package structure according to the package you chose in Create Maven Webapp Project Step 10 above)
  11. Comment out the streams bean
  12. Verify that your red5-web.xml file looks similar to the following:
    Red5 Pro Application
  13. Expand src > main > webapp > WEB-INF and open the web.xml file
  14. Modify the display-name tag so that its contents are example
  15. Modify the context-param webAppRootKey so that its contents are example
  16. Add the WebSockets filter:

    <!-- WebSocket filter -->
    <filter>
        <filter-name>WebSocketFilter</filter-name>
        <filter-class>org.red5.net.websocket.server.WsFilter</filter-class>
        <async-supported>true</async-supported>
    </filter>
    <filter-mapping>
        <filter-name>WebSocketFilter</filter-name>
        <url-pattern>/*</url-pattern>
        <dispatcher>REQUEST</dispatcher>
        <dispatcher>FORWARD</dispatcher>
    </filter-mapping>

Create Application Class

Watch a demonstration of the current section
  1. From the Navigator pane in the Eclipse IDE, Expand the Java Resources source folder
  2. Right-Click on the src/main/java folder and select New > Class
  3. In the Java Class dialog, enter in the following field values:
    •  Package: com.red5pro.example (substitute your package structure as needed)
    •  Name: ExampleApplication
    •  Superclass: org.red5.server.adapter.MultiThreadedApplicationAdapter

    Red5 Pro Application
  4. Click Finish

Handle Application Events

Watch a demonstration of the current section
  1. Override two methods of the superclass MultiThreadedApplicationAdapter
  2. While still editing ExampleApplication.java, click on the Eclipse top level menu item Source > Override/Implement methods…
  3. Select appStart(IScope), appStop(IScope), appConnect(IConnection, Object[]) and appDisconnect(IConnection)
  4. Click Finish
  5. Enable WebSocket support in your application by adding this to your appStart() method:
    configureApplicationScopeWebSocket(scope);

where:

    /**
     * Configures a websocket scope for a given application scope.
     *
     * @param scope Server application scope
     */
    private void configureApplicationScopeWebSocket(IScope scope) {

        // first get the websocket plugin
        WebSocketPlugin wsPlugin = ((WebSocketPlugin) PluginRegistry.getPlugin(WebSocketPlugin.NAME));
        // get the websocket scope manager for the red5 scope
        WebSocketScopeManager manager = wsPlugin.getManager(scope);

        if (manager == null) {
            // get the application adapter
            MultiThreadedApplicationAdapter app = (MultiThreadedApplicationAdapter) scope.getHandler();
            log.debug("Creating WebSocketScopeManager for {}", app);
            // set the application in the plugin to create a websocket scope manager for it
            wsPlugin.setApplication(app);
            // get the new manager
            manager = wsPlugin.getManager(scope);
        }

        // the websocket scope
        WebSocketScope wsScope = (WebSocketScope) scope.getAttribute(WSConstants.WS_SCOPE);

        // check to see if its already configured
        if (wsScope == null) {
            log.debug("Configuring application scope: {}", scope);
            // create a websocket scope for the application
            wsScope = new WebSocketScope(scope);
            // register the ws scope
            wsScope.register();
        }
    }

For clean-up add this to appStop():

    WebSocketScopeManager manager = ((WebSocketPlugin) PluginRegistry.getPlugin("WebSocketPlugin")).getManager(scope);
    manager.removeApplication(scope);
    manager.stop();
  1. Use the inherited log property to logout connection events. Your source should mirror the following:
  public class ExampleApplication extends MultiThreadedApplicationAdapter implements ApplicationContextAware{

    private ApplicationContext applicationContext;

    @Override
    public void setApplicationContext(ApplicationContext applicationContext) throws BeansException {
        this.applicationContext = applicationContext;
    }

    @Override
    public boolean appConnect(IConnection conn, Object[] params) {
      log.info("appConnect");
      return super.appConnect(conn, params);
    }

    @Override
    public void appDisconnect(IConnection conn) {
      log.info("appDisconnect");
      super.appDisconnect(conn);
    }

    @Override
    public void appStart(IScope app) {
      log.info("appStart");

      configureApplicationScopeWebSocket(scope);

      super.appStart(app);
    }

    @Override
    public void appStop(IScope scope) {

      WebSocketScopeManager manager = ((WebSocketPlugin) PluginRegistry.getPlugin("WebSocketPlugin")).getManager(scope);
        manager.removeApplication(scope);
        manager.stop();

    super.appStop(scope);
    }

    /**
     * Configures a websocket scope for a given application scope.
     *
     * @param scope Server application scope
     */
    private void configureApplicationScopeWebSocket(IScope scope) {

        // first get the websocket plugin
        WebSocketPlugin wsPlugin = ((WebSocketPlugin) PluginRegistry.getPlugin(WebSocketPlugin.NAME));
        // get the websocket scope manager for the red5 scope
        WebSocketScopeManager manager = wsPlugin.getManager(scope);

        if (manager == null) {
            // get the application adapter
            MultiThreadedApplicationAdapter app = (MultiThreadedApplicationAdapter) scope.getHandler();
            log.debug("Creating WebSocketScopeManager for {}", app);
            // set the application in the plugin to create a websocket scope manager for it
            wsPlugin.setApplication(app);
            // get the new manager
            manager = wsPlugin.getManager(scope);
        }

        // the websocket scope
        WebSocketScope wsScope = (WebSocketScope) scope.getAttribute(WSConstants.WS_SCOPE);

        // check to see if its already configured
        if (wsScope == null) {
            log.debug("Configuring application scope: {}", scope);
            // create a websocket scope for the application
            wsScope = new WebSocketScope(scope);
            // register the ws scope
            wsScope.register();
        }
    }

  }

Create WebRTC Example Pages

Watch a demonstration of the current section
  1. Navigate to your WebRTC artifacts that you generated in the Video called Red5 Pro: Getting Started with WebRTC
  2. Copy the publisher.html, subscriber.html and lib directory
  3. Paste the copied artifacts in the src > main > webapp folder
  4. Open the publisher.html file and inside of publisher.init(…) change the streamName to myStream. Change the app property to example. Save file
  5. Open the subscriber.html file and inside of subscriber.init(…) change the streamName to myStream. Change the app property to example. Save file

Package And Deploy

Watch a demonstration of the current section
  1. Right-Click the example application from the Project Explorer
  2. Select Run As > Maven install

Test using WebRTC example

  1. Start the Red5 Pro server:
    •  On OSX & Linux: Open Terminal, cd into your Red5 Pro install directory and issue this command: ./red5.sh
    •  On Windows: Navigate to the Red5 Pro install directory in a File Browser and double-click on red5.bat
  2. After the server has started, open a web browser and navigate to http://localhost:5080/example/publisher.html
  3. Open a second browser window and navigate to http://localhost:5080/example/subscriber.html

Conclusion

Congratulations! You have just created your first Red5 Pro Server Application!

This tutorial only scratched the surface of what is capable with live streaming on the Red5 Pro Server. We hope you go forth and start stretching the limits 🙂


Troubleshooting

The following sections may aide in troubleshooting any issues may come across in trying the previous examples.

If you have further questions, please contact us at red5pro@infrared5.com

Required open ports

The following default ports are required to be open in order to allow for Live Streaming and Second Screen:

  • 5080 : default web access of Red5
  • 1935 : default Red5 RTMP port
  • 8554 : default RTSP port
  • 8088 : default Second Screen Client registry
  • 6262 : default Second Screen Host registry