Modifying a Mixed Stream Recording Job

Function

This API is used to update the layout of a mixed stream recording job.

URI

PUT /v2/apps/{app_id}/mix-stream-jobs/{job_id}

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
app_id	Yes	String	Application ID.
job_id	Yes	String	Job ID.

Request Parameters

**Table 2** Request header parameters
Parameter	Mandatory	Type	Description
Content-Type	Yes	String	Content type.
X-Auth-Token	No	String	User token. This parameter is mandatory when token authentication is used. It can be obtained by calling the IAM API that is used for obtaining a user token. The value of X-Subject-Token in the response header is the user token.
Authorization	No	String	Authentication information. This parameter is mandatory when AK/SK-based authentication is used.
X-Sdk-Date	No	String	Time when the request is sent. This parameter is mandatory when AK/SK-based authentication is used.
X-Project-Id	No	String	Project ID. This parameter is mandatory when AK/SK-based authentication is used.

**Table 3** Request body parameters
Parameter	Mandatory	Type	Description
mix_param	Yes	UpdateMixParam object	Mixed stream parameters.

**Table 4** UpdateMixParam
Parameter	Mandatory	Type	Description
layout_template	No	String	ID of a video layout template. Only custom templates can be updated.
background_image	No	String	Address of the canvas background image. Upload the image to OBS first. By default, proportional scaling and cropping is used to ensure full display. Format: s3://bucket/object
default_user_background_image	No	String	Default user background image address. The image is first uploaded to OBS in the format of s3://bucket/object. By default, proportional scaling and cropping is used to ensure full display.
screen_background_image	No	String	Background image address of the shared screen. The image must be first uploaded to OBS in the format of s3://bucket/object. In the one-large-multiple-small layout scenario, this parameter is used to specify the background image regardless of whether the large window displays the desktop of a non-specified user (desktop sharer) or the shared desktop of a specified user.
max_idle_time	No	Integer	Maximum duration of an idle channel. The value ranges from 5 to 43200. The default value is 30. Unit: second If the channel is not connected for a period longer than the value of this parameter, the recording program automatically exits. If the start request is called again after the exit, a new recording task is generated. The co-host refers to a joiner or publisher.
layout_panes	No	Array of MixLayoutPane objects	List of videos that require mixed streams. If mixed video streams are not required, this parameter does not need to be transferred.
user_background_images	No	Array of MixUserBackgroundImage objects	Background image of a user. The priority is higher than that of default_user_background_image.

**Table 5** MixLayoutPane
Parameter	Mandatory	Type	Description
id	No	Integer	Window ID, which starts from 1.
user_id	No	String	ID of the user who joins the room.
video_type	No	String	Video stream type, which can be camera stream or screen sharing stream. CAMERASTREAM: camera video stream SCREENSTREAM: screen sharing video stream The default value is CAMERASTREAM.
x	No	Float	X coordinate (normalized percentage), which is a relative value of the horizontal coordinate at the upper left corner of an image on the canvas. The value range is [0.0,1.0]. Left-to-right layout. 0.0 is at the leftmost and 1.0 is at the rightmost. The decimal value range is within float. Set this parameter in custom layout scenarios.
y	No	Float	Y coordinate (normalized percentage), which is a relative value of the vertical coordinate at the upper left corner of an image on the canvas. The value range is [0.0,1.0]. Top-to-bottom layout. 0.0 is at the top and 1.0 is at the bottom. The decimal value range is within float. Set this parameter in custom layout scenarios.
width	No	Float	Pane width (normalized percentage). The decimal value range is within float. Set this parameter in custom layout scenarios.
height	No	Float	Pane height (normalized percentage). The decimal value range is within float. Set this parameter in custom layout scenarios.
zorder	No	Integer	Stacking sequence. A maximum of 25 floors are supported, with 0 at the bottom. Set this parameter in custom layout scenarios.
crop_mode	No	String	Tailoring mode. Set this parameter in custom layout scenarios. Two modes are supported: KEEP_RATIO_PADDING: padding at a fixed ratio KEEP_RATIO_CROP: cropping at a fixed ratio
filling_policy	No	String	Filling policy. This parameter is mandatory only in screen sharing templates (including screen_share_right and screen_share_left). The options are as follows: FIXED_USER: This field is filled for fixed users. SHARED_SCREEN: Fill in the shared screen.

**Table 6** MixUserBackgroundImage
Parameter	Mandatory	Type	Description
user_id	Yes	String	ID of the user for whom the background image needs to be configured.
image_uri	Yes	String	Background image address. The image is first uploaded to OBS in the format of s3://bucket/object.

Response Parameters

Status code: 200

**Table 7** Response header parameters
Parameter	Type	Description
X-request-Id	String	Request ID for task tracing.

**Table 8** Response body parameters
Parameter	Type	Description
job_id	String	Job ID, which can be used to modify, view, and stop a mixed stream recording job.
stream_name	String	Stream name.
app_id	String	Application ID.
room_id	String	Room ID.
mix_param	MixParam object	Mixed stream parameters.
record_param	RecordParam object	Recording parameters.
create_time	String	Time when a job is created, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.
update_time	String	Time when the layout of a job is updated, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.
state	String	Job status. INIT: The job is being initialized. RUNNING: The job is running. STOPPED: The job has been stopped.
stop_reason	String	Job termination cause.
description	String	Status description, which is the supplementary description of the state field and can be used for manual query.
start_time	String	Time when a job starts, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.
stop_time	String	Time when a job ends, for example, 2006-01-02T15:04:05.075Z. The time zone is UTC.

**Table 9** MixParam
Parameter	Type	Description
room_id	String	Room ID.
encode_template	String	Name of the encoding template. 19201080_30_4620: The output stream is 1080p, the frame rate is 30 FPS, and the bitrate is 4.62 Mbit/s. 19201080_30_3150: The output stream is 1080p, the frame rate is 30 FPS, and the bitrate is 3.15 Mbit/s. 19201080_15_3460: The output stream is 1080p, the frame rate is 15 FPS, and the bitrate is 3.46 Mbit/s. 19201080_15_2080: The output stream is 1080p, the frame rate is 15 FPS, and the bitrate is 2.08 Mbit/s. 1280720_30_3420: The output stream is 720p, the frame rate is 30 FPS, and the bitrate is 3.42 Mbit/s. 1280720_30_1710: The output stream is 720p, the frame rate is 30 FPS, and the bitrate is 1.71 Mbit/s. 1280720_15_2260: The output stream is 720p, the frame rate is 15 FPS, and the bitrate is 2.26 Mbit/s. 1280720_15_1130: The output stream is 720p, the frame rate is 15 FPS, and the bitrate is 1.13 Mbit/s. 640480_30_1000: The output stream is 480p, the frame rate is 30 FPS, and the bitrate is 1.00 Mbit/s. 640480_15_500: The output stream is 480p, the frame rate is 15 FPS, and the bitrate is 500 kbit/s. 480360_30_490: The output stream is 360p, the frame rate is 30 FPS, and the bitrate is 490 kbit/s. 480360_15_320: The output stream is 360p, the frame rate is 15 FPS, and the bitrate is 320 kbit/s.
max_idle_time	Integer	Maximum duration of an idle channel. The value ranges from 5 to 43200. The default value is 30. Unit: second If the channel is not connected for a period longer than the value of this parameter, the recording program automatically exits. If the start request is called again after the exit, a new recording task is generated. The co-host refers to a joiner or publisher.
layout_template	String	Video layout template ID. If mixed video is not required, this parameter does not need to be transferred. nine_grids_view: adaptive gallery view template. screen_share_left: adaptive screen sharing templates with the main screen on the left screen_share_right: adaptive screen sharing templates with the main screen on the right custom: customized layout
default_user_background_image	String	Default user background image address. The image is first uploaded to OBS in the format of s3://bucket/object. By default, proportional scaling and cropping is used to ensure full display.
screen_background_image	String	Background image address of the shared screen. The image must be first uploaded to OBS in the format of s3://bucket/object. In the one-large-multiple-small layout scenario, this parameter is used to specify the background image regardless of whether the large window displays the desktop of a non-specified user (desktop sharer) or the shared desktop of a specified user.
background_image	String	Address of the background image of the canvas. To use the background image function, you need to upload the image to OBS. The format of this parameter must be s3://bucket/object, where bucket and object indicate the bucket and path where the image is located. By default, proportional scaling and cropping is used to ensure full display.
layout_panes	Array of MixLayoutPane objects	List of videos that require mixed streams. If mixed video is not required, this parameter does not need to be transferred. You do not need to set this parameter for the nine_grids_view template.
user_background_images	Array of MixUserBackgroundImage objects	Background image of a user. The priority is higher than that of default_user_background_image.

**Table 10** MixLayoutPane
Parameter	Type	Description
id	Integer	Window ID, which starts from 1.
user_id	String	ID of the user who joins the room.
video_type	String	Video stream type, which can be camera stream or screen sharing stream. CAMERASTREAM: camera video stream SCREENSTREAM: screen sharing video stream The default value is CAMERASTREAM.
x	Float	X coordinate (normalized percentage), which is a relative value of the horizontal coordinate at the upper left corner of an image on the canvas. The value range is [0.0,1.0]. Left-to-right layout. 0.0 is at the leftmost and 1.0 is at the rightmost. The decimal value range is within float. Set this parameter in custom layout scenarios.
y	Float	Y coordinate (normalized percentage), which is a relative value of the vertical coordinate at the upper left corner of an image on the canvas. The value range is [0.0,1.0]. Top-to-bottom layout. 0.0 is at the top and 1.0 is at the bottom. The decimal value range is within float. Set this parameter in custom layout scenarios.
width	Float	Pane width (normalized percentage). The decimal value range is within float. Set this parameter in custom layout scenarios.
height	Float	Pane height (normalized percentage). The decimal value range is within float. Set this parameter in custom layout scenarios.
zorder	Integer	Stacking sequence. A maximum of 25 floors are supported, with 0 at the bottom. Set this parameter in custom layout scenarios.
crop_mode	String	Tailoring mode. Set this parameter in custom layout scenarios. Two modes are supported: KEEP_RATIO_PADDING: padding at a fixed ratio KEEP_RATIO_CROP: cropping at a fixed ratio
filling_policy	String	Filling policy. This parameter is mandatory only in screen sharing templates (including screen_share_right and screen_share_left). The options are as follows: FIXED_USER: This field is filled for fixed users. SHARED_SCREEN: Fill in the shared screen.

**Table 11** MixUserBackgroundImage
Parameter	Type	Description
user_id	String	ID of the user for whom the background image needs to be configured.
image_uri	String	Background image address. The image is first uploaded to OBS in the format of s3://bucket/object.

**Table 12** RecordParam
Parameter	Type	Description
record_rule_id	String	Recording rule ID.

Status code: 400

**Table 13** Response header parameters
Parameter	Type	Description
X-request-Id	String	Request ID for task tracing.

**Table 14** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Description.

Status code: 404

**Table 15** Response header parameters
Parameter	Type	Description
X-request-Id	String	Request ID for task tracing.

**Table 16** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Description.

Status code: 500

**Table 17** Response header parameters
Parameter	Type	Description
X-request-Id	String	Request ID for task tracing.

**Table 18** Response body parameters
Parameter	Type	Description
error_code	String	Error code.
error_msg	String	Description.

Example Requests

PUT https://rtc-api.myhuaweicloud.com/v2/apps/{app_id}/mix-stream-jobs/{job_id}

{
  "mix_param" : {
    "layout_template" : "nine_grids_view"
  }
}

Example Responses

Status code: 200

Modified successfully.

{
  "jobs" : [ {
    "job_id" : "607824b4fa163e19fe301cc817dda855",
    "job_unique_id" : "707e5bfb1ccf4eef",
    "stream_name" : "m_607824b4fa163e19fe301cc817dda855_gigu",
    "app_id" : "123456789abcdefghijklmno",
    "room_id" : "gigu",
    "mix_param" : {
      "room_id" : "gigu",
      "encode_template" : "1920x1080_30_4620",
      "max_idle_time" : 0,
      "layout_template" : "nine_grids_view"
    },
    "record_param" : {
      "record_rule_id" : "5f5e172b9016ed5b0961a43"
    },
    "create_time" : "2021-04-16T16:22:44Z",
    "update_time" : "2021-04-16T16:22:44Z",
    "state" : "INIT",
    "start_time" : "2021-04-16T16:22:44Z",
    "stop_time" : "0001-01-01T00:00:00Z"
  } ]
}

Status code: 400

Modification failed because the request cannot be understood by the server or parameters are incorrect.

{
  "error_code" : "RTC.00001003",
  "error_msg" : "InvalidParameterValue"
}

Status code: 404

Modification failed because the application does not exist.

{
  "error_code" : "RTC.00001003",
  "error_msg" : "InvalidParameterValue"
}

Status code: 500

Modification failed due to server error.

{
  "error_code" : "RTC.00002xxx",
  "error_msg" : "InternalError"
}

Status Codes

Status Code	Description
200	Modified successfully.
400	Modification failed because the request cannot be understood by the server or parameters are incorrect.
404	Modification failed because the application does not exist.
500	Modification failed due to server error.