AOQ Web SDK 支援在瀏覽器中進行即時音視訊和資料互動。本文介紹引擎管理、音視訊擷取與播放、資料訊息和事件回呼等 API。
安裝 SDK
AOQ Web SDK 透過 WebTransport(HTTP/3 / QUIC)連線至服務端,並在 Worker 中收發音訊、視訊和資料訊息。使用 SDK 需要支援 WebTransport 的瀏覽器及 HTTPS 安全上下文,可透過 AoqClientEngine.isAoqSupported() 檢查瀏覽器的基本能力。
透過 npm 安裝 SDK:
接口目錄
引擎生命週期
| 接口 | 簡介 |
|---|---|
| createEngine | 建立引擎實例(單例) |
| createAoqClientEngine | 等價的具名便捷工廠 |
| destroy | 銷毀引擎實例 |
| getVersion | 取得 SDK 版本號 |
| isAoqSupported | 檢查瀏覽器能力 |
| connect | 發起連接 |
| disconnect | 斷開連接 |
音訊設備管理
| 接口 | 簡介 |
|---|---|
| startAudioCapture | 啓動音訊擷取 |
| stopAudioCapture | 停止音訊擷取 |
| muteAudioCapture | 擷取靜音 |
| startAudioPlayer | 啓動音訊播放 |
| stopAudioPlayer | 停止音訊播放 |
| pauseAudioPlayer | 暫停播放(帶淡出) |
| resumeAudioPlayer | 恢復播放(預設淡入) |
| interruptAudioPlayer | 打斷播放 |
音訊編碼設定
| 接口 | 簡介 |
|---|---|
| setAudioEncoderConfig | 設置音訊編碼設定 |
| setAudioDecoderConfig | 設置音訊解碼設定 |
本地音量提示
| 接口 | 簡介 |
|---|---|
| enableLocalAudioVolumeIndication | 開啓本地音量提示 |
視訊設備管理
| 接口 | 簡介 |
|---|---|
| startVideoCapture | 啓動視訊擷取 |
| getCameras | 枚舉攝像頭 |
| switchCamera | 按方向偏好或設備 ID 切換攝像頭 |
| stopVideoCapture | 停止視訊擷取 |
| setLocalView | 設置本地視訊渲染容器 |
| setRemoteView | 設置遠端視訊渲染容器 |
視訊編碼設定
| 接口 | 簡介 |
|---|---|
| setVideoEncoderConfig | 設置視訊編碼設定 |
| setVideoDecoderConfig | 設置視訊解碼設定 |
媒體流發送控制
| 接口 | 簡介 |
|---|---|
| enableSendMediaStream | 啓用/禁用媒體流發送 |
實時消息
| 接口 | 簡介 |
|---|---|
| sendDataMsg | 發送資料消息 |
事件回呼
| 接口 | 簡介 |
|---|---|
| onError | 錯誤回呼 |
| onWarning | 警告回呼 |
| onConnectionStatusChange | 連接狀態變化 |
| onStats | 統計信息 |
| onAudioDeviceStateChanged | 音訊設備狀態變化 |
| onAudioDeviceRouteChanged | 音訊路由變化 |
| onAudioFileState | 預留音訊文件狀態,當前不觸發 |
| onLocalAudioVolumeIndication | 本地音量提示 |
| onVideoDeviceStateChanged | 視訊設備狀態變化 |
| onDataMsg | 資料消息 |
接口詳情
引擎生命週期
createEngine
建立引擎實例。採用單例模式,重復調用返回已有實例。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqCreateConfig | 引擎建立設定 |
AoqClientEngine 實例,失敗返回 null。
說明 引擎為單例,若已存在已初始化的實例則直接返回該實例,不會重新應用設定。銷毀後可重新建立。
createAoqClientEngine
從包入口具名導入的便捷工廠,等價於 AoqClientEngine.createEngine(config),不是實例方法,也不需要二次初始化。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqCreateConfig | 必傳,可傳 {};重復建立不重新應用設定 |
null。
destroy
銷毀引擎實例,發起資源釋放並移除全部事件監聽。
0 表示成功,AoqECStateInvalid(2) 表示當前無實例。
說明 銷毀接口同步返回;日誌保存、可選 dump 導出等異步收尾在後台執行,不代表返回時所有任務已完成。銷毀後需重新調用 createEngine 才能繼續使用 SDK,舊實例不可繼續調用。
getVersion
取得 SDK 版本號。
isAoqSupported
檢查當前瀏覽器環境是否具備使用 AOQ 連接的基礎能力。
Promise<AoqSupportResult>,包含是否支援及缺失能力列表。
說明 返回 supported: true 不代表連接或音視訊通話一定成功;不檢查網絡可達性、服務端設定、鑒權、設備授權及具體媒體設定的可用性。檢測在 Worker 內執行 WebTransport 能力探測,超時為 5 秒。
connect
發起與服務端的連接。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqConnectConfig | 連接鑒權設定,包含 token、會話 ID、接入點等 |
0 表示調用成功。
說明 在建立引擎、註冊事件及編解碼設定完成後調用,正常從 Disconnected 發起;Failed 狀態允許重新發起,其他狀態返回 AoqECStateInvalid(2)。不合法的 Track/媒體設定、連接參數,或選用 Opus 但缺少所需 WebCodecs 能力,均可返回 AoqECParamInvalid(1);Network Worker 不可用返回 AoqECStateInvalid(2)。
返回 0 僅表示連接請求已受理。連接結果通過 onConnectionStatusChange 異步通知,Connected 表示 MEDIA_SETUP 完成且媒體軌道已綁定,不等於模型業務就緒;業務側仍需按模型資料協議設定會話並確認就緒,再啓用音視訊發送。
disconnect
斷開與服務端的連接。
0 表示調用成功。
說明 斷開結果通過 onConnectionStatusChange 事件通知,等待 AoqConnectionStatusDisconnected 後再修改編解碼設定並重新連接。已斷開時調用返回 AoqECStateInvalid(2)。斷開不替代設備停止,結束通話還應調用對應擷取/播放停止接口。
音訊設備管理
startAudioCapture
啓動音訊擷取(麥克風),異步請求設備權限。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqAudioCaptureConfig | 音訊擷取設定 |
Promise<number>,0 表示成功。
說明 首次使用或權限未授予時可能觸發瀏覽器麥克風授權彈窗。擷取狀態變化通過 onAudioDeviceStateChanged 事件通知。
說明 網絡擁塞時,上行音訊在發送隊列中等待達到約 100 ms 即被丟棄,以避免延遲累積;已開始發送的音訊不撤回,該值不代表端到端延遲上限。
stopAudioCapture
停止音訊擷取。
0 表示成功。
說明 設備尚未啓動或已停止時返回 AoqECStateInvalid(2)。
muteAudioCapture
靜音或取消靜音音訊擷取。靜音後繼續擷取但發送靜音幀。
| 參數 | 類型 | 說明 |
|---|---|---|
mute | boolean | true 靜音,false 取消靜音 |
0 表示成功。
startAudioPlayer
啓動音訊播放器,異步初始化音訊輸出設備。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqAudioPlaybackConfig | 音訊播放設定 |
Promise<number>,0 表示成功。
說明 播放狀態變化通過 onAudioDeviceStateChanged 事件通知。
說明 應從使用者點擊事件調用並處理自動播放限制;播放器正在啓動或已啓動時重復調用返回 AoqECStateInvalid(2)。
說明 Realtime 模式(音訊下行 trackMode 為 Stream)下,播放器啓動前收到的音訊會被持續消費而不積壓;每次啓動(含首次)都會清除此前的音訊,從之後收到的新音訊開始播放,不補播啓動前的語音。Segment 模式保留尚未播放的內容。
stopAudioPlayer
停止音訊播放器。
0 表示成功。
說明 設備尚未啓動或已停止時返回 AoqECStateInvalid(2)。
說明 Realtime 模式停止設備輸出後,SDK 仍持續消費收到的音訊,視訊繼續播放;再次啓動只播放新音訊。已有的暫停或打斷狀態在重新啓動後仍然保留。Segment 模式保留尚未播放的內容。
pauseAudioPlayer
暫停音訊播放,淡出完成後停止輸出,後續可調用 resumeAudioPlayer 恢復。
| 參數 | 類型 | 說明 |
|---|---|---|
fadeMs | number | 淡出時長(ms),按實際設備採樣率四捨五入到樣本數;0 不執行淡出,負數或非有限值使用 100 ms |
0 表示控制請求已受理,不證明播放器正在播放或淡出已經完成。
說明 Segment 模式凍結未播放內容及讀取位置,恢復後從暫停處接續。Realtime 模式丟棄待播音訊,暫停期間繼續消費收到的音訊,恢復後從當前實時位置播放,不補播暫停期間的內容。
resumeAudioPlayer
恢復暫停或打斷的音訊播放,使用預設淡入:Segment 為 2 ms,Realtime 為 100 ms。
| 參數 | 類型 | 說明 |
|---|---|---|
fadeMs | number | 保留參數,當前忽略傳入時長;恢復使用預設淡入,不能通過傳 0 取消 |
0 表示控制請求已受理,不證明恢復已經完成。
interruptAudioPlayer
打斷當前音訊播放,淡出完成後丟棄被打斷的未播放餘量;與 Segment 模式保留餘量的暫停不同,之後恢復也不會重新播放已丟棄的部分。
| 參數 | 類型 | 說明 |
|---|---|---|
trackType | AoqTrackType | 兼容性參數,建議傳 Audio;當前未按此參數區分播放流 |
fadeMs | number | 淡出時長(ms),按實際設備採樣率四捨五入到樣本數;0 不執行淡出,負數或非有限值使用 100 ms |
0 表示控制請求已受理,不證明播放器正在播放或打斷已經完成。
說明 打斷後,服務端下發新一輪音訊時自動恢復播放,也可調用 resumeAudioPlayer 恢復。
說明 暫停狀態下的打斷請求會被忽略,仍可能返回 0;Segment 模式恢復後會繼續播放暫停前的餘量。不要將“暫停 → 打斷”的調用序列當作清空播放隊列。
音訊編碼設定
setAudioEncoderConfig
設置音訊編碼參數。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqAudioCodecConfig | 音訊編碼設定 |
0 表示成功。
說明 必須在 connect() 前、引擎處於 Disconnected 時調用。連接中或已連接時修改返回 AoqECStateInvalid(2);需先斷開並等待 Disconnected,再設定及重新連接。
說明 返回 0 表示設定請求已受理;音訊格式在建連時再次校驗,Opus 還依賴瀏覽器 WebCodecs 能力。
setAudioDecoderConfig
設置音訊解碼參數。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqAudioCodecConfig | 音訊解碼設定 |
0 表示成功。
說明 必須在 connect() 前、引擎處於 Disconnected 時調用。連接中或已連接時修改返回 AoqECStateInvalid(2)。
本地音量提示
enableLocalAudioVolumeIndication
開啓或關閉本地擷取音量提示。開啓後通過 onLocalAudioVolumeIndication 事件週期性回呼音量信息。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqAudioVolumeIndicationConfig | 音量提示設定 |
0 表示成功。
說明interval 設置為 0 或負值表示關閉回呼。
視訊設備管理
startVideoCapture
啓動視訊擷取(攝像頭)。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqVideoCaptureConfig | 視訊擷取設定 |
0 表示成功。
說明 返回 0 僅表示異步擷取請求已受理,不能據此判定攝像頭已開啓。實際成功/失敗通過 onVideoDeviceStateChanged 事件通知。
cameraPreference 為攝像頭選擇偏好,可傳方向枚舉或設備 ID;省略時由瀏覽器選擇。方向或設備 ID 無法滿足時,均允許瀏覽器選擇其他可用攝像頭。
getCameras
videoinput,不打開攝像頭或主動申請權限。未授權時設備名稱或 ID 可能不完整,授權或設備插拔後可重新枚舉;引擎未初始化或枚舉失敗時 Promise 拒絕。
switchCamera
| 參數 | 類型 | 必填 | 說明 |
|---|---|---|---|
cameraPreference | AoqCameraDirection | string | 否 | 方向或設備 ID 偏好;省略時清除先前偏好,重新由瀏覽器選擇 |
onVideoDeviceStateChanged 通知,失敗原因通過 onError 報告。未擷取、正在啓動或正在切換時返回 AoqECStateInvalid(2);非法方向或空白 ID 返回 AoqECParamInvalid(1)。
切換先釋放舊設備,再打開目標並等待首幀,若舊擷取向 Worker 轉移過攝像頭軌道(包括隨後回退到主執行緒的情況),打開設備前會等待釋放確認,最多等待 2 秒;確認超時則報告失敗,不繼續打開目標或恢復設備。每次嘗試最多 15 秒。失敗後嘗試以原設備為偏好恢復擷取一次,恢復成功仍報告本次切換失敗。成功通知 CaptureStarted(reason=0);失敗但已恢復擷取通知 CaptureStarted(reason=失敗碼);無法恢復通知 CaptureFail(reason=失敗碼)。顯式目標已滿足時異步通知 CaptureStarted,不重開設備。狀態回呼不提供實際設備 ID,不能把請求偏好當作實際設備。切換不改變發送開關、編碼設定和預覽綁定;停止擷取可取消切換,銷毀後不再回呼。
切換可能短暫中斷畫面;擷取時間線保持連續,但不保證硬件級音畫同步。實際設備由瀏覽器選擇,業務 UI 不應將請求偏好直接顯示為已選設備。
stopVideoCapture
停止視訊擷取。
0 表示成功。
說明 設備尚未啓動或已停止時返回 AoqECStateInvalid(2)。
setLocalView
設置本地視訊渲染容器。SDK 會在指定容器內建立渲染元素。
| 參數 | 類型 | 說明 |
|---|---|---|
trackType | AoqTrackType | 僅支援 AoqTrackTypeVideo,其他類型返回 AoqECUnSupport(3) |
canvas | AoqVideoCanvas | null | 渲染容器設定,傳 null 解除綁定 |
0 表示成功。
說明 容器元素應具有明確尺寸,SDK 在容器內部建立實際渲染元素。
說明 使用尺寸明確的普通 DOM 容器(例如 div),不能直接傳入 video、audio、canvas、img 或空元素。容器無效、id 不存在或 renderMode 非法時返回 AoqECParamInvalid(1),保留原綁定;返回 0 僅表示綁定受理,不保證已經渲染首幀。
setRemoteView
設置遠端視訊渲染容器。SDK 會在指定容器內建立渲染元素。
| 參數 | 類型 | 說明 |
|---|---|---|
trackType | AoqTrackType | 僅支援 AoqTrackTypeVideo,其他類型返回 AoqECUnSupport(3) |
canvas | AoqVideoCanvas | null | 渲染容器設定,傳 null 解除綁定 |
0 表示成功。
說明 使用尺寸明確的普通 DOM 容器(例如 div),不能直接傳入 video、audio、canvas、img 或空元素。容器無效、id 不存在或 renderMode 非法時返回 AoqECParamInvalid(1),保留原綁定;返回 0 僅表示綁定受理,不保證已經渲染首幀。
視訊編碼設定
setVideoEncoderConfig
設置視訊編碼參數。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqVideoCodecConfig | 視訊編碼設定 |
0 表示成功。
說明 必須在引擎處於 Disconnected 時調用,連接中或已連接時返回 AoqECStateInvalid(2)。建議在首次連接及視訊擷取前完成設定;設定合併緩存用於後續建流,不立即重配已有擷取或編碼器。
setVideoDecoderConfig
設置視訊解碼參數。
| 參數 | 類型 | 說明 |
|---|---|---|
config | AoqVideoCodecConfig | 視訊解碼設定 |
0 表示成功。
說明 必須在 connect() 前、引擎處於 Disconnected 時調用。連接中或已連接時修改返回 AoqECStateInvalid(2)。
媒體流發送控制
enableSendMediaStream
啓用或禁用音訊或視訊 Track 的媒體流發送。
| 參數 | 類型 | 說明 |
|---|---|---|
trackType | AoqTrackType | 媒體 track 類型 |
enable | boolean | true 啓用發送,false 禁用發送 |
0 表示成功。
說明 當前僅控制 Audio / Video,不能控制 Data 發送;其他 Track 值即使返回 0 也不代表生效。停發不關閉擷取設備;需要關閉設備時調用相應 stop...Capture()。
實時消息
sendDataMsg
發送以 Uint8Array 承載的 UTF-8 文本消息到遠端,可用於業務 JSON。當前 WT 通路不支援任意二進制載荷,也不能用此接口發送 SDK 內部控制消息。
| 參數 | 類型 | 說明 |
|---|---|---|
msg | AoqDataMsg | 消息對象,msg.data 為非空 UTF-8 編碼字節 |
0 表示成功。
說明 需已連接且媒體軌道就緒、publishTracks 包含 Data,消息不能為空。缺少消息對象或 msg.data 不是 Uint8Array 時返回 AoqECParamInvalid(1);未就緒返回 AoqECStateInvalid(2);發送流未激活或消息為空時當前實現返回 -1。返回 0 僅表示本地受理,UTF-8 校驗或後續發送仍可能通過 onError 報告失敗,不代表遠端確認收到。
msg.data 的底層 ArrayBuffer 可能被轉移並失效,包括共享該緩衝區的其他視圖;需要保留原資料時傳入 data.slice() 的副本。不要在前端消息或日誌中發送 API Key、臨時憑證等敏感信息。
事件回呼
事件通過 engine.on('eventName', callback) 訂閱,engine.once(...) 僅監聽一次,engine.off('eventName', callback) 取消相同函數引用的監聽;銷毀引擎會移除全部監聽。應在連接或啓動設備前註冊,並保持回呼輕量。
| 事件名 | 回呼簽名 | 說明 |
|---|---|---|
onError | (code: number, message: string) => void | 錯誤回呼 |
onWarning | (code: number, message: string) => void | 警告回呼 |
onConnectionStatusChange | (status: AoqConnectionStatus) => void | 連接狀態變化 |
onStats | (stats: AoqStats) => void | 統計信息 |
onAudioDeviceStateChanged | (state: AoqAudioDeviceState) => void | 音訊設備狀態變化 |
onAudioDeviceRouteChanged | (routeType: AoqAudioDeviceRouteType) => void | 音訊路由變化 |
onAudioFileState | (state: AoqAudioFileState) => void | 預留,當前門面未觸發 |
onLocalAudioVolumeIndication | (volume: AoqAudioVolume) => void | 本地音量提示 |
onVideoDeviceStateChanged | (state: AoqVideoDeviceState) => void | 視訊設備狀態變化 |
onDataMsg | (msg: AoqDataMsg) => void | 資料消息 |
onError
報告同步返回值之外的異步錯誤或運行錯誤。code 與 message 用於排查問題;收到錯誤不等於整個連接已終結,應結合連接和設備狀態判斷。網絡錯誤可能使用通用狀態錯誤碼,不應僅按數字推斷錯誤階段。
| 參數 | 類型 | 說明 |
|---|---|---|
code | number | 錯誤碼,參見 AoqErrorCode 枚舉 |
message | string | 錯誤描述信息 |
onWarning
引擎警告回呼,通知可忽略但需關注的異常情況。
| 參數 | 類型 | 說明 |
|---|---|---|
code | number | 警告碼,參見 AoqWarningCode 枚舉 |
message | string | 警告描述信息 |
onConnectionStatusChange
連接狀態變化回呼。
| 參數 | 類型 | 說明 |
|---|---|---|
status | AoqConnectionStatus | 當前連接狀態 |
onStats
連接成功期間約每秒回呼一次統計信息;離開 Connected 狀態後停止。字段可用性見 AoqStats,不能把佔位值當成真實測量。
| 參數 | 類型 | 說明 |
|---|---|---|
stats | AoqStats | 統計信息對象 |
onAudioDeviceStateChanged
音訊設備(擷取/播放)操作狀態變化回呼。
| 參數 | 類型 | 說明 |
|---|---|---|
state | AoqAudioDeviceState | 音訊設備狀態 |
onAudioDeviceRouteChanged
輸出設備列表變化時,SDK 根據瀏覽器設備標籤盡力推斷路由類型並回呼。該事件不是實際輸出路由的確認,可能誤判或漏報;授權前或設備信息不完整時可能返回預設類型。
| 參數 | 類型 | 說明 |
|---|---|---|
routeType | AoqAudioDeviceRouteType | 根據設備標籤推斷的路由類型,不能據此確認實際輸出設備 |
onAudioFileState
預留的音訊文件狀態回呼。當前 AoqClientEngine 門面沒有文件播放控制方法,也未觸發此事件。
| 參數 | 類型 | 說明 |
|---|---|---|
state | AoqAudioFileState | 音訊文件狀態 |
onLocalAudioVolumeIndication
本地擷取音量提示回呼。需先調用 enableLocalAudioVolumeIndication 開啓。
| 參數 | 類型 | 說明 |
|---|---|---|
volume | AoqAudioVolume | 音量信息 |
onVideoDeviceStateChanged
視訊設備擷取操作狀態變化回呼。
| 參數 | 類型 | 說明 |
|---|---|---|
state | AoqVideoDeviceState | 視訊設備狀態 |
onDataMsg
接收遠端資料消息回呼。
| 參數 | 類型 | 說明 |
|---|---|---|
msg | AoqDataMsg | 接收的消息對象,使用 TextDecoder 讀取 msg.data 中的 UTF-8 文本 |
subscribeTracks 中設定 Data;回呼參數是對象,不是直接的 Uint8Array。業務 JSON 的解析和校驗由業務側完成。
資料類型與枚舉
通用類型
AoqCreateConfig
引擎建立設定。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
workDir | string | 否 | — | 保留字段,當前 Web 實現不使用此設定指定存儲目錄 |
enableDumpAudio | boolean | 否 | false | 是否保存音訊調試資料;涉及使用者音訊,應取得授權並控制訪問 |
enableDumpExport | boolean | 否 | false | 僅在 enableDumpAudio=true 時生效;銷毀時異步導出 dump ZIP 並清理相應 OPFS 文件 |
maxEncodedVideoFrameBytes | number | 否 | 194560(190×1024) | JPEG 單幀目標上限(byte),0 關閉;超限自動降質,非法值使用預設值 |
enableDropOversizedVideoFrame | boolean | 否 | false | 最低 JPEG 質量仍超限時是否丟幀;false 時仍可能發送超限幀,上限為 0 時不因此丟幀 |
extras | string | 否 | — | JSON 對象字符串;非法 JSON、非對象或非法遠端渲染策略導致 createEngine 返回 null |
extras 設定:
| JSON 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
remoteVideoRenderer | 'auto' | 'video' | 'canvas' | 'auto' | 遠端渲染策略;auto 優先 video,必要時回退 canvas |
user_specified_enable_av_sync | boolean | true | 是否啓用音畫同步;建議使用 JSON 布爾值 |
user_specified_audio_playback_transport | 'message-port' | 自動選擇 | 指定 MessagePort 播放;省略時按環境自動選擇共享內存或 MessagePort |
AoqConnectConfig
連接鑒權設定。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
token | string | 是 | — | 非空客戶端臨時 token,對應 aoqTokenForClient,不是 API Key |
sid | string | 是 | — | 非空會話 ID,當前取鑒權響應的完整 sid 字符串 |
wtBaseUrl | string | 否 | 根據 Relay 構造 | 單路由時優先使用的 HTTPS WT URL,多路由時忽略並按各自主機、端口連接 /aoq |
signedSid | string | 是(運行時) | — | 完整簽名 SID,通常使用鑒權響應的完整 sid;TypeScript 標為可選,當前 WT 仍要求有效值 |
certFingerprint | string | string[] | 條件必填 | — | 公共 WT 證書 SHA-256 指紋;未提供獨立指紋的路由必須能使用此值 |
workspaceIdHash | string | 否 | — | 對應 extraInfo.workspaceIdHash,不能用原始 Workspace ID 代替 |
relayEndpoints | AoqRelayEndpoint[] | 是 | — | 完整接入點列表,至少一項 |
publishTracks | AoqTrackParam[] | 是 | — | 上行 Track 列表,可為空;與 subscribeTracks 不能同時為空 |
subscribeTracks | AoqTrackParam[] | 是 | — | 下行 Track 列表,可為空;同一方向不能重復 Track,當前不支援 Screen |
clientRelayEndpoints[].route_index 映射為 routeIndex,不要自行補造 SID、接入地址、路由索引或指紋。
WT 指紋必須對應實際 WebTransport 入口證書。若後端使用 sha256/<hex> 格式,適配層需去掉前綴並校驗為 64 位十六進制。公共和路由指紋均可為單個字符串或字符串數組;數組每項均須有效,瀏覽器匹配任一項即可通過。路由非空指紋覆蓋公共指紋,空數組視為未設定。SDK 不內置通用指紋,也不提供跳過校驗選項。
缺少 signedSid 或有效指紋可能在異步連接階段失敗,即使 connect() 已返回 0,也應處理狀態事件及 onError。
AoqRelayEndpoint
Relay 接入點。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
routeIndex | number | 是(運行時) | — | 唯一的 0..2147483647 整數,初連選擇最小索引;TypeScript 標為可選 |
certFingerprint | string | string[] | 條件必填 | 公共指紋 | 當前路由指紋,非空值覆蓋公共設定;無公共指紋時必須提供 |
endpoint | string | 是 | — | WT 主機名/IP,不含協議、路徑、空白、使用者信息或查詢串;支援 IPv6 |
port | number | 是 | — | WT 端口,1..65535 的整數 |
AoqTrackParam
track 屬性。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
trackType | AoqTrackType | 是 | — | Audio、Video 或 Data;同一方向不可重復,Screen 當前不支援 |
trackMode | AoqTrackMode | 否 | 音訊下行為 Segment | 僅控制音訊下行:PCM / Opus 預設 Segment,顯式 Stream 選擇 Realtime;音訊上行固定 Realtime,上行及視訊/資料忽略此字段 |
AoqSupportResult
瀏覽器能力檢測結果。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
supported | boolean | — | 當前環境是否具備使用 AOQ 連接的基礎能力 |
missingFeatures | AoqMissingFeature[] | — | 已觀察到的預檢失敗項列表,可能包含 'secure-context'、'worker'、'web-transport' |
AoqMissingFeature
基礎能力預檢失敗項:'secure-context' | 'worker' | 'web-transport'。worker 也可能表示部署策略阻止、啓動/執行失敗或探測超時,不一定是瀏覽器缺少 Worker API;失敗列表不是全部媒體能力的檢測結果。
音訊類型
AoqAudioCaptureConfig
音訊擷取設定。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
channel | number | 否 | 1 | 請求擷取通道數,支援 1(單聲道)/ 2(立體聲);實際可能由設備軌道設置決定 |
AoqAudioPlaybackConfig
音訊播放設定。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
channel | number | 否 | 1 | 請求播放通道數,支援 1 / 2;輸出採樣率使用實際 AudioContext 採樣率 |
playOnlyAndIgnoreMute | boolean | 否 | false | 僅播放場景使用;瀏覽器支援 audioSession 時設為 playback,以避免 iOS 靜音開關影響。需要擷取麥克風時保持 false;不支援時無法保證忽略靜音開關 |
AoqAudioCodecConfig
音訊編解碼設定。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
trackType | AoqTrackType | 否 | — | 保留字段,當前不用於選擇音訊流 |
codecType | AoqEncoderType | 否 | AoqEncoderTypeAudioPCM | 支援 PCM / Opus,需與對端協商一致 |
sampleRate | number | 否 | 48000 | 採樣率(Hz);協商支援 8000、12000、16000、24000、32000、44100、48000,具體編碼仍需瀏覽器支援 |
channel | number | 否 | 1 | 聲道數,1 或 2 |
bitrate | number | 否 | 32000(Opus 編碼) | 單位 bps,僅 Opus 編碼使用;PCM 碼率由採樣率、聲道和位深決定,解碼不使用 |
AoqAudioVolumeIndicationConfig
本地音量提示設定。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
interval | number | 否 | 0 | 回呼間隔(ms);<=0 關閉,正數小於 10 時按 10 處理 |
smooth | number | 否 | 3 | 音量平滑系數,範圍 0..10,越大越平滑 |
reportSpeech | boolean | 否 | false | 是否上報語音活動狀態(VAD) |
AoqAudioVolume
本地音量信息。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
volume | number | — | 平滑後的瞬時音量,取值範圍 [0-255] |
isSpeech | boolean | — | 可選,語音活動標誌,僅 reportSpeech=true 時有意義,調用方應處理缺省值 |
AoqAudioDeviceState
音訊設備狀態回呼資料。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
state | AoqAudioDeviceStateCode | — | 音訊設備狀態碼 |
reason | number | — | 原因碼,參見 AoqErrorCode |
AoqAudioFileState
預留的音訊文件播放狀態結構;當前 Web 不觸發對應事件。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
fileId | string | — | 音訊文件標識 |
stateCode | AoqAudioFileStateCode | — | 文件播放狀態碼 |
errorCode | number | — | 錯誤碼 |
視訊類型
AoqVideoCaptureConfig
視訊擷取設定。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
width | number | 否 | 1280 | 請求擷取寬度(像素,ideal 約束),實際由瀏覽器/設備決定 |
height | number | 否 | 720 | 請求擷取高度(像素,ideal 約束),實際由瀏覽器/設備決定 |
fps | number | 否 | 15 | 請求擷取幀率(ideal 和 max 約束) |
cameraPreference | AoqCameraDirection | string | 否 | 瀏覽器選擇 | 攝像頭方向/設備 ID 偏好,使用 ideal 約束,無法滿足時允許回退;空白字符串無效 |
AoqVideoCodecConfig
視訊編解碼設定。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
trackType | AoqTrackType | 否 | — | 保留字段,當前不用於選擇視訊流 |
codecType | AoqEncoderType | 否 | AoqEncoderTypeVideoH264 | 支援 H.264 / JPEG,需與對端協商一致 |
width | number | 否 | 540 | 編碼目標寬度/下行協商聲明寬度(像素),連接時要求正整數 |
height | number | 否 | 960 | 編碼目標高度/下行協商聲明高度(像素),連接時要求正整數 |
fps | number | 否 | 5 | 編碼幀率/下行協商聲明幀率,連接時要求正整數 |
bitrate | number | 否 | 500000(編碼) | 編碼目標碼率(bps),需為正數,解碼不使用 |
minBitrate | number | 否 | 128000 | 編碼最低目標碼率(bps);缺省或 0 使用 128000,且不超過使用者目標;H.264 不因 BWE 預算歸零而暫停編碼;解碼不使用 |
keyframeInterval | number | 否 | 2 | H.264 關鍵幀間隔(秒),編碼時至少按 1 秒處理;JPEG/解碼不使用 |
AoqVideoCanvas
視訊渲染容器設定。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
view | HTMLElement | string | 是 | — | 普通容器元素或其 DOM id(不帶 #);不能直接使用 video、audio、canvas、img 或空元素 |
renderMode | AoqRenderMode | 否 | AoqRenderModeAuto(0) | 畫面適配方式 |
AoqVideoDeviceState
視訊設備狀態回呼資料。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
state | AoqVideoDeviceStateCode | — | 視訊設備狀態碼 |
reason | number | — | 原因碼;主動停止為 0,Web 軌道非主動結束為 AoqECVideoDevice(220) |
資料消息類型
AoqDataMsg
公共 sendDataMsg / onDataMsg 統一使用的消息結構,不接收直接的字符串或 Uint8Array 參數。當前 WT 通路以字節數組承載 UTF-8 文本。
| 字段 | 類型 | 必填 | 預設值 | 說明 |
|---|---|---|---|---|
data | Uint8Array | 是 | — | 發送時必須非空且為有效 UTF-8;接收時使用 msg.data 讀取 |
統計信息類型
AoqStats
引擎統計信息匯總。以下字段在類型定義中均為可選,讀取時應處理缺省情況。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
audioPublishStats | AoqAudioPublishStats[] | — | 音訊推流統計列表 |
audioSubscribeStats | AoqAudioSubscribeStats[] | — | 音訊拉流統計列表 |
videoPublishStats | AoqVideoPublishStats[] | — | 視訊推流統計列表 |
videoSubscribeStats | AoqVideoSubscribeStats[] | — | 視訊拉流統計列表 |
dataMsgPublishStats | AoqDataMsgPublishStats[] | — | 資料消息推流統計列表 |
dataMsgSubscribeStats | AoqDataMsgSubscribeStats[] | — | 資料消息拉流統計列表 |
networkStats | AoqNetworkStats | — | 網絡統計 |
AoqAudioPublishStats
音訊推流統計。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
trackType | AoqTrackType | — | track 類型 |
bitrate | number | — | 當前取連接總上行業務碼率(bps),不是獨立音訊碼率 |
bytes | number | — | 當前取連接總上行業務字節數,不是獨立音訊累計量 |
encodeVolume | number | 0 | 當前為佔位值,擷取音量請使用 onLocalAudioVolumeIndication |
AoqAudioSubscribeStats
音訊拉流統計。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
trackType | AoqTrackType | — | track 類型 |
bitrate | number | — | 當前取連接總下行業務碼率(bps),不是獨立音訊碼率 |
bytes | number | — | 當前取連接總下行業務字節數,不是獨立音訊累計量 |
playVolume | number | 0 | 當前為佔位值,不能據此判斷播放是否靜音 |
AoqVideoPublishStats
視訊推流統計。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
trackType | AoqTrackType | — | track 類型 |
bitrate | number | 0 | 當前未提供分視訊碼率統計,此值為佔位 |
bytes | number | 0 | 當前未提供分視訊字節統計,此值為佔位 |
encodeFps | number | — | 編碼幀率 |
AoqVideoSubscribeStats
視訊拉流統計。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
trackType | AoqTrackType | — | track 類型 |
bitrate | number | 0 | 當前未提供分視訊碼率統計,此值為佔位 |
bytes | number | 0 | 當前未提供分視訊字節統計,此值為佔位 |
decodeFps | number | — | 解碼幀率 |
renderFps | number | — | 渲染幀率 |
AoqDataMsgPublishStats
資料消息推流統計。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
trackType | AoqTrackType | — | track 類型 |
bitrate | number | — | 當前碼率(bps) |
bytes | number | — | 累計發送字節數 |
AoqDataMsgSubscribeStats
資料消息拉流統計。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
trackType | AoqTrackType | — | track 類型 |
bitrate | number | — | 當前碼率(bps) |
bytes | number | — | 累計接收字節數 |
AoqNetworkStats
網絡統計信息。碼率為業務載荷 bit/s,累計量為同口徑字節,不含探測和傳輸協議開銷。
| 字段 | 類型 | 預設值 | 說明 |
|---|---|---|---|
sendBitrate | number | — | 上行碼率(bps) |
sendBytes | number | — | 累計上行字節數 |
recvBitrate | number | — | 下行碼率(bps) |
recvBytes | number | — | 累計下行字節數 |
loss | number | — | 可選;上行丟失比例(0–1),優先瀏覽器 QUIC 觀測,否則使用 Relay Datagram 估計;未知時缺省 |
rtt | number | — | 可選;往返時延(ms),未知時缺省 |
bwe | number | — | 可選;Client→Relay 有效應用發送預算(bps),未知或過期時缺省 |
audioReserveBps | number | — | 可選;當前編碼音訊的淨載荷預留碼率(bps),不包含 RED 冗余和傳輸協議開銷,不等於實際音訊流量 |
枚舉類型
AoqTrackType
track 媒體類型。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqTrackTypeAudio | 0 | 音訊 |
AoqTrackTypeVideo | 1 | 視訊 |
AoqTrackTypeData | 2 | 資料消息 |
AoqTrackTypeScreen | 3 | 保留枚舉,當前連接流程不支援 |
AoqTrackMode
音訊傳輸模式。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqTrackModeSegment | 0 | 分段模式 |
AoqTrackModeStream | 1 | 實時流模式(realtime) |
AoqEncoderType
track 媒體格式。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqEncoderTypeUnknown | 0 | 未知 |
AoqEncoderTypeAudioPCM | 1 | 音訊 PCM |
AoqEncoderTypeAudioOpus | 2 | 音訊 Opus |
AoqEncoderTypeVideoH264 | 3 | 視訊 H.264 |
AoqEncoderTypeVideoJpeg | 4 | 視訊 JPEG |
AoqEncoderTypeDataText | 5 | 文本資料 |
AoqConnectionStatus
引擎連接狀態。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqConnectionStatusDisconnected | 0 | 已斷開 |
AoqConnectionStatusConnecting | 1 | 連接中 |
AoqConnectionStatusConnected | 2 | 已連接 |
AoqConnectionStatusFailed | 3 | 連接失敗 |
AoqErrorCode
錯誤碼。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqECOK | 0 | 成功 |
AoqECParamInvalid | 1 | 參數無效 |
AoqECStateInvalid | 2 | 狀態無效 |
AoqECUnSupport | 3 | 當前平台/模式未實現 |
AoqECAudio | 100 | 音訊通用錯誤 |
AoqECAudioExternalBufferFull | 110 | 外部音訊緩衝區已滿 |
AoqECAudioDevice | 120 | 音訊設備通用錯誤 |
AoqECAudioDeviceRecordingAuthFailed | 121 | 麥克風授權失敗 |
AoqECAudioDeviceRecordingOccupied | 122 | 麥克風被佔用 |
AoqECAudioDeviceRecordingBackgroundStart | 123 | 後台啓動擷取 |
AoqECAudioDeviceRecordingStartFail | 124 | 擷取啓動失敗 |
AoqECAudioDevicePlayoutOccupied | 125 | 播放設備被佔用 |
AoqECAudioDevicePlayoutBackgroundStart | 126 | 後台啓動播放 |
AoqECAudioDevicePlayoutStartFail | 127 | 播放啓動失敗 |
AoqECAudioDeviceEarpieceRequiresVoipMode | 128 | 聽筒需要 VoIP 模式 |
AoqECVideo | 200 | 視訊通用錯誤 |
AoqECVideoExternalBufferFull | 210 | 外部視訊緩衝區已滿 |
AoqECVideoExternalCaptureNotEnabled | 211 | 外部視訊擷取未啓用 |
AoqECVideoExternalEncoderNotEnabled | 212 | 外部視訊編碼器未啓用 |
AoqECVideoDevice | 220 | 視訊設備通用錯誤 |
AoqECVideoDeviceCameraOpenFail | 221 | 攝像頭打開失敗 |
AoqECVideoDeviceCameraAuthFailed | 222 | 攝像頭授權失敗 |
AoqECVideoDeviceCameraOccupied | 223 | 攝像頭被佔用 |
AoqECVideoDeviceCameraRunningError | 224 | 攝像頭運行錯誤 |
AoqECVideoCodec | 230 | 視訊編解碼通用錯誤 |
AoqECVideoCodecEncoderInitFail | 231 | 視訊編碼器初始化失敗 |
AoqECVideoRender | 240 | 視訊渲染通用錯誤 |
AoqECVideoRenderCreateFail | 241 | 渲染器建立失敗 |
AoqECVideoRenderDrawError | 242 | 渲染繪制錯誤 |
AoqWarningCode
警告碼。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqWCOK | 0 | 正常 |
AoqWCAudio | 100 | 音訊通用警告 |
AoqWCAudioHowling | 101 | 檢測到嘯叫 |
AoqWCAudioDevice | 120 | 音訊設備通用警告 |
AoqWCAudioDeviceMicEnumerateError | 121 | 麥克風枚舉錯誤 |
AoqWCAudioDeviceMicStartTimeout | 122 | 麥克風啓動超時 |
AoqWCAudioDeviceRecordingError | 123 | 擷取異常 |
AoqWCAudioDeviceSpeakerEnumerateError | 124 | 揚聲器枚舉錯誤 |
AoqWCAudioDeviceSpeakerStartTimeout | 125 | 揚聲器啓動超時 |
AoqWCAudioDevicePlayoutError | 126 | 播放異常 |
AoqWCAudioDeviceSilentMode | 127 | 設備處於靜音模式 |
AoqWCVideo | 200 | 視訊通用警告 |
AoqWCVideoCameraEnumerateError | 201 | 攝像頭枚舉錯誤 |
AoqWCVideoEncoderSwitched | 202 | 視訊編碼器已切換 |
AoqWCVideoRenderDowngrade | 203 | 渲染降級 |
AoqAudioDeviceStateCode
音訊設備狀態碼。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqAudioDeviceNone | 0 | 無狀態 |
AoqAudioDeviceRecordStarting | 1 | 擷取啓動中 |
AoqAudioDeviceRecordStarted | 2 | 擷取已啓動 |
AoqAudioDeviceRecordStopping | 3 | 擷取停止中 |
AoqAudioDeviceRecordStopped | 4 | 擷取已停止 |
AoqAudioDeviceRecordFail | 5 | 擷取失敗 |
AoqAudioDevicePlayStarting | 6 | 播放啓動中 |
AoqAudioDevicePlayStarted | 7 | 播放已啓動 |
AoqAudioDevicePlayStopping | 8 | 播放停止中 |
AoqAudioDevicePlayStopped | 9 | 播放已停止 |
AoqAudioDevicePlayFail | 10 | 播放失敗 |
AoqAudioDeviceRouteType
音訊設備路由類型。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqAudioDeviceRouteDefault | 0 | 預設路由 |
AoqAudioDeviceRouteHeadset | 1 | 耳機 |
AoqAudioDeviceRouteSpeakerPhone | 4 | 內置揚聲器 |
AoqAudioDeviceRouteUsb | 5 | USB 設備 |
AoqAudioDeviceRouteBluetooth | 6 | 藍牙設備 |
AoqAudioFileStateCode
音訊文件播放狀態碼。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqAudioFileNone | 0 | 無狀態 |
AoqAudioFileStarted | 1 | 播放已開始 |
AoqAudioFileStopped | 2 | 播放已停止 |
AoqAudioFilePaused | 3 | 播放已暫停 |
AoqAudioFileResumed | 4 | 播放已恢復 |
AoqAudioFileEnded | 5 | 播放已結束 |
AoqAudioFileBuffering | 6 | 緩衝中 |
AoqAudioFileBufferingEnd | 7 | 緩衝結束 |
AoqAudioFileFailed | 8 | 播放失敗 |
AoqCameraDirection
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqCameraDirectionFront | 0 | 優先前置 |
AoqCameraDirectionBack | 1 | 優先後置 |
AoqVideoDeviceStateCode
視訊設備狀態碼。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqVideoDeviceNone | 0 | 無狀態 |
AoqVideoDeviceCaptureStarting | 1 | 擷取啓動中 |
AoqVideoDeviceCaptureStarted | 2 | 擷取已啓動 |
AoqVideoDeviceCaptureStopping | 3 | 擷取停止中 |
AoqVideoDeviceCaptureStopped | 4 | 擷取已停止 |
AoqVideoDeviceCaptureFail | 5 | 擷取失敗 |
AoqMirrorMode
預留鏡像模式枚舉;當前 Web 沒有使用該枚舉的設定項或接口。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqMirrorModeDisabled | 0 | 關閉鏡像 |
AoqMirrorModeEnabled | 1 | 開啓鏡像 |
AoqOrientationMode
預留方向模式枚舉;當前 Web 沒有使用該枚舉的設定項或接口。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqOrientationModeAuto | 0 | 自動 |
AoqOrientationModePortrait | 1 | 竪屏 |
AoqOrientationModeLandscape | 2 | 橫屏 |
AoqRenderMode
視訊畫面適配方式。
| 枚舉值 | 值 | 說明 |
|---|---|---|
AoqRenderModeAuto | 0 | 預設等比完整顯示 |
AoqRenderModeStretch | 1 | 拉伸鋪滿容器 |
AoqRenderModeFill | 2 | 等比完整顯示,允許留黑邊 |
AoqRenderModeCrop | 3 | 等比鋪滿,裁剪超出部分 |
其他公開聲明
IAoqEngineEvents 定義了 事件回呼 中的 10 個回呼簽名,其中 onAudioFileState 為預留事件。使用事件名訂閱時可直接獲得 TypeScript 參數推導。
以下類型或枚舉雖由包入口導出,但當前 Web 門面沒有對應控制/觀察接口,不能按其他平台同名聲明推斷能力:
| 類別 | 公開聲明 | 當前邊界 |
|---|---|---|
| 音訊文件混音 | AoqAudioFileMixConfig、AoqAudioFileState、AoqAudioFileStateCode | 無文件播放/混音控制方法,文件狀態事件不觸發 |
| 外部音訊與觀察 | AoqAudioExternalStreamConfig、AoqAudioExternalFrameMeta、AoqAudioObserverParams、AoqAudioSource、AoqAudioStreamDirection | 無外部音訊輸入或音訊幀觀察者註冊方法 |
| 外部視訊與觀察 | AoqExternalVideoFrameMeta、AoqExternalVideoEncodedFrameMeta、AoqVideoObserverParams、AoqVideoSource、AoqVideoPixelFormat、AoqVideoObserverAlignment、AoqVideoCodecType | 無外部視訊幀輸入或視訊幀觀察者註冊方法;實際編解碼設定使用 AoqEncoderType |
| 鏡像與方向 | AoqMirrorMode、AoqOrientationMode | 無對應設定字段或方法;本地預覽鏡像由 SDK 自動處理 |
| 底層音訊設備 | AoqAudioDeviceEvent、AudioDeviceApiError、AudioDeviceErrorCode | 底層設備聲明,不是引擎新增事件或完整的門面返回碼契約 |
AOQ_TRACK_AUDIO 和 AOQ_TRACK_DATA 分別為字符串常量 'aoq_track_audio'、'aoq_track_data';不是傳給連接或視圖方法的 Track 選擇參數,業務接口應使用 AoqTrackType。
錯誤和警告枚舉保留了跨平台值,不保證所有值都會由當前 Web 實現產生。具體接口是否可用,以本文方法和其調用條件為準。