Manage live-to-VOD nDVR stores by using the Wowza Streaming Engine REST API

Wowza nDVR allows you to record a live stream as Wowza Streaming Engine™ media server software broadcasts it to viewers with DVR playback controls (play, pause, rewind). Wowza nDVR records the stream as it's ingested so that it remains available for HTTP-based playback after the live stream ends, or you can convert the nDVR stream (called a store) to MP4 for VOD sharing and viewing. Learn how to use the Wowza Streaming Engine REST API to manage nDVR stores, convert nDVR stores to MP4 files, and manage the conversion cache.

Notes:

Get a list nDVR stores


Get a list of all nDVR stores for an application on a local instance of Wowza Streaming Engine:

curl -X GET \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/{appName}/instances/{instanceName}/dvrstores


Note: Going forward, all examples on this page use the application name testlive. You will replace this with the name of your application.

Get a list of all nDVR stores for an application named testlive on a local instance of Wowza Streaming Engine:

curl -X GET \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores

The command should return a response that looks something like this:

{
   "serverName": "serverName",
   "groupConversionStatusList": [],
   "dvrconverterstoresummary": [{
      "location": "/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/myStream.0",
      "name": "myStream.0"
   }] 
}

Get an nDVR store


View the details of a specific nDVR store.

curl -X GET \
-H 'Accept:application/json' \
-H 'Content-Type:application/json; charset=utf-8' \
http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/{dvrStoreName}

View the details of an nDVR store named myStream.0:

curl -X GET \
-H 'Accept:application/json' \
-H 'Content-Type:application/json; charset=utf-8' \
http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/myStream.0

The command should return a response that looks something like this:

{
    "serverName": "serverName",
    "dvrStoreName": "myStream.0",
    "DvrConverterStore": {
        "dvrStoreName": "myStream.0",
        "audioAvailable": true,
        "videoAvailable": true,
        "isLive": false,
        "dvrStartTime": 0,
        "dvrEndTime": 64002,
        "duration": 64002,
        "utcStart": 1489162716364,
        "utcEnd": 1489162780317,
        "outputFilename": null,
        "conversionStatus": {
            "storeName": null,
            "fileName": null,
            "state": "STOPPED",
            "statusCode": "NONE",
            "errorStrings": [],
            "startTime": 0,
            "endTime": 0,
            "duration": 0,
            "currentChunk": 0,
            "chunkCount": 0,
            "fileSize": 0,
            "fileDuration": 0
        }
    }
}

Convert an nDVR Store


Convert a single-bitrate nDVR store to an MP4 VOD asset.

Note: When using this call to convert to a VOD asset, the parameter {action} is replaced with convert:
curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/{dvrStoreName}/actions/{action}

In this example, the call converts the single-rate nDVR store myStream.0 to an MP4 VOD asset:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/myStream.0/actions/convert

The command should return a response that looks something like this:

{
    "success": true,
    "message":" Conversion started",
    "data": null
}

Convert a group of nDVR stores


Convert a group of ABR stream stores named myStream.0 and myStream.1, to MP4:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/actions/convert?dvrConverterStoreList=myStream.0,myStream.1"

Refine conversion queries with optional parameters


nDVR store conversions can be customized by using any of several optional parameters:

ParameterDescription
dvrConverterStartTimeStarts the conversion at a specified UTC Unix timestamp in the store instead of at the first entry.
dvrConverterEndTimeStops the conversion at a specified UTC Unix timestamp in the store instead of at the end of the store.
dvrConverterDurationStops the conversion after a specified amount of time (in milliseconds). Can't be used with dvrConverterStartTime or dvrConverterEndTime.
dvrConverterTimeTypeThe way time is measured for clip extractions. If set to DVR, the dvrConverterStartTime, dvrConverterEndTime, and dvrConverterDuration values are used to extract clips for the specified duration. If not specified, the default value, UTC, is used. For more information, see Configure an nDVR conversion to use DVR time.
dvrConverterTolerance(Wowza Streaming Engine 4.7.5 and later) The length of time, in milliseconds, past the specified duration that the DVR conversion is allowed to run when attempting to apply the last nDVR GOP. The default value is 1000.
dvrConverterOutputFilenameThe filename of the converted MP4 file. If unspecified, the output filename is same as the name of the store being converted.
dvrConverterInterleaveDelay(Wowza Streaming Engine 4.7.0.01 and later) An interleave delay (in milliseconds) used to manage I/O saturation during conversion. This parameter is enabled by default with a value of 100. You can change the value to be anywhere from 0 to 2000. Higher values increase conversion time but enable other processes to access the storage system that contains the nDVR store between conversion operations, resulting in reduced I/O saturation.
dvrConverterDebugConversionsIf true, includes debugging in the Wowza Streaming Engine Server access log file.
dvrConverterDefaultFileDestinationThe file location to use when converting a nDVR store. The default is the StorageDir in the application in use.


Note: See the Swagger reference documentation for additional conversion parameters.

Specify the start and end time of a conversion:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/{dvrStoreName}/actions/convert?dvrConverterStartTime={unix-timestamp}&dvrConverterEndTime={unix-timestamp}"

 

Note: Actual start and end times may vary from the specified dvrConverterStartTime and dvrConverterEndTime values if the framerate and keyframe frequency of your encoded live stream aren’t configured correctly. For a 30-fps stream, insert a keyframe at least once every 30 frames. If you insert a keyframe less frequently—every 60 frames on a 30-fps stream, for example—the start and end times may vary from your specified parameters by 1 or more seconds. Be sure to test your workflow to find the best settings.

Specify the duration of a conversion:

In the default, UTC time:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/{dvrStoreName}/actions/convert?dvrConverterDuration={number-of-milliseconds}"

In DVR time:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://127.0.0.15:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/{dvrStoreName}/actions/convert?dvrConverterStartTime=0&dvrConverterDuration=180000&dvrConverterTimeType=DVR"

Specify the end time of a conversion and the filename of the MP4 asset:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/{dvrStoreName}/actions/convert?dvrConverterEndTime={unix-timestamp}&dvrConverterOutputFilename={outputfilename}"

Change the interleave delay between conversion operations:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/{dvrStoreName}/actions/convert?dvrConverterInterleaveDelay={number-of-milliseconds}"

Enable debugging of the conversion in the Wowza Streaming Engine access log file:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
"http://127.0.0.1:8087/v2/servers/(serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/{dvrStoreName}/actions/convert?dvrConverterDebugConversions=true"

Clear the conversion cache


Conversion requests are cached so they can be reused. If you need to adjust your conversion parameters, clear the cache between requests.

Clear the conversion cache:

curl -X PUT \
-H 'Accept:application/json; charset=utf-8' \
-H 'Content-Type:application/json; charset=utf-8' \
http://127.0.0.1:8087/v2/servers/{serverName}/vhosts/{vhostName}/applications/testlive/instances/{instanceName}/dvrstores/actions/expire

Configure an nDVR conversion to use DVR time


When creating a clip extraction from an nDVR store, the default start and end times are based on the UTC timecodes for the stream. However, there may be some circumstances in which you'd prefer to extract a clip based on the dvrConverterStartTime and dvrConverterEndTime parameters to more accurately gauge the total duration of the content. To do this, you can use the dvrConverterTimeType conversion parameter or you can add the following property to the [install-dir]/conf/Application.xml file in the <Application>/<DVR>/<Properties> section.

<Property>
    <Name>dvrConverterTimeType</Name>
    <Value>DVR</Value>
    <Type>String</Type>
</Property>

Where the dvrConverterTimeType value DVR or UTC. If not specified, the UTC timecode is used.

Note: If both the property and parameter are used, the dvrConverterTimeType parameter will override the property.

More resources