Skip to main content

Record a livestream

This guide provides instructions on how to interact with the recording feature of a livestream:

  • Create a stream with the record feature turned on
  • Turn on the record feature of an existing stream
  • Working with APIs
  • Interact with record feature in the dashboard

How recording works in Livepeer Studio.​

  • 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 Studio's CDN by default.

Note: If you are using OBS, set your keyframe interval to 2 for Livepeer Studio recording to work best.

About the record Parameter​

First, it’s important to understand the relationship between a Livepeer Studio 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.

Note: 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.

Interacting with Livestream Record Session​

  • Via the API
  • Via the dashboard(no code)

Recording live stream sessions with the Livepeer Studio API​

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

Create Stream​

The following creates a stream with the recording feature active.

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

Requests​

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

Response​

Returns the 201 created response with the following object:

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

Update a Stream​

The following turns on the recording feature with an existing stream. Turn recording on. All new sessions will be recorded. In progress sessions will not be recorded.

Turn on recording​

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

Request​

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

Response​

The response should return a 204 message and "record": true in the livestream object.

Turn off recording​

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

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

Response​

The response should return a 204 message and "record": false in the livestream object.

Get the recording status of a stream​

GET /stream/{id} to retrieve a stream and record value

Request​

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

Response​

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

Get the information of a session​

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

Request​

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

Reponse​

Returns a 200 OK with the following:

{
    "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.studio/recordings/mnopa1c9-1775-4797-919e-40d21099d02b/2021_05_04_02_00_31-source.mp4",
    {other asset object keys}
}

Recording settings in the Livepeer Studio Dashboard​

The easiest way to turn recording on or off for a stream is to login to the Livepeer Studio Dashboard, navigate to the
Streams page 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.