Suggestions

close search

Add Messaging, Voice, and Authentication to your apps with Nexmo APIs

Visit Nexmo

OpenTok Java SDK

API referenceDownloadSamplesGitHub

The OpenTok Java SDK lets you generate sessions and tokens for OpenTok applications that run on the JVM. The SDK also includes support for working with working with OpenTok archives, working with OpenTok live streaming broadcasts, working with OpenTok SIP interconnect, signaling OpenTok sessions from the server, and disconnecting clients from sessions.

Installation

The Maven Central repository helps manage dependencies for JVM based projects. It can be used via several build tools, including Maven and Gradle.

Maven

When you use Maven as your build tool, you can manage dependencies in the pom.xml file:

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

Gradle

When you use Gradle as your build tool, you can manage dependencies in the build.gradle file:

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

Manually:

Download the jar file for the latest release from the Releases page. Include it in the classpath for your own project by using the JDK directly or in your IDE of choice.

Usage

Initializing

Import the required classes in any class where it will be used. Then initialize a com.opentok.OpenTok object with your own API Key and API Secret.

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)

And make sure you call close when you are done to prevent leaked file descriptors.

opentok.close();

Creating Sessions

To create an OpenTok Session, use the OpenTok instance’s createSession(SessionProperties properties) method. The properties parameter is optional and it is used to specify two things:

An instance can be initialized using the com.opentok.SessionProperties.Builder class. The sessionId property of the returned com.opentok.Session instance, which you can read using the getSessionId() method, is useful to get an identifier that can be saved to a persistent store (such as a database).

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 used the 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();

Generating Tokens

Once a Session is created, you can start generating Tokens for clients to use when connecting to it. You can generate a token either by calling an com.opentok.OpenTok instance's generateToken(String sessionId, TokenOptions options) method, or by calling a com.opentok.Session instance's generateToken(TokenOptions options) method after creating it. The options parameter is optional and it is used to set the role, expire time, and connection data of the token. An instance can be initialized using the TokenOptions.Builder class.

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());

Working with Archives

You can only archive sessions that use the OpenTok Media Router (sessions with the media mode set to routed).

You can start the recording of an OpenTok Session using a com.opentok.OpenTok instance's startArchive(String sessionId, String name) method. This will return a com.opentok.Archive instance. The parameter name is optional and used to assign a name for the Archive. Note that you can only start an Archive on a Session that has clients connected.

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();

You can also disable audio or video recording by calling the hasAudio(false) or hasVideo(false) methods of an ArchiveProperties builder, and passing the built object into the OpenTok.startArchive(String sessionId, ArchiveProperties properties) method:

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();

Setting the output mode to Archive.OutputMode.INDIVIDUAL setting causes each stream in the archive to be recorded to its own individual file:

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

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

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

The Archive.OutputMode.COMPOSED setting (the default) causes all streams in the archive to be recorded to a single (composed) file.

You can set the composed archive resolution to either "640x480" (SD, the default) or "1280x720" (HD) using the ArchiveProperties builder. Any other value will result in an exception.The property only applies to composed archives. If you set this property and also set the outputMode property to "individual", the method results in an InvalidArgumentException.

import com.opentok.ArchiveProperties;

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

You can stop the recording of a started Archive using a com.opentok.Archive instance's stopArchive(String archiveId) method.

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

To get an com.opentok.Archive instance (and all the information about it) from an archiveId, use a com.opentok.OpenTok instance's getArchive(String archiveId) method.

Archive archive = opentok.getArchive(String archiveId);

To delete an Archive, you can call a com.opentok.OpenTok instance's deleteArchive(String archiveId) method.

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

You can also get a list of all the Archives you've created (up to 1000) with your API Key. This is done using a com.opentok.OpenTok instance's listArchives(int offset, int count) method. You may optionally paginate the Archives you receive using the offset and count parameters. This will return a List<Archive> type. An InvalidArgumentException will be thrown if the offset or count are negative or if the count is greater than 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);

You can also fetch the list of archives for a specific session ID , and optionally use the offset and count parameters as described above.

// 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);

Note that you can also create an automatically archived session, by passing ArchiveMode.ALWAYS into the archiveMode() method of the SessionProperties.Builder object you use to build the sessionProperties parameter passed into the OpenTok.createSession() method (see "Creating Sessions," above).

For composed archives, you can dynamically set the archive layout (while the archive is being recorded) using the OpenTok.setArchiveLayout(String archiveId, ArchiveProperties properties) method. See Customizing the video layout for composed archives for more information. Use the ArchiveProperties builder as follows:

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

For custom layouts the builder looks like:

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

You can set the initial layout class for a client's streams by setting the layout option when you create the token for the client, using the OpenTok.generateToken(String sessionId, TokenOptions options) method. And you can also change the layout classes of a stream as follows:

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

If you want to change the layout of multiple streams, create a StreamProperties object for each stream, and add them to the StreamListProperties object as follows:

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

For more information on archiving, see the OpenTok archiving developer guide.

Disconnecting Clients

Your application server can disconnect a client from an OpenTok session by calling the forceDisconnect(sessionId, connectionId) method of the com.opentok.OpenTok instance.

opentok.forceDisconnect(sessionId, connectionId);

The connectionId parameter is used to specify the connection ID of a client connection to the session.

For more information on the force disconnect functionality and exception codes, please see the REST API documentation.

Signaling

You can send signals to all the connections in a session or to a specific connection:

The SignalProperties builder helps you to construct the signal data and type:

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

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

Make sure that the type string does not exceed the maximum length (128 bytes) and the data string does not exceed the maximum length (8 kB). The SignalProperties builder does not currently check for these limitations.

For more information on signaling and exception codes, refer to the documentation for the OpenTok signaling REST method.

Broadcasting

You can broadcast OpenTok publishing streams to an HLS (HTTP live streaming) or to RTMP streams. To successfully start broadcasting a session, at least one client must be connected to the session. You can only have one active live streaming broadcast at a time for a session (however, having more than one would not be useful). The live streaming broadcast can target one HLS endpoint and up to five RTMP servers simulteneously for a session. You can only start live streaming for sessions that use the OpenTok Media Router (with the media mode set to routed); you cannot use live streaming with sessions that have the media mode set to relayed. (See the OpenTok Media Router and media modes developer guide).

You can start a broadcast using the OpenTok.startBroadcast(sessionId, properties) method, where the properties field is a BroadcastProperties object. Initalize a BroadcastProperties object as follows (see the Opentok Broadcast REST method for more details):

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);

Finally, start a broadcast as shown below:

Broadcast broadcast = opentok.startBroadcast(sessionId, properties)

The Broadcast object returned has the following info:

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

To stop a broadcast use:

Broadcast broadcast = opentok.stopBroadcast(broadcastId);

To get more information about a live streaming broadcast, use:

Broadcast broadcast = opentok.getBroadcast(broadcastId);

The information returned is in the Broadcast object and consists of HLS and/or Rtmp URLs, along with the session ID, resolution, etc.

You can also change the layout of a live broadcast dynamically using:

opentok.setBroadcastLayout(broadcastId, properties);

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

To dynamically change the layout class of an individual stream, use

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

Working with Streams

You can get information about a stream by calling the getStream(sessionId, streamId) method of the com.opentok.OpenTok instance.

// 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

You can get information about all of the streams in a session by calling the listStreams(sessionId) method of the com.opentok.OpenTok instance.


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

streamList.getTotalCount(); // total count

Working with SIP Interconnect

You can add an audio-only stream from an external third party SIP gateway using the SIP Interconnect feature. This requires a SIP URI, the session ID you wish to add the audio-only stream to, and a token to connect to that session ID.

To connect your SIP platform to an OpenTok session, call the OpenTok.dial(String sessionId, String token, SipProperties properties) method. The audio from your end of the SIP call is added to the OpenTok session as an audio-only stream. The OpenTok Media Router mixes audio from other streams in the session and sends the mixed audio to your SIP endpoint. The call ends when your SIP server sends a BYE message (to terminate the call). You can also end a call using the OpenTok.forceDisconnect(sessionId, connectionId) method to disconnect the SIP client from the session (see Disconnecting clients).

The OpenTok SIP gateway automatically ends a call after 5 minutes of inactivity (5 minutes without media received). Also, as a security measure, the OpenTok SIP gateway closes any SIP call that lasts longer than 6 hours.

The SIP interconnect feature requires that you use an OpenTok session that uses the OpenTok Media Router (a session with the media mode set to routed).

To connect an OpenTok session to a SIP gateway:

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);

Requirements

You need an OpenTok API key and API secret, which you can obtain by logging into your TokBox account.

The OpenTok Java SDK requires JDK 8 or greater to compile. Runtime requires Java SE 8 or greater. This project is tested on both OpenJDK and Oracle implementations.

For Java 7 please use OpenTok Java SDK v3.

Release Notes

See the Releases page for details about each release.