Vonage Video API Java SDK

Das OpenTok Java SDK bietet Methoden für:

Einrichtung

Maven Central (empfohlen):

Die Maven-Zentrale Das Repository unterstützt die Verwaltung von Abhängigkeiten für JVM-basierte Projekte. Es kann über verschiedene Build-Tools genutzt werden, darunter Maven und Gradle.

Maven

Wenn Sie Maven als Build-Tool verwenden, können Sie die Abhängigkeiten in der pom.xml Datei:

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

Gradle

Wenn Sie Gradle als Build-Tool verwenden, können Sie die Abhängigkeiten in der build.gradle Datei:

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

Manuell:

Laden Sie die JAR-Datei für die neueste Version von der Veröffentlichungen Seite. Fügen Sie sie in den Klassenpfad Ihres eigenen Projekts ein, indem Sie direkte Verwendung des JDK oder in der IDE Ihrer Wahl.

Verwendung

Initialisierung

Importieren Sie die erforderlichen Klassen in jede Klasse, in der sie verwendet werden sollen. Initialisieren Sie anschließend ein com.opentok.OpenTok Objekt mit Ihrem eigenen API-Schlüssel und API-Geheimnis.

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)

Erweiterte Konfigurationsoptionen

Sie können verwenden OpenTok.Builder um erweiterte Optionen festzulegen. Diese Klasse umfasst die folgenden Methoden:

  • .requestTimeout(int) -- Rufen Sie diese Funktion auf, um das Timeout für HTTP-Anfragen (in Sekunden) festzulegen. Das Standard-Timeout beträgt 60 Sekunden.

  • .proxy(Proxy) -- Mit einem java.net.Proxy Objekt können Sie einen Proxy-Server konfigurieren, den der HTTP-Client beim Aufruf der OpenTok-REST-API verwendet.

Rufen Sie die OpenTok.Builder() Konstruktor, wobei Sie Ihren API-Schlüssel und Ihr API-Geheimnis übergeben, um eine Instanz von OpenTok.Builder Objekt. Rufen Sie anschließend die requestTimeout() oder proxy() Methoden (oder beides). Rufen Sie anschließend die build() Methode, die ein OpenTok-Objekt zurückgibt.

Der folgende Code instanziiert beispielsweise ein OpenTok-Objekt, wobei das Standard-Timeout auf 10 Sekunden festgelegt ist:

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

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

Die Methode „close()“

Rufen Sie unbedingt die OpenTok.close() Methode, wenn Sie fertig sind, um undichte Dateideskriptoren zu vermeiden:

opentok.close();

Sitzungen erstellen

Um eine OpenTok-Sitzung zu erstellen, verwenden Sie die OpenTok Instanz createSession(SessionProperties properties) Methode. Die properties Der Parameter ist optional und dient dazu, zwei Dinge festzulegen:

  • Ob die Sitzung den OpenTok Media Router nutzt
  • Ein Hinweis auf den Standort des OpenTok-Servers.
  • Ob die Sitzung automatisch archiviert wird.

Eine Instanz kann mithilfe der com.opentok.SessionProperties.Builder Klasse. Die sessionId Eigenschaft des zurückgegebenen com.opentok.Session Instanz, die Sie mithilfe der getSessionId() Diese Methode ist nützlich, um eine Kennung zu erhalten, die in einem persistenten Speicher (z. B. einer Datenbank) gespeichert werden kann.

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

Token generieren

Sobald eine Sitzung erstellt wurde, können Sie damit beginnen, Token zu generieren, die Clients bei der Verbindung zu dieser Sitzung verwenden können. Sie können ein Token entweder durch Aufruf einer com.opentok.OpenTok Instanz generateToken(String sessionId, TokenOptions options) Methode oder durch Aufruf einer com.opentok.Session Instanz generateToken(TokenOptions options) Methode nach deren Erstellung. Die options Der Parameter ist optional und dient zur Festlegung der Rolle, der Gültigkeitsdauer und der Verbindungsdaten des Tokens. Eine Instanz kann mithilfe des TokenOptions.Builder Klasse.

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

Arbeiten mit Archiven

Sie können nur Sitzungen archivieren, die den OpenTok Media Router verwenden (Sitzungen, bei denen der Medienmodus auf „routed“ eingestellt ist).

Sie können die Aufzeichnung einer OpenTok-Sitzung mit einem com.opentok.OpenTok Instanz startArchive(String sessionId, String name) Methode. Diese gibt ein com.opentok.Archive Instanz. Der Parameter name ist optional und dient dazu, dem Archiv einen Namen zuzuweisen. Beachten Sie, dass Sie ein Archiv nur in einer Sitzung starten können, mit der Clients verbunden sind.

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

Sie können die Audio- oder Videoaufzeichnung auch deaktivieren, indem Sie die Funktion hasAudio(false) oder hasVideo(false) Methoden eines ArchiveProperties Builder und die Übergabe des erstellten Objekts an den OpenTok.startArchive(String sessionId, ArchiveProperties properties) Methode:

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

Einstellung des Ausgabemodus auf Archive.OutputMode.INDIVIDUAL Durch diese Einstellung wird jeder Stream im Archiv in einer eigenen Datei aufgezeichnet:

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

Die Archive.OutputMode.COMPOSED ist der Standardwert für die Option outputMode. Es archiviert alle aufzuzeichnenden Streams in einer einzigen (zusammengesetzten) Datei.

Sie können nur die resolution für zusammengesetzte Archive unter Verwendung der ArchiveProperties Builder. Wenn Sie die resolution Eigenschaft und setzen Sie auch die outputMode Eigenschaft zu Archive.OutputMode.INDIVIDUAL, löst die Methode einen InvalidArgumentException.

Die zulässigen Werte für resolution sind:

  • "640x480" (SD, Standard)
  • "1280x720" (HD)

    Bitte beachten Sie, dass die Einstellung eines anderen Werts für die resolution Die Eigenschaft führt zu einer Ausnahme.

import com.opentok.ArchiveProperties;

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

Sie können die Aufzeichnung eines bereits gestarteten Archivs mit einem com.opentok.Archive Instanz stopArchive(String archiveId) Methode.

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

Um eine com.opentok.Archive Instanz (und alle Informationen darüber) aus einer archiveId, verwende ein com.opentok.OpenTok Instanz getArchive(String archiveId) Methode.

Archive archive = opentok.getArchive(String archiveId);

Um ein Archiv zu löschen, können Sie eine com.opentok.OpenTok Instanz deleteArchive(String archiveId) Methode.

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

Sie können sich außerdem eine Liste aller Archive anzeigen lassen, die Sie mit Ihrem API-Schlüssel erstellt haben (bis zu 1000). Dies erfolgt mithilfe eines com.opentok.OpenTok Instanz listArchives(int offset, int count) Methode. Optional können Sie die erhaltenen Archivdaten mithilfe der Parameter „offset“ und „count“ paginieren. Dadurch wird ein List<Archive> Typ. Ein InvalidArgumentException wird ausgelöst, wenn der Offset oder die Anzahl negativ sind oder wenn die Anzahl größer als 1000 ist.

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

Sie können auch die Liste der Archive für eine bestimmte Sitzungs-ID abrufen und optional die Parameter „offset“ und „count“ wie oben beschrieben verwenden.

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

Beachten Sie, dass Sie auch eine automatisch archivierte Sitzung erstellen können, indem Sie ArchiveMode.ALWAYS in die archiveMode() Methode der SessionProperties.Builder Objekt, das Sie zum Erstellen des sessionProperties Parameter, der an die OpenTok.createSession() Methode (siehe „Erstellen von Sitzungen“ weiter oben).

Für zusammengesetzte Archive können Sie das Archivlayout dynamisch festlegen (während das Archiv aufgezeichnet wird), indem Sie den Befehl OpenTok.setArchiveLayout(String archiveId, ArchiveProperties properties) Methode. Siehe Anpassen des Videolayouts für zusammengesetzte Archive Weitere Informationen finden Sie hier. Nutzen Sie die ArchiveProperties Erbauer wie folgt:

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

Bei benutzerdefinierten Layouts sieht der Builder wie folgt aus:

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

Sie können die anfängliche Layoutklasse für die Streams eines Clients festlegen, indem Sie die layout Option, wenn Sie das Token für den Client erstellen, unter Verwendung der OpenTok.generateToken(String sessionId, TokenOptions options) Methode. Außerdem können Sie die Layout-Klassen eines Streams wie folgt ändern:

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

Wenn Sie das Layout mehrerer Streams ändern möchten, erstellen Sie für jeden Stream ein StreamProperties-Objekt und fügen Sie diese wie folgt dem StreamListProperties-Objekt hinzu:

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

Weitere Informationen zur Archivierung finden Sie unter OpenTok-Archivierung Leitfaden für Entwickler.

Trennen von Clients

Ihr Anwendungsserver kann einen Client von einer OpenTok-Sitzung trennen, indem er die forceDisconnect(sessionId, connectionId) Methode der com.opentok.OpenTok Instanz.

opentok.forceDisconnect(sessionId, connectionId);

Die connectionId Mit diesem Parameter wird die Verbindungs-ID einer Client-Verbindung zur Sitzung angegeben.

Weitere Informationen über die Funktion "Force Disconnect" und die Ausnahmecodes finden Sie in der REST-API-Dokumentation.

Erzwingen, dass Clients in einer Sitzung das veröffentlichte Audio stummschalten

Sie können den Herausgeber eines bestimmten Streams zwingen, die Veröffentlichung von Audio zu beenden, indem Sie die Opentok.forceMuteStream(String sessionId, String streamId)Methode.

Sie können den Herausgeber aller Streams in einer Sitzung (mit Ausnahme einer optionalen Liste von Streams) zwingen die Veröffentlichung von Audio zu beenden, indem Sie die Opentok.forceMuteAll(String sessionId, MuteAllProperties properties) Methode. Anschließend können Sie den Stummschaltungsstatus der Sitzung aufheben, indem Sie die Opentok.disableForceMute(String sessionId) Methode.

Weitere Informationen finden Sie unter Stummschalten des Tons von Streams in einer Sitzung.

Signalisierung

Sie können Signale an alle Verbindungen einer Sitzung oder an eine bestimmte Verbindung senden:

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

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

Die SignalProperties Mit dem Builder können Sie die Signaldaten und den Typ erstellen:

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

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

Stellen Sie sicher, dass die type Die Zeichenkette überschreitet nicht die maximale Länge (128 Bytes) und die data Die Zeichenkette überschreitet nicht die maximale Länge (8 kB). Die SignalProperties Der Builder prüft derzeit nicht, ob diese Einschränkungen vorliegen.

Weitere Informationen zu Signalisierungs- und Ausnahmecodes finden Sie in der Dokumentation zur OpenTok-Signalisierung REST-Methode.

Rundfunk und Fernsehen

Sie können OpenTok-Publishing-Streams als HLS-Streams (HTTP Live Streaming) oder als RTMP-Streams übertragen. Um die Übertragung einer Sitzung erfolgreich zu starten, muss mindestens ein Client mit der Sitzung verbunden sein. Die Live-Streaming-Übertragung kann pro Sitzung auf einen HLS-Endpunkt und bis zu fünf RTMP-Server gleichzeitig gerichtet sein. Sie können Live-Streaming nur für Sitzungen starten, die den OpenTok Media Router verwenden (wobei der Medienmodus auf „routed“ eingestellt ist); bei Sitzungen, bei denen der Medienmodus auf „relayed“ eingestellt ist, können Sie kein Live-Streaming nutzen. (Siehe die OpenTok Media Router und Medienmodi modes Entwicklerhandbuch).

Sie können eine Übertragung starten, indem Sie die OpenTok.startBroadcast(sessionId, properties) Methode, wobei die properties Das Feld ist ein BroadcastProperties Objekt. Initialisiere ein BroadcastProperties Objekt wie folgt (siehe die Opentok-Übertragung REST-Methode (weitere 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);

Starten Sie schließlich eine Übertragung wie unten gezeigt:

Broadcast broadcast = opentok.startBroadcast(sessionId, properties)

Die Broadcast Das zurückgegebene Objekt enthält die folgenden Informationen:

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

Um eine Übertragung zu beenden, verwenden Sie:

Broadcast broadcast = opentok.stopBroadcast(broadcastId);

Um weitere Informationen zu einer Live-Übertragung zu erhalten, verwenden Sie:

Broadcast broadcast = opentok.getBroadcast(broadcastId);

Die zurückgegebenen Informationen liegen im Broadcast Objekt und besteht aus HLS- und/oder RTMP-URLs, sowie der Sitzungs-ID, der Auflösung usw.

Sie können auch die Layout einer Live-Übertragung dynamisch mithilfe von:

opentok.setBroadcastLayout(broadcastId, properties);

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

Um die Layout-Klasse eines einzelnen Streams dynamisch zu ändern, verwenden Sie

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

Arbeiten mit Strömen

Sie können Informationen über einen Stream erhalten, indem Sie die getStream(sessionId, streamId) Methode der com.opentok.OpenTok Instanz.

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

Sie können Informationen über alle Streams in einer Sitzung erhalten, indem Sie die listStreams(sessionId) Methode der com.opentok.OpenTok Instanz.


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

streamList.getTotalCount(); // total count

Arbeiten mit SIP Interconnect

Mithilfe der SIP-Interconnect-Funktion können Sie einen reinen Audio-Stream von einem externen SIP-Gateway eines Drittanbieters hinzufügen. Dazu benötigen Sie eine SIP-URI, die Sitzungs-ID, zu der Sie den reinen Audio-Stream hinzufügen möchten, sowie ein Token, um eine Verbindung zu dieser Sitzungs-ID herzustellen.

Um Ihre SIP-Plattform mit einer OpenTok-Sitzung zu verbinden, rufen Sie die OpenTok.dial(String sessionId, String token, SipProperties properties) Methode. Der Ton von Ihrer Seite des SIP-Anrufs wird der OpenTok-Sitzung als reiner Audio-Stream hinzugefügt. Der OpenTok Media Router mischt das Audio aus anderen Streams in der Sitzung und sendet das gemischte Audio an Ihren SIP-Endpunkt. Der Anruf endet, wenn Ihr SIP-Server eine BYE-Nachricht sendet (um den Anruf zu beenden). Sie können einen Anruf auch mithilfe der OpenTok.forceDisconnect(sessionId, connectionId) Methode zum Trennen des SIP-Clients von der Sitzung (siehe Trennen von Clients).

Das OpenTok-SIP-Gateway beendet einen Anruf automatisch nach 5 Minuten Inaktivität (5 Minuten ohne empfangene Medien). Außerdem schließt das OpenTok-SIP-Gateway als Sicherheitsmaßnahme jeden SIP-Anruf, der länger als 6 Stunden dauert.

Für die SIP-Verbindungsfunktion müssen Sie eine OpenTok-Sitzung verwenden, die den OpenTok Media Router nutzt (eine Sitzung, bei der der Medienmodus auf „routed“ eingestellt ist).

So verbinden Sie eine OpenTok-Sitzung mit einem 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);

Die Zusammenarbeit mit erfahrenen Komponisten

Sie können ein Erlebnis-Komponist durch Aufruf der OpenTok.startRender(String sessionId, String token, RenderProperties properties) Methode:

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

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

Sie können den Experience Composer anhalten, indem Sie die Funktion OpenTok.stopRender(String renderId) Methode.

Informationen zu Experience Composers erhalten Sie telefonisch unter der Nummer OpenTok.getRender(String renderId), OpenTok.listRenders() oder OpenTok.listRenders(Integer offset, Integer count) Methoden.

Arbeiten mit Audio Connector

Sie können ein Audio-Connector-Stream durch Aufruf der OpenTok.connectAudioStream(String sessionId, String token, AudioConnectorProperties properties) Methode:

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

Beispiele

Das SDK enthält zwei Beispiel-Applications. Um so schnell wie möglich loslegen zu können, klonen Sie das gesamte Repository und folgen Sie den Anleitungen:

Dokumentation

Die Referenzdokumentation finden Sie unter &lt;/opentok/sdks/java/reference/index.html&gt;.

Anforderungen

Sie benötigen einen OpenTok-API-Schlüssel und ein API-Geheimnis, die Sie erhalten, indem Sie sich bei Ihrem Vonage Video API-Konto.

Für die Kompilierung des OpenTok Java SDK ist JDK 8 oder höher erforderlich. Für die Ausführung ist Java SE 8 oder höher erforderlich. Dieses Projekt wurde sowohl mit OpenJDK- als auch mit Oracle-Implementierungen getestet.

Für Java 7 verwenden Sie bitte das OpenTok Java SDK v3.

Anmerkungen zur Veröffentlichung

Siehe die Veröffentlichungen Seite mit weiteren Informationen zu den einzelnen Veröffentlichungen.