オーディオ・コネクター

Audio Connectorを使用すると、Vonage Videoのライブ・セッションから生のオーディオ（PCM 16 khz/16bit）ストリームを送信できます。 AWS、GCP、Azureなどの外部サービスに送信することができます。および分析することができます。

Audio Connectorを使用すると、オーディオストリームを個別に、または混合して送信することができます。複数のWS接続を開き、オーディオストリームを個別に送信することで、スピーカーを特定することができます。

音声ストリームをリアルタイムかつオフラインでさらに処理することで、次のような機能を構築できます。キャプション、トランスクリプション、翻訳、検索、インデックス、コンテンツモデレーションなどの機能を構築できます、メディアインテリジェンス、電子カルテ、センチメント分析など。

Audio Connectorを使用して、WebSocket接続を以下のように使用することもできます。 OpenTokセッションに音声を配信する.

Audio Connector は、すべてのプロジェクトでデフォルトで有効になっており、使用ベースの製品です。 Audio Connector の使用は、WebSocket サーバーに送信された参加者（またはストリーム ID）のオーディオストリームの数に基づいて課金されます。に応じて課金されます。Audio Connector 機能は、以下の場合にのみサポートされます。ルーティングされたセッションでのみサポートされます。 OpenTok メディアルーター). 一度に1つのセッションから最大50のオーディオストリームを送信できます。

注： WebSocketサーバーへの接続が6秒以内に確立されない場合、Connect APIの呼び出しは失敗します。

このページには以下のセクションがあります：

WebSocket接続の開始
WebSocketメッセージ
WebSocket接続の停止
自動再接続
WebSocket経由でセッションにオーディオを公開する
サンプルアプリケーション

WebSocket接続の開始

Audio Connector WebSocket 接続を開始するには OpenTok REST API.

また、OpenTokサーバーSDKを使用して、Audio ConnectorのWebSocket接続を開始することもできます：

Java OpenTok.connectAudioStream() メソッドを使用する。
ノード opentok.websocketConnect() メソッドを使用する。
PHP OpenTok->connectAudio()] メソッド。
Python opentok.connect_audio_to_websocket() メソッドを使用する。
ルビー opentok.websocket.connect() 方法
.NET OpenTok.StartBroadcast() 方法

詳しくは Audio Connector REST API ドキュメント.

カスタムヘッダ（HTTPおよびWebSocket）

RESTまたはサーバーSDK経由でWebSocket接続を開始すると、WebSocketにアップグレードするためのHTTP接続要求がWebSocketに送信されます。接続リクエストをWebSocketにアップグレードするために、WebSocketサーバーに送信されます。サーバーに送信されます。

最初のHTTPアップグレードの間、WebSocketサーバーへのHTTPリクエスト・ヘッダには以下が含まれます：

x-opentok-ws-conferenceid:会議 ID を設定します；
x-opentok-ws-connectionid:接続IDを設定する；
x-opentok-ws-sessionid:セッションIDを設定する。

さらに headers これらのヘッダーは、接続のフェーズによって動作が異なります。これらのヘッダーは、接続のフェーズによって動作が異なります：

最初のHTTPアップグレードの間： 提供されたヘッダーはすべて、HTTPリクエスト・ヘッダーとしてWebSocketサーバーに送信されます。
WebSocketが確立された後： ヘッダーはテキストベースの WebSocket コントロールメッセージにテキストブロックとして含まれます。これには以下が含まれます：
- 最初の websocket:connected というメッセージを送った；
- について websocket:media:update メッセージ（オーディオがアクティブまたは非アクティブになったとき）；
- について websocket:cleared というメッセージを送った；
- について websocket:notify というメッセージを送った；
- 最後の websocket:disconnected というメッセージを送った。
ヘッダー・キーは以下の通り。 正規化 を従来のHTTPヘッダーのケーシングに置き換えた、 X-CUSTOM-HEADER になる。 X-Custom-Header).ヘッダーキーは大文字小文字を区別して扱わない。
例外だ： バッファクリア確認 ({"event":"websocket:cleared"})はカスタムヘッダを含みません。これはAudioConnectorの次のリリースで修正する予定です。
バイナリオーディオフレーム： これらはオーディオデータのみを含み、ヘッダーは含まない。
特別な取り扱い x-opentok-ws* ヘッダである： ヘッダキーの先頭に x-opentok-ws はHTTPハンドシェイクでのみ使用され、テキスト・メッセージでエコーされるJSONペイロードからは削除される。

について CUSTOM-HEADER-* 以下のメッセージ例に示されているプロパティは headers プロパティは、接続開始時に提供される。

カスタムヘッダーは512バイトに制限されています。 headers ウェブソケット・オブジェクト。シリアライズされたサイズが512バイトを超えると、接続リクエストは失敗します。

WebSocketメッセージ

最初のメッセージ

確立されたWebSocket接続で送信される最初のメッセージは、テキストベースでJSONペイロードを含み、それには event フィールドを websocket:connectedのオーディオ・フォーマットの詳細が表示されます。 content-type に入れた他のメタデータと一緒に。 headers プロパティを使用します。その headers プロパティはメッセージの JSON ペイロードには存在しないため、プロパティは JSON のトップ・レベルにあります。例えば

{
    "content-type":"audio/l16;rate=16000",
    "event": "websocket:connected",
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

オーディオ・メッセージのフォーマット

デフォルトでは、Audio ConnectorはWebSocket上で生のバイナリPCM 16ビットフレームとしてオーディオを送受信します。一部のAIベンダー（例えば、OpenAI Realtime API）は、base64エンコーディングでJSONメッセージ内にラップされたオーディオを期待します。オーディオを再フレーム化するためにプロキシを実行する代わりに audioTransport 財産での websocket オブジェクトを作成します。オーディオコネクタの開始.

トランスポート・コンフィギュレーション・フォーマット

について audioTransport valueは、以下のフィールドを持つJSONオブジェクトである：

Field	Required	Description
`transport`	Yes	`"binary"` (raw PCM16 — the default) or `"json"`.
`encoding`	When `transport` is `"json"`	`"base64"`. The encoding used for the audio payload inside the JSON message.
`audio_field`	No	The JSON key that holds the outbound audio data. Defaults to `"audio"`.
`receive_audio_field`	No	The JSON key for inbound audio data (when bidirectional is enabled). Defaults to the same value as `audio_field`.
`static_fields`	No	An object of extra key-value pairs included in every outbound JSON audio message.

例Base64エンコーディングによるJSONトランスポート

以下の通りである。 audioTransport 設定は、JSONメッセージの中にbase64としてアウトバウンドオーディオをラップし、静的な type フィールドをすべてのメッセージに追加します - OpenAI Realtime API が期待するフォーマットと一致します：

{
  "transport": "json",
  "encoding": "base64",
  "audio_field": "audio",
  "static_fields": {
    "type": "input_audio_buffer.append"
  }
}

各アウトバウンドWebSocketメッセージは次のようになる：

{
  "type": "input_audio_buffer.append",
  "audio": "<base64-encoded PCM16 audio>"
}

いつ bidirectional は trueを使用して、Audio Connector は受信 JSON メッセージも読み取ります。 receive_audio_field キー（または audio_field もし receive_audio_field が設定されていない場合）、セッションで再生するためにbase64オーディオをデコードする。

例デフォルトのバイナリ・トランスポート

省略した場合 audioTransport (または transport への "binary")、オーディオは設定されたリニアPCM 16ビットで送受信されます。 audioRate.各メッセージには20msのオーディオフレームが1つ含まれているため、フレームサイズは次のように変化します。 audioRate:8kHzで320バイト、16kHzで640バイト、24kHzで960バイト。もし audioRate を省略した場合、デフォルトのバイナリートランスポートは16kHzのオーディオを640バイトのフレームで使用します。

オーディオ・アクティブ/インアクティブ・メッセージ

WebSocketに含まれるストリームの音声がミュートされると、以下のJSONペイロードを持つテキストメッセージが送信されます。以下のJSONペイロードでテキスト・メッセージが送信されます。 active に設定する。 false):

{
    "content-type":"audio/l16;rate=16000",
    "method": "update",
    "event": "websocket:media:update",
    "active": false,
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

(その CUSTOM-HEADER この例では、プロパティはメタデータを表します。メタデータを表します。 headers プロパティを使用する)。接続を開始します)。

オーディオがミュートされるのは、すべてのクライアントがオーディオのパブリッシュを停止したため、または次のような理由が考えられます。強制ミュートイベントを開催する。

いずれかのストリームの音声が再開されると、以下のJSONペイロードを持つテキストメッセージが送信される。以下のJSONペイロードでテキストメッセージが送信される active に設定する。 true):

{
    "content-type":"audio/l16;rate=16000",
    "method": "update",
    "event": "websocket:media:update",
    "active": true,
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

イベントメッセージのストリーム配信

パブリッシャーがセッションに接続すると、テキストメッセージが以下の JSON ペイロード( method に設定する。 created):

{
    "content-type": "audio/l16;rate=16000",
    "method": "created",
    "event": "websocket:stream:created",
    "info": {
        "projectId": "100",
        "sessionId": "1_MX4xMDB-fjE3NzA3NDAzMzIzMjh-ZXkvR1d6YjZoZHlkcHlySFRuNmtlTFZMfn5-",
        "stream": {
            "id": "c4ed69a1-b9a1-44a9-bbc5-edfcf099d772",
            "connection": {
                "id": "33f8c459-a18a-4a81-b1e4-b7d1bdbbc323"
            }
        }
    },
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

(その CUSTOM-HEADER この例では、プロパティはメタデータを表します。メタデータを表します。 headers プロパティを使用する)。接続を開始します)。

ストリームがセッションから切断すると、テキスト・メッセージが以下の JSON ペイロード ( method に設定する。 destroyed):

{
    "content-type": "audio/l16;rate=16000",
    "method": "destroyed",
    "event": "websocket:stream:destroyed",
    "info": {
        "projectId": "100",
        "sessionId": "1_MX4xMDB-fjE3NzA3NDAzMzIzMjh-ZXkvR1d6YjZoZHlkcHlySFRuNmtlTFZMfn5-",
        "stream": {
            "id": "c4ed69a1-b9a1-44a9-bbc5-edfcf099d772",
            "connection": {
                "id": "33f8c459-a18a-4a81-b1e4-b7d1bdbbc323"
            }
        }
    },
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

バッファのフラッシュ (CLEAR) メッセージ

WebSocketサーバはオプションでテキストベースの制御メッセージを送信し、Audio Connectorに現在バッファされているがまだ配信されていないオーディオフレームを直ちに破棄するよう指示することができます。これは、割り込み、TTS再生の中断、会話ターンのリセットなど、リアルタイムで使用する場合に便利です。

バッファリングされたオーディオをフラッシュするには、以下のJSONメッセージをWebSocketで送信します：

{
    "action": "CLEAR"
}

Audio Connectorがこのメッセージを受信すると、保留中のバッファリングされたオーディオフレームはすべて破棄され、新しい着信オーディオは中断されることなくストリーミングを続け、確認メッセージが返されます：

{
    "event": "websocket:cleared"
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

このコントロール・メッセージはオプションである。もし "action": "CLEAR"オーディオストリーミングは正常に進行する。

通知（NOTIFY）メッセージ

WebSocketサーバーは、オプションでテキストベースの制御メッセージ(NOTIFY).オーディオコネクタは、メッセージがオーディオストリームと順番に処理されると、元のペイロードを変更せずにエコーバックします。これは、アプリケーションイベントとオーディオフローを関連付けるマーカーとして使用できます。

を送信する。 NOTIFY イベントで、以下のJSONメッセージをWebSocket経由で送信する：

{
    "action": "NOTIFY",
    "payload": "some info"
}

メッセージが受信されると、オーディオキューの最後に置かれます。オーディオが消費された後、Audio Connectorがこのメッセージを処理すると、確認メッセージがWebSocketサーバに送信されます：

{
    "event": "websocket:notify",
    "payload": "some info",
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

このコントロール・メッセージはオプションである。もし "action": "NOTIFY"オーディオストリーミングは正常に進行する。

切断メッセージ

Audio Connector WebSocketが強制切断RESTメソッドまたはに達したからである。 WebSocket接続の停止), テキスト・メッセージは、以下のJSONペイロードで送信される：

{
    "content-type":"audio/l16;rate=16000",
    "method": "delete",
    "event": "websocket:disconnected",
    "CUSTOM-HEADER-1": "value-1",
    "CUSTOM-HEADER-2": "value-2"
}

このメッセージはWebSocket接続の終了を示す。

(その CUSTOM-HEADER この例では、プロパティはメタデータを表します。メタデータを表します。 headers プロパティを使用する)。接続を開始します)。

WebSocket接続の停止

WebSocketサーバーが接続を切断すると、その通話に関するOpenTokの接続も終了します。セッションに接続している各クライアントにおいて、OpenTokのクライアント側SDKは、接続が終了したことを示すイベントをディスパッチします（他のクライアントがセッションから切断された場合と同様です）。

Audio Connector WebSocket 接続を切断するには強制切断RESTメソッド.このメソッドで Audio Connector WebSocket 接続の接続 ID を使用する。

セキュリティ対策として、WebSocketは6時間後に自動的に閉じられます。

自動再接続

Audio Connector は、WebSocket 接続の再確立を数回試みます。を呼び出すことなくWebSocketがクローズした場合など）。への呼び出しから強制切断RESTメソッド).

WebSocket経由でセッションにオーディオをパブリッシュする

Audio ConnectorのWebSocket接続を使用すると、（WebSocket接続でセッションから音声を受信することに加え）WebSocket接続からOpenTokセッションで公開されているストリームへ音声データを送信することができます。以下の設定を行ってください。 bidirectional プロパティ true に REST API メソッドで送信するデータの中にある。オーディオコネクタの開始.

参照オーディオメッセージのフォーマット WebSocket接続で送信するオーディオデータのフォーマットの詳細については、こちらをご覧ください。

Audio Connectorが使用するトークンを作成する際に、トークン data Audio Connectorストリームを特定するため。（OpenTokクライアントライブラリには、セッション内のストリームの接続に関する接続データを検査するためのメソッドが含まれています。）

注：について bidirectional このオプションはREST APIでのみ利用可能です。現在、OpenTokサーバーSDKではサポートされていません。

サンプルアプリケーション

参照デモ動画 - ノード・オーディオ・コネクタ Audio Connector を使用する Node アプリケーションのサンプルプロジェクト。

詳細情報

こちらをご覧くださいブログ記事.