ApsaraVideo Live:StartLiveMPUTask

Usage notes

By default, you can create up to 200 single-stream relay tasks and up to 40 mixed-stream relay tasks for an application. To increase the quota, submit a ticket.

Lifecycle of a stream relay task

• Call the StartLiveMPUTask operation to create a task.
  • If no user joins the channel, an error indicating that the channel does not exist is returned.
  • Stream relay is not performed if no stream is ingested. In this case, no relayed stream is available for playback.
  • If the task is in the mixed-stream relay mode, make sure that at least one user is ingesting a stream, which can be relayed for playback. A black screen is displayed in the pane of a user who is not ingesting a stream.
• We recommend that you record the task status, task mode, and task parameters on your business server.
  • Task status: started or stopped.
  • Task mode: single-stream relay or mixed-stream relay.
  • Task parameters: the latest input parameters. For example, after your call of the UpdateLiveMPUTask operation is successful, record the task parameters, which are the latest.
• In co-streaming or battle scenarios, the task is in the mixed-stream relay mode. If the streamer leaves the channel due to exceptions and re-joins the channel, you can directly call the StartLiveMPUTask operation on your business server to start stream relay based on the recorded task parameters.
  • If the task has not been automatically cleared by the system, the task is directly started.
  • If the task has not been automatically cleared by the system, a message indicating that the task already exists is returned.

• After the streamer leaves the channel, you need to call the StopLiveMPUTask operation to stop the task.
• If all users specified in the task have left the channel, but you do not call the StopLiveMPUTask operation, the system stops the task in 2 minutes.

QPS limit

You can call this operation up to 500 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. For more information, see QPS limits.

Request parameters

Layout and volume SEI

If a single streamer is streaming, the SEI message that viewers receive contains information about only one participant. If co-streaming or a battle occurs, the SEI message that viewers receive contains information about multiple participants.

For example, when the streamer whose user ID is 111 is streaming, an SEI frame in the following format is sent to the viewer side:

When the streamer whose user ID is 111 is co-streaming with a co-streamer whose user ID is 222, an SEI frame in the following format is sent to the viewer side:

Viewers can determine whether a streaming layout changes based on the number of stream arrays. If only one stream array exists, a single streamer is streaming. If more than one stream array exists, co-streaming or a battle occurs. The layout information of the participants can indicate the position of each participant in the mixed stream.

SEI pass-through

• To configure custom SEI, call the StartLiveMPUTask operation to start a mixed-stream relay task and specify the PayloadContent parameter under the PassThrough parameter, or call the UpdateLiveMPUTask operation to update a mixed-stream relay task and specify the PayloadContent parameter under the PassThrough parameter.
• Custom SEI can be sent periodically. You can use the Interval parameter under the PassThrough parameter to specify the interval in milliseconds.
• Custom SEI can also be sent with keyframes by specifying the FollowIdr parameter under the PassThrough parameter.
  • You can configure settings to periodically send the custom SEI and send the custom SEI with keyframes at the same time. For example, you can set the Interval parameter to 1000 and the FollowIdr parameter to 1 to send the custom SEI every 1,000 milliseconds and include the custom SEI in keyframes.
  • If you do not specify the Interval parameter and the FollowIdr parameter, the custom SEI is sent only once when you call the operation.

For example, the streamer whose user ID is 111 ingests a stream and calls the UpdateLiveMPUTask operation to specify periodic SEI. In the operation, the Interval parameter is set to 1000, the FollowIdr parameter is set to 0, and the PayloadContent parameter is set to "hello world". In this case, the custom SEI is sent every 1,000 milliseconds. The SEI frame received on the viewer side is in the following format:

Mixed-stream relay across channels

If you want to mix streams from multiple streamers across multiple channels and relay the mixed stream to ApsaraVideo Live, you must specify the user ID and channel ID of the streamer who initiates the cross-channel call and the user IDs of other streamers as input parameters to create a mixed-stream relay task. Example:

In a battle scenario, Streamer A in Channel A initiates a cross-channel battle with Streamer B in Channel B by using the client interface and relays the mixed stream to viewers in Channel A. In this example, the following parameters are specified:

• ChannelID: channelA
• UserId under UserInfos: userA and userB

Response parameters

Examples

Sample requests

http(s)://live.aliyuncs.com/?Action=StartLiveMPUTask
&AppId=yourAppId
&ChannelId=yourChannelId
&TaskId=yourTaskId
&MixMode=0
&StreamURL=rtmp://example.com/live/stream
&MultiStreamURL=[{"URL":"rtmp://example.com/live/stream****"}]
&Region=CN-Shanghai
&SingleSubParams={"SourceType":"camera","StreamType":"0","UserId":"yourSubUserId"}
&TranscodeParams={"Background":{"RenderMode":"1","URL":"yourImageUrl"},"EncodeParams":{"AudioOnly":"false","AudioBitrate":"128","AudioChannels":"2","AudioSampleRate":"44100","VideoCodec":"H.264","VideoBitrate":"3500","VideoFramerate":"25","VideoGop":"20","VideoHeight":"1000","VideoWidth":"1920","EnhancedParam":"{\"profile\": \"high\", \"preset\": \"veryfast\"}"},"Layout":{"UserPanes":[{"UserInfo":{"SourceType":"camera","ChannelId":"yourChannelId","UserId":"yourSubUserId"},"Height":"0.2632","Width":"0.3564","X":"0.2456","Y":"0.3789","ZOrder":"0","BackgroundImageUrl":"yourImageUrl","RenderMode":"1"}]},"UserInfos":[{"SourceType":"camera","StreamType":"0","ChannelId":"yourChannelId","UserId":"yourSubUserId"}]}
&SeiParams={"LayoutVolume":{"FollowIdr":"0","Interval":"1000"},"PassThrough":{"FollowIdr":"0","Interval":"1000","PayloadContent":"yourPayloadContent","PayloadContentKey":"yourPayloadContentKey"},"PayloadType":"100"}
&<Common request parameters>

Sample success responses

XML format

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

<StartLiveMPUTaskResponse>
    <RequestId>0F72851F-5DC1-1979-9B2C-450040316C3E</RequestId>
</StartLiveMPUTaskResponse>

JSON format

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

{
  "RequestId" : "0F72851F-5DC1-1979-9B2C-450040316C3E"
}

Error codes

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