SDK de servidor Java

El Vonage Java SDK proporciona 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

Si utiliza Gradle como herramienta de compilación, puede gestionar las dependencias en el directorio build.gradle archivo:

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

Utilización

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 admitidos en la especificación de la API. Puede obtenerla llamando a la clase getVideoClient() método de VonageClient.

Inicialización de

Inicializar un com.vonage.client.VonageClient con su ID de aplicación de vídeo y su 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 no es obligatorio (puede ser nulo o se puede llamar al parámetro VideoClient#generateToken(String sessionId) por comodidad). El método devolverá un JWT firmado con las reclamaciones apropiadas, como una cadena codificada en Base64 que puede pasar 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 tiempo máximo de caducidad permitido es de 30 días. Puede configurarlo mediante la opción 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 de creación de fichas para 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 es opcional y se utiliza para especificar:

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

Como en la mayoría de las propiedades de petición, se utiliza el patrón constructor. Para instanciarla, comience con la propiedad estática builder() establezca las propiedades y llame a build() para construir una instancia.

Si la solicitud se ha realizado correctamente, aparecerá un CreateSessionResponse se devuelve. La propiedad más útil es el identificador de sesión, que puede obtenerse llamando a la función getSessionId() método. Es posible que desee conservar el ID de sesión para su uso futuro, ya que es un parámetro común para 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

Sólo puedes archivar sesiones que utilicen el router de medios de vídeo de Vonage (es decir, sesiones con el modo de medios establecido en MediaMode.ROUTED). Para obtener más información sobre el archivado, consulte 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 con la respuesta del servidor.

Tenga en cuenta que sólo puede iniciar un Archivo en una Sesión que tenga clientes conectados. La dirección Archive sigue el patrón constructor para su construcción. Todas las propiedades, excepto el identificador de sesión, son opcionales, de ahí que la etiqueta 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();

En 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, utilice la tecla VideoClient#deleteArchive(String archiveId) método.

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

Recuperar un único archivo

Para conseguir un individuo 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

Puede obtener una lista de todos los Archivos que ha creado (hasta 1000) dentro de su aplicación utilizando la opción VideoClient#listArchives() método. Para filtrar los resultados devueltos, llame al método VideoClient#listArchives(ListArchivesRequest request) en su lugar. El objeto de solicitud se construye utilizando el patrón constructor y tiene tres parámetros opcionales:

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

En IllegalArgumentException se lanzará si el offset o count son negativos o si los 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 puede obtener la lista de archivos para un ID de sesión específico y, opcionalmente, utilizar los parámetros offset y count 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 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 puede establecer el tipo de diseño al compartir pantalla, donde el diseño 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.

En 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 desactivará el audio, pasando false para vídeo desactivará el vídeo (dando como resultado un flujo sólo de audio). Establecer cualquiera de estos valores a 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

Puede eliminar un flujo de un archivo compuesto utilizando la función 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 presentación 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, se mostrará un com.vonage.client.video.GetStreamResponse que puede utilizarse para consultar las propiedades de interés del 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 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 que se construye utilizando el patrón constructor, con el ID del flujo que se utiliza para identificar el flujo (este es un parámetro obligatorio). Utilice el parámetro 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 stream1a las clases de diseño 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);

En connectionId 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 forzosa y los códigos de excepción, consulte la página Documentación de la API REST.

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

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

En SignalRequest (construida utilizando el patrón constructor) tiene dos campos: type y dataambos obligatorios. Corresponden a los parámetros de tipo y datos pasados en los manejadores de recepción de señales del cliente. Asegúrese de que los parámetros 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 más información sobre señalización y códigos de excepción, consulte la sección Especificación de la API REST.

SIP

Conecta tu plataforma SIP a una sesión de vídeo de Vonage mediante la función 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. También puede especificar opcionalmente 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 sólo a un participante específico, utilice el método 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.