Connect Mic Feature

The connect mic module (connectMic) provides integration for the connect mic feature. See below for detailed usage.

1. Setting Up Connect Mic and Connect Mic Info

1.1 Setting Up Connect Mic

The viewer page SDK does not enable the connect mic feature by default. If the connect mic feature is needed, developers must manually set it up. After setup, the APIs of the connect mic module can be called.

API Method: setupConnectMic(): Promise<ConnectMicResult>

Return Value Description: Setup result, type Promise<ConnectMicResult>

Example:

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

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

1.2 Whether Connect Mic is Supported

Used to determine if the current environment supports the connect mic feature.

API Method: supportConnectMic(): SupportResult

Return Value Description: Type SupportResult

Example:

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

1.3 Getting Connect Mic Info

The status and data of the connect mic module are stored via connectMicInfo. Developers can obtain connect mic info using the getConnectMicInfo method.

PS: Listen for connect mic event changes via the ConnectMicEvents.ConnectMicInfoChange event.

API Method: getConnectMicInfo(): ConnectMicStoreInfo

Return Value Description: Connect mic info, type ConnectMicStoreInfo. Detailed type description is as follows:

Example:

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

1.4 Checking if Connect Mic Status is Currently Connected

Use isConnectMicing to check if the user or the passed status is currently connected (ConnectMicStatus.Publishing or ConnectMicStatus.Connected).

API Method: isConnectMicing(status?: ConnectMicStatus): boolean

Parameter Description:

• status: Connect mic status, if not passed, uses the current status, type ConnectMicStatus, optional

Return Value Description: Whether currently connected

Example:

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

2. Viewer Going on Stage

2.1 Viewer Applies for Connect Mic

When the instructor/main speaker enables the connect mic feature, users can apply for connect mic. Developers can call the applyConnectMic method to apply. During the application, cancelApplyConnectMic can be called to cancel the application.

PS: Listen for connect mic application approval via ConnectMicEvents.AllowConnectMicApply

API Method: applyConnectMic(): Promise<ConnectMicResult>

Return Value Description: Type Promise<ConnectMicResult>

Example:

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 Canceling Connect Mic Application

After a viewer applies for connect mic, call cancelApplyConnectMic to cancel the application.

API Method: cancelApplyConnectMic(): void

Example:

watchCore.connectMic.cancelApplyConnectMic();

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

2.3 Canceling Connect Mic Application

After a viewer applies for connect mic, call cancelApplyConnectMic to cancel the application.

API Method: cancelApplyConnectMic(): void

Example:

watchCore.connectMic.cancelApplyConnectMic();

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

2.4 Publishing Local Connect Mic Stream

After the instructor approves the connect mic application, use publishLocalStream to publish the connect mic stream. Note that this method should be called after the ConnectMicEvents.LocalStreamInited event is triggered.

Successful stream publishing will trigger the ConnectMicEvents.PublishStreamSuccess event.

It is recommended to use the ConnectMicItem.publishStream method on the connect mic user node for publishing.

API Method: publishLocalStream(options: PublishStreamOptions): Promise<ConnectMicResult>

Parameter Description:

• options: Publishing parameters, type PublishStreamOptions, required. Detailed type description is as follows:

Return Value Description: Type Promise<ConnectMicResult>

Example:

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

2.5 Ending Connect Mic

After the instructor approves the viewer's connect mic application and the connection is successful, use endConnectMic to manually end the viewer's connect mic.

PS: Listen for successful leave via ConnectMicEvents.LeaveConnectMicSuccess.

API Method: endConnectMic(): void

Example:

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

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

3. Small Class Scenario Connect Mic

3.1 Joining Connect Mic Room as Viewer, Only Subscribing to Instructor Stream, Not Publishing Local Stream

In the small class scenario, viewers can use this method to join the room and watch the instructor's stream. This method is only valid in the small class scenario and can only be called after connect mic has been initialized (setupConnectMic).

API Method: joinAsAudience(): Promise<joinAsAudienceResult>

Supported from version v2.13.0

**返回值说明：** 加入结果，`Promise<joinAsAudienceResult>` 类型

<a id="classmethoddoc_plvconnectmicmodule_leaveaudience"></a>

### 3.2 离开观众模式

**Api 方法：** `leaveAudience(): Promise<void>`

> 从 v2.13.0

3.3 Stopping Statistics in Small Class Scenario

API Method: stopSmallClassStat(): void

Supported from version v2.13.0

3.4 Whether Currently in Viewer Mode

API Method: isAudienceModeJoined(): boolean

Supported from version v2.13.0

4. Device Settings

4.1 Opening Device Settings Interface

The connect mic module provides a built-in device settings interface. Use the openDeviceSetting method to open the device settings interface for operations like switching cameras and microphone devices. When it needs to be closed, call closeDeviceSetting.

API Method: openDeviceSetting(): void

Example:

watchCore.connectMic.openDeviceSetting();

4.2 Closing Device Settings Interface

API Method: closeDeviceSetting(): void

Example:

watchCore.connectMic.closeDeviceSetting();

5. Camera Settings

5.1 Enabling Local Camera

Use the enabledVideo method to enable the local camera. Listen for local camera on/off via the ConnectMicEvents.LocalVideoMuteChange event.

API Method: enabledVideo(): void

Example:

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

5.2 Disabling Local Camera

Use the disabledVideo method to disable the local camera. Listen for local camera on/off via the ConnectMicEvents.LocalVideoMuteChange event.

API Method: disabledVideo(): void

Example:

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

5.3 Switching Front/Rear Camera

API Method: changeFacingMode(facingMode: FacingMode): void

Supported from version v2.6.0

Parameter Description:

• facingMode: Camera mode, type FacingMode, required

Example:

watchCore.connectMic.changeFacingMode(FacingMode.Environment);

6. Microphone Settings

6.1 Enabling Local Microphone

Use the enabledAudio method to enable the local microphone. Listen for local microphone on/off via the ConnectMicEvents.LocalAudioMuteChange event.

API Method: enabledAudio(): void

Example:

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

6.2 Disabling Local Microphone

Use the disabledAudio method to disable the local microphone. Listen for local microphone on/off via the ConnectMicEvents.LocalAudioMuteChange event.

API Method: disabledAudio(): void

Example:

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

7. Inviting Connect Mic

7.1 Opening Invitation to Go on Stage Interface

The connect mic module provides a built-in invitation to go on stage interface. When the ConnectMicEvents.InviteConnectMic event (instructor invites to go on stage) is triggered, use the openInviting method to open the invitation interface. When it needs to be closed, call closeInviting.

PS: When a viewer clicks agree, the connection might fail due to reaching the maximum number of connected users. Listen for this via the ConnectMicEvents.ConnectMicOverLimit event and display a prompt on the page.

API Method: openInviting(): void

Example:

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

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

7.2 Closing Invitation to Go on Stage Interface

API Method: closeInviting(): void

Example:

watchCore.connectMic.closeInviting();

7.3 Accepting Instructor's Invitation to Go on Stage

Used in a custom invitation to go on stage UI. Triggering this is equivalent to clicking "Agree" in the SDK's built-in invitation window.

API Method: acceptInvite(): void

Supported from version v2.17.0

Example:

watchCore.connectMic.acceptInvite();

7.4 Refusing Instructor's Invitation to Go on Stage

Used in a custom invitation to go on stage UI. Triggering this is equivalent to clicking "Refuse" in the SDK's built-in invitation window.

API Method: refuseInvite(): void

Supported from version v2.17.0

Example:

watchCore.connectMic.refuseInvite();

7.5 Getting Invitation to Go on Stage Countdown

Returns the remaining time and total time for the current invitation to go on stage. Can be used in the ConnectMicEvents.InviteCountDown event.

API Method: getInviteCountDown(): InviteCountDownData

Supported from version v2.17.0

Return Value Description: Type InviteCountDownData

Example:

const { remain, total } = watchCore.connectMic.getInviteCountDown();
console.log(`剩余 ${remain}s / 总 ${total}s`);

8. Local Preview

8.1 Starting Local Preview

Used to preview the local camera in the connect mic panel. Call this when not connected; preview is not needed during an active connection.

API Method: startPreview(config: PreviewConfig): Promise<PreviewHandle>

Supported from version v2.17.0

await watchCore.connectMic.startPreview({ videoEl: el, video: true });

Parameter Description:

• config: Type PreviewConfig, required

Return Value Description: Type Promise<PreviewHandle>

Example:

8.2 Stopping Local Preview

API Method: stopPreview(): void

Supported from version v2.17.0

Example:

watchCore.connectMic.stopPreview();

8.3 Whether Currently in Local Preview

API Method: isPreviewing(): boolean

Supported from version v2.17.0

8.4 Getting Current Volume of Local Preview (0~1)

Only available during preview; returns 0 when not in preview state.

API Method: getPreviewVolume(): number

Supported from version v2.17.0

9. Local Audio/Video Toggle

9.1 Getting Current Local Audio/Video Mute Status

Returns { video, audio }, where true means disabled/muted. Returns the device preset value when not connected (preview stage), and the real-time underlying publishing stream status when connected.

API Method: getLocalMuteStatus(): Object

Supported from version v2.17.0

Return Value Description: Type Object. Detailed type description is as follows:

9.2 Presetting/Adjusting Local Audio/Video Toggle

When not publishing, this only writes the preset value, which takes effect after acceptInvite / publish. When already publishing, it is equivalent to calling enable/disable on the corresponding track.

API Method: setLocalMuteStatus(option: Object): void

Supported from version v2.17.0

Parameter Description:

• option: Type Object, required. Detailed type description is as follows:

10. Connect Mic Network Status

10.1 Getting Connect Mic Network Info

API Method: getNetworkInfo(): ConnectMicNetworkInfo

Return Value Description: Connect mic network info, type ConnectMicNetworkInfo. Detailed type description is as follows:

Example:

_PLV_KEEP