JavaサーバーSDK

Vonage Java SDKは以下のメソッドを提供します：

インストール

Video APIは2023年にSDKのバージョン8.0.0で追加されましたが、セキュリティ、バグフィックス、後のリリースで追加された機能のために最新バージョンを使用することをお勧めします。

メイブン・セントラル

プロジェクトにVonage Java Server SDKを追加する最善の方法は、プロジェクトのビルドシステムに依存関係を追加することです。手順は GitHubリポジトリのみならずメイブン・セントラル Maven、Gradle、Ivy、SBT、Leiningenなど。

メイブン

ビルドツールとしてMavenを使用する場合、依存関係を pom.xml ファイル：

グラドル

ビルドツールとして Gradle を使用する場合、依存関係は build.gradle ファイル：

使用方法

Vonage Java SDKを使用すると、次のことが可能になります。 Vonage REST API 各APIに1つずつサブクライアントが用意されている。サブクライアントで Video APIを使用する。 com.vonage.client.video.VideoClient クラスのメソッドです。このクラスには、API仕様でサポートされているすべてのエンドポイントのメソッドが含まれています。これは getVideoClient() 方法 VonageClient.

初期化

を初期化する。 com.vonage.client.VonageClient オブジェクトに、動画アプリケーション ID とプライベート・キーを渡します。これは、Video API を使用するために必要なすべてのメソッドを含むオブジェクトを返します。

import com.vonage.client.VonageClient;
import com.vonage.client.video.*;

// Inside a class or method...
VideoClient videoClient = VonageClient.builder()
    .applicationId("APP_ID")
    .privateKeyPath("/path/to/private.key")
    .build().getVideoClient();

トークンの生成

Vonage Videoアプリケーションを有効にするには、クライアント側にトークンが必要です。このトークンは、サーバSDKの VideoClient#generateToken(String sessionId, TokenOptions options) メソッドを使用します。セッションIDを渡す必要がありますが options パラメータは必須ではありません（NULLでもかまいません。 VideoClient#generateToken(String sessionId) 便宜上)。このメソッドは、適切なクレームを含む署名付きJWTを、クライアントに渡すことができるBase64エンコードされた文字列として返します。

String jwt = videoClient.generateToken(sessionId);

デフォルトでは、トークンの有効期限は24時間で、ロールは "publisher "に設定されます(com.vonage.video.client.Role#PUBLISHER).最大有効期限は30日間です。これらの設定は TokenOptions パラメータを使用する。接続メタデータを設定することもできますが、1000文字を超えることはできません。

TokenOptions tokenOptions = TokenOptions.builder()
        .expiryLength(Duration.ofHours(6))
        .role(Role.SUBSCRIBER)
        .build();
String jwt = videoClient.generateToken(sessionId, tokenOptions);

参照トークン作成ガイドコンフィギュレーション・オプションの詳細については、こちらをご覧ください。

セッションの作成

Vonageビデオセッションを作成するには VideoClient#createSession(CreateSessionRequest request) メソッドを使用する。その request パラメータはオプションで、指定するために使用する：

セッションがVonage Video Media Routerを使用しているかどうか
Vonage Videoサーバーのロケーションヒント。
セッションを自動的にアーカイブするかどうか。

他のほとんどのリクエストプロパティと同様に、ビルダーパターンを使用します。インスタンス化するには、まず静的な builder() メソッドでプロパティを設定し build() でインスタンスを構築する。

リクエストが成功した場合 CreateSessionResponse が返される。最も有用なプロパティはセッションIDである。 getSessionId() メソッドを呼び出します。セッションIDは他のメソッド呼び出しの共通パラメータなので、将来使用するために永続化したいと思うかもしれません。

// A session that attempts to stream media directly between clients:
CreateSessionResponse session = videoClient.createSession();

// A session that uses the Vonage Video Media Router:
CreateSessionResponse session = videoClient.createSession(
    CreateSessionRequest.builder().mediaMode(MediaMode.ROUTED).build()
);

// A Session with a location hint:
CreateSessionResponse session = videoClient.createSession(
    CreateSessionRequest.builder().location("12.34.56.78").build()
);

// A session that is automatically archived (it must be used for the routed media mode)
CreateSessionResponse session = videoClient.createSession(
    CreateSessionRequest.builder()
      .mediaMode(MediaMode.ROUTED)
      .archiveMode(ArchiveMode.ALWAYS)
      .build()
);

// Store this sessionId in the database for later use:
String sessionId = session.getSessionId();

アーカイブとの取り組み

アーカイブできるのは、Vonage Video Media Routerを使用するセッションのみです。 MediaMode.ROUTED). アーカイブの詳細については Vonage ビデオ・アーカイブ開発者ガイド

アーカイブの作成

を使用して、Vonage ビデオセッションの録画を手動で開始できます。 createArchive(Archive request) メソッドを呼び出します。成功すれば、これは com.vonage.client.video.Archive インスタンスをサーバーのレスポンスで返します。

アーカイブを開始できるのは、クライアントが接続しているセッションのみです。アーカイブは Archive リクエストはビルダーパターンに従って構築される。セッションID以外のすべてのプロパティはオプションです。 Archive.builder(String sessionId) メソッドはこのパラメーターを必要とする。

// A simple Archive with the default property values
Archive archive = videoClient.createArchive(Archive.builder(sessionId).build());

// Store this archiveId in the database for later use
UUID archiveId = archive.getId();

を呼び出して、音声またはビデオ録画を無効にすることもできます。 hasAudio(false) または hasVideo(false) メソッド Archive ビルダー

// Audio-only archive
Archive.builder(sessionId).hasVideo(false).hasAudio(true).build();

出力モードを OutputMode.INDIVIDUAL は、アーカイブ内の各ストリームを個別のファイルに記録する：

Archive.builder(sessionId).outputMode(OutputMode.INDIVIDUAL).name("My recording").build();

について OutputMode.COMPOSED オプションのデフォルト値は outputMode.録画されるすべてのストリームを1つの（構成された）ファイルにアーカイブする。

指定できるのは resolution を設定する必要があります。もし resolution プロパティを設定し outputMode プロパティ OutputMode.INDIVIDUALその build() メソッドは IllegalStateException.

// Set the archive resolution to 1280x720
Archive.builder(sessionId).resolution(Resolution.HD_LANDSCAPE).build();

録音停止

を使用して、開始したアーカイブの録画を停止することができます。 VideoClient#stopArchive(String archiveId) メソッドを使用する。

// Stop an Archive
Archive archive = videoClient.stopArchive(archiveId);

アーカイブの削除

アーカイブを削除するには VideoClient#deleteArchive(String archiveId) メソッドを使用する。

// Delete an Archive
videoClient.deleteArchive(archiveId);

単一のアーカイブを取得する

個人を獲得するには Archive インスタンス(とそれに関するすべての情報)をアーカイブIDから取得するには VideoClient#getArchive(String archiveId) メソッドを使用する。

// Retrieve archive info
Archive archive = videoClient.getArchive(archiveId);

複数のアーカイブを検索する

を使用すると、アプリケーション内で作成したすべてのアーカイブ（最大1000件）のリストを取得できます。 VideoClient#listArchives() メソッドを呼び出します。返された結果にフィルタをかけるには VideoClient#listArchives(ListArchivesRequest request) メソッドの代わりにリクエストオブジェクトはビルダーパターンを使って構築され、 3つのオプションのパラメータを持つ：

sessionId特定のセッションに関連付けられたアーカイブに結果を限定することができます。
count: 返される結果の数を制限します。
offset: 最初の結果の数を破棄します (アーカイブが 1000 以上ある場合に便利です)。

アン IllegalArgumentException がスローされます。 offset または count が負であるか count は1000より大きい。結果として Archiveになる。日時新しいものから古いものへと順番に。

// Get a list with the first 1000 archives
List<Archive> archives = videoClient.listArchives();

// Get a list of the first 50 archives created
List<Archive> archives = videoClient.listArchives(
    Archive.builder().count(50).build()
);

// Get a list of the next 50 archives
List<Archive> archives = videoClient.listArchives(
    Archive.builder().offset(50).count(50).build()
);

また、特定のセッション ID のアーカイブのリストをフェッチし、オプションで前述のように offset パラメータと count パラメータを使用することもできます。

// Get a list with the first 1000 archives for a specific session
List<Archive> archives = videoClient.listArchives(
    ListStreamCompositionsRequest.builder().sessionId(sessionId).build()
);

// Get a list of the next 1000 archives for a specific session
List<Archive> archives = videoClient.listArchives(
    ListStreamCompositionsRequest.builder()
      .offset(1000)
      .sessionId(sessionId)
      .build()
);

アーカイブレイアウトの設定

構成されたアーカイブの場合、アーカイブのレイアウトを動的に設定することができます。 VideoClient#setArchiveLayout(String archiveId, ArchiveLayout layout) メソッドを使用する。

アーカイブ作成時にレイアウトを設定することもできます ( Archive.Builder#layout(ArchiveLayout layout)).参照構成されたアーカイブのビデオレイアウトをカスタマイズするをご覧ください。

を使用する。 ArchiveProperties ビルダーは次のように述べている：

StreamCompositionLayout layout = StreamCompositionLayout.standardLayout(ScreenLayoutType.VERTICAL);
videoClient.updateArchiveLayout(archiveId, layout);

カスタムレイアウトの場合は、スタイルシート（CSS）を指定する必要があります：

StreamCompositionLayout layout = StreamCompositionLayout.customLayout("stream { position: absolute; }")

また、スクリーン共有時にレイアウトの種類を設定することもできます。 ScreenLayoutType.BEST_FIT:

StreamCompositionLayout layout = StreamCompositionLayout.screenshareLayout(ScreenLayoutType.PIP);

アーカイブにストリームを追加する

で開始した構成済みアーカイブにストリームを追加することができます。 streamMode に設定する。 StreamMode.MANUAL を使用している。 VideoClient#addArchiveStream(String archiveId, String streamId) メソッドに アーカイブID そして ストリームID それぞれアーカイブに追加したい。

について VideoClient#addArchiveStream(String archiveId, String streamId, Boolean audio, Boolean video) このメソッドを使用すると、オーディオとビデオの有効/無効を切り替えることができます。

デフォルトでは、どちらも有効になっている（つまり trueを渡す。 false のために audio パラメータを渡すとオーディオが無効になります。 false をビデオに設定すると、ビデオは無効になる（結果的にオーディオのみのストリームになる）。これらの値のいずれかを null はデフォルト（つまり true どちらの場合も）。

// Add stream to archive
videoClient.addArchiveStream(archiveId, streamId);

// Add stream to archive without audio
videoClient.addArchiveStream(archiveId, streamId, false, true);

// Add stream to archive without video
videoClient.addArchiveStream(archiveId, streamId, true, false);

アーカイブからストリームを削除する

構成されたアーカイブからストリームを削除するには VideoClient#removeArchiveStream(String archiveId, String streamId) メソッドを使用する。ストリームの追加と同様、アーカイブは streamMode manual "に設定する。

videoClient.removeArchiveStream(archiveId, streamId);

ブロードキャストでの作業

ライブ放送を扱うのは、アーカイブを扱うのとよく似ている。

すべてのライブ放送をリストアップ

List<Broadcast> broadcasts = videoClient.listBroadcasts();

特定のブロードキャストの詳細を取得する

Broadcast broadcast = videoClient.getBroadcast(broadcastId);

ライブ・ストリーミング放送の開始

セッションのブロードキャストを正常に開始するには、少なくとも 1 つのクライアントがセッションに接続されている必要があります。ライブ・ストリーミング・ブロードキャストは、1つのセッションに対して、1つのHLSエンドポイントと最大5つのRTMPサーバーを同時にターゲットにすることができます。セッション ID が必要で、少なくとも 1 つの出力ストリーム（RTMP および/または HLS）を指定する必要があります。

Broadcast broadcast = videoClient.createBroadcast(
		Broadcast.builder(sessionId)
            .hls(Hls.builder().lowLatency(true).build())
            .resolution(Resolution.HD_LANDSCAPE)
		    .streamMode(StreamMode.MANUAL)
            .layout(StreamCompositionLayout.builder(ScreenLayoutType.BEST_FIT)
                    .screenshareType(ScreenLayoutType.PIP)
                    .build()
            )
            .maxDuration(Duration.ofMinutes(45))
        .build()
);

放送録画の停止

Broadcast broadcast = videoClient.stopBroadcast(broadcastId);

ライブストリーミング放送のレイアウトタイプを動的に変更する

videoClient.updateBroadcastLayout(broadcastId,
		StreamCompositionLayout.standardLayout(ScreenLayoutType.HORIZONTAL)
);

ライブ・ストリーミング・ブロードキャストにおけるストリームの追加と削除

streamModeを次のように設定して開始したブロードキャストに含まれるストリームを変更する。 SteamMode.MANUAL:

videoClient.addBroadcastStream(broadcastId, streamId);

videoClient.removeBroadcastStream(broadcastId, streamId);

ストリームを使う

ストリームに関する情報は VideoClient#getStream(String sessionId, String streamId) メソッドを使用する。リクエストが成功すると com.vonage.client.video.GetStreamResponse インスタンスが返され、これを使用してストリームに関連するプロパティを問い合わせることができる。

GetStreamResponse stream = videoClient.getStream(sessionId, streamId);

// Stream Properties
VideoType videoType = stream.getVideoType();
String name = stream.getName();
List<String> layoutClassList = stream.layoutClassList();

セッション内のすべてのストリームに関する情報は VideoClient#listStreams(String sessionId) メソッドを呼び出します。これは List の GetStreamResponse インスタンスにアクセスし、探している情報を見つけることができる。

// Get list of streams from a session ID
List<GetStreamResponse> streams = videoClient.listStreams(sessionId);
int count = streams.size();

// Get stream ID for a given stream name
UUID myStreamId = streams.stream()
    .filter(s -> "My Stream".equals(s.getName()))
    .findFirst().ifPresent(GetStreamResponse::getId)
    .orElseThrow(() -> new IllegalStateException(
          "Could not find stream in session "+sessionId
    ));

ストリームレイアウトの設定

ストリームのレイアウト・クラスは VideoClient#setStreamLayout(String sessionId, List<SessionStream> streams) メソッドを使用する。このメソッドは、セッションIDと、変更するストリームのリストを入力とする。各ストリームは SessionStream このオブジェクトは builder パターンを使って構築され、ストリーム ID がストリームの識別に使われます (これは必須のパラメータです)。このオブジェクトは SessionStream.Builder#layoutClassList(List<String> layoutClassList) メソッドを使用して、ストリームのレイアウトを設定します（便宜上、varargsのバリアントも使用できます）。デモンストレーションのために、2つのストリームがあるとします。 stream1 そして stream2. 仮定 stream1Id そして stream2Id のIDを持つ文字列である。 stream1 そして stream2 を設定したい。 stream1レイアウトクラスを full そして focusしかし stream2への min.

その方法を紹介しよう：

SessionStream
    stream1 = SessionStream.builder(stream1Id)
        .layoutClassList("full", "focus").build(),
    stream2 = SessionStream.builder(stream2Id)
        .layoutClassList("min").build();

videoClient.setStreamLayout(sessionId, stream1, stream2);

モデレーション

クライアントの切断

アプリケーションサーバーは、Vonage Video セッションからクライアントを切断するために VideoClient#forceDisconnect(String sessionId, String connectionId) メソッドを使用する。

videoClient.forceDisconnect(sessionId, connectionId);

について connectionId パラメータは、セッションに接続しているクライアントのコネクションIDを指定するために使用される。

強制切断機能と例外コードの詳細については REST API ドキュメント.

セッション内のクライアントに公開音声のミュートを強制する

を使って、特定のストリームのパブリッシャーにオーディオのパブリッシングを停止させることができます。 VideoClient#muteStream(String sessionId, String streamId) メソッドを使用する。

videoClient.muteStream(sessionId, streamId);

を使用して、セッション内のすべてのストリームのパブリッシャー (オプションのストリームリストを除く) に、音声のパブリッシングを強制的に停止させることができます。 VideoClient#muteSession(String sessionId, boolean active, String... excludedStreamIds) メソッドを使用する。その active パラメータは、既存のストリームと新しいストリームを、デフォルトでミュートするかどうかを決定する。オプションの excludedStreamIds パラメータには、このミュートリクエストから除外するストリームを渡すことができる。

videoClient.muteSession(sessionId, true);

詳しくはセッション内のストリームの音声をミュートする.

シグナリング

を使って、セッションの参加者全員にシグナルを送ることができます。 VideoClient#signalAll(String sessionId, SignalRequest request) メソッドを使用してください。特定の参加者にシグナルを送るには VideoClient#signal(String sessionId, String connectionId, SignalRequest request) メソッドに置き換えた。

について SignalRequest クラス（ビルダー・パターンを使って構築される）には2つのフィールドがある： type そして dataどちらも必須である。これらは、クライアント・シグナル受信ハンドラで渡されるタイプ・パラメータとデータ・パラメータに対応する。必ず type 文字列が最大長（128バイト）を超えず、かつ data 文字列が最大長（8kB）を超えないこと。

SignalRequest signal = SignalRequest.builder()
    .type("chat")
    .data("Hello, World!")
    .build();

// Signal all connections in the session
videoClient.signalAll(sessionId, signal);

// Signal a specific connection in the session
videoClient.signal(sessionId, connectionId, signal);

シグナリングと例外コードの詳細については、以下を参照してください。 REST API仕様.

シップ

を使用して、SIPプラットフォームをVonageビデオセッションに接続します。 VideoClient#sipDial(SipDialRequest request) メソッドを使用します。リクエストで URI、sessionId、およびトークンを提供する必要があります。を設定することで、Vonage と SIP エンドポイント間のネゴシエーションをセキュアに (TLS を使用して) 行うかどうかを指定できます。 secure パラメータ SipDialRequest.Builder#uri(URI uri, boolean secure) への true.オプションで、リクエストに認証用のユーザー名とパスワードを指定することもできる。

SipDialRequest request = SipDialRequest.builder()
	.uri(URI.create("sip:user@sip.partner.com"), false)
	.sessionId(sessionId).token(token).build();

SipDialResponse parsed = videoClient.sipDial(request);

を使用して、通話参加者全員にDTMFトーンを再生できます。 VideoClient#sendDtmf(String sessionId, String digits) メソッドを使用します。特定の参加者のみにトーンを送信するには VideoClient#sendDtmf(String sessionId, String connectionId, String digits) メソッドに置き換えた。

String digits = "*0123456789#";
// Send to all participants in the session
videoClient.sendDtmf(sessionId, digits);

// Send to a specific participant
videoClient.sendDtmf(sessionId, connectionId, digits);

必要条件

Vonage VideoアプリのIDと秘密鍵が必要です。 Vonage Video API アカウント.

Vonage Java SDKのコンパイルにはJDK 8以上が必要です。ランタイムにはJava SE 8以上が必要です。

リリースノート

参照リリース各リリースの詳細については

ナビゲーション