Skip to main content
SDK簡介

AOQ Client SDK Android API 參考

AOQ Client SDK Android 版提供完整的即時音視頻通訊能力，包括引擎生命週期管理、音頻/視頻採集與播放、編解碼配置、外部音頻流注入、音頻檔案混音、即時訊息收發、音視訊框架資料回調等功能。本文檔為 Android 平台 Java API 的完整參考。

介面目錄

引擎生命週期

介面

簡介

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

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

sendDataMsg

發送即時資料訊息

音頻檔案播放

介面

簡介

startAudioFile

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

stopAudioFile

停止音頻檔案播放

pauseAudioFile

暫停音頻檔案播放

resumeAudioFile

恢複音頻檔案播放

getAudioFileDuration

擷取音頻檔案總時間長度

getAudioFileCurrentPosition

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

setAudioFilePositionMillis

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

setAudioFileVolume

設定音頻檔案音量

getAudioFileVolume

擷取音頻檔案當前音量

外部音頻流

介面

簡介

addAudioExternalStream

新增一條外部音頻流

removeAudioExternalStream

移除外部音頻流

pushAudioExternalStreamData

輸入外部音頻 PCM 資料

setAudioExternalStreamVolume

設定外部音頻流音量

getAudioExternalStreamVolume

擷取外部音頻流音量

clearAudioExternalStreamBuffer

清空外部音頻流緩衝

音視訊框架回調

介面

簡介

setAudioFrameObserver

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

enableAudioFrameObserver

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

setVideoFrameObserver

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

enableVideoFrameObserver

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

AoqClientListener 回調

回調

簡介

onError

引擎錯誤回調

onWarning

引擎警告回調

onConnectionStatusChange

串連狀態變化回調

onStats

引擎統計資訊回調

onAudioDeviceStateChanged

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

onAudioDeviceRouteChanged

音訊輸出路由變化回調

onAudioDeviceInterrupted

音訊裝置中斷回調

onVideoDeviceStateChanged

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

onAudioDeviceFocusChanged

音頻焦點變化回調

onAudioFileState

音頻檔案播放狀態回調

onDataMsg

收到即時資料訊息回調

介面詳情

引擎生命週期

createEngine 建立引擎執行個體。SDK 內部以全域單例方式持有引擎，重複調用會返回已建立的執行個體。 
@NonNull
public static AoqClientEngine createEngine(
    @NonNull Context context,
    @NonNull AoqCreateConfig config,
    @NonNull AoqClientListener listener)

參數

類型

說明

context

Context

Android 應用上下文

config

AoqCreateConfig

引擎建立配置

listener

AoqClientListener

引擎事件回調監聽

傳回值：AoqClientEngine 引擎執行個體，不會返回 null。 destroy 銷毀引擎執行個體，釋放所有資源。 
public static int destroy()
傳回值：0 表示成功；非 0 表示失敗。 getVersion 
@NonNull
public static String getVersion()
傳回值：版本號碼字串，如 "1.0.0"。 connect 串連 Relay 伺服器。串連參數由業務方 AppServer 通過 /api/v1/allocate 分配後下發給用戶端。 
public abstract int connect(@NonNull AoqConnectConfig config)
傳回值：0 表示調用已下發（非同步執行）；非 0 表示參數校正失敗。 disconnect 
public abstract int disconnect()
傳回值：0 表示調用已下發（非同步執行）；非 0 表示失敗。

音訊裝置管理 

public abstract int startAudioCapture(@NonNull AoqAudioCaptureConfig config)
public abstract int stopAudioCapture()
public abstract int muteAudioCapture(boolean mute)
public abstract int startAudioPlayer(@NonNull AoqAudioPlaybackConfig config)
public abstract int stopAudioPlayer()
public abstract int pauseAudioPlayer(int fadeMs)
public abstract int resumeAudioPlayer(int fadeMs)
public abstract int interruptAudioPlayer(@NonNull AoqTrackType trackType, int fadeMs)
public abstract int enableSpeakerphone(boolean enable)
public abstract boolean isSpeakerphoneEnabled()
fadeMs：淡出/淡入時間長度（毫秒）；0 表示立即執行。

音頻編碼配置 

public abstract int setAudioEncoderConfig(@NonNull AoqAudioCodecConfig config)
public abstract int setAudioDecoderConfig(@NonNull AoqAudioCodecConfig config)

視頻裝置管理 

public abstract int startVideoCapture(@NonNull AoqVideoCaptureConfig config)
public abstract int stopVideoCapture()
public abstract int switchCamera(@NonNull AoqCameraDirection direction)
public abstract int setLocalView(@NonNull AoqTrackType trackType, @Nullable AoqVideoCanvas canvas)
public abstract int setRemoteView(@NonNull AoqTrackType trackType, @Nullable AoqVideoCanvas canvas)
setLocalView/setRemoteView 的 trackType 參數傳 AoqTrackTypeVideo。

視頻編碼與外部輸入 

public abstract int setVideoEncoderConfig(@NonNull AoqVideoCodecConfig config)
public abstract int pushExternalVideoCapturedFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrame frame)
public abstract int pushExternalVideoEncodedFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoEncodedFrame frame)
pushExternalVideoCapturedFrame 僅在 startVideoCapture(isExternal=true) 後消費。若緩衝區滿返回 AoqErrorCodeVideoExternalBufferFull(210)。

媒體流發送控制 

public abstract int enableSendMediaStream(@NonNull AoqTrackType trackType, boolean enable)
建議初始化後先 enableSendMediaStream(false)，待 onConnectionStatusChange(Connected) 後再開啟。

音頻檔案播放 

public abstract int startAudioFile(@NonNull String fileId, @NonNull AoqAudioFileMixConfig config)
public abstract int stopAudioFile(@NonNull String fileId)
public abstract int pauseAudioFile(@NonNull String fileId)
public abstract int resumeAudioFile(@NonNull String fileId)
public abstract long getAudioFileDuration(@NonNull String fileId)
public abstract long getAudioFileCurrentPosition(@NonNull String fileId)
public abstract int setAudioFilePositionMillis(@NonNull String fileId, long positionMillis)
public abstract int setAudioFileVolume(@NonNull String fileId, @NonNull AoqAudioStreamDirection type, int volume)
public abstract int getAudioFileVolume(@NonNull String fileId, @NonNull AoqAudioStreamDirection type)

外部音頻流 

public abstract int addAudioExternalStream(@NonNull String streamId, @NonNull AoqAudioExternalStreamConfig config)
public abstract int removeAudioExternalStream(@NonNull String streamId)
public abstract int pushAudioExternalStreamData(@NonNull String streamId, @NonNull AoqAudioFrameData data)
public abstract int setAudioExternalStreamVolume(@NonNull String streamId, @NonNull AoqAudioStreamDirection type, int volume)
public abstract int getAudioExternalStreamVolume(@NonNull String streamId, @NonNull AoqAudioStreamDirection type)
public abstract void clearAudioExternalStreamBuffer(@NonNull String streamId, int fadeoutMs)
pushAudioExternalStreamData 緩衝區滿時返回 AoqErrorCodeAudioExternalBufferFull(110)，建議 Sleep 30ms 後重試。

即時訊息 

public abstract int sendDataMsg(@NonNull AoqDataMsg msg)

音訊框架回調 

public abstract int setAudioFrameObserver(@Nullable AoqClientListener.AoqAudioFrameListener listener)
public abstract int enableAudioFrameObserver(boolean enabled, @NonNull AoqAudioSource audioSource, @NonNull AoqAudioObserverConfig config)

視訊框架回調 

public abstract int setVideoFrameObserver(@Nullable AoqClientListener.AoqVideoFrameListener listener)
public abstract int enableVideoFrameObserver(boolean enabled, @NonNull AoqVideoSource videoSource, @NonNull AoqVideoObserverConfig config)

AoqClientListener 回調

AoqClientListener 是 SDK 所有非同步事件通知的統一出口。所有回調方法都帶有預設空實現，無需強制重寫不關心的方法。 
public void onError(int code, String message)
public void onWarning(int code, String message)
public void onConnectionStatusChange(@NonNull AoqConnectionStatus status)
public void onStats(@NonNull AoqStats stats)
public void onAudioDeviceStateChanged(@NonNull AoqAudioDeviceState state)
public void onAudioDeviceRouteChanged(int routeType)
public void onAudioDeviceInterrupted(boolean interrupt)
public void onVideoDeviceStateChanged(@NonNull AoqVideoDeviceState state)
public void onAudioDeviceFocusChanged(int audioFocus)
public void onAudioFileState(@NonNull AoqAudioFileState state)
public void onDataMsg(@NonNull AoqDataMsg msg)
串連狀態流轉：Disconnected → Connecting → Connected/Failed → Disconnected。

AoqAudioFrameListener 

public interface AoqAudioFrameListener {
    default void onCapturedAudioFrame(@NonNull AoqAudioFrameData frame) {}
    default void onProcessCapturedAudioFrame(@NonNull AoqAudioFrameData frame) {}
    default void onPublishAudioFrame(@NonNull AoqTrackType trackType, @NonNull AoqAudioFrameData frame) {}
    default void onPlaybackAudioFrame(@NonNull AoqAudioFrameData frame) {}
}

AoqVideoFrameListener 

public interface AoqVideoFrameListener {
    default boolean onCapturedVideoFrame(@NonNull AoqVideoFrameData frame) { return false; }
    default boolean onPreEncodeVideoFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrameData frame) { return false; }
    default boolean onRemoteVideoFrame(@NonNull AoqTrackType trackType, @NonNull AoqVideoFrameData frame) { return false; }
}
返回 true 表示資料已修改需寫回 SDK（僅 I420 寫回生效）。frame 中 ByteBuffer/textureId 僅在回調期間有效，非同步使用需自行拷貝。

資料類型與枚舉

通用類型

AoqCreateConfig

欄位

類型

預設值

說明

workDir

String

""

SDK 工作目錄

isBTScoMode

boolean

false

true 藍芽 SCO 模式；false A2DP 模式

enableDumpAudio

boolean

false

是否開啟音頻 dump（調試用）

extras

String

""

擴充參數字串

AoqConnectConfig

欄位

類型

預設值

說明

token

String

""

串連鑒權 Token

sid

String

""

會話 ID

certFingerprint

String

""

伺服器憑證指紋

relayEndpoints

List<AoqRelayEndpoint>

空

Relay 存取點列表

workspaceIdHash

String

""

工作空間 ID Hash

publishTracks

List<AoqTrackParam>

空

本端發布軌道列表

subscribeTracks

List<AoqTrackParam>

空

本端訂閱軌道列表

統計資訊類型

AoqNetworkStats

欄位

類型

說明

sendBitrate

int

發送碼率（bps）

sendBytes

long

累計發送位元組數

recvBitrate

int

接收碼率（bps）

recvBytes

long

累計接收位元組數

loss

int

丟包率（0-100）

rtt

int

往返延遲（ms）

枚舉類型

AoqErrorCode

枚舉值

值

說明

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

播放啟動失敗

AoqErrorCodeAudioDeviceEarpieceRequiresVoipMode

128

耳機需要 VoIP 模式

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

視頻渲染繪製錯誤

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

資料訊息軌道

AoqEncoderType

枚舉值

值

說明

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

串連失敗

音訊類型

AoqAudioCaptureConfig

欄位

類型

預設值

說明

isExternal

boolean

false

是否為外部採集模式

isVoipMode

boolean

false

是否啟用 VoIP 模式（影響裝置路由，如耳機）

channel

int

1

聲道數（預設單聲道）

AoqAudioPlaybackConfig

欄位

類型

預設值

說明

isVoipMode

boolean

false

是否啟用 VoIP 模式（硬體 AEC），移動端有效

isDefaultSpeaker

boolean

true

是否預設擴音器，移動端有效

isExternal

boolean

false

是否為外部播放模式

channel

int

1

聲道數（預設單聲道）

AoqAudioCodecConfig

欄位

類型

預設值

說明

trackType

AoqTrackType

Audio

軌道類型

codecType

AoqEncoderType

AudioPCM

編碼格式

sampleRate

int

48000

採樣率（Hz）

channel

int

1

聲道數

bitrate

int

32000

位元速率（bps）

視頻類型

AoqVideoCaptureConfig

欄位

類型

預設值

說明

width

int

1280

採集寬度（像素），isExternal=true 時無效

height

int

720

採集高度（像素），isExternal=true 時無效

fps

int

15

採集幀率，isExternal=true 時無效

isExternal

boolean

false

是否外部採集，true 時不開啟網路攝影機

cameraDirection

AoqCameraDirection

Front

網路攝影機方向，isExternal=true 時無效

AoqVideoCodecConfig

欄位

類型

預設值

說明

trackType

AoqTrackType

Video

軌道類型

codecType

AoqEncoderType

VideoH264

編碼格式

width

int

720

編碼寬度（像素）

height

int

1280

編碼高度（像素）

fps

int

5

編碼幀率

bitrate

int

500000

目標位元速率（bps）

minBitrate

int

128000

最小位元速率（bps）

keyframeInterval

int

2

主要畫面格間隔（秒）

mirrorMode

AoqMirrorMode

Disabled

鏡像模式

orientationMode

AoqOrientationMode

Auto

視頻方向模式

isExternal

boolean

false

true 時 SDK 不做二次編碼，由 pushExternalVideoEncodedFrame 直推

AoqVideoPixelFormat

枚舉值

值

說明

AoqVideoPixelFormatUnknown

0

未知格式

AoqVideoPixelFormatI420

1

I420（YUV 三平面格式）

AoqVideoPixelFormatNV12

2

NV12（YUV 半平面格式）

AoqVideoPixelFormatNV21

3

NV21（YUV 半平面格式）

AoqVideoPixelFormatBGRA

4

BGRA（32 位）

AoqVideoPixelFormatRGBA

5

RGBA（32 位）

AoqVideoPixelFormatTextureOES

7

外部 OES 紋理

AoqVideoPixelFormatTexture2D

8

普通 2D 紋理

外部音頻流類型

AoqAudioExternalStreamConfig

欄位

類型

預設值

說明

trackType

AoqTrackType

Audio

音頻軌道類型

codecType

AoqEncoderType

AudioPCM

音頻流格式

channels

int

1

聲道數

sampleRate

int

48000

採樣率（Hz）

playoutVolume

int

100

播放音量 [0-100]

publishVolume

int

100

推流音量 [0-100]

maxBufferDuration

int

1000

最大緩衝時間長度（毫秒）

enable3A

boolean

false

是否對輸入 PCM 進行 3A 處理

AoqAudioStreamDirection

枚舉值

值

說明

AoqAudioStreamPublish

0

發布流（推流）

AoqAudioStreamPlayout

1

播放流（拉流）

資料訊息類型

AoqDataMsg

欄位

類型

預設值

說明

data

byte[]

new byte[0]

訊息資料（位元組數組）

使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多