Skip to main content
功能參考

音頻常用功能介紹

AOQ Client SDK 提供了完整的音頻能力，覆蓋音頻採集、播放、編解碼配置、擴音器管理、檔案混音、外部音頻流注入、音訊框架資料回調等核心情境。本文檔基於 Android（Java）、iOS（Objective-C）、Ohos（ArkTS）三個平台的公開 API，對音頻常用功能進行統一介紹。

音頻採集

音頻採集用於開啟裝置麥克風，將即時音頻資料送入 SDK 編碼推流管線。SDK 支援兩種採集模式：
  • 內部採集（預設）：SDK 自動管理麥克風裝置的開啟、錄音和關閉。
  • 外部採集：由應用自行管理麥克風，採集到的 PCM 資料通過外部音頻流介面輸入 SDK。

配置參數

參數

類型

預設值

說明

isExternal

bool

false

是否使用外部採集模式

isVoipMode

bool

false

是否啟用 VoIP 模式（硬體 AEC），移動端有效，採集播放參數先到為準

channel

int

1

採集通道數，支援 1（單聲道）/ 2（立體聲）

API 對照

功能

Android

iOS

Ohos

開啟採集

startAudioCapture(config)

startAudioCapture:config:

startAudioCapture(config)

關閉採集

stopAudioCapture()

stopAudioCapture

stopAudioCapture()

靜音/取消靜音

muteAudioCapture(mute)

muteAudioCapture:

muteAudioCapture(mute)

使用樣本

Android 
AoqAudioCaptureConfig config = new AoqAudioCaptureConfig();
config.isVoipMode = true;
config.channel = 1;
engine.startAudioCapture(config);
iOS 
AoqAudioCaptureConfig *config = [[AoqAudioCaptureConfig alloc] init];
config.isVoipMode = YES;
config.channel = 1;
[engine startAudioCapture:config];
Ohos 
const config: AoqAudioCaptureConfig = { isVoipMode: true, channel: 1 };
engine.startAudioCapture(config);

音頻播放

音頻播放用於將接收到的遠端音頻資料渲染到本地擴音器或耳機。SDK 支援播放暫停/恢複（帶淡入淡出）、打斷當前輪語音通話等進階控制。

配置參數

參數

類型

預設值

說明

isVoipMode

bool

false

是否啟用 VoIP 模式（硬體AEC），移動端有效，採集播放參數先到為準

isDefaultSpeaker

bool

true

是否預設使用擴音器（移動端有效，非VoIP時無效）

isExternal

bool

false

是否使用外部播放模式

channel

int

1

播放通道數，支援 1（單聲道）/ 2（立體聲）

API 對照

功能

Android

iOS

Ohos

開始播放

startAudioPlayer(config)

startAudioPlayer:config:

startAudioPlayer(config)

停止播放

stopAudioPlayer()

stopAudioPlayer

stopAudioPlayer()

暫停播放

pauseAudioPlayer(fadeMs)

pauseAudioPlayer:

pauseAudioPlayer(fadeMs)

恢複播放

resumeAudioPlayer(fadeMs)

resumeAudioPlayer:

resumeAudioPlayer(fadeMs)

打斷通話

interruptAudioPlayer(trackType, fadeMs)

interruptAudioPlayer:fadeMs:

interruptAudioPlayer(trackType, fadeMs)

fadeMs 參數：暫停和恢複播放時的淡入/淡出時間長度（毫秒），設為 0 則立即切換。

擴音器管理

控制音訊輸出裝置在擴音器和耳機之間切換。

功能

Android

iOS

Ohos

切換擴音器

enableSpeakerphone(enable)

enableSpeakerphone:

enableSpeakerphone(enable)

查詢擴音器狀態

isSpeakerphoneEnabled()

isSpeakerphoneEnabled

isSpeakerphoneEnabled()

需要在 VoIP 模式下才允許切換，非 VoIP 時，enableSpeakerphone 調用有 OnError(AoqECAudioDeviceEarpieceRequiresVoipMode) 錯誤通知。
iOS 特殊行為：iPad 裝置只有擴音器模式；當 AVAudioSession 不是 PlayAndRecord 類別時，也始終返回 YES。

音頻編解碼配置

設定音頻上行（編碼器）和下行（解碼器）的編碼格式、採樣率、聲道數和碼率。表示推流/拉流的格式。

配置參數

參數

類型

預設值

說明

trackType

AoqTrackType

Audio

音頻軌道類型，當前只支援一條音頻流

codecType

AoqEncoderType

AudioPCM

編碼類別型：AudioPCM(1) 或 AudioOpus(2)

sampleRate

int

48000

採樣率，Opus 支援 8K/16K/48K，PCM 支援 8K/16K/32K/48K

channel

int

1

聲道數，支援 1（單聲道）/ 2（立體聲）

bitrate

int

32000

碼率（bps）

API 對照

功能

Android

iOS

Ohos

設定編碼參數

setAudioEncoderConfig(config)

setAudioEncoderConfig:

setAudioEncoderConfig(config)

設定解碼參數

setAudioDecoderConfig(config)

setAudioDecoderConfig:

setAudioDecoderConfig(config)

支援的編碼格式

枚舉值

數值

說明

AoqEncoderTypeAudioPCM

1

PCM 裸音頻

AoqEncoderTypeAudioOpus

2

Opus 編碼

音頻檔案混音

支援將本地音頻檔案混入當前音頻流中一起推流和/或本地播放。每個音頻檔案通過業務自分配的 fileId 標識，可同時管理多個檔案執行個體。

混音配置參數

參數

類型

預設值

說明

fileName

String

-

音頻檔案路徑（含檔案名稱）

cycles

int

-1

迴圈次數，-1 表示無限迴圈

startPosMs

long

0

起始播放位置（毫秒）

publishVolume

int

100

推流音量 [0-100]

playoutVolume

int

100

本地播放音量 [0-100]

API 對照

功能

Android

iOS

Ohos

開始播放

startAudioFile(fileId, config)

startAudioFile:config:

startAudioFile(fileId, config)

停止播放

stopAudioFile(fileId)

stopAudioFile:

stopAudioFile(fileId)

暫停

pauseAudioFile(fileId)

pauseAudioFile:

pauseAudioFile(fileId)

恢複

resumeAudioFile(fileId)

resumeAudioFile:

resumeAudioFile(fileId)

擷取檔案時間長度

getAudioFileDuration(fileId)

getAudioFileDuration:

getAudioFileDuration(fileId)

擷取當前位置

getAudioFileCurrentPosition(fileId)

getAudioFileCurrentPosition:

getAudioFileCurrentPosition(fileId)

設定播放位置

setAudioFilePositionMillis(fileId, pos)

setAudioFilePositionMillis:positionMillis:

setAudioFilePositionMillis(fileId, pos)

設定音量

setAudioFileVolume(fileId, type, vol)

setAudioFileVolume:type:volume:

setAudioFileVolume(fileId, type, vol)

擷取音量

getAudioFileVolume(fileId, type)

getAudioFileVolume:type:

getAudioFileVolume(fileId, type)

音量方向（type）：AoqAudioStreamPublish(0) 控制推流音量；AoqAudioStreamPlayout(1) 控制本地播放音量。

狀態回調

狀態代碼

數值

說明

AoqAudioFileNone

0

初始狀態

AoqAudioFileStarted

1

已開始播放

AoqAudioFileStopped

2

已停止

AoqAudioFilePaused

3

已暫停

AoqAudioFileResumed

4

已恢複

AoqAudioFileEnded

5

播放結束

AoqAudioFileBuffering

6

緩衝中

AoqAudioFileBufferingEnd

7

緩衝結束

AoqAudioFileFailed

8

播放失敗

外部音頻流

外部音頻流允許將應用產生的 PCM 音頻資料注入到 SDK 的音頻管線中，支援推流和/或本地播放。典型情境包括 TTS 語音合成輸出、AI 模型音訊輸出、背景音效等。每個外部音頻流通過業務自分配的 streamId 標識。

配置參數

參數

類型

預設值

說明

trackType

AoqTrackType

Audio

音頻軌道類型

codecType

AoqEncoderType

AudioPCM

音頻流格式

channels

int

1

聲道數

sampleRate

int

48000

採樣率，支援 8/12/16/24/32/44.1/48/64/88.2/96/176.4/192K

playoutVolume

int

100

本地播放音量 [0-100]

publishVolume

int

100

推流音量 [0-100]

maxBufferDuration

int

600000

最大緩衝時間長度（毫秒），取值範圍 [100, ~]，超過時 Push 失敗

enable3A

bool

false

輸入 PCM 是否經過 3A 處理

API 對照

功能

Android

iOS

Ohos

新增外部音頻流

addAudioExternalStream(streamId, config)

addAudioExternalStream:config:

addAudioExternalStream(streamId, config)

輸入音頻資料

pushAudioExternalStreamData(streamId, data)

pushAudioExternalStreamData:data:

pushAudioExternalStreamData(streamId, data)

設定音量

setAudioExternalStreamVolume(streamId, type, vol)

setAudioExternalStreamVolume:type:volume:

setAudioExternalStreamVolume(streamId, type, vol)

擷取音量

getAudioExternalStreamVolume(streamId, type)

getAudioExternalStreamVolume:type:

getAudioExternalStreamVolume(streamId, type)

清空緩衝

clearAudioExternalStreamBuffer(streamId, fadeoutMs)

clearAudioExternalStreamBuffer:fadeoutMs:

clearAudioExternalStreamBuffer(streamId, fadeoutMs)

移除流

removeAudioExternalStream(streamId)

removeAudioExternalStream:

removeAudioExternalStream(streamId)

Push 資料最佳實務

  • 需要迴圈調用 pushAudioExternalStreamData，保證資料 push 成功
  • 返回錯誤碼 110（緩衝區滿）時短暫 Sleep 30ms 後重試，不要丟棄資料
  • 引擎退出前先停止推送迴圈，再調用 removeAudioExternalStream
  • 即時採集每幀 10ms 長，有資料就調用 push；從檔案解析每幀 40ms 長，間隔 30ms 調用 push 一次

音訊框架資料回調

音訊框架回調允許開發人員在音頻管線的不同位置擷取原始 PCM 資料，用於音頻分析、自訂處理、錄製等情境。

支援的資料來源位置

資料來源

枚舉值

說明

Captured

0

採集後的原始音頻資料（未經 3A 處理）

ProcessCaptured

1

經過 3A 處理後的音頻資料，需要 Connect 成功後才回調資料

Publish

2

即將推流的音頻資料（需要 Connect 成功）

Playback

3

即將播放的音頻資料（遠端下行）

回調配置參數

參數

類型

預設值

說明

sampleRate

int

48000

回調音訊採樣率

channels

int

1

回調音訊聲道數，支援 1/2

mode

AoqAudioObserverMode

ReadOnly

唯讀(0)/讀寫(1) 模式

使用步驟

  1. 註冊觀察者：調用 setAudioFrameObserver 設定音訊框架回調監聽器
  2. 啟用資料來源：調用 enableAudioFrameObserver 選擇需要監聽的資料來源位置，開啟回調
  3. 處理回調資料：在回呼函數中擷取 PCM 資料

API 對照

功能

Android

iOS

Ohos

註冊觀察者

setAudioFrameObserver(listener)

setAudioFrameObserver:

setAudioFrameObserver(observer)

啟用回調

enableAudioFrameObserver(enabled, source, config)

enableAudioFrameObserver:audioSource:config:

enableAudioFrameObserver(enabled, source, config)

回調方法

回調

Android

iOS

Ohos

採集資料

onCapturedAudioFrame(frame)

onCapturedAudioFrame:

onCapturedAudioFrame(frame)

3A 後資料

onProcessCapturedAudioFrame(frame)

onProcessCapturedAudioFrame:

onProcessCapturedAudioFrame(frame)

推流資料

onPublishAudioFrame(trackType, frame)

onPublishAudioFrame:frame:

onPublishAudioFrame(trackType, frame)

播放資料

onPlaybackAudioFrame(frame)

onPlaybackAudioFrame:

onPlaybackAudioFrame(frame)

音頻狀態與路由

SDK 自動監測音訊裝置的狀態變化和路由切換，並通過回調通知應用程式層。

裝置狀態代碼

狀態代碼

值

說明

AoqAudioDeviceNone

0

初始狀態

RecordStarting

1

採集啟動中

RecordStarted

2

採集已啟動

RecordStopping

3

採集停止中

RecordStopped

4

採集已停止

RecordFail

5

採集失敗

PlayStarting

6

播放啟動中

PlayStarted

7

播放已啟動

PlayStopping

8

播放停止中

PlayStopped

9

播放已停止

PlayFail

10

播放失敗

裝置路由類型

路由

值

說明

Default

0

預設

Headset

1

有線耳機

Earpiece

2

耳機

HeadsetNoMic

3

無麥克風耳機

SpeakerPhone

4

擴音器

Usb

5

USB 裝置

Bluetooth

6

藍芽 SCO

BluetoothA2dp

7

藍芽 A2DP

回調對照

回調

Android

iOS

Ohos

裝置狀態變化

onAudioDeviceStateChanged(state)

onAudioDeviceStateChanged:

onAudioDeviceStateChanged(state, reason)

路由變化

onAudioDeviceRouteChanged(routeType)

onAudioDeviceRouteChanged:

onAudioDeviceRouteChanged(routeType)

裝置中斷

onAudioDeviceInterrupted(interrupt)

onAudioDeviceInterrupted:

onAudioDeviceInterrupted(interrupt)

檔案狀態

onAudioFileState(state)

onAudioFileState:

onAudioFileState(fileId, stateCode, errorCode)

音頻錯誤碼與警告碼

音頻錯誤碼

錯誤碼

值

說明

AoqErrorCodeAudio

100

通用音頻錯誤

AudioExternalBufferFull

110

外部緩衝區已滿

AudioDevice

120

裝置通用錯誤

RecordingAuthFailed

121

麥克風許可權失敗

RecordingOccupied

122

麥克風被佔用

RecordingBackgroundStart

123

後台啟動錄音

RecordingStartFail

124

錄音啟動失敗

PlayoutOccupied

125

播放裝置被佔用

PlayoutBackgroundStart

126

後台啟動播放

PlayoutStartFail

127

播放啟動失敗

EarpieceRequiresVoipMode

128

耳機需要啟用 VoIP 模式

音頻警告碼

警告碼

值

說明

AoqWCAudio

100

通用音頻警告

AudioHowling

101

嘯叫檢測

AudioDevice

120

裝置通用警告

MicEnumerateError

121

麥克風枚舉錯誤

MicStartTimeout

122

麥克風啟動逾時

RecordingError

123

錄音錯誤

SpeakerEnumerateError

124

擴音器枚舉錯誤

SpeakerStartTimeout

125

擴音器啟動逾時

PlayoutError

126

播放錯誤

iOS 專有：AVAudioSession 控制

iOS 平台提供了 setAudioSessionRestriction 介面，可精細控制 SDK 對系統 AVAudioSession 的系統管理權限。

控制項

說明

SetCategory

SDK 是否有權設定 Session 類別

ConfigureSession

SDK 是否有權配置 Session 參數

DeactivateSession

SDK 是否有權停用 Session

ActivateSession

SDK 是否有權啟用 Session

通過按位組合傳入 restriction 值，可限制 SDK 對 AVAudioSession 的控制範圍，避免與應用程式層其他音頻組件衝突。
使用 API
文本產生
映像產生
視頻產生
音頻
即時多模態
Realtime API
向量與排序
更多模型
工具包/架構
模型生產
檔案管理
更多