Connecteur vidéo

Vonage Video Connector vous permet de participer par programmation à des sessions de la Video API Vonage en tant que participant côté serveur. Il vous permet de vous connecter à des sessions vidéo, de publier et de vous abonner à des flux, et de traiter des données audio et vidéo en temps réel.

La bibliothèque gère automatiquement la connectivité WebRTC, le traitement des médias et la gestion des sessions, ce qui vous permet de vous concentrer sur la construction de votre logique d'application. sur la construction de votre logique d'application. L'audio est transmis sous forme de données PCM linéaires de 16 bits et la vidéo est transmise sous forme d'images de 8 bits aux formats YUV420P, RGB24 ou ARGB32. aux formats YUV420P, RGB24 ou ARGB32, à des fréquences d'échantillonnage, des résolutions et des configurations de canaux configurables.

Cette page décrit les concepts et le comportement communs à toutes les bibliothèques Video Connector. Pour obtenir des instructions d'installation, les signatures d'API et des exemples de code, consultez le guide correspondant à votre langage de programmation.

Choisissez votre bibliothèque

Ces deux bibliothèques offrent les mêmes fonctionnalités et s'appuient sur la même implémentation native. Elles se distinguent par leurs conventions de nommage et par la manière dont les opérations asynchrones sont mises en œuvre : la bibliothèque Python utilise des callbacks de fin d'exécution, tandis que la bibliothèque Node.js renvoie des « promises ». Cette page décrit les comportements qu'elles ont en commun.

Cette rubrique comprend les sections suivantes :

• Comment cela fonctionne-t-il ?
• Exigences
• Concepts fondamentaux
• Formats multimédias
• Configuration de la session
• Médias d'édition
• S'abonner à des flux
• Gestion de la mémoire tampon des médias
• Modèle d'événement
• Limites

Comment cela fonctionne-t-il ?

Le « Video Connector » rejoint une session en tant que participant WebRTC classique. Du point de vue des autres participants, il est impossible de le distinguer d’un navigateur ou d’un client mobile : il dispose de sa propre connexion, il peut diffuser un flux et s’abonner aux flux des autres.

La différence réside dans le fait que les données multimédias sont échangées avec le code de votre application plutôt qu’avec une caméra, un microphone ou un écran. Vous transmettez des trames audio et vidéo brutes au connecteur pour les publier, et vous recevez des données audio et vidéo brutes issues des flux auxquels vous êtes abonné. Le connecteur est donc particulièrement adapté aux charges de travail côté serveur telles que :

• Agents IA vocaux et vidéo en temps réel
• Transcription, traduction et sous-titrage en direct
• Enregistrement, archivage et capture à des fins de conformité
• Vision par ordinateur et modération de contenu
• Traitement des effets audio et vidéo

Le cycle de vie type est le suivant :

1. Connectez-vous à une session à l'aide de votre identifiant d'application, de votre identifiant de session et d'un jeton.
2. Publiez un flux, puis transmettez-y des trames audio et/ou vidéo.
3. Abonnez-vous aux flux des autres participants dès leur arrivée, puis traitez les fichiers multimédias que vous recevez.
4. Désabonnez-vous, supprimez la publication et déconnectez-vous lorsque vous avez terminé.

Exigences

Video Connector est fourni sous forme de bibliothèque native avec des binaires précompilés. Il fonctionne sur Linux sur x86_64 (AMD64) et ARM64 seulement.

Nous recommandons Debian Bookworm, car c'est la distribution sur laquelle le connecteur a été testé de la manière la plus approfondie.

Concepts fondamentaux

Video Connector utilise un petit ensemble d'objets pour représenter les sessions, les participants, les flux et les médias. Il est essentiel de bien comprendre ces concepts pour pouvoir utiliser efficacement l'une ou l'autre de ces bibliothèques.

Session

Une session de la Video API Vonage à laquelle les clients se connectent. La session est identifiée par son ID et est transmise aux gestionnaires d'événements au niveau de la session, ce qui vous permet d'identifier quelle session a déclenché un événement.

Connexion

La connexion d'un participant à une session. Chaque participant, y compris le connecteur lui-même, dispose d'exactement une connexion. Une connexion transporte :

• Un identifiant unique
• Un horodatage de création
• Les données de connexion, qui sont encodées dans le jeton utilisé pour établir la connexion

Les données de connexion permettent de stocker des métadonnées personnalisées concernant les participants, telles que leurs identifiants ou leurs rôles.

Flux

Un flux multimédia (audio, vidéo ou les deux) publié par un participant. Chaque flux possède un identifiant unique et une référence à la connexion qui l'a publié. Les flux vous sont signalés dès que les participants commencent à les publier, et ce sont à eux que vous vous abonnez pour recevoir les contenus multimédias.

Éditeur

Votre propre flux publié au cours de la session. Il n'y a qu'un seul éditeur par instance de connecteur. L'éditeur détient une référence au flux qu'il a créé ; c'est ainsi que les autres participants vous perçoivent.

Abonné

Un abonnement au flux d'un autre participant. Vous créez un abonné pour chaque flux dont vous souhaitez recevoir les données multimédias, et chaque abonné contient une référence au flux auquel il est abonné. Les événements multimédias et de sous-titrage sont transmis avec l'abonné qui les a générés, ce qui vous permet d'identifier le participant à l'origine des données.

Quel est le lien entre eux ?

Session
├── Connection (multiple participants)
│   └── Stream (participant's published media)
│       ├── Publisher (your published stream)
│       └── Subscriber (your subscription to their stream)
├── Audio data (flowing through streams)
└── Video frames (flowing through streams)

Formats multimédias

Audio

Les données audio sont toujours échangées sous la forme de PCM linéaire, entiers signés de 16 bits. Une trame audio correspond à un échantillon par canal ; un tampon doit donc contenir au moins (nombre de trames × nombre de canaux) échantillons.

• Taux d'échantillonnage: 8000, 12000, 16000, 24000, 32000, 44100, ou 48000 Hz
• Canaux: 1 (mono) ou 2 (stéréo)
• Taille du cadre: généralement par tranches de 20 ms, en fonction de la fréquence d'échantillonnage

La fréquence d'échantillonnage et le nombre de canaux sont configurables indépendamment pour le flux audio que vous publiez et le flux audio mixé que vous recevez. Voir Configuration de la session.

Vidéo

La vidéo est échangée sous la forme de Valeurs non signées sur 8 bits dans l'un des trois formats de pixels suivants :

• Résolutions: jusqu'à 1 920 × 1 080 (2 073 600 pixels au total)
• Taux de rafraîchissement: 1 à 30 images par seconde

Configuration de la session

Contenu audio destiné à la publication ou à l'abonnement

Ce connecteur vous permet de configurer deux formats audio indépendants :

• Fichier audio de l'éditeur définit le format des données audio que vous fournissez lors de la publication. Le fichier audio que vous envoyez doit respecter cette fréquence d'échantillonnage et ce nombre de canaux.
• Mixage audio des abonnés définit le format du flux audio mixé que vous recevez à partir de tous les flux auxquels vous êtes abonné. La bibliothèque gère le mixage de plusieurs participants ainsi que le rééchantillonnage ou la conversion des canaux afin de s'adapter au format que vous avez demandé.

Cette distinction vous permet d'optimiser la solution en fonction de votre cas d'utilisation. Par exemple :

• Publiez en stéréo pour obtenir un résultat de haute qualité tout en recevant un mixage mono afin de simplifier le traitement
• Émettre à 16 kHz pour la parole tout en recevant à 48 kHz pour une lecture haute fidélité
• Utiliser des débits différents de chaque côté pour répondre aux exigences d'un pipeline de traitement audio

Résolution et fréquence d'images recommandées pour les abonnés

Lors de l'abonnement à des flux acheminés utilisant la diffusion simultanée (simulcast), l'unité de transfert sélectif (SFU) de la Video API peut envoyer différentes couches de qualité pour la vidéo. Les paramètres de l'abonné vous permettent de demander une couche spécifique :

• Résolution préférée demande une couche géographique. Le SFU envoie la couche qui correspond le mieux.
• Fréquence d'images préférée demande une couche temporelle. Le SFU envoie la couche qui correspond le mieux.

Ces préférences permettent d'optimiser la bande passante et la charge de traitement côté abonné, en ne demandant que le niveau de qualité dont vous avez besoin, plutôt que de toujours recevoir la meilleure qualité disponible.

Migration de session

La migration de session peut être activée afin que le connecteur effectue automatiquement la migration en cas de rotation du SFU. Elle est désactivée par défaut.

Exploitation forestière

Le niveau de détail des messages de journalisation de la console est configurable selon cinq niveaux : ERROR, WARN, INFO, DEBUGet TRACE.

Médias d'édition

Un diffuseur doit diffuser du contenu audio, vidéo ou les deux. La configuration d'un diffuseur sans aucun de ces deux types de contenu constitue une erreur.

En attente de la disponibilité audio

Continuité audio

Lorsque vous publiez du contenu audio, la bibliothèque assure la diffusion en continu à votre place :

Première publication. La bibliothèque envoie du silence (trames remplies de zéros) jusqu'à ce que vous fournissiez vos premières données audio. Cela permet aux abonnés d'accéder immédiatement au flux, sans avoir à attendre que votre application génère du son.

Tolérance au silence. Si vous interrompez temporairement la diffusion audio, la bibliothèque tolère les brèves interruptions en ne transmettant tout simplement aucun paquet audio. Cette hystérésis évite l'envoi de paquets de silence inutiles en cas de retards de traitement momentanés.

Un silence explicite. À l'issue de la période de tolérance, si aucun nouveau flux audio n'est disponible, la bibliothèque passe à l'envoi de trames de silence explicites. Cela permet de maintenir le flux tout en indiquant qu'aucun flux audio actif n'est fourni.

Vider le tampon. Si vous fournissez une durée audio inférieure à une période complète, la bibliothèque efface les données restantes et les complète par du silence afin de préserver la synchronisation et d'éviter tout décalage audio.

Continuité vidéo

Lorsque vous publiez une vidéo, la bibliothèque gère pour vous la continuité des images :

Première publication. La bibliothèque envoie des trames noires jusqu'à ce que vous fournissiez votre première trame, de sorte que le flux soit immédiatement disponible pour les abonnés.

Répétition de la dernière image. Si vous cessez de fournir des images, la bibliothèque répète la dernière image que vous avez fournie pendant 2 secondes maximum, afin de garantir une lecture fluide pour les abonnés.

Solution de secours avec cadre noir. Au bout de 2 secondes de répétition, la bibliothèque passe à des images noires. Cela indique aux abonnés que la vidéo n'est plus diffusée activement, tout en maintenant le flux actif.

Meilleures pratiques

• Envoyez les données multimédia à intervalles réguliers, en fonction de la fréquence d'échantillonnage et de la fréquence d'images que vous avez configurées.
• Surveillez les statistiques relatives au tampon pour vous assurer que vous fournissez suffisamment de données
• Gérez l'événement « buffer-drained » pour détecter quand vos tampons multimédia sont vides
• Adaptez votre stratégie de création de contenu multimédia en fonction des variations de la charge de traitement

S'abonner à des flux

Lorsqu'un participant commence à diffuser du contenu, un événement « stream-received » se déclenche et vous décidez alors si vous souhaitez vous y abonner. Les contenus multimédias issus de vos abonnements sont diffusés via trois canaux distincts.

Vidéo est transmise par flux. Chaque image est accompagnée d'un identifiant de source, ce qui vous permet de traiter la vidéo de chaque participant de manière indépendante — que ce soit pour la gestion de la mise en page, l'enregistrement par flux ou l'application d' effets par flux.

Son mixé est diffusé sous la forme d'un flux unique au niveau de la session. La bibliothèque mélange automatiquement le son de tous les flux auxquels on est abonné en un seul flux, dans le format que vous avez configuré pour le mixage des abonnés. Il n'est pas possible de distinguer les différents participants dans ce flux audio mixé.

Audio individuel est diffusé par flux, au niveau de l'abonné. Cette fonctionnalité est actuellement disponible en version bêta. Le signal audio est transmis dans le format reçu du flux — PCM linéaire 16 bits — et ni la fréquence d'échantillonnage ni le nombre de canaux ne peuvent être configurés avant la réception.

Légendes sont diffusés par flux. Cette fonctionnalité est actuellement disponible en version bêta. Chaque événement de sous-titrage comprend l'identifiant de l'abonné, le flux source, le texte du sous-titre, ainsi que la mention indiquant si le résultat est définitif ou provisoire :

• Intérimaire Les résultats sont partiels et peuvent être mis à jour à mesure que de nouveaux extraits de discours sont traités. Utile pour un affichage en temps réel.
• Finale Les résultats sont définitifs et ne changeront plus. Utilisez-les pour le stockage ou le traitement en aval.

Gestion de la mémoire tampon des médias

Le connecteur gère des tampons internes pour les flux audio et vidéo que vous publiez. Vous pouvez vérifier à tout moment la quantité de contenus multimédias en file d'attente et vider ces deux tampons lorsque vous devez supprimer les contenus en attente — par exemple, lorsque vous interrompez un bot en plein milieu d'une phrase.

Événements de vidange du tampon

Un événement « buffer-drained » se déclenche lorsqu'un tampon audio ou vidéo interne est vide. Cela se produit lorsque le contenu multimédia est transmis à la session à un rythme plus rapide que celui auquel votre application le fournit. Considérez cet événement comme un signal vous invitant à augmenter votre débit de production de contenu multimédia ou à adapter votre stratégie de publication.

Cet événement utilise un mécanisme d'hystérésis pour éviter les déclenchements excessifs : après une première vidange, il ne se déclenchera plus tant que le tampon n'aura pas été réapprovisionné en nouveau contenu et ne se sera pas à nouveau vidé. Cela permet d'éviter un afflux de notifications répétées tant que le tampon reste vide.

Modèle d'événement

Ces deux bibliothèques proposent le même ensemble d'événements, regroupés en fonction de l'objet auquel ils appartiennent.

La manière dont ces événements sont mis en évidence varie selon le langage. En Python, chaque événement correspond à une fonction de rappel que vous enregistrez. Dans Node.js, les événements ponctuels du cycle de vie — connexion à une session, création d’un flux d’éditeur et connexion d’un abonné — sont traités par la promesse renvoyée par la méthode correspondante, tandis que les autres événements sont des fonctions de rappel. Consultez le guide du langage pour plus de détails.

Limites