Skip to main content
SDK簡介

AOQ Client SDK OHOS (HarmonyOS) API 參考

AOQ Client SDK HarmonyOS (OHOS) 端 API 參考，平台語言為 ArkTS (.ets)，通過 NAPI 橋接 C++ 引擎。

HarmonyOS SDK

目錄

引擎生命週期

介面

簡介

createEngine

建立引擎執行個體（單例模式）

destroy

銷毀引擎執行個體

getVersion

擷取 SDK 版本號碼

connect

串連 Relay 伺服器

disconnect

斷開伺服器串連

音訊裝置管理

介面

簡介

startAudioCapture

開啟音頻採集裝置（麥克風）

stopAudioCapture

關閉音頻採集裝置

muteAudioCapture

靜音或取消靜音音頻採集

startAudioPlayer

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

stopAudioPlayer

停止音頻渲染

pauseAudioPlayer

暫停音頻渲染，支援淡出

resumeAudioPlayer

恢複音頻渲染，支援淡入

interruptAudioPlayer

打斷本輪語音通話

enableSpeakerphone

切換音訊輸出到擴音器或耳機

isSpeakerphoneEnabled

查詢當前是否使用擴音器輸出

音頻編碼配置

介面

簡介

setAudioEncoderConfig

設定音頻編碼參數

setAudioDecoderConfig

設定音頻解碼參數

視頻裝置管理

介面

簡介

startVideoCapture

開啟視頻採集裝置（網路攝影機）

stopVideoCapture

關閉視頻採集裝置

switchCamera

切換前後置網路攝影機

setLocalView

設定或移除本地視頻渲染視窗

setRemoteView

設定或移除遠端視頻渲染視窗

視頻編碼與外部輸入

介面

簡介

setVideoEncoderConfig

設定視頻編碼參數

pushExternalVideoCapturedFrame

推送外部採集視訊框架

pushExternalVideoEncodedFrame

推送外部已編碼視訊框架

媒體流發送控制

介面

簡介

enableSendMediaStream

控制本地媒體流的發送開關

音頻檔案播放

介面

簡介

startAudioFile

開始推流播放本地音頻檔案

stopAudioFile

停止音頻檔案播放

pauseAudioFile

暫停音頻檔案播放

resumeAudioFile

恢複音頻檔案播放

getAudioFileDuration

擷取音頻檔案總時間長度

getAudioFileCurrentPosition

擷取音頻檔案當前播放位置

setAudioFilePositionMillis

設定音頻檔案播放位置（seek）

setAudioFileVolume

設定音頻檔案音量

getAudioFileVolume

擷取音頻檔案當前音量

外部音頻流

介面

簡介

addAudioExternalStream

新增一條外部音頻流

removeAudioExternalStream

移除外部音頻流

pushAudioExternalStreamData

輸入外部音頻 PCM 資料

setAudioExternalStreamVolume

設定外部音頻流音量

getAudioExternalStreamVolume

擷取外部音頻流音量

clearAudioExternalStreamBuffer

清空外部音頻流緩衝

即時訊息

介面

簡介

sendDataMsg

發送即時資料訊息

音訊框架回調

介面

簡介

setAudioFrameObserver

設定音訊框架資料回調監聽

enableAudioFrameObserver

開啟或關閉指定位置的音訊框架回調

視訊框架回調

介面

簡介

setVideoFrameObserver

設定視訊框架資料回調監聽

enableVideoFrameObserver

開啟或關閉指定位置的視訊框架回調

AoqEngineEventListener 回調

回調

簡介

onError

引擎錯誤回調

onWarning

引擎警告回調

onConnectionStatusChange

串連狀態變化回調

onStats

統計資料回調

onAudioDeviceStateChanged

音訊裝置操作狀態變化回調

onAudioDeviceRouteChanged

音訊輸出路由變化回調

onAudioDeviceInterrupted

音訊裝置中斷回調

onVideoDeviceStateChanged

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

onAudioFileState

音頻檔案播放狀態回調

onDataMsg

收到即時資料訊息回調

IAudioFrameObserver

音訊框架資料觀察者介面

IVideoFrameObserver

視訊框架資料觀察者介面

介面詳情

引擎生命週期

createEngine

建立引擎執行個體。SDK 內部以全域單例方式持有引擎，重複調用會返回已建立的執行個體。native 建立失敗時返回 null。 
static createEngine(config: AoqCreateConfig, listener: AoqEngineEventListener, context: common.Context): AoqClientEngine | null

參數

類型

說明

config

AoqCreateConfig

引擎建立配置

listener

AoqEngineEventListener

引擎事件回調監聽（interface，所有回調均為可選）

context

common.Context

UIAbility/Page 的 Context，用於 aki+ACPM 初始化

傳回值：AoqClientEngine | null（native 建立失敗時返回 null） 注意事項：與 Android 不同，OHOS 端建立失敗會返回 null，調用方需判空處理。context 必須是有效 UIAbility 或 Page Context。

destroy

銷毀引擎單例，釋放所有資源。調用後需重新 createEngine 才能繼續使用。 
static destroy(): number
傳回值：0 表示成功；非 0 表示失敗

getVersion

擷取 SDK 目前的版本號。 
static getVersion(): string
傳回值：版本號碼字串，如 "1.0.0"

connect

串連 Relay 伺服器。串連參數由業務方 AppServer 通過 /api/v1/allocate 分配後下發給用戶端。 
connect(config: AoqConnectConfig): number

參數

類型

說明

config

AoqConnectConfig

串連配置，包含 Token、SID、Relay 存取點列表等

傳回值：0 表示調用已下發（非同步執行）；非 0 表示參數校正失敗 注意事項：串連狀態變化通過 onConnectionStatusChange 非同步通知。建議在 connect 前調用 enableSendMediaStream(false)。

disconnect

斷開與伺服器的串連，釋放串連相關資源。音視頻採集/播放裝置不會自動停止。 
disconnect(): number
傳回值：0 表示調用已下發（非同步執行）；非 0 表示失敗

音訊裝置管理

startAudioCapture

開啟音頻採集裝置（麥克風）。 
startAudioCapture(config: AoqAudioCaptureConfig): number

參數

類型

說明

config

AoqAudioCaptureConfig

採集配置

傳回值：0 表示成功；非 0 表示失敗

stopAudioCapture

關閉音頻採集裝置。 
stopAudioCapture(): number

muteAudioCapture

靜音或取消靜音音頻採集。 
muteAudioCapture(mute: boolean): number

參數

類型

說明

mute

boolean

true 為靜音；false 為取消靜音

startAudioPlayer

開始音頻渲染（擴音器/耳機播放遠端音頻）。 
startAudioPlayer(config: AoqAudioPlaybackConfig): number

參數

類型

說明

config

AoqAudioPlaybackConfig

播放配置

stopAudioPlayer

停止音頻渲染。 
stopAudioPlayer(): number

pauseAudioPlayer

暫停音頻渲染，可指定淡出時間長度實現平滑過渡。 
pauseAudioPlayer(fadeMs: number): number

參數

類型

說明

fadeMs

number

淡出時間長度（毫秒）；0 表示立即停止

resumeAudioPlayer

恢複音頻渲染，可指定淡入時間長度實現平滑過渡。 
resumeAudioPlayer(fadeMs: number): number

參數

類型

說明

fadeMs

number

淡入時間長度（毫秒）；0 表示立即恢複

interruptAudioPlayer

打斷本輪語音通話。 
interruptAudioPlayer(trackType: AoqTrackType, fadeMs: number): number

參數

類型

說明

trackType

AoqTrackType

目標軌道類型，通常傳 AoqTrackTypeAudio

fadeMs

number

淡出時間長度（毫秒）

enableSpeakerphone

切換音訊輸出路由到擴音器或耳機。 
enableSpeakerphone(enable: boolean): number

參數

類型

說明

enable

boolean

true 使用擴音器；false 使用耳機

isSpeakerphoneEnabled

查詢當前是否使用擴音器輸出。 
isSpeakerphoneEnabled(): boolean
傳回值：true 表示當前為擴音器模式；false 表示耳機模式

音頻編碼配置

setAudioEncoderConfig

設定音頻編碼參數。 
setAudioEncoderConfig(config: AoqAudioCodecConfig): number

setAudioDecoderConfig

設定音頻解碼參數。 
setAudioDecoderConfig(config: AoqAudioCodecConfig): number

視頻裝置管理

startVideoCapture

開啟視頻採集裝置（網路攝影機）。當 config.isExternal = true 時不開啟網路攝影機，由調用方通過 pushExternalVideoCapturedFrame 喂幀。 
startVideoCapture(config: AoqVideoCaptureConfig): number

stopVideoCapture

關閉視頻採集裝置。 
stopVideoCapture(): number

switchCamera

切換前後置網路攝影機。 
switchCamera(direction: AoqCameraDirection): number

參數

類型

說明

direction

AoqCameraDirection

AoqCameraDirectionFront 或 AoqCameraDirectionBack

setLocalView

設定或移除本地視頻渲染視窗。 
setLocalView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number

參數

類型

說明

trackType

AoqTrackType

AoqTrackTypeVideo

canvas

AoqVideoCanvas | null

渲染畫布配置；傳 null 或 canvas.view 為 null 表示移除渲染視窗

注意：OHOS 上必須在 XComponent.onLoad 回調之後調用，canvas.view 應傳入 AoqXComponentController 執行個體。

setRemoteView

設定或移除遠端視頻渲染視窗。 
setRemoteView(trackType: AoqTrackType, canvas: AoqVideoCanvas | null): number

參數

類型

說明

trackType

AoqTrackType

AoqTrackTypeVideo

canvas

AoqVideoCanvas | null

渲染畫布配置；傳 null 或 canvas.view 為 null 表示移除渲染視窗

視頻編碼與外部輸入

setVideoEncoderConfig

設定視頻編碼參數，按 config.trackType 路由到對應軌道。 
setVideoEncoderConfig(config: AoqVideoCodecConfig): number

pushExternalVideoCapturedFrame

推送外部採集視訊框架。 
pushExternalVideoCapturedFrame(trackType: AoqTrackType, frame: AoqVideoFrame): number

參數

類型

說明

trackType

AoqTrackType

AoqTrackTypeVideo

frame

AoqVideoFrame

視訊框架資料

路由規則：僅在 startVideoCapture(isExternal=true) 後消費。支援格式：NV12 / NV21 / BGRA / RGBA / I420。 若緩衝區滿，會返回錯誤碼 AoqECVideoExternalBufferFull(210)，調用方需 sleep 後重試，禁止 busy loop。

pushExternalVideoEncodedFrame

推送外部已編碼視訊框架。SDK 不做二次編碼，直接打包發送。 
pushExternalVideoEncodedFrame(trackType: AoqTrackType, frame: AoqVideoEncodedFrame): number

參數

類型

說明

trackType

AoqTrackType

AoqTrackTypeVideo

frame

AoqVideoEncodedFrame

已編碼幀資料

路由規則：僅在 setVideoEncoderConfig(isExternal=true) 配置後才消費。

媒體流發送控制

enableSendMediaStream

控制本地媒體流的發送，按 trackType 路由到對應軌道。 
enableSendMediaStream(trackType: AoqTrackType, enable: boolean): number

參數

類型

說明

trackType

AoqTrackType

AoqTrackTypeAudio / AoqTrackTypeVideo

enable

boolean

true 啟用發送；false 停用發送

使用建議：初始化後先調用 enableSendMediaStream(trackType, false)，待 connect 成功且會話握手完成（收到 onConnectionStatusChange(AoqConnectionStatusConnected)）後再開啟發送。

音頻檔案播放

startAudioFile

開始推流播放本地音頻檔案。音頻檔案播放會混音到推流和本地播放中。 
startAudioFile(fileId: string, config: AoqAudioFileMixConfig): number

參數

類型

說明

fileId

string

音頻檔案唯一標識，由調用方指定

config

AoqAudioFileMixConfig

播放配置

stopAudioFile / pauseAudioFile / resumeAudioFile 

stopAudioFile(fileId: string): number
pauseAudioFile(fileId: string): number
resumeAudioFile(fileId: string): number

getAudioFileDuration / getAudioFileCurrentPosition 

getAudioFileDuration(fileId: string): number      // 返回總時間長度(ms)；負值表示失敗
getAudioFileCurrentPosition(fileId: string): number // 返回當前位置(ms)；負值表示失敗

setAudioFilePositionMillis 

setAudioFilePositionMillis(fileId: string, positionMillis: number): number

setAudioFileVolume / getAudioFileVolume 

setAudioFileVolume(fileId: string, type: AoqAudioStreamDirection, volume: number): number
getAudioFileVolume(fileId: string, type: AoqAudioStreamDirection): number // 返回 [0,100]；負值表示失敗

外部音頻流

addAudioExternalStream

新增一條外部音頻流。 
addAudioExternalStream(streamId: string, config: AoqAudioExternalStreamConfig): number

pushAudioExternalStreamData

輸入外部音頻 PCM 資料。若緩衝區滿返回 AoqECAudioExternalBufferFull(110)。 
pushAudioExternalStreamData(streamId: string, data: AoqAudioFrameData): number

setAudioExternalStreamVolume / getAudioExternalStreamVolume 

setAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection, vol: number): number
getAudioExternalStreamVolume(streamId: string, type: AoqAudioStreamDirection): number

clearAudioExternalStreamBuffer

清空外部音頻流緩衝。無傳回值，非同步執行。 
clearAudioExternalStreamBuffer(streamId: string, fadeoutMs: number): void

參數

類型

說明

fadeoutMs

number

-1 預設淡出；0 立即清空；>0 保留指定毫秒後淡出

removeAudioExternalStream 

removeAudioExternalStream(streamId: string): number

即時訊息

sendDataMsg

發送即時資料訊息，通過 MoQT Data 通道傳輸。 
sendDataMsg(msg: AoqDataMsg): number

音訊框架回調

setAudioFrameObserver

設定音訊框架資料回調監聽。先註冊監聽，再 enableAudioFrameObserver 開啟回調。 
setAudioFrameObserver(observer: IAudioFrameObserver | null): number

enableAudioFrameObserver 

enableAudioFrameObserver(enabled: boolean, audioSource: AoqAudioSource, config: AoqAudioObserverConfig): number

視訊框架回調

setVideoFrameObserver 

setVideoFrameObserver(observer: IVideoFrameObserver | null): number

enableVideoFrameObserver 

enableVideoFrameObserver(enabled: boolean, videoSource: AoqVideoSource, config: AoqVideoObserverConfig): number

AoqEngineEventListener 回調

所有回調均為可選屬性（?）。 
export interface AoqEngineEventListener {
  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: number) => void;
  onAudioDeviceInterrupted?: (interrupt: boolean) => void;
  onVideoDeviceStateChanged?: (state: AoqVideoDeviceState) => void;
  onAudioFileState?: (state: AoqAudioFileState) => void;
  onDataMsg?: (msg: AoqDataMsg) => void;
}

IAudioFrameObserver 

export interface IAudioFrameObserver {
  onCapturedAudioFrame?: (frame: AoqAudioFrameData) => void;
  onProcessCapturedAudioFrame?: (frame: AoqAudioFrameData) => void;
  onPublishAudioFrame?: (trackType: AoqTrackType, frame: AoqAudioFrameData) => void;
  onPlaybackAudioFrame?: (frame: AoqAudioFrameData) => void;
}
frame.dataPtr 是 native 記憶體的 Uint8Array 拷貝，當前 ReadOnly（修改不寫回 SDK）。

IVideoFrameObserver 

export interface IVideoFrameObserver {
  onCapturedVideoFrame?: (frame: AoqVideoFrame) => boolean;
  onPreEncodeVideoFrame?: (trackType: AoqTrackType, frame: AoqVideoFrame) => boolean;
  onRemoteVideoFrame?: (trackType: AoqTrackType, frame: AoqVideoFrame) => boolean;
}
frame 各 buffer 是 native 記憶體的 Uint8Array 拷貝，回調期間有效。當前等效 ReadOnly，P2 實現真寫回。

資料類型與枚舉

通用類型

AoqCreateConfig

欄位

類型

預設值

說明

workDir

string

""

SDK 工作目錄

enableDumpAudio

boolean

false

是否開啟音頻未經處理資料 dump（調試用）

extras

string

""

擴充參數字串

與 Android 不同：OHOS 無 isBTScoMode 欄位。

AoqConnectConfig

欄位

類型

預設值

說明

token

string

""

串連鑒權 Token

sid

string

""

會話 ID

certFingerprint

string

""

伺服器憑證指紋

relayEndpoints

AoqRelayEndpoint[]

[]

Relay 存取點列表

workspaceIdHash

string

""

工作空間 ID Hash

publishTracks

AoqTrackParam[]

[]

本端計劃發布的軌道列表

subscribeTracks

AoqTrackParam[]

[]

本端計劃訂閱的軌道列表

AoqRelayEndpoint

欄位

類型

說明

endpoint

string

Relay 伺服器網域名稱或 IP

port

number

Relay 伺服器連接埠

AoqTrackParam

欄位

類型

說明

trackType

AoqTrackType

軌道類型

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

播放過程錯誤

AoqWCVideo

200

視頻通用警告

AoqWCVideoCameraEnumerateError

201

網路攝影機枚舉錯誤

AoqWCVideoEncoderSwitched

202

視頻編碼器已切換

AoqWCVideoRenderDowngrade

203

視頻渲染降級

AoqTrackType

枚舉值

值

說明

AoqTrackTypeAudio

0

音頻軌道

AoqTrackTypeVideo

1

視頻軌道

AoqTrackTypeData

2

資料訊息軌道

與 Android 不同：OHOS 當前不包含 AoqTrackTypeScreen(3)，螢幕採集功能暫未對外開放。

AoqConnectionStatus

枚舉值

值

說明

AoqConnectionStatusDisconnected

0

未串連

AoqConnectionStatusConnecting

1

串連中

AoqConnectionStatusConnected

2

已串連

AoqConnectionStatusFailed

3

串連失敗

AoqEncoderType / AoqMirrorMode / AoqOrientationMode

同原文檔，無變化。

音訊類型

AoqAudioCaptureConfig

欄位

類型

預設值

說明

isExternal

boolean

false

true 使用外部音頻輸入

isVoipMode

boolean

false

true 啟用 VoIP 模式（硬體 AEC）

channel

number

1

聲道數，支援 1/2

AoqAudioPlaybackConfig

欄位

類型

預設值

說明

isVoipMode

boolean

false

true 啟用 VoIP 模式（硬體 AEC），採集/播放參數先到為準

isDefaultSpeaker

boolean

true

true 預設擴音器；false 預設耳機

isExternal

boolean

false

true 使用外部音訊輸出

channel

number

1

聲道數，支援 1/2

AoqAudioCodecConfig

欄位

類型

預設值

說明

trackType

AoqTrackType

AoqTrackTypeAudio

目標軌道

codecType

AoqEncoderType

AoqEncoderTypeAudioPCM

編碼格式

sampleRate

number

48000

採樣率(Hz)

channel

number

1

聲道數

bitrate

number

32000

碼率(bps)

視頻類型

AoqVideoCaptureConfig

欄位

類型

預設值

說明

width

number

1280

採集寬度；isExternal=true 時無效

height

number

720

採集高度

fps

number

15

採集幀率

isExternal

boolean

false

true 不開啟網路攝影機，由 pushExternalVideoCapturedFrame 喂幀

cameraDirection

AoqCameraDirection

Front

網路攝影機方向

AoqVideoCodecConfig

欄位

類型

預設值

說明

trackType

AoqTrackType

AoqTrackTypeVideo

目標軌道

codecType

AoqEncoderType

AoqEncoderTypeVideoH264

編碼格式

width

number

720

編碼寬度

height

number

1280

編碼高度

fps

number

15

幀率

bitrate

number

500

碼率(kbps)

minBitrate

number

128

最小碼率(kbps)

keyframeInterval

number

2

主要畫面格間隔(秒)

mirrorMode

AoqMirrorMode

Disabled

鏡像模式

orientationMode

AoqOrientationMode

Auto

視頻方向

isExternal

boolean

false

true 時 SDK 不做二次編碼

與 Android 不同：OHOS 碼率單位為 kbps（預設 500/128），Android 為 bps（預設 500000/128000）。

AoqVideoCanvas

欄位

類型

預設值

說明

view

Object | null

null

AoqXComponentController 執行個體；傳 null 表示移除渲染綁定

renderMode

AoqRenderMode

AoqRenderModeAuto

顯示模式

AoqVideoPixelFormat

枚舉值

值

說明

AoqVideoPixelFormatUnknown

0

未知

AoqVideoPixelFormatI420

1

I420

AoqVideoPixelFormatNV12

2

NV12

AoqVideoPixelFormatNV21

3

NV21

AoqVideoPixelFormatBGRA

4

BGRA

AoqVideoPixelFormatRGBA

5

RGBA

OHOS 不支援 TextureOES/Texture2D。

AoqVideoFrame

欄位

類型

說明

format

AoqVideoPixelFormat

像素格式

width

number

寬度(像素)

height

number

高度(像素)

dataPtr

ArrayBuffer | Uint8Array | null

打包格式資料

dataSize

number

打包資料位元組數

dataY / dataU / dataV

ArrayBuffer | Uint8Array | null

I420 平面

strideY / strideU / strideV

number

平面 stride

timeStamp

number

時間戳記(ms)；0 時 SDK 用本地時鐘補

AoqVideoEncodedFrame

欄位

類型

說明

codec

AoqVideoCodecType

編碼格式 (AoqVideoCodecTypeJPEG=0)

data

ArrayBuffer | Uint8Array

編碼後資料

width

number

寬度

height

number

高度

timeStamp

number

時間戳記(ms)

音頻檔案與外部流類型

AoqAudioFileMixConfig

欄位

類型

預設值

說明

fileName

string

""

檔案名稱（含路徑）

cycles

number

-1

迴圈次數，-1 無限迴圈

startPosMs

number

0

起始播放位置(ms)

publishVolume

number

100

推流音量 [0,100]

playoutVolume

number

100

本地播放音量 [0,100]

AoqAudioExternalStreamConfig

欄位

類型

預設值

說明

trackType

AoqTrackType

AoqTrackTypeAudio

軌道類型

codecType

AoqEncoderType

AoqEncoderTypeAudioPCM

音頻格式

channels

number

1

聲道數

sampleRate

number

48000

採樣率(Hz)

playoutVolume

number

100

播放音量 [0,100]

publishVolume

number

100

推流音量 [0,100]

maxBufferDuration

number

1000

最大緩衝(ms)

enable3A

boolean

false

輸入 PCM 做 3A 處理

AoqAudioFrameData

欄位

類型

說明

dataPtr

ArrayBuffer | Uint8Array | null

音頻 PCM 裸資料

dataSize

number

PCM 位元組數

numOfSamples

number

採樣點數(單聲道)

bytesPerSample

number

每採樣點位元組數

numOfChannels

number

聲道數

samplesPerSec

number

每秒採樣點數

pushSequence

number

PCM 輸入輪次

timeStamp

number

時間戳記

autoGenMute

boolean

true 表示 SDK 產生的靜音資料

Observer 配置類型

AoqAudioObserverConfig

欄位

類型

預設值

說明

sampleRate

number

48000

回調採樣率

channels

number

1

回調聲道數

mode

AoqAudioObserverMode

ReadOnly

讀寫入模式

AoqVideoObserverConfig

欄位

類型

預設值

說明

format

AoqVideoPixelFormat

I420

回調像素格式

alignment

AoqVideoObserverAlignment

Default

寬度對齊

mode

AoqVideoObserverMode

ReadOnly

讀寫入模式

mirrorApplied

boolean

false

是否應用鏡像

統計資料類型

AoqStats

欄位

類型

說明

audioPublishStats

AoqAudioPublishStats[]

音頻推流統計

videoPublishStats

AoqVideoPublishStats[]

視頻推流統計

dataMsgPublishStats

AoqDataMsgPublishStats[]

資料訊息推流統計

audioSubscribeStats

AoqAudioSubscribeStats[]

音頻拉流統計

videoSubscribeStats

AoqVideoSubscribeStats[]

視頻拉流統計

dataMsgSubscribeStats

AoqDataMsgSubscribeStats[]

資料訊息拉流統計

networkStats

AoqNetworkStats | null

網路統計

統計子類型

AoqAudioPublishStats：trackType / bitrate / bytes / encodeVolume AoqVideoPublishStats：trackType / bitrate / bytes / encodeFps AoqAudioSubscribeStats：trackType / bitrate / bytes / playVolume AoqVideoSubscribeStats：trackType / bitrate / bytes / decodeFps / renderFps AoqDataMsgPublishStats / AoqDataMsgSubscribeStats：trackType / bitrate / bytes AoqNetworkStats：sendBitrate / sendBytes / recvBitrate / recvBytes / loss / rtt

與 Android 版本的主要差異

類別

Android

OHOS

實現語言

Java

ArkTS(.ets)，NAPI 橋接 C++

傳回值類型

int / long / boolean

number / boolean

createEngine 傳回值

@NonNull AoqClientEngine

AoqClientEngine | null

createEngine context

android.content.Context

common.Context (UIAbility/Page)

listener 形式

abstract class，預設空實現

TS interface，所有回調 optional (?)

frame observer 形式

interface + default 方法

TS interface，所有回調 optional (?)

AoqCreateConfig

包含 isBTScoMode

不含 isBTScoMode

AoqAudioPlaybackConfig

無 isVoipMode

含 isVoipMode，採集/播放參數先到為準

onAudioDeviceFocusChanged

提供

不提供（無音頻焦時間點事件抽象）

視頻渲染 view

View(SurfaceView/TextureView)

AoqXComponentController(繼承 XComponentController)

Pixel Format 枚舉

包含 TextureOES(7) / Texture2D(8)

不包含紋理格式

視訊框架附加欄位

textureId / transformMatrix / eglContext

無這些欄位

幀資料容器

byte[] / ByteBuffer

ArrayBuffer / Uint8Array

視頻編碼碼率單位

bps（預設 500000/128000）

kbps（預設 500/128）

AoqTrackType

含 AoqTrackTypeScreen(3)

不含 AoqTrackTypeScreen，螢幕採集暫未開放

螢幕採集 API

startScreenCapture / stopScreenCapture

暫未提供

Observer ReadWrite

I420 支援寫回

當前等效 ReadOnly，P2 實現真回寫

Observer 重註冊安全

依賴 SDK 內部

UAF 防護墓地模式

裝置監測能力

Java 側隱含

AoqDeviceMonitor(內部模組)自動啟動

枚舉命名空間

AoqErrorCodeXxx

AoqECXxx (如 AoqECOK、AoqECParamInvalid)

主要設計要點

  1. AoqXComponentController：繼承自 XComponentController，重寫 onSurfaceCreated/Changed/Destroyed。業務需建立後傳入 XComponent，並在 setLocalView/setRemoteView 時作為 canvas.view。
  2. NAPI 架構：facade (AoqClientEngine.ets) -> 實現層 (AoqClientEngineImpl.ets) -> NAPI (libaoq_client_sdk.so)。配置在實現層被拍平為多個參數。
  3. 裝置監測(內部)：AoqDeviceMonitor 在 createEngine 後自動啟動，下沉網路狀態與 App 前後台狀態到 C++ 引擎。
  4. Observer UAF 防護：重註冊時採用 "cpp 切舊引用 -> 舊 obs push 入墓地 -> 佔位指新 obs" 三步順序。
  5. 幀負載語義：音視訊框架回調中的 Uint8Array 是 native 拷貝，P1 不支援寫回，P2 計劃零拷貝。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多
AOQ Client SDK OHOS (HarmonyOS) API 參考 - Alibaba Cloud Model Studio