How to create and manage recorders by using the Wowza Streaming Engine REST API

You can use the Wowza Streaming Engine™ media server software REST API to create and manage stream recorders in a Wowza Streaming Engine instance.

A stream recorder creates an MP4 recording of a stream as it's broadcast from a live application. A recorder can be created before the live application starts streaming, or while the live application is actually streaming. You can use the REST API to stop recorder at any time, otherwise, it stops when the server no longer receives the incoming stream. After the recorder stops, it is no longer available—the MP4 recording is saved but you have to create a new recorder if you plan to restart and record the same live application.

Notes:

Contents


Get a list of recorders
Create a recorder
Split an active recording
Stop a recording

Get a list of recorders


View a list of all stream recorders for an application (live, in this example) on a local Wowza Streaming Engine instance:

curl -X GET --header 'Accept:application/json; charset=utf-8' --header 'Content-Type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/streamrecorders

If the stream and recording haven't started, the command should return a response that looks something like this:

{
  "serverName": "_defaultServer_",
  "instanceName": "_definst_",
  "streamrecorder": [{
      "recorderName": "myStream",
      "instanceName": "_definst_",
      "recorderState": "Waiting for stream",
      "defaultRecorder": false,
      "segmentationType": "None",
      "outputPath": "/Library/WowzaStreamingEngine/content",
      "baseFile": ".mp4",
      "fileFormat": "MP4",
      "fileVersionDelegateName": "com.wowza.wms.livestreamrecord.manager.StreamRecorderFileVersionDelegate",
      "fileTemplate": "${BaseFileName}_${RecordingStartTime}_${SegmentNumber}",
      "segmentDuration": 900000,
      "segmentSize": 10485760,
      "segmentSchedule": "0 * * * * *",
      "recordData": false,
      "startOnKeyFrame": false,
      "splitOnTcDiscontinuity": false,
      "backBufferTime": 0,
      "option": "Version existing file",
      "moveFirstVideoFrameToZero": true,
      "currentSize": 0,
      "currentDuration": 0,
      "recordingStartTime": ""
  }]
}

If the stream and recorder have started, the response looks something like this:

{
  "serverName": "_defaultServer_",
  "instanceName": "_definst_",
  "streamrecorder": [{
      "recorderName": "myStream",
      "instanceName": "_definst_",
      "recorderState": "Recording in Progress",
      "defaultRecorder": false,
      "segmentationType": "None",
      "outputPath": "/Library/WowzaStreamingEngine/content",
      "baseFile": "myStream.mp4",
      "fileFormat": "MP4",
      "fileVersionDelegateName": "com.wowza.wms.livestreamrecord.manager.StreamRecorderFileVersionDelegate",
      "fileTemplate": "${BaseFileName}_${RecordingStartTime}_${SegmentNumber}",
      "segmentDuration": 38537,
      "segmentSize": 10485760,
      "segmentSchedule": "0 * * * * *",
      "recordData": false,
      "startOnKeyFrame": false,
      "splitOnTcDiscontinuity": false,
      "backBufferTime": 0,
      "option": "Version existing file",
      "moveFirstVideoFrameToZero": true,
      "currentSize": 3104321,
      "currentDuration": 38537,
      "currentFile": "/Library/WowzaStreamingEngine/content/myStream_2017-04-06-16.07.01.033-PDT_0.mp4",
      "recordingStartTime": "2017-04-06-16.07.01.033--07:00"
    }]
}

Create a recorder


When you create a recorder, it starts immediately if the stream is running. Otherwise, it starts when you start the stream.

Create a stream recorder named myStream using the default settings (notice that the stream recorder name matches the incoming stream name and is included in the request URL and in the body of the request, and they must match):

curl -X POST --header 'Accept:application/json; charset=utf-8' --header 'Content-Type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/streamrecorders/myStream -d '
{
  "instanceName": "",
  "fileVersionDelegateName": "",
  "serverName": "",
  "recorderName": "myStream",
  "currentSize": 0,
  "segmentSchedule": "",
  "startOnKeyFrame": false,
  "outputPath": "",
  "currentFile": "",
  "saveFieldList": [
    ""
  ],
  "recordData": false,
  "applicationName": "",
  "moveFirstVideoFrameToZero": false,
  "recorderErrorString": "",
  "segmentSize": 0,
  "defaultRecorder": false,
  "splitOnTcDiscontinuity": false,
  "version": "",
  "baseFile": "",
  "segmentDuration": 0,
  "recordingStartTime": "",
  "fileTemplate": "",
  "backBufferTime": 0,
  "segmentationType": "",
  "currentDuration": 0,
  "fileFormat": "",
  "recorderState": "",
  "option": ""
}
'

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

{
  "success": true,
  "message": "Recorder Created",
  "data": null
}

Split an active recording


When you split, or segment, an active recording, the recorder keeps running but the current recording ends and a new recording begins from the moment of the split. Both recordings are stored in the specified output_path (by default, /Library/WowzaStreamingEngine/content) and are named according to the filenaming template (by default, [BaseFilename]_[RecordingStartTime]_[SegmentNumber].mp4).

Split a recording:

curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-Type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/streamrecorders/myStream/actions/splitRecording

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

{
  "success": true,
  "message": "Recording (myStream) split",
  "data": null
}

Stop a recording


Stop a recording:

curl -X PUT --header 'Accept:application/json; charset=utf-8' --header 'Content-Type:application/json; charset=utf-8' http://localhost:8087/v2/servers/_defaultServer_/vhosts/_defaultVHost_/applications/live/instances/_definst_/streamrecorders/myStream/actions/stopRecording

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

{
  "success": true,
  "message": "Recording (myStream) stopped",
  "data": null
}

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