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

Querying a Mixed Stream Recording Job

Function

This API is used to query a mixed stream recording job.

URI

GET /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.

Response Parameters

Status code: 200

Table 3 Response header parameters

Parameter

Type

Description

X-request-Id

String

Request ID for task tracing.

Table 4 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 5 MixParam

Parameter

Type

Description

room_id

String

Room ID.

encode_template

String

Name of the encoding template.

  • 1920*1080_30_4620: The output stream is 1080p, the frame rate is 30 FPS, and the bitrate is 4.62 Mbit/s.

  • 1920*1080_30_3150: The output stream is 1080p, the frame rate is 30 FPS, and the bitrate is 3.15 Mbit/s.

  • 1920*1080_15_3460: The output stream is 1080p, the frame rate is 15 FPS, and the bitrate is 3.46 Mbit/s.

  • 1920*1080_15_2080: The output stream is 1080p, the frame rate is 15 FPS, and the bitrate is 2.08 Mbit/s.

  • 1280*720_30_3420: The output stream is 720p, the frame rate is 30 FPS, and the bitrate is 3.42 Mbit/s.

  • 1280*720_30_1710: The output stream is 720p, the frame rate is 30 FPS, and the bitrate is 1.71 Mbit/s.

  • 1280*720_15_2260: The output stream is 720p, the frame rate is 15 FPS, and the bitrate is 2.26 Mbit/s.

  • 1280*720_15_1130: The output stream is 720p, the frame rate is 15 FPS, and the bitrate is 1.13 Mbit/s.

  • 640*480_30_1000: The output stream is 480p, the frame rate is 30 FPS, and the bitrate is 1.00 Mbit/s.

  • 640*480_15_500: The output stream is 480p, the frame rate is 15 FPS, and the bitrate is 500 kbit/s.

  • 480*360_30_490: The output stream is 360p, the frame rate is 30 FPS, and the bitrate is 490 kbit/s.

  • 480*360_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 6 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 7 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 8 RecordParam

Parameter

Type

Description

record_rule_id

String

Recording rule ID.

Status code: 404

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

error_code

String

Error code.

error_msg

String

Description.

Status code: 500

Table 11 Response header parameters

Parameter

Type

Description

X-request-Id

String

Request ID for task tracing.

Table 12 Response body parameters

Parameter

Type

Description

error_code

String

Error code.

error_msg

String

Description.

Example Requests

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

Example Responses

Status code: 200

The mixed stream recording job is successfully queried. The query result is as follows:

{
  "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: 404

Failed to query the mixed stream recording job because the job ID does not exist.

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

Status code: 500

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

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

Status Codes

Status Code

Description

200

The mixed stream recording job is successfully queried. The query result is as follows:

404

Failed to query the mixed stream recording job because the job ID does not exist.

500

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

Error Codes

See Error Codes.