Help Center/ SparkRTC/ API Reference/ Examples/ Mixed stream recording job management/ Starting a Mixed Stream Recording Job

Updated on 2022-10-08 GMT+08:00

View PDF

Starting a Mixed Stream Recording Job

Function

Creates and starts a mixed stream recording job.

Both audio-only recording and audio & video recording are supported.

Audio-only recording

If encode_template is set to audio_only, the three parties with the loudest voices are dynamically selected during audio stream mixing.

Leave layout_template, layout_panes, and other video-related parameters empty.

Audio & video recording (including desktop sharing)

If encode_template is not audio_only, layout_template and layout_panes must not be left empty.

The three parties with the loudest voices are dynamically selected during audio stream mixing.

The name of the stream mixing recording triggered by the API is in the format of {jobtype}_{jobid}_{roomid}, in which the value of jobtype is m, indicating that the stream mixing recording is triggered.

URI

POST /v2/apps/{app_id}/mix-stream-jobs

**Table 1** Path Parameters
Parameter	Mandatory	Type	Description
app_id	Yes	String	Application 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	MixParam object	Mixed stream parameters.
publish_param	No	PublishParam object	Forwarding parameters.
record_param	No	RecordParam object	Recording parameters.

**Table 4** MixParam
Parameter	Mandatory	Type	Description
room_id	Yes	String	Room ID.
encode_template	Yes	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	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_template	No	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	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.
background_image	No	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	No	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	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.

**Table 7** PublishParam
Parameter	Mandatory	Type	Description
rtmp_urls	Yes	Array of strings	RTMP stream push URL after a mixed stream streaming job is complete.

**Table 8** RecordParam
Parameter	Mandatory	Type	Description
record_rule_id	Yes	String	Recording rule ID.

Response Parameters

Status code: 201

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

**Table 10** 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 11** 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 12** 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 13** 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 14** RecordParam
Parameter	Type	Description
record_rule_id	String	Recording rule ID.

Status code: 400

**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: 404

**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.

Status code: 500

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

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

Example Requests

Sample request for a nine-grid recording

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

{
  "mix_param" : {
    "room_id" : "room001",
    "encode_template" : "1280x720_15_2260",
    "max_idle_time" : 30,
    "layout_template" : "nine_grids_view"
  },
  "record_param" : {
    "record_rule_id" : "5f5e172b9016ed5b0961a43"
  }
}

Sample request for a shared screen recording: displaying the shared screen in the main window

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

{
  "mix_param" : {
    "room_id" : "room001",
    "encode_template" : "1280x720_15_2260",
    "max_idle_time" : 30,
    "layout_template" : "screen_share_right",
    "layout_panes" : [ {
      "id" : 1,
      "user_id" : "",
      "video_type" : "SCREENSTREAM",
      "filling_policy" : "SHARED_SCREEN"
    } ]
  },
  "record_param" : {
    "record_rule_id" : "5f5e172b9016ed5b0961a43"
  }
}

Sample request for a shared screen recording: displaying the camera in the main window

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

{
  "mix_param" : {
    "room_id" : "room001",
    "encode_template" : "1280x720_15_2260",
    "max_idle_time" : 30,
    "layout_template" : "screen_share_right",
    "layout_panes" : [ {
      "id" : 1,
      "user_id" : "user1",
      "video_type" : "CAMERASTREAM",
      "filling_policy" : "FIXED_USER"
    } ]
  },
  "record_param" : {
    "record_rule_id" : "5f5e172b9016ed5b0961a43"
  }
}

Sample request for a customized layout recording

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

{
  "mix_param" : {
    "room_id" : "room001",
    "encode_template" : "1280x720_15_2260",
    "max_idle_time" : 30,
    "layout_template" : "custom",
    "layout_panes" : [ {
      "id" : 1,
      "user_id" : "user1",
      "video_type" : "CAMERASTREAM",
      "x" : 0,
      "y" : 0,
      "width" : 0.666,
      "height" : 0.333,
      "crop_mode" : "KEEP_RATIO_CROP"
    }, {
      "id" : 2,
      "user_id" : "user2",
      "video_type" : "CAMERASTREAM",
      "x" : 0.666,
      "y" : 0,
      "width" : 0.333,
      "height" : 0.666,
      "crop_mode" : "KEEP_RATIO_CROP"
    } ]
  },
  "record_param" : {
    "record_rule_id" : "5f5e172b9016ed5b0961a43"
  }
}

Example Responses

Status code: 201

The job is created, and the job summary information is returned.

{
  "job_id" : "607824b4fa163e19fe301cc817dda855",
  "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

Failed to create the mixed stream recording job because the request cannot be understood by the server or parameters are incorrect.

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

Status code: 404

The application ID does not exist.

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

Status code: 500

Failed to create the mixed stream recording job due to server error.

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

Status Codes

Status Code	Description
201	The job is created, and the job summary information is returned.
400	Failed to create the mixed stream recording job because the request cannot be understood by the server or parameters are incorrect.
404	The application ID does not exist.
500	Failed to create the mixed stream recording job due to server error.