• How to record live streams (Wowza Streaming Engine)

    Wowza Streaming Engine™ media server software has a new system that enables you to access and control Stream Recorders (formerly LiveStreamRecorders) by using either Wowza Streaming Engine Manager or Java APIs. Stream Recorders can be started, monitored, and controlled in Wowza Streaming Engine Manager or programmatically by using new LiveStreamRecordManager APIs. Wowza Streaming Engine software supports legacy LiveStreamRecord URLs, which can also be monitored and controlled in Streaming Engine manager or by using the LiveStreamRecordManager APIs.

    This article focuses on how to use the Incoming Streams feature in Streaming Engine manager to record live streams to video on demand (VOD) assets for later playback. For a detailed tutorial that describes how to use the new LiveStreamRecordManager APIs programmatically, see How to start and stop live stream recordings programmatically (LiveStreamRecordAutoRecord example).

    Notes:
    • This article is for use with Wowza Streaming Engine™ software. For information about similar recording functionality supported in Wowza Media Server™ software (version 3.5 and later), see How to record live streams (HTTPLiveStreamRecord). For older versions of Wowza Media Server software (version 3.1.2 and earlier), recording functionality is provided by the LiveStreamRecord AddOn package. See How to get LiveStreamRecord AddOn, API, and examples.

    • We recommend that you install the latest Wowza Streaming Engine Development Build to get the latest fixes and enhancements for the Incoming Streams feature. After you download the update, see the README.txt file in the compressed (zipped) folder for installation instructions.

    • You can download an example module that demonstrates how to use the LiveStreamRecordManager APIs to record a live stream published from a Flash application (Download LiveStreamRecordExampleModule_4.0.zip). See the README.html file in the compressed (zipped) folder for installation instructions.

    Contents


    Prerequisites
    Viewing incoming live streams and recording status
    Recording live streams in Wowza Streaming Engine Manager
    Stream Recorder properties
    Recording live streams with URL queries
    Recording live streams programmatically with the LiveStreamRecordManager APIs
    Troubleshooting
    How to get LiveStreamRecord AddOn, API, and examples
    More resources
    Appendix: About crontab expressions

    Prerequisites


    Starting Wowza Streaming Engine and Wowza Streaming Engine Manager

    The Wowza Streaming Engine software and web-based Streaming Engine manager application must be running. See How to start and stop Wowza Streaming Engine software.

    Specifying an authentication method

    Live Stream Record functionality in Wowza Media Server is enabled by an HTTP Provider that's configured on a per-port basis in the [install-dir]/conf/VHost.xml file. The default HTTP Provider configuration in VHost.xml for Live Stream Record is:
    <HTTPProvider>
    	<BaseClass>com.wowza.wms.livestreamrecord.http.HTTPLiveStreamRecord</BaseClass>
    	<RequestFilters>livestreamrecord*</RequestFilters>
    	<AuthenticationMethod>admin-digest</AuthenticationMethod>
    </HTTPProvider>
    The AuthenticationMethod property specifies the authentication method that's used to control access to this HTTP Provider. The default value (admin-digest) specifies that Digest authentication (a challenge/response system to authenticate users--credentials are never sent in cleartext) is used to control access to the HTTP Provider and is recommended if you access the Live Stream Record web-based user interface from a remote computer. To use this authentication method, you must specify a user name and password for Digest authentication in the [install-dir]/conf/admin.password file. Open this file in a text editor and enter a new line with a user name and password. For example, to add the user name myuser and the password mypassword:
    # Admin password file (format [username][space][password])
    #username password
    myuser mypassword
    To enable unauthenticated access to this HTTP Provider, open the [install-dir]/conf/VHost.xml file in a text editor and change the AuthenticationMethod property value to none. This isn't recommended if you'll be accessing the web-based UI from a remote computer.

    Specifying IP whitelists and blacklists

    Note: Supported in Wowza Streaming Engine 4.4.1 and later.
    In addition to specifying an authentication method to authenticate access to the HTTP Provider, you can set up IP whitelist and IP blacklist configurations to control the IP addresses that can connect to the Live Stream Record interface. The configuration is part of the HTTP Provider configuration and is enabled by adding the liveStreamRecordWhitelistRequestIPs and liveStreamRecordBlacklistRequestIPs properties to [install-dir]/conf/VHost.xml.
    <HTTPProvider>
    	<BaseClass>com.wowza.wms.livestreamrecord.http.HTTPLiveStreamRecord</BaseClass>
    	<RequestFilters>livestreamrecord*</RequestFilters>
    	<AuthenticationMethod>admin-digest</AuthenticationMethod>
    	<Properties>
    		<Property>
    			<Name>liveStreamRecordWhitelistRequestIPs</Name>
    			<Value>192.168.1.1</Value>
    			<Type>String</Type>
    		</Property>
    		<Property>
    			<Name>liveStreamRecordBlacklistRequestIPs</Name>
    			<Value>192.168.1.2</Value>
    			<Type>String</Type>
    		</Property>
    	</Properties>
    </HTTPProvider>
    The liveStreamRecordWhitelistRequestIPs property is a comma-separated list of IP addresses that ARE allowed to connect to the Live Stream Record interface while the liveStreamRecordBlacklistRequestIPs property is a comma-separated list of IP addresses that ARE NOT allowed to connect.

    If the liveStreamRecordWhitelistRequestIPs property has any IP addresses, then only the listed IP addresses can connect to the Live Stream Record interface. If liveStreamRecordWhitelistRequestIPs is empty, all IP addresses can connect, except for those listed in the liveStreamRecordBlacklistRequestIPs property.

    Publishing a live stream to the Wowza Streaming Engine

    To start a recording, you must publish a live stream to an application in the Streaming Engine. For this tutorial, assume that a live stream named myStream is published to the default live application. Use one of the following tutorials that matches your encoding source to publish a live stream:


    Supported file formats

    To record a live stream to MP4 (QuickTime container) files or FLV (Flash Video container) files, you must use the supported codecs to encode the live stream. When recording to the MP4 Format, the following video and audio codecs are supported:

    Video

    • H.264

    Audio

    • AAC
    • MPEG-1 Layer 3 (MP3)
    • Speex

    When recording to the FLV Format, the following video and audio codecs are supported:

    Video


    Audio


    Viewing incoming live streams and recording status


    Wowza Streaming Engine manager includes an Incoming Streams page for each live application. This page displays all of the live streams being published to the application and their recording status. If you click a stream name, an Incoming Streams Details page is displayed for the stream. This page has more information about the incoming stream and its associated recording.

    As an example, to get to the Incoming Streams Page of the default live application, do the following:

    1. Make sure that you have fulfilled all prerequisite requirements. For more information, see the Prerequisites section.

    2. On the local server or from a remote computer, open Streaming Engine manager in a web browser: http://[wowza-ip-address]:8088/enginemanager/Home.htm and sign in.

    3. Click the Applications tab in Streaming Engine manager, located at the top of the page.

    4. Click live in the contents panel. This will place the live application at the top of the contents panel, and show a list of available pages for the application.

    5. Click incoming streams in the contents panel.


    For this example, under Default Instance (_definst), there should now be a single stream called myStream with a status of Active and a Record icon under Actions.


    Recording live streams in Wowza Streaming Engine Manager


    You can start a recording, stop a recording, or segment ("split") an active recording manually on the Incoming Streams or Incoming Streams Details pages in Streaming Engine manager. To start a recording for the example live stream myStream, which creates a single MP4 file, do the following:

    1. Make sure that you have fulfilled all prerequisite requirements. For more information, see the Prerequisites section.

    2. Display the incoming live streams for the live application by following the instructions in Viewing available live streams and recording status.

    3. Click the Record icon to open the Recording dialog box.

    4. Configure the recording parameters as desired. The Streaming Engine defaults will record the live stream to a single MP4 file, where the filename is the same as the stream name.

      Note: The default values in the Recording dialog box can also be configured by using the StreamRecorder properties.

      Recording tab



      Filename - The base filename of the recorded file. You can change the default output filenames of your recorded files by entering a new filename. The name can't contain any of the following symbols: less-than (<), greater-than (>), colon (: ), quotation (' and "), forward slash (/), backslash (\), pipe (|), question mark (?), asterisk (*), double-dot (..), and tilde (~) characters.

      Path - The physical path of a location on the computer where the recorded files are stored. By default, the files are stored in the server content directory. If you want to store files in a different location, make sure that it exists on the computer and then specify its physical path. The path value can't contain any of the following symbols: less-than (<), greater-than (>), quotation (' and "), backslash (\), pipe (|), question mark (?), and asterisk (*) characters.

      Output File Format - The video on demand (VOD) format of the recorded file, either MP4 (the default value) or FLV.

      Recording Options:

      • Record data - If metadata is available in the live stream, include it in the recorded file.

      • Start on keyframe - Start recording the live stream at the first keyframe that's encountered.


      Segmentation tab



      Segmentation Option -The segmentation options specify how live streams are recorded to multiple files. The split points can be based on the recorded file size or duration, or on a schedule:

      • None - Record the live stream to a single file (the default setting). Select one of the following Versioning Options that specify what to do if the desired filename already exists:

        • Append to existing file - Resume recording the live stream to the existing file.

        • Version existing file - Start recording the live stream to a new file (the default setting). The live stream will be recorded to a new file with a filename that's generated by using the File Versioning Template value.

        • Overwrite existing file - Start recording the live stream to a new file with the same name as the existing file. This option will replace the previously recorded file with a new one.

      • Segment by size - Split the live stream into multiple on-demand files with a maximum size. Specify the maximum size value (in megabytes) in Segment Size. The minimum supported segment size is 1 MB. The live stream will be recorded to a new file with a filename that's generated by using the File Versioning Template value.

      • Segment by duration - Split the live stream into multiple on-demand files with a maximum duration. Specify the maximum duration value (in Hours:Minutes:Seconds) in Segment Duration. The minimum supported segment duration is 10 seconds. The live stream will be recorded to a new file with a filename that's generated by using the File Versioning Template value.

      • Segment by schedule - Split the live stream into multiple on-demand files based on a schedule. Specify the schedule by selecting one of the following Segment Schedule options:

        • Every hour on the hour - Split the recording into a new file at the top of each hour. This is the default setting.

        • Advanced - Split the recording by using a customized segmentation schedule that's derived from a crontab expression.


        File Versioning Template and File Versioning Module

        If you select a Segmentation Option that requires live streams to be recorded to multiple files, the filenames of new recordings are created based on the template variables specified in the File Versioning Template by using the module specified in the File Versioning Module. For more information about template variable values that you can use in the File Versioning Template, see Defining filenames of recorded segments with template strings. To specify your own module that creates filenames, enter the custom module name in the File Versioning Module.

    5. Click Record to start recording the live stream.


    After you click Record, Wowza Streaming Engine will start recording the live stream. The Recording dialog box will be removed and the underlying page updated with the new status of the live stream. You may need to click Refresh to display the most recent live stream status.


    Stopping a recording

    To stop recording a live stream, click the Stop recording icon next to a stream with a recording in progress.


    Splitting a recording

    To manually split an active recording, click the Split recording icon next to a stream with a recording in progress. This will cause Wowza Streaming Engine to switch the recording to a new file.


    Record the live stream to multiple segmented files

    To record and automatically segment a recording into multiple files, with the split points based on video duration, clock time, or file size, select one of the following combinations of options to specify how to segment the recorded files:

    Note: Wowza Streaming Engine segments files at the video keyframe closest to the configured split point. For this reason, segmented files may not be the exact size or duration specified in the Segmentation Options.
    • To split the live stream into multiple on-demand files with a maximum size, on the Segmentation tab in the Recording dialog box, under Segmentation Options, 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, on the Segmentation tab in the Recording dialog box, under Segmentation Options, select Start Recording Segment By Duration. Then in the Segment Duration box, specify the maximum duration in hours:minutes:seconds. The default value is 15 minutes (00:15:00).


    • To split the live stream into multiple on-demand files based on a schedule, on the Segmentation tab in the Recording dialog box, under Segmentation Options, 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 segment the recording into a new file at the top of each hour.
      Note: Starting and stopping recordings using crontab expressions is NOT SUPPORTED by Wowza Streaming Engine. This Segmentation Option is solely used to schedule when an active recording transitions to a new file (that is, segments the recording).


    Stream Recorder properties


    The StreamRecorder properties can be used to configure the default values used by Stream Recorders. The default StreamRecorder values are reflected in the initial settings displayed in the Recording dialog box.

    A list of available StreamRecorder properties and their descriptions can be found in the "com.wowza.wms.livestreamrecord.manager.IStreamRecorderConstants" section in the installed Javadocs ([install-dir]/documentation/serverapi) or in the Wowza Streaming Engine Server-Side API.

    Recording live streams with 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:
    http://[wowza-ip-address]:8086/livestreamrecord?app=live&streamname=myStream&action=startRecording
    Where the required URL parameters are:

    • app=live application 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
      The default value is version.

    • startOnKeyFrame=true | false
      The default value is false.

    • recordData=true | false
      The default value is true.

    • outputPath=[path]
      The default value is [] or left blank, which means that files are recorded to the default Wowza Streaming Engine content folder ([install-dir]/content). If you specify another location on the server for recorded files, you must use the fully qualified path location (for example, C:/content). You must not include a filename in the path value.

    • outputFile=[file-name].[extension]
      The default value is [] or left blank, which means that the [file-name] is the same as the [stream-name] and [extension] takes on the specified format value.

    • format=1 | 2
      1 = FLV and 2 = MP4. The default value is 2 (MP4).

    • segmentSize=[megabytes]
      The default value is 10 (10 megabytes).

    • segmentDuration=[seconds]
      The default is 900 (15 minutes).

    • segmentSchedule=[crontab string]
      See Appendix: About crontab expressions for more information.

    • fileTemplate=[file template string]
      For more information, see the installed Javadocs ([install-dir]/documentation/serverapi) or the Wowza Streaming Engine Server-Side API.

    If you set up an authentication method (see Specifying an authentication method) that requires a user name and password, add the user name and password to the URL querystring as follows:
    http://[username]:[password]@[wowza-ip-address]:8086/livestreamrecord?app=live&streamname=myStream&action=startRecording

    Recording live streams programmatically with the LiveStreamRecordManager APIs


    Wowza Streaming Engine includes the LiveStreamRecordManager Application Programming Interfaces (APIs) that enable you to have more programmatic control over live stream recordings. These APIs are fully documented in the "com.wowza.wms.livestreamrecord.manager" section in the installed Javadocs ([install-dir]/documentation/serverapi) and in the Wowza Streaming Engine Server-Side API.

    Some of the capabilities these APIs provide include:

    • Start/Stop/Split Stream Recorders - (ILiveStreamRecordManager)

    • Get a list of Stream Recorders - (ILiveStreamRecordManager)

    • Register/Unregister for LiveStreamRecordManager events - (ILiveStreamRecordManagerActionNotify)

    • Configure default parameters used by Stream Recorders via properties in Application.xml - (IStreamRecorderConstants)

    • Configure Stream Recorders when starting a recording - (StreamRecorderParameter)

    • Register/Unregister for Stream Recorder events - (IStreamRecorderActionNotify)

    • Get detailed information about a specific Stream Recorder - (IStreamRecorder)

    • Create custom code to version filenames used for the recorded segmented files of a live stream - (IStreamRecorderFileVersionDelegate)


    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 can contain any valid filename characters as well as any valid template key, in any order.

    These strings are for used 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}_${SegmentNumber}, which generates recorded MP4 filenames such as the following:

    myStream_2014-02-11-08.51.31.104-PDT_0.mp4
    myStream_2014-02-11-08.51.31.104-PDT_1.mp4
    myStream_2014-02-11-08.51.31.104-PDT_2.mp4

    Example template strings:

    ${SourceStreamName}_${SegmentNumber}:

    mystream_0
    mystream_1
    mystream_2

    ${SourceStreamName}_t${RecordingStartTime}_ct${SegmentTime}:

    mystream_t2014-02-11-02.34.53.102-PDT_ct2014-02-11-02.00.00.000-PDT
    mystream_t2014-02-11-02.34.53.102-PDT_ct2014-02-11-02.15.00.000-PDT
    mystream_t2014-02-11-02.34.53.102-PDT_ct2014-02-11-02.30.00.000-PDT

    Troubleshooting


    • Wowza Streaming Engine must be actively ingesting a live stream before you can start recording it.

    • A recording must be completed before it can be played back.

    • The Stream Recorder APIs are designed for server-side recording. Client-side recording, where multiple recording requests can be made for the same stream, isn't supported.

    • When using the SegmentBy* APIs, the Version option is used and can't be changed.


    Verifying settings by enabling additional debug logging

    You can enable additional debug logging by enabling the streamRecorderDebugEnable property for the live application in Wowza Streaming Engine manager:

    1. In the Streaming Engine manager contents panel, click live.

    2. On the live application page Properties tab, click StreamRecorder Defaults in the Quick Links bar.

      Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
    3. In the StreamRecorder Defaults area, click Edit.

    4. Click the Enabled check box for the streamRecorderDebugEnable property, and then select the option True for the property.

    5. Click Save.

    6. Click Restart in the upper-right corner of the live application page to restart the application.


    To configure [install-dir]/conf/[application]/Application.xml manually, open the file in a text editor and add the property to the <StreamRecorder>/<Properties> container in the file (be sure to get the correct <Properties> container--there are several in Application.xml):
    <Property>
        <Name>streamRecorderDebugEnable</Name>
        <Value>true</Value>
        <Type>boolean</Type>
    </Property>
    The debug log messages are recorded to the [install-dir]/logs/wowzastreamingengine_access.log file.

    The following is an example log message with the streamRecorderDebugEnable property enabled. If you get unexpected results while recording, you can use the log message to confirm the settings that are being used.
    comment server INFO 200 - [live/_definst_]StreamRecorder:stopRecorder(): recording stopped: C:\Program Files (x86)\Wowza Media Systems\Wowza Streaming Engine 4.0.0\content\myStream.mp4

    How to get LiveStreamRecord AddOn, API, and examples


    The following downloadable LiveStreamRecord AddOn packages work with Wowza Media Server 3.1.2 or earlier. These AddOn packages don't provide the full capabilities for recording live streams to on-demand files that are available in later versions of the Wowza media server software. 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.x
    Version for Wowza Media Server 2.0.0.04 to 2.2.4.x
    Version for Wowza Media Server Pro 1.7.x

    More resources



    Appendix: About crontab expressions


    In Wowza Streaming Engine, you can use crontab expressions to split a recording into multiple segmented files, based on a schedule.
    Note: Starting and stopping recordings using crontab expressions is NOT SUPPORTED in Wowza Streaming Engine. Crontab expressions are solely used to schedule when an active recording transitions to a new file (that is, segments the recording).
    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, 2014).

    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 Streaming Engine 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)

    To split a live recording every 15 minutes on even hours:
    */15 */2 * * * *
    */15 */2
    (simplified version)

    To split a live recording at 8AM and 6PM:
    0 8,18 * * * *
    0 8,18
    (simplified version)

    Originally Published: 02-11-2014.
    Updated: For Wowza Streaming Engine 4.4.1 on 03-02-2016.

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