Record a transcoder with the Wowza Streaming Cloud REST API

Learn how to use the REST API to record a live stream or transcoder in the Wowza Streaming Cloud™ service and how to programmatically download recordings.

Notes:
  • Recordings stored in Wowza Streaming Cloud generate additional costs. Billing is based on your peak recording storage, which is the greatest amount of recorded content stored in a given month. You can check your peak recording storage in the Wowza Streaming Cloud manager or by using the API. See the article View usage data with the Wowza Streaming Cloud REST API.
  • Recordings are limited to 8 hours. To record an event longer than 8 hours, stop and restart the transcoder or live stream.

Recording options for a live stream or transcoder


There are multiple workflows available for recording a live stream or transcoder in Wowza Streaming Cloud using the REST API. Start by deciding which option or combination of options is right for you.

Recording source options:

  • Record the source stream coming from your encoder
  • Record a specific output rendition of the transcoder

Start and stop recording options:

  • Start and stop a recording when the live stream or transcoder starts and stops
  • Start a recording after the live stream or transcoder has started
  • Stop a recording before the live stream or transcoder has stopped

Record a source stream


By default, Wowza Streaming Cloud records the source stream that it ingests. Follow the steps for Record a stream at transcoder start or Record a stream after a transcoder has started to record a source stream.

Record a specific output rendition


You can configure the transcoder to record a specific output rendition by setting the record transcoder output property to a specific output ID. This allows you to include a watermark if the transcoder has one enabled. It also allows you to determine the quality of the recording by selecting a particular output rendition.

  1. Using the Wowza Streaming Cloud REST API, create a live stream or a transcoder that receives video from a source encoder and delivers the stream to a hosted page or the transcoded output to a target. For specific instructions, see More resources.
  2. Make note of the output ID for the output you want to record. For a live stream, query for the details of the associated transcoder to determine the output ID.
  3. Configure the record transcoder property to specify the output ID for the output rendition you want to record.

    You can only record one output of a transcoder. If you specify a passthrough output as the recording source, Wowza Streaming Cloud uses the source stream from the encoder for the recording.

    Notes:

    Configure the transcoder output property:
    curl -X POST \
    -H "Content-Type: application/json" \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    -d '{
       "property": {
         "key": "record",
         "section": "output",
         "value": "[output_id]"
       } 
    }' "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/properties"
  4. If you have started a transcoder at any point before updating its transcoder property, you must reset the transcoder for the property to take effect. This step isn’t necessary if you haven’t started the transcoder at all.

    Reset a transcoder:
    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/reset"

    The transcoder is now configured to record the specified output rendition. See Record a stream at transcoder start or Record a stream after a transcoder has started for options to start and stop recording.

Record a stream at transcoder start


  1. Using the Wowza Streaming Cloud REST API, create a live stream or a transcoder that receives video from a source encoder and delivers the stream to a hosted page or the transcoded output to a target. For specific instructions, see More resources.
  2. When you create the live stream or transcoder, set the recording parameter to true.
     
  3. Make note of the unique live stream ID or transcoder ID that Wowza Streaming Cloud creates for your stream. You'll need it to start and stop the broadcast and to retrieve its recording.
  4. When your live stream or transcoder is fully configured and your event begins, use the PUT method to start the stream or transcoder.
    Start the live stream:
    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/start"

    Start the transcoder:
    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/start"
  5. When you're ready to stop recording, choose from one of the following options:
     
    • If you want to stop the recording before you stop the live stream or transcoder, use the PUT method to stop the recording. Note that this request uses the /transcoders endpoint, but the ID for a live stream and its associated transcoder is the same value.

      Stop the recording:
      curl -X PUT \
      -H "wsc-api-key: ${WSC_API_KEY}" \
      -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
      "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/stop_recording"
    • If you want to stop the recording when the live stream or transcoder stops, use the PUT method to stop the stream or transcoder. The recording will stop automatically.
       
      Note: We recommend leaving the live stream or transcoder running for 10 to 15 seconds after the end of the event. This ensures that the recording doesn't cut off prematurely.
      Stop the live stream:
      curl -X PUT \
      -H "wsc-api-key: ${WSC_API_KEY}" \
      -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
      "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/stop"

      Stop the transcoder:
       curl -X PUT \
      -H "wsc-api-key: ${WSC_API_KEY}" \
      -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
      "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/stop"

Record a stream after a transcoder has started


  1. Using the Wowza Streaming Cloud REST API, create a live stream or a transcoder that receives video from a source encoder and delivers the stream to a hosted page or the transcoded output to a target. For specific instructions, see More resources.
  2. When you create the live stream or transcoder, set the recording parameter to false.
     
  3. Make note of the unique live stream ID or transcoder ID that Wowza Streaming Cloud creates for your stream. You'll need it to start and stop the broadcast, start and stop the recording, and retrieve the recording.
  4. When your live stream or transcoder is fully configured, use the PUT method to start the stream or transcoder.

    Start the live stream:
    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/start"

    Start the transcoder:
    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/start"
  5. When you're ready to record, use the PUT method to start recording. Note that this request uses the /transcoders endpoint, but the ID for a live stream and its associated transcoder is the same value.
     
    Note: When you initiate an API request to start recording, there is a delay of approximately 10 seconds before the first recorded video frames pass through the transcoder in Wowza Streaming Cloud. If you are watching the source live, you will need to allow a minimum of 10 seconds between the API request and live events that need to be captured in the stream recording. 
    Start recording:
    curl -X PUT \
    -H "wsc-api-key: ${WSC_API_KEY}" \
    -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
    "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/start_recording"
  6. When you're ready to stop recording, choose from one of the following options:
     
    • If you want to stop the recording before you stop the live stream or transcoder, use the PUT method to stop the recording. 

      Stop the recording:
      curl -X PUT \
      -H "wsc-api-key: ${WSC_API_KEY}" \
      -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
      "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/stop_recording"
       
      Note: You can start and stop the recording multiple times while the transcoder is running. The resulting recording will be a single recording comprised of multiple recorded segments as opposed to multiple separate recordings.
    • If you want to stop the recording when the live stream or transcoder stops, use the PUT method to stop the stream or transcoder. The recording will stop automatically.
       
      Note: We recommend leaving the live stream or transcoder running for 10 to 15 seconds after the end of the event. This ensures that the recording doesn't cut off prematurely.
      Stop the live stream:
      curl -X PUT \
      -H "wsc-api-key: ${WSC_API_KEY}" \
      -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
      "${WSC_HOST}/api/${WSC_VERSION}/live_streams/[live_stream_id]/stop"

      Stop the transcoder:
       curl -X PUT \
      -H "wsc-api-key: ${WSC_API_KEY}" \
      -H "wsc-access-key: ${WSC_ACCESS_KEY}" \
      "${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/stop"

Get the recording


Wowza Streaming Cloud begins converting the recording to MP4 format when the transcoder stops, not necessarily when the recording stops. If the transcoder continues running after recording stops, you will need to wait until the transcoder stops to retrieve the recording.

Get all recordings for a specific live stream or transcoder:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/transcoders/[transcoder_id]/recordings"

Get all recordings for your account:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/recordings"

Related requests


View the state of the recording:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/recordings/[recording_id]/state"

Possible recording states are uploading, converting, removing, completed, and failed.

View the details of the recording:

curl -X GET \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \ 
"${WSC_HOST}/api/${WSC_VERSION}/recordings/[recording_id]"

Delete a recording:

curl -X DELETE \
-H "wsc-api-key: ${WSC_API_KEY}" \
-H "wsc-access-key: ${WSC_ACCESS_KEY}" \
"${WSC_HOST}/api/${WSC_VERSION}/recordings/[recording_id]"

More resources