Updates a stream relay task.

Usage notes

  • Make sure that a stream relay task is started before you call this operation. You can call the StartMpuTask operation to start a stream relay task.
  • The update takes effect only if you call the operation when a stream relay task runs in the normal state. The update does not take effect if the task is not started, or is stopped or in the abnormal state. You can call the GetMPUTaskStatus operation to query the task status.

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 UpdateMPUTask

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

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 testId

The task ID. You can specify only one task ID. The value must be the same as the task ID specified by the TaskId parameter in your call of the StartMpuTask operation.

StreamURL String Yes 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.
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.
MediaEncode Integer No 2

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

TaskType Integer No 0

The type of media processing. Valid values:

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

The mode in which video images are cropped. Valid values:

  • 1: Video images are cropped at the original aspect ratio.
  • 2 (default): Video images are cropped at the original aspect ratio and with borders.
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.

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.
SubSpecAudioUsers.N String No audioUserID

The users whose audio tracks to which the task subscribes. A value of allStream indicates that the task subscribes to the audio 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 64.

Note The values of N must start from 1 and must be in consecutive ascending order.
SubSpecShareScreenUsers.N String No videoUserID

The users whose screen tracks to which the task subscribes. A value of allStream indicates that the task subscribes to the screen 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 64.

Note The values of N must start from 1 and must be in consecutive ascending order.
SubSpecCameraUsers.N String No cameraUserID

The users whose camera tracks to which the task subscribes. A value of allStream indicates that the task subscribes to the camera 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 64.

Note The values of N must start from 1 and must be in consecutive ascending order.
UnsubSpecAudioUsers.N String No audioUserID2

The users whose audio tracks from which the task unsubscribes. A value of allStream indicates that the task unsubscribes from the audio 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 64.

Note The values of N must start from 1 and must be in consecutive ascending order.
UnsubSpecShareScreenUsers.N String No videoUserID2

The users whose screen tracks from which the task unsubscribes. A value of allStream indicates that the task unsubscribes from the screen 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 64.

Note The values of N must start from 1 and must be in consecutive ascending order.
UnsubSpecCameraUsers.N String No cameraUserID2

The users whose camera tracks from which the task unsubscribes. A value of allStream indicates that the task unsubscribes from the camera 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 64.

Note The values of N must start from 1 and must be in consecutive ascending order.
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 1

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 TestUserID

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

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

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
  • shareScreen
UserPanes.N.PaneId Integer No 2

The pane ID. Valid values: 0 to 15.

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 1

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

SourceType String No camera

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

  • camera
  • shareScreen
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.
BackgroundColor Integer No 0

The background color, which is an RGB value. The default value is 0, which indicates the black color.

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.

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=UpdateMPUTask
&AppId=yourAppId
&TaskId=testId
&BackgroundColor=0
&LayoutIds.1=2
&UserPanes.1.PaneId=2
&UserPanes.1.UserId=TestUserID
&UserPanes.1.SourceType=camera
&<Common request parameters>

Sample success responses

XML format

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

<UpdateMPUTaskResponse>
    <RequestId>760bad53276431c499e30dc36f6b26be</RequestId>
</UpdateMPUTaskResponse>

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.