Contraintes vidéo de l'éditeur — Web

Une fois que vous avez initialisation d'un Publisher, vous pouvez définir la résolution et la fréquence d'images souhaitées pour la piste vidéo de sortie. Cela vous permet d'optimiser la bande passante et l'utilisation du processeur en fonction des différentes tailles d'interface utilisateur (vignettes, mosaïques, plein écran) et des appareils des abonnés.

Cette rubrique comprend les sections suivantes :

Comprendre les contraintes liées aux vidéos des éditeurs

L'éditeur peut faire la promotion d'un préféré résolution et fréquence d'images de sa piste vidéo : le SDK impose des contraintes au périphérique de capture et à la piste de sortie. Les abonnés bénéficient d'une bande passante et d'une charge CPU réduites lorsque l'éditeur définit des tailles plus petites ou des fréquences d'images plus faibles pour les petites cibles d'interface utilisateur. Notez que la qualité fournie peut être encore ajustée en fonction des capacités de l'appareil et des conditions du réseau.

Définition de la résolution souhaitée

Appeler publisher.setPreferredResolution(preferredResolution) pour définir les dimensions en pixels souhaitées :

await publisher.setPreferredResolution({ width: 640, height: 360 });
  • preferredResolution est un objet : { width: number, height: number }.
  • La résolution souhaitée ne doit pas dépasser la résolution de publication initiale.
  • S'applique uniquement lorsque l'éditeur enregistre une vidéo (publishVideo: true).

Génère une erreur si :

  • L'éditeur propose uniquement du contenu audio.
  • width ou height n'est pas un nombre entier positif.
  • La résolution demandée est supérieure à la résolution de publication initiale.
try {
  // If the initial publish was 640x480, this will throw:
  await publisher.setPreferredResolution({ width: 1920, height: 1080 });
} catch (error) {
  console.error('Failed to set preferred resolution:', error.message);
}

Définition de la fréquence d'images souhaitée

Appeler publisher.setPreferredFrameRate(frameRate) Pour définir une valeur de nombre d'images par seconde souhaitée :

await publisher.setPreferredFrameRate(15);
  • frameRate doit être un nombre entier positif (≥ 1).
  • Nécessite une piste vidéo active.

Génère une erreur si :

  • L'éditeur propose uniquement du contenu audio.
  • frameRate n'est pas un nombre entier valide ≥ 1.

Comment les contraintes influent-elles sur la livraison ?

Les contraintes préférentielles influencent la piste vidéo sortante pour tous les abonnés vers le flux. Toutefois, la résolution et la fréquence d'images finales diffusées peuvent être inférieures pour les raisons suivantes :

  • Limites des périphériques de capture
  • Limitations liées au navigateur ou au système d'exploitation
  • Conditions du réseau et choix adaptatifs en matière de médias

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 façon dont un abonné unique reçoit/décode/affiche un flux. Cela n'affecte que cet abonné et ne modifie en rien ce que l'éditeur envoie ni ce que reçoivent les autres abonnés.
  • Utilisez les API de l'éditeur (publisher.setPreferredResolution() / publisher.setPreferredFrameRate()) pour modifier ce que le Éditeur envoie. Cela concerne tous les abonnés à ce flux, qui recevront automatiquement les paramètres mis à jour. Vous pouvez souhaiter réduire la résolution de l'éditeur à l'aide de la méthode `preferredResolution` dans plusieurs cas, 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.
  • Utilisez des fréquences d'images adaptées :
    • 5 images par seconde — tableaux de bord statiques, diapositives, interfaces utilisateur sensibles à la bande passante
    • 15 images par seconde — contenu peu animé
    • 30 images par seconde — vidéo en plein écran / 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).
  • Ces API sont actuellement prises en charge uniquement dans le SDK JavaScript.

Exemples

// Lower quality for mobile users
if (isMobileUser) {
  publisher.setPreferredResolution({ width: 320, height: 180 });
  publisher.setPreferredFrameRate(15);
}

// Higher quality for desktop
if (isDesktopUser) {
  publisher.setPreferredResolution({ width: 1280, height: 720 });
  publisher.setPreferredFrameRate(30);
}

// Error when using resolution above initial publish
try {
  await publisher.setPreferredResolution({ width: 1920, height: 1080 }); // If initial was 640x480, throws error
} catch (error) {
  console.error(error.message);
}

// Debugging: Current track settings
const videoTrack = publisher.getVideoSource().track;
const { width, height, frameRate } = videoTrack.getSettings();
console.log('Current resolution:', width, 'x', height);
console.log('Current frame rate:', frameRate);

Dépannage

Gestion des erreurs

Encadrer les appels dans try/catch et afficher des messages clairs et compréhensibles lorsque les contraintes ne sont pas valides ou que l'environnement ne peut pas les satisfaire.

async function setPublisherQuality(publisher, preferredResolution, preferredFrameRate) {
  try {
    await publisher.setPreferredResolution(preferredResolution);
    await publisher.setPreferredFrameRate(preferredFrameRate);
  } catch (err) {
    showMessage('Unable to apply video constraints. Check your device and network.');
    console.error(err);
  }
}

Considérations relatives au réseau

Si le réseau est saturé, le pipeline multimédia peut réduire la résolution ou la fréquence d'images diffusées, quels que soient les paramètres définis. Envisagez de mettre en place des indicateurs dans l'interface utilisateur pour signaler les modes de qualité réduite.

Ressources supplémentaires