Vonage Video API Java SDK

OpenTok Java SDK には、以下の機能を実現するためのメソッドが用意されています：

生成セッションそしてトークン～のためにオープントーク Applications
OpenTokとの連携アーカイブ
OpenTokとの連携ライブ・ストリーミング放送
OpenTokとの連携 SIP相互接続
セッションに接続しているクライアントにシグナルを送る
セッションからのクライアントの切断
セッション内のクライアントに、公開されたオーディオを強制的に切断またはミュートさせる
一緒に働く経験豊富な作曲家たち
一緒に働くオーディオコネクタ

インストール

Maven Central（推奨）：

についてメイブン・セントラルこのリポジトリは、JVM ベースのプロジェクトの依存関係管理に役立ちます。Maven や Gradle を含む、いくつかのビルドツールを通じて利用できます。

メイブン

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

<dependency>
    <groupId>com.tokbox</groupId>
    <artifactId>opentok-server-sdk</artifactId>
    <version>4.11.0</version>
</dependency>

グラドル

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

dependencies {
  compile group: 'com.tokbox', name: 'opentok-server-sdk', version: '4.11.0'
}

手動で：

最新リリースのjarファイルは、以下の場所からダウンロードしてください。リリースページ。これを、以下の手順でご自身のプロジェクトのクラスパスに追加してください。 JDKを直接使用するまたは、お好みのIDEで。

使用方法

初期化

使用するクラスで、必要なクラスをインポートします。その後、 com.opentok.OpenTok 独自のAPIキーとAPIシークレットを指定してください。

import com.opentok.OpenTok;

// inside a class or method...
int apiKey = 000000; // YOUR API KEY
String apiSecret = "YOUR API SECRET";
OpenTok opentok = new OpenTok(apiKey, apiSecret)

詳細設定オプション

を使うことができる。 OpenTok.Builder 詳細設定を行うには。このクラスには以下のメソッドが含まれています：

.requestTimeout(int) -- HTTPリクエストのタイムアウト時間を指定するには、これを呼び出してください（単位は秒）。デフォルトのタイムアウト時間は60秒です。
.proxy(Proxy) -- を使用して java.net.Proxy オブジェクトを使用すると、HTTP クライアントが OpenTok REST API を呼び出す際に使用するプロキシサーバーを設定できます。

に電話する。 OpenTok.Builder() コンストラクタにAPIキーとシークレットを渡して、インスタンスを作成します。 OpenTok.Builder オブジェクト。次に、 requestTimeout() または proxy() メソッド（あるいはその両方）。その後、 build() OpenTok オブジェクトを返すメソッド。

たとえば、次のコードでは、デフォルトのタイムアウトを10秒に設定して、OpenTokオブジェクトをインスタンス化しています：

int apiKey = 12345; // YOUR API KEY
String apiSecret = "YOUR API SECRET";
int timeout = 10;

OpenTok opentok = new OpenTok.Builder(apiKey, apiSecret)
  .requestTimeout(timeout)
  .build();

close() メソッド

必ず以下の番号に電話してください。 OpenTok.close() 処理が完了したら、ファイル記述子のリークを防ぐために、次のメソッドを呼び出してください：

opentok.close();

セッションの作成

OpenTokセッションを作成するには、次の OpenTok インスタンスの createSession(SessionProperties properties) メソッド。その properties このパラメータはオプションであり、次の2つのことを指定するために使用されます：

そのセッションで OpenTok Media Router が使用されているかどうか
OpenTokサーバーの設置場所に関するヒント。
セッションを自動的にアーカイブするかどうか。

インスタンスは、 com.opentok.SessionProperties.Builder クラス。その sessionId 返される値の com.opentok.Session インスタンス。これは、以下の getSessionId() このメソッドは、永続ストレージ（データベースなど）に保存できる識別子を取得するのに役立ちます。

import com.opentok.MediaMode;
import com.opentok.ArchiveMode;
import com.opentok.Session;
import com.opentok.SessionProperties;

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

// A session that uses the OpenTok Media Router:
Session session = opentok.createSession(new SessionProperties.Builder()
  .mediaMode(MediaMode.ROUTED)
  .build());

// A Session with a location hint:
Session session = opentok.createSession(new SessionProperties.Builder()
  .location("12.34.56.78")
  .build());

// A session that is automatically archived (it must be used for routed media mode)
Session session = opentok.createSession(new SessionProperties.Builder()
  .mediaMode(MediaMode.ROUTED)
  .archiveMode(ArchiveMode.ALWAYS)
  .build());

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

トークンの生成

セッションが作成されると、クライアントがそのセッションに接続する際に使用するトークンの生成を開始できます。トークンは、 com.opentok.OpenTok インスタンスの generateToken(String sessionId, TokenOptions options) メソッド、または com.opentok.Session インスタンスの generateToken(TokenOptions options) メソッドを作成した後。その options パラメータはオプションであり、トークンのロール、有効期限、および接続データを設定するために使用されます。インスタンスは、 TokenOptions.Builder クラスである。

import com.opentok.TokenOptions;
import com.opentok.Role;

// Generate a token from just a sessionId (fetched from a database)
String token = opentok.generateToken(sessionId);
// Generate a token by calling the method on the Session (returned from createSession)
String token = session.generateToken();

// Set some options in a token
String token = session.generateToken(new TokenOptions.Builder()
  .role(Role.MODERATOR)
  .expireTime((System.currentTimeMillis() / 1000L) + (7 * 24 * 60 * 60)) // in one week
  .data("name=Johnny")
  .build());

アーカイブとの取り組み

OpenTok Media Router を使用しているセッションのみをアーカイブできます（メディアモードが「routed」に設定されているセッション）。

OpenTokセッションの録画は、以下の方法を使用して開始できます。 com.opentok.OpenTok インスタンスの startArchive(String sessionId, String name) メソッド。これにより、 com.opentok.Archive インスタンス。パラメータ name これはオプションであり、アーカイブに名前を付けるために使用されます。なお、アーカイブを開始できるのは、クライアントが接続しているセッションのみであることに注意してください。

import com.opentok.Archive;

// A simple Archive (without a name)
Archive archive = opentok.startArchive(sessionId, null);

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

を呼び出して、音声またはビデオ録画を無効にすることもできます。 hasAudio(false) または hasVideo(false) 〜の方法 ArchiveProperties ビルダー、そして構築されたオブジェクトを OpenTok.startArchive(String sessionId, ArchiveProperties properties) メソッドを使用する：

import com.opentok.Archive;
import com.opentok.ArchiveProperties;

// Start an audio-only archive
Archive archive = opentok.startArchive(sessionId, new ArchiveProperties.Builder()
  .hasVideo(false)
  .build());

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

出力モードを Archive.OutputMode.INDIVIDUAL この設定により、アーカイブ内の各ストリームがそれぞれ個別のファイルに記録されるようになります：

import com.opentok.Archive;
import com.opentok.ArchiveProperties;

Archive archive = opentok.startArchive(sessionId, new ArchiveProperties.Builder()
  .outputMode(Archive.OutputMode.INDIVIDUAL)
  .build());

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

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

指定できるのは resolution 以下の方法を使用して作成されたアーカイブについては、 ArchiveProperties ビルダー。もし resolution プロパティを設定し outputMode プロパティ Archive.OutputMode.INDIVIDUAL, このメソッドは InvalidArgumentException.

の許容値は resolution は次のとおりです：

"640x480" (SD、デフォルト)
"1280x720" (HD)
なお、この設定項目に他の値を設定した場合は、 resolution このプロパティを使用すると、例外が発生します。

import com.opentok.ArchiveProperties;

ArchiveProperties properties = new ArchiveProperties.Builder().resolution("1280x720").build();

開始済みのアーカイブの録画は、 com.opentok.Archive インスタンスの stopArchive(String archiveId) メソッドを使用する。

// Stop an Archive from an archiveId (fetched from database)
Archive archive = opentok.stopArchive(archiveId);

を得るには com.opentok.Archive インスタンス（とそれに関するすべての情報）を archiveId, 以下の a com.opentok.OpenTok インスタンスの getArchive(String archiveId) メソッドを使用する。

Archive archive = opentok.getArchive(String archiveId);

アーカイブを削除するには、 com.opentok.OpenTok インスタンスの deleteArchive(String archiveId) メソッドを使用する。

// Delete an Archive from an archiveId (fetched from database)
opentok.deleteArchive(archiveId);

また、APIキーを使用して、自分が作成したすべてのアーカイブ（最大1000件）の一覧を取得することもできます。これは以下の方法で行います。 com.opentok.OpenTok インスタンスの listArchives(int offset, int count) メソッド。必要に応じて、 offset および count パラメータを使用して、取得したアーカイブをページ分割することができます。これにより、 List<Archive> タイプ。An InvalidArgumentException オフセットまたはカウントが負の場合、あるいはカウントが1000を超える場合、例外が発生します。

// Get a list with the first 1000 archives created by the API Key
List<Archive> archives = opentok.listArchives();

// Get a list of the first 50 archives created by the API Key
List<Archive> archives = opentok.listArchives(0, 50);

// Get a list of the next 50 archives
List<Archive> archives = opentok.listArchives(50, 50);

また、特定のセッションIDに対応するアーカイブのリストを取得することもでき、必要に応じて前述のようにoffsetおよびcountパラメータを使用することもできます。

// Get a list with the first 1000 archives for a specific session
ArchiveList archives = opentok.listArchives(sessionId);

// Get a list of the first 50 archives  for a specific session
ArchiveList archives = sdk.listArchives(sessionId, 0, 50);

// Get a list of the next 50 archives for a specific session
ArchiveList archives = sdk.listArchives(sessionId, 50, 50);

なお、以下を渡すことで、自動的にアーカイブされるセッションを作成することも可能です。 ArchiveMode.ALWAYS ～へ archiveMode() のメソッドを使用する。 SessionProperties.Builder …を構築するために使用するオブジェクト sessionProperties パラメータに渡される。 OpenTok.createSession() メソッド（上記の「セッションの作成」を参照）。

構成されたアーカイブの場合、アーカイブのレイアウトを動的に設定することができます。 OpenTok.setArchiveLayout(String archiveId, ArchiveProperties properties) メソッド。参照：構成されたビデオのレイアウトをカスタマイズするアーカイブ詳細については、以下の ArchiveProperties ビルダーは次のように述べている：

ArchiveProperties properties = new ArchiveProperties.Builder()
    .layout(new ArchiveLayout(ArchiveLayout.Type.VERTICAL))
    .build();
opentok.setArchiveLayout(archiveId, properties);

カスタムレイアウトの場合、ビルダーは次のような見た目になります：

ArchiveProperties properties = new ArchiveProperties.Builder()
.layout(new ArchiveLayout(ArchiveLayout.Type.CUSTOM, "stream { position: absolute; }"))
.build();

を設定することで、クライアントのストリームの初期レイアウト・クラスを設定できます。 layout クライアント用のトークンを作成する際、 OpenTok.generateToken(String sessionId, TokenOptions options) メソッド。また、次のようにしてストリームのレイアウトクラスを変更することもできます：

StreamProperties streamProps = new StreamProperties.Builder()
  .id(streamId)
  .addLayoutClass("full")
  .addLayoutClass("focus")
  .build();
StreamListProperties properties = new StreamListProperties.Builder()
  .addStreamProperties(streamProps)
  .build();
opentok.setStreamLayouts(sessionId, properties);

複数のストリームのレイアウトを変更したい場合は、各ストリームごとに StreamProperties オブジェクトを作成し、次のように StreamListProperties オブジェクトに追加します。

StreamListProperties properties = new StreamListProperties.Builder()
  .addStreamProperties(streamProps1)
  .addStreamProperties(streamProps2)
  .build();
opentok.setStreamLayouts(sessionId, properties);

アーカイブに関する詳細については、以下の OpenTokのアーカイブ機能開発者ガイド

クライアントの切断

アプリケーションサーバーは、 forceDisconnect(sessionId, connectionId) のメソッド com.opentok.OpenTok インスタンスだ。

opentok.forceDisconnect(sessionId, connectionId);

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

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

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

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

セッション内のすべてのストリームのパブリッシャーを強制的に停止することができます（オプションのストリームリストを除く）。を使って音声の公開を停止させることができます。 Opentok.forceMuteAll(String sessionId, MuteAllProperties properties) メソッド。その後、 Opentok.disableForceMute(String sessionId) メソッドを使用する。

詳細については、以下を参照してください。セッション内のストリームの音声をミュートする.

シグナリング

セッション内のすべての接続に対して、あるいは特定の接続に対してシグナルを送信することができます：

public void signal(String sessionId, SignalProperties props) throws OpenTokException , RequestException, InvalidArgumentException
public void signal(String sessionId, String connectionId, SignalProperties props) throws OpenTokException , RequestException , InvalidArgumentException

について SignalProperties builder を使用すると、信号データと型を構築することができます：

SignalProperties properties = new SignalProperties.Builder()
  .type("test")
  .data("This is a test string")
  .build();

opentok.signal(sessionId, properties);
opentok.signal(sessionId, connectionId, properties);

必ず type 文字列が最大長（128バイト）を超えていないことおよび data 文字列が最大長（8 kB）を超えていません。この SignalProperties ビルダーは現在、これらの制限についてチェックを行っていません。

シグナリングおよび例外コードの詳細については、以下のドキュメントを参照してください。 OpenTokのシグナリング RESTメソッド。

放送

OpenTokのパブリッシングストリームは、HLS（HTTPライブストリーミング）または RTMPストリームとして配信できます。セッションの配信を正常に開始するには、少なくとも1つのクライアントがそのセッションに接続されている必要があります。 1つのセッションにつき、ライブストリーミングの配信先は、1つのHLSエンドポイントと最大5つの RTMPサーバーを同時に指定できます。ライブストリーミングを開始できるのは、 OpenTok Media Router を使用し（メディアモードが「routed」に設定されている）、メディアモードが「relayed」に設定されているセッションではライブストリーミングを使用できません。（詳細は OpenTok メディアルーターとメディアモード（開発者ガイド）。

以下の方法を使って放送を開始できます。 OpenTok.startBroadcast(sessionId, properties) メソッド、ここで、 properties field は BroadcastProperties オブジェクト。を初期化します。 BroadcastProperties オブジェクトは次のように定義されます（ Opentok ブロードキャスト（詳細についてはRESTメソッドを参照）：

BroadcastProperties properties = new BroadcastProperties.Builder()
        .hasHls(true)
        .addRtmpProperties(rtmpProps)
        .addRtmpProperties(rtmpNextProps)
        .maxDuration(1000)
        .resolution("640x480")
        .layout(layout)
        .build();

// The Rtmp properties can be build using RtmpProperties as shown below
RtmpProperties rtmpProps = new RtmpProperties.Builder()
        .id("foo")
        .serverUrl("rtmp://myfooserver/myfooapp")
        .streamName("myfoostream").build();

//The layout object is initialized as follows:
BroadcastLayout layout = new BroadcastLayout(BroadcastLayout.Type.PIP);

最後に、以下に示すように放送を開始してください：

Broadcast broadcast = opentok.startBroadcast(sessionId, properties)

について Broadcast 返されたオブジェクトには、以下の情報が含まれています：

String broadcastId;
String sessionId;
int projectId;
long createdAt;
long updatedAt;
String resolution;
String status;
List<Rtmp> rtmpList = new ArrayList<>();  //not more than 5
String hls;    // HLS url

// The Rtmp class mimics the RtmpProperties

ブロードキャストを停止するには、次のようにします：

Broadcast broadcast = opentok.stopBroadcast(broadcastId);

ライブ配信に関する詳細情報を確認するには、以下をご利用ください：

Broadcast broadcast = opentok.getBroadcast(broadcastId);

返される情報は、 Broadcast オブジェクトであり、HLSおよび／またはRTMPのURL、ならびにセッションID、解像度などが含まれます。

また、次の設定を変更することもできます。レイアウト以下の方法を用いて、ライブ放送を動的に：

opentok.setBroadcastLayout(broadcastId, properties);

//properties can be
BroadcastProperties properties = new BroadcastProperties.Builder()
          .layout(new BroadcastLayout(BroadcastLayout.Type.VERTICAL))
          .build();

個々のストリームのレイアウトクラスを動的に変更するには、以下を使用します。

StreamProperties streamProps = new StreamProperties.Builder()
          .id(streamId)
          .addLayoutClass("full")
          .addLayoutClass("focus")
          .build();
StreamListProperties properties = new StreamListProperties.Builder()
          .addStreamProperties(streamProps)
          .build();
opentok.setStreamLayouts(sessionId, properties);

ストリームを使う

ストリームに関する情報は getStream(sessionId, streamId) メソッドの com.opentok.OpenTok インスタンスだ。

// Get stream info from just a sessionId (fetched from a database)
Stream stream = opentok.getStream(sessionId, streamId);

// Stream Properties
stream.getId(); // string with the stream ID
stream.getVideoType(); // string with the video type
stream.getName(); // string with the name
stream.layoutClassList(); // List with the layout class list

を呼び出すことで、セッション内のすべてのストリームに関する情報を取得できます。 listStreams(sessionId) のメソッドを使用する。 com.opentok.OpenTok インスタンスだ。


// Get list of streams from just a sessionId (fetched from a database)
StreamList streamList = opentok.listStreams(sessionId);

streamList.getTotalCount(); // total count

SIPインターコネクトでの作業

SIP 相互接続機能を使用すると、外部のサードパーティ製SIPゲートウェイからの音声専用ストリームを追加できます。これには、SIP URI、音声専用ストリームを追加したいセッションID、およびそのセッションIDに接続するためのトークンが必要です。

SIPプラットフォームをOpenTokセッションに接続するには、 OpenTok.dial(String sessionId, String token, SipProperties properties) 方法。 SIP通話の相手側からの音声は、音声専用ストリームとしてOpenTokセッションに追加されます。 OpenTok メディアルーターは、セッション内の他のストリームからの音声をミックスし、そのミックスされた音声を SIP エンドポイントに送信します。SIP サーバーが BYE メッセージ（通話を終了するためのメッセージ）を送信すると、通話は終了します。また、 OpenTok.forceDisconnect(sessionId, connectionId) SIPクライアントをセッションから切断する方法（参照：クライアントの切断).

OpenTok SIPゲートウェイは、5分間操作がない場合（メディアの受信がない状態が5分間続いた場合）、自動的に通話を終了します。また、セキュリティ対策として、 OpenTok SIPゲートウェイは、6時間以上継続するSIP通話をすべて切断します。

SIP相互接続機能を利用するには、 OpenTok Media Router を使用する OpenTok セッション（メディアモードが「routed」に設定されたセッション）を使用する必要があります。

OpenTokセッションをSIPゲートウェイに接続するには：

SipProperties properties = new SipProperties.Builder()
         .sipUri("sip:user@sip.partner.com;transport=tls")
         .from("from@example.com")
         .headersJsonStartingWithXDash(headerJson)
         .userName("username")
         .password("password")
         .secure(true)
         .build();

 Sip sip = opentok.dial(sessionId, token, properties);

経験豊富な作曲家との協業

[...]を開始できます。エクスペリエンス・コンポーザーを呼び出すことで OpenTok.startRender(String sessionId, String token, RenderProperties properties) メソッドを使用する：

RenderProperties properties = new RenderProperties.Builder()
         .url("http://example.com/path-to-page/")
         .build();

Render render = opentok.startRender(sessionId, token, properties);

Experience Composer は、 OpenTok.stopRender(String renderId) メソッドを使用する。

「エクスペリエンス・コンポーザー」に関する情報は、以下の電話番号にお問い合わせいただければご提供いたします。 OpenTok.getRender(String renderId), OpenTok.listRenders() または OpenTok.listRenders(Integer offset, Integer count) のメソッドがある。

Audio Connector の使用方法

[...]を開始できます。オーディオコネクタのストリームを呼び出すことで OpenTok.connectAudioStream(String sessionId, String token, AudioConnectorProperties properties) メソッドを使用する：

AudioConnectorProperties properties = new AudioConnectorProperties.Builder("wss://service.com/ws-endpoint")
        .addStreams("streamId-1", "streamId-2")
        .addHeader("X-CustomHeader-Key", "headerValue")
        .build();

AudioConnector ac = opentok.connectAudioStream(sessionId, token, properties);

サンプル

SDK には 2 つのサンプル Applications が含まれています。できるだけ早く使い始めるには、リポジトリ全体をクローンし、チュートリアルに従ってください：

ドキュメンテーション

リファレンスドキュメントは、 </opentok/sdks/java/reference/index.html> でご覧いただけます。

必要条件

OpenTokのAPIキーとAPIシークレットが必要です。これらは、アカウントにログインすることで取得できます。 Vonage Video API アカウント.

OpenTok Java SDK をコンパイルするには、JDK 8 以降が必要です。実行には Java SE 8 以降が必要です。このプロジェクトは、OpenJDK および Oracle の実装の両方でテストされています。

Java 7 をお使いの場合は、OpenTok Java SDK v3 をご利用ください。

リリースノート

参照リリース各リリースの詳細については、こちらのページをご覧ください。