Live Platform API v1
Live Platform API
Live Platform API
Version 1

Overview

Copy link

Cloud recording is a feature that allows you to record the host view of a live event. You can download the recorded file from Sendbird Dashboard or copy files from Sendbird's S3 storage to your own S3 storage in the same region. You can also save cloud recordings directly to your S3 storage whenever they're created.

To use this feature, you need to activate the feature on the dashboard first. For a detailed guide, refer to Activate cloud recording.

Note: If the recorded file is saved directly to your own S3 storage, it can't be downloaded or copied from Sendbird.


Cloud recording status

Copy link
StatusDescription

ready

Indicates that the recording is ready to take place as soon as the host starts a live event.

recording

Indicates that the the recording of a live event is taking place.

paused

Indicates that a recording was paused.

uploading

Indicates that the recording file is being uploaded to the cloud.

completed

Indicates that the recording was successfully completed and ready for download from the Sendbird Dashboard.

failed

Indicates that the recording has encountered an error and has not completed successfully.

Resource representation

Copy link

The following tables show the list of properties in a cloud recording resource.

Property nameTypeDescription

recording_id

string

The unique ID of the cloud recording file.

*The recording_id can be found by retrieving a live event or retrieving a list of live events. In its response, cloud_recordings[] object will be returned with the recording_id information.

target_event_type

string

The type of event to record. Valid value is live.

live_event_id

string

A unique ID of the live event.

status

string

The status of cloud recording. Valid values are ready,recording,paused,uploading,completed, and failed. The cloud recording status table explains each status in detail.

started_at

long

The timestamp of when the recording for a live event was started, in Unix milliseconds.

stopped_at

long

The timestamp of when the recording for a live event was stopped, in Unix milliseconds.

duration

int

The total length of recording for a live event, measured in milliseconds.

byte_size

int

The total size of recording file, measured in byte.

media_type

string

The type of media that is recorded. Valid value is all.


Actions

Copy link
  • API endpoints are relative to the base URL allocated to your application. In this page, the /cloud-recordings endpoint refers to https://api-{application_id}.calls.sendbird.com/v1/cloud-recordings.

Note: To get your application ID, sign in to your dashboard, go to the Settings > Application > General, and then check the Application ID.

  • It's recommended that the parameter values such as {recording_id} in API URLs be URL encoded.

List of actions

Copy link
ActionHTTP request

Copy a cloud recording

POST /cloud-recordings/{recording_id}/copy
Copies a cloud recording file to your S3 storage.


Activate cloud recording

Copy link

When the feature is turned on, each live event in the application is recorded, uploaded, and you can download the recorded file from the dashboard. You can also copy the recorded file to your AWS storage when the files are uploaded to the Sendbird server.

To use the cloud recording feature, contact our support team. You can go to Settings > Live > Features on the dashboard to see if the feature is available for your Sendbird application.


Record a live event

Copy link

When the cloud recording feature is turned on, the host's media stream, including live events using RTMP (Real-Time Messaging Protocol) stream, is recorded. Recording starts when the host has successfully entered and started the live event. If there isn't any host's media stream during the Live status, such as the host exiting the live event without ending it, recording pauses. When the host has ended and exited the live event, recording ends and it is processed for download.

If recording pauses during the live event, the duration of the recorded file may be shorter than that of the live event.

Relationship between live event status and recording status

Copy link
Live event statusRecording statusNote

Upcoming

Waiting

Recording can start when the host enters and starts the live event.

Open

Waiting

Recording can start when the host starts the live event.

Live

Recording,
Paused

-Recording indicates that the host is streaming.

When the live event is in the Live status, its recording can be either in the Recording or Paused status because the live event is recorded only when the host is streaming.

-Paused indicates that the host's stream is ended while the live event isn't ended. When the host's media stream starts again, recording continues and the status changes to Recording.

Ended

Uploading,
Completed,
Failed

Once the live event has ended, the recording status changes to Uploading to indicate that the recording is being uploaded. After it's uploaded successfully, the status changes to Completed. When the recording has a problem or can't be uploaded, the status changes to Failed.


Download the recorded file

Copy link

Once the file has been uploaded successfully, you can download it from the dashboard. To download the file, click the live event of the recording you would like to download on Live events. You can download the file immediately or later by using the link, which stays valid for 24 hours and can be reissued.

File spec and retention

Copy link

Recordings are processed to .mp4 files in default resolution of 1280 x 720 with 30 fps. Each file can be downloaded for two weeks from the date the recording upload has completed.

Copy the file to your S3 storage

Copy link

If you would like to copy the file to your AWS S3 storage, you need to check the file's status on the dashboard before you make a request. To make an API request to copy the file, refer to Copy cloud recording.