Note: We recommend that you install the latest Wowza Media Server Development Build to get the latest fixes and enhancements for Live Stream Record. After you download the patch, see the README.txt file in the compressed (zipped) folder for installation instructions.
Note: You can download an example module that shows how to create a module that uses the APIs (Download LiveStreamRecordExampleModule_3.5.zip). See the README.html file in the zipped folder for instructions.
Note: To get LiveStreamRecord AddOn packages for older versions of Wowza Media Server, see How to get LiveStreamRecord AddOn, API, and examples.
Contents
Prerequisites
Recording live streams using the web-based user interface
Recording live streams using URL queries
Recording live streams programmatically
Overriding Live Stream Record Parameters using Properties
Troubleshooting
How to get LiveStreamRecord AddOn, API, and examples
Related articles
Understanding crontab expressions
Prerequisites
Specifying an authentication method
Live Stream Record functionality in Wowza Media Server is enabled by an HTTP Provider, which is configured on a per-port basis in [install-dir]/conf/VHost.xml. In Wowza Media Server 3.5, the default HTTP Provider configuration in VHost.xml for Live Stream Record is:
Code:
<HTTPProvider> <BaseClass>com.wowza.wms.livestreamrecord.http.HTTPLiveStreamRecord</BaseClass> <RequestFilters>livestreamrecord*</RequestFilters> <AuthenticationMethod>admin-digest</AuthenticationMethod> </HTTPProvider>
Code:
# Admin password file (format [username][space][password]) #username password myuser mypassword
Publishing a live stream
You must configure an application for live streaming and then publish a live stream from an encoder to Wowza Media Server in order for it to be recorded for later video on demand playback.
On Wowza Media Server:
- Create an application folder [install-dir]/applications/live.
- Create a configuration folder [install-dir]/conf/live and copy [install-dir]/conf/Application.xml to this new folder.
- Open the newly copied Application.xml file in a text editor and make the following changes (some of these settings may already be present):
Note: To skip the following steps, right-click here to download a preconfigured version of Application.xml.
- Set the Streams/StreamType property to:
Code:<StreamType>live</StreamType>
- Set the HTTPStreamers property to:
Code:<HTTPStreamers>cupertinostreaming,smoothstreaming,sanjosestreaming</HTTPStreamers>
- Set the Streams/LiveStreamPacketizers property to:
Code:<LiveStreamPacketizers>cupertinostreamingpacketizer,smoothstreamingpacketizer,sanjosestreamingpacketizer</LiveStreamPacketizers>
- Set the RTP/Authentication/PlayMethod property to:
Code:<PlayMethod>none</PlayMethod>
- Set the Streams/StreamType property to:
- Start Wowza Media Server. For more information, see Starting and Stopping the Server (Standalone) or Starting and Stopping the Server (System Service).
On the encoder:
- Enter the Wowza Media Server URL and stream name information, and then click the Publish or Start button on the encoder. The following example shows information that you might enter for an RTMP-based encoder.
Code:Server URL: rtmp://[wowza-ip-address]/live Stream Name: myStream
Note: The steps for publishing a stream from your encoder to Wowza Media Server may vary depending on the encoder that is used. For more information about how to configure your encoder, see Specific Encoding Technologies or your encoder documentation.
Supported file formats
Live Stream Record supports recording live streams to MP4 (QuickTime container) files or FLV (Flash Video container) files.
Live streams must be encoded with the following video and audio codecs to enable recording to MP4 format:
Video
- H.264
Audio
- AAC
- MPEG-1 Layer 1/2 (MP3)
- Speex
Recording live streams using the web-based user interface
Wowza Media Server 3.5 includes a web-based user interface (UI) that provides basic options for recording live streams to video on demand files. You can use the UI to control the recording process locally or from a remote computer and specify when the recording starts and stops, the filename and location, the container format, and other details. To split in-process live stream recording archives into multiple files, with the split points based on video duration, clock time, or file size, do the following:
- Make sure that you have fulfilled all prerequisite requirements. For more information, see the Prerequisites section.
- Start Wowza Media Server 3.5. For more information, see Starting and Stopping the Server (Standalone) or Starting and Stopping the Server (System Service).
- On the Wowza Media Server or from a remote computer, open the following URL in a web browser: http://[wowza-ip-address]:8086/livestreamrecord.
- In the Wowza Media Server: Live Stream Record webpage, click start recording.
After you click start recording, the web-based Start Recording dialog box is displayed.
- In the Start Recording dialog box, select options to specify how the live stream is split to on-demand recorded files.
Record the live stream to a single file
In Action, select Start Recording to record the live stream to a single video on demand file (this is the default setting). Then in Recording Options, select one of the following options that specify what to do if the live stream is restarted:
- Version existing file. Start recording the live stream to a new file after it is restarted (this is the default setting). For example, if you were recording a live stream to the file myStream.mp4, the live stream will be recorded to a new file named myStream_2012-10-23-15.08.10.645-PDT_0.mp4 after it is restarted.
- Append to existing file. Resume recording the live stream to the existing file (for example, myStream.mp4) after it is restarted.
- Overwrite existing file. Start recording the live stream to a new file with the same name as the existing file (for example, myStream.mp4) after it is restarted. This option will replace the previously recorded file with a new one.
Record the live stream to a multiple segmented files
To record the live stream to multiple video on demand files, select one of the following combination of options to specify how to split the recorded files:
- To split the live stream into multiple on-demand files with a maximum size, in Action, select Start Recording Segment By Size. Then in the Segment Size box, specify the maximum file size in megabytes (MB). The default size is 10 MB.
- To split the live stream into multiple on-demand files with a maximum duration, in Action, select Start Recording Segment By Duration. Then in the Segment Duration box, specify the maximum duration in <hours>:<minutes>:<seconds>.<milliseconds>. The default value is 15 minutes (00:15:00.000).
- To split the live stream into multiple on-demand files based on a schedule, in Action, select Start Recording Segment By Schedule. Then in the Segment Schedule box, specify the schedule parameters by entering a crontab expression. The default value is to split the recording into a new file at the top of each hour.
- Version existing file. Start recording the live stream to a new file after it is restarted (this is the default setting). For example, if you were recording a live stream to the file myStream.mp4, the live stream will be recorded to a new file named myStream_2012-10-23-15.08.10.645-PDT_0.mp4 after it is restarted.
- (Optional). In the Start Recording dialog box, you can specify output options for the recorded files. In the Custom Output Path and File Name area, click Enable and then configure the following options:
- Stream Format. Select the video on demand format of the recorded file, either MP4 (the default value) or FLV.
- Path. Specify the physical path of a location on the computer where the recorded files are stored. By default, the files are stored in the [install-dir]/content directory. If you want to store files in a different location, make sure that the folder exists on the computer and then specify its physical path.
- File Name. To change the default output filenames of your recorded files, update the default template string. You can add any valid filename characters and change the template keys in the string value. For more information about how to use template strings, see Defining filenames of recorded segments with template strings.
- Stream Format. Select the video on demand format of the recorded file, either MP4 (the default value) or FLV.
- Click Submit.
After you click Submit, Wowza Media Server will start recording the live stream and the Wowza Media Server: Live Stream Record webpage will display the selected options.
Note: The Wowza Media Server: Live Stream Record webpage may incorrectly display the status Waiting for stream after you click Submit. Refresh the webpage to view the current status, which should be Recording in progress.
In the Wowza Media Server: Live Stream Record webpage, you can click stop recording to stop recording the live stream. If you click split recording, Wowza Media Server will continue to record the live stream to new file.
Note: When you click split recording, Wowza Media Server immediately stops writing data for the live stream to the currently recording segmented file and closes it, and then opens a new segmented file to continue the recording. If you specified that the segmented files not exceed a maximum duration, data will be written to the new file until either the duration value specified in Segment Duration is reached or you click split recording again.
Recording live streams using URL queries
You can use the HTTP get method and URL querystring parameters to record live streams. The following URL querystring shows the minimum required URL parameters for recording live streams:
Code:
http://[wowza-address]:8086/livestreamrecord?app=live&streamname=myStream&action=startRecording
- app=[app-name]
- streamname=[stream-name] (must be a live stream)
- action=startRecording | stopRecording | splitRecordingNow | startRecordingSegmentByDuration | startRecordingSegmentBySize | startRecordingSegmentBySchedule
You can add the following optional URL parameters to the URL querystring:
- option=version | append | overwrite (default value is version)
- startonkeyframe=true | false (default value is false)
- recorddata=true | false (default value is true)
- outputPath=[path] (default value is left blank, which means that files are recorded to the [install-dir]/content folder)
- outputFile=[filename].[ext] (default value is left blank, which means that the [filename] is the same as the [stream-name] and [ext] takes on the specified format value)
- format=1 | 2 (1 = FLV, 2 = MP4, default value is 1)
- SegmentSize=[bytes] (default value is 10485760 (10 megabytes))
- SegmentDuration=[seconds] (default is 900 (15 minutes))
- SegmentSchedule=[crontab string] (see Understanding crontab expressions for more information)
If you set up an authentication method (see Specifying an authentication method) that requires a username and password, add the username and password to the URL querystring as follows:
Code:
http://[username]:[password]@[wowza-address]:8086/livestreamrecord?app=live&streamname=myStream&action=startRecording
Code:
http://[wowza-address]:8086/livestreamrecord
Recording live streams programmatically
Wowza Media Server 3.5 includes the following Application Programming Interfaces (APIs) that enable you to have more programmatic control over live stream recordings:
- public void startRecording(IMediaStream stream, String filePath, boolean append, Map<String, Object> extraMetadata, int splitOnTcDiscontinuity). Start recording a live stream and indicate if the recording should be split when timecode discontinuities occur.
The default for the startRecording API is to not split the recording (append).
Valid options for splitting the recording on timecode discontinuties are:
- SPLIT_ON_DISCONTINUITY_DEFAULT
- SPLIT_ON_DISCONTINUITY_ALWAYS
- SPLIT_ON_DISCONTINUITY_NEVER
- SPLIT_ON_DISCONTINUITY_DEFAULT
- public void startRecordingSegmentByDuration(IMediaStream stream, String filePath, Map extraMetadata, long duration). Start recording a live stream and split the recording into segmented files of a specified duration (in milliseconds). For example, pass in 15000 to get 15 second files.
- public void startRecordingSegmentBySize(IMediaStream stream, String filePath, Map extraMetadata, long size). Start recording a live stream and split the recording into multiple segmented files of a specified size (in bytes). For example, pass in 1048576 to get 1 megabyte (MB) files.
- public void startRecordingSegmentBySchedule(IMediaStream stream, String filePath, Map extraMetadata, String schedule). Start recording a live stream and split the recording into segmented files on a schedule specified by a crontab string. The crontab string specifies the split interval in minutes, hours, months, years, days of the month, or days of the week. For more information, see Understanding crontab expressions.
- public void splitRecordingNow(). Split an active recording immediately. This action stops writing data to the currently recording segmented file and closes it, and then opens a new segmented file to continue the recording. If the startRecordingSegmentByDuration API is being used to split the live stream into segmented files, data will be written to the new file until either the duration value specified by startRecordingSegmentByDuration is reached or splitRecordingNow() is called again.
- public void setFileVersionDelegate(ILiveStreamRecordFileVersio nDelegate delegate). Specify a custom File Version Naming function.
- public void getCurrentDuration(). Get the current segment file duration, in seconds.
- public void getCurrentSize(). Get the current segment file size, in bytes.
- public void stopRecording(). Stop recording the specified stream.
For more information about the Live Stream Record APIs, see the installed Javadocs ([install-dir]/documentation/serverapi) or download the Wowza Media Server Server-Side API documentation in PDF file format.
Specifying the file version naming convention
You can implement the ILiveStreamRecordFileVersionDelegate interface to override the default file version naming convention used for the recorded segmented files of a live stream.
- public abstract String getFilename(ILiveStreamRecord recorder). Returns a String that will be used to name the next recorded segment. The String that is returned should include the fully qualified path along with the filename (for example: c:\temp\saved\mystream_123.mp4).
Code:
import java.text.DateFormat;
import java.text.SimpleDateFormat;
public class MyDelegate implements ILiveStreamRecordFileVersionDelegate
{
public String getFilename(ILiveStreamRecord recorder)
{
String name;
DateFormat dateFormat = new SimpleDateFormat("yyyy_MM_dd_HHmmssSSS");
Date date = new Date();
try
{
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+"_"+dateFormat.format(date)+oldExt;
file = new File(name);
if (file.exists())
{
file.delete();
}
}
catch (Exception e)
{
WMSLoggerFactory.getLogger(null).error("MyDelegate.getFilename: "+e.toString());
// return a temp filename
name = "temp"+dateFormat.format(date)+".tmp";
}
return name;
}
}
Defining filenames of recorded segments with template strings
The default delegate allows you to specify a template string that defines the filenames of the recorded segments.
- public void setFileTemplate(String template). Enables a custom filename template string to be specified.
- public String getFileTemplate().Returns the current filename template string.
The template string may contain any valid filename characters as well as any valid template key, in any order.
These strings are for use with:
- Start Recording Segment By Size
- Start Recording Segment By Duration
- Start Recording Segment By Schedule
Valid template keys are:
- ${SourceStreamName}. The name of the live stream.
- ${SegmentNumber}. An incrementing value that represents the current number of recorded segments that have been created for this live stream, starting at 0.
- ${RecordingStartTime}. The time at which the recording was started.
- ${SegmentTime}. The time at which the recorded segment was created.
Note: ${RecordingStartTime} and ${SegmentTime} use the date time format yyyy-MM-dd-HH.mm.ss.SSS-zzz (<year>-<month>-<day>-<hour>.<minute>.<second>.<millisecond>-<time zone>).
The default file template string is ${SourceStreamName}_${RecordingStartTime}_${Segmen tNumber}, which generates recorded MP4 filenames such as the following:
myStream_2012-10-16-08.51.31.104-MDT_0.mp4
myStream_2012-10-16-08.51.31.104-MDT_1.mp4
myStream_2012-10-16-08.51.31.104-MDT_2.mp4
myStream_2012-10-16-08.51.31.104-MDT_1.mp4
myStream_2012-10-16-08.51.31.104-MDT_2.mp4
Example template strings:
${SourceStreamName}_${SegmentNumber}:
mystream_0
mystream_1
mystream_2
mystream_1
mystream_2
${SourceStreamName}_t${RecordingStartTime}_ct${Seg mentTime}:
mystream_t2012-08-05-02.34.53.102-MDT_ct2012-08-05-02.00.00.000-MDT
mystream_t2012-08-05-02.34.53.102-MDT_ct2012-08-05-02.15.00.000-MDT
mystream_t2012-08-05-02.34.53.102-MDT_ct2012-08-05-02.30.00.000-MDT
mystream_t2012-08-05-02.34.53.102-MDT_ct2012-08-05-02.15.00.000-MDT
mystream_t2012-08-05-02.34.53.102-MDT_ct2012-08-05-02.30.00.000-MDT
Configuring notifications
You can implement the ILiveStreamRecordNotify interface to receive notifications about when a new file is opened for writing and when the current recorded segment has been closed. (See the code snippet later in this section for an example listener.)
- public abstract void onSegmentStart(ILiveStreamRecord recorder). Receive a notification that a new file has been opened for writing.
- public abstract void onSegmentEnd(ILiveStreamRecord recorder). Receive a notification that the current recorded file has been closed (data is no longer being written to the file).
Code:
public class MyListener implements ILiveStreamRecordNotify
{
public void onSegmentStart(ILiveStreamRecord recorder)
{
// Nothing to do here
}
public void onSegmentEnd(ILiveStreamRecord recorder)
{
// move completed file to storage location
File file = new File (recorder.getCurrentFile());
if (!file.renameTo(new File("c:/storage"+file.getName())))
{
WMSLoggerFactory.getLogger(null).error("MyListener.onSegmentEnd: file move failed for "+file.getAbsolutePath());
}
}
}
Splitting live recordings at timecode discontinuities
You can change the default behavior for splitting live recordings when a timecode discontinuity is encountered in the source stream by adding the following property to the <Properties> container at the end of [install-dir]/conf/[application]/Application.xml (be sure to get the correct <Properties> container—there are several in Application.xml):
Code:
<Property>
<Name>liveStreamRecorderSplitOnTcDiscontinuity</Name>
<Value>true</Value>
<Type>boolean</Type>
</Property>
Note: This property only applies to the startRecording API. The onSegment* APIs will always split live recordings at timecode discontinuities.
Overriding Live Stream Record Parameters using Properties
| Note: For use with for Wowza Media Server 3.5.2 patch 6 and later. |
The following is a list of properties which can be used to override the values set using the Live Stream Record API's and configured on the Live Stream Record Webpage.
Caution:When an override property is set in application.xml, it's value is always used and cannot be changed via API or the Webpage.
These properties can be used by adding them to the <Properties> container at the end of [install-dir]/conf/[application]/Application.xml (be sure to get the correct <Properties> container—there are several in Application.xml):
Valid values for the liveStreamRecordOption property are; append, overwrite, version
Code:
<Property>
<Name>liveStreamRecordOption</Name>
<Value>overwrite</Value>
<Type>String</Type>
</Property>
<Property>
<Name>liveStreamRecordStartOnKeyFrame</Name>
<Value>false</Value>
<Type>boolean</Type>
</Property>
<Property>
<Name>liveStreamRecordRecordData</Name>
<Value>false</Value>
<Type>boolean</Type>
</Property>
Code:
<Property>
<Name>liveStreamRecordFilePath</Name>
<Value>c:/content</Value>
<Type>String</Type>
</Property>
Code:
<Property>
<Name>liveStreamRecordSegmentSize</Name>
<Value>102400</Value>
<Type>long</Type>
</Property>
Code:
<Property>
<Name>liveStreamRecordSegmentDuration</Name>
<Value>10000</Value>
<Type>long</Type>
</Property>
Code:
<Property>
<Name>liveStreamRecordSegmentSchedule</Name>
<Value>2 * * * * *</Value>
<Type>String</Type>
</Property>
Troubleshooting
- Wowza Media Server must be actively ingesting a live stream before you can start recording it.
- You cannot use separate instances of the web-based user interface to record the same live stream. If a recording for a live stream is started and another recording request for the same stream is submitted, the first recording is terminated and a new one is started to honor the second recording request.
- A recording must be completed before it can be played back.
- The Live Stream Recording APIs are designed for server-side recording. Client-side recording, where multiple recording requests can be made for the same stream, is not supported.
- When using the onSegment* APIs:
- The Version flag must be set to true for the recorded files to be created correctly.
- Setting the Overwrite flag to true can cause previously recorded files to be overwritten.
- The Append flag is ignored.
- The Version flag must be set to true for the recorded files to be created correctly.
Enabling additional debug logging
You can enable additional debug logging for Live Stream Record by adding the following property to the <Properties> container at the end of [install-dir]/conf/[application]/Application.xml (be sure to get the correct <Properties> container—there are several in Application.xml):
Code:
<Property>
<Name>liveStreamRecorderDebugLog</Name>
<Value>true</Value>
<Type>boolean</Type>
</Property>
Code:
filePath has been overridden in application.xml, value=C:/content/myStream.mp4 versionFile has been overridden in application.xml by liveStreamRecordOption=overwrite appendFile has been overridden in application.xml by liveStreamRecordOption=overwrite startOnKeyFrame has been overridden in application.xml, value=false recordData has been overridden in application.xml, value=false segmentSize has been overridden in application.xml, value=102400 segmentDuration has been overridden in application.xml, value=10000 segmentSchedule string has been overridden in application.xml, value=2 * * * * *
How to get LiveStreamRecord AddOn, API, and examples
This section describes the downloadable LiveStreamRecord AddOn packages that work with Wowza Media Server 3.1.2 and earlier. These AddOn packages do not provide the full capabilities for recording live streams to on-demand files that are available in Wowza Media Server 3.5. To learn more about how to use the LiveStreamRecord AddOn package with your version of Wowza Media Server, see the ReadMe.html file in the compressed (zipped) folder.
Version for Wowza Media Server 3.0.3.08 to 3.1.2.*
LiveStreamRecord_3.0.zip
Version for Wowza Media Server 2.0.0.04 to 2.2.4.*
LiveStreamRecord_2.0.zip
Version for Wowza Media Server Pro 1.7.x
LiveStreamRecord.zip
Understanding crontab expressions
In Wowza Media Server 3.5, you can use crontab expressions to start recording a live stream and split the recording into multiple segmented files based on a schedule. The crontab expression specifies the split interval in minutes, hours, months, years, days of the month, or days of the week. The available crontab fields are (in order):
<Minute> <Hour> <Day_of_the_Month> <Month_of_the_Year> <Day_of_the_Week> <Year>
where:
- <Minute> - Specifies the minute value (between 0 and 59) at which the split occurs.
- <Hour> - Specifies the hour (between 0 and 23 based on a 24-hour clock) at which the split occurs.
- <Day_of_the_Month> - Specifies the day (between 0 and 31) at which the split occurs. To specify that live recordings always be split on the last day of the month, specify 31.
- <Month_of_the_Year> - Specifies the month at which the split occurs. You can specify the month by using the abbreviated name of the month (for example, Jan) or a numerical equivalent (for example, 1).
- <Day_of_the_Week> - Specifies the day in a week at which the split occurs. You can specify the day by using the abbreviated name of the day (for example, Mon) or a numerical equivalent (for example, 1).
- <Year> - Specifies the year at which the split occurs (for example, 2013).
The crontab fields are meant to be used in combination in a cron expression (a string comprising the field values separated by white space) to give you a powerful mechanism for splitting your live recordings. You can also use special characters as field values to give you even more flexibility. Wowza Media Server 3.5 supports the nnCcron cron format (http://www.nncron.ru/help/EN/working/cron-format.htm).
Note: The nnCron nonstandard question mark character (?), which specifies that the server startup time is substituted into the cron expression, is currently not supported.
Example cron expressions:
The following are some simple examples that introduce cron expressions. For more advanced examples, see the nnCcron cron format page (http://www.nncron.ru/help/EN/working/cron-format.htm).
To split a live recording every 30 minutes (at the top of each hour and every half-hour):
0,30 * * * * *
0,30 (simplified version)
0,30 (simplified version)
To split a live recording every 15 minutes on even hours:
*/15 */2 * * * *
*/15 */2 (simplified version)
*/15 */2 (simplified version)
To split a live recording at 8AM and 6PM:
0 8,18 * * * *
0 8,18 (simplified version)
0 8,18 (simplified version)
Updated: For Wowza Media Server 3.5 on 11-08-2012
- Click here, if you are having problems or would like to discuss this article.
- Leave a comment below, if there is some aspect of this article you would like to see changed or improved.
Article List
Categories
Wowza Media