Record a live stream session

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 recording to work best.

The easiest way to turn recording on or off for a stream is to login to the Livepeer.com Dashboard, navigate to the Streams page ( livepeer.com/dashboard/streams) and click on a stream name. On the stream detail page, you can toggle the recording setting or use the Actions button in the top right hand corner and select Enable/Disable recording. All new sessions will adopt the updated recording setting, but changing the settings will not change the recording preference for any active sessions.

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.

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.

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

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.

• 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.

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}
}