How to make a schedule-based stream in Wowza Streaming Engine

I worked last 5 months of this year at the media streaming field. I still was a Linux servers maintainer who tries to explore this awesome OS world as much as possible. But the main goal was special and quite different. That goal – servers customization for live stream videos transcoding and broadcast.

Day by day I documented my goals and solutions in articles format. But now this time is over. To summarize this term of my life, I’m starting to publish posts about media streaming. Up to the end of this summer there will be only streaming server guides.

Mostly I worked with WowzaStreamingEngine – unified streaming server software. You might hear about WowzaMediaServer. It’s the same product, Wowza was called that way until 4.0 version.

What’s the point of WowzaStreamingEngine?

---

Well, that’s a good question. I’d like to explain it step by step through my articles. But here will be just a short explanation for your understanding what the hell is going on here.

The main destination of Wowza – streaming of multitudinous media formats. It could be a live video, VOD (video on demand), audio, so on and so forth. They have a huge documentation, you’re welcome to fill your interest. Wowza solutions of streaming issues are pretty flexible. It used as for cross-platform Web-streaming as sure as for IPTV with set-top boxes (STB).

Wowza is written on Java entirely. It means that Wowza is cross-platform software for Win, Mac, and, of course, Linux. It’s also informative to look at this product from the view of Java apps structure. The most disgusting fact – WowzaStreamingEngine is a proprietary software. It’s free only for test and trial versions (it’s not the same things for Wowza). But there is already a reason to devote a particular post for this problem. Or it’s not a problem at all, suit yourself.

What is the schedule-based channel?

---

Scheduled streaming channels – channels combined from some sources. Each one of these has a special time interval to be shown at the channel.

For example: we can set up a channel where:

• from midnight to 8:00 will be single video playback;
• from 8:00 to 17:00 – Kids TV streaming;
• from 17:00 to 19:00 – news channel live streaming;
• and from 19:00 to midnight – movies record playback.

And this consequence could be repeated every day. Shortly, sometimes we need to create a special schedule stream to transmit any special data at any special time.

Schedule streams configuration are described in SMIL-files by structure one channel-one file. Encrypting abbreviation, SMIL means a Synchronized Multimedia Integration Language. SMIL is a markup language basically used for multimedia presentations. For each content instance you can describe a multimedia type and special parameters. Under parameters i mean duration of play, bitrate, resolution and so on. SMIL syntax is pretty easy to understand, because it looks like HTML and XML.

Generally schedule streaming for Wowza is a job for StreamPublisher Module from modules collection. But this module doesn’t provide all opportunities to build a dynamic schedule channel. Below is the complex guide how to fix this lack.

Switch on JMX console

---

1. Enable JMX at the configuration file [install_dir]/conf/Server.xml by modifying this piece of code:

<JMXRemoteConfiguration>
	<Enable>true</Enable>
	<IpAddress>localhost</IpAddress> <!-- set to localhost or internal ip address if behind NAT -->
	<RMIServerHostName>localhost</RMIServerHostName> <!-- set to external ip address or domain name if behind NAT -->
	<RMIConnectionPort>8084</RMIConnectionPort>
	<RMIRegistryPort>8085</RMIRegistryPort>
	<Authenticate>true</Authenticate>
	<PasswordFile>${com.wowza.wms.ConfigHome}/conf/jmxremote.password</PasswordFile>
	<AccessFile>${com.wowza.wms.ConfigHome}/conf/jmxremote.access</AccessFile>
	<SSLSecure>false</SSLSecure>
</JMXRemoteConfiguration>

Note. [install_dir] means a directory where your Wowza server is installed. By default it’s a /usr/local/WowzaStreamingEngine.
You can also set suitable beans for JMX monitoring at ObjectList variable:

<AdminInterface>
<!-- Objects: Server, VHost, VHostItem, Application, ApplicationInstance, MediaCaster, Module, Client, MediaStream, SharedObject, Acceptor, IdleWorker -->
<ObjectList>Server,VHost,VHostItem,Application,ApplicationInstance,MediaCaster,Module,IdleWorker,Client,MediaStream,SharedObject,Acceptor</ObjectList>
</AdminInterface>

2.  Set desired roles and login credentials at [install_dir]/conf/jmxremote.access and [install_dir]/conf/jmxremote.password files.

Default roles and credentials:

[install_dir]/conf/jmxremote.access file

admin readwrite
monitorRole readonly
controlRole readwrite

[install_dir]/conf/jmxremote.password file

admin admin
monitorRole admin
controlRole admin

3. Get a JMX command-line client and place it in your Wowza server. Recommend directory is a [install_dir]/lib (if you have externally installed Java) or [install_dir]/java/bin/ (otherwise).

4. Restart WowzaStreamingEngine and test your JMX console.

Example with external Java:

java -jar /usr/local/WowzaStreamingEngine/lib/cmdline-jmxclient-0.10.3.jar admin:admin localhost:8085

Example with local Wowza Java:

/usr/local/WowzaStreamingEngine/java/bin/java -jar /usr/local/WowzaStreamingEngine/java/bin/cmdline-jmxclient-0.10.3.jar admin:admin localhost:8085

admin:admin – login and password respectively. The result should be positive with a plenty of beans like these::

WowzaStreamingEngine:name=IOPerformanceHTTPMPEGDash
WowzaStreamingEngine:name=StreamItem,streamTypeName=chat,streamTypes=StreamTypes,vHostName=_defaultVHost_,vHosts=VHosts
WowzaStreamingEngine:applicationName=scheduler,applications=Applications,name=ConnectionsHTTPCupertino,vHostName=_defaultVHost_,vHosts=VHosts
WowzaStreamingEngine:name=IOScheduler,vHostName=_defaultVHost_,vHosts=VHosts
WowzaStreamingEngine:name=StreamItem,streamTypeName=rtp-live-record,streamTypes=StreamTypes,vHostName=_defaultVHost_,vHosts=VHosts
WowzaStreamingEngine:name=Properties,streamTypeName=rtpout,streamTypes=StreamTypes,vHostName=_defaultVHost_,vHosts=VHosts
WowzaStreamingEngine:name=StreamItem,streamTypeName=rtp-buffer,streamTypes=StreamTypes,vHostName=_defaultVHost_,vHosts=VHosts
WowzaStreamingEngine:name=Properties,streamTypeName=rtp-buffer,streamTypes=StreamTypes,vHostName=_defaultVHost_,vHosts=VHosts

Deploy StreamPublisher Module

---

1. Get a Wowza Module Collection library. If you have this lib in your Wowza instance already – skip this step.

2. Enable StreamPublisher Module at the configuration file [install_dir]/conf/Server.xml adding new ServerListener at ServerListeners directive.

<ServerListener> 
	<BaseClass>com.wowza.wms.plugin.collection.serverlistener.ServerListenerStreamPublisher</BaseClass>
</ServerListener>

3. Enable StreamPublisher Module at the configuration file [install_dir]/conf/[app_name]/Application.xml adding new Module at Modules directive.

<Module>
	<Name>streamPublisher</Name>
	<Description>Schedules streams and playlists.</Description>
	<Class>com.wowza.wms.plugin.collection.module.ModuleStreamPublisher</Class>
</Module>

4. Add StreamPublisher Module properties at the bottom of configuration file [install_dir]/conf/Server.xml (Properties directive).

<Properties>
		<Name>streamPublisherVHost</Name>
		<Value> _defaultVHost_</Value>
		<Type>String</Type>
	</Property>
	<Property>
		<Name>streamPublisherApplication</Name>
		<Value>live/_definst_</Value>
		<Type>String</Type>
	</Property>
	<Property>
		<Name>streamPublisherSmilFile</Name>
		<Value>channel5.smil</Value>
		<Type>String</Type>
	</Property>
	<Property>
		<Name>streamPublisherPassMetaData</Name>
		<Value>true</Value>
		<Type>Boolean</Type>
	</Property>
	<Property>
		<Name>streamPublisherSwitchLog</Name>
		<Value>false</Value>
		<Type>Boolean</Type>
</Properties>

Properties description:

• streamPublisherVHost – Wowza vHost name (_defaultVHost_ by default).
• streamPublisherApplication – application where module is enabled (in this instance it’s live).
• streamPublisherSmilFile – name of scheduled SMIL file. Layout of file is a application content directory. In this configuration instance it’s channel5.smil.
• streamPublisherPassMetaData – option for stream components to pass metadata.
• streamPublisherSwitchLog – enable/disable module extensive logging. Set false if everything is alright. Cause any debug for any Wowza module makes your log files tremendous.

Create schedule SMIL file

---

1. Find out path to content directory in scheduled Wowza Application. Look for a StorageDir variable at [install_dir]/conf/[app_name]/Application.xml file.

<StorageDir>${com.wowza.wms.context.VHostConfigHome}/content</StorageDir>

2. Create a new SMIL file in application content direcotry you found in config. The name of SMIL file should be the same as you typed in module configuration. Here will be [install_dir]/content/channel5.smil file. Here is example of scheduling mix: live stream (rbc) and VOD video from content directory (error.mp4).

<smil>
    <head>
    </head>
    <body>
        <stream name="channel5"></stream>   
        <playlist name="pl1" playOnStream="channel5" repeat="true" scheduled="2016-04-14 06:00:00">
            <video src="mp4:rbc" start="-2" length="-1"/>
        </playlist>
        <playlist name="pl2" playOnStream="channel5" repeat="true" scheduled="2016-04-14 17:49:00">
            <video src="mp4:error.mp4" start="0" length="-1"/>
        </playlist>
    </body>
</smil>

Notes:

• For live stream sources, use -2 for the start parameter.
• For VOD sources, use either 0 or a positive number for the start parameter. A positive number will start that number of seconds into the video.
• To play the source until the end, use -1 for the length parameter. Any positive value will play the source for that number of seconds.
• To loop through the schedule, set repeat to true. Setting repeat to false will shut down the stream after the playlist has finished. Later playlists aren’t loaded unless they start before the non-repeating playlist ends.
• Set the scheduled parameter to start the playlist at a specific time. If the begin time is in the past, each playlist is loaded in order and immediately replaces the previous playlist for the stream.

Pay attention! If you want to put a live stream on the schedule – ensure this live stream is transcoded in Wowza application with StreamPublisher module. Links on external live streams doesn’t work at this module! You nead to stream live channels by yourself.

3. Put all necessary stuff for streaming in application content directory. Also start to play in your application all live streams you pointed at SMIL file if it doesn’t play yet.

4. Create a new Startup Stream for Wowza and call it like your SMIL file name (before extension). At this instance it should be channel5 stream. Do it from WowzaStreamingEngine Manager or through [install_dir]/conf/StartupStreams.xml file adding a new StartupStream XML-block.

<StartupStream>
	<Application>live/_definst_</Application>
	<StreamName>channel5</StreamName>
	<MediaCasterType>liverepeater</MediaCasterType>
</StartupStream>

Deploy a Bash script

---

Here is the feature for dynamic schedule streaming. By default module configuation we need to change our SMIL file every day to set current date. StreamPublisher doesn’t make this operation by itself and SMIL file cannot be updated dynamically. Surely it’s trivial to do it manually. Let’s set a simple Bash script for automatic schedule update.

1. Create a file reschedule.sh at any place in Wowza server (here will be /opt directory).

2. Put this code in your file.

#!/bin/bash
today=$(date +%Y-%m-%d)
last_day=$(cat /usr/local/WowzaStreamingEngine/content/channel5.smil | grep -oh "....-..-.." | head -n 1)
sed -i "s/$yesterday/$last_day/g" /usr/local/WowzaStreamingEngine/content/channel5.smil
java -jar /usr/local/WowzaStreamingEngine/lib/cmdline-jmxclient-0.10.3.jar admin:admin localhost:8085 WowzaStreamingEngine:applicationInstanceName=_definst_,applicationInstances=ApplicationInstances,applicationName=live,\
applications=Applications,module=streamPublisher,modules=Modules,name=Instance,vHostName=_defaultVHost_,vHosts=VHosts \
loadSchedule

Notes:

• /usr/local/WowzaStreamingEngine/content/channel5.smil is the full name of schedule SMIL-file. Change it if you have another name.
• /usr/local/WowzaStreamingEngine/lib/cmdline-jmxclient-0.10.3.jar is the full name of JMX command-line client. Change it if you have another path.
• admin:admin is login and password for JMX access. Change it if you have another credentials.
• localhost:8085 is the Wowza server address, cause we make it in local Wowza Server.
• live is the name of Wowza Application which has streamPublisher module enabled. Change it if you have another one.

3. Make it executable.

chmod +x /opt/reschedule.sh

4. Test it. Date should be change up to current one and stdout should look like this:

04/15/2016 17:34:38 +0300 org.archive.jmx.Client loadSchedule: DONE!

5. Create a new cron job for the time you need to reload schedule. Call a crontab from command line.

crontab -e

Set a new job. Here is an example for 6:00 schedule reloading:

0 6 * * * bash /opt/reschedule.sh

Now you’re able to build your own dynamic schedule-based streams. Mix as many sources as possible! 🙂

• Bash
• schedule
• smil
• Streaming
• Wowza
• xml