#Record a live stream session

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

Here is how recording works in Livepeer.com.

Recording is turned off by default. Recording OFF means that new sessions are not recorded.
Turning recording ON means that new sessions are recorded.
When updating this setting, note that in progress sessions will adhere to the on/off setting when the live stream began. The changed setting only applies to new stream sessions.
The adaptive bitrate (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.
Recording 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.

#Recording settings in the Livepeer.com Dashboard

The easiest way to turn recording on or off for a stream is to login to the Livepeer.com Dashboard, navigate to the streams list page, livepeer.com/app/user, and click on a stream name. Update the Record Sessions radio button, and all new sessions will adopt the updated recording setting. In progress sessions will not start/stop recording though.

The session recording playback URL will be available about 5 minutes after the live stream ends and will appear in the session table at the bottom of the stream’s page. Note the session table only appears after you start your first live stream.

#Recording live stream sessions with the Livepeer.com API

Make requests of the Livepeer.com API to turn recording on/off, find out if a recording is ready for playback, and get the recording playback URL.

#The `record` parameter

First, it’s important to understand the relationship between a Livepeer.com stream and session.

Every session has a parent stream. The session parentId value is the same as the stream id value. When you set the record value of the parent stream, each new session adopts that value.

On a stream object.

record: true means that each new session is recorded.
record: false means that each new session is not recorded.

On a session 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 or session object is equivalent to record: false.

#Notable parameters for a `session` with `record:true`

id: This string is the unique identifier for the 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 live stream 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 live stream session is over, this number equates to the length of the live stream session and recording.
recordingStatus: This boolean appears only if record is true, and it is either ready when the recorded live stream is available for playback or waiting while the livestream is still active or just recently completed.
recordingUrl: This string appears only if record is true and when recordingStatus changes to ready. It’s value is the .m3u8 URL to stream the recorded session.
mp4Url : This string appears only if record is true and when recordingStatus changes to ready. Its value is the link to the mp4 file that represents the recording.

#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,
    "profiles":[
        {"name":"720p","bitrate":2000000,"fps":30,"width":1280,"height":720},
        {"name":"480p","bitrate":1000000,"fps":30,"width":854,"height":480}],
        {"name":"360p","bitrate":500000,"fps":30,"width":640,"height":360}],
    "id":"ijkl61f3-95bd-4971-a7b1-4dcb5d39e78a",
    "createdAt":1596081229373,
    "streamKey":"abcd-uimq-jtgy-x98v",
    "playbackId":"efghb2mxupongp5k"
    {other asset object keys}
}

PATCH /stream/{id}/record 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}'

Turn 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 a stream and record value

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

GET /session/{id} to retrieve a session, recordingStatus and recordingUrl value

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

200 OK

{
    "name":"test_session_recording_on",
    "record":true,
    "profiles":[
        {"name":"720p","bitrate":2000000,"fps":30,"width":1280,"height":720},
        {"name":"480p","bitrate":1000000,"fps":30,"width":854,"height":480}],
        {"name":"360p","bitrate":500000,"fps":30,"width":640,"height":360}],
    "id":"ijkl61f3-95bd-4971-a7b1-4dcb5d39e78a",
    "createdAt":1596081229373,
    "streamKey":"abcd-uimq-jtgy-x98v",
    "playbackId":"efghb2mxupongp5k",
    "recordingStatus":"ready",
    "recordingURL":"https://mdw-cdn.livepeer.monster/recordings/mnopa1c9-1775-4797-919e-40d21099d02b/index.m3u8",
    "mp4URL":"https://mdw-cdn.livepeer.com/recordings/mnopa1c9-1775-4797-919e-40d21099d02b/2021_05_04_02_00_31-source.mp4",
    {other asset object keys}
}