Configure an External Wowza Media Server

Overview

This page provides the necessary instructions for installing and configuring a Wowza media server for use with the EchoSystem.

You can install Wowza on the same server as the ESS or on a separate server. Both configurations are referred to as "external" because you will select "External Flash Server" in the Streaming Settings section of the System Settings page on the ESS. "Internal" configurations are only available for existing customers who are upgrading; the instructions on this page do not apply to internal configurations.

For performance and scalability, we highly recommend using a dedicated server solely for the purpose of streaming Flash content that the EchoSystem produces.

Preparing for Installation

EchoSystem 5.5 requires the use of Wowza v3.5, v3.6 or v4. Be sure the server you will be using meets Wowza's specifications. Refer to the Wowza FAQs page for details and installation recommendations.

1. Wowza is a Java application and requires Java Runtime Environment (JRE) version 6 or 7. Installers for your platform are available from Oracle.
2. Download the Wowza Media Server installation bits for your platform from the Wowza installer page.
3. Make a note of your Wowza license key, which will be required during installation.
4. Proceed with the installation of Wowza on the server.

The next section provides instructions on configuring the content storage location that Wowza will use. The flash content does NOT need to be in the same location as the program files.

Co-locating the Flash Content

The ESS System Settings allow you to identify the specific location where the ESS is to deposit the Flash content it generates. This location can be either a local volume or a UNC-addressable path. The location is represented as the "Flash Folder" field in the Streaming Settings section of the System Settings configuration.

In order for the Wowza server to find and stream the Flash content delivered by the ESS, that content must be stored on a volume that the Wowza application has read and write access to. This can be a local drive (that the ESS writes to via a network share), a mounted SMB/CIFS file share, or mounted NAS/SAN storage.

Consult your operating system’s documentation for configuring file shares, or contact Echo360 Technical Support for guidance.

Installing the On-Demand Bundle

For on-demand Echoes and Apreso content, Echo360 has created an archive that contains the proper directory structure needed inside the Wowza application directory, along with the required files for configuration. For reference, the directory structure required is shown in the Configuring Wowza section below.

These steps are only necessary if you are configuring an external Wowza server for the first time.

1. Download the latest Wowza On-Demand Bundle available from the Customer Support Portal.
2. Extract the contents of the downloaded zip file to your Wowza Media Server installation root. This will create the necessary folder structure, and will deposit Application.xml configuration files into each subfolder of the /conf directory.

Installing the Live Streaming Bundle

For live content and the chat and presence features, Echo360 has created a script that automatically installs the proper directory structure needed inside the Wowza application directory, and adds the required files for configuration as well as additional required Java libraries.

The following steps are required if you are configuring an external Wowza server for the first time, OR if you have an existing external Wowza server that you want to configure for live streaming.

1. Download the latest Wowza Live Streaming Bundle available from the Customer Support Portal.
2. Extract the contents of the downloaded zip file to a temporary location on your Wowza server.
3. Open the included README.html document and follow the instructions appropriate for your platform.

Configuring Wowza

Wowza Media Server relies on virtual servers, called applications, to serve the correct content based on the document root given in URL requests. These applications are configured by creating directory structures and XML documents at specific locations within the Wowza instance’s installation folder.

Both live and on-demand streaming, along with their supporting components, are configured as separate Wowza applications with distinct parameters. There are four applications in total:

• One for on-demand Echo streaming,
• One for live Echo streaming,
• One for the chat and presence functions of live Echoes,
• One for legacy Apreso content.

Installing the On-Demand and Live Streaming bundles, covered in the above sections, creates the necessary application folders and provides the Application.xml files and Java libraries needed for Wowza to deliver ESS streaming content.

Once those steps are completed, use the below information to verify the proper folder structure and customize the Application.xml files for your system.

1. Starting at the installation root for the Wowza server instance, verify that the necessary components of the directory tree (in addition to the program files) appear. By default, the installation root for Wowza is:
   
   • Unix: /usr/local/WowzaMediaServer/
   • Windows: C:\Program Files\Wowza Media Server\

2. Within the installation root, the directory structure should appear as follows, noting that if you did not install the Live bundle, you will not see the /echolive/ or /echotextchat/ folders:

   WowzaMediaServer
   --- applications
      --- apreso
      --- echo
         --- keys
             --- _definst_
         --- sharedobjects
             --- _definst_
      --- echolive
         --- sharedobjects
             --- _definst_
      --- echotextchat
   --- conf
      --- apreso
      --- echo
      --- echolive
      --- echotextchat

3. Next, you will need to edit one line in each of the installed Application.xml files (each conf/{application name} folder contains one) to define the location where Wowza should look for your Flash content.
4. The /echo/, /echolive/, and /apreso/ Application.xml files all contain a parameter named StorageDir in the first Streams stanza near the top of the file:

<StorageDir>C:\Echo360\FlashStreaming</StorageDir>
   
   The default value of this parameter will not be valid for most deployments.
5. In each file, replace the path between the StorageDir tags with the location that corresponds (or will correspond) to the Flash Folder defined on your ESS System Settings page. As defined above this is the location where the ESS will deposit the Flash content it generates, and can be either a local volume or a UNC-addressable path.

6. The /echotextchat/ Application.xml file is different. Near the bottom of the file, this document contains a set of property values encoded as follows:

   <Properties>
       <Property>
           <Name>objectstoragedirectory</Name>
           <Value>
           ${com.wowza.wms.context.VHostConfigHome}/echotextchat/rso
           </Value>
       </Property>
       <Property>
           <Name>chatlogstoragedirectory</Name>
           <Value>
           ${com.wowza.wms.context.VHostConfigHome}/echotextchat/chatlogs
           </Value>
       </Property>
       <Property>
           <Name>echosystemdirectory</Name>
           <Value>
           ${com.wowza.wms.context.VHostConfigHome}/
           </Value>
       </Property>
   </Properties>

7. Replace the ${com.wowza.wms.context.VHostConfigHome} string with the value entered for StorageDir in the other three Application.xml files BUT leave the appended paths (where this string precedes the path values) in place.

Changing this last property value identifies the echosystemdirectory as the storage or Flash Folder directory. This tells Wowza to write its chat and presence logs to a location accessible to the ESS, in a subfolder called "content" beneath the Flash storage root.

Finally, if you are using Wowza v4, make the following change to the server.xml file located in the /conf/ folder of the Wowza installation root:

• Change the DefaultStreamPrefix value from "mp4" to "flv"

Enabling iOS Live Streaming

Before proceeding, ensure that you have followed the steps above and modified the Application.xml file for each of the four applications (echo, echolive, echotextchat and apreso).

As of EchoSystem 5.2, iOS streaming is supported for live presentations. However for this to work as expected, you must edit the Server.xml file located in the /conf/ folder of the Wowza installation root as follows.

1. Open the Server.xml file for editing, and do the following:

   1. Insert the following entry in the <ServerListeners> section of the Server.xml file:

      <ServerListener>
      	<BaseClass>com.echo360.streaming.live.MediaCaster</BaseClass>
      </ServerListener>

   2. Insert the following entries at the bottom of the Server.xml file, placing them after the final <Properties> tag and before the final </Properties> tag (creating properties within the last Properties tag):

      <Property>
          <!-- the directory that contains the streams.txt file -->
          <Name>StreamMonitorDir</Name>
          <Value> ${com.wowza.wms.context.VHostConfigHome}/monitor</Value>
      </Property>
      
      
      <Property>
          <!-- the wowza application that the streams will be activated on. Default is echolive -->
          <Name>EchoLiveApplication</Name>
          <Value>echolive</Value>
      </Property>
      
      
      <Property>
          <!-- time the thread waits between checks of the streams.txt file. Default is 5 seconds -->
          <Name>WaitInterval</Name>
          <Value>5000</Value>
      </Property>

2. Replace the ${com.wowza.wms.context.VHostConfigHome} string with the value you used for the StorageDir in the Application.xml files.

For your reference, a file named example-Server.xml is included with the Live Bundle files, that shows this change made to the file. This file contains a basic Wowza server configuration along with all of the necessary changes for iOS live streaming. It is not automatically installed as a part of the bundle (otherwise, it would have overwritten your existing Server.xml file).

Once all the configuration files have been edited and saved according to these instructions, restart your Wowza service.

Configuring ESS

There are five especially important fields in the Streaming Settings section of your ESS System Settings that you will need to validate before the ESS can provision your configured Wowza server to stream content. The information shown below is also contained in the Streaming Settings section of the System Settings configuration page.

1. Log in to the ESS and navigate to the Configuration > System Settings.
2. Click the Edit button.
3. Scroll down to the Streaming Settings section of the page.
4. For the Flash Streaming parameter, select External Flash Server.
5. For the External Flash URL parameter, compose a URL consisting of the RTMP protocol, the fully-qualified domain name (FQDN) of the Wowza server, the on-demand application name (echo), and a _definst_ pointer. The URL should look similar to the following:
   rtmp://fqdn.of.wowza.server/echo/_definst_
6. For the Live Flash URL parameter, compose a similar URL consisting of all the same elements, but using the live application name (echolive), as follows:
   rtmp://fqdn.of.wowza.server/echolive/_definst_
7. The Flash Folder parameter should already reflect the location where you have chosen to store your Flash content.
8. The Live Streaming Server Host parameter should represent the FQDN (without schema or path components) of your Flash server.
9. Once all these parameters are validated, click Save.

The ESS is now configured to direct your viewers’ browsers to call the external Wowza streaming server when playing live and on-demand Echo content.