• How to start and stop live stream recordings programmatically (LiveStreamRecordAutoRecord example)

    Wowza™ provides two example modules that demonstrate how to use the LiveStreamRecordManager APIs to automatically start recording any live stream published to an application and automatically stop recording the stream when it's unpublished.

    Note: For use with Wowza Streaming Engine™ software.
    You can download this zip file that has the source code for the examples discussed in this article as well as the JAR file that has the compiled modules. The example modules show how to use the new LiveStreamRecordManager APIs to implement "Auto-Record" functionality. Download StreamRecorderAutoRecord_4.0.zip

    Contents


    About the example modules
    Module basics
    ModuleAutoRecordBasicExample
    ModuleAutoRecordAdvancedExample
    Installing a Live Stream Record AutoRecord example module
    LiveStreamRecordManager documentation
    More resources

    About the example modules


    The StreamRecorderAutoRecordBasicExample module does the minimum to set up and record all live streams coming into an application. It uses the the default StreamRecorder configuration parameters.

    The StreamRecorderAutoRecordAdvancedExample module demonstrates how to set StreamRecorder configuration parameters such as the segmentationType, segmentationDuration, fileFormat, and so on. This module also has a custom file version delegate that implements the IStreamRecorderFileVersionDelegate interface and sets the StreamRecorder parameters to use this class instead of the built-in one.

    This module also implements a StreamRecorder notification listener, and sets the StreamRecorder parameters to use this listener. The listener logs the notification events that are received during the StreamRecorder life cycle.

    The StreamRecorder parameters are then used for every Stream Recorder created by the module.

    Module basics


    The example modules extend the ModuleBase class and implement the IModuleOnApp interface.

    • The ModuleBase class provides basic utility functionality for handling function parameters and return data as well as a simplified API for logging. The example modules only use the logging API from ModuleBase.

    • The IModuleOnApp interface provides notification methods for when an application is started and stopped.

    The main code for these examples is implemented in the application start notification function onAppStart.

    ModuleAutoRecordBasicExample



    File: com.wowza.wms.plugin.livestreamrecord.module.ModuleAutoRecordBasicExample.java

    This example demonstrates the basic items that are required to implement the application auto-recording functionality for all incoming streams. Within the onAPPStart function:

    1. Instantiate a StreamRecorderParameters object.
      StreamRecorderParameters recordParams = new StreamRecorderParameters(this.appInstance);
    2. Set the StreamRecorderParameters to the desired values.
      recordParams.segmentationType = IStreamRecorderConstants.SEGMENT_NONE;
      recordParams.versioningOption = IStreamRecorderConstants.OVERWRITE_FILE;
      Notes:
      • The StreamRecorderParameters class contains all of the available parameters used by Stream Recorders. The values in this class are initially populated with the Wowza Streaming Engine default values.

      • Valid values and a description for each parameter can be found in the LiveStreamRecordManager documentation. See the "com.wowza.wms.livestreamrecord.manager.IStreamRecordConstants" section.
    3. Call the LiveStreamRecordManager startRecording API to start recorders for all streams published to this instance using the configured StreamRecorderParameters.
      this.vhost.getLiveStreamRecordManager().startRecording(appInstance, recordParams);

    After this module is installed for an application, any stream published to the application is recorded using the StreamRecorderParameters configured in item 2.

    ModuleAutoRecordAdvancedExample



    File: com.wowza.wms.plugin.livestreamrecord.module.ModuleAutoRecordAdvancedExample.java

    This example builds on the basic example and demonstrates the following:

    • A custom class that implements the IStreamRecorderFileVersionDelegate interface. This creates custom files names when segmenting recordings.

    • A custom class that implements the IStreamRecorderActionNotify interface to receive Stream Recorder action notifications.

    • Configuration of the above custom classes in the StreamRecorderParameters.

    MyFileVersionDelegate class

    Stream Recorders rely on a file version delegate to generate a file name for use by the recorder. Wowza Streaming Engine has two built-in file version delegates, StreamRecorderFileVersionDelegate and StreamRecorderSimpleFileVersionDelegate. See the LiveStreamRecordManager documentation for full details on what these classes can do.

    Creating a custom file version delegate

    You can create a custom file version delegate class that implements the IStreamRecorderFileVersionDelegate interface for use by Stream Recorders. This class has a single function (getFilename) that must be implemented. You can get information such as stream name, recorder starttime, and so on, from the requesting Stream Recorder via the IStreamRecorder interface.

    The MyFileVersionDelegate example class simply appends the current time (in milliseconds) to the end of the recorder's default file name (which is usually the stream name) and returns that name back to the caller:
    File file = new File(recorder.getBaseFilePath());
    String oldBasePath = file.getParent();
    String oldName = file.getName();
    String oldExt = "";
    int oldExtIndex = oldName.lastIndexOf(".");
    if (oldExtIndex >= 0)
    {
    	oldExt = oldName.substring(oldExtIndex);
    	oldName = oldName.substring(0, oldExtIndex);
    }
    
    name = oldBasePath+"/"+oldName+"_"+DateTime.now().millisOfDay().getAsText()+oldExt;

    Configuring Stream Recorders for a custom file version delegate

    To configure Stream Recorders to use the MyFileVersionDelegate class, in the onAppStart function, set recordParams.fileVersionDelegate to an instance of the class:
    recordParams.fileVersionDelegate = new MyFileVersionDelegate();

    MyStreamRecorderListener class

    Stream Recorders will notify registered listeners about the actions that they are taking. These actions are described in the LiveStreamRecordManager documentation. See the "IStreamRecorderActionNotify" section under "LiveStreamRecordManager" for full details about what the actions are and when they are called in the Stream Recorder life cycle.

    Note: A similar notification interface exists for LiveStreamRecordManager that provides notifications at different points in a Stream Recorder life cycle. See the "ILiveStreamRecordManagerActionNotify" under "LiveStreamRecordManager" in the LiveStreamRecordManager documentation for more information about when these notifications are called.

    Creating a StreamRecorderActionNotify listener

    The Listener class is a simple class that implements the IStreamRecorderFileVersionDelegate interface. All interface functions must be implemented; however, notifications that are not of interesting can do nothing.

    The MyStreamRecorderListener example class simply writes a message to the log file for each notification is received:
    	class MyStreamRecorderListener implements IStreamRecorderActionNotify
    	{
    		@Override
    		public void onCreateRecorder(IStreamRecorder recorder)
    		{
    			/*
    			To set stream specific StreamRecorderParameter values, set them here
    			if (recorder.getStreamName().equals("mySpeciaStream"))
    			{
    				StreamRecorderParameters params = recorder.getRecorderParams();
    				params.fileVersionDelegate = new SpecialStreamFileVersionDelegate();
    				params.notifyListener = new SpecialStreamOtherListener();
    			}
    			*/
    			getLogger().info("MyStreamRecorderListener.onCreateRecorder[" + appInstance.getContextStr() + "]: new Recording created:" + recorder.getStreamName());
    		}
    ...
    
    		@Override
    		public void onSegmentEnd(IStreamRecorder recorder)
    		{
    			getLogger().info("MyStreamRecorderListener.onSegmentEnd[" + appInstance.getContextStr() + "]: segment closed:" + recorder.getStreamName());
    		}
    	}

    Configuring Stream Recorders to use the listener

    To configure Stream Recorders to use the MyStreamRecorderListener class, in the onAppStart function, set recordParams.notifyListener to an instance of the class:
    recordParams.notifyListener = new MyStreamRecorderListener();
    After this module is installed for an application, any stream published to the application is recorded using the configured StreamRecorderParameters. This means that MyFileVersionDelegate and MyStreamRecorderListener are called for every Stream Recorder.

    You can customize the StreamRecorderParameters within the onCreateRecorder notify function on a stream-by-stream basis.

    Note: LiveStreamRecordManager doesn't support multiple Stream Recorders for a single stream; therefore, stream names must be unique within an application. If a duplicate stream name is used, the existing recording associated with the current stream name will be stopped and a new recording will be started for the duplicate stream name.

    Installing a Live Stream Record AutoRecord example module


    1. Copy the lib/wms-plugin-wms-plugin-livestreamrecordautorecord_4.0.jar file from the downloadable package to the lib folder in the Wowza Streaming Engine installation ([install-dir]/lib).

    2. In Wowza Streaming Engine Manager, click the desired live application in the contents panel.

    3. On the live application page, click the Modules tab.

      Note: Access to the Modules tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
    4. On the Modules tab, do the following:

      1. Click the Edit button.

      2. Click the Add Module button and then add one of the following entries:
        Name: ModuleAutoRecordBasicExample
        Description: ModuleAutoRecordBasicExample
        Fully Qualified Class Name: com.wowza.wms.plugin.livestreamrecord.module.ModuleAutoRecordBasicExample
        -or-
        Name: ModuleAutoRecordAdvancedExample
        Description: ModuleAutoRecordAdvancedExample
        Fully Qualified Class Name: com.wowza.wms.plugin.livestreamrecord.module.ModuleAutoRecordAdvancedExample
    5. Click the application Restart button.

    6. Live streams that are sent to the live application will be recorded to [install-dir]/content automatically.


    LiveStreamRecordManager documentation


    The LiveStreamRecordManager APIs are fully documented in the "com.wowza.wms.livestreamrecord.manager" section in the Javadocs installed with the Wowza Streaming Engine software ([install-dir]/documentation/serverapi) and in the Wowza Streaming Engine Server-Side API (PDF file format).

    Originally Published: For Wowza Streaming Engine on 02-11-2014.

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