ビデオコネクター

Vonage Video Connector を使用すると、サーバーサイドの参加者として、Vonage Video API セッションにプログラム経由で参加することができます。 これにより、ビデオセッションへの接続、ストリームの公開および購読、 ならびにリアルタイムの音声・映像データの処理が可能になります。

このライブラリは、WebRTC接続、メディア処理、セッション管理を自動的に処理するため、アプリケーション・ロジックの構築に集中できます。 アプリケーションロジックの構築に集中できます。オーディオはリニアPCM 16ビット・データとして、ビデオはYUV420P、RGB24、ARGB32フォーマットの8ビット・フレームとして配信されます。 YUV420P、RGB24、またはARGB32フォーマットで、すべて設定可能なサンプル・レート、解像度、チャンネル構成で配信されます。

このページでは、すべての Video Connector ライブラリに共通する Concepts と動作について説明します。インストール 手順、API シグネチャ、およびコードサンプルについては、お使いの言語に対応したガイドを参照してください。

図書館をお選びください

どちらのライブラリも同様の機能を提供しており、同じネイティブ実装に基づいています。両者の違いは、 命名規則と、非同期操作の提供方法にあります。Pythonライブラリは完了コールバックを使用するのに対し、 Node.jsライブラリはプロミスを返します。これらの違いについては、言語ガイドに詳しく説明されています。

このトピックには以下のセクションが含まれます：

• 仕組み
• 必要条件
• 基本概念
• メディア形式
• セッションの設定
• 出版メディア
• ストリームの購読
• メディア・バッファ管理
• イベントモデル
• 制限

仕組み

Video Connectorは、通常のWebRTC参加者としてセッションに参加します。他の 参加者から見ると、ブラウザやモバイルクライアントと何ら変わりません。つまり、独自の接続を持ち、 ストリームを配信できるほか、他の参加者のストリームを購読することも可能です。

異なる点は、カメラやマイク、 あるいは画面ではなく、アプリケーションコードとメディアをやり取りする点です。生のオーディオおよびビデオフレームをコネクタにプッシュして公開し、サブスクライブしたストリームから生のオーディオ およびビデオを受け取ります。これにより、このコネクタは次のようなサーバーサイドのワークロードに適しています：

• リアルタイム音声・映像AIエージェント
• リアルタイム文字起こし、翻訳、字幕表示
• 記録、アーカイブ、およびコンプライアンス対応のためのデータ収集
• コンピュータビジョンとコンテンツのモデレーション
• オーディオとビデオのエフェクト処理

一般的なライフサイクルは以下の通りです：

1. アプリケーション ID、セッション ID、およびトークンを使用して、セッションに接続します。
2. ストリームを公開し、そのストリームにオーディオおよび／またはビデオのフレームを送信します。
3. 他の参加者からのストリームが到着次第、それらを購読し、受信したメディアを処理します。
4. 作業が終わったら、購読を解除し、公開を取りやめ、接続を切断してください。

必要条件

Video Connector は、あらかじめコンパイル済みのバイナリを含むネイティブライブラリとして提供されます。これは以下の環境で動作します。 x86_64 (AMD64) 上の Linux および ARM64 だけである。

コネクタのテストが最も徹底的に行われているディストリビューションであるため、Debian Bookwormをお勧めします。

基本概念

Video Connector では、セッション、参加者、ストリーム、メディアを表すために、少数のオブジェクトが使用されています。 これらのオブジェクトを理解することは、どちらのライブラリも効果的に活用するために不可欠です。

セッション

クライアントが接続するVonage Video APIのセッションです。このセッションはIDによって識別され、 セッションレベルのイベントハンドラに渡されるため、どのセッションがイベントをトリガーしたかを特定することができます。

接続

セッションに対する参加者の接続。コネクタ自体を含め、すべての参加者は、 正確に1つの接続を持っています。接続には以下の情報が含まれます：

• 一意の識別子
• 作成日時
• 接続に使用されるトークンにエンコードされている接続データ

接続データは、ユーザーIDや役割など、参加者に関するカスタムメタデータを保存するのに役立ちます。

ストリーム

参加者が公開するメディアストリーム（音声、動画、またはその両方）。ストリームには一意の識別子と、 それを公開した接続への参照情報が含まれます。参加者が公開を開始すると、そのストリームがあなたに通知され、 メディアを受信するためには、このストリームを購読する必要があります。

出版社

セッション内で自身が公開したストリームです。コネクタインスタンスごとに、パブリッシャーは最大1つです。パブリッシャーは 自身が作成したストリームへの参照を保持しており、他の参加者はこのストリームを通じてあなたを認識します。

購読者

別の参加者のストリームへのサブスクリプションです。メディアの受信を希望するストリームごとに1つのサブスクライバーを作成し、 各サブスクライバーは、サブスクライブしているストリームへの参照を保持します。メディアおよびキャプションのイベントは、 それらを生成したサブスクライバーとともに配信されるため、データがどの参加者から送信されたかを判別できます。

それらの関係性

Session
├── Connection (multiple participants)
│   └── Stream (participant's published media)
│       ├── Publisher (your published stream)
│       └── Subscriber (your subscription to their stream)
├── Audio data (flowing through streams)
└── Video frames (flowing through streams)

メディア形式

オーディオ

音声は常に次のようにやり取りされます。 リニアPCM、16ビット符号付き整数. オーディオフレームはチャンネルあたり1サンプルであるため、 バッファには少なくとも（フレーム数 × チャンネル数）サンプル分を格納できる必要があります。

• サンプルレート8000、12000、16000、24000、32000、44100、または48000 Hz
• チャンネル:1（モノラル）または2（ステレオ）
• フレームサイズ: 通常は20ミリ秒単位ですが、サンプルレートによって異なります

配信するオーディオと受信するミックス済みオーディオについて、サンプリングレートとチャンネル数はそれぞれ個別に設定可能です。 詳しくは、 セッションの設定.

ビデオ

動画は次のようにやり取りされます 8ビットの符号なし値 次の3つのピクセル形式のいずれかで：

• 決議: 最大1920×1080（合計2,073,600ピクセル）
• フレームレート: 1～30 FPS

セッションの設定

配信用と購読用の音声の違い

このコネクタを使用すると、2つの独立したオーディオフォーマットを設定できます：

• パブリッシャーの音声 公開時に提供するオーディオデータの形式を定義します。送信するオーディオは、 このサンプリングレートおよびチャンネル数と一致している必要があります。
• 加入者構成の音声 購読しているすべてのストリームから受信するミックス音声のフォーマットを定義します。この ライブラリは、複数の参加者の音声をミックスする処理や、指定されたフォーマットに合わせてリサンプリングやチャンネル変換を行う処理を処理します。

この分離により、ユースケースに合わせて最適化を行うことができます。例えば：

• ステレオで公開して高品質な出力を確保しつつ、モノラルミックスを受け取ることで処理を簡素化
• 音声の送信には16 kHzを使用し、高音質再生のための受信には48 kHzを使用する
• オーディオ処理パイプラインの要件に合わせて、左右のチャンネルで異なるレートを使用する

推奨される加入者の解像度とフレームレート

シムキャストを使用するルーティングされたストリームを購読する場合、Vonage Video APIのSFU（Selective Forwarding Unit）は、 異なる品質レベルの動画を配信することができます。加入者設定により、特定の品質レベルをリクエストすることが可能です：

• 望ましい解像度 空間レイヤーを要求します。SFUは、最も一致するレイヤーを送信します。
• 希望フレームレート 一時レイヤーを要求します。SFUは、最も一致するレイヤーを送信します。

これらの設定により、利用可能な最高品質を常に受信するのではなく、必要な品質 レベルのみを要求することで、加入者側の帯域幅と処理能力を最適化することができます。

セッション移行

セッション移行を有効にすると、SFUのローテーションが発生した際にコネクタが自動的に移行するようになります。 デフォルトでは無効になっています。

ログ記録

コンソールのログ出力レベルは、以下の5段階から設定可能です： ERROR, WARN, INFO, DEBUGそして TRACE.

出版メディア

パブリッシャーは、オーディオ、ビデオ、またはその両方を公開する必要があります。いずれも設定されていないパブリッシャーを設定すると、エラーとなります。

音声の準備完了を待機中

音声の連続性

オーディオを公開すると、ライブラリがユーザーに代わって連続したストリームを維持します：

初版。 このライブラリは、ユーザーが最初のオーディオデータを送信するまで、無音（ゼロで埋められたフレーム）を送信し続けます。 これにより、アプリケーションがオーディオを生成するのを待つことなく、サブスクライバーはすぐにストリームを利用できるようになります。

沈黙への寛容。 音声の配信を一時的に停止した場合、ライブラリは音声パケットを一切送信しないことで、 短い間隙を許容します。このヒステリシス機能により、一時的な処理遅延が発生した際にも、不要な無音パケットが送信されるのを防ぎます。

明示的な沈黙。 許容期間が経過した後、新しいオーディオが利用できない場合、ライブラリは 明示的な無音フレームの送信に切り替わります。これにより、アクティブなオーディオが提供されていないことを示しつつ、ストリームを維持することができます。

バッファのフラッシュ。 1期間分のオーディオデータに満たないデータを提供した場合、ライブラリは残りのデータを破棄し、 正しいタイミングを維持し、オーディオのずれを防ぐために、無音で埋め合わせを行います。

動画の連続性

動画を公開すると、ライブラリが自動的にフレームの連続性を維持します：

初版。 このライブラリは、最初のフレームが送信されるまでブラックフレームを送信し続けるため、 サブスクライバーはすぐにストリームを利用できるようになります。

最後のフレームの繰り返し。 フレームの提供を停止した場合、ライブラリは最後に提供されたフレームを最大 2秒間繰り返し再生し、加入者への再生をスムーズな状態に保ちます。

黒い枠の代替表示。 2秒間繰り返し再生された後、ライブラリはブラックフレームに切り替わります。これにより、 ストリームを維持したまま、動画の配信が停止していることを購読者に知らせます。

ベストプラクティス

• 設定したサンプリングレートおよびフレームレートに合わせて、一定の間隔でメディアを送信してください
• バッファの統計情報を監視し、十分なデータが供給されていることを確認してください
• メディアバッファが枯渇したタイミングを検知するために、バッファ枯渇イベントを処理します
• 処理負荷の変動に応じて、メディア生成戦略を調整する

ストリームの購読

参加者が配信を開始すると、ストリーム受信イベントが発生し、その際にサブスクライブするかどうかを決定します。サブスクライブした メディアは、3つの別々のチャネルを通じて配信されます。

ビデオ はストリームごとに配信されます。各フレームにはその送信元を特定するサブスクライバー情報が含まれているため、 各参加者の動画を個別に処理することができます。これにより、レイアウト管理、ストリームごとの録画、あるいはストリームごとの エフェクト処理などが可能です。

音声の混在 セッションレベルで単一のストリームとして配信されます。このライブラリは、 サブスクライブされたすべてのストリームからのオーディオを、サブスクライバーミックス用に設定した形式で自動的に1つのストリームにミックスします。このミックスされたオーディオでは、個々の 参加者を区別することはできません。

個別の音声 は、ストリームごとに、加入者レベルで配信されます。オーディオは、ストリームから受信した形式（リニアPCM 16ビット）のまま到着し、 サンプリングレートもチャンネル数も、受信前に設定することはできません。

キャプション はストリームごとに配信されます。各キャプション イベントには、ソースストリームを特定するサブスクライバー、キャプションテキスト、および結果が最終的なものか 暫定的なものかが含まれます：

• 中間 結果は暫定的なものであり、より多くの音声が処理されるにつれて更新される可能性があります。ライブ表示に役立ちます。
• 決勝 結果は確定しており、今後変更されることはありません。保存や後続の処理にこれらをご利用ください。

メディア・バッファ管理

このコネクタは、公開する音声および動画用の内部バッファを保持しています。キューに格納されているメディアの量を いつでも確認でき、保留中のメディアを破棄する必要がある場合（たとえば、 ボットの発話途中で中断する場合など）には、両方のバッファをクリアすることができます。

バッファの排出イベント

バッファ枯渇イベントは、内部のオーディオまたはビデオバッファが枯渇したときに発生します。これは、メディアが アプリケーションによる供給速度よりも速いペースでセッションに送信された場合に発生します。このイベントを、 メディアの生成レートを上げるか、配信戦略を調整すべきというシグナルとして扱ってください。

このイベントは、過度なトリガー発生を防ぐためにヒステリシスを実装しています。最初のデータ排出後、バッファが新しいメディアで補充され、その後再び空になるまでは、再度トリガーされることはありません。これにより、バッファが空の状態で 通知が繰り返し大量に送信されるのを防ぎます。

イベントモデル

どちらのライブラリも、所属するオブジェクトごとにグループ化された、同じ一連のイベントを提供しています。

これらのイベントがどのように通知されるかは、言語によって異なります。Python では、すべてのイベントは登録したコールバックとして扱われます。 Node.js では、セッションの接続、パブリッシャー・ストリームの作成、サブスクライバーの接続といった 1 回限りのライフサイクルイベントは、 対応するメソッドから返される Promise によって処理され、それ以外のイベントはコールバックとして扱われます。 詳細については、各言語のガイドを参照してください。

制限