The Dolby.io Communications APIs let you record conference media, including shared files, screens, and participant audiovisuals. It is beneficial for distributing recordings among absent participants, broadcasting, archiving important meetings, and post-processing.
Recordings can be divided into the following types that impact cost calculation based on your target use case:
Video mix recording: Composition of all media streams sent from participants in the form of a 1080p/30fps MP4 recording file. You can also create multiple video mixes of various resolutions or layout logic.
Audio mix recording: Mix of audio streams sent from participants in the form of an MP3 file.
Individual participant audio recording: Individual participants' audio recordings in separate MP3 files. This is also known as call leg recording. The Dolby.io platform creates individual audio recordings only for Dolby Voice conferences when the Generate audio recordings for each participant option and MP3 or BOTH recording format is selected in the dashboard. This recording format is for advanced use cases where an individual participant’s audio track is important. An example use case is a post-processing or analysis of an individual participant’s speech.
Raw recording: Raw recording is always generated whenever a conference is recorded, even when the liveRecording option is disabled. The raw recording is not downloadable; it is only available via the replay method in the client SDKs. To create a downloadable file out of raw recording, you can use the Remix REST API.
The recording types depend on the selected recording format and the liveRecording setting. You can select the preferred recording format through conference creation REST API or in the Dolby.io dashboard. However, the REST API setting always takes precedence. The following table lists all available formats and their meaning:
|Individual participant recording
|Video mix recording
|Audio mix recording
|Audio and video
|Generated, contains only voice and screen share audio archives
|Generated, contains only voice and screen share audio archives
The liveRecording property is a conference creation option that indicates whether you wish to receive a downloadable archive when your recording becomes available. If the liveRecording is set to false, only raw recording is generated and it is not downloadable. Setting liveRecording to false is useful to reduce the cost if your use case does not require all conferences to be recorded in a downloadable format.
Enabling the liveRecording property triggers using a mixer that is a service component responsible for generating composited video recording. When you enable liveRecording and request an MP4 or BOTH recording format, the mixer joins a conference upon recording start as a special participant type. The Client SDK may see such a participant appearing in the participant list indicating there's a mixer listening to the conference in real time.
To record a conference, use the Recording REST APIs that let your application start and stop a recording, as well as specify a custom layout URL. You can initiate and stop recording multiple times during a conference, as well as start recording multiple times using different mixIds. However, when liveRecording option is disabled, multiple simultaneous recording operations for a single conference are not supported. To customize the recording configuration per conference, use the conference creation API.
The client SDKs can start and stop recording and be notified about the recording status change. If you want to control recording from the client side, use the Enhanced Conference Access Control feature so you can control which client can perform recording operations.
Dolby.io Communications APIs platform allows downloading the recorded files in three ways; you can either use webhooks, REST APIs, or download recordings from the dashboard. However, the platform is not designed for distributing files to end-users. To deliver recordings to end-users, you need to download recordings from your own storage and distribute them from your content distribution platform.
During a conference, you can initiate and stop recording multiple times. Upon each recording stop, a recording file becomes available and the platform triggers the Recordings.Available webhook that lets you download the recording file. The webhook contains a temporary URL that expires in ten minutes. If the recording is not downloaded within ten minutes, you will not be able to access the recording using the original URL included in the webhook. If your application is enabled with secured service provisioning, you may receive pre-signed URLs. If you do not receive the webhook event, or the URL has expired, you can use the Monitor API to retrieve the pre-signed URL.
If you subscribed to the deprecated Recording.MP4.Available webhook, your application will continue to work and receive download URLs from this webhooks. However, the deprecated webhook will not carry additional information, such as multi-layout mixed recording or step recordings. We recommend migrating to the Recordings.Available webhook as soon as you can.
You can also retrieve download URLs using the Monitor API. Use the Get recording details and Get the recordings of a specific conference REST APIs to access the recording details and receive pre-signed URLs to download the split recordings, audio recordings, and video recordings of one or more conferences.
If you use the deprecated v1 Monitor APIs to retrieve recordings, your application will continue to work. However, the deprecated v1 Monitor API will not provide additional information, such as multi-layout mixed recording or step recordings. We recommend migrating to the v2 API as soon as you can.
Only mixed and merged recordings can be downloaded from the dashboard. To download all types of recordings, use Monitor APIs or webhooks instead. To download your recording from the Dolby.io dashboard, follow these steps:
Select the Login link located in the upper right corner of the Dolby.io page. Log in using your email and password.
In the dashboard, select your application from the APPLICATIONS category located on the left-side menu.
Select the Monitor tab at the top of the page.
Use the conference alias, ID, or date to search for the recorded conference.
In the Recording section, click the Download button.
Merged mixed recording archives are stored for a maximum of 180 days. The individual participant recording files are only retained for 15 days. The Monitor API will only return recording data for recordings that are available to download.
If you did not use the liveRecording option when a conference was created and you recorded the conference, you can use the Remix API to generate downloadable MPx files after the conference is ended. Multiple simultaneous remix operations for a single conference are not supported. The recording mechanism that uses the Remix REST API is a time-consuming process and will take as long as the recorded duration to complete.
The mixer layout application is a Web application loaded by the mixer during recording sessions. Dolby.io Communications APIs offer a default mixer layout, which depends on the shared media:
- When participants only use microphones during a conference and do not share any other media, the recording contains only a blank page with participants' avatars.
- When participants use cameras and microphones but do not share any additional media, the recording contains the participant's video tiles (full-screen, half-screen, or otherwise, depending on the number of participants).
- When participants use the screen share function or share files during a conference, the recording contains the shared media in full-screen mode. When a presenter additionally shares a video from a camera, the video is visible as a thumbnail in the corner of a screen.
If you prefer to use a different layout, you can create your own layout and use it for recording. For more information, see the Creating a Custom Mixer Layout Application guide.
The layoutUrl REST API parameter overrides the dashboard-configured layout URL but is disregarded when liveRecording is set to false or for MP3-only recordings. The parameter sets a custom name, aiding in the identification of API calls, error messages, and webhooks. The parameter enables a flexible use of custom mixer layouts for recording, streaming, or remixing tasks. By calling the Recording API start recording multiple times with varying URLs and frame sizes, the system generates mixed recordings based on your input.
Upon conference termination, the individual recording files are automatically merged into one. If you record a conference multiple times using multiple layouts, then each layout will generate its own merged recording file. For advanced post-processing of recording files, use Transcode API.
Updated 7 months ago