Cloud Recording
  • Introduction
  • Release notes
  • Getting started
  • Guides
    • Single-stream recording
    • Mixed-stream recording
    • Set mixed-stream layout
    • Multi-sector recording (Whiteboard)
    • Capture screenshots
  • API reference
    • API overview
    • Accessing Server APIs
    • Start recording
    • Stop recording
    • Update the mixed-stream layout
    • Update the whiteboard
    • Query recording status
    • Query the recording task list
    • Pause recording
    • Resume recording
    • Callback of the recording status
    • API testing with Postman
  • Error codes
  • FAQ

Start recording

Last updated:2022-04-14 15:12

Description

Starts cloud recording.

After you successfully call the StartRecord method, the Cloud Recording will record the audio and video streams and whiteboards in the room based on the specified recording parameters.

Each recording task may last up to 24 hours. When the recording duration reaches the maximum, the recording task automatically ends.

Request method and endpoint

  • Request method: POST
  • Request endpoint: https://cloudrecord-api.zego.im/?Action=StartRecord
  • Transmission protocol: HTTPS
  • Rate limit: 50 requests/second (testing environment: 20 requests/second)

Request parameters

Listed below are the parameters specific to this request. For the list of public request parameters, see Accessing Server APIs - Public parameters.

Parameter Type Required Description
RoomId
String
Yes
Room ID.
RecordInputParams
Object
Yes
Recording task input parameters.
For details, see RecordInputParams member parameters.
RecordOutputParams
Object
No
Recording task output parameters.
For details, see RecordOutputParams member parameters.
StorageParams
Object
Yes
Recording task storage parameters.
For details, see StorageParams member parameters.
If this parameter is not specified, the storage settings provided when the Cloud Recording service is enabled will be used.

Listed below are RecordInputParams member parameters.

Parameter Type Required Description
RecordMode
Int
Yes
Recording mode.
  • 1: single-stream recording
  • 2: mixed-stream recording
StreamType
Int
No
Recording type of a media stream. This parameter is valid only for audio or video streams. For whiteboards, only video files will be recorded.
  • 1: only audio files
  • 2: only video files
  • 3 (default value): combined audio and video files
  • 4: separate audio and video files
RecordStreamList
Array of Object
No
List of streams to be recorded. This parameter is valid only in single-stream recording mode.
For details, see RecordStreamList member parameters.
If the parameter is not specified or set to an empty list, all streams in the room will be recorded by default.
FillBlank
Bool
No
Whether to automatically perform supplementary recording of blank screens after the streaming of a user is interrupted.
  • true: yes. Upon interruption, the video recording pauses at the last frame (by default) or the background image of the stream is displayed. When the user resumes the streaming with the same stream ID, the recording resumes and data will be written into the same recording files.
  • false (default value): no. When the user resumes the streaming, a new recording file is generated.
There are two possible occasions for supplementary recording of blank screens:
  • Cloud recording automatically stops when the duration of no stream in the room reaches the maximum. For details, see MaxIdleTime.
  • The user proactively stops cloud recording.
For details about the background images of streams, see DefaultMixStreamBackgroundImage and BackgroundImage.
FillFrame
Object
No
Settings for filling in screens after the camera is turned off while the audio streaming continues. This parameter is valid only in mixed-stream recording mode.
For details, see FillFrame member parameters.
RecordMuteAudio
Int
No
Whether to record audio frames in mute mode. This parameter is valid only in the following scenarios: a single stream is recorded; only audio files are recorded and they are stored in MP3 format.
  • 1 (default value): yes
  • 2: no
RecordMuteAudioSplitThreshold
Int
No
Mute time threshold for automatically split recording files, in seconds.
When the mute duration of a stream reaches this threshold during the recording, a new recording file will be generated.
This parameter is valid only in the following scenarios: a single stream is recorded; only audio files are recorded; the recording file is stored in MP3 mode and RecordMuteAudio is set to 2.
If this parameter is set to 0, a separate recording file is generated immediately when a stream is muted. If this parameter is set to 0 or a negative value, the recording file will not be split.
HasWhiteboard
Bool
No
Whether to record a whiteboard.
  • true: yes
  • false (default value): no
If this parameter is set to true, the Whiteboard parameter is required.
Whiteboard
Array of Object
No
Whiteboard parameter, which is required when HasWhiteboard is set to true.
For details, see Whiteboard member parameters.
MaxIdleTime
Int
No
Maximum duration with no stream or whiteboard after which cloud recording automatically stops, in seconds. The default value is 30. The value must be greater or equal to 5, and less than or equal to 86400 (24 hours).
Note: This parameter is valid only when there is no stream or whiteboard in the room.
MaxRecordTime
Int
No
Maximum duration of a recording task. Recording automatically stops when the duration reaches the maximum, in seconds. The default value is 86400. The value must be greater or equal to 300 and less than or equal to 86400 (24 hours).
MixConfig
Object
No
Mixed-stream settings. This parameter is required when RecordMode is set to 2.
For details, see MixConfig member parameters.
  1. FillBlank and MaxIdleTime have different application scopes.
  • FillBlank: applies to the stream. Assume that FillBlank is set to true. When the streaming is interrupted, the system supplements blank screens as long as the recording task is still ongoing. In this case, the interrupted streaming status will not affect the judgment of whether there is a stream in the room.
  • MaxIdleTime: applies to the recording task. When the duration with no stream in a room exceeds the maximum specified by MaxIdleTime, the recording task ends.
  1. In mixed-stream recording mode, when StreamType is 1, only audio files are recorded and the whiteboards are not.

Listed below are RecordStreamList member parameters.

Parameter Type Required Description
StreamId
String
Yes
ID of a stream to be recorded.

Listed below are FillFrame member parameters.

Parameter Type Required Description
FrameFillMode
Int
No
Screen filling mode.
  • 1 (default value): Fill in the last frame.
  • 2: Fill in a frame of the specified color.
  • 3: Do not fill in any frame.
FrameFillColor
Int
No
Color of the frame to be filled in. This parameter is valid only when FrameFillMode is set to 2. The default color is black. The first three bytes specify the RGB color code and the fourth byte is fixed at 0, that is, 0xRRGGBB00.

Pay attention to the following information about FrameFillMode:

  • For the mini program client, this parameter can only be set to 1.
  • For the web client, this parameter can only be set to 2 and the color of the frame to be filled in can only be black.

Listed below are Whiteboard member parameters.

Parameter Type Required Description
HorizontalRatio
Int
Yes
Width of the original whiteboard.
VerticalRatio
Int
Yes
Height of the original whiteboard.
Width
Int
No
Resolution width of the output whiteboard video in single-recording mode. The default value is 1280.
Height
Int
No
Resolution height of the output whiteboard video in single-recording mode. The default value is 1280.
WhiteboardId
String
No
Whiteboard ID.
  • If a whiteboard must be recorded immediately after the start of recording, this parameter is required.
  • If no whiteboard needs to be recorded immediately after the start of recording, this parameter is not required and the whiteboard ID can be specified later when necessary by calling the Update the whiteboard method.
IsPPTAnimation
Bool
No
Whether to record an animated PowerPoint file, including the animation effects and videos.
  • true: yes
  • false (default value): no
PPTAnimationFps
Int
No
Frame rate for recording an animated PowerPoint file. The value ranges from 1 to 30 and the default value is 15.

Animated PowerPoint file recording will be charged separately. To enable this function, contact ZEGOCLOUD business personnel. If this function is not enabled, the settings of IsPPTAnimation and PPTAnimationFps will be invalid.

Listed below are MixConfig member parameters.

Parameter Type Required Description
MixMode
Int
No
Layout.
  • 1: customized layout. In this layout, MixInputList is required.
  • 2 (default value): grid layout
  • 3: horizontal layout
  • 4: vertical layout
  • 5: floating layout
MixInputList
Array of Object
No
Customized layout parameters.
For details, see MixInputList member parameters.
MixOutputStreamId
String
Yes
Stream ID in mixed-stream recording mode, which will be used as a part of OutputFileRule.
MixOutputVideoConfig
Object
No
Output video parameters.
For details, see MixOutputVideoConfig member parameters.
MixOutputAudioConfig
Object
No
Output audio parameters.
For details, see MixOutputAudioConfig member parameters.
MixOutputBackgroundColor
Int
No
Recording background color, which is black by default. The first three bytes specify the RGB color code and the fourth byte is fixed at 0, that is, 0xRRGGBB00.
MixOutputBackgroundImage
String
No
URL of the background image of a video canvas.
  • We recommend that the resolution of the background image be the same as the output video resolution. If the resolutions are different, the background image will be stretched or compressed to fully fill in the screen.
  • The background image can be in JPG or PNG format. The maximum image size is 5 MB. If the background image download fails, the setting will be invalid.
  • HTTP and HTTPS URLs are supported.
MixMaxResolutionStreamId
String
No
Stream ID of the large screen when MixMode is set to 3, 4, or 5.
MixOutputWatermarkImage
String
No
URL of the watermark image.
  • We recommend that the resolution of the watermark image be the same as the output video resolution. If the resolutions are different, the watermark image will be stretched or compressed to fully fill in the screen.
  • The watermark image can be in PNG format and the background must be transparent. Otherwise, the screens to be recorded will be blocked. The maximum image size is 5 MB. If the background image download fails, the setting will be invalid.
  • HTTP and HTTPS URLs are supported.
MixOutputWatermarkImageConfig
Object
No
Watermark layout configuration.
See MixOutputWatermarkImageConfig member list.
DefaultMixStreamBackgroundImage
String
No
URL of the default background image of a stream. Assume that FillBlank is true. When the specified stream does not exist or the streaming is interrupted, the background image specified by this parameter is displayed.
  • For a customized layout, if BackgroundImage is specified for a stream ID, the specified background image is displayed preferentially.
  • If the resolution of the background image is different from that of the stream images, the background image will be stretched or compressed to fill in the screen.
  • The background image can be in JPG or PNG format. The maximum image size is 5 MB. If the background image download fails, the setting will be invalid.
  • HTTP and HTTPS URLs are supported.

Listed below are MixInputList member parameters.

Parameter Type Required Description
StreamId
String
No
ID of the stream to be displayed on a screen. If this parameter is not set, the stream will be matched based on its order to enter the room.
ViewType
Int
No
Type of content to be displayed on a screen.
  • 1 (default value): audio and video
  • 2: whiteboard
The value 2 is valid only when whiteboard recording is enabled. This parameter can be set to 2 for only one screen. Otherwise, an error will be returned.
Top
Int
Yes
Y-axis coordinate of the upper left corner of a screen on the canvas. The value ranges from 0 to 1920 and can't exceed the value of Bottom or the canvas height.
Left
Int
Yes
X-axis coordinate of the upper left corner of a screen on the canvas. The value ranges from 0 to 1920 and can't exceed the value of Right or the canvas width.
Bottom
Int
Yes
Y-axis coordinate of the lower right corner of a screen on the canvas. The value ranges from 0 to 1920 and can't exceed the canvas height.
Right
Int
Yes
X-axis coordinate of the lower right corner of a screen on the canvas. The value ranges from 0 to 1920 and can't exceed the canvas width.
Layer
Int
Yes
Layer priority of a screen. When an overlap occurs between two screens, the one with a larger value of Layer will be displayed on top.
FillMode
Int
No
Filling mode when the aspect ratio of a video stream is different from that of the screen.
  • 1 (default value): cropping. In this mode, the video stream is scaled equally to fully fill in the screen and the content outside the screen will be cropped.
  • 2: scaling. In this mode, the video screen is scaled equally to fill in the screen and black borders will be filled in along all sides.
BackgroundImage
String
No
URL of the background image of a stream. This parameter is valid only when StreamId is set.
When the specified stream specified for a customized layout does not exist or the streaming is interrupted, the background image specified by this parameter is displayed.
  • We recommend that the resolution of the background image be the same as the output video resolution. If the resolutions are different, the background image will be stretched or compressed to fully fill in the screen.
  • The background image can be in JPG or PNG format. The maximum image size is 5 MB. If the background image download fails, the setting will be invalid.
  • HTTP and HTTPS URLs are supported.

Listed below are MixOutputVideoConfig member parameters.

Parameter Type Required Description
Width
Int
Yes
Resolution width of the output video, in pixels.
The value must be less than or equal to 1920 and the product of the values of Width and Height can't exceed 1920 x 1080. Otherwise, an error message will be returned.
Height
Int
Yes
Resolution height of the output video, in pixels.
The value must be less than or equal to 1920 and the product of the values of Width and Height can't exceed 1920 x 1080. Otherwise, an error message will be returned.
Fps
Int
Yes
Frame rate of the output video. The value ranges from 5 to 30 and the default value is 15.
Bitrate
Int
Yes
Bit rate of the output video, in bps. If you want to set the bit rate to 1.5 Mbps, this parameter must be set to 1500000, that is, 1500 x 1000.

Listed below are MixOutputAudioConfig member parameters.

Parameter Type Required Description
Bitrate
Int
No
Audio bit rate, which is 48000 bps by default.

Listed below are MixOutputWatermarkImageConfig member parameters.

Parameter Type Required Description
Left
Int
Yes
The x-axis coordinate of the upper left corner of the screen on the canvas, the value range is [0, 1920], which cannot exceed the value of Right and the width of the canvas.
Top
Int
Yes
The y-axis coordinate of the upper left corner of the screen on the canvas, the value range is [0, 1920], which cannot exceed the value of Bottom and the height of the canvas.
Right
Int
Yes
The x-axis coordinate of the lower right corner of the screen on the canvas, the value range is [0, 1920], which cannot exceed the width of the canvas.
Bottom
Int
Yes
The y-axis coordinate of the lower right corner of the screen on the canvas, the value range is [0, 1920], and cannot exceed the height of the canvas.

Listed below are RecordOutputParams member parameters.

Parameter Type Required Description
OutputFileFormat
String
No
Format of an output recording file. The options are mp4, flv, hls, jpg, and mp3, and the default value is mp4. If this parameter is set to mp4 or flv and StreamType is set as 4, an audio file in AAC format will be generated.
OutputFolder
String
No
Output directory of a recording file stored on a third-party cloud storage platform. The root directory is used by default.
OutputFileRule
Int
No
Naming rule of a recording file. The default value and the only value that is supported currently is 1. That is, the naming rules for different recording modes are as follows:
  • Single-stream recording mode: TaskId_RoomId_UserId_StreamId_Type_UTC
  • Mixed-stream recording mode: Taskid_RoomId_MixOutputStreamId_Type_UTC
  • Single-stream recording with whiteboard: Taskid_Roomid_whiteboard_Type_UTC
The meanings of file name fields are as follows:
  • Type: file type, which can be V (video), A (audio), and VA (video and audio).
  • UTC: UTC time when recording starts for the file. The time zone is UTC+0 and the time is composed of year, month, day, hour, minute, second, and millisecond.
  • MixOutputStreamId: same as that specified in MixConfig.
  • whiteboard: fixed part in the file name
SnapshotInterval
Int
No
Screen capture interval, in seconds. This parameter is valid when the recording file is generated in JPG format. The value ranges from 5 to 3600 and the default value is 10.
CallbackUrl
String
No
Customized callback URL. The callback URL configured when the service is enabled will be used if this parameter is not set. HTTP and HTTPS URLs are supported.

Listed below are StorageParams member parameters.

Parameter Type Required Description
Vendor
Int
Yes
Recording file storage service provider. Currently, the following service providers are supported:
  • 1: Amazon S3
  • 2: Alibaba Cloud OSS
  • 3: Tencent Cloud COS
  • 4: Qiniu Cloud KODO
  • 5: Alibaba Cloud VOD
  • 6: Tencent Cloud VOD
  • 7: Huawei Cloud OBS
Region
String
No
Region.
Bucket
String
No
Bucket.
AccessKeyId
String
No
Access key. We recommend that you provide an access key with the write-only permission.
AccessKeySecret
String
No
Secret key.
AlibabaCloudVodParams
Object
No
Storage information when Alibaba Cloud VOD is used.
For details, see AlibabaCloudVodParams member parameters.
TencentCloudVodParams
Object
No
Storage information when Tencent Cloud VOD is used.
For details, see TencentCloudVodParams member parameters.
  • When Vendor is set to 1 to 4 or 7, Region, Bucket, AccessKeyId, and AccessKeySecret are required.
  • When Vendor is set to 5, AlibabaCloudVodParams is required. Currently, only MP4 and FLV files can be uploaded.
  • When Vendor is set to 6, TencentCloudVodParams is required. Currently, only MP4 and FLV files can be uploaded.

Listed below are AlibabaCloudVodParams member parameters.

Parameter Type Required Description
Region
String
Yes
Region, such as cn-shanghai.
AccessKeyId
String
Yes
Access key.
AccessKeySecret
String
Yes
Secret key. We recommend that you provide an access key with the write-only permission.
Title
String
Yes
Video name.
StorageLocation
String
Yes
Fixed parameter.

Listed below are TencentCloudVodParams member parameters.

Parameter Type Required Description
SecretId
String
Yes
Access key.
SecretKey
String
Yes
Secret key. We recommend that you provide an access key with the write-only permission.
Region
String
Yes
Region, such as ap-shanghai.
SubAppId
Int64
No
Sub-application ID.

Sample request

  • Request URL
    https://cloudrecord-api.zego.im/?Action=StartRecord
    &AppId=1234567890
    &SignatureNonce=15215528852396
    &Timestamp=1234567890
    &Signature=7a2c0f11145fb760d607a07b54825013
    &SignatureVersion=2.0
    &IsTest=false
  • Request message body

The following is an example of the request message body when Amazon S3, Alibaba Cloud OSS, Tencent Cloud COS, Qiniu Cloud KODO, or Huawei Cloud OBS is used:

{
    "RoomId": "xxxx",
    "RecordInputParams": {
        "RecordMode": 1,
        "StreamType": 3,
        "MaxIdleTime": 60
    },
    "RecordOutputParams": {
        "OutputFileFormat": "mp4",
        "OutputFolder": "record/"
    },
    "StorageParams": {
        "Vendor": 2,
        "Region": "oss-xxxx",
        "Bucket": "xxxx",
        "AccessKeyId": "xxxx",
        "AccessKeySecret": "xxxx"
    }
}

The following is an example of the request message body when Alibaba Cloud VOD is used:

{
    "RoomId": "xxxx",
    "RecordInputParams": {
        "RecordMode": 1,
        "StreamType": 3,
        "MaxIdleTime": 60
    },
    "RecordOutputParams": {
        "OutputFileFormat": "mp4",
        "OutputFolder": "record/"
    },
    "StorageParams": {
        "Vendor": 5,
        "Region": "",
        "Bucket": "",
        "AccessKeyId": "",
        "AccessKeySecret": "",
        "AlibabaCloudVodParams":{
            "Region": "cn-xxxxx",
            "AccessKeyId": "xxxx",
            "AccessKeySecret": "xxxx",
            "Title": "xxxx",
            "StorageLocation": "xxxx.oss-cn-xxxx.aliyuncs.com",
            }
    }
}

Response parameters

Parameter Type Description
Code
Int64
Return code.
Message
String
Description of the request execution result.
RequestId
String
Request ID.
Data
Object
Response object.
For details, see the Data member parameter.

Listed below is the Data member parameter.

Parameter Type Description
TaskId
String
Task ID assigned by the cloud recording service. The value is a 16-byte character string. The task ID is the unique identifier of a recording lifecycle and becomes meaningless after the recording ends.

Sample response

The following is a response example of the StartRecord method:

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "abcd123",
    "Data": {
        "TaskId": "XXXXXXXXXXXX"
    }
}