SDK de Java para la Video API de Vonage

Descripción general del SDK
Referencia API
Descargar
Muestras
GitHub

El SDK de Java de OpenTok ofrece métodos para:

Generación sesiones y fichas para OpenTok Applications
Trabajar con OpenTok archivos
Trabajar con OpenTok retransmisiones en directo
Trabajar con OpenTok Interconexión SIP
Envío de señales a los clientes conectados a una sesión
Desconectar a los clientes de las sesiones
Forzar a los clientes de una sesión a desconectarse o silenciar el audio publicado
Trabajar con Compositores con experiencia
Trabajar con Conectores de audio

Instalación

Maven Central (recomendado):

El Maven Central Este repositorio ayuda a gestionar las dependencias de los proyectos basados en la JVM. Se puede utilizar con varias herramientas de compilación, como Maven y Gradle.

Maven

Si utiliza Maven como herramienta de compilación, puede gestionar las dependencias en el directorio pom.xml archivo:

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

Gradle

Cuando utilizas Gradle como herramienta de compilación, puedes gestionar las dependencias en el build.gradle archivo:

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

De forma manual:

Descarga el archivo JAR de la última versión desde el Comunicados página. Inclúyela en la ruta de clases de tu propio proyecto mediante utilizando directamente el JDK o en el IDE que prefieras.

Uso

Inicialización de

Importa las clases necesarias en cualquier clase en la que se vayan a utilizar. A continuación, inicializa un com.opentok.OpenTok objeto con tu propia clave API y tu propio secreto 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)

Opciones de configuración avanzadas

Puede utilizar OpenTok.Builder para configurar opciones avanzadas. Esta clase incluye los siguientes métodos:

.requestTimeout(int) -- Utiliza esta opción para especificar el tiempo de espera de las solicitudes HTTP (en segundos). El tiempo de espera predeterminado es de 60 segundos.
.proxy(Proxy) -- Utilizando un java.net.Proxy objeto, puedes configurar un servidor proxy que el cliente HTTP utilizará al llamar a la API REST de OpenTok.

Llame al OpenTok.Builder() constructor, pasando tu clave API y tu secreto, para crear una instancia de un OpenTok.Builder objeto. A continuación, llama a la requestTimeout() o proxy() métodos (o ambos). A continuación, llama a la build() método que devuelve un objeto OpenTok.

Por ejemplo, el siguiente código crea una instancia de un objeto OpenTok, con el tiempo de espera predeterminado fijado en 10 segundos:

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

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

El método close()

Asegúrate de llamar al OpenTok.close() método cuando hayas terminado, para evitar fugas de descriptores de archivo:

opentok.close();

Creación de sesiones

Para crear una sesión de OpenTok, utiliza el OpenTok de la instancia createSession(SessionProperties properties) método. El properties Este parámetro es opcional y se utiliza para especificar dos cosas:

Si la sesión utiliza el OpenTok Media Router
Una indicación de la ubicación del servidor de OpenTok.
Si la sesión se archiva automáticamente.

Una instancia se puede inicializar utilizando el com.opentok.SessionProperties.Builder clase. El sessionId propiedad del valor devuelto com.opentok.Session instancia, que puedes leer utilizando el getSessionId() Este método resulta útil para obtener un identificador que se pueda guardar en un almacén persistente (como una base de datos).

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

Generación de fichas

Una vez creada una sesión, puedes empezar a generar tokens para que los clientes los utilicen al conectarse a ella. Puedes generar un token llamando a una com.opentok.OpenTok de la instancia generateToken(String sessionId, TokenOptions options) método, o llamando a un com.opentok.Session de la instancia generateToken(TokenOptions options) método tras crearlo. El options El parámetro es opcional y se utiliza para configurar el rol, el tiempo de caducidad y los datos de conexión del token. Una instancia se puede inicializar utilizando el TokenOptions.Builder clase.

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

Trabajar con archivos

Solo puedes archivar las sesiones que utilicen el OpenTok Media Router (sesiones cuyo modo multimedia esté configurado como «enrutado»).

Puedes iniciar la grabación de una sesión de OpenTok utilizando un com.opentok.OpenTok de la instancia startArchive(String sessionId, String name) método. Esto devolverá un com.opentok.Archive instancia. El parámetro name Es opcional y sirve para asignar un nombre al archivo. Ten en cuenta que solo puedes iniciar un archivo en una sesión que tenga clientes conectados.

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

También puedes desactivar la grabación de audio o vídeo llamando al botón hasAudio(false) o hasVideo(false) métodos de un ArchiveProperties constructor, y pasando el objeto creado al OpenTok.startArchive(String sessionId, ArchiveProperties properties) método:

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

Establecer el modo de salida en Archive.OutputMode.INDIVIDUAL Esta configuración hace que cada flujo del archivo se grabe en su propio archivo 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();

El Archive.OutputMode.COMPOSED es el valor por defecto de outputMode. Archiva todos los flujos que se van a grabar en un único fichero (compuesto).

Sólo puede especificar el resolution para archivos compuestos que utilizan el ArchiveProperties constructor. Si configuras el resolution y también la propiedad outputMode propiedad a Archive.OutputMode.INDIVIDUAL, el método lanzará un InvalidArgumentException.

Los valores admitidos para resolution son:

"640x480" (SD, el valor por defecto)
"1280x720" (HD)
Ten en cuenta que si se establece cualquier otro valor para el resolution Esta propiedad provocará una excepción.

import com.opentok.ArchiveProperties;

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

Puedes detener la grabación de un archivo que ya se haya iniciado utilizando un com.opentok.Archive de la instancia stopArchive(String archiveId) método.

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

Para obtener un com.opentok.Archive (y toda la información sobre ella) de una instancia de archiveId, utiliza un com.opentok.OpenTok de la instancia getArchive(String archiveId) método.

Archive archive = opentok.getArchive(String archiveId);

Para eliminar un archivo, puedes llamar a una com.opentok.OpenTok de la instancia deleteArchive(String archiveId) método.

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

También puedes obtener una lista de todos los archivos que hayas creado (hasta 1000) con tu clave API. Para ello, se utiliza un com.opentok.OpenTok de la instancia listArchives(int offset, int count) método. Si lo deseas, puedes paginación los archivos que recibas utilizando los parámetros «offset» y «count». Esto devolverá un List<Archive> tipo. Un InvalidArgumentException Se producirá un error si el desplazamiento o el recuento son negativos o si el recuento es superior a 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);

También puedes recuperar la lista de archivos correspondientes a un ID de sesión concreto y, si lo deseas, utilizar los parámetros «offset» y «count» tal y como se ha descrito anteriormente.

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

Ten en cuenta que también puedes crear una sesión que se archive automáticamente, pasando ArchiveMode.ALWAYS hacia el archiveMode() método del SessionProperties.Builder objeto que se utiliza para crear el sessionProperties pasado al parámetro OpenTok.createSession() método (véase «Creación de sesiones», más arriba).

Para los archivos compuestos, puede establecer dinámicamente el diseño del archivo (mientras se graba el archivo) mediante la función OpenTok.setArchiveLayout(String archiveId, ArchiveProperties properties) método. Véase Personalización del diseño de vídeo para composiciones archivos Para obtener más información, utiliza el ArchiveProperties constructor de la siguiente manera:

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

En el caso de los diseños personalizados, el generador tiene el siguiente aspecto:

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

Puedes establecer la clase de diseño inicial para las transmisiones de un cliente configurando el layout opción al crear el token para el cliente, utilizando el OpenTok.generateToken(String sessionId, TokenOptions options) método. Además, puedes modificar las clases de diseño de un flujo de la siguiente manera:

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 quieres modificar la disposición de varias secuencias, crea un objeto `StreamProperties` para cada secuencia y añádelos al objeto `StreamListProperties` de la siguiente manera:

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

Para obtener más información sobre el archivado, consulta el Archivado de OpenTok guía del desarrollador.

Desconexión de clientes

Tu servidor de aplicaciones puede desconectar a un cliente de una sesión de OpenTok llamando a la función forceDisconnect(sessionId, connectionId) método del com.opentok.OpenTok instancia.

opentok.forceDisconnect(sessionId, connectionId);

El connectionId Este parámetro se utiliza para especificar el ID de conexión de un cliente a la sesión.

Para obtener más información sobre la función de desconexión forzada y los códigos de excepción, consulta el Documentación de la API REST.

Forzar a los clientes de una sesión a silenciar el audio publicado

Puede forzar al editor de un flujo específico a dejar de publicar audio utilizando la opción Opentok.forceMuteStream(String sessionId, String streamId)método.

Puede forzar al editor de todos los flujos de una sesión (excepto una lista opcional de flujos) para que deje de publicar audio mediante la opción Opentok.forceMuteAll(String sessionId, MuteAllProperties properties) método. A continuación, puedes desactivar el estado de silencio de la sesión llamando al Opentok.disableForceMute(String sessionId) método.

Para obtener más información, consulta Silenciar el audio de los flujos de una sesión.

Señalización

Puedes enviar señales a todas las conexiones de una sesión o a una conexión concreta:

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

El SignalProperties El generador te ayuda a crear los datos y el tipo de la señal:

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

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

Asegúrate de que el type la cadena no supera la longitud máxima (128 bytes) y la data La cadena no supera la longitud máxima (8 kB). El SignalProperties Actualmente, el generador no comprueba estas limitaciones.

Para obtener más información sobre los códigos de señalización y de excepción, consulta la documentación de la Señalización de OpenTok Método REST.

Radiodifusión

Puedes retransmitir las transmisiones de OpenTok a un flujo HLS (HTTP Live Streaming) o a flujos RTMP. Para iniciar correctamente la retransmisión de una sesión, debe haber al menos un cliente conectado a la sesión. La retransmisión en directo puede dirigirse a un punto final HLS y hasta cinco servidores RTMP simultáneamente por sesión. Solo se puede iniciar la retransmisión en directo en sesiones que utilicen OpenTok Media Router (con el modo multimedia configurado en «routed»); no se puede utilizar la retransmisión en directo en sesiones cuyo modo multimedia esté configurado en «relayed». (Consulte el OpenTok Media Router y los modos multimedia (Guía para desarrolladores).

Puedes iniciar una retransmisión utilizando el OpenTok.startBroadcast(sessionId, properties) método, en el que el properties «field» es un BroadcastProperties objeto. Inicializar un BroadcastProperties objeto de la siguiente manera (véase el Emisión de Opentok Método REST (para más detalles):

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

Por último, inicia una retransmisión tal y como se muestra a continuación:

Broadcast broadcast = opentok.startBroadcast(sessionId, properties)

El Broadcast El objeto devuelto contiene la siguiente información:

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

Para detener una emisión, utiliza:

Broadcast broadcast = opentok.stopBroadcast(broadcastId);

Para obtener más información sobre una retransmisión en directo, utiliza:

Broadcast broadcast = opentok.getBroadcast(broadcastId);

La información devuelta se encuentra en el Broadcast objeto y está compuesto por direcciones URL de HLS y/o RTMP, junto con el ID de sesión, la resolución, etc.

También puedes cambiar el diseño de una retransmisión en directo de forma dinámica utilizando:

opentok.setBroadcastLayout(broadcastId, properties);

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

Para cambiar dinámicamente la clase de diseño de un flujo concreto, utiliza

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

Trabajar con flujos

Puede obtener información sobre un flujo llamando a la función getStream(sessionId, streamId) método del com.opentok.OpenTok instancia.

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

Puede obtener información sobre todos los flujos de una sesión llamando a la función listStreams(sessionId) método del com.opentok.OpenTok instancia.


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

streamList.getTotalCount(); // total count

Trabajar con la interconexión SIP

Puedes añadir un flujo de solo audio procedente de una pasarela SIP externa de terceros mediante la función de interconexión SIP. Para ello, se necesita un URI SIP, el ID de sesión al que deseas añadir el flujo de solo audio y un token para conectarte a ese ID de sesión.

Para conectar tu plataforma SIP a una sesión de OpenTok, llama a la OpenTok.dial(String sessionId, String token, SipProperties properties) método. El audio de tu extremo de la llamada SIP se añade a la sesión de OpenTok como un flujo solo de audio. El enrutador multimedia de OpenTok mezcla el audio de otras transmisiones de la sesión y envía el audio mezclado a tu terminal SIP. La llamada finaliza cuando tu servidor SIP envía un mensaje BYE (para dar por terminada la llamada). También puedes finalizar una llamada utilizando el OpenTok.forceDisconnect(sessionId, connectionId) método para desconectar el cliente SIP de la sesión (véase Desconexión de clientes).

La pasarela SIP de OpenTok finaliza automáticamente una llamada tras 5 minutos de inactividad (5 minutos sin recibir datos multimedia). Además, como medida de seguridad, la pasarela SIP de OpenTok cierra cualquier llamada SIP que dure más de 6 horas.

La función de interconexión SIP requiere que utilices una sesión de OpenTok que emplee el OpenTok Media Router (una sesión con el modo multimedia configurado en «routed»).

Para conectar una sesión de OpenTok a una pasarela 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);

Trabajar con compositores experimentados

Puedes iniciar un Experiencia con Composer llamando al OpenTok.startRender(String sessionId, String token, RenderProperties properties) método:

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

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

Puedes detener un Experience Composer llamando a la función OpenTok.stopRender(String renderId) método.

Puedes obtener información sobre Experience Composers llamando al OpenTok.getRender(String renderId), OpenTok.listRenders() o OpenTok.listRenders(Integer offset, Integer count) métodos.

Cómo trabajar con Audio Connector

Puedes iniciar un Flujo de «Audio Connector» llamando al OpenTok.connectAudioStream(String sessionId, String token, AudioConnectorProperties properties) método:

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

Muestras

El SDK incluye dos aplicaciones de ejemplo. Para empezar lo antes posible, clona todo el repositorio y sigue las guías prácticas:

Documentación

La documentación de referencia está disponible en </opentok/sdks/java/reference/index.html>.

Requisitos

Necesitas una clave API y un secreto API de OpenTok, que puedes obtener iniciando sesión en tu Cuenta API de Video de Vonage.

El SDK de Java de OpenTok requiere JDK 8 o una versión posterior para su compilación. El entorno de ejecución requiere Java SE 8 o una versión posterior. Este proyecto se ha probado tanto en la implementación de OpenJDK como en la de Oracle.

Para Java 7, utiliza el SDK de OpenTok para Java v3.

Notas de publicación

Véase el Comunicados página para obtener más información sobre cada lanzamiento.