AOQ SDK の音声機能 - キャプチャ、再生、ミキシング、フレームコールバック - Alibaba Cloud Model Studio

AOQ Client SDK は、音声キャプチャ、再生、コーデック設定、スピーカー管理、ファイルミキシング、外部音声ストリームの注入、音声フレームデータのコールバックをカバーする包括的な音声機能を提供します。このドキュメントでは、Android (Java)、iOS (Objective-C)、HarmonyOS (ArkTS) に共通する音声機能について説明します。

音声キャプチャ

音声キャプチャは、デバイスのマイクを有効にし、リアルタイムの音声データを SDK のエンコーディングパイプラインに供給します。SDK は 2 つのキャプチャモードをサポートしています：

内部キャプチャ (デフォルト)：SDK がマイクの有効化、録音、無効化を自動的に管理します。
外部キャプチャ：アプリケーションが直接マイクを管理し、キャプチャした PCM データを外部音声ストリーム API を介して SDK に供給します。

設定パラメーター

パラメーター	型	デフォルト	説明
isExternal	bool	false	外部キャプチャモードを使用するかどうか
isVoipMode	bool	false	VoIP モード (ハードウェア AEC) を有効にするかどうか。モバイルで有効です。キャプチャと再生の両方が設定されている場合、最初に設定された方が有効になります。
channel	int	1	キャプチャチャンネル数。1 (モノラル) または 2 (ステレオ) をサポートします。

API リファレンス

機能	Android	iOS	HarmonyOS
キャプチャの開始	`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];

HarmonyOS

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	HarmonyOS
再生の開始	`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	HarmonyOS
スピーカーの切り替え	`enableSpeakerphone(enable)`	`enableSpeakerphone:`	`enableSpeakerphone(enable)`
スピーカー状態のクエリ	`isSpeakerphoneEnabled()`	`isSpeakerphoneEnabled`	`isSpeakerphoneEnabled()`

注記スピーカーの切り替えは VoIP モードでのみ許可されます。VoIP モードでないときに enableSpeakerphone を呼び出すと、OnError(AoqECAudioDeviceEarpieceRequiresVoipMode) エラー通知がトリガーされます。

注記iOS 固有の動作：iPad デバイスにはスピーカーモードしかありません。AVAudioSession のカテゴリが PlayAndRecord でない場合、このメソッドは常に YES を返します。

音声コーデック設定

音声アップリンク (エンコーダー) とダウンリンク (デコーダー) のエンコード形式、サンプルレート、チャンネル数、ビットレートを設定します。これらの設定は、ストリームの配信とプルの形式を決定します。

設定パラメーター

パラメーター	型	デフォルト	説明
trackType	AoqTrackType	Audio	音声トラックタイプ。現在、1 つの音声ストリームのみがサポートされています。
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	HarmonyOS
エンコーダー設定	`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	HarmonyOS
再生の開始	`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/192 kHz をサポートします。
playoutVolume	int	100	ローカル再生音量 [0–100]
publishVolume	int	100	発行ボリューム [0–100]
maxBufferDuration	int	600000	最大バッファー持続時間 (ミリ秒)。有効値：[100, ~]。バッファーが満杯の場合、プッシュは失敗します。
enable3A	bool	false	入力 PCM に 3A 処理を適用するかどうか

API リファレンス

機能	Android	iOS	HarmonyOS
外部ストリームの追加	`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)`

データプッシュに関する推奨事項

データが正常にプッシュされるように、ループ内で pushAudioExternalStreamData を呼び出します。
エラーコード 110 (バッファー満杯) が返された場合は、30 ms スリープしてからリトライします。データは破棄しないでください。
エンジンが終了する前に、まずプッシュループを停止し、次に removeAudioExternalStream を呼び出します。
リアルタイムキャプチャの場合、各フレームは 10 ms です。データが利用可能になるたびにプッシュを呼び出します。ファイルベースの入力の場合、各フレームは 40 ms です。30 ms ごとにプッシュを呼び出します。

音声フレームコールバック

音声フレームコールバックを使用すると、音声パイプラインのさまざまなポイントで生の PCM データを取得し、音声分析、カスタム処理、録音などのシナリオで使用できます。

サポートされているデータソースの位置

データソース	列挙値	説明
Captured	0	キャプチャ後、3A 処理前の生の音声データ
ProcessCaptured	1	3A 処理後の音声データ。コールバックは接続が成功した後にのみ開始されます。
Publish	2	配信直前の音声データ。接続が成功している必要があります。
Playback	3	再生直前の音声データ (リモートダウンリンク)

コールバック設定パラメーター

パラメーター	型	デフォルト	説明
sampleRate	int	48000	コールバック音声のサンプルレート
channels	int	1	コールバック音声のチャンネル数。1 または 2 をサポートします。
mode	AoqAudioObserverMode	ReadOnly	読み取り専用 (0) または読み書き (1) モード

利用手順

オブザーバーの登録：setAudioFrameObserver を呼び出して、音声フレームコールバックリスナーを設定します。
データソースの有効化：enableAudioFrameObserver を呼び出して、データソースの位置を選択し、コールバックを開始します。
コールバックデータの処理：コールバックで PCM データを処理します。

API リファレンス

機能	Android	iOS	HarmonyOS
オブザーバーの登録	`setAudioFrameObserver(listener)`	`setAudioFrameObserver:`	`setAudioFrameObserver(observer)`
コールバックの有効化	`enableAudioFrameObserver(enabled, source, config)`	`enableAudioFrameObserver:audioSource:config:`	`enableAudioFrameObserver(enabled, source, config)`

コールバックメソッド

コールバック	Android	iOS	HarmonyOS
キャプチャデータ	`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	Bluetooth SCO
BluetoothA2dp	7	Bluetooth A2DP

コールバックリファレンス

コールバック	Android	iOS	HarmonyOS
デバイス状態の変更	`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 API を使用して、SDK がシステムの AVAudioSession をどのように管理するかを詳細に制御できます。

制御	説明
SetCategory	SDK がセッションカテゴリを設定できるかどうか
ConfigureSession	SDK がセッションパラメーターを設定できるかどうか
DeactivateSession	SDK がセッションを非アクティブ化できるかどうか
ActivateSession	SDK がセッションをアクティブ化できるかどうか

制限値のビット単位の組み合わせを渡すことで、SDK の AVAudioSession に対する制御を制限し、アプリケーション層の他の音声コンポーネントとの競合を防ぎます。