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:

• Wowza Streaming Engine 4.3.0 or later is required.
• PHP examples for the tasks in this article are available in the tests folder of the PHP REST Library for Wowza Streaming Engine on GitHub.
• Reference documentation for the Wowza Streaming Engine REST API is available by using OpenAPI (Swagger), which you can download and install locally. See Access reference documentation for the Wowza Streaming Engine REST API.

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:

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

• Extract MP4-formatted files from DVR streams with Wowza Streaming Engine Java API