#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 parentstream
. Thesession
parentId
value is the same as thestream
id
value. When you set therecord
value of the parentstream
, each newsession
adopts that value.
On a stream
object.
record: true
means that each newsession
is recorded.record: false
means that each newsession
is not recorded.
On a session
object, the record
value is read-only.
record: true
means that thesession
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 thesession
. This string is also used to form the playback URL for the recordedsession
.parentId
: Equivalent to theid
of the parentstream
object.createdAt
: This number is the timestamp when the live streamsession
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 streamsession
is over, this number equates to the length of the live streamsession
and recording.recordingStatus
: This boolean appears only ifrecord
istrue
, and it is eitherready
when the recorded live stream is available for playback orwaiting
while the livestream is still active or just recently completed.recordingUrl
: This string appears only ifrecord
istrue
and whenrecordingStatus
changes toready
. It’s value is the .m3u8 URL to stream the recorded session.mp4Url
: This string appears only ifrecord
istrue
and whenrecordingStatus
changes toready
. 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}}