How to record live stream sessions with the Livepeer.com API

Please note this beta feature is a new and still being optimized. Send feedback to help@livepeer.com.

Recording Livepeer.com livestreams is easy.

Enabling recording on a Livepeer.com livestream is super simple. Enable recording with an API call when creating a stream or updating an asset's configuration. The recordingStatus parameter tells you when the recording is ready for playback a few minutes after the stream ends.

This recording feature provides Livepeer.com users with a link to an adaptive bitrate streaming (ABR) recording of their completed livestream.

The ABR settings for the recording are inherited from the transcoding profiles set for the livestream. At this time you cannot set recording-specific ABR settings. Playback is delivered via Livepeer.com's CDN by default.

Please note if you are using OBS, set your keyframe interval to 2 for Livepeer.com beta recording to work best.

The record parameter

To turn recording on and off, update the record parameter on the stream object. The record parameter is a boolean with a false default value.

💡 Before proceeding, it will be helpful to review this guide about the relationship between parent-config and child-session stream objects. Understanding this core concept make using the recording feautre simple.

On a parent stream object.

• record: true means that new sessions are recorded.
• record: false means that new sessions are not recorded.

On a child-session stream object, the record value is read-only.

• record: true means that the session is actively being recorded or was recorded.
• record: false means that the session is not being recorded or was not recorded.

The absence of a record parameter on a stream object is equivalent to record: false.

Notable JSON parameters for a stream session with record:true

A list of JSON parameters for the stream object is at https://livepeer.com/docs/api/stream.

• id: This string is the unique identifier for the asset, in this case a single livestream session. This string is also used to form the playback URL for the recorded session.
• parentId: Equivalent to the id of the parent stream object.
• createdAt: This number is the timestamp when the livestream session began and the asset was created. Reported in Unix epoch time.
• sourceSegmentsDuration: This number is the duration in seconds of asset source processed. When the livestream session is over, this number equates to the length of the livestream session and recording.
• recordingStatus: This boolean appears only when record: true, and it is either ready when the recorded livestream is available for playback or waiting while the livestream is still active or just recently completed.

Reference code examples

POST /stream to create a parent stream object with recording turned on. All sessions will be recorded.

curl -X POST \
-H 'content-type: application/json' \
-H 'authorization: Bearer <api key>' \
-d '{
  "name": "test_stream_recording_on",
  "record": true
}' \
https://livepeer.com/api/stream

201 created

{
  "name":"test_stream_recording_on",
  "record":true,
  "kind":"stream",
  "userId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxx",
  "id":"yyyyyyyy-yyyy-yyyy-yyyy-yyyy",
  "createdAt":1595721600,
  "streamKey":"zzzz-zzzz-zzzz-zzzz",
  "playbackId":"xyz123xyz123",
  "createdByTokenName":"test-api-key",
  {other asset object keys, like profiles}
}

PATCH /stream/{id} to turn on/off recording for an existing asset

Turn recording on. All new sessions will be recorded. In progress sessions will not be recorded.

curl -X PATCH https://livepeer.com/api/stream/{id}/record \
-H 'content-type: application/json' \
-H 'authorization: Bearer {api-key}' \
-d '{"record":true}'

Turns recording off. All new sessions will not be recorded. In progress sessions will still be recorded.

curl -X PATCH https://livepeer.com/api/stream/{id}/record \
-H 'content-type: application/json' \
-H 'authorization: Bearer {api-key}' \
-d '{"record":false}'

GET /stream/{id} to retrieve an asset and record value

curl -H 'authorization: Bearer {api-key}' \
"https://livepeer.com/api/stream/{id}"

200 OK

If the record parameter is not returned in the JSON response, recording is not turned on. An absent record parameter is equivalent to "record": false.

{
  "id":"yyyyyyyy-yyyy-yyyy-yyyy-yyyy",
  "kind":"stream",
  "name":"test_stream",
  "record": false,
  "userId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxx",
  "createdAt":1595721600,
  "streamKey":"zzzz-zzzz-zzzz-zzzz"
  "createdByTokenName":"test-api-key",
  {other asset object keys, like parentId and profiles}
}

Next, learn how to playback a recorded session.