Documentation
Cloud Recording
API Documents
Update the Mixed Stream Layout

Update the mixed-stream layout

Last updated：2024-10-17 15:02

Description

Updates the mixed-stream layout settings at any time during the recording.

Request method and endpoint

Request method: POST
Request endpoint: https://cloudrecord-api.zego.im/?Action=UpdateLayout
Transmission protocol: HTTPS
Rate limit: 10 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
TaskId	String	Yes	Task ID. The value is a 16-byte character string.
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.
MixMaxResolutionStreamId	String	No	Stream ID of the large screen when `MixMode` is set to 3, 4, or 5.

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.

Sample request

The following is a request example of the UpdateLayout method:

Request URL

https://cloudrecord-api.zego.im/?Action=UpdateLayout
&AppId=1234567890
&SignatureNonce=15215528852396
&Timestamp=1234567890
&Signature=7a2c0f11145fb760d607a07b54825013
&SignatureVersion=2.0

Request message body

{
  "TaskId": "xxxx",
  "MixMode": 1,
  "MixInputList": [
      {
          "StreamId": "xxxx", 
          "ViewType": 1, 
          "Top": 0, 
          "Left": 0, 
          "Bottom": 720, 
          "Right": 540, 
          "Layer": 1
      },
      {
          "StreamId": "", 
          "ViewType": 1, 
          "Top": 0, 
          "Left": 540, 
          "Bottom": 360, 
          "Right": 1080, 
          "Layer": 1
      },
      {
          "StreamId": "", 
          "ViewType": 1, 
          "Top": 360, 
          "Left": 540, 
          "Bottom": 720, 
          "Right": 1080, 
          "Layer": 1
      }
  ]
}

Response parameters

Parameter	Type	Description
Code	Int64	Return code.
Message	String	Description of the request execution result.
RequestId	String	Request ID.

Sample response

The following is a response example of the UpdateLayout method:

{
    "Code": 0,
    "Message": "succeed",
    "RequestId": "abcd123"
}