All Products
Search

This Product

    :StartMPUTask

    Document Center

    :StartMPUTask

    最終更新日:Aug 28, 2024

    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 number of concurrent stream relay tasks allowed 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.
    • After you enable the stream relay feature and configure URL signing for the ingest URL, the ingest URL cannot be accessed after the validity period elapses. For more information, see URL signing.

    QPS limit

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

    Debugging

    OpenAPI Explorer automatically generates 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 ID of the application. You can specify only one application ID in each request.

    ChannelId String Yes yourChannelId

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

    TaskId String Yes yourTaskId

    The ID of the task. You can specify only one task ID in each request. 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.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.Height Float No 0.2456

    The height 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.Width Float No 0.2456

    The width of the image. The value is normalized.

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

    The x-coordinate 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.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.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.
    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.SourceType String No camera

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

    • camera (default)
    • shareScreen
    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.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.BorderWidth Integer No 1

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

    UserPanes.N.Texts.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.
    UserPanes.N.Texts.N.BoxBorderWidth Integer No 0

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

    UserPanes.N.Texts.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.

    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.FontSize Integer No 1

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

    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.Text String No text

    The content of the text.

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

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

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

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

    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.UserId String No TestId

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

    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.Height Float No 0.2456

    The height 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.Width Float No 0.2456

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

    Backgrounds.N.X Float No 0.7576

    The x-coordinate 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.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.

    Watermarks.N.Alpha Float No 0.0

    The transparency of the watermark. 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.

    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.Height Float No 0.2456

    The height 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.Width Float No 0.2456

    The width of the watermark. The value is normalized.

    Watermarks.N.X Float No 0.7576

    The x-coordinate 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.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.

    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.

    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.BorderWidth Integer No 1

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

    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.BoxBorderWidth Integer No 0

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

    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.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.FontSize Integer No 1

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

    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.X Float No 0.7576

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

    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.

    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: video stream
    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 ingest URL is under a domain name for which hotlink protection is enabled, you must include an access token in the 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 ID of the request.

    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.