Contraintes vidéo : Définition de la résolution et de la fréquence d'images préférées

La Video API de Vonage permet aux éditeurs d'optimiser les flux vidéo en définissant des contraintes préférentielles sur la résolution vidéo et la fréquence d'images. Ces contraintes permettent de gérer l'utilisation de la bande passante, de s'adapter aux capacités des appareils et d'offrir une expérience utilisateur personnalisée aux abonnés.

Ce guide explique comment utiliser le preferredResolution et preferredFrameRate API pour les éditeurs.

Vue d'ensemble

Lors de la publication d'un flux vidéo, vous pouvez vouloir ajuster dynamiquement la qualité vidéo pour diverses raisons : économies de bande passante, alignement sur les exigences de l'interface utilisateur ou restriction de la consommation de ressources pour certains rôles d'abonnés (tels que les vignettes ou les écrans à faible mouvement). L'API de l'éditeur de Vonage expose des méthodes qui vous permettent d'ajuster la résolution et la fréquence d'images préférées pour vos pistes vidéo. Ces contraintes sont appliquées au périphérique d'entrée vidéo à l'aide d'API WebRTC standard pour des résultats optimaux, mais elles influencent en fin de compte ce que tous les abonnés recevront.

Contrôle de la résolution vidéo et de la fréquence d'images

L'éditeur peut spécifier :

• Résolution préférée: Largeur et hauteur (en pixels) souhaitées pour le flux vidéo.
• Fréquence d'images préférée: Le nombre d'images par seconde (ips) souhaité pour le flux vidéo.

Vous pouvez les contrôler dynamiquement à l'aide des méthodes suivantes après l'éditeur est initialisé :

// Set preferred resolution (width x height)
await publisher.setPreferredResolution({ width: 640, height: 360 });

// Set preferred frame rate
await publisher.setPreferredFrameRate(15);

Définition de la résolution préférée

Méthode : publisher.setPreferredResolution(preferredResolution)

• preferredResolution est un objet avec width et height (tous deux entiers positifs, en pixels).
• La résolution ne peut pas être supérieure à la résolution de publication initiale. Par exemple, si vous avez publié à 640×480, vous ne pouvez pas définir une résolution supérieure.

Utilisation typique :

publisher.setPreferredResolution({ width: 320, height: 240 });

Validations :

• Doit être appelé sur un éditeur qui capture de la vidéo (publishVideo: true).
• Les deux width et height doivent être des nombres entiers positifs.
• La résolution ne peut être supérieure à la résolution initiale de la publication.

Cas d'erreur :

• Lance la procédure si elle est appelée sur un éditeur audio uniquement ou si les valeurs d'entrée ne sont pas valides.

Réglage de la fréquence d'images préférée

Méthode : publisher.setPreferredFrameRate(frameRate)

• frameRate doit être un nombre entier supérieur ou égal à 1.

Utilisation typique :

publisher.setPreferredFrameRate(15);

Validations :

• Doit être appelé sur un éditeur avec une piste vidéo active.
• La fréquence d'images doit être un nombre entier valide ≥ 1.

Cas d'erreur :

• Lance la procédure si elle est appelée sur un éditeur audio uniquement ou si frameRate n'est pas valide.

Meilleures pratiques

• Si vous connaissez à l'avance la résolution et la fréquence d'images idéales, définissez-les lors de la création du Publisher à l'aide de la fonction OT.initPublisher() (par exemple via resolution et frameRate). Pour les abonnés, vous pouvez omettre ces paramètres ou utiliser la fonction preferredResolution: 'auto' lors de l'appel Session.subscribe().
• Utiliser les API de l'abonné (subscriber.setPreferredResolution() / subscriber.setPreferredFrameRate()) pour modifier la manière dont un seul abonné reçoit/décode/rend un flux. Cela n'affecte que cet abonné et ne modifie pas ce que l'éditeur envoie ou ce que les autres abonnés reçoivent.
• Utilisez les API de l'éditeur (publisher.setPreferredResolution() / publisher.setPreferredFrameRate()) pour modifier ce que l'éditeur envoie. Cela affecte tous les abonnés à ce flux, qui recevront automatiquement les paramètres mis à jour. Vous pouvez réduire la résolution de l'éditeur à l'aide de la fonction preferredResolution dans plusieurs cas, comme par exemple :
  • Lorsque vous remarquez que l'appareil de l'éditeur est en difficulté, que ce soit en raison de limitations de l'unité centrale ou de problèmes de réseau, et que vous souhaitez alléger la pression plus rapidement que ne le ferait généralement la pile WebRTC.
  • Si la batterie de l'appareil est faible et que vous souhaitez minimiser la consommation d'énergie pour prolonger la durée de l'appel.
  • Lorsque vous lancez un partage d'écran ou des éditeurs supplémentaires à partir du même appareil et que vous devez libérer des ressources informatiques pour ces activités.
• La résolution et la fréquence d'images préférées de l'éditeur ne peuvent jamais dépasser les valeurs spécifiées lors de l'initialisation de l'éditeur. Initialisez le Publisher avec la résolution et la fréquence d'images maximales dont vous pourriez avoir besoin, puis réduisez ou augmentez dynamiquement ces limites en fonction de votre cas d'utilisation.
• Choisissez des fréquences d'images adaptées au contenu, par exemple :
  • 5 ips pour les diapositives statiques, les tableaux de bord, les écrans avec très peu de mouvement ou une utilisation minimale de la bande passante.
  • 15 ips pour les écrans à faible mouvement ou les scénarios sensibles à la bande passante
  • 30 ips pour les vidéos en pleine action ou les exigences de haute qualité
• Les conditions du réseau peuvent empêcher le SDK de maintenir la résolution et la fréquence d'images préférées. Traitez les valeurs préférées comme des objectifs : si la bande passante ou l'unité centrale est limitée, le SDK peut automatiquement réduire la qualité vidéo publiée/souscrite (par exemple, une préférence 1080p peut temporairement passer à une résolution inférieure en cas de mauvaises conditions de réseau).
• La résolution et la fréquence d'images préférées ne sont actuellement disponibles que dans le SDK JavaScript. Il n'y a pas de calendrier pour l'ajout de cette fonctionnalité dans d'autres SDK.

Notes complémentaires

• Les contraintes que vous fixez influencent tous les abonnés à votre flux, et pas seulement à l'interface utilisateur locale.
• Le réseau et le backend détermineront en fin de compte la qualité réelle de la vidéo diffusée, en fonction de la santé de la connexion et de la bande passante disponible.
• Ces API ne sont disponibles qu'avec le SDK JavaScript ; les autres SDK ne prennent pas en charge les modifications dynamiques des contraintes vidéo pour le moment.

Ressources complémentaires

• Flux de publication
• Documents de référence de l'éditeur
• Contraintes de MediaTrack WebRTC