Start and stop recording
This guide focuses on using room composite (browser-based) recordings.
A composite recording is a single MP4 file that records all peers and their tracks (audio, video and screen share). It captures the experience that a peer has in the room and is equivalent to recordings generated from Google Meet and Zoom.
A composite recording is different from track-level recordings, which generate single file per audio/video track. To use track-level recordings, enable SFU recordings on your template.
Start recording with API
Use the server-side API to start recording for a given room (passed as room_id
in the request body).
Also see API reference.
curl --request POST 'https://api.100ms.live/v2/recordings/room/<room_id>/start' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <management_token>' \ --data-raw '{ "meeting_url" : "<meeting_url>", "resolution" : {"width": 1280, "height": 720} }'
Internally, this API launches a browser window that opens the meeting_url
of the room. This browser instance joins the room and records it, similar to what a peer would do. You can define a role for this peer to ensure the peer's tile is not visible.
meeting_url
This is a URL which lands into the room directly. You can use 100ms room links that look like:
https://<domain>.app.100ms.live/preview/<room_id>/<role>?skip_preview=true
Other supported query parameters:
skip_preview=true
: skips the preview page and directly joins the meeting with header and controls disabledskip_preview_headful=true
: skips the preview page and directly joins the meeting with header and controls enabledauth_token=token1234
: Use this to pass an auth token to authenticate the room join actionui_mode=activespeaker
: Render active speaker mode by defaultname=johndoe
: Use this to add a name for the peer
Automate start recording (Optional)
Instead of relying on peers in the room to start recording, you use room lifecycle events to automate start recording.
To do so, set up a webhook listener and act on the relevant webhook:
- Start recording for every session: Use the
session.open.success
event to start recording (with the above API) - Start recording when a particular peer joins: Use the
peer.join.success
event to start recording (with the above API)
Listen to recording status updates
Start recording is asynchronous and you can listen to status changes to the recording jobs with webhooks.
beam.started.success
event: This is sent when recording starts successfullybeam.recording.success
event: This is sent when recording ends successfullybeam.failure
event: This is sent when there is a failure
Stop recording with API
Use the server-side API to end recording for a given room (passed as room_id
in the request body).
curl --request POST 'https://api.100ms.live/v2/recordings/room/<room_id>/stop' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <management_token>'
Also see API reference.
Automatically stop recording
Note that recording automatically ends in 5 minutes after all peers (excluding Beam) have left the room.
To instantly end recording when peers have left the room, you can also chain up our APIs to run relevant business logic before stopping the recording. This ensures the video file will not have the extra 5 minutes of empty frames.
- Listen to the
peer.leave.success
webhook event - Make an API call to get peers in the session with the active room APIs: fetching the active room (session) and relevant peer info
- If Beam (bot peer that records the session) is the only peer in the room, you can end the recording with the above API
Get recording assets
There are multiple ways to get the recording assets (files). By default, recording assets are saved in 100ms storage buckets and retained up to 15 days. We recommend configuring your own storage buckets so that assets are automatically transferred and you control their retention lifecycle.
If you are relying on the 100ms storage bucket, we recommend downloading the asset from the dashboard or programmatically via the webhook/API.
Configure your own storage
100ms supports AWS S3, Google Cloud Storage and Alibaba OSS as storage buckets. These can be configured on the 100ms dashboard.
Download assets from dashboard
Recording assets can be downloaded from the 100ms dashboard. Use the sessions page to navigate to the relevant session page, which has links to the recorded assets.
Download assets via webhooks
The beam.recording.success
webhook event contains the pre-signed URL to the recording asset (in the property called recording_presigned_url
). This is a short-lived URL, that can be used to download the asset.
Fetch assets via API
You can use the recording assets REST APIs to fetch the assets:
- List recording assets for a room/session
- Generate a pre-signed URL for an asset