• How to schedule streaming with Wowza Streaming Engine (StreamPublisher)

    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.

    Contents


    Prerequisites
    Installation
    Configuration
    Properties
    Schedules
    Playback
    For developers
    More resources

    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 How to loop a pre-roll until a live stream starts (LoopUntilLive).

    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 How to use a server listener to load and lock an appinstance (ServerListenerLoadAndLockAppInstances) for details.

    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

    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 live/_definst_ Name of the application/application instance that the schedule will be loaded on. (default: live/_definst_)

    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)

    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>

    Reloading schedules

    To reload a schedule on an application, the module must be configured for the application. To do this, edit the SMIL file before reloading a schedule. This will update it with the new schedule.

    The following methods can be used to reload a schedule:

    • Create a simple Flash application with a function that makes the following call to the Wowza media server:
      netconnection.call("loadSchedule",new Responder(function(msg:String):void
      {
          trace(msg);
      }
      ));
      Call the method each time the schedule must be loaded.

      To get a pre-built Flash application that has this functionality, download ModuleStreamPublisherClient.zip.

    • Use JConsole to connect to your Wowza media server's JMX interface, and then run the loadSchedule operation directly on the module instance. In the MBeans tab, navigate to the AppInstance Modules/ModuleStreamPublisher/Instances/Operations tab, and then run the loadSchedule operation. An unloadSchedule operation is also available to shut down the streams.

    Playback


    You can play the streams by configuring a player as you would for any other live stream. Use the stream name that's set in the SMIL file.

    When the playlist item changes on a stream, a message is broadcast to all Flash clients connected to the application. You can listen for these messages by adding a "PlaylistItemStart" callback on the NetConnection in your Flash application. For example:
    var clientObj:Object = new Object();
    clientObj.PlaylistItemStart(itemName:String):void
    {
        trace("Item Name: " + itemName);
    });
    
    netconnection.client = clientObj;
    netconnection.connect("rtmp://[wowza-ip-address]:1935/[app-name]");

    For developers


    Source code is available on GitHub.

    Wowza Media Systems™ provides developers with a platform to create streaming applications and solutions. See Wowza Developer Tools to learn more about our APIs and SDK.

    More resources


    How to loop a pre-roll until a live stream starts (LoopUntilLive)
    Wowza media server software and all components, including modules, source code, and other related items offered on this page, are copyrighted (c) 2006-2016 by Wowza Media Systems, LLC, all rights reserved, and are licensed pursuant to the Wowza Media Software End User License Agreement.
    Originally Published: 10-03-2010.
    Updated: For Wowza Streaming Engine on 04-18-2016.

    If you're having problems or want to discuss this article, post in our forum.