SDK du serveur Java

Le SDK Java de Vonage fournit des méthodes pour :

Installation

L'API Video a été ajoutée dans la version 8.0.0 du SDK en 2023, bien qu'il soit recommandé d'utiliser la dernière version pour la sécurité, les corrections de bogues et les fonctionnalités ajoutées dans les versions ultérieures.

Maven Central :

La meilleure façon d'ajouter le SDK Vonage Java Server à votre projet est d'ajouter la dépendance au système de construction de votre projet. Les instructions sont disponibles sur le site Repo GitHub ainsi que Maven Central pour Maven, Gradle, Ivy, SBT, Leiningen, etc.

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.vonage</groupId>
    <artifactId>server-sdk</artifactId>
    <version>9.3.1</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 {
  implementation 'com.vonage:server-sdk:9.+'
}

Utilisation

Le SDK Java de Vonage vous permet d'utiliser API REST de Vonage à l'aide de ses sous-clients, un pour chaque API. Pour travailler avec l'API Video API, utiliser le com.vonage.client.video.VideoClient classe. Elle contient des méthodes pour tous les points de terminaison pris en charge dans la spécification de l'API. Vous pouvez l'obtenir en appelant la classe getVideoClient() méthode de VonageClient.

Initialisation

Initialiser un com.vonage.client.VonageClient avec votre ID d'application vidéo et votre clé privée. Cet objet renvoie un objet contenant toutes les méthodes nécessaires pour travailler avec l'API Video.

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

Générer des jetons

Votre application Vonage Video aura besoin d'un jeton côté client pour être utile. Ce jeton peut être généré par le SDK du serveur via la fonction VideoClient#generateToken(String sessionId, TokenOptions options) méthode. Vous devrez transmettre l'identifiant de la session, mais la méthode options n'est pas obligatoire (il peut être nul, ou vous pouvez appeler la fonction VideoClient#generateToken(String sessionId) pour plus de commodité). La méthode renvoie un JWT signé avec les revendications appropriées, sous la forme d'une chaîne encodée en Base64 que vous pouvez transmettre au client.

String jwt = videoClient.generateToken(sessionId);

Par défaut, le jeton aura un délai d'expiration de 24 heures et le rôle sera défini comme "éditeur" (com.vonage.video.client.Role#PUBLISHER). Le délai d'expiration maximal autorisé est de 30 jours. Vous pouvez les définir à l'aide de la fonction TokenOptions qui utilise le modèle du constructeur. Vous pouvez également définir les métadonnées de connexion, qui ne doivent pas dépasser 1000 caractères.

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

Voir le guide de création de jetons pour une explication plus détaillée des options de configuration.

Création de sessions

Pour créer une session vidéo Vonage, utilisez la fonction VideoClient#createSession(CreateSessionRequest request) méthode. La méthode request est facultatif et sert à spécifier :

  • Si la session utilise le routeur vidéo de Vonage
  • Un indice d'emplacement pour le serveur vidéo de Vonage.
  • Si la session est automatiquement archivée.

Comme pour la plupart des autres propriétés de requête, le modèle de construction est utilisé. Pour l'instanciation, commencez par la propriété statique builder() définir les propriétés et appeler la méthode build() pour construire une instance.

Si la demande a abouti, un message CreateSessionResponse est renvoyée. La propriété la plus utile est l'identifiant de la session, qui peut être obtenu en appelant la fonction getSessionId() (méthode). Vous pouvez conserver l'identifiant de session pour un usage ultérieur, car il s'agit d'un paramètre commun pour d'autres appels de méthode.

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

Travailler avec les archives

Vous ne pouvez archiver que les sessions qui utilisent le routeur vidéo de Vonage (c.-à-d. les sessions dont le mode média est réglé sur MediaMode.ROUTED). Pour plus d'informations sur l'archivage, voir la page Vonage Archivage vidéo guide du développeur.

Créer une archive

Vous pouvez lancer manuellement l'enregistrement d'une session vidéo Vonage à l'aide du bouton createArchive(Archive request) (méthode d'analyse des données). En cas de succès, des propriétés supplémentaires seront renseignées dans le fichier com.vonage.client.video.Archive avec la réponse du serveur.

Notez que vous ne pouvez lancer une archive que sur une session à laquelle des clients sont connectés. Les Archive suit le modèle de construction du constructeur. Toutes les propriétés, à l'exception de l'identifiant de la session, sont facultatives, d'où l'utilisation de l'attribut Archive.builder(String sessionId) requiert ce paramètre.

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

Vous pouvez également désactiver l'enregistrement audio ou vidéo en appelant la fonction hasAudio(false) ou hasVideo(false) les méthodes d'un Archive constructeur.

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

En réglant le mode de sortie sur OutputMode.INDIVIDUAL permet d'enregistrer chaque flux de l'archive dans son propre fichier :

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

Les 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. Si vous définissez l'option resolution et définit également la propriété outputMode à la propriété OutputMode.INDIVIDUAL, le build() lancera un IllegalStateException.

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

Arrêter l'enregistrement

Vous pouvez arrêter l'enregistrement d'une archive commencée à l'aide de la touche VideoClient#stopArchive(String archiveId) méthode.

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

Supprimer une archive

Pour supprimer une archive, utilisez la fonction VideoClient#deleteArchive(String archiveId) méthode.

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

Récupérer une seule archive

Pour obtenir un individu Archive (et toutes les informations la concernant) à partir d'un ID d'archive, utilisez la commande VideoClient#getArchive(String archiveId) méthode.

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

Récupérer plusieurs archives

Vous pouvez obtenir une liste de toutes les Applications que vous avez créées (jusqu'à 1000) dans votre application en utilisant la fonction VideoClient#listArchives() méthode. Pour filtrer les résultats renvoyés, appelez la méthode VideoClient#listArchives(ListArchivesRequest request) à la place. L'objet de la requête est construit en utilisant le modèle du constructeur et possède trois paramètres optionnels :

  • sessionId: permet de limiter les résultats aux archives associées à une session spécifique.
  • count: limite le nombre de résultats renvoyés.
  • offset: rejette un nombre initial de résultats (utile lorsqu'il y a plus de 1000 archives).

Un IllegalArgumentException sera lancé si le offset ou count sont négatifs ou si les count est supérieur à 1000. La liste résultante de Archiveseront en date/heure dans l'ordre, du plus récent au plus ancien.

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

Vous pouvez également récupérer la liste des archives pour un identifiant de session spécifique, et éventuellement utiliser les paramètres offset et count comme décrit ci-dessus.

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

Définir la mise en page de l'archive

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 VideoClient#setArchiveLayout(String archiveId, ArchiveLayout layout) méthode.

Vous pouvez également définir la mise en page lors de la création de l'archive (voir Archive.Builder#layout(ArchiveLayout layout)). Voir aussi Personnalisation de la présentation vidéo pour les archives composées pour plus d'informations.

Utiliser le ArchiveProperties comme suit :

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

Pour les mises en page personnalisées, vous devez spécifier la feuille de style (en CSS) :

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

Vous pouvez également définir le type de mise en page lors d'un partage d'écran, la mise en page initiale étant alors définie comme suit ScreenLayoutType.BEST_FIT:

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

Ajouter un flux à une archive

Vous pouvez ajouter un flux à une archive composée qui a été lancée avec la commande streamMode fixé à StreamMode.MANUAL en utilisant le VideoClient#addArchiveStream(String archiveId, String streamId) en passant par la méthode ID de l'archive et ID du flux que vous souhaitez ajouter à l'archive, respectivement.

Les VideoClient#addArchiveStream(String archiveId, String streamId, Boolean audio, Boolean video) La variante de cette méthode permet d'activer ou de désactiver l'audio et la vidéo.

Par défaut, les deux sont activés (c.-à-d. true). false pour les audio désactivera l'audio, tandis que le paramètre false pour la vidéo désactivera la vidéo (ce qui se traduira par un flux audio uniquement). La définition de l'une ou l'autre de ces valeurs à null est équivalent à la valeur par défaut (c.-à-d. true dans les deux cas).

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

Supprimer un flux d'une archive

Vous pouvez supprimer un flux d'une archive composée à l'aide de la fonction VideoClient#removeArchiveStream(String archiveId, String streamId) méthode. Comme pour l'ajout d'un flux, l'archive doit avoir été lancée avec la méthode streamMode sur "manuel".

videoClient.removeArchiveStream(archiveId, streamId);

Travailler avec des diffusions

Travailler avec des émissions en direct est très similaire à travailler avec des archives.

Liste de toutes les émissions en direct

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

Obtenir des détails sur une diffusion spécifique

Broadcast broadcast = videoClient.getBroadcast(broadcastId);

Lancer une diffusion en direct

Pour lancer avec succès la diffusion d'une session, au moins un client doit être connecté à la session. La diffusion en direct peut cibler un point d'extrémité HLS et jusqu'à cinq serveurs RTMP simultanément pour une session. L'identifiant de la session est requis et au moins un flux de sortie (RTMP et/ou HLS) doit être spécifié.

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

Arrêter l'enregistrement d'une émission

Broadcast broadcast = videoClient.stopBroadcast(broadcastId);

Changement dynamique du type de mise en page d'une diffusion en direct

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

Ajouter ou supprimer un flux dans une diffusion en direct

Modifier les flux inclus dans une diffusion qui a été lancée avec la valeur streamMode fixée à SteamMode.MANUAL:

videoClient.addBroadcastStream(broadcastId, streamId);

videoClient.removeBroadcastStream(broadcastId, streamId);

Travailler avec des flux

Vous pouvez obtenir des informations sur un flux en appelant la fonction VideoClient#getStream(String sessionId, String streamId) méthode. Si la demande a abouti, un message com.vonage.client.video.GetStreamResponse sera renvoyée, qui peut être utilisée pour interroger les propriétés d'intérêt relatives au flux.

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

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

Vous pouvez obtenir des informations sur tous les flux d'une session à l'aide de la fonction VideoClient#listStreams(String sessionId) méthode. Celle-ci renverra un List de GetStreamResponse que vous pouvez parcourir pour trouver l'information que vous recherchez.

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

Définir la disposition des flux

Vous pouvez modifier les classes de présentation d'un flux à l'aide de la fonction VideoClient#setStreamLayout(String sessionId, List<SessionStream> streams) Cette méthode prend en entrée l'identifiant de la session et la liste des flux à modifier. Cette méthode prend en entrée l'identifiant de la session et la liste des flux à modifier. Chaque flux est représenté par un SessionStream qui est construit selon le modèle du constructeur, l'ID du flux étant utilisé pour identifier le flux (il s'agit d'un paramètre obligatoire). Utiliser le modèle SessionStream.Builder#layoutClassList(List<String> layoutClassList) pour définir les dispositions du flux (ou la variante varargs pour plus de commodité). Pour illustrer notre propos, supposons que nous ayons deux flux, appelons-les stream1 et stream2. Supposons que stream1Id et stream2Id sont des chaînes avec les ID de stream1 et stream2 respectivement, et que l'on souhaite mettre en place stream1aux classes de mise en page de full et focusmais stream2à min.

Voici comment y parvenir :

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

videoClient.setStreamLayout(sessionId, stream1, stream2);

La modération

Déconnexion des clients

Votre serveur d'application peut déconnecter un client d'une session vidéo Vonage en appelant la fonction VideoClient#forceDisconnect(String sessionId, String connectionId) méthode.

videoClient.forceDisconnect(sessionId, connectionId);

Les connectionId est utilisé pour spécifier l'identifiant de connexion d'un client connecté à 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 VideoClient#muteStream(String sessionId, String streamId) méthode.

videoClient.muteStream(sessionId, streamId);

Vous pouvez forcer l'éditeur de tous les flux d'une session (à l'exception d'une liste facultative de flux) à cesser de publier de l'audio à l'aide de la commande VideoClient#muteSession(String sessionId, boolean active, String... excludedStreamIds) méthode. La méthode active détermine si les flux existants et nouveaux seront mis en sourdine par défaut. Le paramètre optionnel excludedStreamIds permet d'indiquer les flux à exclure de cette demande de mise en sourdine.

videoClient.muteSession(sessionId, true);

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

Signalisation

Vous pouvez envoyer des signaux à tous les participants d'une session à l'aide de la fonction VideoClient#signalAll(String sessionId, SignalRequest request) méthode. Pour signaler un participant spécifique, utilisez la méthode VideoClient#signal(String sessionId, String connectionId, SignalRequest request) à la place.

Les SignalRequest (construite à l'aide du modèle du constructeur) comporte deux champs : type et dataqui sont tous deux obligatoires. Ils correspondent aux paramètres de type et de données transmis dans les gestionnaires de signaux reçus par le client. Assurez-vous que les paramètres type ne dépasse pas la longueur maximale (128 octets) et que la chaîne de caractères data ne dépasse pas la longueur maximale (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);

Pour plus d'informations sur la signalisation et les codes d'exception, reportez-vous à la section Spécification de l'API REST.

SIP

Connectez votre plateforme SIP à une session vidéo Vonage à l'aide de la fonction VideoClient#sipDial(SipDialRequest request) méthode. Vous devez fournir l'URI, le sessionId et le token dans la demande. Vous pouvez spécifier si la négociation entre Vonage et le point de terminaison SIP sera effectuée de manière sécurisée (en utilisant TLS) en définissant l'option secure paramètre de SipDialRequest.Builder#uri(URI uri, boolean secure) à true. Vous pouvez également spécifier un nom d'utilisateur et un mot de passe pour l'authentification dans la demande.

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

SipDialResponse parsed = videoClient.sipDial(request);

Vous pouvez diffuser des tonalités DTMF à tous les participants d'un appel à l'aide de la touche VideoClient#sendDtmf(String sessionId, String digits) méthode. Pour envoyer des tonalités à un participant spécifique uniquement, utilisez la méthode VideoClient#sendDtmf(String sessionId, String connectionId, String digits) à la place.

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

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

Exigences

Vous avez besoin d'un identifiant et d'une clé privée pour l'In-App Video de Vonage, que vous pouvez obtenir en vous connectant à vos Compte Video API de Vonage.

Le SDK Java de Vonage nécessite le JDK 8 ou une version plus récente pour être compilé. L'exécution nécessite Java SE 8 ou une version plus récente.

Notes de mise à jour

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