Configure advanced properties for Wowza nDVR

This article explains the properties you can use for an advanced nDVR configuration in Wowza Streaming Engine™ media server software. Basic configuration, including enabling recording, is described in Set up and run Wowza nDVR in Wowza Streaming Engine. We recommend that you start with the basic configuration and test playback of your recorded streams before using the additional properties described here.

Note: Wowza Streaming Engine 4.7.6 or later is required to use Wowza nDVR for MPEG-DASH streaming.

How to configure nDVR properties


Advanced properties for Wowza nDVR configuration can be added to your live application in Wowza Streaming Engine Manager or by editing the live application's configuration file (Application.xml) in a text editor.

Configure nDVR properties in Wowza Streaming Engine Manager

  1. Click the Applications tab, select your live application, and then select nDVR in the application's contents panel.
     
  2. On the nDVR page Properties tab, in the DVR section, click Edit.
     
    Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
  3. Select the Enabled check box next to the desired property, and then set its value. See the Property reference below for details on each property.
     
  4. Click Save, and then restart the application to apply the changes.

Configure nDVR properties in XML

Note: Editing Application.xml is the only way to add properties with Wowza Media Server™ software.

  1. Navigate to [install-dir]/conf/[application]/ and open Application.xml in a text editor.
  2. Add the desired properties to the <DVR>/<Properties> container. Be sure to add the property to the correct <Properties> element in Application.xml as there are several similar containers in the file. See the Property reference below for details on each property.
     
  3. Restart Wowza Streaming Engine to apply the changes.

Property reference


dvrAllowableAVPacketDelta

Specifies the allowable difference (delta) between audio and video synchronization, in milliseconds. Wowza nDVR expects the incoming audio and video to be aligned, so this setting safeguards against audio and video data packets that aren't closely aligned. If the audio and video are out of alignment by more than the specified value, the Wowza Streaming Engine briefly ignores the audio and video chunks and attempts to get the stream back into alignment. The default value is 2000 ms.

Note: If you already have an out-of-alignment issue, increasing the dvrAllowableAVPacketDelta value is likely to cause more problems. While it increases the tolerance level, the overall quality may diminish significantly.

<Properties>
     <Property>
          <Name>dvrAllowableAVPacketDelta</Name>
          <Value>2000</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrAppendDiscontinuityDelta

Applies to <ArchiveStrategy> append mode. The default value is 0 ms. When using append mode, a short time delta, in milliseconds, is placed between the old recording and the newly appended recording.

<Properties>
     <Property>
          <Name>dvrAppendDiscontinuityDelta</Name>
          <Value>0</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrAudioOnlyChunkTargetDuration

Specifies the target chunk size, in milliseconds, to use when recording audio-only content. The default value is 2000 ms. This setting is ignored if the stream contains video and audio because in that case, the keyframe determines the chunk size.

<Properties>
     <Property>
          <Name>dvrAudioOnlyChunkTargetDuration</Name>
          <Value>2000</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrChunkDurationMinimum

Controls the minimum nDVR chunk size, in milliseconds (ms). The default value is 1500 ms (1.5 seconds). Chunks are broken on keyframes, so set this value to a multiple of your group of pictures (GOP) size. For example, if you GOP is 2 seconds, you could set dvrChunkDurationMinimum to 2, 4, 6, or 8. If your GOP is 3 seconds, instead you'd want to use 3, 6, or 9.

Note: With HTTP streaming, there's a tradeoff between chunk size and latency. The larger the chunks, the longer it takes for playback to start and the shorter your playlists. However, if your chunk size is too small, you'll have longer playlists and more frequent requests to the server.
<Properties>
     <Property>
          <Name>dvrChunkDurationMinimum</Name>
          <Value>10000</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrChunkGroupingSeconds

Specifies, in seconds, how much content is recorded into one directory. The default value is 600 seconds (10 minutes). The directory naming convention is HHHH_MM_SS where H = hours, M = minutes, S = seconds. Using the default values, the first directory would be named 0000_00_00, the second directory would be named 0000_10_00, and so on.

Note: There are very few reasons to change this layout, as it's hidden from users and is an internal construct used to guarantee that a folder doesn't reach its maximum number of files.
<Properties>
     <Property>
          <Name>dvrChunkGroupingSeconds</Name>
          <Value>600</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrEncryptionSharedSecret

In live stream repeater (origin/edge) scenarios where Wowza Streaming Engine uses encryption, a shared secret must be defined for both origin and edges to encrypt information sent between origin and edge.

<Properties>
     <Property>
          <Name>dvrEncryptionSharedSecret</Name>
          <Value>[AGoodSecret]</Value>
          <Type>String</Type>
     </Property>
</Properties>

Note: See also liveRepeaterEncryptionSharedSecret.

dvrMaxChunkLogCount

Maximum number of chunks to log recording information about in the wowzastreaming_access.log file. The default value is 10 chunks. As recording is continued past this value, there is no feedback for normal operation in the log. View directories and files created in [install-dir]/dvr for ongoing feedback that recording is occurring.

<Properties>
     <Property>
          <Name>dvrMaxChunkLogCount</Name>
          <Value>10</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrMaxRecountDurationLogCount

Maximum number of log statements recorded about chunk duration being recalculated. A value less than 0 means that all statements are logged with no limit. The default value is 30.

<Properties>
     <Property>
          <Name>dvrMaxRecountDurationLogCount</Name>
          <Value>30</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrMinimumAvailableChunks

Minimum number of chunks required to be available before HTTP streaming can start. The unit is the number of chunks. The default and minimum value is 3 chunks.

<Properties>
     <Property>
          <Name>dvrMinimumAvailableChunks</Name>
          <Value>3</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrMPEGDashavailabilityStartTimeAdjustment

Adjusts the time at which the chunks are available. The default is 6000 ms (6 seconds). Smaller values allow players to start playback closer to the live point, because the value indicates that chunks are available earlier. However, if the start time adjustment is too small, then players may request chunks before they're available, causing playback to stall. You might need to experiment to find the right value.

<Properties>
     <Property>
          <Name>dvrMPEGDashavailabilityStartTimeAdjustment</Name>
          <Value>6000</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrPacketSortTime

Adds a packet sorter, in milliseconds, before the audio and video packets get to Wowza nDVR. This is similar to the live streaming packet sorter and adds latency equal to the value. We recommend always fixing the audio and video alignment of the stream before it's ingested by Wowza Streaming Engine, but when necessary this setting can be used in an attempt to fix alignment. The default value, 0, doesn't add a packet sorter or any latency to the stream.

<Properties>
     <Property>
          <Name>dvrPacketSortTime</Name>
          <Value>0</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

dvrPlaylistRequestDelegate

Registers a delegate to generate or limit a DVR playlist request. For more information, see How to use Wowza nDVR Playlist Request API.

<Properties>
    <Property>
        <Name>dvrPlaylistRequestDelegate</Name>
        <Value>com.wowza.wms.dvr.impl.DvrStartDurationPlaylistRequestDelegate</Value>
        <Type>String</Type>
    </Property>
</Properties>

dvrSanJosePlaylistVersion

Specifies the San Jose F4M playlist version number (version 1.0 or version 2.0). The default value is 2.0.

<Properties>
    <Property>
        <Name>dvrSanJosePlaylistVersion</Name>
        <Value>1.0</Value>
    </Property>
</Properties>

dvrWaitForCodecTime

Amount of time, in milliseconds (ms), that Wowza nDVR waits to receive audio and video codec information after streaming has started. The default value is 8000 ms.

<Properties>
     <Property>
          <Name>dvrWaitForCodecTime</Name>
          <Value>8000</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

liveRepeaterEncryptionSharedSecret

A shared secret used to encrypt sensitive data, including nDVR chunk data, that's sent across servers in an origin/edge configuration. Using this property provides a unique key for each stream served by the origin, in contrast to the dvrEncryptionSharedSecret property, which generates an identical key for all streams.

Note: If both a dvrEncryptionSharedSecret and liveRepeaterEncryptionSharedSecret are defined, then the dvrEncryptionSharedSecret property is used by default. If neither property is defined, then a default liveRepeaterEncryptionSharedSecret is used.

Unlike the other properties in this article, the liveRepeaterEncryptionSharedSecret is configured by creating a custom application property, not by editing the application's nDVR properties.

To configure a liveRepeaterEncryptionSharedSecret in Wowza Streaming Engine Manager, do the following:

  1. Click the Applications tab and then click the name of your live application (such as live) in the contents pane.
  2. Click the Properties tab and then, in the Quick Links bar, click Custom.
     
    Note: Access to the Properties tab is limited to administrators with advanced permissions. For more information, see Manage credentials.
  3. In the Custom area, click Edit.
  4. Click Add Custom Property, specify the following settings in the Add Custom Property dialog box, and then click Add:
    • Path - Select /Root/Application.
    • Name - Enter liveRepeaterEncryptionSharedSecret.
    • Type - Select String.
    • Value - Enter the shared secret to be encrypted.
  5. Click Save, and then restart the live application to apply the changes.

recordAudio

Set to true (the default) to record audio of incoming stream. Set to false to ignore audio packets during recording. Either recordAudio or recordVideo must be set to true.

<Properties>
     <Property>
          <Name>recordAudio</Name>
          <Value>true</Value>
          <Type>Boolean</Type>
     </Property>
</Properties>

recordVideo

Set to true (the default) to record video of incoming stream. Set to false to ignore video packets during recording. Either recordVideo or recordAudio must be set to true.

<Properties>
     <Property>
          <Name>recordVideo</Name>
          <Value>true</Value>
          <Type>Boolean</Type>
     </Property>
</Properties>

startRecordingOnStartup

Determines if DVR should start recording immediately upon stream start. The default value (true) means that when a stream starts, DVR immediately starts recording. If the DVR recording is controlled via API, it's useful to set the value to false.

<Properties>
     <Property>
          <Name>startRecordingOnStartup</Name>
          <Value>false</Value>
          <Type>boolean</Type>
     </Property>
</Properties>

streamTimeout

Specifies the amount of time, in milliseconds (ms), that Wowza nDVR will wait for packets until it stops recording. This timeout is meant to account for when encoders disconnect and then restart. The default value is 300,000 ms (5 minutes). The value should be a non-zero value or else your recording will stop whenever there is no data.

For MPEG-DASH nDVR playback, we recommend that you use a much lower value, such as 30000 (20 seconds). Otherwise, there might be a relatively long window of time during which new clients try to start playback and then quickly stall because chunks aren't actually available. You might need to experiment to find the right value.

<Properties>
     <Property>
          <Name>streamTimeout</Name>
          <Value>300000</Value>
          <Type>Integer</Type>
     </Property>
</Properties>

More resources