Schedule streaming with a Wowza Streaming Engine Java module

The StreamPublisher module for Wowza Streaming Engine™ media server software lets you use a server listener and application module to create a schedule of streams and playlists. Using television as an analogy, a stream is a channel and a playlist is a program with one or more video segments. A schedule can have as many streams (channels) as you want, with as many playlists (programs) as you want, and each playlist can be scheduled to play on a stream at a certain time. If a playlist is scheduled to start on a stream while another playlist is running, the existing playlist is replaced with the new one. If you set a schedule to begin in the past, the playlist plays immediately.

Prerequisites


Wowza Streaming Engine 4.0.0 or later is required.

Installation


  1. Download wse-plugin-streampublisher.zip.
  2. Extract the contents from the downloaded (zipped) package, and then copy the lib/wse-plugin-streampublisher.jar file from the package to the lib folder in your Wowza Streaming Engine installation ([install-dir]/lib).
  3. Restart Wowza Streaming Engine.
Note: The StreamPublisher module download includes the ModuleLoopUntilLive application module, which you can use to detect when a live stream is available and switch from the filler video to the live stream. For more information, see Loop a pre-roll until a live stream starts with a Wowza Streaming Engine Java module.

Configuration

You can create a schedule with server listener and application module methods, either together or separately, depending on your needs.

You can use the ServerListenerStreamPublisher server listener to load a set of scheduled streams on a single application when the media server starts. This procedure keeps the streams running until the server is shut down. If you use this process, the schedule can't be reloaded by using just the server listener.

You can use the ModuleStreamPublisher application module on any application to load a set of scheduled streams on that application when the application starts and unload the streams when the application is shut down. The schedule can be reloaded by modifying the SMIL file for the application and then reloading it. The module can provide the reload functionality to the schedule that's configured in the server listener. It can also be used on its own, in separate applications, to provide separate schedules for each application. Each application that runs a schedule must have a live stream type.

Note: Applications are normally loaded after a stream is requested. If the schedule must be started when the server starts and the module is used on its own, there is a separate server listener that can be used to load multiple applications at server startup. See Load and lock an appinstance with a Wowza Streaming Engine server listener for details.

You can use the HttpProviderStreamPublisherControl HTTP provider to load and unload the schedules.

Server listener configuration

To enable the server listener, add the following server listener definition to your media server configuration. See Configure server listeners for details.

Fully Qualified Class Name
com.wowza.wms.plugin.streampublisher.ServerListenerStreamPublisher

Module configuration

To configure the application module, either with the server listener or on its own, add the following module definition to your application. See Configure modules for details.

Name
Description
Fully Qualified Class Name
streamPublisher Schedules streams and playlists. com.wowza.wms.plugin.streampublisher.ModuleStreamPublisher

HTTP provider configuration

To configure the HttpProviderStreamPublisherControl HTTP provider, use a text editor to open [install-dir]/conf/VHost.xml and add the following HTTPProvider definition to the the Default Admin host port (port 8086) in the VHost/HostPortList/HostPort/HTTPProviders container.

<HTTPProvider>
	<BaseClass>com.wowza.wms.plugin.streampublisher.HttpProviderStreamPublisherControl</BaseClass>
	<RequestFilters>schedules*</RequestFilters>
	<AuthenticationMethod>admin-digest</AuthenticationMethod>
</HTTPProvider>

Properties


After enabling the scheduler, you can adjust the default setting by adding the following properties to the server or application. If a property is set at both levels, the application-level setting overrides the server-level setting. See Configure properties for details.

Server properties

The following table lists the properties that can only be set for the server listener at a server level. They control which application the server listener will load the schedule on.

Path
Name
Type
Value
Notes
/Root/Server streamPublisherVHost String _defaultVHost_ Name of the Virtual Host (VHost) that the schedule will be loaded on. Only required for a custom VHost Name. (default: _defaultVHost_)
/Root/Server streamPublisherApplication String [application-name]/_definst_ Name of the application/application instance that the schedule will be loaded on.

Application properties

The following table lists the properties that can be set at either the server level or application level. If set at both levels, the application-level property is used.

Note: For the Path values below, use /Root/Server to set the properties at the server level and /Root/Application to set the properties at the application level.
Path
Name
Type
Value
Notes
/Root/Server
-or-

/Root/Application
streamPublisherSmilFile String streamschedule.smil Name of the SMIL file that's for this application's schedule. The SMIL file must be in the application's Content Storage directory. (default: streamschedule.smil)
/Root/Server
-or-
/Root/Application
streamPublisherPassMetaData Boolean true If set to true, passes source video metadata to the stream. (default: true)
/Root/Server
-or-
/Root/Application
streamPublisherSwitchLog Boolean true If set to true, logs when each schedule switch occurs. If a schedule is set but all items are missing, excessive logging can occur. Set this to false to prevent excessive logging. (default: true)
/Root/Server
-or-
/Root/Application
streamPublisherTimeInMilliSeconds Boolean true If set then the positive start and duration times are in milliseconds instead of seconds. (default: false)
/Root/Server
-or-
/Root/Application
streamPublisherStartLiveOnPreviousKeyFrame Boolean true If set, when switching to a live source, use the most recent key frame as the start instead of waiting for the next one. (default: false)
/Root/Server
-or-
/Root/Application
streamPublisherStartOnPreviousBufferTime Integer 4100 How far to look back in the packet list for the previous key frame. (default: 4100)
/Root/Server
-or-
/Root/Application
streamPublisherTimeOffsetBetweenItems Integer 33 Specifies the millisecond gap between items (default: 0) (is currently overridden by an automatic check that use the larger of audio or video gap)
/Root/Server
-or-
/Root/Application
streamPublisherUpdateMetadataOnNewItem Booelan true If set, the onMetadata packet `title` field will be updated with the name of the new item when a switch occurs. (default: true)

Schedules


Notes:

  • Each application that's configured to load a schedule must have its own SMIL file. The name of the SMIL file is set in the streamPublisherSmilFile property. The SMIL file must be located in the application's Stream Storage directory, which is set in the application's configuration.
  • You can't use the SMIL Files feature in Wowza Streaming Engine Manager edit SMIL files for the scheduler. The SMIL file here has extra tags that the manager can't recognize. Use a text editor to create and edit the scheduler SMIL files.

Creating the SMIL file for each schedule

Create at least one stream, and then create at least one playlist that references the stream.

  • For live stream sources, use -2 for the start parameter.
  • For on-demand stream 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.

You can create an elaborate schedule with several streams and many playlists scheduled to play on a stream. For example:

<smil>
    <head>
    </head>
    <body>

        <stream name="Stream1"></stream>
        <stream name="Stream2"></stream>

        <playlist name="pl1" playOnStream="Stream1" repeat="true" scheduled="2016-04-15 16:00:00">
            <video src="mp4:sample.mp4" start="5" length="5"/>
            <video src="mp4:sample.mp4" start="50" length="5"/>
            <video src="mp4:sample.mp4" start="150" length="5"/>
        </playlist>

        <playlist name="pl2" playOnStream="Stream1" repeat="true" scheduled="2016-04-15 16:30:00">
            <video src="mp4:sample.mp4" start="0" length="-1"/>
        </playlist>

        <playlist name="pl3" playOnStream="Stream2" repeat="true" scheduled="2016-04-15 16:00:00">
            <video src="mp4:sample.mp4" start="30" length="5"/>
        </playlist>

    </body>
</smil>

Loading, reloading, and unloading schedules

The following query parameters are supported in requests to the HttpProviderStreamPublisherControl HTTP provider:
  • appName - Use to specify the name of the application for which the schedule should be loaded.
  • appInstName - Use to specify the name of the application instance for which the schedule should be loaded.
  • action - Use to specify the action to take. Valid values are loadSchedule, reloadSchedule, and unloadSchedule.
    Note: If the application is already running a schedule and the HTTP provider receives a request with the loadSchedule or reloadSchedule actions, the schedule is reloaded.

Load a schedule

The following is an example request to load the schedule.

curl http://localhost:8086/schedules?appName=myApplication&action=loadSchedule

Reload a schedule

The following is an example request to reload the schedule.

curl http://localhost:8086/schedules?appName=myApplication&action=reloadSchedule

Unload a schedule

The following is an example request to unload the schedule.

curl http://localhost:8086/schedules?appName=myApplication&action=unloadSchedule

Note: After you unload a schedule, you must use the loadSchedule action if you wish to run a schedule again.

For developers


  • Get the source code on GitHub