AOQ クライアント SDK の認証情報取得、初期化、メディア方向の設定、接続、モデルイベント交換、リソース解放の手順を説明します。
AOQ は音声、映像、モデルイベントを別々のトラックで転送します。SDK はメディアのキャプチャ、エンコード、デコード、転送、再生を処理します。アプリケーションは Data トラックでモデルイベントを送信し、応答を処理します。対象モデルに必要なメディア方向とイベントプロトコルを選択してください。
前提条件
-
接続の概要の準備を完了し、対象モデル、リージョン、AOQ 対応状況を確認します。
-
SDK のダウンロードからプラットフォームに対応する SDK をインポートします。Opus を使用する場合は対応するプラグインもインポートします。
-
アプリケーションサーバー (AppServer) にトークン認証を実装します。API キーは AppServer に保持し、クライアントには一時的な接続認証情報を渡します。
注記マイクやカメラの権限は、キャプチャが必要な場合にのみ要求します。たとえば、音声合成にはどちらの権限も不要です。
処理フロー
- AppServer 経由で接続認証情報を取得します。
- SDK エンジンを作成し、コールバックを登録します。
- メディアトラックと Data トラックを設定し、上りメディアの送信を無効にします。
- AOQ 接続を開始し、接続完了を待ちます。
- モデルのプロトコルに従って設定します。確認後、必要な上りメディアを有効にします。
- 対話が終了したら切断し、リソースを解放します。
注記
-
AOQ SDK はメディアのキャプチャ、処理、送信、受信、再生を担当します。アプリケーションは対象モデルのイベント定義に従って Data メッセージを送受信する必要があります。
-
接続成功はモデルへのトランスポートチャネルの確立を意味します。音声の設定などの事前操作が必要な場合は、モデルの設定を完了してからメディアを送信してください。たとえば、Realtime モデルでは
session.updated、Inference モデルではtask-startedを待つ必要があります。クライアントはモデルの初期化成功後にのみ、必要な上りメディアを有効にできます。
1. 接続認証情報の取得
クライアントは AppServer に認証情報を要求します。AppServer は対象モデルに応じて Realtime または Inference の接続エンドポイントを選択し、API キーと x-dashscope-rtc-transport: moq ヘッダーをゲートウェイに送信します。エンドポイント、リクエスト、フィールドについてはトークン認証を参照してください。
応答を AoqConnectConfig に対応付けます。
| ゲートウェイの応答 | SDK 設定 |
|---|---|
aoqTokenForClient | token |
sid | sid |
clientRelayCertFingerprint | certFingerprint |
clientRelayEndpoints | relayEndpoints：各エンドポイントを必要な構造に変換 |
extraInfo.workspaceIdHash | workspaceIdHash |
新しい接続ごとに新しい認証情報を取得してください。同じ接続でセッションを再利用したり、別のタスクを開始したりできるかどうかは、対象モデルのプロトコルに依存します。
2. SDK の初期化とコールバックの登録
エンジンを作成し、接続状態、Data メッセージ、エラーのコールバックを登録します。以下は iOS の Swift の例です。
let createConfig = AoqCreateConfig()
createConfig.workDir = workDir
createConfig.enableDumpAudio = false
engine = AoqClientEngine.createEngine(createConfig, delegate: self)
AoqEngineDelegate を実装します。onConnectionStatusChange で接続状態を管理し、onDataMsg でモデルイベントを解析し、onError で SDK エラーを処理します。モデルのエラーイベントは Data メッセージのハンドラーで別途処理してください。SDK インターフェイスとエラーについては AOQ クライアント SDK を参照してください。
3. SDK の設定
メディア方向の選択
方向はクライアントから見たものです。アプリケーションに必要な入力と出力のモダリティだけを設定し、使用しない方向のトラックは追加しないでください。
| 方向 | 設定 | 主な用途 |
|---|---|---|
| 音声送信 | Audio トラックを発行し、エンコーダーを設定して、内蔵または外部キャプチャを使用 | 音声認識、会話、翻訳 |
| 音声受信 | Audio トラックを購読し、デコーダーを設定して、内蔵または外部再生を使用 | 音声合成、音声応答 |
| 映像送信 | Video トラックを発行し、カメラまたは外部入力とエンコードを設定 | 視覚入力対応モデルに画像を提供 |
| 映像受信 | 対象モデルまたはアプリケーションが映像出力を明示的にサポートする場合のみ、購読と受信を設定 | 対象モデルまたはアプリケーションのドキュメントに従う |
Data トラックは、この 4 方向とは独立しています。モデルイベントの送信用に Data トラックを発行し、応答を受信するために購読します。テキストの入出力にも Data トラックが必要です。
モデルに応じた方向の選択
以下に代表的な設定を示します。対応モデルとバージョンは Realtime API の概要およびモデルのドキュメントを参照してください。
| モデルまたはアプリケーション | 音声送信 | 音声受信 | 映像送信 | 映像受信 |
|---|---|---|---|---|
| Qwen-Omni-Realtime | 音声入力時 | 音声応答時 | 視覚入力時 | 非対応 |
| Qwen-Audio-Realtime | 音声会話時 | 音声応答時 | 非対応 | 非対応 |
| Qwen-Audio-TTS, CosyVoice | 非対応 | 有効 | 非対応 | 非対応 |
| Qwen-Audio-ASR-Streaming | 有効 | 非対応 | 非対応 | 非対応 |
| Fun-ASR-Realtime | 有効 | 非対応 | 非対応 | 非対応 |
| Qwen-LiveTranslate-Realtime | 音声入力時 | 音声翻訳出力時 | バージョンとシナリオに依存 | 非対応 |
| multimodal-dialog | アプリケーションの入力に応じる | アプリケーションの出力に応じる | アプリケーションの機能に応じる | アプリケーションが明示的にサポートする場合のみ |
メディアパラメーターとトラックの設定
上り音声と下り音声を別々に設定します。上りには setAudioEncoderConfig、下りには setAudioDecoderConfig を使用します。これらはネットワーク転送を制御するパラメーターで、ゲートウェイがモデルに必要な形式に音声を変換します。転送時のエンコードは SDK の要件に、モデルイベント内の音声形式は対象モデルの要件に従って設定してください。
必要に応じて startAudioCapture、startAudioPlayer、startVideoCapture を開始します。カスタム入出力については後述の高度な機能を参照してください。
publishTracks はクライアントが送信するトラック、subscribeTracks はクライアントが受信するトラックです。
| シナリオ | publishTracks | subscribeTracks |
|---|---|---|
| 音声会話 | Audio, Data | Audio, Data |
| 視覚入力を伴う音声会話 | Audio, Video, Data | Audio, Data |
| 音声認識 | Audio, Data | Data |
| 音声合成 | Data | Audio, Data |
モデルの準備前に入力が届かないよう、接続前に上りメディアを無効にします。
engine.enableSendMediaStream(.audio, enable: false)
engine.enableSendMediaStream(.video, enable: false)
キャプチャ、トラック発行、送信許可は別々の操作です。送信を無効にしてもローカルのキャプチャは停止せず、Data イベントにも影響しません。送信を有効にしても、未追加のトラックが作成されるわけではありません。
4. 接続の確立
認証情報とトラック設定を AoqConnectConfig に設定し、次を呼び出します。
engine.connect(connectConfig)
onConnectionStatusChange で .connected を受け取ってからモデルを初期化します。connect の呼び出しが戻っただけでは接続成功を意味しません。
5. モデルイベントとメディアの交換
モデルイベントの送信と解析
Data トラックでイベントを送信します。以下は iOS の Swift の例です。
// Build eventJSON according to the target model client event protocol.
let msg = AoqDataMsg()
msg.data = eventJSON.data(using: .utf8)!
engine.send(msg)
onDataMsg で応答を解析します。すべてのイベントが type を使用すると想定しないでください。Realtime イベントは通常 type、Inference のサーバーイベントは header.event を使用します。フィールド、パラメーター、完了条件は対象モデルのドキュメントに従ってください。
モデルの準備完了後にメディアを有効化
現在のモデル、セッション、タスクの準備完了条件を満たした後、設定済みの上り方向だけを有効にします。音声入力の場合は次を呼び出します。
engine.enableSendMediaStream(.audio, enable: true)
映像入力が必要な場合のみ .video を有効にします。TTS はテキスト入力を使用するため、上り音声や映像は不要です。
音声と映像はそれぞれのメディアトラックで、モデルイベントとテキストは Data トラックで送信します。たとえば AOQ 経由の Omni では、同じメディアを input_audio_buffer.append や input_image_buffer.append で再送する必要はありません。下り音声は設定済みプレーヤーまたは外部再生ロジックで処理します。
6. 対話の終了とリソースの解放
接続が不要になったら、アプリケーションから AOQ SDK の切断とリソース解放のインターフェイスを呼び出します。
engine.disconnect()
AoqClientEngine.destroy()
予期しない切断後はアプリケーションの準備完了状態をクリアし、接続状態の管理に従ってください。再接続後はモデルを再初期化します。
Data トラックでのイベント送受信
接続時に Data トラックを発行、購読します。送信時はイベントを AoqDataMsg にシリアライズして engine.send(msg) を呼び出します。受信メッセージは onDataMsg で解析します。
送信するイベント名、フィールド、パラメーター、タイミングは対象モデルのクライアントイベント定義に従ってください。応答の解析、状態変化、結果、エラーはサーバーイベント定義に従います。モデルに必要な初期化イベントを送り、その後はアプリケーションに必要なテキストや制御イベントを送信します。
| モデルまたはアプリケーション | クライアントイベント (送信) | サーバーイベント (受信) |
|---|---|---|
| Qwen-Omni-Realtime | クライアントイベント | サーバーイベント |
| Qwen-Audio-Realtime | クライアントイベント | サーバーイベント |
| Qwen-Audio-TTS, CosyVoice | クライアントイベント | サーバーイベント |
| Qwen-Audio-ASR-Streaming | クライアントイベント | サーバーイベント |
| Fun-ASR-Realtime | クライアントイベント | サーバーイベント |
| Qwen-LiveTranslate-Realtime | クライアントイベント | サーバーイベント |
| multimodal-dialog | 対話プロトコルの Input Message | 対話プロトコルの Output Message |
マルチモーダル対話スイートでは 1 つの対話プロトコルに両方向を定義しています。実際に使用するモデルバージョンのイベント定義を選択してください。すべてのモデルに共通する固定のイベントスキーマはありません。
次のルールにも従ってください。
-
モデルに応じてイベント種別と相関 ID を識別します。Realtime は通常
type、Inference クライアントはheader.action、サーバーはheader.eventを使用し、タスクはtask_idで関連付けます。 -
初期化確認、入力送信、応答キャンセル、タスク完了は、プロトコルに従って Data トラックで処理します。これらはトランスポート接続を閉じる操作とは異なります。
-
たとえば Inference モデルでは
finish-taskでタスクを終了し、task-finishedで完了を確認します。残りの結果を受信してから接続を解放してください。最後まで再生する必要がある場合は、ローカルに残っている音声の再生完了も待ちます。 -
メディアにはメディアトラックを使用します。モデルイベントのドキュメントを参照する場合も、メディア転送と利用可能な対話モードはこの AOQ ページに従い、WebSocket のメディアアップロード方式をコピーしないでください。
高度な機能
| 機能 | 用途 | ドキュメント |
|---|---|---|
| 音声と映像の送信を個別制御 | モデルの準備完了待ち、上りメディアの一時停止、必要に応じた映像の有効化 | メディア送信の管理 |
| 音声デバイスと処理 | エンコード、デコード、スピーカー、ファイルミキシング、音声フレームのコールバック | 一般的な音声機能 |
| 外部音声入力 | アプリケーションが提供する音声ソースの使用 | カスタム音声キャプチャ |
| 外部音声出力 | アプリケーションで出力音声を処理または再生 | カスタム音声再生 |
| 映像キャプチャと入力 | カメラまたはアプリケーションが提供する画像の使用 | 一般的な映像機能, カスタム映像入力 |
メディア送信の制御はメディアのみに作用します。モデル応答のキャンセルやターンの送信には、対象モデルのイベントが引き続き必要です。
ベストプラクティス
-
Omni リアルタイム通話：音声・映像入力、音声応答、セッションイベント。
-
Omni プッシュツートーク：ボタン操作による入力と手動ターン。
-
Qwen-Audio 音声会話：双方向音声。
-
Qwen-Audio 音声合成：Data トラックでのテキスト入力と Audio トラックでの音声出力。
-
Fun-ASR 音声認識：Audio トラックでの音声入力と Data トラックでの認識結果。