连麦功能

连麦模块(connectMic) 提供连麦功能的集成，详细使用方式见下文。

一、设置连麦及连麦信息

1.1 设置连麦

观看页 SDK 默认不会设置连麦功能，如果需要连麦功能，开发者需要手动设置连麦功能，设置完成后即可调用连麦模块的 Api。

Api 方法： setupConnectMic(): Promise<ConnectMicResult>

返回值说明： 设置结果，Promise<ConnectMicResult> 类型

示例：

// 设置连麦功能
const result = await watchCore.connectMic.setupConnectMic();

if (result.success) {
  // 打开设备设置
  watchCore.connectMic.openDeviceSetting();
} else {
  console.log('设置失败', result.failReason);
}

1.2 是否支持连麦功能

用于判断当前环境是否支持连麦功能。

Api 方法： supportConnectMic(): SupportResult

返回值说明： SupportResult 类型

示例：

const result = watchCore.connectMic.supportConnectMic();
console.log('是否支持连麦：', result.support ? '支持' : '不支持');

1.3 获取连麦信息

连麦模块的状态，数据均通过 connectMicInfo 保存，开发者可通过 getConnectMicInfo 方法获取连麦信息。

PS：通过 ConnectMicEvents.ConnectMicInfoChange 事件监听连麦事件改变。

Api 方法： getConnectMicInfo(): ConnectMicStoreInfo

返回值说明： 连麦信息，ConnectMicStoreInfo 类型，详细类型说明如下

属性名	说明	类型
supportConnectMic	当前环境是否支持连麦	boolean
openMicStatus	连麦状态，开启或关闭	boolean
inviteStatus	邀请上麦状态	boolean
connectMicType	连麦类型	ConnectMicType
connectMicStatus	用户连麦状态	ConnectMicStatus
showJoinQueueNumberEnabled	连麦排序显示开关	boolean
currentMicIndex	连麦顺序索引值(-1 表示不在队列)	number
currentIsSpeaker	当前用户是否为主讲	boolean

示例：

const info = watchCore.connectMic.getConnectMicInfo();
console.log('当前是否支持连麦功能', data.supportConnectMic);
console.log('当前是否开启连麦', data.openMicStatus);

1.4 判断连麦状态是否处于连麦中

通过 isConnectMicing 判断用户或传入的状态是否处于连麦中（ConnectMicStatus.Publishing or ConnectMicStatus.Connected）。

Api 方法： isConnectMicing(status?: ConnectMicStatus): boolean

参数说明：

• status：连麦状态，不传则用当前状态，ConnectMicStatus 类型，选传

返回值说明： 是否连麦中

示例：

const res = watchCore.connectMic.isConnectMicing();
if (res) {
  console.log('用户连麦中');
} else {
  console.log('用户没有连麦');
}

二、观众上麦

2.1 观众申请连麦

当讲师/主播开启连麦功能后，用户即可申请连麦，开发者可调用 applyConnectMic 方法申请连麦，在申请时可调用 cancelApplyConnectMic 取消连麦申请。

PS: 通过 ConnectMicEvents.AllowConnectMicApply 监听连麦申请通过

Api 方法： applyConnectMic(): Promise<ConnectMicResult>

返回值说明： Promise<ConnectMicResult> 类型

示例：

import { ConnectMicError, ConnectMicEvents } from '@polyv/live-watch-sdk';

// 申请连麦
async function applyConnectMic() {
  const result = await watchCore.connectMic.applyConnectMic();
  if (result.success) {
    toast.success('连麦申请成功！请等待主播同意');
    const info = watchCore.connectMic.getConnectMicInfo();
    console.log('当前连麦状态：', info.connectMicStatus); // ConnectMicStatus.Applying
    return;
  }

  if (result.failReason === ConnectMicError.GetDevicePermissionFail) {
    toast.error('连麦申请失败！未获取设备权限');
  }
}

watchCore.connectMic.eventEmitter.on(ConnectMicEvents.AllowConnectMicApply, () => {
  toast.success('讲师已通过你的连麦申请');
});

2.2 取消连麦申请

当观众申请连麦后，调用 cancelApplyConnectMic 即可取消连麦申请。

Api 方法： cancelApplyConnectMic(): void

示例：

watchCore.connectMic.cancelApplyConnectMic();

const info = watchCore.connectMic.getConnectMicInfo();
console.log('当前连麦状态：', info.connectMicStatus); // ConnectMicStatus.NotConnect

2.3 取消连麦申请

当观众申请连麦后，调用 cancelApplyConnectMic 即可取消连麦申请。

Api 方法： cancelApplyConnectMic(): void

示例：

watchCore.connectMic.cancelApplyConnectMic();

const info = watchCore.connectMic.getConnectMicInfo();
console.log('当前连麦状态：', info.connectMicStatus); // ConnectMicStatus.NotConnect

2.4 推送本地连麦流

讲师通过连麦申请后，通过 publishLocalStream 进行连麦流推送，注意该方法需要在 ConnectMicEvents.LocalStreamInited 事件触发后调用。

推流成功后将触发 ConnectMicEvents.PublishStreamSuccess 事件。

建议通过连麦用户节点 ConnectMicItem.publishStream 方法进行推送。

Api 方法： publishLocalStream(options: PublishStreamOptions): Promise<ConnectMicResult>

参数说明：

• options：推流参数，PublishStreamOptions 类型，必传，详细类型说明如下

参数名	说明	类型	必须	默认值
element	渲染节点	HTMLDivElement	是	-
control	控制栏	boolean	否	true
fit	视频裁剪模式	ConnectMicFitType	否	ConnectMicFitType.Cover
profile	推流属性	StreamProfile	否	'240p'

返回值说明： Promise<ConnectMicResult> 类型

示例：

watchCore.connectMic.eventEmitter.on(ConnectMicEvents.LocalStreamInited, () => {
  watchCore.connectMic.publishLocalStream({
    element: 'NodeElement',
  });
});

2.5 结束连麦

当讲师通过观众的连麦申请并连麦成功后，通过 endConnectMic 可手动结束观众的连麦。

PS：通过 ConnectMicEvents.LeaveConnectMicSuccess 监听离开成功。

Api 方法： endConnectMic(): void

示例：

// 结束连麦
watchCore.connectMic.endConnectMic();

watchCore.connectMic.eventEmitter(ConnectMicEvents.LeaveConnectMicSuccess, () => {
  toast.success('结束连麦成功');
  const info = watchCore.connectMic.getConnectMicInfo();
  console.log('当前连麦状态：', info.connectMicStatus); // ConnectMicStatus.NotConnect
});

三、设备设置

3.1 打开设备设置界面

连麦模块提供内置的设备设置界面，通过 openDeviceSetting 方法打开设备设置界面，用于切换摄像头、麦克风设备等操作，当需要关闭时可调用 closeDeviceSetting 进行关闭。

Api 方法： openDeviceSetting(): void

示例：

watchCore.connectMic.openDeviceSetting();

3.2 关闭设备设置界面

Api 方法： closeDeviceSetting(): void

示例：

watchCore.connectMic.closeDeviceSetting();

四、摄像头设置

4.1 开启本地摄像头

通过 enabledVideo 方法开启本地摄像头，可通过 ConnectMicEvents.LocalVideoMuteChange 事件监听本地摄像头的开关。

Api 方法： enabledVideo(): void

示例：

// 开启本地摄像头
watchCore.connectMic.enabledVideo();

4.2 关闭本地摄像头

通过 disabledVideo 方法关闭本地摄像头，可通过 ConnectMicEvents.LocalVideoMuteChange 事件监听本地摄像头的开关。

Api 方法： disabledVideo(): void

示例：

// 关闭本地摄像头
watchCore.connectMic.disabledVideo();

五、麦克风设置

5.1 开启本地麦克风

通过 enabledAudio 方法开启本地麦克风，可通过 ConnectMicEvents.LocalAudioMuteChange 事件监听本地麦克风的开关。

Api 方法： enabledAudio(): void

示例：

// 开启本地麦克风
watchCore.connectMic.enabledAudio();

5.2 关闭本地麦克风

通过 disabledAudio 方法关闭本地麦克风，可通过 ConnectMicEvents.LocalAudioMuteChange 事件监听本地麦克风的开关。

Api 方法： disabledAudio(): void

示例：

// 关闭本地麦克风
watchCore.connectMic.disabledAudio();

六、邀请连麦

6.1 打开邀请上麦界面

连麦模块提供内置的邀请上麦界面，当监听到 ConnectMicEvents.InviteConnectMic 讲师邀请上麦事件后，通过 openInviting 方法打开邀请上麦界面，需要关闭时可调用 closeInviting 进行关闭。

PS: 观众点击同意时，可能因连麦人数到达上限而连麦失败，通过 ConnectMicEvents.ConnectMicOverLimit 事件监听并页面提示

Api 方法： openInviting(): void

示例：

import { ConnectMicEvents } from '@polyv/live-watch-sdk';

watchCore.connectMic.eventEmitter.on(ConnectMicEvents.InviteConnectMic, () => {
  // 打开邀请连麦窗口
  watchCore.connectMic.openInviting();
});
watchCore.connectMic.eventEmitter.on(ConnectMicEvents.ConnectMicOverLimit, () => {
  toast.error('连麦失败，连麦人数已到达上限');
});

6.2 关闭邀请上麦界面

Api 方法： closeInviting(): void

示例：

watchCore.connectMic.closeInviting();

七、连麦网络状态

7.1 获取连麦网络信息

Api 方法： getNetworkInfo(): ConnectMicNetworkInfo

返回值说明： 连麦网络信息，ConnectMicNetworkInfo 类型，详细类型说明如下

属性名	说明	类型
uplinkNetworkQuality	连麦上行网络质量	UplinkNetworkQuality
uplinkNetworkStatus	连麦上行网络状态	NetworkStatus
downlinkNetworkQuality	连麦下行网络质量	DownlinkNetworkQuality
downlinkNetworkStatus	连麦下行网络状态	NetworkStatus

示例：

const network = watchCore.connectMic.getNetworkInfo();
console.log('推流网络状态', network.uplinkNetworkStatus);
console.log('拉流网络状态', network.downlinkNetworkStatus);

八、其他

8.1 用户连麦状态

Enum 枚举： ConnectMicStatus

常量	枚举成员	说明
'notConnect'	ConnectMicStatus.NotConnect	未连麦
'applying'	ConnectMicStatus.Applying	连麦申请中
'publishing'	ConnectMicStatus.Publishing	推流中
'connected'	ConnectMicStatus.Connected	已连麦
'error'	ConnectMicStatus.Error	连麦异常

8.2 连麦类型

用于区分讲师开启的是视频连麦或音频连麦

Enum 枚举： ConnectMicType

常量	枚举成员	说明
'video'	ConnectMicType.Video	视频连麦
'audio'	ConnectMicType.Audio	音频连麦