SDK de Java Server

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

Instalación

La Video API se añadió en la versión 8.0.0 del SDK en 2023, aunque se recomienda utilizar la última versión por motivos de seguridad, corrección de errores y funciones añadidas en versiones posteriores.

Maven Central:

La mejor manera de agregar Vonage Java Server SDK a tu proyecto es agregar la dependencia al sistema de compilación de tu proyecto. Puedes encontrar instrucciones en la página Repo de GitHub así como Maven Central para Maven, Gradle, Ivy, SBT, Leiningen, etc.

Maven

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

<dependency>
    <groupId>com.vonage</groupId>
    <artifactId>server-sdk</artifactId>
    <version>9.3.1</version>
</dependency>

Gradle

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

dependencies {
  implementation 'com.vonage:server-sdk:9.+'
}

Uso

El SDK Java de Vonage te permite utilizar API REST de Vonage utilizando sus subclientes, uno para cada API. Para trabajar con el Video APIutilice el botón com.vonage.client.video.VideoClient clase. Contiene métodos para todos los puntos finales compatibles con la especificación de la API. Puedes obtenerla llamando a la getVideoClient() método de VonageClient.

Inicialización de

Inicializar un com.vonage.client.VonageClient objeto con tu ID de aplicación de vídeo y tu clave privada. Esto devuelve un objeto con todos los métodos necesarios para trabajar con la Video API.

import com.vonage.client.VonageClient;
import com.vonage.client.video.*;

// Inside a class or method...
VideoClient videoClient = VonageClient.builder()
    .applicationId("APP_ID")
    .privateKeyPath("/path/to/private.key")
    .build().getVideoClient();

Generación de fichas

Tu aplicación de Vonage Video necesitará un token del lado del cliente para ser útil. Este token puede ser generado por el SDK del servidor a través de la función VideoClient#generateToken(String sessionId, TokenOptions options) método. Tendrá que pasar el ID de sesión, pero el método options El parámetro no es obligatorio (puede ser nulo, o bien puedes llamar a la VideoClient#generateToken(String sessionId) (por comodidad). El método devolverá un JWT firmado con las reclamaciones correspondientes, en forma de cadena codificada en Base64 que podrás enviar al cliente.

String jwt = videoClient.generateToken(sessionId);

Por defecto, el token tendrá una caducidad de 24 horas y el rol será "editor" (com.vonage.video.client.Role#PUBLISHER). El plazo máximo de caducidad permitido es de 30 días. Puedes configurarlos mediante el TokenOptions que utiliza el patrón constructor. También puede establecer los metadatos de conexión, pero estos no pueden superar los 1000 caracteres.

TokenOptions tokenOptions = TokenOptions.builder()
        .expiryLength(Duration.ofHours(6))
        .role(Role.SUBSCRIBER)
        .build();
String jwt = videoClient.generateToken(sessionId, tokenOptions);

Véase el Guía para la creación de tokens para obtener una explicación más detallada de las opciones de configuración.

Creación de sesiones

Para crear una sesión de vídeo de Vonage, utiliza el botón VideoClient#createSession(CreateSessionRequest request) método. En request Este parámetro es opcional y se utiliza para especificar:

  • Si la sesión utiliza el router de medios de vídeo de Vonage
  • Una indicación de la ubicación del servidor de Vonage Video.
  • Si la sesión se archiva automáticamente.

Al igual que con la mayoría de las demás propiedades de solicitud, se utiliza el patrón «builder». Para crear una instancia, empieza por el método estático builder() establezca las propiedades y llame a build() para construir una instancia.

Si la solicitud se ha realizado correctamente, un CreateSessionResponse se devuelve. La propiedad más útil es el ID de sesión, que se puede obtener llamando a la función getSessionId() método. Es posible que te interese conservar el identificador de sesión para utilizarlo más adelante, ya que es un parámetro habitual en otras llamadas a métodos.

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

// A session that uses the Vonage Video Media Router:
CreateSessionResponse session = videoClient.createSession(
    CreateSessionRequest.builder().mediaMode(MediaMode.ROUTED).build()
);

// A Session with a location hint:
CreateSessionResponse session = videoClient.createSession(
    CreateSessionRequest.builder().location("12.34.56.78").build()
);

// A session that is automatically archived (it must be used for the routed media mode)
CreateSessionResponse session = videoClient.createSession(
    CreateSessionRequest.builder()
      .mediaMode(MediaMode.ROUTED)
      .archiveMode(ArchiveMode.ALWAYS)
      .build()
);

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

Trabajar con archivos

Solo se pueden archivar las sesiones que utilicen el Vonage Video Media Router (es decir, las sesiones cuyo modo multimedia esté configurado en MediaMode.ROUTED). Para obtener más información sobre el archivado, consulta el Archivo de vídeo de Vonage guía del desarrollador.

Crear archivo

Puedes iniciar manualmente la grabación de una sesión de video de Vonage utilizando la función createArchive(Archive request) método. Si tiene éxito, se rellenarán propiedades adicionales en el archivo com.vonage.client.video.Archive instancia con la respuesta del servidor.

Ten en cuenta que solo puedes iniciar un archivo en una sesión que tenga clientes conectados. El Archive La solicitud sigue el patrón «builder» para su construcción. Todas las propiedades, excepto el ID de sesión, son opcionales, de ahí que el Archive.builder(String sessionId) requiere este parámetro.

// A simple Archive with the default property values
Archive archive = videoClient.createArchive(Archive.builder(sessionId).build());

// Store this archiveId in the database for later use
UUID 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 Archive constructor.

// Audio-only archive
Archive.builder(sessionId).hasVideo(false).hasAudio(true).build();

Establecer el modo de salida en OutputMode.INDIVIDUAL hace que cada flujo del archivo se grabe en su propio archivo individual:

Archive.builder(sessionId).outputMode(OutputMode.INDIVIDUAL).name("My recording").build();

El 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. Si establece la opción resolution y también la propiedad outputMode propiedad a OutputMode.INDIVIDUALEl build() lanzará un mensaje IllegalStateException.

// Set the archive resolution to 1280x720
Archive.builder(sessionId).resolution(Resolution.HD_LANDSCAPE).build();

Detener grabación

Puede detener la grabación de un Archivo iniciado utilizando la tecla VideoClient#stopArchive(String archiveId) método.

// Stop an Archive
Archive archive = videoClient.stopArchive(archiveId);

Eliminar un archivo

Para eliminar un archivo, utiliza la opción VideoClient#deleteArchive(String archiveId) método.

// Delete an Archive
videoClient.deleteArchive(archiveId);

Recuperar un único archivo

Para conseguir una persona Archive (y toda su información) a partir de un ID de archivo, utilice la función VideoClient#getArchive(String archiveId) método.

// Retrieve archive info
Archive archive = videoClient.getArchive(archiveId);

Recuperar varios archivos

Puedes obtener una lista de todos los archivos que hayas creado (hasta 1000) en tu aplicación utilizando el VideoClient#listArchives() método. Para filtrar los resultados devueltos, llama al VideoClient#listArchives(ListArchivesRequest request) método en su lugar. El objeto de solicitud se crea utilizando el patrón «builder» y tiene tres parámetros opcionales:

  • sessionId: te permite limitar los resultados a los archivos asociados a una sesión concreta.
  • count: limita el número de resultados devueltos.
  • offset: descarta un número inicial de resultados (útil cuando hay más de 1000 archivos).

Un IllegalArgumentException se lanzará si el offset o count son negativas o si el count es superior a 1000. La lista resultante de Archives estarán en fecha/hora orden, del más reciente al más antiguo.

// Get a list with the first 1000 archives
List<Archive> archives = videoClient.listArchives();

// Get a list of the first 50 archives created
List<Archive> archives = videoClient.listArchives(
    Archive.builder().count(50).build()
);

// Get a list of the next 50 archives
List<Archive> archives = videoClient.listArchives(
    Archive.builder().offset(50).count(50).build()
);

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
List<Archive> archives = videoClient.listArchives(
    ListStreamCompositionsRequest.builder().sessionId(sessionId).build()
);

// Get a list of the next 1000 archives for a specific session
List<Archive> archives = videoClient.listArchives(
    ListStreamCompositionsRequest.builder()
      .offset(1000)
      .sessionId(sessionId)
      .build()
);

Establecer la disposición del archivo

Para los archivos compuestos, puede establecer dinámicamente el diseño del archivo (mientras se graba el archivo) mediante la función VideoClient#setArchiveLayout(String archiveId, ArchiveLayout layout) método.

También puede definir la disposición al crear el archivo (véase Archive.Builder#layout(ArchiveLayout layout)). Véase Personalización del diseño de vídeo para los archivos compuestos para más información.

Utiliza el ArchiveProperties constructor de la siguiente manera:

StreamCompositionLayout layout = StreamCompositionLayout.standardLayout(ScreenLayoutType.VERTICAL);
videoClient.updateArchiveLayout(archiveId, layout);

Para los diseños personalizados, debe especificar la hoja de estilos (en CSS):

StreamCompositionLayout layout = StreamCompositionLayout.customLayout("stream { position: absolute; }")

También puedes configurar el tipo de disposición al compartir la pantalla; la disposición inicial se establecerá en ScreenLayoutType.BEST_FIT:

StreamCompositionLayout layout = StreamCompositionLayout.screenshareLayout(ScreenLayoutType.PIP);

Añadir flujo a un archivo

Puede añadir un flujo a un archivo compuesto que se inició con la función streamMode ajustado a StreamMode.MANUAL utilizando el VideoClient#addArchiveStream(String archiveId, String streamId) pasando el método ID de archivo y ID de flujo que desea añadir al archivo, respectivamente.

El VideoClient#addArchiveStream(String archiveId, String streamId, Boolean audio, Boolean video) La variante de este método permite activar o desactivar el audio y el vídeo.

Por defecto, ambos están activados (es decir. true). false para la audio Este parámetro desactivará el audio, pasando false «para vídeo» desactivará el vídeo (lo que dará lugar a una transmisión solo de audio). Si se establece cualquiera de estos valores en null es equivalente al valor por defecto (es decir, true en ambos casos).

// Add stream to archive
videoClient.addArchiveStream(archiveId, streamId);

// Add stream to archive without audio
videoClient.addArchiveStream(archiveId, streamId, false, true);

// Add stream to archive without video
videoClient.addArchiveStream(archiveId, streamId, true, false);

Eliminar una secuencia de un archivo

Puedes eliminar un flujo de un archivo compuesto utilizando el VideoClient#removeArchiveStream(String archiveId, String streamId) método. Al igual que al añadir un flujo, el archivo debe haberse iniciado con streamMode en "manual".

videoClient.removeArchiveStream(archiveId, streamId);

Trabajar con emisiones

Trabajar con emisiones en directo es muy parecido a trabajar con archivos

Lista de todas las emisiones en directo

List<Broadcast> broadcasts = videoClient.listBroadcasts();

Obtener información detallada sobre una emisión concreta

Broadcast broadcast = videoClient.getBroadcast(broadcastId);

Iniciar una retransmisión en directo

Para iniciar correctamente la emisión de una sesión, al menos un cliente debe estar conectado a la sesión. La retransmisión en directo puede dirigirse a un extremo HLS y hasta cinco servidores RTMP simultáneamente para una sesión. Se requiere el ID de sesión y se debe especificar al menos un flujo de salida (RTMP y/o HLS).

Broadcast broadcast = videoClient.createBroadcast(
		Broadcast.builder(sessionId)
            .hls(Hls.builder().lowLatency(true).build())
            .resolution(Resolution.HD_LANDSCAPE)
		    .streamMode(StreamMode.MANUAL)
            .layout(StreamCompositionLayout.builder(ScreenLayoutType.BEST_FIT)
                    .screenshareType(ScreenLayoutType.PIP)
                    .build()
            )
            .maxDuration(Duration.ofMinutes(45))
        .build()
);

Detener la grabación de una emisión

Broadcast broadcast = videoClient.stopBroadcast(broadcastId);

Cambiar dinámicamente el tipo de diseño de una retransmisión en directo

videoClient.updateBroadcastLayout(broadcastId,
		StreamCompositionLayout.standardLayout(ScreenLayoutType.HORIZONTAL)
);

Añadir o eliminar un flujo en una retransmisión en directo

Cambia los flujos incluidos en una emisión iniciada con streamMode configurado como SteamMode.MANUAL:

videoClient.addBroadcastStream(broadcastId, streamId);

videoClient.removeBroadcastStream(broadcastId, streamId);

Trabajar con flujos

Puede obtener información sobre un flujo llamando a la función VideoClient#getStream(String sessionId, String streamId) método. Si la solicitud se ha realizado correctamente, un com.vonage.client.video.GetStreamResponse Se devolverá una instancia, que podrá utilizarse para consultar las propiedades de interés relacionadas con el flujo.

GetStreamResponse stream = videoClient.getStream(sessionId, streamId);

// Stream Properties
VideoType videoType = stream.getVideoType();
String name = stream.getName();
List<String> layoutClassList = stream.layoutClassList();

Puede obtener información sobre todos los flujos de una sesión mediante la función VideoClient#listStreams(String sessionId) método. Esto devolverá un List de GetStreamResponse instancias, que puedes recorrer para encontrar la información que buscas.

// Get list of streams from a session ID
List<GetStreamResponse> streams = videoClient.listStreams(sessionId);
int count = streams.size();

// Get stream ID for a given stream name
UUID myStreamId = streams.stream()
    .filter(s -> "My Stream".equals(s.getName()))
    .findFirst().ifPresent(GetStreamResponse::getId)
    .orElseThrow(() -> new IllegalStateException(
          "Could not find stream in session "+sessionId
    ));

Establecer el diseño del flujo

Puede cambiar las clases de diseño de un flujo utilizando la función VideoClient#setStreamLayout(String sessionId, List<SessionStream> streams) método. Éste toma como entrada el ID de sesión y la lista de flujos a cambiar. Cada flujo está representado por un SessionStream objeto, que se crea mediante el patrón «builder», utilizando el ID del flujo para identificarlo (este es un parámetro obligatorio). Utiliza el SessionStream.Builder#layoutClassList(List<String> layoutClassList) para establecer los diseños del flujo (o la variante varargs por conveniencia). Para demostrarlo, supongamos que tenemos dos flujos, llamémoslos stream1 y stream2. Supongamos que stream1Id y stream2Id son cadenas con los ID de stream1 y stream2 respectivamente, y desea establecer stream1las clases de diseño de 's a full y focuspero stream2's a min.

He aquí cómo conseguirlo:

SessionStream
    stream1 = SessionStream.builder(stream1Id)
        .layoutClassList("full", "focus").build(),
    stream2 = SessionStream.builder(stream2Id)
        .layoutClassList("min").build();

videoClient.setStreamLayout(sessionId, stream1, stream2);

Moderación

Desconexión de clientes

Tu servidor de aplicaciones puede desconectar a un cliente de una sesión de Vonage Video llamando a la función VideoClient#forceDisconnect(String sessionId, String connectionId) método.

videoClient.forceDisconnect(sessionId, connectionId);

El connectionId Este parámetro se utiliza para especificar el ID de conexión de un cliente conectado 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

Puedes obligar al emisor de una transmisión concreta a dejar de emitir audio utilizando el VideoClient#muteStream(String sessionId, String streamId) método.

videoClient.muteStream(sessionId, streamId);

Puede forzar al editor de todas las secuencias de una sesión (excepto una lista opcional de secuencias) a dejar de publicar audio mediante la opción VideoClient#muteSession(String sessionId, boolean active, String... excludedStreamIds) método. En active determina si los flujos existentes y nuevos serán silenciados por defecto. El parámetro opcional excludedStreamIds le permite pasar los flujos que desea excluir de esta solicitud de silenciamiento.

videoClient.muteSession(sessionId, true);

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

Señalización

Puedes enviar señales a todos los participantes de una sesión utilizando el VideoClient#signalAll(String sessionId, SignalRequest request) método. Para señalar a un participante concreto, utiliza el VideoClient#signal(String sessionId, String connectionId, SignalRequest request) en su lugar.

El SignalRequest (construida utilizando el patrón constructor) tiene dos campos: type y data, ambos obligatorios. Estos se corresponden con los parámetros de tipo y de datos que se pasan a los controladores de recepción de señales del cliente. Asegúrate de que el type no supere la longitud máxima (128 bytes) y la cadena data no supere la longitud máxima (8 kB).

SignalRequest signal = SignalRequest.builder()
    .type("chat")
    .data("Hello, World!")
    .build();

// Signal all connections in the session
videoClient.signalAll(sessionId, signal);

// Signal a specific connection in the session
videoClient.signal(sessionId, connectionId, signal);

Para obtener más información sobre los códigos de señalización y de excepción, consulta el Especificación de la API REST.

SIP

Conecta tu plataforma SIP a una sesión de vídeo de Vonage utilizando el VideoClient#sipDial(SipDialRequest request) método. Debes proporcionar el URI, sessionId y token en la solicitud. Puedes especificar si la negociación entre Vonage y el punto final SIP se realizará de manera segura (utilizando TLS) configurando el parámetro secure parámetro de SipDialRequest.Builder#uri(URI uri, boolean secure) a true. Además, si lo deseas, puedes indicar un nombre de usuario y una contraseña para la autenticación en la solicitud.

SipDialRequest request = SipDialRequest.builder()
	.uri(URI.create("sip:user@sip.partner.com"), false)
	.sessionId(sessionId).token(token).build();

SipDialResponse parsed = videoClient.sipDial(request);

Puede reproducir tonos DTMF para todos los participantes en una llamada utilizando la tecla VideoClient#sendDtmf(String sessionId, String digits) método. Para enviar tonos únicamente a un participante concreto, utiliza el VideoClient#sendDtmf(String sessionId, String connectionId, String digits) en su lugar.

String digits = "*0123456789#";
// Send to all participants in the session
videoClient.sendDtmf(sessionId, digits);

// Send to a specific participant
videoClient.sendDtmf(sessionId, connectionId, digits);

Requisitos

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

Vonage Java SDK requiere JDK 8 o superior para compilar. El tiempo de ejecución requiere Java SE 8 o superior.

Notas de publicación

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