API de codecs vidéo préférés de l'éditeur

Un guide pratique pour définir les préférences de codec par éditeur, comprendre comment ces préférences interagissent avec la négociation et confirmer le codec réellement utilisé lors d'une session en direct.

Cette rubrique comprend les sections suivantes :

• Conditions préalables
• Vue d'ensemble
• Choisir un mode
• Ordres de codecs recommandés pour les scénarios courants
• Fonctionnement de la négociation des codecs
• Définition des préférences par plate-forme
• Verify the codec in use (vérifier le codec utilisé)
• Meilleures pratiques

Conditions préalables

Avant d'utiliser l'API Preferred Video Codec via le SDK, vous devez l'activer dans les paramètres de votre projet :

1. Allez sur le tableau de bord de l'API de Vonage et sélectionnez votre projet.
2. Dans les paramètres du projet, sélectionnez le codec vidéo préféré au niveau du projet.
3. Appliquez les paramètres requis pour activer les préférences de codec au niveau du SDK.

Vue d'ensemble

L'API du codec vidéo préféré de l'éditeur permet à chaque éditeur de déclarer sa propre priorité en matière de codec, indépendamment du codec préféré au niveau du projet configuré dans le fichier Tableau de bord Vonage. Vous pouvez soit fournir une liste explicite et ordonnée de codecs, soit déléguer la décision au SDK dans la rubrique mode automatique.

Utilisez cette API lorsque le paramètre au niveau du projet n'est pas suffisamment spécifique pour vos besoins. Les scénarios les plus courants sont les suivants :

• Sessions mixtes. Les différents éditeurs d'une même session bénéficient de codecs différents. Grâce aux préférences par éditeur, chaque appareil peut exprimer l'ordre des codecs qui lui convient le mieux.

• Éditeurs spécifiques à une fonctionnalité. Un éditeur de partage d'écran peut bénéficier de VP9, tandis qu'un éditeur de caméra dans la même session préfère VP8 pour une plus grande compatibilité.

• Laisser le SDK décider. Si vous ne souhaitez pas coder une liste en dur, le mode automatique délègue le choix au SDK.

Si tous les éditeurs de votre application doivent utiliser le même codec et que les paramètres au niveau du projet reflètent déjà ce choix, vous n'avez pas besoin de cette API.

VP8 est un codec dont la mise en œuvre est obligatoire et qui est pris en charge par tous les points d'extrémité. Étant donné que tous les codecs pris en charge sont automatiquement ajoutés en tant que solutions de repli, le VP8 est toujours disponible en tant que solution de repli ultime, même si vous ne l'incluez pas explicitement dans votre liste.

Pour en savoir plus sur les codecs VP8, H.264 et VP9, sur les tables de couverture des codecs et sur les paramètres des codecs préférés au niveau du projet, voir le document Codecs vidéo guide.

Choisir un mode

Automatique

Transmettre la chaîne de caractères 'automatic' (Web, React Native) ou appeler la méthode d'usine correspondante sur les SDK natifs. Le SDK évalue l'environnement local et détermine un ordre de priorité des codecs approprié.

Utilisez le mode automatique lorsque :

• Vous souhaitez que le SDK s'adapte aux différents navigateurs et appareils sans avoir à maintenir votre propre logique par appareil.
• Vous préférez une approche compatible avec l'avenir. Le mode automatique intégrera des heuristiques de sélection plus sophistiquées dans les prochaines versions du SDK, de sorte que les applications qui l'adoptent aujourd'hui bénéficieront des améliorations sans modification du code.

Manuel

Fournit un tableau ordonné de codecs. Le premier élément a la priorité la plus élevée :

['vp9', 'vp8']          prefer VP9, fall back to VP8, then remaining codecs
['h264']                 prefer H.264; remaining codecs (VP8, VP9) are appended automatically as fallbacks
['vp8', 'h264', 'vp9']  explicit full ordering: VP8 first, then H.264, then VP9

Utilisez le mode manuel lorsque vous savez exactement quel ordre de codec est le meilleur pour un éditeur ou un appareil donné. Ce paramètre remplace le codec préféré configuré dans le tableau de bord au niveau du projet.

Défaut

Si vous ne définissez pas preferredVideoCodecs l'éditeur utilise le codec préféré au niveau du projet, configuré dans le tableau de bord. Il s'agit du même comportement qu'avant l'existence de cette API.

Comparaison

Ordres de codecs recommandés pour les scénarios courants

Lorsque vous utilisez le mode manuel, l'ordre des codecs que vous fournissez dépend du type de session, du public et du cas d'utilisation. Le tableau ci-dessous répertorie les scénarios les plus courants avec une suggestion d'ordre des codecs. preferredVideoCodecs et le raisonnement qui la sous-tend.

Fonctionnement de la négociation des codecs

La définition d'un codec préféré pas ne garantit pas que le codec sera utilisé. Le codec final est déterminé par un processus de négociation qui dépend du type de session.

Sessions routées (Media Router)

Dans un session acheminéel'éditeur négocie avec le routeur média :

1. L'éditeur envoie une offre SDP avec des codecs classés en fonction des préférences (le codec préféré apparaît en premier).
2. Le routeur multimédia examine l'offre et sélectionne un codec qu'il prend en charge.
3. Si le codec préféré est pris en charge, il est utilisé. Dans le cas contraire, le routeur multimédia passe au codec suivant dans l'offre.

Comme le routeur multimédia se charge de la distribution des médias, tous les abonnés d'une session acheminée reçoivent une vidéo codée avec le même codec que celui négocié par l'éditeur.

Sessions relayées (peer-to-peer)

Dans un session relayéeIl n'y a pas de routeur de média. Chaque paire éditeur-abonné négocie indépendamment :

1. L'éditeur envoie une offre SDP avec des codecs classés par ordre de préférence.
2. L'abonné répond par une réponse SDP énumérant les codecs qu'il prend en charge.
3. La paire sélectionne le codec le plus prioritaire pris en charge par les deux points d'extrémité.

Cela signifie que différentes paires d'abonnés dans la même session relayée pourraient utiliser différents codecs, en fonction des capacités de chaque abonné.

Qu'est-ce qui peut provoquer un retour en arrière ?

Un repli signifie que le codec préféré n'a pas été utilisé et qu'un codec différent a été sélectionné pour la publication. Cela peut se produire dans les cas suivants

• Le codec préféré n'est pas pris en charge par le terminal distant (dans les sessions relayées) ou par le routeur de médias (dans les sessions routées).
• Le navigateur ou l'appareil ne prend pas en charge l'encodage avec le codec préféré (par exemple, H.264 sur certains appareils Android, VP9 sur les anciennes versions de Safari).

Étant donné que des retours en arrière peuvent se produire, vérifiez toujours le codec utilisé plutôt que de supposer que la préférence a été honorée. Connaître le codec actif vous aide :

• Déboguer et contrôler la qualité. Enregistrez le codec utilisé à des fins de diagnostic et d'analyse de la qualité via Insights.
• Adapter au moment de l'exécution. Ajustez les paramètres de résolution ou de débit en fonction des points forts du codec négocié (par exemple, VP9 peut atteindre la même qualité à un débit inférieur à VP8).
• Assurer la cohérence de la session. Confirmer que tous les éditeurs d'une session utilisent le codec prévu, en particulier dans les sessions routées où le routeur multimédia distribue un seul codec par éditeur à tous les abonnés.

Voir Verify the codec in use (vérifier le codec utilisé) pour obtenir des instructions spécifiques à la plate-forme.

Définition des préférences par plate-forme

SDK Web

La transmission d'un tableau vide ou d'une chaîne de codecs invalide entraîne l'échec de l'éditeur avec un message d'erreur OT_INVALID_PARAMETER erreur.

SDK iOS

SDK Android

// Automatic mode
PublisherKit.PreferredVideoCodecs preferredVideoCodecs =
    PublisherKit.PreferredVideoCodecs.automatic();

Publisher publisher = new Publisher.Builder(context)
    .preferredVideoCodecs(preferredVideoCodecs)
    .build();

// Manual mode
PublisherKit.PreferredVideoCodecs preferredVideoCodecs =
    PublisherKit.PreferredVideoCodecs.manual(
        new ArrayList<PublisherKit.PreferredVideoCodecs.Codec>(
            List.of(PublisherKit.PreferredVideoCodecs.Codec.VP9,
                    PublisherKit.PreferredVideoCodecs.Codec.H264)));

Publisher publisher = new Publisher.Builder(context)
    .preferredVideoCodecs(preferredVideoCodecs)
    .build();

Transmission d'un null ou une liste vide à manual() lancers IllegalArgumentException.

SDK Windows

La transmission d'une liste vide entraîne ArgumentException.

SDK Linux

SDK React Native

Verify the codec in use (vérifier le codec utilisé)

Après qu'un éditeur a commencé la diffusion en continu, utilisez les API statistiques du SDK pour confirmer quel codec a été effectivement négocié. Ne supposez pas que la préférence a été respectée.

Vérification des codecs pris en charge avant la publication

Vous pouvez vérifier de manière proactive les codecs pris en charge par un client avant de définir une préférence.

Web SDK :

SDK Android :

MediaUtils.SupportedCodecs supported =
    MediaUtils.SupportedCodecs.getSupportedCodecs(context);
Log.d("Codecs", "Encoders: " + supported.videoEncoders);
Log.d("Codecs", "Decoders: " + supported.videoDecoders);

SDK Linux :

Lecture du codec actif dans les statistiques du SDK

SDK Web

Éditeur :

Abonné :

Pour obtenir des informations de niveau inférieur sur WebRTC, utilisez getRtcStatsReport():

SDK Android

publisher.setNetworkStatsListener(new PublisherKit.NetworkStatsListener() {
    @Override
    public void onVideoStats(PublisherKit publisher,
                             PublisherKit.PublisherVideoStats[] statsArray) {
        if (statsArray != null && statsArray.length > 0) {
            for (PublisherKit.VideoLayerStats layer : statsArray[0].videoLayers) {
                Log.d("Codec", "Publisher codec: " + layer.codec);
            }
        }
    }
});

SDK iOS

SDK React Native

Utiliser Insights et Video Inspector

L'inspecteur vidéo affiche le codec, la résolution et la fréquence d'images dans le module Quality Metrics. Passez la souris sur n'importe quel point d'une ligne tracée pour voir le codec utilisé à ce moment-là.

Vous pouvez également filtrer les statistiques de flux par codec dans la rubrique Perspectives Requêtes GraphQL :

Meilleures pratiques

1. Tenez compte du type de session. Dans les sessions acheminées, tous les abonnés partagent un codec par éditeur. Dans les sessions relayées, chaque paire négocie indépendamment, de sorte que le même éditeur peut utiliser différents codecs avec différents abonnés.

2. Aligner les paramètres par éditeur et au niveau du projet. Le codec préféré au niveau du projet s'applique toujours aux éditeurs qui ne définissent pas leur propre préférence. Veillez à ce que les deux niveaux soient cohérents pour éviter les surprises.

3. Vérifier la prise en charge du codec par le client. Avant de définir une préférence manuelle, utilisez OT.getSupportedCodecs() (Web) ou MediaUtils.SupportedCodecs (Android) pour confirmer que le codec préféré est disponible localement.

4. Commencez par le mode automatique. À moins que vous n'ayez besoin d'un codec spécifique, utilisez le mode automatique et laissez le SDK choisir. Les prochaines versions du SDK affineront l'heuristique de sélection automatique, et votre application en bénéficiera sans modification du code.

5. Verify the negotiated codec. Utilisation getStats() ou getRtcStatsReport() pour confirmer le codec après le début de la publication.

6. Tester sur l'ensemble des dispositifs cibles. La prise en charge des codecs varie selon les navigateurs et les plateformes. Voir la page tableaux de couverture des codecs pour plus de détails. Testez la configuration de vos préférences sur les appareils réellement utilisés par vos utilisateurs.