Skip to main content

AOQ Web SDK API 參考

AOQ Web SDK 支援在瀏覽器中進行即時音視訊和資料互動。本文介紹引擎管理、音視訊擷取與播放、資料訊息和事件回呼等 API。

安裝 SDK

AOQ Web SDK 透過 WebTransport(HTTP/3 / QUIC)連線至服務端,並在 Worker 中收發音訊、視訊和資料訊息。使用 SDK 需要支援 WebTransport 的瀏覽器及 HTTPS 安全上下文,可透過 AoqClientEngine.isAoqSupported() 檢查瀏覽器的基本能力。 透過 npm 安裝 SDK:
npm install aoq-web-sdk@1.0.1-60040320
也可以在SDK 下載頁面下載安裝套件,並在專案目錄中執行以下命令。將安裝套件路徑替換為實際路徑。
npm install ./aoq-web-sdk-1.0.1-60040320.tgz

接口目錄

引擎生命週期

接口簡介
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

建立引擎實例。採用單例模式,重復調用返回已有實例。
static createEngine(config: AoqCreateConfig): AoqClientEngine | null
參數類型說明
configAoqCreateConfig引擎建立設定
返回值:成功返回 AoqClientEngine 實例,失敗返回 null。 說明 引擎為單例,若已存在已初始化的實例則直接返回該實例,不會重新應用設定。銷毀後可重新建立。

createAoqClientEngine

從包入口具名導入的便捷工廠,等價於 AoqClientEngine.createEngine(config),不是實例方法,也不需要二次初始化。
function createAoqClientEngine(config: AoqCreateConfig): AoqClientEngine | null
參數類型說明
configAoqCreateConfig必傳,可傳 {};重復建立不重新應用設定
返回值:成功返回單例引擎,失敗返回 null。
import { createAoqClientEngine } from 'aoq-web-sdk';

const engine = createAoqClientEngine({});
if (!engine) throw new Error('创建引擎失败');

destroy

銷毀引擎實例,發起資源釋放並移除全部事件監聽。
static destroy(): number
返回值:0 表示成功,AoqECStateInvalid(2) 表示當前無實例。 說明 銷毀接口同步返回;日誌保存、可選 dump 導出等異步收尾在後台執行,不代表返回時所有任務已完成。銷毀後需重新調用 createEngine 才能繼續使用 SDK,舊實例不可繼續調用。

getVersion

取得 SDK 版本號。
static getVersion(): string
返回值:當前安裝包的版本號字符串,與該包的版本一致;不返回文檔修訂號或源碼提交號。

isAoqSupported

檢查當前瀏覽器環境是否具備使用 AOQ 連接的基礎能力。
static isAoqSupported(): Promise<AoqSupportResult>
返回值:Promise<AoqSupportResult>,包含是否支援及缺失能力列表。 說明 返回 supported: true 不代表連接或音視訊通話一定成功;不檢查網絡可達性、服務端設定、鑒權、設備授權及具體媒體設定的可用性。檢測在 Worker 內執行 WebTransport 能力探測,超時為 5 秒。

connect

發起與服務端的連接。
connect(config: AoqConnectConfig): number
參數類型說明
configAoqConnectConfig連接鑒權設定,包含 token、會話 ID、接入點等
返回值:0 表示調用成功。 說明 在建立引擎、註冊事件及編解碼設定完成後調用,正常從 Disconnected 發起;Failed 狀態允許重新發起,其他狀態返回 AoqECStateInvalid(2)。不合法的 Track/媒體設定、連接參數,或選用 Opus 但缺少所需 WebCodecs 能力,均可返回 AoqECParamInvalid(1);Network Worker 不可用返回 AoqECStateInvalid(2)。 返回 0 僅表示連接請求已受理。連接結果通過 onConnectionStatusChange 異步通知,Connected 表示 MEDIA_SETUP 完成且媒體軌道已綁定,不等於模型業務就緒;業務側仍需按模型資料協議設定會話並確認就緒,再啓用音視訊發送。

disconnect

斷開與服務端的連接。
disconnect(): number
返回值:0 表示調用成功。 說明 斷開結果通過 onConnectionStatusChange 事件通知,等待 AoqConnectionStatusDisconnected 後再修改編解碼設定並重新連接。已斷開時調用返回 AoqECStateInvalid(2)。斷開不替代設備停止,結束通話還應調用對應擷取/播放停止接口。

音訊設備管理

startAudioCapture

啓動音訊擷取(麥克風),異步請求設備權限。
startAudioCapture(config: AoqAudioCaptureConfig): Promise<number>
參數類型說明
configAoqAudioCaptureConfig音訊擷取設定
返回值:Promise<number>,0 表示成功。 說明 首次使用或權限未授予時可能觸發瀏覽器麥克風授權彈窗。擷取狀態變化通過 onAudioDeviceStateChanged 事件通知。 說明 網絡擁塞時,上行音訊在發送隊列中等待達到約 100 ms 即被丟棄,以避免延遲累積;已開始發送的音訊不撤回,該值不代表端到端延遲上限。

stopAudioCapture

停止音訊擷取。
stopAudioCapture(): number
返回值:0 表示成功。 說明 設備尚未啓動或已停止時返回 AoqECStateInvalid(2)。

muteAudioCapture

靜音或取消靜音音訊擷取。靜音後繼續擷取但發送靜音幀。
muteAudioCapture(mute: boolean): number
參數類型說明
mutebooleantrue 靜音,false 取消靜音
返回值:0 表示成功。

startAudioPlayer

啓動音訊播放器,異步初始化音訊輸出設備。
startAudioPlayer(config: AoqAudioPlaybackConfig): Promise<number>
參數類型說明
configAoqAudioPlaybackConfig音訊播放設定
返回值:Promise<number>,0 表示成功。 說明 播放狀態變化通過 onAudioDeviceStateChanged 事件通知。 說明 應從使用者點擊事件調用並處理自動播放限制;播放器正在啓動或已啓動時重復調用返回 AoqECStateInvalid(2)。 說明 Realtime 模式(音訊下行 trackMode 為 Stream)下,播放器啓動前收到的音訊會被持續消費而不積壓;每次啓動(含首次)都會清除此前的音訊,從之後收到的新音訊開始播放,不補播啓動前的語音。Segment 模式保留尚未播放的內容。

stopAudioPlayer

停止音訊播放器。
stopAudioPlayer(): number
返回值:0 表示成功。 說明 設備尚未啓動或已停止時返回 AoqECStateInvalid(2)。 說明 Realtime 模式停止設備輸出後,SDK 仍持續消費收到的音訊,視訊繼續播放;再次啓動只播放新音訊。已有的暫停或打斷狀態在重新啓動後仍然保留。Segment 模式保留尚未播放的內容。

pauseAudioPlayer

暫停音訊播放,淡出完成後停止輸出,後續可調用 resumeAudioPlayer 恢復。
pauseAudioPlayer(fadeMs: number): number
參數類型說明
fadeMsnumber淡出時長(ms),按實際設備採樣率四捨五入到樣本數;0 不執行淡出,負數或非有限值使用 100 ms
返回值:0 表示控制請求已受理,不證明播放器正在播放或淡出已經完成。 說明 Segment 模式凍結未播放內容及讀取位置,恢復後從暫停處接續。Realtime 模式丟棄待播音訊,暫停期間繼續消費收到的音訊,恢復後從當前實時位置播放,不補播暫停期間的內容。

resumeAudioPlayer

恢復暫停或打斷的音訊播放,使用預設淡入:Segment 為 2 ms,Realtime 為 100 ms。
resumeAudioPlayer(fadeMs: number): number
參數類型說明
fadeMsnumber保留參數,當前忽略傳入時長;恢復使用預設淡入,不能通過傳 0 取消
返回值:0 表示控制請求已受理,不證明恢復已經完成。

interruptAudioPlayer

打斷當前音訊播放,淡出完成後丟棄被打斷的未播放餘量;與 Segment 模式保留餘量的暫停不同,之後恢復也不會重新播放已丟棄的部分。
interruptAudioPlayer(trackType: AoqTrackType, fadeMs: number): number
參數類型說明
trackTypeAoqTrackType兼容性參數,建議傳 Audio;當前未按此參數區分播放流
fadeMsnumber淡出時長(ms),按實際設備採樣率四捨五入到樣本數;0 不執行淡出,負數或非有限值使用 100 ms
返回值:0 表示控制請求已受理,不證明播放器正在播放或打斷已經完成。 說明 打斷後,服務端下發新一輪音訊時自動恢復播放,也可調用 resumeAudioPlayer 恢復。 說明 暫停狀態下的打斷請求會被忽略,仍可能返回 0;Segment 模式恢復後會繼續播放暫停前的餘量。不要將“暫停 → 打斷”的調用序列當作清空播放隊列。

音訊編碼設定

setAudioEncoderConfig

設置音訊編碼參數。
setAudioEncoderConfig(config: AoqAudioCodecConfig): number
參數類型說明
configAoqAudioCodecConfig音訊編碼設定
返回值:0 表示成功。 說明 必須在 connect() 前、引擎處於 Disconnected 時調用。連接中或已連接時修改返回 AoqECStateInvalid(2);需先斷開並等待 Disconnected,再設定及重新連接。 說明 返回 0 表示設定請求已受理;音訊格式在建連時再次校驗,Opus 還依賴瀏覽器 WebCodecs 能力。

setAudioDecoderConfig

設置音訊解碼參數。
setAudioDecoderConfig(config: AoqAudioCodecConfig): number
參數類型說明
configAoqAudioCodecConfig音訊解碼設定
返回值:0 表示成功。 說明 必須在 connect() 前、引擎處於 Disconnected 時調用。連接中或已連接時修改返回 AoqECStateInvalid(2)。

本地音量提示

enableLocalAudioVolumeIndication

開啓或關閉本地擷取音量提示。開啓後通過 onLocalAudioVolumeIndication 事件週期性回呼音量信息。
enableLocalAudioVolumeIndication(config: AoqAudioVolumeIndicationConfig): number
參數類型說明
configAoqAudioVolumeIndicationConfig音量提示設定
返回值:0 表示成功。 說明interval 設置為 0 或負值表示關閉回呼。

視訊設備管理

startVideoCapture

啓動視訊擷取(攝像頭)。
startVideoCapture(config: AoqVideoCaptureConfig): number
參數類型說明
configAoqVideoCaptureConfig視訊擷取設定
返回值:0 表示成功。 說明 返回 0 僅表示異步擷取請求已受理,不能據此判定攝像頭已開啓。實際成功/失敗通過 onVideoDeviceStateChanged 事件通知。 cameraPreference 為攝像頭選擇偏好,可傳方向枚舉或設備 ID;省略時由瀏覽器選擇。方向或設備 ID 無法滿足時,均允許瀏覽器選擇其他可用攝像頭。

getCameras

getCameras(): Promise<MediaDeviceInfo[]>
枚舉瀏覽器可見的 videoinput,不打開攝像頭或主動申請權限。未授權時設備名稱或 ID 可能不完整,授權或設備插拔後可重新枚舉;引擎未初始化或枚舉失敗時 Promise 拒絕。

switchCamera

switchCamera(cameraPreference?: AoqCameraDirection | string): number
參數類型必填說明
cameraPreferenceAoqCameraDirection | string否方向或設備 ID 偏好;省略時清除先前偏好,重新由瀏覽器選擇
方向和設備 ID 使用 ideal 約束,無法滿足時允許回退到其他可用攝像頭。返回 0 只表示受理,狀態通過 onVideoDeviceStateChanged 通知,失敗原因通過 onError 報告。未擷取、正在啓動或正在切換時返回 AoqECStateInvalid(2);非法方向或空白 ID 返回 AoqECParamInvalid(1)。 切換先釋放舊設備,再打開目標並等待首幀,若舊擷取向 Worker 轉移過攝像頭軌道(包括隨後回退到主執行緒的情況),打開設備前會等待釋放確認,最多等待 2 秒;確認超時則報告失敗,不繼續打開目標或恢復設備。每次嘗試最多 15 秒。失敗後嘗試以原設備為偏好恢復擷取一次,恢復成功仍報告本次切換失敗。成功通知 CaptureStarted(reason=0);失敗但已恢復擷取通知 CaptureStarted(reason=失敗碼);無法恢復通知 CaptureFail(reason=失敗碼)。顯式目標已滿足時異步通知 CaptureStarted,不重開設備。狀態回呼不提供實際設備 ID,不能把請求偏好當作實際設備。切換不改變發送開關、編碼設定和預覽綁定;停止擷取可取消切換,銷毀後不再回呼。 切換可能短暫中斷畫面;擷取時間線保持連續,但不保證硬件級音畫同步。實際設備由瀏覽器選擇,業務 UI 不應將請求偏好直接顯示為已選設備。

stopVideoCapture

停止視訊擷取。
stopVideoCapture(): number
返回值:0 表示成功。 說明 設備尚未啓動或已停止時返回 AoqECStateInvalid(2)。

setLocalView

設置本地視訊渲染容器。SDK 會在指定容器內建立渲染元素。
setLocalView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number
參數類型說明
trackTypeAoqTrackType僅支援 AoqTrackTypeVideo,其他類型返回 AoqECUnSupport(3)
canvasAoqVideoCanvas | null渲染容器設定,傳 null 解除綁定
返回值:0 表示成功。 說明 容器元素應具有明確尺寸,SDK 在容器內部建立實際渲染元素。 說明 使用尺寸明確的普通 DOM 容器(例如 div),不能直接傳入 video、audio、canvas、img 或空元素。容器無效、id 不存在或 renderMode 非法時返回 AoqECParamInvalid(1),保留原綁定;返回 0 僅表示綁定受理,不保證已經渲染首幀。

setRemoteView

設置遠端視訊渲染容器。SDK 會在指定容器內建立渲染元素。
setRemoteView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number
參數類型說明
trackTypeAoqTrackType僅支援 AoqTrackTypeVideo,其他類型返回 AoqECUnSupport(3)
canvasAoqVideoCanvas | null渲染容器設定,傳 null 解除綁定
返回值:0 表示成功。 說明 使用尺寸明確的普通 DOM 容器(例如 div),不能直接傳入 video、audio、canvas、img 或空元素。容器無效、id 不存在或 renderMode 非法時返回 AoqECParamInvalid(1),保留原綁定;返回 0 僅表示綁定受理,不保證已經渲染首幀。

視訊編碼設定

setVideoEncoderConfig

設置視訊編碼參數。
setVideoEncoderConfig(config: AoqVideoCodecConfig): number
參數類型說明
configAoqVideoCodecConfig視訊編碼設定
返回值:0 表示成功。 說明 必須在引擎處於 Disconnected 時調用,連接中或已連接時返回 AoqECStateInvalid(2)。建議在首次連接及視訊擷取前完成設定;設定合併緩存用於後續建流,不立即重配已有擷取或編碼器。

setVideoDecoderConfig

設置視訊解碼參數。
setVideoDecoderConfig(config: AoqVideoCodecConfig): number
參數類型說明
configAoqVideoCodecConfig視訊解碼設定
返回值:0 表示成功。 說明 必須在 connect() 前、引擎處於 Disconnected 時調用。連接中或已連接時修改返回 AoqECStateInvalid(2)。

媒體流發送控制

enableSendMediaStream

啓用或禁用音訊或視訊 Track 的媒體流發送。
enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number
參數類型說明
trackTypeAoqTrackType媒體 track 類型
enablebooleantrue 啓用發送,false 禁用發送
返回值:0 表示成功。 說明 當前僅控制 Audio / Video,不能控制 Data 發送;其他 Track 值即使返回 0 也不代表生效。停發不關閉擷取設備;需要關閉設備時調用相應 stop...Capture()。

實時消息

sendDataMsg

發送以 Uint8Array 承載的 UTF-8 文本消息到遠端,可用於業務 JSON。當前 WT 通路不支援任意二進制載荷,也不能用此接口發送 SDK 內部控制消息。
sendDataMsg(msg: AoqDataMsg): number
參數類型說明
msgAoqDataMsg消息對象,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、臨時憑證等敏感信息。
const data = new TextEncoder().encode(JSON.stringify({ type: 'user_message', text: '你好' }));
const code = engine.sendDataMsg({ data });
if (code !== 0) console.error('消息未受理', code);
示例 JSON 僅用於展示編碼方式,實際字段和業務就緒流程應遵循所用模型的資料消息協議。

事件回呼

事件通過 engine.on('eventName', callback) 訂閱,engine.once(...) 僅監聽一次,engine.off('eventName', callback) 取消相同函數引用的監聽;銷毀引擎會移除全部監聽。應在連接或啓動設備前註冊,並保持回呼輕量。
import { AoqConnectionStatus } from 'aoq-web-sdk';

const handleStatus = (status: AoqConnectionStatus) => console.log('连接状态', status);
engine.on('onConnectionStatusChange', handleStatus);
engine.off('onConnectionStatusChange', handleStatus);
事件名回呼簽名說明
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 用於排查問題;收到錯誤不等於整個連接已終結,應結合連接和設備狀態判斷。網絡錯誤可能使用通用狀態錯誤碼,不應僅按數字推斷錯誤階段。
engine.on('onError', (code: number, message: string) => { /* 在此处理回调 */ });
參數類型說明
codenumber錯誤碼,參見 AoqErrorCode 枚舉
messagestring錯誤描述信息

onWarning

引擎警告回呼,通知可忽略但需關注的異常情況。
engine.on('onWarning', (code: number, message: string) => { /* 在此处理回调 */ });
參數類型說明
codenumber警告碼,參見 AoqWarningCode 枚舉
messagestring警告描述信息

onConnectionStatusChange

連接狀態變化回呼。
engine.on('onConnectionStatusChange', (status: AoqConnectionStatus) => { /* 在此处理回调 */ });
參數類型說明
statusAoqConnectionStatus當前連接狀態

onStats

連接成功期間約每秒回呼一次統計信息;離開 Connected 狀態後停止。字段可用性見 AoqStats,不能把佔位值當成真實測量。
engine.on('onStats', (stats: AoqStats) => { /* 在此处理回调 */ });
參數類型說明
statsAoqStats統計信息對象

onAudioDeviceStateChanged

音訊設備(擷取/播放)操作狀態變化回呼。
engine.on('onAudioDeviceStateChanged', (state: AoqAudioDeviceState) => { /* 在此处理回调 */ });
參數類型說明
stateAoqAudioDeviceState音訊設備狀態

onAudioDeviceRouteChanged

輸出設備列表變化時,SDK 根據瀏覽器設備標籤盡力推斷路由類型並回呼。該事件不是實際輸出路由的確認,可能誤判或漏報;授權前或設備信息不完整時可能返回預設類型。
engine.on('onAudioDeviceRouteChanged', (routeType: AoqAudioDeviceRouteType) => { /* 在此处理回调 */ });
參數類型說明
routeTypeAoqAudioDeviceRouteType根據設備標籤推斷的路由類型,不能據此確認實際輸出設備

onAudioFileState

預留的音訊文件狀態回呼。當前 AoqClientEngine 門面沒有文件播放控制方法,也未觸發此事件。
engine.on('onAudioFileState', (state: AoqAudioFileState) => { /* 在此处理回调 */ });
參數類型說明
stateAoqAudioFileState音訊文件狀態

onLocalAudioVolumeIndication

本地擷取音量提示回呼。需先調用 enableLocalAudioVolumeIndication 開啓。
engine.on('onLocalAudioVolumeIndication', (volume: AoqAudioVolume) => { /* 在此处理回调 */ });
參數類型說明
volumeAoqAudioVolume音量信息

onVideoDeviceStateChanged

視訊設備擷取操作狀態變化回呼。
engine.on('onVideoDeviceStateChanged', (state: AoqVideoDeviceState) => { /* 在此处理回调 */ });
參數類型說明
stateAoqVideoDeviceState視訊設備狀態

onDataMsg

接收遠端資料消息回呼。
engine.on('onDataMsg', (msg: AoqDataMsg) => { /* 使用 msg.data 读取消息数据 */ });
參數類型說明
msgAoqDataMsg接收的消息對象,使用 TextDecoder 讀取 msg.data 中的 UTF-8 文本
說明 接收資料消息需在 subscribeTracks 中設定 Data;回呼參數是對象,不是直接的 Uint8Array。業務 JSON 的解析和校驗由業務側完成。

資料類型與枚舉

通用類型

AoqCreateConfig

引擎建立設定。
字段類型必填預設值說明
workDirstring否—保留字段,當前 Web 實現不使用此設定指定存儲目錄
enableDumpAudioboolean否false是否保存音訊調試資料;涉及使用者音訊,應取得授權並控制訪問
enableDumpExportboolean否false僅在 enableDumpAudio=true 時生效;銷毀時異步導出 dump ZIP 並清理相應 OPFS 文件
maxEncodedVideoFrameBytesnumber否194560(190×1024)JPEG 單幀目標上限(byte),0 關閉;超限自動降質,非法值使用預設值
enableDropOversizedVideoFrameboolean否false最低 JPEG 質量仍超限時是否丟幀;false 時仍可能發送超限幀,上限為 0 時不因此丟幀
extrasstring否—JSON 對象字符串;非法 JSON、非對象或非法遠端渲染策略導致 createEngine 返回 null
可使用的 extras 設定:
JSON 字段類型預設值說明
remoteVideoRenderer'auto' | 'video' | 'canvas''auto'遠端渲染策略;auto 優先 video,必要時回退 canvas
user_specified_enable_av_syncbooleantrue是否啓用音畫同步;建議使用 JSON 布爾值
user_specified_audio_playback_transport'message-port'自動選擇指定 MessagePort 播放;省略時按環境自動選擇共享內存或 MessagePort
這些字段不用於修改 HTTP 響應頭或開啓公共診斷 API。

AoqConnectConfig

連接鑒權設定。
字段類型必填預設值說明
tokenstring是—非空客戶端臨時 token,對應 aoqTokenForClient,不是 API Key
sidstring是—非空會話 ID,當前取鑒權響應的完整 sid 字符串
wtBaseUrlstring否根據 Relay 構造單路由時優先使用的 HTTPS WT URL,多路由時忽略並按各自主機、端口連接 /aoq
signedSidstring是(運行時)—完整簽名 SID,通常使用鑒權響應的完整 sid;TypeScript 標為可選,當前 WT 仍要求有效值
certFingerprintstring | string[]條件必填—公共 WT 證書 SHA-256 指紋;未提供獨立指紋的路由必須能使用此值
workspaceIdHashstring否—對應 extraInfo.workspaceIdHash,不能用原始 Workspace ID 代替
relayEndpointsAoqRelayEndpoint[]是—完整接入點列表,至少一項
publishTracksAoqTrackParam[]是—上行 Track 列表,可為空;與 subscribeTracks 不能同時為空
subscribeTracksAoqTrackParam[]是—下行 Track 列表,可為空;同一方向不能重復 Track,當前不支援 Screen
說明 業務後端應返回完整有效的連接材料,適配層將 clientRelayEndpoints[].route_index 映射為 routeIndex,不要自行補造 SID、接入地址、路由索引或指紋。 WT 指紋必須對應實際 WebTransport 入口證書。若後端使用 sha256/<hex> 格式,適配層需去掉前綴並校驗為 64 位十六進制。公共和路由指紋均可為單個字符串或字符串數組;數組每項均須有效,瀏覽器匹配任一項即可通過。路由非空指紋覆蓋公共指紋,空數組視為未設定。SDK 不內置通用指紋,也不提供跳過校驗選項。 缺少 signedSid 或有效指紋可能在異步連接階段失敗,即使 connect() 已返回 0,也應處理狀態事件及 onError。

AoqRelayEndpoint

Relay 接入點。
字段類型必填預設值說明
routeIndexnumber是(運行時)—唯一的 0..2147483647 整數,初連選擇最小索引;TypeScript 標為可選
certFingerprintstring | string[]條件必填公共指紋當前路由指紋,非空值覆蓋公共設定;無公共指紋時必須提供
endpointstring是—WT 主機名/IP,不含協議、路徑、空白、使用者信息或查詢串;支援 IPv6
portnumber是—WT 端口,1..65535 的整數

AoqTrackParam

track 屬性。
字段類型必填預設值說明
trackTypeAoqTrackType是—Audio、Video 或 Data;同一方向不可重復,Screen 當前不支援
trackModeAoqTrackMode否音訊下行為 Segment僅控制音訊下行:PCM / Opus 預設 Segment,顯式 Stream 選擇 Realtime;音訊上行固定 Realtime,上行及視訊/資料忽略此字段

AoqSupportResult

瀏覽器能力檢測結果。
字段類型預設值說明
supportedboolean—當前環境是否具備使用 AOQ 連接的基礎能力
missingFeaturesAoqMissingFeature[]—已觀察到的預檢失敗項列表,可能包含 'secure-context'、'worker'、'web-transport'

AoqMissingFeature

基礎能力預檢失敗項:'secure-context' | 'worker' | 'web-transport'。worker 也可能表示部署策略阻止、啓動/執行失敗或探測超時,不一定是瀏覽器缺少 Worker API;失敗列表不是全部媒體能力的檢測結果。

音訊類型

AoqAudioCaptureConfig

音訊擷取設定。
字段類型必填預設值說明
channelnumber否1請求擷取通道數,支援 1(單聲道)/ 2(立體聲);實際可能由設備軌道設置決定

AoqAudioPlaybackConfig

音訊播放設定。
字段類型必填預設值說明
channelnumber否1請求播放通道數,支援 1 / 2;輸出採樣率使用實際 AudioContext 採樣率
playOnlyAndIgnoreMuteboolean否false僅播放場景使用;瀏覽器支援 audioSession 時設為 playback,以避免 iOS 靜音開關影響。需要擷取麥克風時保持 false;不支援時無法保證忽略靜音開關

AoqAudioCodecConfig

音訊編解碼設定。
字段類型必填預設值說明
trackTypeAoqTrackType否—保留字段,當前不用於選擇音訊流
codecTypeAoqEncoderType否AoqEncoderTypeAudioPCM支援 PCM / Opus,需與對端協商一致
sampleRatenumber否48000採樣率(Hz);協商支援 8000、12000、16000、24000、32000、44100、48000,具體編碼仍需瀏覽器支援
channelnumber否1聲道數,1 或 2
bitratenumber否32000(Opus 編碼)單位 bps,僅 Opus 編碼使用;PCM 碼率由採樣率、聲道和位深決定,解碼不使用

AoqAudioVolumeIndicationConfig

本地音量提示設定。
字段類型必填預設值說明
intervalnumber否0回呼間隔(ms);<=0 關閉,正數小於 10 時按 10 處理
smoothnumber否3音量平滑系數,範圍 0..10,越大越平滑
reportSpeechboolean否false是否上報語音活動狀態(VAD)

AoqAudioVolume

本地音量信息。
字段類型預設值說明
volumenumber—平滑後的瞬時音量,取值範圍 [0-255]
isSpeechboolean—可選,語音活動標誌,僅 reportSpeech=true 時有意義,調用方應處理缺省值

AoqAudioDeviceState

音訊設備狀態回呼資料。
字段類型預設值說明
stateAoqAudioDeviceStateCode—音訊設備狀態碼
reasonnumber—原因碼,參見 AoqErrorCode

AoqAudioFileState

預留的音訊文件播放狀態結構;當前 Web 不觸發對應事件。
字段類型預設值說明
fileIdstring—音訊文件標識
stateCodeAoqAudioFileStateCode—文件播放狀態碼
errorCodenumber—錯誤碼

視訊類型

AoqVideoCaptureConfig

視訊擷取設定。
字段類型必填預設值說明
widthnumber否1280請求擷取寬度(像素,ideal 約束),實際由瀏覽器/設備決定
heightnumber否720請求擷取高度(像素,ideal 約束),實際由瀏覽器/設備決定
fpsnumber否15請求擷取幀率(ideal 和 max 約束)
cameraPreferenceAoqCameraDirection | string否瀏覽器選擇攝像頭方向/設備 ID 偏好,使用 ideal 約束,無法滿足時允許回退;空白字符串無效

AoqVideoCodecConfig

視訊編解碼設定。
字段類型必填預設值說明
trackTypeAoqTrackType否—保留字段,當前不用於選擇視訊流
codecTypeAoqEncoderType否AoqEncoderTypeVideoH264支援 H.264 / JPEG,需與對端協商一致
widthnumber否540編碼目標寬度/下行協商聲明寬度(像素),連接時要求正整數
heightnumber否960編碼目標高度/下行協商聲明高度(像素),連接時要求正整數
fpsnumber否5編碼幀率/下行協商聲明幀率,連接時要求正整數
bitratenumber否500000(編碼)編碼目標碼率(bps),需為正數,解碼不使用
minBitratenumber否128000編碼最低目標碼率(bps);缺省或 0 使用 128000,且不超過使用者目標;H.264 不因 BWE 預算歸零而暫停編碼;解碼不使用
keyframeIntervalnumber否2H.264 關鍵幀間隔(秒),編碼時至少按 1 秒處理;JPEG/解碼不使用

AoqVideoCanvas

視訊渲染容器設定。
字段類型必填預設值說明
viewHTMLElement | string是—普通容器元素或其 DOM id(不帶 #);不能直接使用 video、audio、canvas、img 或空元素
renderModeAoqRenderMode否AoqRenderModeAuto(0)畫面適配方式
本地預覽根據實際擷取軌道的前置方向自動進行 CSS 鏡像,方向未知時不鏡像;這不改變編碼像素。當前沒有獨立的鏡像或方向設定項。非法替換保留原綁定;傳 null 解綁僅移除 SDK 自有渲染節點,保留業務節點。

AoqVideoDeviceState

視訊設備狀態回呼資料。
字段類型預設值說明
stateAoqVideoDeviceStateCode—視訊設備狀態碼
reasonnumber—原因碼;主動停止為 0,Web 軌道非主動結束為 AoqECVideoDevice(220)

資料消息類型

AoqDataMsg

公共 sendDataMsg / onDataMsg 統一使用的消息結構,不接收直接的字符串或 Uint8Array 參數。當前 WT 通路以字節數組承載 UTF-8 文本。
字段類型必填預設值說明
dataUint8Array是—發送時必須非空且為有效 UTF-8;接收時使用 msg.data 讀取

統計信息類型

AoqStats

引擎統計信息匯總。以下字段在類型定義中均為可選,讀取時應處理缺省情況。
字段類型預設值說明
audioPublishStatsAoqAudioPublishStats[]—音訊推流統計列表
audioSubscribeStatsAoqAudioSubscribeStats[]—音訊拉流統計列表
videoPublishStatsAoqVideoPublishStats[]—視訊推流統計列表
videoSubscribeStatsAoqVideoSubscribeStats[]—視訊拉流統計列表
dataMsgPublishStatsAoqDataMsgPublishStats[]—資料消息推流統計列表
dataMsgSubscribeStatsAoqDataMsgSubscribeStats[]—資料消息拉流統計列表
networkStatsAoqNetworkStats—網絡統計
說明 當前 onStats 未填充 dataMsgPublishStats / dataMsgSubscribeStats。音訊數組的 bitrate / bytes 使用連接總量,尚非獨立音訊流量;encodeVolume / playVolume 固定為 0。視訊數組的 bitrate / bytes 也固定為 0,僅幀率由視訊引擎提供。總流量請讀 networkStats,擷取音量請使用 onLocalAudioVolumeIndication。

AoqAudioPublishStats

音訊推流統計。
字段類型預設值說明
trackTypeAoqTrackType—track 類型
bitratenumber—當前取連接總上行業務碼率(bps),不是獨立音訊碼率
bytesnumber—當前取連接總上行業務字節數,不是獨立音訊累計量
encodeVolumenumber0當前為佔位值,擷取音量請使用 onLocalAudioVolumeIndication

AoqAudioSubscribeStats

音訊拉流統計。
字段類型預設值說明
trackTypeAoqTrackType—track 類型
bitratenumber—當前取連接總下行業務碼率(bps),不是獨立音訊碼率
bytesnumber—當前取連接總下行業務字節數,不是獨立音訊累計量
playVolumenumber0當前為佔位值,不能據此判斷播放是否靜音

AoqVideoPublishStats

視訊推流統計。
字段類型預設值說明
trackTypeAoqTrackType—track 類型
bitratenumber0當前未提供分視訊碼率統計,此值為佔位
bytesnumber0當前未提供分視訊字節統計,此值為佔位
encodeFpsnumber—編碼幀率

AoqVideoSubscribeStats

視訊拉流統計。
字段類型預設值說明
trackTypeAoqTrackType—track 類型
bitratenumber0當前未提供分視訊碼率統計,此值為佔位
bytesnumber0當前未提供分視訊字節統計,此值為佔位
decodeFpsnumber—解碼幀率
renderFpsnumber—渲染幀率

AoqDataMsgPublishStats

資料消息推流統計。
字段類型預設值說明
trackTypeAoqTrackType—track 類型
bitratenumber—當前碼率(bps)
bytesnumber—累計發送字節數
說明 類型已定義,但當前 onStats 不填充此統計數組。

AoqDataMsgSubscribeStats

資料消息拉流統計。
字段類型預設值說明
trackTypeAoqTrackType—track 類型
bitratenumber—當前碼率(bps)
bytesnumber—累計接收字節數
說明 類型已定義,但當前 onStats 不填充此統計數組。

AoqNetworkStats

網絡統計信息。碼率為業務載荷 bit/s,累計量為同口徑字節,不含探測和傳輸協議開銷。
字段類型預設值說明
sendBitratenumber—上行碼率(bps)
sendBytesnumber—累計上行字節數
recvBitratenumber—下行碼率(bps)
recvBytesnumber—累計下行字節數
lossnumber—可選;上行丟失比例(0–1),優先瀏覽器 QUIC 觀測,否則使用 Relay Datagram 估計;未知時缺省
rttnumber—可選;往返時延(ms),未知時缺省
bwenumber—可選;Client→Relay 有效應用發送預算(bps),未知或過期時缺省
audioReserveBpsnumber—可選;當前編碼音訊的淨載荷預留碼率(bps),不包含 RED 冗余和傳輸協議開銷,不等於實際音訊流量

枚舉類型

AoqTrackType

track 媒體類型。
枚舉值值說明
AoqTrackTypeAudio0音訊
AoqTrackTypeVideo1視訊
AoqTrackTypeData2資料消息
AoqTrackTypeScreen3保留枚舉,當前連接流程不支援

AoqTrackMode

音訊傳輸模式。
枚舉值值說明
AoqTrackModeSegment0分段模式
AoqTrackModeStream1實時流模式(realtime)

AoqEncoderType

track 媒體格式。
枚舉值值說明
AoqEncoderTypeUnknown0未知
AoqEncoderTypeAudioPCM1音訊 PCM
AoqEncoderTypeAudioOpus2音訊 Opus
AoqEncoderTypeVideoH2643視訊 H.264
AoqEncoderTypeVideoJpeg4視訊 JPEG
AoqEncoderTypeDataText5文本資料

AoqConnectionStatus

引擎連接狀態。
枚舉值值說明
AoqConnectionStatusDisconnected0已斷開
AoqConnectionStatusConnecting1連接中
AoqConnectionStatusConnected2已連接
AoqConnectionStatusFailed3連接失敗

AoqErrorCode

錯誤碼。
枚舉值值說明
AoqECOK0成功
AoqECParamInvalid1參數無效
AoqECStateInvalid2狀態無效
AoqECUnSupport3當前平台/模式未實現
AoqECAudio100音訊通用錯誤
AoqECAudioExternalBufferFull110外部音訊緩衝區已滿
AoqECAudioDevice120音訊設備通用錯誤
AoqECAudioDeviceRecordingAuthFailed121麥克風授權失敗
AoqECAudioDeviceRecordingOccupied122麥克風被佔用
AoqECAudioDeviceRecordingBackgroundStart123後台啓動擷取
AoqECAudioDeviceRecordingStartFail124擷取啓動失敗
AoqECAudioDevicePlayoutOccupied125播放設備被佔用
AoqECAudioDevicePlayoutBackgroundStart126後台啓動播放
AoqECAudioDevicePlayoutStartFail127播放啓動失敗
AoqECAudioDeviceEarpieceRequiresVoipMode128聽筒需要 VoIP 模式
AoqECVideo200視訊通用錯誤
AoqECVideoExternalBufferFull210外部視訊緩衝區已滿
AoqECVideoExternalCaptureNotEnabled211外部視訊擷取未啓用
AoqECVideoExternalEncoderNotEnabled212外部視訊編碼器未啓用
AoqECVideoDevice220視訊設備通用錯誤
AoqECVideoDeviceCameraOpenFail221攝像頭打開失敗
AoqECVideoDeviceCameraAuthFailed222攝像頭授權失敗
AoqECVideoDeviceCameraOccupied223攝像頭被佔用
AoqECVideoDeviceCameraRunningError224攝像頭運行錯誤
AoqECVideoCodec230視訊編解碼通用錯誤
AoqECVideoCodecEncoderInitFail231視訊編碼器初始化失敗
AoqECVideoRender240視訊渲染通用錯誤
AoqECVideoRenderCreateFail241渲染器建立失敗
AoqECVideoRenderDrawError242渲染繪制錯誤

AoqWarningCode

警告碼。
枚舉值值說明
AoqWCOK0正常
AoqWCAudio100音訊通用警告
AoqWCAudioHowling101檢測到嘯叫
AoqWCAudioDevice120音訊設備通用警告
AoqWCAudioDeviceMicEnumerateError121麥克風枚舉錯誤
AoqWCAudioDeviceMicStartTimeout122麥克風啓動超時
AoqWCAudioDeviceRecordingError123擷取異常
AoqWCAudioDeviceSpeakerEnumerateError124揚聲器枚舉錯誤
AoqWCAudioDeviceSpeakerStartTimeout125揚聲器啓動超時
AoqWCAudioDevicePlayoutError126播放異常
AoqWCAudioDeviceSilentMode127設備處於靜音模式
AoqWCVideo200視訊通用警告
AoqWCVideoCameraEnumerateError201攝像頭枚舉錯誤
AoqWCVideoEncoderSwitched202視訊編碼器已切換
AoqWCVideoRenderDowngrade203渲染降級

AoqAudioDeviceStateCode

音訊設備狀態碼。
枚舉值值說明
AoqAudioDeviceNone0無狀態
AoqAudioDeviceRecordStarting1擷取啓動中
AoqAudioDeviceRecordStarted2擷取已啓動
AoqAudioDeviceRecordStopping3擷取停止中
AoqAudioDeviceRecordStopped4擷取已停止
AoqAudioDeviceRecordFail5擷取失敗
AoqAudioDevicePlayStarting6播放啓動中
AoqAudioDevicePlayStarted7播放已啓動
AoqAudioDevicePlayStopping8播放停止中
AoqAudioDevicePlayStopped9播放已停止
AoqAudioDevicePlayFail10播放失敗

AoqAudioDeviceRouteType

音訊設備路由類型。
枚舉值值說明
AoqAudioDeviceRouteDefault0預設路由
AoqAudioDeviceRouteHeadset1耳機
AoqAudioDeviceRouteSpeakerPhone4內置揚聲器
AoqAudioDeviceRouteUsb5USB 設備
AoqAudioDeviceRouteBluetooth6藍牙設備

AoqAudioFileStateCode

音訊文件播放狀態碼。
枚舉值值說明
AoqAudioFileNone0無狀態
AoqAudioFileStarted1播放已開始
AoqAudioFileStopped2播放已停止
AoqAudioFilePaused3播放已暫停
AoqAudioFileResumed4播放已恢復
AoqAudioFileEnded5播放已結束
AoqAudioFileBuffering6緩衝中
AoqAudioFileBufferingEnd7緩衝結束
AoqAudioFileFailed8播放失敗

AoqCameraDirection

枚舉值值說明
AoqCameraDirectionFront0優先前置
AoqCameraDirectionBack1優先後置

AoqVideoDeviceStateCode

視訊設備狀態碼。
枚舉值值說明
AoqVideoDeviceNone0無狀態
AoqVideoDeviceCaptureStarting1擷取啓動中
AoqVideoDeviceCaptureStarted2擷取已啓動
AoqVideoDeviceCaptureStopping3擷取停止中
AoqVideoDeviceCaptureStopped4擷取已停止
AoqVideoDeviceCaptureFail5擷取失敗

AoqMirrorMode

預留鏡像模式枚舉;當前 Web 沒有使用該枚舉的設定項或接口。
枚舉值值說明
AoqMirrorModeDisabled0關閉鏡像
AoqMirrorModeEnabled1開啓鏡像

AoqOrientationMode

預留方向模式枚舉;當前 Web 沒有使用該枚舉的設定項或接口。
枚舉值值說明
AoqOrientationModeAuto0自動
AoqOrientationModePortrait1竪屏
AoqOrientationModeLandscape2橫屏

AoqRenderMode

視訊畫面適配方式。
枚舉值值說明
AoqRenderModeAuto0預設等比完整顯示
AoqRenderModeStretch1拉伸鋪滿容器
AoqRenderModeFill2等比完整顯示,允許留黑邊
AoqRenderModeCrop3等比鋪滿,裁剪超出部分

其他公開聲明

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 實現產生。具體接口是否可用,以本文方法和其調用條件為準。