Starts a stream relay task.

Usage notes

You can call this operation to start a stream relay task. The following limits apply when you use the stream relay feature:

  • The maximum allowed number of concurrent stream relay tasks is 20.
  • If you do not enable transcoding, each accelerated domain name supports concurrent ingest of up to 20 live streams that are in original quality.
  • If you enable transcoding, each accelerated domain name supports concurrent ingest of up to 10 live streams that are transcoded.

QPS limit

You can call this operation up to 10 times per second per account. Requests that exceed this limit are dropped and you will experience service interruptions. We recommend that you take note of this limit when you call this operation.

Debugging

OpenAPI Explorer automatically calculates the signature value. For your convenience, we recommend that you call this operation in OpenAPI Explorer. OpenAPI Explorer dynamically generates the sample code of the operation for different SDKs.

Request parameters

Parameter Type Required Example Description
Action String Yes StartMPUTask

The operation that you want to perform. Set the value to StartMPUTask.

AppId String Yes yourAppId

The application ID. You can specify only one application ID.

ChannelId String Yes yourChannelId

The channel ID. You can specify only one channel ID.

TaskId String Yes yourTaskId

The task ID. You can specify only one task ID. The ID can be up to 55 bytes in length and can contain letters, digits, underscores, and hyphens (-).

Note The ID must be unique.
TaskType Integer No 0

The type of media processing. Valid values:

  • 0: stream relay task
  • 1: MCU mixed-stream low-latency distribution task
MixMode Integer No 0

The stream mixing mode. Valid values:

  • 0: the single-stream relay mode. In this mode, the service only relays the original single stream, but does not transcode mixed streams. You do not need to set parameters for mixed-stream transcoding.
  • 1 (default): the mixed-stream transcoding mode. In this mode, transcoded mixed streams can be generated.
Note
  • The following parameters are valid if you set MixMode to 0: StreamType, SourceType, and SubSpecUsers.
  • The following parameters are valid if you set MixMode to 1: MediaEncode, LayoutIds, BackgroundColor, SubSpecUsers, CropMode, UserPanes, Backgrounds, and Watermarks.
TaskProfile String No Mixed_Audio

The task profile. For audio-only stream mixing, you must set this parameter to Mixed_Audio. In other cases, leave this parameter empty.

MediaEncode Integer No 2

The encoding option. For more information, see the "Enumeration values of the MediaEncode parameter" section in this topic.

SubSpecUsers.N String No userID

The users whose tracks to which the task subscribes. By default, the task subscribes to the tracks of all users in the current channel. N is an integer that indicates the index of the user. Valid values of N: 1 to 16.

Note The values of N must start from 1 and must be in consecutive ascending order.
LayoutIds.N Long No 1

The layout ID. You can specify multiple layouts for a task. The system selects the layout based on the number of users in the channel. Valid values of N: 1 to 16. You can specify up to 16 layouts for a stream relay task.

Note
  • The values of N must start from 1 and must be in consecutive ascending order.
  • You cannot specify layouts that have the same number of panes at the same time. For example, you cannot specify layouts whose IDs are 2 and 3 at the same time in the console, because both layouts have two panes.
UserPanes.N.Images.N.Width Float No 0.2456

The width of the image. The value is normalized.

UserPanes.N.Images.N.Height Float No 0.2456

The height of the image. The value is normalized.

UserPanes.N.Images.N.Y Float No 0.7576

The y-coordinate of the image. The value is normalized.

UserPanes.N.Images.N.Url String No https://www.example.com/image.jpg

The HTTP or HTTPS URL of the image.

UserPanes.N.Images.N.Display Integer No 2

Specifies whether to display the image. Valid values:

  • 0: does not display the image.
  • 1: always displays the image.
  • 2: displays the image if the user is not ingesting a stream for a video track.
UserPanes.N.Images.N.ZOrder Integer No 0

The layer in which the image resides. A value of 0 indicates the bottom layer. A value of 1 indicates the upper layer of the bottom layer. By analogy, you can obtain the specific layer indicated by a specific value.

UserPanes.N.Images.N.X Float No 0.7576

The x-coordinate of the image. The value is normalized.

UserPanes.N.SegmentType Integer No 0

Specifies whether to segment human figures. Valid values:

  • 0 (default): does not segment human figures.
  • 1: segments human figures. This value is valid only if you enable the human figure segmentation feature.
UserPanes.N.UserId String No TestId

The ID of the user whose track is played in the pane. Valid values of N: 1 to 16.

UserPanes.N.Texts.N.FontType Integer No 0

The font type of the text. Valid values:

  • 0 (default): NOTO_SERIF_CJKSC_REGULAR
  • 1: ALIBABA_PUHUITI_REGULAR
  • 2: ALIBABA_PUHUITI_BOLD
  • 3: ALIBABA_PUHUITI_Heavy
  • 4: ALIBABA_PUHUITI_LIGHT
  • 5: ALIBABA_PUHUITI_MEDIUM
UserPanes.N.Texts.N.FontColor Integer No 0

The font color of the text, which is an RGB value.

The following formula is used to calculate the RGB value: R + G × 256 + B × 65536. Valid values of R, G, or B: 0 to 255.

UserPanes.N.Texts.N.Y Float No 0.2456

The y-coordinate of the text. The value is normalized.

UserPanes.N.Texts.N.Text String No text

The content of the text.

UserPanes.N.Texts.N.ZOrder Integer No 0

The layer in which the text resides. A value of 0 indicates the bottom layer. A value of 1 indicates the upper layer of the bottom layer. By analogy, you can obtain the specific layer indicated by a specific value.

UserPanes.N.Texts.N.X Float No 0.7576

The x-coordinate of the text. The value is normalized.

UserPanes.N.Texts.N.FontSize Integer No 1

The font size of the text. Valid values: 0 to 72.

UserPanes.N.Texts.N.BorderWidth Integer No 1

The width of the text outline. Unit: pixel. Default value: 0.

UserPanes.N.Texts.N.BorderColor Long No 0

The color of the text outline, which is an RGB value.

The following formula is used to calculate the RGB value: R + G × 256 + B × 65536. Valid values of R, G, or B: 0 to 255.

UserPanes.N.Texts.N.Box Boolean No false

Specifies whether to display the text bounding box. Valid values:

  • false (default): does not display the text bounding box.
  • true: displays the text bounding box.
UserPanes.N.Texts.N.BoxColor Long No 0

The color of the text bounding box, which is an RGB value.

The following formula is used to calculate the RGB value: R + G × 256 + B × 65536. Valid values of R, G, or B: 0 to 255.

UserPanes.N.Texts.N.BoxBorderWidth Integer No 0

The width of the text bounding box. Unit: pixel. Default value: 0.

UserPanes.N.Texts.N.Alpha Float No 0.0

The transparency of the text bounding box and the text. A value of 0.0 indicates that the text bounding box and the text are transparent. A value of 1.0 indicates that the text bounding box and the text are opaque.

UserPanes.N.SourceType String No camera

The type of the track that is played in the pane. Valid values:

  • camera (default)
  • shareScreen
UserPanes.N.PaneId Integer No 2

The pane ID. Valid values: 0 to 15.

Note If no user with the specified pane ID is found, a default track is played in the pane. The default track is determined based on the order in which users join the channel.
Backgrounds.N.Width Float No 0.2456

The width of the background image. The value is normalized.

Backgrounds.N.Height Float No 0.2456

The height of the background image. The value is normalized.

Backgrounds.N.Y Float No 0.7576

The y-coordinate of the background image. The value is normalized.

Backgrounds.N.Url String No https://www.example.com/image.jpg

The HTTP or HTTPS URL of the background image.

Backgrounds.N.Display Integer No 1

Specifies whether to display the background image. Valid values:

  • 0: does not display the background image.
  • 1: always displays the background image.
Backgrounds.N.ZOrder Integer No 0

The layer in which the background image resides. A value of 0 indicates the bottom layer. A value of 1 indicates the upper layer of the bottom layer. By analogy, you can obtain the specific layer indicated by a specific value.

Backgrounds.N.X Float No 0.7576

The x-coordinate of the background image. The value is normalized.

Watermarks.N.Alpha Float No 0.0

The transparency of the watermark. A value of 0.0 indicates that the watermark is transparent. A value of 1.0 indicates that the watermark is opaque.

Watermarks.N.Width Float No 0.2456

The width of the watermark. The value is normalized.

Watermarks.N.Height Float No 0.2456

The height of the watermark. The value is normalized.

Watermarks.N.Y Float No 0.7576

The y-coordinate of the watermark. The value is normalized.

Watermarks.N.Url String No https://www.example.com/image.jpg

The HTTP or HTTPS URL of the watermark.

Watermarks.N.Display Integer No 0

Specifies whether to display the watermark. Valid values:

  • 0: does not display the watermark.
  • 1: always displays the watermark.
Watermarks.N.ZOrder Integer No 0

The layer in which the watermark resides. A value of 0 indicates the bottom layer. A value of 1 indicates the upper layer of the bottom layer. By analogy, you can obtain the specific layer indicated by a specific value.

Watermarks.N.X Float No 0.7576

The x-coordinate of the watermark. The value is normalized.

ClockWidgets.N.FontType Integer No 0

The font type of the clock. Valid values:

  • 0 (default): NOTO_SERIF_CJKSC_REGULAR
  • 1: ALIBABA_PUHUITI_REGULAR
  • 2: ALIBABA_PUHUITI_BOLD
  • 3: ALIBABA_PUHUITI_Heavy
  • 4: ALIBABA_PUHUITI_LIGHT
  • 5: ALIBABA_PUHUITI_MEDIUM
ClockWidgets.N.FontColor Integer No 0

The font color of the clock, which is an RGB value.

The following formula is used to calculate the RGB value: R + G × 256 + B × 65536. Valid values of R, G, or B: 0 to 255.

ClockWidgets.N.Y Float No 0.7576

The y-coordinate of the clock. The value is normalized.

ClockWidgets.N.ZOrder Integer No 0

The layer in which the clock resides. A value of 0 indicates the bottom layer. A value of 1 indicates the upper layer of the bottom layer. By analogy, you can obtain the specific layer indicated by a specific value.

ClockWidgets.N.X Float No 0.7576

The x-coordinate of the clock. The value is normalized.

ClockWidgets.N.FontSize Integer No 1

The font size of the clock. Valid values: 0 to 72.

ClockWidgets.N.BorderWidth Integer No 1

The width of the text outline in the clock. Unit: pixel. Default value: 0.

ClockWidgets.N.BorderColor Long No 0

The color of the text outline in the clock, which is an RGB value.

The following formula is used to calculate the RGB value: R + G × 256 + B × 65536. Valid values of R, G, or B: 0 to 255.

ClockWidgets.N.Box Boolean No false

Specifies whether to display the text bounding box in the clock. Valid values:

  • false (default): does not display the text bounding box.
  • true: displays the text bounding box.
ClockWidgets.N.BoxColor Long No 0

The color of the text bounding box in the clock, which is an RGB value.

The following formula is used to calculate the RGB value: R + G × 256 + B × 65536. Valid values of R, G, or B: 0 to 255.

ClockWidgets.N.BoxBorderWidth Integer No 0

The width of the text bounding box in the clock. Unit: pixel. Default value: 0.

ClockWidgets.N.Alpha Float No 0

The transparency of the text bounding box and the text in the clock. A value of 0.0 indicates that the text bounding box and the text are transparent. A value of 1.0 indicates that the text bounding box and the text are opaque.

StreamType Integer No 0

The stream to be relayed in single-stream relay mode. Valid values:

  • 0 (default): the source stream.
  • 1: the stream for the audio track.
  • 2: the stream for the video track.
SourceType String No camera

The video source in single-stream relay mode. Valid values:

  • camera
  • shareScreen
StreamURL String No rtmp://example.com/live/stream

The ingest URL. You can specify only one URL. For information about the generation rules of ingest URLs, see Ingest and streaming URLs.

Note
  • If the URL is under a domain name for which hotlink protection is enabled, you must include an access token in the ingest URL.
  • You cannot use the same ingest URL in different tasks.
  • You cannot use the same ingest URL within 10 seconds after a task is stopped.
PayloadType String No 0

The payload type. Valid values:

  • 0: no payload
  • 1: video supplemental enhancement information (SEI)
VadInterval String No 86400

The callback interval for speech excitation.

EnhancedParam.EnablePortraitSegmentation Boolean No false

Specifies whether to enable the human figure segmentation feature. This feature is in private preview. Valid values:

  • true
  • false (default)

The parameter settings for stream relay in audio-only mode are similar to those in audio-and-video mode. The differences lie in the settings of the LayoutIds, MediaEncode, and TaskProfile parameters. The three parameters respectively specify the layout, encoding option, and task profile. Take note of the following rules when you configure stream relay in audio-only mode:

  • LayoutIds: The value of this parameter is determined by TaskProfile. If TaskProfile is set to Mixed_Audio, the number of audio sources allowed is not limited.
  • MediaEncode: You must set this parameter to 0.

Enumeration values of the MediaEncode parameter

ID

Width

Height

Bitrate (Kbit/s)

Frame rate (FPS)

0

0

0

64

0

1

640

360

500

15

54

360

640

500

30

53

360

640

500

15

52

640

360

500

30

10

960

540

700

24

20

1280

720

1024

25

22

720

1280

1024

30

23

800

600

1024

30

30

1920

1080

2048

30

31

1080

1920

2048

30

24

750

780

1024

30

25

750

540

700

30

26

720

1280

2048

30

27

1280

720

2048

30

28

1280

720

3096

30

32

1024

768

1024

24

33

1280

960

1024

24

34

1024

768

2048

24

35

1280

960

2048

24

36

1280

720

1024

24

37

1280

720

2048

24

38

540

960

750

15

39

540

960

1500

30

40

1280

720

1200

15

41

720

1280

1200

15

42

720

1280

1500

15

43

540

960

1200

15

Response parameters

Parameter Type Example Description
RequestId String 760bad53276431c499e30dc36f6b26be

The request ID.

Examples

Sample requests

https://live.aliyuncs.com/?Action=StartMPUTask
&AppId=yourAppId
&ChannelId=yourChannelId
&TaskId=yourTaskId
&MediaEncode=2
&BackgroundColor=0
&LayoutIds.1=2
&UserPanes.1.PaneId=0
&UserPanes.1.UserId=TestId
&UserPanes.1.SourceType=camera
&StreamURL=rtmp://example.com/live/stream
&<Common request parameters>

Sample success responses

XML format

HTTP/1.1 200 OK
Content-Type:application/xml

<StartMPUTaskResponse>
    <RequestId>760bad53276431c499e30dc36f6b26be</RequestId>
</StartMPUTaskResponse>

JSON format

HTTP/1.1 200 OK
Content-Type:application/json

{
  "RequestId" : "760bad53276431c499e30dc36f6b26be"
}

Error codes

For a list of error codes, see Service error codes.