オーディオ・コネクター

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

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

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

Audio Connectorを使用して、WebSocket接続を以下のように使用することもできます。オーディオをセッションに公開する.

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

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

WebSocket接続の開始

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

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

Java vonage.video.connectToWebsocket() メソッドを使用する。
ノード vonage.video.connectToWebsocket() メソッドを使用する。
PHP vonage->video->connectAudio() メソッドを使用する。
Python vonage.video.start_audio_connector() メソッドを使用する。
ルビー vonage.video.web_socket.connect() 方法
.NET vonage.video.Broadcast.StartBroadcast() 方法

以下のURLにHTTPS POSTリクエストを行う：

https://video.api.vonage.com/v2/project/:application_id/connect

交換 application_id を添えてお申し込みください。

OAuth2.0生成の非対話型メソッドを使用して、JWT構造と秘密鍵を使用してベアラ・トークンを作成します。詳細については REST APIコールの認証.

リクエストのボディに以下の形式のJSONデータを設定する：

{
  "sessionId": "session ID",
  "token": "A valid token",
  "websocket": {
    "uri": "wss://service.com/ws-endpoint",
    "streams": [
      "streamId-1",
      "streamId-2"
    ],
    "headers": {
      "headerKey": "headerValue"
    },
    "audioRate": 8000,
    "bidirectional": false
  }
}

JSONオブジェクトには以下のプロパティが含まれる：

sessionId (必須) - WebSocketストリームに含めたいストリームを含むセッションID。を含むセッション ID。
token (必須) - セッションへの Audio Connector 接続に使用される Vonage ビデオトークン。セッションへのオーディオコネクタ接続に使用するトークン data 接続が Audio Connector エンドポイントであることを識別するため、またはその他の識別データのために(クライアントライブラリには、セッションに接続されたクライアントの接続データを検査するためのプロパティが含まれています)。詳細はトークン作成開発者ガイド
websocket 必須）：WebSocketに含まれる詳細：
- uri 必須）：(必須): 音声ストリームの送信先として使用する、一般に到達可能な WebSocket URI。 (必須): オーディオストリームの送信先として使用される、一般に到達可能な WebSocket URI (例: "wss://service.com/ws-endpoint")。
- streams (オプション) - WebSocketストリームに含めたいストリームのストリームIDの配列。ストリーム ID の配列。このプロパティを省略すると、セッション内のすべてのストリームのすべてのストリームが含まれます。
- headers (オプション) - 各メッセージで Web ソケット・サーバーに送信されるヘッダーのキーと値のペアのオブジェクト。最大長は 512 バイトです。
- audioRate (オプション) - オーディオ・サンプリング・レート（Hz）を表す数値。使用可能な値は8000、16000（デフォルト）、24000です。

呼び出しに成功すると、HTTP 200レスポンスが返され、その詳細がJSONレスポンス・データに含まれる：

{
  "id": "b0a5a8c7-dc38-459f-a48d-a7f2008da853",
  "connectionId": "e9f8c166-6c67-440d-994a-04fb6dfed007"
}

JSONレスポンス・データには、以下のプロパティが含まれる：

id - Audio Connector WebSocket 接続を識別する一意の ID。
connectionId - セッション内の Audio Connector WebSocket 接続の接続 ID のコネクションID。

詳しくは 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 というメッセージを送った。
- 最初の websocket:connected メッセージ
- websocket:media:update メッセージ（オーディオがアクティブまたは非アクティブになったとき）
- 最後の 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"
}

バイナリ音声メッセージ

バイナリ・メッセージは通話の音声を表す。WebSocketインターフェイスでサポートされているオーディオコーデックは、リニアPCM 16ビットで、サンプルレートは16kHzです。各メッセージには、1秒間に50フレーム（メッセージ）の640バイトのデータ（20msのオーディオ）が1フレーム含まれます。

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

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 サーバーが接続を閉じると、通話用の Vonage ビデオ接続も終了します。セッションに接続されている各クライアントでは、クライアント側 SDK が接続の終了を示すイベントをディスパッチします。をディスパッチします。

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

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

自動再接続

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

WebSocket経由でセッションにオーディオを公開する

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

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

Audio Connectorが使用するトークンを作成する際に、トークン data を使用して Audio Connector ストリームを識別します。(Vonageクライアントライブラリには、セッション中のストリームの接続データを検査するメソッドが含まれています)。

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

参照双方向オーディオコネクタプロジェクトで双方向オーディオコネクタを使用するサンプルNodeアプリケーションをご覧ください。

ナビゲーション

オーディオ・コネクター

WebSocket接続の開始

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

WebSocketメッセージ

最初のメッセージ

バイナリ音声メッセージ

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

ストリーム・イベント・メッセージ

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

通知（NOTIFY）メッセージ

切断メッセージ

WebSocket接続の停止

自動再接続

WebSocket経由でセッションにオーディオを公開する

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