連麥功能

連麥模組(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 類型，詳細類型說明如下

範例：

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 類型，必傳，詳細類型說明如下

回傳值說明： 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 以觀眾模式加入連麥房間，僅訂閱講師流，不推本地流

在小班課場景下，觀眾可以透過此方法加入房間並觀看講師的流。 此方法僅在小班課場景下有效，且連麥已初始化（setupConnectMic）後才能呼叫。

Api 方法： joinAsAudience(): Promise<joinAsAudienceResult>

從 v2.13.0

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

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

### 3.2 离开观众模式

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

> 从 v2.13.0
``` 版本開始支援

<a id="classmethoddoc_plvconnectmicmodule_stopsmallclassstat"></a>

### 3.3 小班課場景停止統計

**Api 方法：** `stopSmallClassStat(): void`

> 從 v2.13.0 版本開始支援

<a id="classmethoddoc_plvconnectmicmodule_isaudiencemodejoined"></a>

### 3.4 目前是否為觀眾模式

**Api 方法：** `isAudienceModeJoined(): boolean`

> 從 v2.13.0 版本開始支援

## 四、裝置設定

<a id="classmethoddoc_plvconnectmicmodule_opendevicesetting"></a>

### 4.1 開啟裝置設定介面

連麥模組提供內建的裝置設定介面，透過 `openDeviceSetting` 方法開啟裝置設定介面，用於切換鏡頭、麥克風裝置等操作，當需要關閉時可呼叫 [closeDeviceSetting](/live/js/new_sdk/live_watch_sdk/articles/modules/connect-mic/function.md?id=classmethoddoc_plvconnectmicmodule_closedevicesetting) 進行關閉。

**Api 方法：** `openDeviceSetting(): void`

**範例：** 

```js
watchCore.connectMic.openDeviceSetting();

4.2 關閉裝置設定介面

Api 方法： closeDeviceSetting(): void

範例：

watchCore.connectMic.closeDeviceSetting();

五、鏡頭設定

5.1 開啟本地鏡頭

透過 enabledVideo 方法開啟本地鏡頭，可透過 ConnectMicEvents.LocalVideoMuteChange 事件監聽本地鏡頭的開關。

Api 方法： enabledVideo(): void

範例：

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

5.2 關閉本地鏡頭

透過 disabledVideo 方法關閉本地鏡頭，可透過 ConnectMicEvents.LocalVideoMuteChange 事件監聽本地鏡頭的開關。

Api 方法： disabledVideo(): void

範例：

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

5.3 切換前後鏡頭

Api 方法： changeFacingMode(facingMode: FacingMode): void

從 v2.6.0 版本開始支援

參數說明：

• facingMode：鏡頭模式，FacingMode 類型，必傳

範例：

watchCore.connectMic.changeFacingMode(FacingMode.Environment);

六、麥克風設定

6.1 開啟本地麥克風

透過 enabledAudio 方法開啟本地麥克風，可透過 ConnectMicEvents.LocalAudioMuteChange 事件監聽本地麥克風的開關。

Api 方法： enabledAudio(): void

範例：

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

6.2 關閉本地麥克風

透過 disabledAudio 方法關閉本地麥克風，可透過 ConnectMicEvents.LocalAudioMuteChange 事件監聽本地麥克風的開關。

Api 方法： disabledAudio(): void

範例：

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

七、邀請連麥

7.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('连麦失败，连麦人数已到达上限');
});

7.2 關閉邀請上麥介面

Api 方法： closeInviting(): void

範例：

watchCore.connectMic.closeInviting();

7.3 接受講師上麥邀請

用於在自訂邀請上麥 UI 中呼叫，觸發後等同於 SDK 內建邀請視窗的"同意"操作。

Api 方法： acceptInvite(): void

從 v2.17.0 版本開始支援

範例：

watchCore.connectMic.acceptInvite();

7.4 拒絕講師上麥邀請

用於在自訂邀請上麥 UI 中呼叫，觸發後等同於 SDK 內建邀請視窗的"拒絕"操作。

Api 方法： refuseInvite(): void

從 v2.17.0 版本開始支援

範例：

watchCore.connectMic.refuseInvite();

7.5 取得邀請上麥倒數計時

回傳目前邀請上麥的剩餘時間和總時間，可在 ConnectMicEvents.InviteCountDown 事件中使用。

Api 方法： getInviteCountDown(): InviteCountDownData

從 v2.17.0 版本開始支援

回傳值說明： InviteCountDownData 類型

範例：

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

八、本地預覽

8.1 開啟本地預覽

用於在連麥面板中預覽本地鏡頭，未連麥時呼叫，連麥中無需預覽。

Api 方法： startPreview(config: PreviewConfig): Promise<PreviewHandle>

從 v2.17.0

await watchCore.connectMic.startPreview({ videoEl: el, video: true });
``` 版本開始支援

**參數說明：** 

- config：`PreviewConfig` 類型，必傳

**回傳值說明：** `Promise<PreviewHandle>` 類型

**範例：** 

```ts

8.2 停止本地預覽

Api 方法： stopPreview(): void

從 v2.17.0 版本開始支援

範例：

watchCore.connectMic.stopPreview();

8.3 是否正在本地預覽

Api 方法： isPreviewing(): boolean

從 v2.17.0 版本開始支援

8.4 取得本地預覽的目前音量（0~1）

僅在預覽中可用；非預覽態回傳 0。

Api 方法： getPreviewVolume(): number

從 v2.17.0 版本開始支援

九、本地音視訊開關

9.1 取得目前本地音視訊靜音狀態

回傳 { video, audio }，true 表示已關閉/靜音。未連麥（預覽階段）時回傳裝置預設值，已連麥時回傳底層推流即時狀態。

Api 方法： getLocalMuteStatus(): Object

從 v2.17.0 版本開始支援

回傳值說明： Object 類型，詳細類型說明如下

9.2 預設/調整本地音視訊開關

未推流時僅寫入預設值，acceptInvite / publish 後生效；已推流時等價於呼叫 enable/disable 對應軌道。

Api 方法： setLocalMuteStatus(option: Object): void

從 v2.17.0 版本開始支援

參數說明：

• option：__PLV