Skip to main content

AOQ Client SDK Android API リファレンス

AOQ Client SDK for Android は、エンジンのライフサイクル管理、音声/ビデオのキャプチャと再生、コーデック構成、外部音声ストリームのインジェクション、音声ファイルのミキシング、リアルタイムメッセージング、音声/ビデオフレームのコールバックなど、リアルタイムの音声/ビデオ通信に関する全機能を提供します。このドキュメントは、Android プラットフォーム向けの完全な Java API リファレンスです。

AOQ SDK は汎用の動画 API を提供します。Qwen-Audio-Realtime は動画の入出力をサポートしていません。その他のモデルのメディア機能は、それぞれのアクセスドキュメントをご覧ください。

API インデックス

エンジンのライフサイクル

API

説明

createEngine

エンジンインスタンスを作成します (シングルトン)

destroy

エンジンインスタンスを破棄します

getVersion

SDK のバージョン文字列を取得します

connect

Relay サーバーに接続します

disconnect

サーバーから切断します

オーディオデバイス管理

API

説明

startAudioCapture

音声キャプチャデバイス (マイク) を開きます

stopAudioCapture

音声キャプチャデバイスを閉じます

muteAudioCapture

音声キャプチャをミュートまたはミュート解除します

startAudioPlayer

音声再生を開始します (リモート音声を再生)

stopAudioPlayer

音声再生を停止します

pauseAudioPlayer

オプションのフェードアウト付きで音声再生を一時停止します

resumeAudioPlayer

オプションのフェードイン付きで音声再生を再開します

interruptAudioPlayer

現在のオーディオコールターンを中断します

enableSpeakerphone

オーディオ出力をスピーカーとイヤピースで切り替えます

isSpeakerphoneEnabled

スピーカーが現在アクティブかどうかを問い合わせます

オーディオコーデック構成

API

説明

setAudioEncoderConfig

音声エンコーディングパラメーターを設定します

setAudioDecoderConfig

音声デコーディングパラメーターを設定します

ビデオデバイス管理

API

説明

startVideoCapture

ビデオキャプチャデバイス (カメラ) を開きます

stopVideoCapture

ビデオキャプチャデバイスを閉じます

switchCamera

前面カメラと背面カメラを切り替えます

setLocalView

ローカルビデオレンダリングビューを設定または削除します

setRemoteView

リモートビデオレンダリングビューを設定または削除します

ビデオエンコーディングと外部入力

API

説明

setVideoEncoderConfig

ビデオエンコーディングパラメーターを設定します

pushExternalVideoCapturedFrame

外部でキャプチャされたRAWビデオフレームをプッシュします

pushExternalVideoEncodedFrame

外部でエンコードされたビデオフレームをプッシュします

メディアストリーム制御 / リアルタイムメッセージング

API

説明

enableSendMediaStream

ローカルメディアストリームの送信を有効または無効にします

sendDataMsg

リアルタイムデータメッセージを送信します

オーディオファイルの再生

API

説明

startAudioFile

ローカルオーディオファイルのストリーミングを開始します

stopAudioFile

オーディオファイルの再生を停止します

pauseAudioFile

オーディオファイルの再生を一時停止します

resumeAudioFile

オーディオファイルの再生を再開します

getAudioFileDuration

オーディオファイルの総再生時間を取得します

getAudioFileCurrentPosition

現在の再生位置を取得します

setAudioFilePositionMillis

オーディオファイル内の位置にシークします

setAudioFileVolume

オーディオファイルのボリュームを設定します

getAudioFileVolume

現在のオーディオファイルのボリュームを取得します

外部音声ストリーム

API

説明

addAudioExternalStream

外部音声ストリームを追加します

removeAudioExternalStream

外部音声ストリームを削除します

pushAudioExternalStreamData

外部 PCM 音声データをプッシュします

setAudioExternalStreamVolume

外部音声ストリームのボリュームを設定します

getAudioExternalStreamVolume

外部音声ストリームのボリュームを取得します

clearAudioExternalStreamBuffer

外部音声ストリームのバッファーをクリアします

音声/ビデオフレームのコールバック

API

説明

setAudioFrameObserver

音声フレームデータコールバックリスナーを設定します

enableAudioFrameObserver

指定されたポイントで音声フレームコールバックを有効または無効にします

setVideoFrameObserver

ビデオフレームデータコールバックリスナーを設定します

enableVideoFrameObserver

指定されたポイントでビデオフレームコールバックを有効または無効にします

AoqClientListener コールバック

コールバック

説明

onError

エンジンエラーコールバック

onWarning

エンジン警告コールバック

onConnectionStatusChange

接続状態変更コールバック

onStats

エンジン統計コールバック

onAudioDeviceStateChanged

オーディオデバイス状態変更コールバック

onAudioDeviceRouteChanged

オーディオ出力ルート変更コールバック

onAudioDeviceInterrupted

オーディオデバイス中断コールバック

onVideoDeviceStateChanged

ビデオデバイス状態変更コールバック

onAudioDeviceFocusChanged

オーディオフォーカス変更コールバック

onAudioFileState

オーディオファイル再生状態コールバック

onDataMsg

リアルタイムデータメッセージ受信コールバック

API の詳細

エンジンのライフサイクル

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 が接続パラメーターをクライアントに配信します。この呼び出しは直ちに戻ります。実際の接続結果は onConnectionStatusChange コールバックで通知されます。
汎用 SDK API のドキュメントでは、AppServer が /api/v1/allocate を通じて接続パラメーターを割り当てます。特定のモデルについては、Qwen-Omni-Realtime AOQ アクセス、Qwen-Audio-Realtime AOQ アクセス、Qwen-LiveTranslate-Realtime AOQ アクセスをご覧ください。
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) を返した場合、内部バッファーは一杯です。30 ミリ秒待ってからリトライしてください。

リアルタイムメッセージング

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; }
}
フレームデータを変更し、SDK にそれを読み戻させることを示すには true を返します (書き戻しは I420 フォーマットでのみ有効です)。frame 内の ByteBuffer と textureId はコールバック中のみ有効です。非同期で使用する前に、これらをコピーしてください。

データ型と列挙型

一般的な型

AoqCreateConfig

フィールド

型

デフォルト

説明

workDir

String

""

SDK の作業ディレクトリ

isBTScoMode

boolean

false

true:Bluetooth SCO モード、false:A2DP モード

enableDumpAudio

boolean

false

オーディオダンプを有効にします (デバッグ用)

extras

String

""

追加のパラメーター文字列

AoqConnectConfig

フィールド

型

デフォルト

説明

token

String

""

認証トークン

sid

String

""

セッション ID

certFingerprint

String

""

サーバー証明書の指紋

relayEndpoints

List<AoqRelayEndpoint>

empty

Relay エンドポイントのリスト

workspaceIdHash

String

""

ワークスペース ID ハッシュ

publishTracks

List<AoqTrackParam>

empty

公開するローカルトラック

subscribeTracks

List<AoqTrackParam>

empty

サブスクライブするリモートトラック

統計タイプ

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]

メッセージデータ (バイト配列)