StartRecord

POST

https://cloudrecord-api.zego.im/

Call this API to start cloud recording.

After developers successfully call the StartRecord API, the cloud recording service will record audio and video streams and whiteboards in the room according to the configured recording parameters.

Warning

Each recording task has a maximum duration of 24 hours. After 24 hours, the recording task will automatically stop recording.
ZEGOCLOUD recommends that you call the StopRecord method to stop recording for each recording task to avoid incurring additional costs from continuous recording.

Note

Call frequency limit: 50 times/second

Request

Query Parameters

Action stringrequired

Possible values: [StartRecord]

API prototype parameter

https://cloudrecord-api.zego.im?Action=StartRecord

AppId uint32required

💡Common parameter. Application ID, a unique credential assigned by ZEGOCLOUD. You can obtain it from the ZEGOCLOUD Console.

SignatureNonce stringrequired

💡Common parameter. A 16-character hexadecimal random string (hex encoding of an 8-byte random number). For the generation algorithm, refer to Signature Example.

Timestamp int64required

💡Common parameter. Current Unix timestamp in seconds. For the generation algorithm, refer to Signature Example. A maximum error of 10 minutes is allowed.

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡Common parameter. Signature version number.

Signature stringrequired

💡Common parameter. Signature used to verify the legitimacy of the request. Please refer to Signature Mechanism for generation.

application/json

Body

required

RoomId stringrequired

Room ID to be recorded.

RecordInputParams objectrequired

Note
FillBlank and MaxIdleTime have different scopes:
FillBlank: Applies to the stream itself. As long as the recording task is still in progress, after FillBlank is set to true, if the stream is in an interrupted state, it will continue to record with blank filling. At this time, the stream is still in an interrupted state and does not affect the determination of whether there are streams in the room.
MaxIdleTime: Applies to the entire recording task state. When the duration without streams in the room exceeds MaxIdleTime, the entire recording task will be terminated.
In stream mixing recording mode, if StreamType is 1, it means only audio is recorded, and whiteboards cannot be recorded at this time.

RecordMode integerrequired

Possible values: [1, 2]

Recording mode.

1: Single stream recording
2: Stream mixing recording

StreamType integer

Possible values: [1, 2, 3, 4]

Default value: 3

Recording media stream type, only applicable to audio and video streams. Whiteboards only record video.

1: Record audio only
2: Record video only
3: Record audio and video (audio and video files merged) (default)
4: Record audio and video (audio and video files separated)

ClientTaskId string

Task ID of the recording request initiated by the user. If a recording task with the specified ClientTaskId already exists, the response parameter TaskId will return the existing recording task ID; otherwise, the server will create a new recording task and the response parameter TaskId will return the new recording task ID.

RecordStreamList object[]

Only applicable to single stream recording mode, specifies the list of stream information to be recorded.If this field is not specified or the list is empty, all streams in the room are recorded by default.

Array[

StreamId stringrequired

Stream ID to be recorded.

]

FillBlank boolean

Default value: false

Whether to automatically fill blanks when the stream is interrupted. Default is false, i.e., no blank filling.

true: When a user's stream is interrupted, blank filling will be automatic. The effect of automatic blank filling varies depending on the recording mode.
- Single stream recording: Only audio is filled with blanks.
  
  Note
  
  If the publishing end only publishes video streams, or the recording media stream type is video only, blank filling is not possible.
  
  During the interruption, the server will supplement the audio with silent frames until the stream is published again in the room using the same stream ID. Finally, the same recording file will retain normal stream content and silent frames.
- Stream mixing recording: During the interruption, the video will stay on the last frame (default) or display the stream view background image. In addition, if there is no audio content in the mixed stream, the server will supplement silent frames until the stream is published again in the room using the same stream ID. Finally, the same recording file will retain normal stream content, blank filling frames, and silent frames (if any). If you need to use a stream view background image for blank filling, please refer to the DefaultMixStreamBackgroundImage and BackgroundImage parameter descriptions. Setting the stream view background image only takes effect when performing stream mixing recording (i.e., RecordMode is 2).
false: No blank filling when the user's stream is interrupted. In single stream recording mode, a new recording file will be generated the next time the user publishes the stream again. In stream mixing recording mode, there will only be one recording file, and no new recording file will be generated when the user publishes the stream again.

There are two possible timings for interruption blank filling:

Cloud recording automatically stops due to timeout when there are no streams in the room. See the definition of MaxIdleTime.
Actively stop cloud recording.

FillFrame object

Method of filling frames after turning off the camera (while audio continues to be published), only applicable to stream mixing recording.

FrameFillMode integer

Possible values: [1, 2, 3]

Default value: 1

Frame filling mode.

1: Fill with last frame (default)
2: Fill with specified color
3: Do not fill frames

Note

Regarding FrameFillMode:

Mini program clients only support filling with the last frame and do not support filling with a specified color or not filling frames.

Web clients only support filling with black and do not support filling with the last frame, filling with other colors, or not filling frames.

FrameFillColor int32

Valid when FrameFillMode is set to 2, used to specify the fill color. Default is black. The first three bytes are RGB color values, and the fourth byte is fixed at 0, i.e., 0xRRGGBB00.

RecordMuteAudio integer

Possible values: [1, 2]

Default value: 1

Specifies whether to record audio frame data in muted state. Only takes effect when single stream recording, recording audio only, and output file format is mp3.

1: Record audio frames in muted state (default)
2: Do not record audio frames in muted state

RecordMuteAudioSplitThreshold integer

"Silence duration threshold for automatic recording file splitting, in seconds."

"During recording, if the silence duration is greater than or equal to this threshold, different recording files will be generated before and after this silence period."

"Only takes effect when single stream recording, recording audio only, output file format is mp3, and RecordMuteAudio is 2."

"When specified as 0, splitting occurs upon encountering silence. When not specified or specified as a negative number, no splitting occurs."

HasWhiteboard boolean

Default value: false

Whether to record whiteboard.

true: Record whiteboard
false: Do not record whiteboard (default)

When this parameter is true, the Whiteboard parameter is required.

Whiteboard object[]

Whiteboard parameters, required when HasWhiteboard is true.

Array[

HorizontalRatio integerrequired

Aspect ratio of the original whiteboard (width).

VerticalRatio integerrequired

Aspect ratio of the original whiteboard (height).

Width integer

Default value: 1280

Resolution width of the output video for single stream whiteboard recording. Default is 1280.

Height integer

Default value: 720

Resolution height of the output video for single stream whiteboard recording. Default is 720.

WhiteboardId string

ID of the whiteboard to be recorded.

If you want to record the whiteboard immediately after starting recording, you must specify the whiteboard ID.
If you want to start recording without recording the whiteboard first, you can omit this parameter and call the Update whiteboard API to specify the whiteboard ID when you need to record the whiteboard.

BackgroundColor int32

Whiteboard background color. Default is white. The first three bytes are RGB color values, and the fourth byte is fixed at 0, i.e., 0xRRGGBB00.

IsPPTAnimation boolean

Default value: false

Whether to record animated PPT. Default is false.

true: Record animated PPT, supports recording animation effects and videos in PPT.
false: Do not record animated PPT. Animation effects and videos in PPT will not be recorded.

Note

Before using the animated PPT recording feature, please contact ZEGOCLOUD sales to enable it for a fee. Otherwise, setting the IsPPTAnimation and PPTAnimationFps parameters will have no effect.

PPTAnimationFps integer

Possible values: >= 1 and <= 30

Default value: 15

Frame rate for recording animated PPT. Default is 15, valid range is [1,30].

]

MaxIdleTime integer

Possible values: >= 5 and <= 86400

Default value: 30

"How long after there are no streams or whiteboards in the room to automatically stop cloud recording, in seconds. Default is 30 seconds. This value must be greater than or equal to 5 and less than or equal to 86400 (24 hours)."

Note

This parameter only takes effect when there are no streams or whiteboards in the room.

MaxRecordTime integer

Possible values: >= 300 and <= 86400

Default value: 86400

Maximum recording task duration. Recording automatically ends when the duration reaches this value, in seconds. Default is 86400 seconds (24 hours). This value must be greater than or equal to 300 and less than or equal to 86400 (24 hours).

Note

The maximum recording duration limit supports increasing to 48 hours. If you need to adjust the maximum recording duration, please contact ZEGOCLOUD Technical Support.

MixConfig object

Stream mixing parameters, required when RecordMode is 2.

MixMode integer

Possible values: [1, 2, 3, 4, 5]

Default value: 2

Layout mode.

1: Custom layout, MixInputList must be specified
2: (Default) Equal division layout
3: Horizontal layout
4: Vertical layout
5: Floating layout

MixInputList object[]

Custom layout parameters.

Array[

StreamId string

Specifies the ID of the stream to be recorded in this view.

If not specified, recording will be done in the order in which streams join the room.

ViewType integer

Possible values: [1, 2]

Default value: 1

Type of content displayed in this view.

1: Audio and video (default)
2: Whiteboard

Type 2 is only valid when whiteboard recording is enabled. Only one view can be set as whiteboard. Setting two or more will return an error.

Top integerrequired

Possible values: >= 0 and <= 1920

Y-axis coordinate of the upper left corner of this view on the canvas, value range [0, 1920].

Left integerrequired

Possible values: >= 0 and <= 1920

X-axis coordinate of the upper left corner of this view on the canvas, value range [0, 1920].

Bottom integerrequired

Possible values: >= 0 and <= 1920

Y-axis coordinate of the lower right corner of this view on the canvas, value range [0, 1920].

Right integerrequired

Possible values: >= 0 and <= 1920

X-axis coordinate of the lower right corner of this view on the canvas, value range [0, 1920].

Layer integerrequired

Layer priority of this view. When two views overlap, the one with the larger value is displayed on top.

FillMode integer

Possible values: [1, 2]

Default value: 1

How to handle when the actual video stream aspect ratio is inconsistent with the view.

1: Crop mode. In this mode, priority is given to ensuring the view is filled. After the original video is scaled proportionally to fill the view, content exceeding the view on all sides will be cropped. (Default)
2: Scale mode. In this mode, priority is given to ensuring the integrity of the original video. After the original video is scaled proportionally to fill the view, black borders will be added on all sides.

BackgroundImage string

URL address of the stream view background image. Only takes effect when the StreamId parameter is specified. This background image will be displayed when the stream specified in custom layout does not exist or is interrupted.

It is recommended that the background image size matches the set stream view size. If the two are inconsistent, the background image will be stretched or compressed to fill the entire view.
Background image format supports JPG and PNG, size cannot exceed 5MB. If the background image download fails, the setting will not take effect.
URL supports HTTP and HTTPS protocols.

]

FillMode integer

Possible values: [1, 2]

Default value: 1

(Applicable when MixMode in MixConfig is not 1, i.e., not custom layout)

How to handle when the actual video stream aspect ratio is inconsistent with the view.

1: Crop mode. In this mode, priority is given to ensuring the view is filled. After the original video is scaled proportionally to fill the view, content exceeding the view on all sides will be cropped. (Default)
2: Scale mode. In this mode, priority is given to ensuring the integrity of the original video. After the original video is scaled proportionally to fill the view, black borders will be added on all sides.

Note

To learn about FillMode applicable to custom layout, please refer to mixinputlist.FillMode.

MixOutputStreamId stringrequired

Specifies the stream ID for mixed stream output, which will be part of OutputFileRule.

MixOutputVideoConfig object

Output video parameters; this parameter is required when StreamType is 2, 3, or 4.

Width integerrequired

Possible values: <= 1920

"Resolution width of the output video, in pixels."

"Width must be less than or equal to 1920, and the product of Width and Height cannot exceed 1920 * 1080, otherwise an error will be returned."

Height integerrequired

Possible values: <= 1920

"Resolution height of the output video, in pixels."

"Height must be less than or equal to 1920, and the product of Width and Height cannot exceed 1920 * 1080, otherwise an error will be returned."

Fps integerrequired

Possible values: >= 5 and <= 30

Default value: 15

Output video frame rate. Default is 15, valid range [5,30].

Bitrate integerrequired

"Output video bitrate, in bps. For example, to set the bitrate to 1.5 Mbps, you need to set this parameter to 1500*1000, which is 1500000."

MixOutputAudioConfig object

Bitrate integer

Default value: 48000

Audio bitrate. Default is 48000 bps.

MixOutputBackgroundColor int32

Recording background color. Default is black. The first three bytes are RGB color values, and the fourth byte is fixed at 0, i.e., 0xRRGGBB00.

MixOutputBackgroundImage string

URL address of the video canvas background image.

It is recommended that the background image resolution matches the output video resolution. If the two resolutions are inconsistent, the background image will be stretched or compressed to fill the entire view.
Background image format supports JPG and PNG, size cannot exceed 5MB. If the background image download fails, the setting will not take effect.
URL supports HTTP and HTTPS protocols.

MixMaxResolutionStreamId string

When MixMode is set to 3, 4, or 5, used to specify the stream ID to display in the large view.

MixOutputWatermarkImage string

URL address of the watermark image.

It is recommended that the watermark image size matches the set watermark layout size. If the two are inconsistent, the watermark image will be stretched to fill the watermark layout position.
Watermark image format supports JPG and PNG, size cannot exceed 5MB. If the watermark image download fails, the setting will not take effect.
URL supports HTTP and HTTPS protocols.

MixOutputWatermarkImageConfig object

Watermark layout configuration.

Left integerrequired

Possible values: >= 0 and <= 1920

X-axis coordinate of the upper left corner of the watermark on the canvas, value range [0, 1920], cannot exceed the value of Right and the width of the canvas.

Top integerrequired

Possible values: >= 0 and <= 1920

Y-axis coordinate of the upper left corner of the watermark on the canvas, value range [0, 1920], cannot exceed the value of Bottom and the height of the canvas.

Right integerrequired

Possible values: >= 0 and <= 1920

X-axis coordinate of the lower right corner of the watermark on the canvas, value range [0, 1920], cannot exceed the width of the canvas.

Bottom integerrequired

Possible values: >= 0 and <= 1920

Y-axis coordinate of the lower right corner of the watermark on the canvas, value range [0, 1920], cannot exceed the height of the canvas.

DefaultMixStreamBackgroundImage string

URL address of the default background image for stream view. When the FillBlank parameter is true and FrameFillMode = 3, this background image will be displayed when the specified stream does not exist or is interrupted, and the recording mode is stream mixing recording.

In custom layout, if the BackgroundImage parameter is set for a specified stream ID, BackgroundImage will be displayed with priority.
It is recommended that the background image size matches the set stream view size. If the two are inconsistent, the background image will be stretched or compressed to fill the entire view.
Background image format supports JPG and PNG, size cannot exceed 5MB. If the background image download fails, the setting will not take effect.
URL supports HTTP and HTTPS protocols.

IsAlwaysMix boolean

Default value: false

Whether to start recording immediately after the recording task is started. Default is false, which means recording starts after streams are published in the room.

true: Start recording immediately after the recording task is started.
false: After the recording task is started, wait for streams to be published in the room before starting recording.

MixOutputWatermarkTimestampConfig object

Timestamp watermark configuration. After configuration, the timestamp watermark is displayed in the upper right corner of the video in the format yyyy-MM-dd HH

FontSize integerrequired

Possible values: >= 12 and <= 100

Font size, value range [12, 100], in px.

RecordSoundWave boolean

Default value: false

Whether to record sound wave information after the recording task is started. Default is false.

true: After the recording task is started, record the sound wave information of all current streams every 1 second.
false: After the recording task is started, do not record sound wave information.

Sound wave information will be written to a separate file in JSON format. The file name is the same as the recording file name with a .sw suffix. After the recording task ends, it will be uploaded to the specified cloud storage location together with the recording file.

SoundWaveType integer

Possible values: [0, 1]

Default value: 0

"Sound wave information type. This parameter only takes effect when RecordSoundWave is true."

"- 0: Record stream ID information (default). Example: {\"time\":10, \"sound_wave\":[{\"stream_id\":\"s1\", \"volume\":0}]}" "- 1: Record user ID information. Example: {\"time\":10, \"sound_wave\":[{\"user_id\":\"u1\", \"volume\":0}]}"

StreamConfigList object[]

Custom stream parameters.

Array[

StreamId string

Stream ID. If StreamId is empty, it indicates setting the default value of the parameter. Other streams that do not appear in StreamConfigList will use the parameter default value.

StreamType integer

Possible values: [0, 1, 2, 3]

Stream recording type. Only takes effect when StreamType in RecordInputParams equals 3 or 4.

0: Default type
1: Audio
2: Video
3: Audio and video

]

ClearInputStreamTimeout integer

"Timeout for waiting for input streams, in milliseconds. During this period, the ZEGOCLOUD server waits to obtain input streams before starting stream mixing. If the timeout is reached and no input stream is received, stream mixing will start automatically."

RecordOutputParams object

Recording task output parameters.

OutputFileFormat string

Possible values: [mp4, flv, hls, jpg, mp3]

Default value: mp4

"Specifies the format of the recording file. Default is "mp4". Currently supports "mp4", "flv", "hls", "jpg", and "mp3". If recording "mp4" or "flv" and StreamType is set to 4, the generated audio file format is aac."

Note

When the stream is VP8 encoded and the recording file format is "mp4", please contact ZEGOCLOUD Technical Support for configuration.

OutputFolder string

Output directory of the recording file in third-party cloud storage. Default is the root directory.

OutputFileRule integer

Possible values: [1]

Default value: 1

Recording file naming rule.

Note

Currently only "1" is supported as the unique naming format. Custom naming formats are not supported yet.

Default is 1, which means the naming format is:

TaskId_RoomId_UserId_StreamId_Type_UTC (single stream recording)
Taskid_RoomId_MixOutputStreamId_Type_UTC (stream mixing recording)
Taskid_Roomid_whiteboard_Type_UTC (single stream recording with whiteboard)

"The fields in the file name have the following meanings:" "- Type: File type. V represents video file, A represents audio file, VA represents audio and video file." "- UTC: UTC time when the file started recording, time zone is UTC+0, composed of year, month, day, hour, minute, second, and millisecond."

MixOutputStreamId: Specified in MixConfig. "- whiteboard: Fixed, cannot be modified."

SnapshotInterval integer

Possible values: >= 5 and <= 3600

Default value: 10

Snapshot interval, in seconds. Valid when the recording file format is "jpg", value range is [5, 3600], default is 10.

CallbackUrl string

URL of the custom callback address. If this parameter is not filled in, the callback address configured when the service was activated will be used. URL supports HTTP and HTTPS protocols.

FragmentSeconds integer

Possible values: >= 2 and <= 60

Default value: 15

"Fragment duration, in seconds, value range is [2, 60], default is 15."

"Note: This parameter only takes effect when OutputFileFormat is "hls"."

RealtimeUploadFragment boolean

Whether to upload fragments in real time during recording.

"Note: This parameter only takes effect when OutputFileFormat is "hls"."

ShortFragmentPath boolean

Whether the M3U8 file only saves the file name of the video fragment file (such as .ts file) instead of the path of the video fragment.

"Note: Only takes effect when RealtimeUploadFragment is "true"."

StorageParams objectrequired

Note
For how to fill in each property parameter, please refer to How to fill in the cloud storage related parameters in StorageParams?

Vendor integerrequired

Possible values: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]

Recording file storage service provider. Currently supported storage service providers are as follows:

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
8: Google Cloud Storage
9: China Mobile Cloud EOS
10: Storage service provider using S3 protocol. You need to fill in the StorageParams property parameter EndPoint.

Note

When Vendor is set to 1, 2, 3, 4, 7, 9, or 10, Region, Bucket, AccessKeyId, and AccessKeySecret are required.

When Vendor is set to 5, AlibabaCloudVodParams is required. Currently only supports uploading MP4 and FLV format files.

When Vendor is set to 6, TencentCloudVodParams is required. Currently only supports uploading MP4, FLV, JPG, and MP3 format files.

When Vendor is set to 8, Bucket, AccessKeyId, and AccessKeySecret are required.

When Vendor is set to 10, Bucket and EndPoint are required.

Region string

Region information specified by cloud storage.

Bucket string

Cloud storage bucket.

AccessKeyId string

Access key of cloud storage. It is recommended to provide an access key with write-only permission.

AccessKeySecret string

Secret key of cloud storage.

AlibabaCloudVodParams object

Region stringrequired

Region information specified by Alibaba Cloud VOD.

AccessKeyId stringrequired

Access key of Alibaba Cloud VOD.

AccessKeySecret stringrequired

Secret key of Alibaba Cloud VOD. It is recommended to provide an access key with write-only permission.

Title stringrequired

Alibaba Cloud VOD video name.

StorageLocation stringrequired

Fixed parameter provided by Alibaba Cloud VOD.

TencentCloudVodParams object

SecretId stringrequired

Access key of Tencent Cloud VOD.

SecretKey stringrequired

Secret key of Tencent Cloud VOD. It is recommended to provide an access key with write-only permission.

Region stringrequired

Region information specified by Tencent Cloud VOD.

SubAppId int64

Sub-application ID of Tencent Cloud VOD.

EndPoint string

When Vendor is 10, fill in the address of the storage service using the S3 protocol.

Responses

application/json

Schema
Example (from schema)

Schema

Code int64

Error code.

Message string

Error description.

RequestId string

Request ID.

Data object

TaskId string

"Task ID assigned by the cloud recording service, a fixed-length string of 16 bytes. The task ID is a unique identifier for a recording lifecycle process and loses its meaning when recording ends."

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

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

StartRecord

https://cloudrecord-api.zego.im/

Request

Query Parameters

Body

Responses​

Responses