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.

  • 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 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 instructions, see the following tutorials:
  1. When you create the live stream or transcoder, set the recording parameter to true.
     
  2. 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.
  3. When your live stream or transcoder is fully configured and your event begins, use the PUT method to start the stream or transcoder.

    Notes:

    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"
  4. 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 instructions, see the following tutorials:
  1. When you create the live stream or transcoder, set the recording parameter to false.
     
  2. 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.
  3. 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"
  4. When you're ready to record, use the PUT method to start recording.
     
    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"
  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"

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]"