Wowza Media Server Pro Examples: Stream Name Alias

Description

This package includes a module that adds support for stream name aliases. This system can be used to simplify complex url based stream names, provide security to limit the valid stream names used or just a simple method for mapping one stream name to another. The source code is included so the system can be extended if needed.

To install

1. Install Wowza Media Server 2 (preview 7 or greater).

2. Copy files conf/aliasmap.play.txt and conf/aliasmap.stream.txt to the [install-dir]/conf/ folder.

3. Copy file lib/wms-plugin-streamnamealias.jar to the [install-dir]/lib/ folder.

4. To add this module to an application, edit [install-dir]/conf/[application]/Application.xml

Add an entry the ModuleStreamNameAlias module as the last entry in the <Modules> list

<Module>
	<Name>ModuleStreamNameAlias</Name>
	<Description>ModuleStreamNameAlias</Description>
	<Class>com.wowza.wms.plugin.streamnamealias.ModuleStreamNameAlias</Class>
</Module>

In the same Application.xml, add these properties to the <Properties> list below <Modules>. These properties specify the location of the alias files, and turn on/off debug logging, for this application:

<Property>
	<Name>aliasMapFileStream</Name>
	<Value>${com.wowza.wms.context.VHostConfigHome}/conf/aliasmap.stream.txt</Value>
</Property>
<Property>
	<Name>aliasMapFilePlay</Name>
	<Value>${com.wowza.wms.context.VHostConfigHome}/conf/aliasmap.play.txt</Value>
</Property>
<Property>
	<Name>aliasMapPathDelimiter</Name>
	<Value>/</Value>
</Property>
<Property>
	<Name>aliasMapNameDelimiter</Name>
	<Value>=</Value>
</Property>
<Property>
	<Name>aliasMapDebug</Name>
	<Value>true</Value>
	<Type>Boolean</Type>
</Property>

Note: When this alias package is configured for a given application it will replace the built-in alias system that is implemented using .play and .stream files.

To Use

An alias file has the following format:

# comment
[pattern]=[alias]

The [pattern] is tested against the stream name. The first [pattern] that completely matches the stream name is used. Patterns can included wildcards (*). A pattern can contain multiple wildcards.

Alias files will be re-read by Wowza Media Server each time a change is made to the file.

There are two different types of aliases: play aliases (defined for this example in [install-dir]/conf/aliasmap.play.txt) and stream aliases (defined for this example in [install-dir]/conf/aliasmap.stream.txt). The name and location of the alias files is specified in the properties above, per application. Each application can define a different set of alias files as defined by the application properties aliasMapFilePlay and aliasMapFileStream

Play Aliases

The play aliases are applied each time a play operation is executed. The stream name that is sent to Wowza by a client is run through the alias system. If a match is found it is tranformed. If no match is found an error is returned to the client. Here are a three sample play alias files

An play alias file has the following format:

# comment
[pattern]=[alias]

Example play alias file 1:

# Prepends mp4: and mp3: to files with common H.264/MP3 extensions. The first match is used, no more lines are compared. Note that the default rule *=${Stream.name} in the last line allows any stream that has not been matched.
*.mp4=mp4:${Stream.Name}
*.mov=mp4:${Stream.Name}
*.m4v=mp4:${Stream.Name}
*.m4a=mp4:${Stream.Name}
*.f4v=mp4:${Stream.Name}
*.3gp=mp4:${Stream.Name}
*.3g2=mp4:${Stream.Name}
*.mp3=mp3:${Stream.Name}
*=${Stream.Name}

In this example, if a Flash client sent a play command netstream.play("Extremists.m4v"), the stream name would be transformed to mp4:Extremists.m4v

Example play alias file 2:

# limit allowed streams to content in a subfolder. Note that the default rule *=${Stream.name} is removed.
mp4:someClient/*=${Stream.Name}
someClient/*=${Stream.Name}

In this example if a Flash client sent a play command netstream.play("anotherClient/somevideo.flv"), there would be no match and Wowza will return an error with a code of NetStream.Play.Failed and a description of "ModuleStreamNameAlias: No match for stream name [streamname]."  

Example play alias file 3:

# Map one stream to another
OldStream.flv=NewStream.flv
*=${Stream.Name}

In this example if a Flash client sent a play command netstream.play("OldStream.flv"), NewStream.flv would play instead. All other streams would not be transformed.

Stream Aliases

The stream aliases are executed by the Media Caster subsystem which is used to provide the following streaming functions; live stream repeater, SHOUTcast/IceCast re-streaming and RTSP/RTP re-streaming. These type of alias are generally used to turn complex url based stream names into simple names. For example if you are re-streaming a SHOUTcast stream that is hosted at the url http://192.168.1.7/myradiostation then you can create a stream alias such as myradiostation. You can then use this alias name to refer to the SHOUTcast stream.

A stream alias will never not return an error or status messages when no match is found, where as play alias will.

Here are a few sample common stream aliases:

A stream alias file has the following format:

# comment
[pattern]=[alias]

Examples stream alias file 1:

# Fork streams off to multiple origins
origin1/*=rtmp://origin1.com/${Application.Name}/${AppInstance.Name}/${Stream.Name.Part2}
origin2/*=rtmp://origin2.com/${Application.Name}/${AppInstance.Name}/${Stream.Name.Part2}
origin3/*=rtmp://origin3.com/${Application.Name}/${AppInstance.Name}/${Stream.Name.Part2}

Note the use of special variables in this example. See table below.

Example stream alias file 2:

# Expands stream names to SHOUTcast urls
# Omit default rule to block users from entering any url
station1=http://myradiostation.com:8006
station2=http://myradiostation.com:8007
station3=http://myradiostation.com:8008

In this example, if you used the MediaCasterStreamManager to start a stream named "station1", the shoutcast url "http://myradiostation.com:8006" is started with the alias "station1".

Using Special Variables

There are special variables that can be used in the [alias] name. They are: