Start a cloud recording task
Updated
Starts a cloud recording task with an acquired resource ID.
https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/startAfter receiving a resource ID from acquire, call this endpoint within five minutes to start cloud recording.
Note
After calling start, check that the recording service has started successfully. See Integration best practices.
Path Parameters
The App ID of your project.
- For web page recording mode, enter the App ID for which the cloud recording service is enabled.
- For individual and composite recording modes, use the same App ID as the channel to be recorded. Ensure that the cloud recording service has been enabled for this App ID.
The resource ID obtained from the acquire endpoint.
The recording mode:
individual: Individual recording mode.mix: Composite recording mode.web: Web page recording mode.
individual | mix | webHeader Parameters
Request Body
application/json
The name of the channel to record. Must match the cname used in the acquire request.
The UID used by the cloud recording service in the channel. Must match the uid used in the acquire request.
A dynamic key used for authentication. Required if your project has enabled the App Certificate. See Token authentication for details.
Only required in individual recording and composite recording modes. Cloud recording does not support token updates, so ensure the token validity period is longer than your expected recording duration to prevent the task from exiting the channel prematurely.
Configuration for third-party cloud storage.
Third-party cloud storage platform:
1: Amazon S32: Alibaba Cloud3: Tencent Cloud5: Microsoft Azure6: Google Cloud7: Huawei Cloud8: Baidu IntelligentCloud11: S3-compatible storage. Specify the domain name inextensionParams.endpoint.
The region of the third-party cloud storage.
Note
To ensure upload success and real-time performance, the cloud storage region must match the region of the server where you initiate the request. See Third-party cloud storage regions.
The cloud storage bucket name. Must comply with the naming rules of the corresponding cloud storage service.
The access key for the third-party cloud storage.
The secret key for the third-party cloud storage.
A temporary security token issued by the cloud provider's Security Token Service (STS), granting limited access to cloud storage resources.
Currently supported only for Amazon S3 (1), Alibaba Cloud (2), and Tencent Cloud (3).
The stsToken expiration time as a Unix timestamp in seconds.
- Use Uint64 storage to avoid timestamp overflow.
- Set the longest possible validity period when applying the token. The minimum validity period is 4 hours.
- If the recording task runs longer than 1 hour, reapply a new
stsTokenevery 60 minutes and callupdateagain to refresh thestorageConfig.
The storage path prefix for recorded files. For example, setting ["directory1","directory2"] results in a file name prefix of directory1/directory2/. The total prefix length, including slashes, cannot exceed 128 characters. Supported characters: lowercase letters a-z, uppercase letters A-Z, digits 0-9.
Encryption and tagging settings applied to uploaded recording files by the cloud storage service.
The encryption mode for uploaded files. Applicable to Amazon S3 only. See the Amazon S3 documentation.
kms: KMS encryption.aes256: AES256 encryption.
Tag content applied to uploaded files. Applicable to Alibaba Cloud and Amazon S3 only.
The domain name for S3 protocol cloud storage. This field is required when you set vendor to 11.
Configuration for recorded audio and video streams. Set this object in individual and composite recording modes.
The channel profile:
0: Communication.1: Live streaming.
Must match the channel profile set in the Agora RTC SDK.
0The decryption mode, required if channel encryption is enabled in the SDK client:
0: No encryption.1: AES_128_XTS.2: AES_128_ECB.3: AES_256_XTS.4: SM4_128_ECB.5: AES_128_GCM.6: AES_256_GCM.7: AES_128_GCM2. Requires settingsecretandsalt.8: AES_256_GCM2. Requires settingsecretandsalt.
0The encryption key. Required when decryptionMode is not 0.
The encryption salt. Base64-encoded, 32 bytes. Required when decryptionMode is 7 or 8.
Maximum channel idle time, in seconds. The recording service exits after the channel is idle for longer than this value.
30[5, 2592000]The type of media stream to subscribe to:
0: Audio only.1: Video only.2: Audio and video.
2The remote video stream type to subscribe to when dual-stream mode is enabled:
0: High-quality video stream (high resolution and high bitrate).1: Low-quality video stream (low resolution and low bitrate).
0Audio UIDs to subscribe to. Use ["#allstream#"] to subscribe to all audio streams. Do not set together with unsubscribeAudioUids.
Audio streams to subscribe to. The array length cannot exceed 32. Set to ["#allstream#"] to subscribe to all UIDs. Cannot be set together with unsubscribeAudioUids.
Only applicable when streamTypes is 0 or 2. If a subscription list is set for only one media type, the service will not subscribe to the other type.
Audio UIDs not to subscribe to. Do not set together with subscribeAudioUids.
Audio streams to exclude. The service subscribes to all other UIDs. The array length cannot exceed 32. Cannot be set together with subscribeAudioUids.
Video UIDs to subscribe to. Use ["#allstream#"] to subscribe to all video streams. Do not set together with unsubscribeVideoUids.
Video streams to subscribe to. The array length cannot exceed 32. Set to ["#allstream#"] to subscribe to all UIDs. Cannot be set together with unsubscribeVideoUids.
Only applicable when streamTypes is 1 or 2. If a subscription list is set for only one media type, the service will not subscribe to the other type.
Video UIDs not to subscribe to. Do not set together with subscribeVideoUids.
Video streams to exclude. The service subscribes to all other UIDs. The array length cannot exceed 32. Cannot be set together with subscribeVideoUids.
Estimated peak number of subscribed UIDs. Required in individual recording mode.
0: 1–2 UIDs.1: 3–7 UIDs.2: 8–12 UIDs.3: 13–17 UIDs.4: 18–32 UIDs.5: 33–49 UIDs.
For example, if subscribeVideoUids is ["100","101","102"] and subscribeAudioUids is ["101","102","103"], the subscriber count is 4.
Output mode of the media stream. Only applicable in individual recording mode. See Media streaming output modes.
"default": Audio transcoding generates separate M3U8 audio and video index files."standard": Generates separate M3U8 audio and video index files, plus a merged audio-and-video index file. If VP8 encoding is used on the Web client, a merged MPD file is generated instead."original": Original encoding mode for individual non-transcoding audio recording. Only takes effect whenstreamTypesis0. No transcoding occurs; generates an M3U8 audio index file.
defaultAudio output sampling rate, bitrate, encoding mode, and channel count. Only applicable in composite recording mode.
0: 48 kHz, music encoding, mono, ~48 Kbps.1: 48 kHz, music encoding, mono, ~128 Kbps.2: 48 kHz, music encoding, stereo, ~192 Kbps.
0Transcoded video output settings. Only applicable in composite recording mode. See Set the video profile.
The UID of the large video window in vertical layout. Must be an integer from 1 to (2³²−1), cannot be 0. Only required in vertical layout.
Composite video layout:
0: Floating layout. The first user to join fills the entire canvas; other users appear as small windows arranged horizontally from bottom to top, up to 4 rows of 4 windows (17 windows total).1: Adaptive layout. All user windows are equal in size, automatically adjusted based on user count. Supports up to 17 windows.2: Vertical layout. ThemaxResolutionUiduser appears in a large window on the left; other users are arranged in up to two columns on the right, 8 windows per column (17 windows total).3: Custom layout. Configure positions usinglayoutConfig.
0Canvas background color as an RGB hex string (e.g., "#FF0000" for red).
#000000URL of the canvas background image. Displayed in cropped mode: the image is scaled proportionally until the canvas is filled, and excess edges are cropped.
URL of the default background image shown when a user stops sending video for more than 3.5 seconds. Overridden if a per-UID background image is set in backgroundConfig.
Per-user screen layout settings for custom layout. Supports up to 17 users. Only applicable when mixedVideoLayout is 3.
17The UID of the user assigned to this layout region. If not specified, layout regions are assigned in the order users join the channel.
Horizontal coordinate of the region's upper-left corner as a relative value (6 decimal places). 0.0 is the far left, 1.0 is the far right.
[0, 1]Vertical coordinate of the region's upper-left corner as a relative value (6 decimal places). 0.0 is the top, 1.0 is the bottom.
[0, 1]Transparency of the user's video window. 0.0 is fully transparent, 1.0 is fully opaque.
1[0, 1]Display mode for the user's video window:
0: Cropped mode. The window is filled; video is scaled proportionally and cropped at the edges if the aspect ratio differs.1: Fit mode. All video content is visible; the video is scaled proportionally and black borders may appear.
0Per-user background image settings.
The UID of the user.
The URL of the user's background image, shown when the user stops sending video for more than 3.5 seconds. Supports HTTPS, JPG and BMP formats, maximum 6 MB. Settings take effect only after the image is successfully downloaded.
Display mode for the background image:
0: Cropped mode. The window is filled; image is scaled proportionally and cropped at the edges if the aspect ratio differs.1: Fit mode. All image content is visible; the image is scaled proportionally and black borders may appear.
0Configuration for recorded files.
Note
Cannot be set when taking screenshots only. Required in all other cases including individual recording (without transcoding, with transcoding, or simultaneous recording and screenshots), composite recording, and web page recording.
The type of recorded video files:
"hls": M3U8 and TS files."mp4": MP4 files.
In individual recording mode (non-screenshot-only), use the default value. In composite recording and web page recording modes, set to ["hls","mp4"] to generate MP4 files. Setting to ["mp4"] alone causes an error. In composite recording mode, a new MP4 file is created when the current file exceeds ~2 hours or ~2 GB. In web page recording mode, a new MP4 file is created when the current file exceeds maxVideoDuration.
["hls"]hls | mp4Screenshot capture settings. Only applicable in individual recording mode.
- Screenshots can be taken separately or simultaneously with recording. See Capture screenshots.
- If the recording service or the recording upload service malfunctions, the screenshot may fail. Recording is not affected if the screenshot malfunctions.
streamTypesmust be1or2. IfsubscribeAudioUidsis set,subscribeVideoUidsmust also be set.
Screenshot file format. Currently only jpg is supported.
jpgConfiguration for extended services. Only applicable in web page recording mode.
Error handling policy. Currently only "error_abort" is supported: when an error occurs in an extension service, all other non-extension services (such as stream subscription) also stop.
error_abortName of the extension service:
"web_recorder_service": Web page recording."rtmp_publish_service": Push web page recording to CDN.
Error handling policy within the extension service:
"error_abort": Default for web page recording. Stops other extension services when this service encounters an error."error_ignore": Default for CDN push. Other extension services are unaffected when this service encounters an error.
Errors in the page recording service will cause CDN push to fail, but errors in the CDN push service do not affect page recording
Specific configuration for the extension service.
The URL of the page to record.
Audio output sampling rate, bitrate, encoding mode, and channel count:
0: 48 kHz, music encoding, mono, ~48 Kbps.1: 48 kHz, music encoding, mono, ~128 Kbps.2: 48 kHz, music encoding, stereo, ~192 Kbps.
Output video width in pixels. videoWidth × videoHeight must not exceed 1920 × 1080.
Output video height in pixels. videoWidth × videoHeight must not exceed 1920 × 1080.
Output video bitrate in Kbps.
Maximum MP4 file duration in minutes. A new MP4 file is created when the current file exceeds this duration.
120[30, 240]Whether to start the recording in a paused state:
true: The service opens and renders the page but does not generate slice files. Callupdatewithonhold: falseto resume.false: Recording starts immediately.
To pause and resume reliably, wait for each update response before sending the next one.
falseCDN output settings for web page recording push.
CDN address to which the stream is pushed.
Container format, such as mp4, mp3, m4a, or aac.
Audio sampling rate in Hz.
Audio bitrate in Kbps.
Number of audio channels.
Response
-
If the returned status code is
200, the request was successful. -
If the returned status code is not
200, the request failed. See Response status codes for troubleshooting.
Response Body
application/json
Response schema
200The request succeeded. To confirm that the recording service started successfully, follow the integration best practices.
The cloud recording resource ID. Valid for five minutes; re-request from acquire if expired.
The resource ID used by cloud recording.
The recording ID. Uniquely identifies a recording session. Generated after the cloud recording service starts successfully.
The recording ID, identifying the current recording session.
The name of the channel to be recorded.
The name of the channel being recorded.
The UID used by the cloud recording service in the RTC channel.
defaultThe request failed. If the HTTP status code is not 200, see the Cloud Recording response status codes for troubleshooting.
Response
See Page load timeout detection.
Response example
{
"code": 7,
"reason": "already started"
}
Request examples
curl --request POST \
--url https://api.sd-rtn.com/v1/apps/{appid}/cloud_recording/resourceid/{resourceid}/mode/{mode}/start \
--header 'Authorization: Basic <credentials>' \
--header 'Content-Type: application/json' \
--data '{
"cname": "<your_channel_name>",
"uid": "527841",
"clientRequest": {
"recordingConfig": {
"channelType": 1,
"streamTypes": 2,
"streamMode": "default",
"videoStreamType": 0,
"maxIdleTime": 30,
"subscribeAudioUids": ["123", "456"],
"subscribeVideoUids": ["123", "456"],
"subscribeUidGroup": 0
},
"recordingFileConfig": {
"avFileType": ["hls"]
},
"storageConfig": {
"vendor": 2,
"region": 3,
"bucket": "xxxxx",
"accessKey": "xxxxx",
"secretKey": "xxxxx",
"fileNamePrefix": ["directory1", "directory2"]
}
}
}'
Response example
{ "cname": "string", "uid": "string", "resourceId": "string", "sid": "string"}