• Live to VOD clip extraction query examples (nDVR) for the Wowza Streaming Engine REST API

    Wowza Streaming Engine™ media server software has a REST Application Programming Interface (API) that can be used to configure, manage, and monitor the media server through HTTP requests. This article provides some basic cURL examples that demonstrate how to query the Wowza Streaming Engine REST service to get information about nDVR stores and extract clips from live to VOD streams in nDVR stores. For a complete breakdown and documentation of the API, see How to access documentation for the Wowza Streaming Engine REST API.

    Note: Wowza Streaming Engine 4.3.0 or later is required. You must also have working knowledge of cURL and REST-related services.

    Contents


    Get a list of nDVR stores
    Get an nDVR item
    Convert an nDVR store
    Convert a group of nDVR stores
    Optional parameters
    Clear the conversion cache
    More resources

    Get a list nDVR stores


    The following example shows how to request a list of all nDVR stores in your Wowza Streaming Engine instance:
    curl  -X GET --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/dvrstores
    An example result:
    {"restURI":"http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/dvrstores","groupConversionStatusList":[],"dvrconverterstoresummary":[{"location":"/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/dvrstores/myStream.0","name":"myStream.0"}]}

    Get an nDVR item


    The following example shows how to request information about a single nDVR store (myStream):
    curl -X GET --header 'Accept:application/json' --header 'Content-type:application/json; charset=utf-8' http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/dvrstores/myStream
    An example result:
    {"restURI":"http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/dvrstores/myStream","dvrStoreName":"myStream.0","DvrConverterStore":{"dvrStoreName":"myStream.0","audioAvailable":true,"videoAvailable":true,"isLive":false,"dvrStartTime":0,"dvrEndTime":64000,"duration":64000,"utcStart":1442589049009,"utcEnd":1442589320752,"outputFilename":null,"conversionStatus":{"storeName":"myStream.0","fileName":"/Library/WowzaStreamingEngine/content/myStream.0.mp4","state":"SUCCESSFUL","statusCode":"NONE","errorStrings":[],"startTime":1442589398242,"endTime":1442589399459,"duration":1217,"currentChunk":8,"chunkCount":8,"fileSize":475171,"fileDuration":56009}}}

    Convert an nDVR Store


    The following example shows how to initiate the conversion of single-bitrate DVR stream to a VOD asset:
    curl  -X PUT --header 'Accept:application/xml; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/dvrstores/myStream.0/actions/convert
    An example XML result:
    <?xml version="1.0" encoding="UTF-8" ?>
    <wmsResponse>
      <success>true</success>
      <message>Conversion started</message>
    </wmsResponse>
    Note: A conversion request is cached so it can be viewed and used for conversions of the same store in the future. If you need to adjust any conversion parameters for future conversions, you must clear the cache. For more information, see Clear the conversion cache.

    Convert a group of nDVR stores


    The following example shows how to initiate the conversion of DVR streams in an adaptive bitrate (ABR) streaming group to a VOD asset:
    curl  --digest -u "admin:pass"  -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' "http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/dvrstores/actions/convert?dvrConverterStoreList=myStream.0,myStream.1"
    An example result:
    {"success":true,"message":"ID:2","data":null}
    Note: A conversion request is cached so it can be viewed and used for conversions of the same store in the future. If you need to adjust any conversion parameters for future conversions, you must clear the cache. For more information, see Clear the conversion cache.

    Optional parameters


    You can include the following parameters in your HTTP requests to control when DVR store conversion starts and stops and to specify the file name of the extracted clip:

    • dvrConverterStartTime - Starts conversion at the indicated Unix timestamp.

    • dvrConverterEndTime - Stops conversion at the indicated Unix timestamp.

    • dvrConverterDuration - Stops conversion after an amount of time specified milliseconds.

    • dvrConverterOutputFilename - The file name of the extracted on-demand clip.

    • dvrConverterDebugConversions - Enables debugging to be shown in the Wowza Streaming Engine access log file.

    Note: A conversion request is cached so it can be viewed and used for conversions of the same store in the future. If you need to adjust any conversion parameters for future conversions, you must clear the cache. For more information, see Clear the conversion cache.

    Start and end time example


    curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' "http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/dvrstores/myStream.0/actions/convert?dvrConverterStartTime=[unix-timestamp]&dvrConverterEndTime=[unix-timestamp]"
    Note: The actual start and/or end times may vary from the specified dvrConverterStartTime and/or dvrConverterEndTime time(s), depending on the framerate and keyframe frequency of your encoded live stream. To help avoid this issue, if you're encoding a live stream at 30 frames-per-second (30 fps), we suggest that your encoder insert a keyframe into the stream at least once every 30 frames. If you're encoding a live stream at 30 fps, and you choose to insert a keyframe for every 60 frames, the start/end times may vary from the specified parameter values by 1 or more seconds. The start/end time variation may differ depending on other framerate/keyframe frequency setting combinations that you specify for your encoding, so be sure to test your workflow to find the best settings.

    Start time and duration example


    curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' "http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/dvrtest/instances/_definst_/dvrstores/myStream.0/actions/convert?dvrConverterStartTime=[unix-timestamp]&dvrConverterDuration=[milliseconds]"

    End time and duration example


    curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' "http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/dvrtest/instances/_definst_/dvrstores/myStream.0/actions/convert?dvrConverterEndTime=[unix-timestamp]&dvrConverterDuration=[milliseconds]"

    End time, duration, and output file name example


    curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' "http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/dvrtest/instances/_definst_/dvrstores/myStream.0/actions/convert?dvrConverterEndTime=[unix-timestamp]&dvrConverterDuration=[milliseconds]&dvrConverterOutputFilename=[outputfilename]"

    Enable debug output example


    curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' "http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/dvrtest/instances/_definst_/dvrstores/myStream.0/actions/convert?dvrConverterDebugConversions=true"

    Clear the conversion cache


    When a conversion is requested, the request is cached so it can be viewed and used for conversions of the same store in the future. If you need to adjust any conversion parameters for future conversions, you must clear the cache. The following cURL example shows how to clear the conversion cache for the nDVR converter:
    curl  --digest -u "admin:pass"  -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-type:application/json; charset=utf-8' http://127.0.0.1:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/dvrstores/actions/expire

    More resources




    Originally Published: For Wowza Streaming Engine 4.3.0 on 10-06-2015.
    Updated: For Wowza Streaming Engine 4.5.0 on 06-23-2016.

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