AOQ Client SDK Electron API 參考

適用包：aoq-electron-sdk（npm）。支援平台：macOS（x64 / arm64）、Windows x64；Node.js >= 16。

介面目錄

引擎入口與生命週期

介面	簡介
createAoqClientEngine	擷取引擎封裝執行個體（模組層級懶載入單例）
createEngine	建立 native 引擎執行個體
destroy	銷毀引擎執行個體
getVersion	擷取 SDK 版本號碼
connect	串連 Relay 伺服器
disconnect	斷開伺服器串連

音訊裝置管理

介面	簡介
startAudioCapture	開啟音頻採集裝置（麥克風）
stopAudioCapture	關閉音頻採集裝置
muteAudioCapture	靜音或取消靜音音頻採集
startAudioPlayer	開始音頻渲染（播放遠端音頻）
stopAudioPlayer	停止音頻渲染
pauseAudioPlayer	暫停音頻渲染，支援淡出
resumeAudioPlayer	恢複音頻渲染，支援淡入
interruptAudioPlayer	打斷本輪語音通話

音頻編解碼配置

介面	簡介
setAudioEncoderConfig	設定音頻編碼參數
setAudioDecoderConfig	設定音頻解碼參數

視頻裝置管理

介面	簡介
startVideoCapture	開啟視頻採集裝置（網路攝影機）
stopVideoCapture	關閉視頻採集裝置

視頻編解碼與外部輸入

介面	簡介
setVideoEncoderConfig	設定視頻編碼參數
setVideoDecoderConfig	設定視頻解碼參數
pushExternalVideoCapturedFrame	推送外部採集視訊框架
pushExternalVideoEncodedFrame	推送外部已編碼視訊框架

媒體流發送控制

介面	簡介
enableSendMediaStream	控制本地媒體流的發送開關

音頻檔案播放

介面	簡介
startAudioFile	開始推流播放本地音頻檔案
stopAudioFile	停止音頻檔案播放
pauseAudioFile	暫停音頻檔案播放
resumeAudioFile	恢複音頻檔案播放
getAudioFileDuration	擷取音頻檔案總時間長度
getAudioFileCurrentPosition	擷取音頻檔案當前播放位置
setAudioFilePositionMillis	設定音頻檔案播放位置（seek）
setAudioFileVolume	設定音頻檔案音量
getAudioFileVolume	擷取音頻檔案當前音量

外部音頻流

介面	簡介
addAudioExternalStream	新增一條外部音頻流
removeAudioExternalStream	移除外部音頻流
pushAudioExternalStreamData	輸入外部音頻 PCM 資料
setAudioExternalStreamVolume	設定外部音頻流音量
getAudioExternalStreamVolume	擷取外部音頻流音量
clearAudioExternalStreamBuffer	清空外部音頻流緩衝

即時訊息

介面	簡介
sendDataMsg	發送即時資料訊息

音訊框架回調

介面	簡介
setAudioFrameObserver	開啟或關閉音訊框架資料觀察者
enableAudioFrameObserver	開啟或關閉指定位置的音訊框架回調

本地音量提示

介面	簡介
enableLocalAudioVolumeIndication	開啟或關閉本地採集音量提示回調

視訊框架回調

介面	簡介
setVideoFrameObserver	開啟或關閉視訊框架資料觀察者
enableVideoFrameObserver	開啟或關閉指定位置的視訊框架回調

視頻渲染（YUVCanvasRenderer）

介面	簡介
bind	綁定 canvas 元素
unbind	解除綁定並清空畫面
bound	查詢當前是否已綁定
drawFrame	繪製一幀 I420 視頻資料

引擎事件（IAoqEngineEvents）

事件	簡介
onError	引擎錯誤回調
onWarning	引擎警告回調
onConnectionStatusChange	串連狀態變化回調
onStats	引擎統計資訊回調
onAudioDeviceStateChanged	音訊裝置操作狀態變化回調
onAudioDeviceRouteChanged	音訊輸出路由變化回調
onAudioFileState	音頻檔案播放狀態回調
onLocalAudioVolumeIndication	本地採集音量提示回調
onVideoDeviceStateChanged	視頻裝置操作狀態變化回調
onDataMsg	收到即時資料訊息回調
onCapturedAudioFrame	採集裸音頻資料回調
onProcessCapturedAudioFrame	3A 處理後音頻資料回調
onPublishAudioFrame	推流音頻資料回調
onPlaybackAudioFrame	播放音頻資料回調
onCapturedVideoFrame	本地採集後裸視頻資料回調
onPreEncodeVideoFrame	本地編碼前裸視頻資料回調
onRemoteVideoFrame	遠端解碼後、渲染前視頻資料回調

介面詳情

引擎入口與生命週期

createAoqClientEngine

擷取引擎封裝執行個體。模組層級懶載入單例，重複調用返回同一執行個體，與 native 引擎單例語義對齊；也是包的 default export。

import createAoqClientEngine from 'aoq-electron-sdk';
export function createAoqClientEngine(): IAoqClientEngine

傳回值：IAoqClientEngine 引擎執行個體。注意本方法僅建立 JS 封裝層與 native bridge，真正建立引擎需再調 createEngine()。

createEngine

建立 native 引擎執行個體。引擎為全域單例，重複調用直接返回成功。

createEngine(config: AoqCreateConfig): number

參數	類型	說明
config	AoqCreateConfig	引擎建立配置

傳回值：0 成功；-1 表示建立失敗或參數不是合法 JSON。

Windows 上 createEngine() 會在當前 JS 線程的 libuv 迴圈上掛一個 16ms 的 Win32 訊息泵（網路攝影機採集依賴），destroy() 時停掉；因此不要在 createEngine() 之後長時間同步阻塞 JS 線程。

destroy

銷毀引擎執行個體，釋放所有資源。

destroy(): number

傳回值：0 表示成功；非 0 表示失敗。引擎未建立時返回 0。

getVersion

擷取 SDK 目前的版本號，無需先調 createEngine()。

getVersion(): string

傳回值：版本號碼字串，如 "1.2.0"；取不到時返回Null 字元串。

connect

串連 Relay 伺服器。業務 AppServer 應根據所用協議擷取臨時 AOQ 串連參數並下發給用戶端，具體操作請參見Token 鑒權。

connect(config: AoqConnectConfig): number

參數	類型	說明
config	AoqConnectConfig	串連配置，包含 Token、SID、Relay 存取點列表、推拉流 track 列表等

傳回值：0 表示調用已下發（非同步執行）；非 0 表示參數校正失敗。串連結果由 onConnectionStatusChange 事件通知。

disconnect

斷開與伺服器的串連，釋放串連相關資源。

disconnect(): number

傳回值：0 表示調用已下發（非同步執行）；非 0 表示失敗。

音訊裝置管理

startAudioCapture

startAudioCapture(config: AoqAudioCaptureConfig): number

開啟音頻採集裝置（麥克風）。首次採集會觸發系統授權，macOS 需在應用 Info.plist 中聲明 NSMicrophoneUsageDescription。

stopAudioCapture

stopAudioCapture(): number

關閉音頻採集裝置。

muteAudioCapture

muteAudioCapture(mute: boolean): number

靜音或取消靜音音頻採集。mute=true 靜音，false 取消靜音。

startAudioPlayer

startAudioPlayer(config: AoqAudioPlaybackConfig): number

開始音頻渲染（播放遠端音頻）。

stopAudioPlayer / pauseAudioPlayer / resumeAudioPlayer

stopAudioPlayer(): number
pauseAudioPlayer(fadeMs: number): number
resumeAudioPlayer(fadeMs: number): number

fadeMs：淡出/淡入時間長度（毫秒）；0 表示立即執行。

interruptAudioPlayer

interruptAudioPlayer(trackType: AoqTrackType, fadeMs: number): number

打斷本輪語音通話，丟棄已緩衝的本輪下行資料。

參數	類型	說明
trackType	AoqTrackType	軌道類型
fadeMs	number	淡出時間長度（毫秒）

音頻編解碼配置

setAudioEncoderConfig(config: AoqAudioCodecConfig): number
setAudioDecoderConfig(config: AoqAudioCodecConfig): number

建議在 connect() 之前調用。使用 Opus（AoqEncoderTypeAudioOpus）需 SDK 內建或隨包分發 PluginOpus 外掛程式。

視頻裝置管理

startVideoCapture(config: AoqVideoCaptureConfig): number
stopVideoCapture(): number

開啟/關閉視頻採集裝置。macOS 需在 Info.plist 中聲明 NSCameraUsageDescription。當 config.isExternal=true 時不開啟網路攝影機，由 pushExternalVideoCapturedFrame 送幀。

Electron renderer 為 Chromium 環境，無法嵌入原生視圖，因此未提供 setLocalView / setRemoteView / switchCamera；預覽請使用「幀觀察者 + YUVCanvasRenderer」（見 2.13）。

視頻編解碼與外部輸入

setVideoEncoderConfig(config: AoqVideoCodecConfig): number
setVideoDecoderConfig(config: AoqVideoCodecConfig): number
pushExternalVideoCapturedFrame(meta: AoqExternalVideoFrameMeta, buffer: Uint8Array): number
pushExternalVideoEncodedFrame(meta: AoqExternalVideoEncodedFrameMeta, buffer: Uint8Array): number

參數	類型	說明
meta	AoqExternalVideoFrameMeta / AoqExternalVideoEncodedFrameMeta	幀元資訊（尺寸、格式、時間戳記）
buffer	Uint8Array	幀資料（像素資料或已編碼資料）

注意：

pushExternalVideoCapturedFrame 僅在 startVideoCapture({ isExternal: true }) 後被消費；未開啟時返回 211，緩衝區滿時返回 210。
支援 AoqVideoPixelFormatI420 與打包格式（NV12 / NV21 / BGRA / RGBA）；I420 時 buffer 必須為緊湊布局（stride = width），Y / U / V 三平面順序拼接。
pushExternalVideoEncodedFrame 需先 setVideoEncoderConfig({ isExternal: true })；未開啟時返回 212。當前僅支援 JPEG。
meta.timeStamp 為 0 時由 SDK 使用本地時間補齊。

媒體流發送控制

enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number

控制本地某路媒體流是否發送。建議初始化後先 enableSendMediaStream(trackType, false)，待 onConnectionStatusChange 上報 AoqConnectionStatusConnected 後再開啟。

音頻檔案播放

startAudioFile(config: AoqAudioFileMixConfig): number
stopAudioFile(fileId: string): number
pauseAudioFile(fileId: string): number
resumeAudioFile(fileId: string): number
getAudioFileDuration(fileId: string): number
getAudioFileCurrentPosition(fileId: string): number
setAudioFilePositionMillis(fileId: string, positionMs: number): number
setAudioFileVolume(fileId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioFileVolume(fileId: string, type: AoqAudioStreamDirection): number

參數	類型	說明
config	AoqAudioFileMixConfig	檔案混音配置，`fileId` 作為配置欄位攜帶
fileId	string	檔案標識，由調用方定義，後續介面以此定位
positionMs	number	目標播放位置（毫秒）
type	AoqAudioStreamDirection	推流音量或本地播放音量
volume	number	音量，取值範圍 0-100

傳回值說明：

getAudioFileDuration / getAudioFileCurrentPosition 返回毫秒數；
getAudioFileVolume 返回當前音量值；
上述 getter 在引擎未建立時返回 -1。

播放狀態變化通過 onAudioFileState 事件上報。

外部音頻流

addAudioExternalStream(config: AoqAudioExternalStreamConfig): number
removeAudioExternalStream(streamId: string): number
pushAudioExternalStreamData(meta: AoqAudioExternalFrameMeta, buffer: Uint8Array): number
setAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection): number
clearAudioExternalStreamBuffer(streamId: string, fadeoutMs: number): number

參數	類型	說明
config	AoqAudioExternalStreamConfig	外部音頻流配置，`streamId` 作為配置欄位攜帶
streamId	string	流標識，由調用方定義
meta	AoqAudioExternalFrameMeta	PCM 幀元資訊，`streamId` 作為元資訊欄位攜帶
buffer	Uint8Array	PCM 資料
fadeoutMs	number	清空緩衝時的淡出時間長度（毫秒）

注意：

pushAudioExternalStreamData 緩衝時間長度超過 maxBufferDuration 時返回 110（外部音頻緩衝區滿）。
getAudioExternalStreamVolume 返回當前音量值；引擎未建立時返回 -1。
clearAudioExternalStreamBuffer native 側無傳回值，調用成功固定返回 0。

即時訊息

sendDataMsg(data: Uint8Array | string): number

發送即時資料訊息。傳入 string 時內部按 UTF-8 編碼為 Buffer 後發送。對端訊息通過 onDataMsg 事件回調。

音訊框架回調

setAudioFrameObserver(enable: boolean): number
enableAudioFrameObserver(params: AoqAudioObserverParams): number

參數	類型	說明
enable	boolean	`true` 註冊內建音訊框架觀察者，`false` 登出
params	AoqAudioObserverParams	指定回調位置、開關與回調格式

使用步驟：先 setAudioFrameObserver(true) 註冊觀察者，再對需要的位置調 enableAudioFrameObserver，資料通過對應事件下發。

engine.setAudioFrameObserver(true)
engine.enableAudioFrameObserver({
  enabled: true,
  audioSource: AoqAudioSource.AoqAudioSourceCaptured,
  sampleRate: 48000,
  channels: 1
})
engine.on('onCapturedAudioFrame', (frame) => { /* frame.buffer 為 PCM 資料 */ })

Electron 側幀觀察者僅支援唯讀模式，回調中不支援回寫幀資料（native 內部固定 ReadOnly）。

本地音量提示

enableLocalAudioVolumeIndication(config: AoqAudioVolumeIndicationConfig): number

開啟/關閉本地採集音量提示。config.interval <= 0 時關閉回調；開啟後按 config.interval 周期觸發 onLocalAudioVolumeIndication。需在 startAudioCapture() 之後調用才有音量資料。

視訊框架回調

setVideoFrameObserver(enable: boolean): number
enableVideoFrameObserver(params: AoqVideoObserverParams): number

參數	類型	說明
enable	boolean	`true` 註冊內建視訊框架觀察者，`false` 登出
params	AoqVideoObserverParams	指定回調位置、開關、像素格式與對齊策略

回調資料以 AoqVideoFrameEvent 形式通過 onCapturedVideoFrame / onPreEncodeVideoFrame / onRemoteVideoFrame 下發；I420 時 buffer 為 Y / U / V 三平面按 stride 拼接，其餘打包格式為原資料透傳。同樣僅支援唯讀模式。

視頻渲染（YUVCanvasRenderer）

SDK 內建的軟渲染器，承擔移動端 setLocalView / setRemoteView 的預覽職責。

import { YUVCanvasRenderer } from 'aoq-electron-sdk';

class YUVCanvasRenderer {
  bind(canvas: HTMLCanvasElement): void
  unbind(): void
  get bound(): boolean
  drawFrame(frame: AoqVideoFrameEvent): void
}

介面	說明
bind	綁定 canvas（重複綁定會替換 sink）
unbind	解除綁定並清空畫面
bound	是否已綁定
drawFrame	繪製一幀；僅支援 I420，非 I420 / 尺寸或 buffer 長度不足時靜默返回

const renderer = new YUVCanvasRenderer()
renderer.bind(document.getElementById('preview'))

engine.setVideoFrameObserver(true)
engine.enableVideoFrameObserver({
  enabled: true,
  videoSource: AoqVideoSource.AoqVideoSourceCaptured,
  format: AoqVideoPixelFormat.AoqVideoPixelFormatI420
})
engine.on('onCapturedVideoFrame', (frame) => renderer.drawFrame(frame))

渲染填充模式（展開 / 裁剪等）用 CSS object-fit 控制 canvas 即可。

引擎事件（IAoqEngineEvents）

引擎繼承 EventEmitter<IAoqEngineEvents>，事件是 SDK 所有非同步通知的統一出口，與 native AoqEngineEventListener 回調一一對應。不關心的事件無需註冊。

engine.on('onError', (code, message) => {})
engine.off('onError', handler)
engine.once('onStats', (stats) => {})
engine.removeAllListeners()

onError

onError: (code: number, message: string) => void

引擎錯誤回調。code 對應 AoqErrorCode 數值（見 3.3）。

onWarning

onWarning: (code: number, message: string) => void

引擎警告回調。code 對應 AoqWarningCode 數值（見 3.3）。

onConnectionStatusChange

onConnectionStatusChange: (status: AoqConnectionStatus) => void

串連狀態變化回調。狀態流轉：Disconnected -> Connecting -> Connected / Failed -> Disconnected。

onStats

onStats: (stats: AoqStats) => void

引擎統計資訊回調。SDK 周期性上報音視頻推拉流及網路統計資料，可用於即時監測通話品質、網路狀態、診斷音視頻問題。

參數	類型	說明
stats	AoqStats	包含音頻 / 視頻 / 資料訊息的推拉流統計及網路統計

onAudioDeviceStateChanged

onAudioDeviceStateChanged: (state: AoqAudioDeviceState) => void

音訊裝置採集 / 播放操作狀態變化回調。

onAudioDeviceRouteChanged

onAudioDeviceRouteChanged: (routeType: number) => void

音訊輸出路由變化回調。routeType 對應 AoqAudioDeviceRouteType 數值（見 3.4）。

onAudioFileState

onAudioFileState: (state: AoqAudioFileState) => void

音頻檔案播放狀態回調。

onLocalAudioVolumeIndication

onLocalAudioVolumeIndication: (volume: AoqAudioVolume) => void

本地採集音量提示回調，需調用 enableLocalAudioVolumeIndication 開啟。

onVideoDeviceStateChanged

onVideoDeviceStateChanged: (state: AoqVideoDeviceState) => void

視頻裝置採集操作狀態變化回調。

onDataMsg

onDataMsg: (data: Uint8Array) => void

收到即時資料訊息回調。data 為 native 側拷貝後的 Buffer，可安全非同步持有；簡訊用 Buffer.from(data).toString() 轉字串。

音訊框架事件

onCapturedAudioFrame:        (frame: AoqAudioFrameEvent) => void  /* 採集裸資料 */
onProcessCapturedAudioFrame: (frame: AoqAudioFrameEvent) => void  /* 3A 後資料 */
onPublishAudioFrame:         (frame: AoqAudioFrameEvent) => void  /* 推流資料 */
onPlaybackAudioFrame:        (frame: AoqAudioFrameEvent) => void  /* 播放資料 */

需先調 setAudioFrameObserver(true) 與 enableAudioFrameObserver 開啟。

視訊框架事件

onCapturedVideoFrame:  (frame: AoqVideoFrameEvent) => void  /* 採集後（前處理前） */
onPreEncodeVideoFrame: (frame: AoqVideoFrameEvent) => void  /* 編碼前（前處理後） */
onRemoteVideoFrame:    (frame: AoqVideoFrameEvent) => void  /* 遠端解碼後、渲染前 */

需先調 setVideoFrameObserver(true) 與 enableVideoFrameObserver 開啟。幀事件為唯讀，回調中修改 buffer 不會寫回 SDK。

事件回調中避免重計算：native 回調經非同步線程投遞到 JS 主線程，高頻幀事件中做耗時操作會造成堆積。

資料類型與枚舉

所有類型均從包根匯出，可直接 import { ... } from 'aoq-electron-sdk'。枚舉為 TypeScript enum，運行時可用；介面（interface）僅類型約束。標記為可選的欄位預設時取表中預設值。

通用類型

AoqCreateConfig

欄位	類型	必填	預設值	說明
workDir	string	否	""	SDK 工作目錄（日誌與臨時檔案）
enableDumpAudio	boolean	否	false	是否開啟音頻資料儲存（調試用）
extras	string	否	""	擴充參數（JSON 字串）

Android 的 isBTScoMode 為移動端欄位，Electron 不提供。

AoqConnectConfig

欄位	類型	必填	預設值	說明
token	string	是	-	串連鑒權 Token
sid	string	是	-	會話 ID
certFingerprint	string	否	""	伺服器憑證指紋
workspaceIdHash	string	否	空	工作空間 ID Hash；Null 字元串等同不傳
relayEndpoints	Array	是	-	Relay 存取點列表
publishTracks	Array	是	-	本端發布軌道列表
subscribeTracks	Array	是	-	本端訂閱軌道列表

AoqRelayEndpoint

欄位	類型	必填	預設值	說明
routeIndex	number	否	-1	路由序號
endpoint	string	是	-	Relay 伺服器網域名稱或 IP
port	number	是	-	Relay 伺服器連接埠

AoqTrackParam

欄位	類型	必填	預設值	說明
trackType	AoqTrackType	是	-	軌道類型
trackMode	AoqTrackMode	否	AoqTrackModeSegment	流式 / 非流式模式，僅對音頻下行生效

統計資訊類型

AoqStats

引擎統計資訊匯總，通過 onStats 周期性上報。數組欄位無資料時為空白數組，networkStats 無資料時不下發。

欄位	類型	說明
audioPublishStats	Array	音頻推流統計
videoPublishStats	Array	視頻推流統計
dataMsgPublishStats	Array	資料訊息推流統計
audioSubscribeStats	Array	音頻拉流統計
videoSubscribeStats	Array	視頻拉流統計
dataMsgSubscribeStats	Array	資料訊息拉流統計
networkStats	AoqNetworkStats	網路統計資訊

AoqAudioPublishStats

欄位	類型	說明
trackType	AoqTrackType	軌道類型
bitrate	number	碼率（bps）
bytes	number	累計發送位元組數
encodeVolume	number	推流編碼音量

AoqAudioSubscribeStats

欄位	類型	說明
trackType	AoqTrackType	軌道類型
bitrate	number	碼率（bps）
bytes	number	累計接收位元組數
playVolume	number	播放音量

AoqVideoPublishStats

欄位	類型	說明
trackType	AoqTrackType	軌道類型
bitrate	number	碼率（bps）
bytes	number	累計發送位元組數
encodeFps	number	編碼幀率

AoqVideoSubscribeStats

欄位	類型	說明
trackType	AoqTrackType	軌道類型
bitrate	number	碼率（bps）
bytes	number	累計接收位元組數
decodeFps	number	解碼幀率
renderFps	number	渲染幀率

AoqDataMsgPublishStats / AoqDataMsgSubscribeStats

欄位	類型	說明
trackType	AoqTrackType	軌道類型
bitrate	number	碼率（bps）
bytes	number	累計發送 / 接收位元組數

AoqNetworkStats

欄位	類型	說明
sendBitrate	number	發送碼率（bps）
sendBytes	number	累計發送位元組數
recvBitrate	number	接收碼率（bps）
recvBytes	number	累計接收位元組數
loss	number	丟包率（0-100）
rtt	number	往返延遲（ms）

枚舉類型

AoqTrackType

枚舉值	值	說明
AoqTrackTypeAudio	0	音頻軌道
AoqTrackTypeVideo	1	視頻軌道
AoqTrackTypeData	2	資料訊息軌道

AoqTrackMode

枚舉值	值	說明
AoqTrackModeSegment	0	分段：資料按語義片段（如一句話）打包送達
AoqTrackModeStream	1	流式：資料持續、連續地送達

AoqEncoderType

枚舉值	值	說明
AoqEncoderTypeUnknown	0	未知格式
AoqEncoderTypeAudioPCM	1	音頻 PCM
AoqEncoderTypeAudioOpus	2	音頻 Opus（外掛程式化，需 PluginOpus）
AoqEncoderTypeVideoH264	3	視頻 H.264
AoqEncoderTypeVideoJpeg	4	視頻 JPEG
AoqEncoderTypeDataText	5	資料文本

AoqConnectionStatus

枚舉值	值	說明
AoqConnectionStatusDisconnected	0	未串連
AoqConnectionStatusConnecting	1	串連中
AoqConnectionStatusConnected	2	已串連
AoqConnectionStatusFailed	3	串連失敗

AoqMirrorMode

枚舉值	值	說明
AoqMirrorModeDisabled	0	關閉鏡像
AoqMirrorModeEnabled	1	開啟鏡像

AoqOrientationMode

枚舉值	值	說明
AoqOrientationModeAuto	0	自動適應
AoqOrientationModePortrait	1	豎屏
AoqOrientationModeLandscape	2	橫屏

AoqErrorCode

錯誤碼為 native 層定義，onError 的 code 與介面傳回值均使用該數值（TS 層未將其匯出為 enum）。

枚舉值	值	說明
AoqErrorCodeOK	0	成功
AoqErrorCodeParamInvalid	1	參數非法
AoqErrorCodeStateInvalid	2	狀態非法
AoqErrorCodeUnSupport	3	當前平台 / 模式不支援
AoqErrorCodeAudio	100	音頻通用錯誤
AoqErrorCodeAudioExternalBufferFull	110	外部音頻緩衝區滿
AoqErrorCodeAudioDevice	120	音訊裝置通用錯誤
AoqErrorCodeAudioDeviceRecordingAuthFailed	121	錄音許可權未擷取
AoqErrorCodeAudioDeviceRecordingOccupied	122	錄音裝置被佔用
AoqErrorCodeAudioDeviceRecordingBackgroundStart	123	後台啟動錄音失敗
AoqErrorCodeAudioDeviceRecordingStartFail	124	錄音啟動失敗
AoqErrorCodeAudioDevicePlayoutOccupied	125	播放裝置被佔用
AoqErrorCodeAudioDevicePlayoutBackgroundStart	126	後台啟動播放失敗
AoqErrorCodeAudioDevicePlayoutStartFail	127	播放啟動失敗
AoqErrorCodeVideo	200	視頻通用錯誤
AoqErrorCodeVideoExternalBufferFull	210	外部視頻緩衝區滿
AoqErrorCodeVideoExternalCaptureNotEnabled	211	外部視頻採集未啟用
AoqErrorCodeVideoExternalEncoderNotEnabled	212	外部視頻編碼未啟用
AoqErrorCodeVideoDevice	220	視頻裝置通用錯誤
AoqErrorCodeVideoDeviceCameraOpenFail	221	網路攝影機開啟失敗
AoqErrorCodeVideoDeviceCameraAuthFailed	222	網路攝影機許可權未擷取
AoqErrorCodeVideoDeviceCameraOccupied	223	網路攝影機被佔用
AoqErrorCodeVideoDeviceCameraRunningError	224	網路攝影機運行異常
AoqErrorCodeVideoCodec	230	視頻編解碼通用錯誤
AoqErrorCodeVideoCodecEncoderInitFail	231	視頻編碼器初始化失敗
AoqErrorCodeVideoRender	240	視頻渲染通用錯誤
AoqErrorCodeVideoRenderCreateFail	241	視頻渲染建立失敗
AoqErrorCodeVideoRenderDrawError	242	視頻渲染繪製錯誤

除上述 native 錯誤碼外，Electron 層還會在引擎未建立 / 已銷毀、或參數不是合法 JSON 時返回 -1。

AoqWarningCode

枚舉值	值	說明
AoqWCOK	0	無警告
AoqWCAudio	100	音頻通用警告
AoqWCAudioHowling	101	音頻嘯叫檢測
AoqWCAudioDevice	120	音訊裝置通用警告
AoqWCAudioDeviceMicEnumerateError	121	麥克風枚舉錯誤
AoqWCAudioDeviceMicStartTimeout	122	麥克風啟動逾時
AoqWCAudioDeviceRecordingError	123	錄音過程錯誤
AoqWCAudioDeviceSpeakerEnumerateError	124	擴音器枚舉錯誤
AoqWCAudioDeviceSpeakerStartTimeout	125	擴音器啟動逾時
AoqWCAudioDevicePlayoutError	126	播放過程錯誤
AoqWCVideo	200	視頻通用警告
AoqWCVideoCameraEnumerateError	201	網路攝影機枚舉錯誤
AoqWCVideoEncoderSwitched	202	視頻編碼器已切換
AoqWCVideoRenderDowngrade	203	視頻渲染降級

音訊類型

AoqAudioCaptureConfig

欄位	類型	必填	預設值	說明
isExternal	boolean	否	false	是否為外部採集模式
channel	number	否	1	音頻採集通道數，支援 1 / 2

AoqAudioPlaybackConfig

欄位	類型	必填	預設值	說明
isExternal	boolean	否	false	是否為外部播放模式
channel	number	否	1	音頻播放通道數，支援 1 / 2

isVoipMode / isDefaultSpeaker 為移動端欄位，Electron 不提供。

AoqAudioCodecConfig

欄位	類型	必填	預設值	說明
trackType	AoqTrackType	否	AoqTrackTypeAudio	軌道類型
codecType	AoqEncoderType	否	AoqEncoderTypeAudioPCM	編碼格式
sampleRate	number	否	48000	採樣率（Hz）。編碼支援 Opus 8/16/48K、PCM 8/16/32/48K；解碼額外支援 24K（僅 Segment 模式）
channel	number	否	1	聲道數，支援 1 / 2
bitrate	number	否	32000	位元速率（bps）

AoqAudioDeviceRouteType

onAudioDeviceRouteChanged 的 routeType 取值（native 定義，TS 層未匯出為 enum）。

枚舉值	值	說明
AoqAudioDeviceRouteDefault	0	預設路由
AoqAudioDeviceRouteHeadset	1	有麥克風的頭戴裝置
AoqAudioDeviceRouteEarpiece	2	耳機
AoqAudioDeviceRouteHeadsetNoMic	3	無麥克風的頭戴裝置
AoqAudioDeviceRouteSpeakerPhone	4	擴音器
AoqAudioDeviceRouteUsb	5	USB 音訊裝置
AoqAudioDeviceRouteBluetooth	6	藍芽 SCO 模式
AoqAudioDeviceRouteBluetoothA2dp	7	藍芽 A2DP 模式

AoqAudioDeviceStateCode

枚舉值	值	說明
AoqAudioDeviceNone	0	無狀態
AoqAudioDeviceRecordStarting	1	採集啟動中
AoqAudioDeviceRecordStarted	2	採集已啟動
AoqAudioDeviceRecordStopping	3	採集停止中
AoqAudioDeviceRecordStopped	4	採集已停止
AoqAudioDeviceRecordFail	5	採集失敗
AoqAudioDevicePlayStarting	6	播放啟動中
AoqAudioDevicePlayStarted	7	播放已啟動
AoqAudioDevicePlayStopping	8	播放停止中
AoqAudioDevicePlayStopped	9	播放已停止
AoqAudioDevicePlayFail	10	播放失敗

AoqAudioDeviceState

欄位	類型	說明
state	AoqAudioDeviceStateCode	裝置操作狀態
reason	number	錯誤原因代碼（參考 AoqErrorCode）

音頻檔案類型

AoqAudioFileMixConfig

欄位	類型	必填	預設值	說明
fileId	string	是	-	檔案標識符，後續介面以此定位
fileName	string	是	-	檔案名稱（含路徑）
cycles	number	否	-1	迴圈次數，-1 表示無限迴圈
startPosMs	number	否	0	起始播放位置（毫秒）
publishVolume	number	否	100	推流音量，取值範圍 0-100
playoutVolume	number	否	100	播放音量，取值範圍 0-100

AoqAudioFileStateCode

枚舉值	值	說明
AoqAudioFileNone	0	無狀態
AoqAudioFileStarted	1	播放已啟動
AoqAudioFileStopped	2	播放已停止
AoqAudioFilePaused	3	播放已暫停
AoqAudioFileResumed	4	播放已恢複
AoqAudioFileEnded	5	播放已結束
AoqAudioFileBuffering	6	播放緩衝中
AoqAudioFileBufferingEnd	7	緩衝結束
AoqAudioFileFailed	8	播放失敗

AoqAudioFileErrorCode

AoqAudioFileState.errorCode 的取值（native 定義，TS 層作為 number 下發）。

枚舉值	值	說明
AoqAudioFileNoError	0	無錯誤
AoqAudioFileOpenFailed	1	檔案開啟失敗
AoqAudioFileDecodeFailed	2	檔案解碼失敗

AoqAudioFileState

欄位	類型	說明
fileId	string	檔案標識符
stateCode	AoqAudioFileStateCode	檔案播放狀態代碼
errorCode	number	檔案錯誤碼（參考 AoqAudioFileErrorCode）

外部音頻流類型

AoqAudioStreamDirection

枚舉值	值	說明
AoqAudioStreamPublish	0	發布流（推流）
AoqAudioStreamPlayout	1	播放流（本地播放）

AoqAudioExternalStreamConfig

欄位	類型	必填	預設值	說明
streamId	string	是	-	流標識符
trackType	AoqTrackType	否	AoqTrackTypeAudio	音頻軌道類型
codecType	AoqEncoderType	否	AoqEncoderTypeAudioPCM	音頻流格式，當前支援 PCM
channels	number	否	1	聲道數，受限推流 Codec，支援 1 / 2
sampleRate	number	否	48000	採樣率（Hz），支援 8/12/16/24/32/44.1/48/64/88.2/96/176.4/192K
playoutVolume	number	否	100	播放音量，取值範圍 0-100
publishVolume	number	否	100	推流音量，取值範圍 0-100
maxBufferDuration	number	否	600000	最大緩衝時間長度（毫秒），取值範圍 100 以上；超過時 push 失敗
enable3A	boolean	否	false	是否對輸入 PCM 做 3A 處理

AoqAudioExternalFrameMeta

外部音訊框架元資訊，PCM 資料另走 buffer 參數。

欄位	類型	必填	預設值	說明
streamId	string	是	-	目標外部音頻流標識
numOfSamples	number	是	0	採樣點數（單聲道）
bytesPerSample	number	是	2	每個採樣點的位元組數
numOfChannels	number	是	1	聲道數
samplesPerSec	number	是	48000	每秒採樣點數（採樣率）
pushSequence	number	否	0	PCM 輸入輪次
timeStamp	number	否	0	時間戳記

AoqAudioFrameEvent

音訊框架觀察者事件數目據。

欄位	類型	說明
trackType	AoqTrackType	軌道類型
numOfSamples	number	採樣點數（單聲道）
bytesPerSample	number	每個採樣點的位元組數
numOfChannels	number	聲道數
samplesPerSec	number	每秒採樣點數（採樣率）
timeStamp	number	時間戳記
autoGenMute	boolean	true 表示 SDK 產生的靜音資料
buffer	Uint8Array	音頻 PCM 資料（native 側已拷貝）

AoqAudioSource

枚舉值	值	說明
AoqAudioSourceCaptured	0	採集的音頻資料
AoqAudioSourceProcessCaptured	1	3A 處理後的音頻資料
AoqAudioSourcePublish	2	推流的音頻資料（需 connect 成功）
AoqAudioSourcePlayback	3	播放的音頻資料

AoqAudioObserverParams

欄位	類型	必填	預設值	說明
enabled	boolean	是	false	開啟或關閉該位置的回調
audioSource	AoqAudioSource	是	AoqAudioSourceCaptured	回調位置
sampleRate	number	否	48000	回調音頻採樣率（Hz），不一致時重採樣
channels	number	否	1	回調音頻聲道數，支援 1 / 2

回調模式固定為唯讀，Electron 不開放讀寫入模式。

AoqAudioVolumeIndicationConfig

欄位	類型	必填	預設值	說明
interval	number	否	0	回調間隔（毫秒）；小於等於 0 表示關閉回調，大於 0 且小於 10 時按 10 處理
smooth	number	否	3	音量平滑係數，取值越大越平滑，取值範圍 0-10

AoqAudioVolume

欄位	類型	說明
volume	number	平滑後的瞬時音量，取值範圍 0-255

視頻類型

AoqVideoCaptureConfig

欄位	類型	必填	預設值	說明
width	number	否	1280	採集寬度（像素），isExternal=true 時無效
height	number	否	720	採集高度（像素），isExternal=true 時無效
fps	number	否	15	採集幀率，isExternal=true 時無效（節奏由送幀決定）
isExternal	boolean	否	false	是否外部採集，true 時不開啟網路攝影機

cameraDirection 為移動端欄位，案頭端無此欄位。

AoqVideoCodecConfig

編碼與解碼共用同一結構（setVideoEncoderConfig / setVideoDecoderConfig）。

欄位	類型	必填	預設值	說明
isExternal	boolean	否	false	true 時 SDK 不做採集與編碼，由 pushExternalVideoEncodedFrame 直推
trackType	AoqTrackType	否	AoqTrackTypeVideo	軌道類型
codecType	AoqEncoderType	否	AoqEncoderTypeVideoH264	編碼格式
width	number	否	540	編碼寬度（像素）
height	number	否	960	編碼高度（像素）
fps	number	否	5	編碼幀率
bitrate	number	否	500000	起始位元速率（bps）
minBitrate	number	否	128000	最小位元速率（bps）
keyframeInterval	number	否	2	主要畫面格間隔（秒）
mirrorMode	AoqMirrorMode	否	AoqMirrorModeDisabled	鏡像模式
orientationMode	AoqOrientationMode	否	AoqOrientationModeAuto	視頻方向模式

AoqVideoPixelFormat

Electron 側支援的像素格式（不包含移動端的紋理 / CVPixelBuffer 格式）。

枚舉值	值	說明
AoqVideoPixelFormatUnknown	0	未知格式
AoqVideoPixelFormatI420	1	I420（YUV 三平面格式）
AoqVideoPixelFormatNV12	2	NV12（YUV 半平面格式）
AoqVideoPixelFormatNV21	3	NV21（YUV 半平面格式）
AoqVideoPixelFormatBGRA	4	BGRA（32 位）
AoqVideoPixelFormatRGBA	5	RGBA（32 位）

AoqExternalVideoFrameMeta

外部視頻裸幀元資訊，像素資料另走 buffer 參數。

欄位	類型	必填	預設值	說明
trackType	AoqTrackType	否	AoqTrackTypeVideo	軌道類型
format	AoqVideoPixelFormat	是	-	像素格式
width	number	是	-	視頻寬度（像素）
height	number	是	-	視頻高度（像素）
timeStamp	number	否	0	時間戳記（毫秒）；0 時 SDK 使用本地時間補齊

format = I420 時 buffer 必須為緊湊布局（stride = width），Y / U / V 三平面順序拼接；其餘打包格式直接傳整幀位元組。

AoqVideoCodecType

枚舉值	值	說明
AoqVideoCodecTypeJPEG	0	JPEG 編碼

AoqExternalVideoEncodedFrameMeta

外部已編碼視訊框架元資訊，編碼資料另走 buffer 參數。

欄位	類型	必填	預設值	說明
trackType	AoqTrackType	否	AoqTrackTypeVideo	軌道類型
codec	AoqVideoCodecType	否	AoqVideoCodecTypeJPEG	編碼格式
width	number	是	-	寬度（像素）
height	number	是	-	高度（像素）
timeStamp	number	否	0	時間戳記（毫秒）；0 時 SDK 使用本地時間補齊

AoqVideoDeviceStateCode

枚舉值	值	說明
AoqVideoDeviceNone	0	無狀態
AoqVideoDeviceCaptureStarting	1	採集啟動中
AoqVideoDeviceCaptureStarted	2	採集已啟動
AoqVideoDeviceCaptureStopping	3	採集停止中
AoqVideoDeviceCaptureStopped	4	採集已停止
AoqVideoDeviceCaptureFail	5	採集失敗（許可權拒絕、裝置不可用等）

AoqVideoDeviceState

欄位	類型	說明
state	AoqVideoDeviceStateCode	裝置採集操作狀態
reason	number	錯誤原因代碼（參考 AoqErrorCode）

視訊框架回調類型

AoqVideoSource

枚舉值	值	說明
AoqVideoSourceCaptured	0	採集後的視頻資料（前處理前）
AoqVideoSourcePreEncode	1	編碼前的視頻資料（前處理後）
AoqVideoSourceRemote	2	遠端解碼後、渲染前的視頻資料

AoqVideoObserverAlignment

枚舉值	值	說明
AoqVideoObserverAlignmentDefault	0	預設對齊
AoqVideoObserverAlignmentEven	1	偶數對齊
AoqVideoObserverAlignment4	2	4 位元組對齊
AoqVideoObserverAlignment8	3	8 位元組對齊
AoqVideoObserverAlignment16	4	16 位元組對齊

AoqVideoObserverParams

欄位	類型	必填	預設值	說明
enabled	boolean	是	false	開啟或關閉該位置的回調
videoSource	AoqVideoSource	是	AoqVideoSourceCaptured	回調位置
format	AoqVideoPixelFormat	否	AoqVideoPixelFormatI420	期望回調像素格式
alignment	AoqVideoObserverAlignment	否	AoqVideoObserverAlignmentDefault	寬度對齊策略
mirrorApplied	boolean	否	false	是否對回調資料應用鏡像

回調模式固定為唯讀，Electron 不開放讀寫入模式。使用內建 YUVCanvasRenderer 渲染時需選 I420。

AoqVideoFrameEvent

視訊框架觀察者事件數目據。

欄位	類型	說明
trackType	AoqTrackType	軌道類型
format	AoqVideoPixelFormat	像素格式
width	number	寬度（像素）
height	number	高度（像素）
strideY	number	Y 平面行跨度（僅 I420 有效）
strideU	number	U 平面行跨度（僅 I420 有效）
strideV	number	V 平面行跨度（僅 I420 有效）
timeStamp	number	時間戳記（毫秒）
buffer	Uint8Array	幀資料；I420 為 Y / U / V 三平面按 stride 拼接，其餘打包格式為原資料透傳

資料訊息類型

Electron 不使用 AoqDataMsg 封裝類型，資料訊息直接以二進位收發：

方向	類型	說明
發送	Uint8Array 或 string	`sendDataMsg(data)`；字串按 UTF-8 編碼
接收	Uint8Array	`onDataMsg(data)`；native 側已拷貝，可非同步持有

​介面目錄

​引擎入口與生命週期

​音訊裝置管理

​音頻編解碼配置

​視頻裝置管理

​視頻編解碼與外部輸入

​媒體流發送控制

​音頻檔案播放

​外部音頻流

​即時訊息

​音訊框架回調

​本地音量提示

​視訊框架回調

​視頻渲染（YUVCanvasRenderer）

​引擎事件（IAoqEngineEvents）

​介面詳情

​引擎入口與生命週期

​createAoqClientEngine

​createEngine

​destroy

​getVersion

​connect

​disconnect

​音訊裝置管理

​startAudioCapture

​stopAudioCapture

​muteAudioCapture

​startAudioPlayer

​stopAudioPlayer / pauseAudioPlayer / resumeAudioPlayer

​interruptAudioPlayer

​音頻編解碼配置

​視頻裝置管理

​視頻編解碼與外部輸入

​媒體流發送控制

​音頻檔案播放

​外部音頻流

​即時訊息

​音訊框架回調

​本地音量提示

​視訊框架回調

​視頻渲染（YUVCanvasRenderer）

​引擎事件（IAoqEngineEvents）

​onError

​onWarning

​onConnectionStatusChange

​onStats

​onAudioDeviceStateChanged

​onAudioDeviceRouteChanged

​onAudioFileState

​onLocalAudioVolumeIndication

​onVideoDeviceStateChanged

​onDataMsg

​音訊框架事件

​視訊框架事件

​資料類型與枚舉

​通用類型

​AoqCreateConfig

​AoqConnectConfig

​AoqRelayEndpoint

​AoqTrackParam

​統計資訊類型

​AoqStats

​AoqAudioPublishStats

​AoqAudioSubscribeStats

​AoqVideoPublishStats

​AoqVideoSubscribeStats

​AoqDataMsgPublishStats / AoqDataMsgSubscribeStats

​AoqNetworkStats

​枚舉類型

​AoqTrackType

​AoqTrackMode

​AoqEncoderType

​AoqConnectionStatus

​AoqMirrorMode

​AoqOrientationMode

​AoqErrorCode

​AoqWarningCode

​音訊類型

​AoqAudioCaptureConfig

​AoqAudioPlaybackConfig

介面目錄

引擎入口與生命週期

音訊裝置管理

音頻編解碼配置

視頻裝置管理

視頻編解碼與外部輸入

媒體流發送控制

音頻檔案播放

外部音頻流

即時訊息

音訊框架回調

本地音量提示

視訊框架回調

視頻渲染（YUVCanvasRenderer）

引擎事件（IAoqEngineEvents）

介面詳情

引擎入口與生命週期

createAoqClientEngine

createEngine

destroy

getVersion

connect

disconnect

音訊裝置管理

startAudioCapture

stopAudioCapture

muteAudioCapture

startAudioPlayer

stopAudioPlayer / pauseAudioPlayer / resumeAudioPlayer

interruptAudioPlayer

音頻編解碼配置

視頻裝置管理

視頻編解碼與外部輸入

媒體流發送控制

音頻檔案播放

外部音頻流

即時訊息

音訊框架回調

本地音量提示

視訊框架回調

視頻渲染（YUVCanvasRenderer）

引擎事件（IAoqEngineEvents）

onError

onWarning

onConnectionStatusChange

onStats

onAudioDeviceStateChanged

onAudioDeviceRouteChanged

onAudioFileState

onLocalAudioVolumeIndication

onVideoDeviceStateChanged

onDataMsg

音訊框架事件

視訊框架事件

資料類型與枚舉

通用類型

AoqCreateConfig

AoqConnectConfig

AoqRelayEndpoint

AoqTrackParam

統計資訊類型

AoqStats

AoqAudioPublishStats

AoqAudioSubscribeStats

AoqVideoPublishStats

AoqVideoSubscribeStats

AoqDataMsgPublishStats / AoqDataMsgSubscribeStats

AoqNetworkStats

枚舉類型

AoqTrackType

AoqTrackMode

AoqEncoderType

AoqConnectionStatus

AoqMirrorMode

AoqOrientationMode

AoqErrorCode

AoqWarningCode

音訊類型

AoqAudioCaptureConfig

AoqAudioPlaybackConfig