Video API Vonage – SDK Java

Le SDK Java d'OpenTok propose des méthodes permettant de :

Installation

Maven Central (recommandé) :

Les Maven Central Ce référentiel permet de gérer les dépendances des projets basés sur la JVM. Il peut être utilisé avec plusieurs outils de construction, notamment Maven et Gradle.

Maven

Lorsque vous utilisez Maven comme outil de construction, vous pouvez gérer les dépendances dans le fichier pom.xml fichier :

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

Gradle

Lorsque vous utilisez Gradle comme outil de construction, vous pouvez gérer les dépendances dans le fichier build.gradle fichier :

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

Manuellement :

Téléchargez le fichier JAR de la dernière version à partir du site Communiqués page. Intégrez-la dans le classpath de votre propre projet en en utilisant directement le JDK ou dans l'IDE de votre choix.

Utilisation

Initialisation

Importez les classes nécessaires dans toute classe où elles seront utilisées. Ensuite, initialisez un com.opentok.OpenTok objet avec votre propre clé API et votre secret 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)

Options de configuration avancées

Vous pouvez utiliser OpenTok.Builder pour définir des options avancées. Cette classe comprend les méthodes suivantes :

  • .requestTimeout(int) -- Appelez cette fonction pour définir le délai d'expiration des requêtes HTTP (en secondes). Le délai d'expiration par défaut est de 60 secondes.

  • .proxy(Proxy) -- À l'aide d'un java.net.Proxy objet, vous pouvez configurer un serveur proxy que le client HTTP utilisera lorsqu'il appellera l'API REST d'OpenTok.

Appeler le OpenTok.Builder() constructor, en lui transmettant votre clé API et votre secret, pour instancier un OpenTok.Builder objet. Appelez ensuite la méthode requestTimeout() ou proxy() méthodes (ou les deux). Appelez ensuite la build() méthode permettant de renvoyer un objet OpenTok.

Par exemple, le code suivant instancie un objet OpenTok, avec un délai d'expiration par défaut fixé à 10 secondes :

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

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

La méthode close()

N'oubliez pas d'appeler le OpenTok.close() méthode une fois que vous avez terminé, pour éviter les fuites de descripteurs de fichiers :

opentok.close();

Création de sessions

Pour créer une session OpenTok, utilisez la commande OpenTok de l’instance createSession(SessionProperties properties) méthode. La properties Ce paramètre est facultatif ; il sert à préciser deux éléments :

  • Si la session utilise le routeur multimédia OpenTok
  • Une indication de l'emplacement du serveur OpenTok.
  • Si la session est automatiquement archivée.

Une instance peut être initialisée à l'aide de la fonction com.opentok.SessionProperties.Builder classe. Le sessionId propriété de la valeur renvoyée com.opentok.Session instance, que vous pouvez lire à l'aide de la getSessionId() Cette méthode permet d'obtenir un identifiant pouvant être enregistré dans un système de stockage persistant (tel qu'une base de données).

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

Générer des jetons

Une fois la session créée, vous pouvez commencer à générer des jetons que les clients utiliseront pour s'y connecter. Vous pouvez générer un jeton soit en appelant une com.opentok.OpenTok de l'instance generateToken(String sessionId, TokenOptions options) méthode, ou en appelant une com.opentok.Session de l'instance generateToken(TokenOptions options) méthode après l'avoir créée. La options Le paramètre est facultatif ; il sert à définir le rôle, la durée de validité et les données de connexion du jeton. Une instance peut être initialisée à l'aide de la méthode TokenOptions.Builder classe.

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

Travailler avec les archives

Vous ne pouvez archiver que les sessions qui utilisent OpenTok Media Router (les sessions dont le mode multimédia est défini sur « routed »).

Vous pouvez lancer l'enregistrement d'une session OpenTok à l'aide d'un com.opentok.OpenTok de l'instance startArchive(String sessionId, String name) méthode. Cela renverra un com.opentok.Archive par exemple. Le paramètre name est facultatif et sert à attribuer un nom à l'archive. Notez que vous ne pouvez lancer une archive que sur une session à laquelle des clients sont connectés.

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

Vous pouvez également désactiver l'enregistrement audio ou vidéo en appelant la fonction hasAudio(false) ou hasVideo(false) méthodes d'un ArchiveProperties constructeur, puis en transmettant l'objet créé à la OpenTok.startArchive(String sessionId, ArchiveProperties properties) méthode :

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

En réglant le mode de sortie sur Archive.OutputMode.INDIVIDUAL Ce paramètre fait en sorte que chaque flux de l'archive soit enregistré dans son propre fichier :

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

Les Archive.OutputMode.COMPOSED est la valeur par défaut de l'option outputMode. Il archive tous les flux à enregistrer dans un seul fichier (composé).

Vous ne pouvez spécifier que le resolution pour les archives composées à l'aide du ArchiveProperties générateur. Si vous définissez le resolution et définit également la propriété outputMode à la propriété Archive.OutputMode.INDIVIDUAL, la méthode lancera une InvalidArgumentException.

Les valeurs admises pour resolution sont :

  • "640x480" (SD, valeur par défaut)
  • "1280x720" (HD)

    Veuillez noter que si vous définissez une autre valeur pour le resolution Cette propriété provoquera une exception.

import com.opentok.ArchiveProperties;

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

Vous pouvez interrompre l'enregistrement d'une archive déjà lancée à l'aide d'un com.opentok.Archive de l'instance stopArchive(String archiveId) méthode.

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

Pour obtenir un com.opentok.Archive (et toutes les informations la concernant) à partir d'une instance de archiveId, utilisez un com.opentok.OpenTok de l'instance getArchive(String archiveId) méthode.

Archive archive = opentok.getArchive(String archiveId);

Pour supprimer une archive, vous pouvez appeler une com.opentok.OpenTok de l'instance deleteArchive(String archiveId) méthode.

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

Vous pouvez également obtenir la liste de toutes les archives que vous avez créées (jusqu'à 1 000) à l'aide de votre clé API. Pour cela, il suffit d'utiliser une com.opentok.OpenTok de l'instance listArchives(int offset, int count) méthode. Vous pouvez, si vous le souhaitez, pager les archives que vous recevez à l'aide des paramètres « offset » et « count ». Cela renverra un List<Archive> type. Un InvalidArgumentException Une exception sera levée si l'offset ou le nombre sont négatifs ou si le nombre est supérieur à 1 000.

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

Vous pouvez également récupérer la liste des archives correspondant à un identifiant de session spécifique et, si vous le souhaitez, utiliser les paramètres « offset » et « count » comme décrit ci-dessus.

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

Notez que vous pouvez également créer une session archivée automatiquement, en transmettant ArchiveMode.ALWAYS dans le archiveMode() de la méthode SessionProperties.Builder objet que vous utilisez pour créer le sessionProperties passé dans le paramètre OpenTok.createSession() méthode (voir « Création de sessions », ci-dessus).

Pour les archives composées, vous pouvez définir dynamiquement la mise en page de l'archive (pendant l'enregistrement de l'archive) à l'aide de la fonction OpenTok.setArchiveLayout(String archiveId, ArchiveProperties properties) méthode. Voir Personnalisation de la mise en page vidéo pour les composées Pour plus d'informations, utilisez le ArchiveProperties comme suit :

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

Pour les mises en page personnalisées, l'éditeur se présente comme suit :

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

Vous pouvez définir la classe de mise en page initiale pour les flux d'un client en définissant la propriété layout option lors de la création du jeton pour le client, à l'aide de la OpenTok.generateToken(String sessionId, TokenOptions options) méthode. Vous pouvez également modifier les classes de mise en page d'un flux comme suit :

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

Si vous souhaitez modifier la mise en page de plusieurs flux, créez un objet StreamProperties pour chaque flux, puis ajoutez-les à l'objet StreamListProperties comme suit :

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

Pour plus d'informations sur l'archivage, consultez le Archivage OpenTok guide du développeur.

Déconnexion des clients

Votre serveur d'applications peut déconnecter un client d'une session OpenTok en appelant la méthode forceDisconnect(sessionId, connectionId) méthode de la com.opentok.OpenTok instance.

opentok.forceDisconnect(sessionId, connectionId);

Les connectionId Ce paramètre sert à spécifier l'identifiant de connexion d'un client à la session.

Pour plus d'informations sur la fonctionnalité de déconnexion forcée et les codes d'exception, veuillez consulter le document Documentation de l'API REST.

Forcer les clients d'une session à couper le son publié

Vous pouvez forcer l'éditeur d'un flux spécifique à cesser de publier de l'audio à l'aide de la commande Opentok.forceMuteStream(String sessionId, String streamId)méthode.

Vous pouvez forcer l'éditeur de tous les flux d'une session (à l'exception d'une liste optionnelle de flux) à cesser de publier de l'audio à l'aide de la commande Opentok.forceMuteAll(String sessionId, MuteAllProperties properties) méthode. Vous pouvez ensuite désactiver le mode « muet » de la session en appelant la méthode Opentok.disableForceMute(String sessionId) méthode.

Pour plus d'informations, consultez Désactiver l'audio des flux dans une session.

Signalisation

Vous pouvez envoyer des signaux à toutes les connexions d'une session ou à une connexion spécifique :

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

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

Les SignalProperties Le générateur vous aide à créer les données et le type du signal :

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

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

Assurez-vous que le type la chaîne ne dépasse pas la longueur maximale (128 octets) et la data la chaîne ne dépasse pas la longueur maximale (8 ko). La SignalProperties Le générateur ne prend actuellement pas en compte ces restrictions.

Pour plus d'informations sur la signalisation et les codes d'exception, consultez la documentation relative à la Signalisation OpenTok Méthode REST.

Radiodiffusion

Vous pouvez diffuser des flux OpenTok vers un flux HLS (HTTP Live Streaming) ou vers des flux RTMP. Pour que la diffusion d'une session puisse démarrer correctement, au moins un client doit être connecté à la session. La diffusion en direct peut cibler un point de terminaison HLS et jusqu’à cinq serveurs RTMP simultanément pour une même session. Vous ne pouvez lancer la diffusion en direct que pour les sessions qui utilisent OpenTok Media Router (avec le mode multimédia défini sur « routed ») ; vous ne pouvez pas utiliser la diffusion en direct avec des sessions dont le mode multimédia est défini sur « relayed ». (Voir le Routeur multimédia OpenTok et modes multimédia guide du développeur).

Vous pouvez lancer une diffusion à l'aide de la commande OpenTok.startBroadcast(sessionId, properties) méthode, où le properties Le champ est un BroadcastProperties objet. Initialiser un BroadcastProperties objet comme suit (voir le Diffusion Opentok Méthode REST (pour plus de détails) :

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

Enfin, lancez une diffusion comme indiqué ci-dessous :

Broadcast broadcast = opentok.startBroadcast(sessionId, properties)

Les Broadcast L'objet renvoyé contient les informations suivantes :

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

Pour interrompre une diffusion, utilisez :

Broadcast broadcast = opentok.stopBroadcast(broadcastId);

Pour obtenir plus d'informations sur une diffusion en direct, utilisez :

Broadcast broadcast = opentok.getBroadcast(broadcastId);

Les informations renvoyées se trouvent dans le Broadcast objet et comprend des URL HLS et/ou RTMP, ainsi que l'identifiant de session, la résolution, etc.

Vous pouvez également modifier le mise en page d'une émission en direct de manière dynamique à l'aide de :

opentok.setBroadcastLayout(broadcastId, properties);

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

Pour modifier dynamiquement la classe de mise en page d'un flux individuel, utilisez

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

Travailler avec des flux

Vous pouvez obtenir des informations sur un flux en appelant la fonction getStream(sessionId, streamId) méthode de la 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

Vous pouvez obtenir des informations sur tous les flux d'une session en appelant la fonction listStreams(sessionId) de la méthode com.opentok.OpenTok instance.


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

streamList.getTotalCount(); // total count

Travailler avec SIP Interconnect

Vous pouvez ajouter un flux audio uniquement provenant d'une passerelle SIP tierce externe à l'aide de la fonctionnalité « Interconnexion SIP ». Pour cela, vous devez disposer d'un URI SIP, de l'identifiant de session auquel vous souhaitez ajouter le flux audio uniquement, ainsi que d'un jeton permettant de se connecter à cet identifiant de session.

Pour connecter votre plateforme SIP à une session OpenTok, appelez la fonction OpenTok.dial(String sessionId, String token, SipProperties properties) méthode. Le flux audio provenant de votre côté de l'appel SIP est ajouté à la session OpenTok sous la forme d'un flux audio uniquement. Le routeur multimédia OpenTok mélange l’audio provenant des autres flux de la session et envoie le flux audio mixé vers votre terminal SIP. L’appel prend fin lorsque votre serveur SIP envoie un message BYE (pour mettre fin à l’appel). Vous pouvez également mettre fin à un appel à l’aide de la OpenTok.forceDisconnect(sessionId, connectionId) méthode permettant de déconnecter le client SIP de la session (voir Déconnexion des clients).

La passerelle SIP OpenTok met automatiquement fin à un appel après 5 minutes d'inactivité (5 minutes sans réception de données multimédia). De plus, par mesure de sécurité, la passerelle SIP OpenTok met fin à tout appel SIP qui dure plus de 6 heures.

La fonctionnalité d'interconnexion SIP nécessite l'utilisation d'une session OpenTok exploitant l' OpenTok Media Router (une session dont le mode multimédia est défini sur « routed »).

Pour connecter une session OpenTok à une passerelle 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);

Travailler avec des compositeurs expérimentés

Vous pouvez lancer un Compositeur d'expérience en appelant le OpenTok.startRender(String sessionId, String token, RenderProperties properties) méthode :

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

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

Vous pouvez arrêter un Experience Composer en appelant la fonction OpenTok.stopRender(String renderId) méthode.

Pour obtenir des informations sur Experience Composers, vous pouvez appeler le OpenTok.getRender(String renderId), OpenTok.listRenders() ou OpenTok.listRenders(Integer offset, Integer count) des méthodes.

Utilisation d'Audio Connector

Vous pouvez lancer un Flux « Audio Connector » en appelant le OpenTok.connectAudioStream(String sessionId, String token, AudioConnectorProperties properties) méthode :

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

Exemples

Le SDK comprend deux exemples d'applications. Pour vous lancer le plus rapidement possible, clonez l'intégralité du dépôt et suivez les guides pratiques :

Documentation

La documentation de référence est disponible à l'adresse suivante : &lt;/opentok/sdks/java/reference/index.html&gt;.

Exigences

Vous avez besoin d'une clé API OpenTok et d'un secret API, que vous pouvez obtenir en vous connectant à votre Compte Video API de Vonage.

Le SDK Java d'OpenTok nécessite le JDK 8 ou une version ultérieure pour la compilation. L'exécution nécessite Java SE 8 ou une version ultérieure. Ce projet a été testé à la fois sur les implémentations OpenJDK et Oracle.

Pour Java 7, veuillez utiliser le SDK Java OpenTok v3.

Notes de mise à jour

Voir le Communiqués page pour plus de détails sur chaque sortie.