StartAutoMix

POST

https://rtc-api.zego.im/

本文介绍如何调用服务端 API 接口，指定房间，自动将房间内的所有 音频 流进行混流。可以应用在语聊房、合唱等场景中。

在跨房间 PK 连麦等场景中，支持增加其他房间内的某条流，参与自动混流；或剔除当前房间的某条流，不参与自动混流，具体请参考请求参数中的 ExtraMixInput 参数说明。

说明

目前只支持自动混 音频 流。
后续房间内如果有流新增或删除，您都不需要做任何处理，ZEGO 服务端内部自动更新混流。

“客户端”的混流功能，请参考混流 - 自动混流；“服务端”的相关回调，请参考混流开始回调和混流结束回调。

前提条件

在实现混流之前，请确保：

已在 ZEGO 控制台创建项目，并申请有效的 AppId 和 ServerSecret，详情请参考控制台 - 项目信息。
已在 ZEGO 控制台自助接入服务开通“混流”服务权限，详情请参考控制台 - 服务配置 - 混流，或联系 ZEGO 技术支持开通。
已通过开发者自己的客户端，在房间内发起推拉流，详情请参考实现视频通话。
若您希望创建自动混流时，如果房间不存在，可自动创建对应房间，请联系 ZEGO 技术支持开启相关功能。

说明

测试环境下（详见 IsTest 公共参数说明），输入流的流 ID 和输出流的流 ID：

如果是开发者自己输入的原始流 ID，需要加上 “zegotest-AppId-” 前缀，否则会导致混流失败（混流服务器拉不到输入流或拉不到混流输出流）。例如，开发者输入流 ID 为 “test”，在 AppId 为 “123456789” 的测试环境下，流 ID 应为 “zegotest-123456789-test”。
如果是通过 SDK 接口，或通过服务端 API 接口获取到的，此时不需要添加 “zegotest-AppId-” 的前缀。

调用频率限制

100 次/秒

此接口中只有部分参数在开始混流后支持动态更新，未标注的则不支持动态更新，详情请参考下表中的参数描述。

Request

Query Parameters

Action stringrequired

Possible values: [StartAutoMix]

接口原型参数

https://rtc-api.zego.im?Action=StartAutoMix

AppId uint32required

💡公共参数。AppId，ZEGO 分配的用户唯一凭证。

SignatureNonce stringrequired

💡公共参数。随机字符串。

Timestamp int64required

💡公共参数。Unix 时间戳，单位为秒。最多允许 10 分钟的误差。

Signature stringrequired

💡公共参数。签名，用于验证请求的合法性。

SignatureVersion stringrequired

Possible values: [2.0]

Default value: 2.0

💡公共参数。签名版本号。

IsTest string

Possible values: [true, false]

Default value: false

💡公共参数。是否为测试环境。设为 true 表示使用测试环境。2021-11-16 及之前在 ZEGO 控制台创建的项目默认是测试环境，可根据业务需求设置此参数；而之后创建的项目默认是正式环境。

application/json

Body

required

TaskId stringrequired

任务 ID，混流任务的唯一标识。

重复调用"开始混流"接口，传入相同的 TaskId，可以直接更新混流任务信息。
发起"音视频"混流时，如果之前已发起过对应 TaskId 的"纯音频"混流任务，则需要先停止此任务，再重新发起"音视频"混流任务。

UserId stringrequired

发起混流任务的用户 ID，由开发者自定义。

同一个任务的用户 ID 需要一致，不同任务的用户 ID 需要保持不同。

通过 UserId 可以实现混流任务的用户归属，也就是该用户才能更新或者停止对应 TaskId 的混流任务，该功能需要联系 ZEGO 技术支持开通。

RoomId stringrequired

房间 ID。

ExtraMixInput object[]

额外的输入流列表（其他房间内的流），默认最多支持 9 条额外的输入流。
📌注意
开启自动混流时，最多支持 9 条输入流。即该房间内的流，增加、剔除（根据 ModifyType 取值判断增加或删除某条流）额外的输入流后，流的总数量不能超过 9 条。

Array[

StreamId string

混流输入流 ID，该流 ID 来自 RTC 服务。

仅支持数字、英文字符和 "-"、"_"。

注意

StreamId 和 StreamUrl 二者取其一即可，若同时填写 StreamId 和 StreamUrl：

ModifyType 为 0（增加）时，StreamUrl 生效。

ModifyType 为 1（剔除）时，StreamId 生效。

StreamUrl string

混流输入流 URL，支持 RTMP 和 HTTP-FLV 两种协议。

注意

StreamId 和 StreamUrl 二者取其一即可，若同时填写 StreamId 和 StreamUrl：

ModifyType 为 0（增加）时，StreamUrl 生效。

ModifyType 为 1（剔除）时，StreamId 生效。

ModifyType int

Possible values: [0, 1]

输入流列表的类型，表示在当前混流任务中"增加"或"剔除"该条输入流：

0：开启自动混流时，在输入流列表中增加当前流，默认值
1：开启自动混流时，在输入流列表中剔除当前流。此时只需要填写 StreamId 和本参数的取值即可

SoundLevelId int

声浪 ID。参数 SoundLevel（混流声浪）取值为 "1" 时，此参数必填。

Volume int

Default value: 100

音量，取值范围 [0, 200]，默认为 100。

]

MixOutput object[]required

输出流信息，目前最多支持 3 个。当输出目标为 URL 格式时，目前只支持 RTMP URL 格式：rtmp://xxxxxxxx，且不能传入两个相同的混流输出的地址。

Array[

StreamId string

输出流 ID。默认情况下表示混流输出至 RTC 或低延迟直播产品，也可联系 ZEGO 技术支持配置混流输出至 ZEGO 代理的 CDN 直播产品，生效范围为整个 AppId。如果希望控制指定流输出至 CDN 直播产品，则不能配置混流默认输出至 ZEGO 代理 CDN，应按需设置 StreamUrl。

StreamId 和 StreamUrl 二者取其一即可，若填写了 StreamId，则 StreamUrl 不生效。

StreamUrl string

仅支持 RTMP 协议，表示混流输出至 CDN 直播服务，观众可以从 CDN 直播拉混流。

StreamId 和 StreamUrl 二者取其一即可，若填写了 StreamUrl，则 StreamId 不生效。

AudioCodec int

Possible values: [0, 1, 2, 3]

音频编码及采样率。如需修改采样率，请联系 ZEGO 技术支持配置：

0：HE-AAC，采样率：44100 kHz，默认值
1：AAC-LC，采样率：44100 kHz
2：MP3，采样率：44100 kHz
3：OPUS，采样率：48000 kHz

AudioBitrate int

混流输出音频码率，不填时默认值为 48000，单位为 bps。

SoundChannel int

Possible values: [1, 2]

输出音频声道数，优先级比全局参数高：

1：单声道，默认值
2：双声道

]

Sequence int

混流请求的序列号，用于保证时序，同个任务的参数修改需要保证序列号的递增。例如："Sequence": 1。

如果开启了混流任务的时序控制（如有需要，请联系 ZEGO 技术支持开启），此参数必填。

UserData string

自定义用户数据，使用时需要对此参数内容进行 base64 编码。长度限制为 4000 字节，建议不超过 850 字节。

自定义的用户数据将作为 SEI 信息传输给拉流方，拉流方可通过监听客户端的 onPlayerSyncRecvSEI 回调获取该数据。

🔁再次调用本接口，即可动态更新该参数。

SoundLevel int

Possible values: [0, 1]

混流声浪，指混流的音量大小。支持混流过程中实时更新：

0：不开启，默认值
1：开启。开启后，客户端可以通过 onAutoMixerSoundLevelUpdate 回调来接收自动混流声浪更新的通知

🔁再次调用本接口，即可动态更新该参数。

ByPass int

Possible values: [0, 1]

Default value: 0

单流透传开关，即输入流就一个时是否按输出参数重新编码，该功能需要联系 ZEGO 技术支持开通：

0：不启用，默认值
1：启用

SoundChannel int

Possible values: [1, 2]

Default value: 1

输出音频声道数，当没有指定输出流时使用该配置：

1：单声道，默认值
2：双声道

AlignmentType int

Possible values: [0, 1, 2]

控制播放的实时音视频流是否需要按照 NTP（网络时间）精准对齐后进行混流。此参数主要应用于 KTV 场景中，会增加一定的混流延时；非 KTV 类似场景，不建议设置此参数。

0：不对齐，默认值
1：指定流对齐
2：所有流强制对齐

RecvBufferLevel int

Possible values: >= 0 and <= 4000

控制拉流最小缓冲时间，取值范围 [0, 4000]，单位：毫秒；默认最小缓冲时间为 0。

ExPara object[]

拓展参数，根据实际情况填入，常规任务可不填。

Array[

Key string

key 值。

Value string

value 值。

]

Responses

操作成功

application/json

Schema
Example (from schema)

Schema

Code int

以下仅列出了接口业务逻辑相关的部分返回码，完整返回码请参考全局返回码。

返回码	说明	处理建议
110200001	失败。	请重试。
110200002	输入参数错误。	请参考 Message 信息处理。
110200003	鉴权失败。	请确认鉴权信息是否正确或过期，详情请参考调用方式中的 "3 签名机制"。
110200004	解析输入参数失败。	请检查混流参数是否正确。
110200005	混流开始获取分布式锁失败。	同一个 UserId 开始混流请求过于频繁，请稍后再试。
110200006	混流结束获取分布式锁失败。	同一个 UserId 停止混流请求过于频繁，请稍后再试。
110200151	混流任务失败。	请重试，或联系 ZEGO 技术支持处理。
110200194	混流请求过载。	请求过于频繁，请稍后再试。

Message string

操作结果描述。

RequestId string

请求 ID。

Data object

响应数据。

UserId string

用户 ID。

Sequence int

序列号。

RoomId string

房间 ID。

PlayInfo object[]

播放信息。

Array[

StreamId string

输出流的流 ID。

RTMP string

RTMP 协议对应的 CDN 播放地址（如果指定混流输出地址是 CDN 并且配置了这个协议的拉流域名）。

HLS string

HLS 协议对应的 CDN 播放地址（如果指定混流输出地址是 CDN 并且配置了这个协议的拉流域名）。

FLV string

HTTP-FLV 协议对应的 CDN 播放地址（如果指定混流输出地址是 CDN 并且配置了这个协议的拉流域名）。

Status integer

流状态。

UserName string

用户名称。

]

{
  "Code": 0,
  "Message": "success",
  "RequestId": "8472822294336370476",
  "Data": {
    "UserId": "123",
    "Sequence": 1,
    "RoomId": "room123",
    "PlayInfo": [
      {
        "StreamId": "test",
        "RTMP": "rtmp://domain/appname/test",
        "HLS": "http://domain/appname/test/playlist.m3u8",
        "FLV": "http://domain/appname/test.flv",
        "Status": 0,
        "UserName": ""
      }
    ]
  }
}

{
  "Code": 0,
  "Message": "success",
  "RequestId": "8472822294336370476",
  "Data": {
    "UserId": "123",
    "Sequence": 1,
    "RoomId": "room123",
    "PlayInfo": [
      {
        "StreamId": "test",
        "RTMP": "rtmp://domain/appname/test",
        "HLS": "http://domain/appname/test/playlist.m3u8",
        "FLV": "http://domain/appname/test.flv",
        "Status": 0,
        "UserName": ""
      }
    ]
  }
}

CURL

Base URL

https://rtc-api.zego.im

统一接入地址（不区分区域）

Parameters

Actionqueryrequired

AppIdqueryrequired

SignatureNoncequeryrequired

Timestampqueryrequired

Signaturequeryrequired

SignatureVersionqueryrequired

IsTestquery

Bodyrequired

Example (from schema)
Example

{
  "TaskId": "2213699902971205739",
  "UserId": "123",
  "RoomId": "room123",
  "ExtraMixInput": [
    {
      "StreamId": "room_other_stream1",
      "StreamUrl": "",
      "ModifyType": 0,
      "SoundLevelId": 0,
      "Volume": 100
    }
  ],
  "MixOutput": [
    {
      "StreamId": "stream3"
    }
  ],
  "Sequence": 0,
  "UserData": "base64_encoded_data",
  "SoundLevel": 0,
  "ByPass": 0,
  "SoundChannel": 1,
  "AlignmentType": 0,
  "RecvBufferLevel": 0,
  "ExPara": [
    {
      "Key": "k1",
      "Value": "v1"
    }
  ]
}

RESPONSEClear

Click the "Send" button above and see the response here!

StartAutoMix

https://rtc-api.zego.im/

前提条件

Request

Query Parameters

Body

Responses​

Responses