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

Note: This article is for an older Wowza™ product or technology that either has been updated or is no longer supported. For the current version of this article, see How to start recording streams automatically (LiveStreamRecordAutoRecord).
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


About the example modules
Module basics
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.



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;
    • 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.



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+"_";

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
		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());

		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), and then restart Wowza Streaming Engine.
  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
      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).