Démarrage rapide : Définir des contraintes vidéo dans votre application appelante

Vue d'ensemble

L’API Contraintes vidéo permet aux développeurs de contrôler la qualité vidéo à partir de leurs appels vidéo. Dans ce guide de démarrage rapide, nous expliquons comment utiliser l’API pour définir les contraintes.

Prérequis

Reportez-vous au Guide de démarrage rapide des appels vocaux pour configurer un exemple d’application avec les appels vocaux.

Classes

Utilisation de contraintes vidéo

Les sections suivantes expliquent comment les contraintes vidéo peuvent être définies pour les flux vidéo entrants et/ou sortants à différents moments d’un appel.

Définir des contraintes vidéo avant de commencer un appel

Pour les flux vidéo entrants, un IncomingVideoConstraints doit être ajouté à IncomingVideoOptions.

    var IncomingVideoOptions = new IncomingVideoOptions()
    {
        Constraints = new IncomingVideoConstraints() 
        { 
            MaxWidth = /*value*/, 
            MaxHeight = /*value*/ 
        },
        // other options
        // ...
    }

Pour les flux vidéo sortants, un OutgoingVideoConstraints doit être ajouté à OutgoingVideoOptions.

    var OutgoingVideoOptions = new OutgoingVideoOptions()
    {
        Constraints = new OutgoingVideoConstraints() 
        { 
            MaxWidth = /*value*/, 
            MaxHeight = /*value*/, 
            MaxFrameRate = /*value*/ 
        },
        // other options
        // ...
    }

Étant donné que les options sont utilisées pour démarrer/joindre un appel, les contraintes peuvent ensuite être appliquées automatiquement aux flux. Par exemple :

    var joinCallOptions = new JoinCallOptions()
    {
        IncomingVideoOptions = new IncomingVideoOptions()
        {
            Constraints = new IncomingVideoConstraints() 
            { 
                MaxWidth = /*value*/, 
                MaxHeight = /*value*/ 
            },
            // other options
            // ...
        },

        OutgoingVideoOptions = new OutgoingVideoOptions()
        {
            Constraints = new OutgoingVideoConstraints() 
            { 
                MaxWidth = /*value*/, 
                MaxHeight = /*value*/, 
                MaxFrameRate = /*value*/ 
            },
            // other options
            // ...
        }
    };
    await callAgent.JoinAsync(locator, joinCallOptions);

Définir des contraintes vidéo pendant un appel

Au lieu de définir les contraintes vidéo avant de commencer un appel, vous pouvez également ajuster dynamiquement les contraintes vidéo pendant un appel. Vous devez appeler SetVideoConstraints sur votre classe de type Call et fournir les contraintes.

    OutgoingVideoConstraints outgoingVideoConstraints = new OutgoingVideoConstraints()
    {
        outgoingVideoConstraints.MaxWidth = /*value*/ ;
        outgoingVideoConstraints.MaxHeight = /*value*/ ;
        outgoingVideoConstraints.MaxFrameRate = /*value*/ ;
    };
    
    IncomingVideoConstraints incomingVideoConstraints = new IncomingVideoConstraints()
    {
        incomingVideoConstraints.MaxWidth = /*value*/ ;
        incomingVideoConstraints.MaxHeight = /*value*/ ;
    };
  
    VideoConstraints constraints = new VideoConstraints();
    constraints.OutgoingVideoConstraints = outgoingVideoConstraints;
    constraints.IncomingVideoConstraints = incomingVideoConstraints;
    
    call.SetVideoConstraints(constraints);

Pour réinitialiser/supprimer les contraintes vidéo que vous avez définies précédemment, vous devez suivre le modèle ci-dessus et fournir 0 comme valeur de contrainte. Le fait de fournir des valeurs null pour IncomingVideoConstraints ou OutgoingVideoConstraints ne réinitialise pas/supprime les contraintes et les contraintes avec une valeur null sont ignorées.

Limites

Il existe certaines limitations connues de l’API Contraintes vidéo actuelle.

• La contrainte est une contrainte maximale, ce qui signifie que la valeur de contrainte possible peut être la valeur spécifiée ou inférieure. Il n’existe aucune garantie que la valeur réelle reste identique à celle spécifiée par l’utilisateur.

• Lorsque l’utilisateur définit une valeur de contrainte trop petite, le SDK utilise la plus petite valeur disponible prise en charge.

• Pour la configuration OutgoingVideoConstraints pendant un appel, le flux vidéo en cours ne récupère pas automatiquement les contraintes spécifiées. Pour que les contraintes prennent effet, vous devez arrêter et redémarrer la vidéo sortante.

• IncomingVideoConstraints est actuellement une contrainte préférée par l’utilisateur au lieu d’une contrainte dure, ce qui signifie que, en fonction de votre réseau et de votre matériel, la valeur réelle reçue peut toujours dépasser le jeu de contraintes.

Statistiques des médias

Pour évaluer et comparer la qualité vidéo après avoir appliqué les contraintes vidéo, vous pouvez accéder à l’API MediaStats pour obtenir des informations de résolution et de débit vidéo du flux. Les statistiques des médias incluent également d’autres statistiques granulaires liées aux flux, telles que la gigue, la perte de paquets, le temps d’aller-retour, etc.

Vue d'ensemble

L’API Contraintes vidéo permet aux développeurs de contrôler la qualité vidéo à partir de leurs appels vidéo. Dans ce guide de démarrage rapide, nous expliquons comment utiliser l’API pour définir les contraintes.

Prérequis

Reportez-vous au Guide de démarrage rapide des appels vocaux pour configurer un exemple d’application avec les appels vocaux.

Classes

Utilisation de contraintes vidéo

Les sections suivantes expliquent comment les contraintes vidéo peuvent être définies pour les flux vidéo entrants et/ou sortants à différents moments d’un appel.

Définir des contraintes vidéo avant de commencer un appel

Pour les flux vidéo entrants, un IncomingVideoConstraints doit être ajouté à IncomingVideoOptions.

    IncomingVideoConstraints incomingVideoConstraints = new IncomingVideoConstraints();
    incomingVideoConstraints.setMaxWidth(/*value*/);
    incomingVideoConstraints.setMaxHeight(/*value*/);

    // ...

    IncomingVideoOptions incomingVideoOptions = new IncomingVideoOptions();
    incomingVideoOptions.setConstraints(incomingVideoConstraints);

Pour les flux vidéo sortants, un OutgoingVideoConstraints doit être ajouté à OutgoingVideoOptions.

    OutgoingVideoConstraints outgoingVideoConstraints = new OutgoingVideoConstraints() 
    outgoingVideoConstraints.setMaxWidth(/*value*/); 
    outgoingVideoConstraints.setMaxHeight(/*value*/); 
    outgoingVideoConstraints.setMaxFrameRate(/*value*/); 
   
    // ...
    
    OutgoingVideoOptions outgoingVideoOptions = new OutgoingVideoOptions();
    outgoingVideoOptions.setConstraints(outgoingVideoConstraints);

Étant donné que les options sont utilisées pour démarrer/joindre un appel, les contraintes peuvent ensuite être appliquées automatiquement aux flux. Par exemple :

    JoinCallOptions joinCallOptions = new JoinCallOptions();
    joinCallOptions.setIncomingVideoOptions(incomingVideoOptions);
    joinCallOptions.setOutgoingVideoOptions(outgoingVideoOptions);
    callAgent.Join(context, locator, joinCallOptions);

Définir des contraintes vidéo pendant un appel

Au lieu de définir les contraintes vidéo avant de commencer un appel, vous pouvez également ajuster dynamiquement les contraintes vidéo pendant un appel. Vous devez appeler setVideoConstraints sur votre classe de type Call et fournir les contraintes.

    OutgoingVideoConstraints outgoingVideoConstraints = new OutgoingVideoConstraints();
    outgoingVideoConstraints.setMaxWidth(/*value*/); 
    outgoingVideoConstraints.setMaxHeight(/*value*/); 
    outgoingVideoConstraints.setMaxFrameRate(/*value*/); 
    
    IncomingVideoConstraints incomingVideoConstraints = new IncomingVideoConstraints();
    incomingVideoConstraints.setMaxWidth(/*value*/);
    incomingVideoConstraints.setMaxHeight(/*value*/);
  
    VideoConstraints constraints = new VideoConstraints();
    constraints.setOutgoingVideoConstraints(outgoingVideoConstraints);
    constraints.setIncomingVideoConstraints(incomingVideoConstraints);
    
    call.setVideoConstraints(constraints);

Pour réinitialiser/supprimer les contraintes vidéo que vous avez définies précédemment, vous devez suivre le modèle ci-dessus et fournir 0 comme valeur de contrainte. Le fait de fournir des valeurs null pour IncomingVideoConstraints ou OutgoingVideoConstraints ne réinitialise pas/supprime les contraintes et les contraintes avec une valeur null sont ignorées.

Limites

Il existe certaines limitations connues de l’API Contraintes vidéo actuelle.

• La contrainte est une contrainte maximale, ce qui signifie que la valeur de contrainte possible peut être la valeur spécifiée ou inférieure. Il n’existe aucune garantie que la valeur réelle reste identique à celle spécifiée par l’utilisateur.

• Lorsque l’utilisateur définit une valeur de contrainte trop petite, le SDK utilise la plus petite valeur disponible prise en charge.

• Pour la configuration OutgoingVideoConstraints pendant un appel, le flux vidéo en cours ne récupère pas automatiquement les contraintes spécifiées. Pour que les contraintes prennent effet, vous devez arrêter et redémarrer la vidéo sortante.

• IncomingVideoConstraints est actuellement une contrainte préférée par l’utilisateur au lieu d’une contrainte dure, ce qui signifie que, en fonction de votre réseau et de votre matériel, la valeur réelle reçue peut toujours dépasser le jeu de contraintes.

Statistiques des médias

Pour évaluer et comparer la qualité vidéo après avoir appliqué les contraintes vidéo, vous pouvez accéder à l’API MediaStats pour obtenir des informations de résolution et de débit vidéo du flux. Les statistiques des médias incluent également d’autres statistiques granulaires liées aux flux, telles que la gigue, la perte de paquets, le temps d’aller-retour, etc.

Vue d'ensemble

L’API Contraintes vidéo permet aux développeurs de contrôler la qualité vidéo à partir de leurs appels vidéo. Dans ce guide de démarrage rapide, nous expliquons comment utiliser l’API pour définir les contraintes.

Prérequis

Reportez-vous au Guide de démarrage rapide des appels vocaux pour configurer un exemple d’application avec les appels vocaux.

Classes

Utilisation de contraintes vidéo

Les sections suivantes expliquent comment les contraintes vidéo peuvent être définies pour les flux vidéo entrants et/ou sortants à différents moments d’un appel.

Définir des contraintes vidéo avant de commencer un appel

Pour les flux vidéo entrants, un IncomingVideoConstraints doit être ajouté à IncomingVideoOptions.

    let incomingVideoConstraints = IncomingVideoConstraints()
    incomingVideoConstraints.maxWidth = /*value*/ 
    incomingVideoConstraints.maxHeight = /*value*/ 
    
    // ...
    
    let incomingVideoOptions = IncomingVideoOptions()
    incomingVideoOptions.constraints = incomingVideoConstraints

Pour les flux vidéo sortants, un OutgoingVideoConstraints doit être ajouté à OutgoingVideoOptions.

    let outgoingVideoConstraints = OutgoingVideoConstraints()
    outgoingVideoConstraints.maxWidth = /*value*/ 
    outgoingVideoConstraints.maxHeight = /*value*/
    outgoingVideoConstraint.maxFrameRate = /*value*/ 
    
    // ...

    let outgoingVideoOptions = OutgoingVideoOptions()
    outgoingVideoOptions.constraints = outgoingVideoConstraints

Étant donné que les options sont utilisées pour démarrer/joindre un appel, les contraintes peuvent ensuite être appliquées automatiquement aux flux. Par exemple :

    let incomingVideoConstraints = IncomingVideoConstraints()
    incomingVideoConstraints.maxWidth = /*value*/ 
    incomingVideoConstraints.maxHeight = /*value*/ 
    let incomingVideoOptions = IncomingVideoOptions()
    incomingVideoOptions.constraints = incomingVideoConstraints
    
    let outgoingVideoConstraints = OutgoingVideoConstraints()
    outgoingVideoConstraints.maxWidth = /*value*/ 
    outgoingVideoConstraints.maxHeight = /*value*/
    outgoingVideoConstraint.maxFrameRate = /*value*/ 
    let outgoingVideoOptions = OutgoingVideoOptions()
    outgoingVideoOptions.constraints = outgoingVideoConstraints
    
    let joinCallOptions = new JoinCallOptions()
    joinCallOptions.incomingVideoOptions = incomingVideoOptions
    joinCallOptions.outgoingVideoOptions = outgoingVideoOptions

    callAgent.join(with: locator, joinCallOptions: joinCallOptions);

Définir des contraintes vidéo pendant un appel

Au lieu de définir les contraintes vidéo avant de commencer un appel, vous pouvez également ajuster dynamiquement les contraintes vidéo pendant un appel. Vous devez appeler set(videoConstraints) sur votre classe de type Call et fournir les contraintes.

    let outgoingVideoConstraints = OutgoingVideoConstraints()
    outgoingVideoConstraints.maxWidth = /*value*/ 
    outgoingVideoConstraints.maxHeight = /*value*/
    outgoingVideoConstraint.maxFrameRate = /*value*/ 
    
    let incomingVideoConstraints = IncomingVideoConstraints()
    incomingVideoConstraints.maxWidth = /*value*/ 
    incomingVideoConstraints.maxHeight = /*value*/ 
  
    let videoConstraints = VideoConstraints()
    videoConstraints.outgoingVideoConstraints = outgoingVideoConstraints
    videoConstraints.incomingVideoConstraints = incomingVideoConstraints
    
    call?.set(videoConstraints: videoConstraints)

Pour réinitialiser/supprimer les contraintes vidéo que vous avez définies précédemment, vous devez suivre le modèle ci-dessus et fournir 0 comme valeur de contrainte. Le fait de fournir des valeurs null pour IncomingVideoConstraints ou OutgoingVideoConstraints ne réinitialise pas/supprime les contraintes et les contraintes avec une valeur null sont ignorées.

Limites

Il existe certaines limitations connues de l’API Contraintes vidéo actuelle.

• La contrainte est une contrainte maximale, ce qui signifie que la valeur de contrainte possible peut être la valeur spécifiée ou inférieure. Il n’existe aucune garantie que la valeur réelle reste identique à celle spécifiée par l’utilisateur.

• Lorsque l’utilisateur définit une valeur de contrainte trop petite, le SDK utilise la plus petite valeur disponible prise en charge.

• Pour la configuration OutgoingVideoConstraints pendant un appel, le flux vidéo en cours ne récupère pas automatiquement les contraintes spécifiées. Pour que les contraintes prennent effet, vous devez arrêter et redémarrer la vidéo sortante.

• IncomingVideoConstraints est actuellement une contrainte préférée par l’utilisateur au lieu d’une contrainte dure, ce qui signifie que, en fonction de votre réseau et de votre matériel, la valeur réelle reçue peut toujours dépasser le jeu de contraintes.

Statistiques des médias

Pour évaluer et comparer la qualité vidéo après avoir appliqué les contraintes vidéo, vous pouvez accéder à l’API MediaStats pour obtenir des informations de résolution et de débit vidéo du flux. Les statistiques des médias incluent également d’autres statistiques granulaires liées aux flux, telles que la gigue, la perte de paquets, le temps d’aller-retour, etc.

Vous pouvez définir des contraintes vidéo dans vos appels pour contrôler la qualité vidéo en fonction de la résolution, du nombre d’images par seconde ou du débit de vos appels vidéo. Dans ce guide de démarrage rapide, nous expliquons comment définir des contraintes vidéo au début d’un appel et comment utiliser notre méthode setConstraints sur l’objet de l’appel pour définir des contraintes vidéo dynamiquement pendant l’appel.

Envoyer des contraintes vidéo

Le kit de développement logiciel (SDK) d’appel web Azure Communication Services prend en charge la définition de la résolution, de la fréquence d’images ou de la vitesse de transmission maximales d’une vidéo envoyée par un client. Les contraintes vidéo de l’expéditeur sont prises en charge sur les navigateurs de bureau (Chrome, Edge, Firefox) et lors de l’utilisation des navigateurs mobiles iOS Safari ou Android Chrome.

Définition de contraintes vidéo au début d’un appel : vidéo sortante (envoi)

Le paramètre de contraintes vidéo est implémenté sur l’interface Call. Pour utiliser les contraintes vidéo, vous pouvez spécifier les contraintes à partir de CallOptions lorsque vous effectuez un appel, acceptez un appel ou rejoignez un appel. Vous devez spécifier localVideoStreams dans videoOptions.
Notez que les contraintes ne fonctionnent pas si vous rejoignez un appel avec l’option audio uniquement et activez l’appareil photo ultérieurement. Dans ce cas, vous pouvez définir des contraintes vidéo dynamiquement à l’aide de la méthode setConstraints sur l’interface Call.

const callOptions = {
    videoOptions: {
        localVideoStreams: [...],
        constraints: {
            send: {
                bitrate: {
                    max: 575000
                },
                frameHeight: {
                    max: 240
                },
                frameRate: {
                    max: 20
                }
            }
        }
    },
    audioOptions: {
        muted: false
    }
};
// make a call
this.callAgent.startCall(identitiesToCall, callOptions);
// join a group call
this.callAgent.join({ groupId }, callOptions);
// accept an incoming call
this.incomingCall.accept(callOptions)

Les types de contraintes vidéo sont décrits comme suit :

export declare interface VideoOptions {
    localVideoStreams?: LocalVideoStream[];
    //video constraint when call starts
    constraints?: VideoConstraints;
};

export declare type VideoConstraints = {
    send?: VideoSendConstraints;
};

export type VideoSendConstraints = {
    /**
     * Resolution constraint
     */
    frameHeight?: MediaConstraintRange;

    /**
     * FrameRate constraint
     */
    frameRate?: MediaConstraintRange;

    /**
     * Bitrate constriant
     */
    bitrate?: MediaConstraintRange;
};

export declare type MediaConstraintRange = {
    max?: number;
};

Lors de la définition de contraintes vidéo, le kit de développement logiciel (SDK) choisit la valeur la plus proche qui se trouve dans le jeu de contraintes pour empêcher les valeurs de résolution, de fréquence d’images ou de vitesse de transmission de dépasser les valeurs des contraintes maximales définies. En outre, lorsque la valeur de la contrainte de résolution est trop petite, le kit de développement logiciel (SDK) choisit la plus petite résolution disponible. Dans ce cas, la hauteur de la résolution choisie peut être supérieure à la valeur de contrainte.

frameHeight dans VideoSendConstraints a une signification différente lorsqu’un appareil mobile est en mode portrait. En mode portrait, cette valeur indique le côté le plus court de l’appareil. Par exemple, si vous spécifiez frameHeight.max une valeur avec 240 sur un appareil 1080(W) x 1920(H) en mode portrait, la hauteur de la contrainte se trouve du côté 1080(W). Lorsque le même appareil est en mode paysage (1920(W) x 1080(H)), la contrainte se trouve du côté 1080(H).

Si vous utilisez l’API MediaStats pour suivre la résolution vidéo envoyée, vous pouvez constater que la résolution envoyée peut changer pendant l’appel. Elle peut monter ou descendre, mais doit être égale ou inférieure à la valeur de contrainte que vous fournissez. Ce changement de résolution est un comportement attendu. Le navigateur a également une règle de dégradation pour ajuster la résolution envoyée en fonction des conditions du processeur ou du réseau.

Définition de contraintes vidéo pendant un appel : vidéo sortante (envoi)

Vous pouvez définir des contraintes vidéo pendant l’appel en utilisant la méthode setConstraints sur l’objet Call.

// For eg, when you've started a call,
const currentCall = this.callAgent.startCall(identitiesToCall, callOptions);

// To set constraints during the call,
await currentCall.setConstraints({
    video: {
        send: {
            frameHeight: {
                max: 360
            },
            frameRate: {
                max: 15
            }
        }
    }
});

// To set only a particular constraint (the others will stay as what they were set before, if they were set)
await currentCall.setConstraints({
    video: {
        send: {
            bitrate: {
                max: 400000
            }
        }
    }
});

// To unset any constraint,
await currentCall.setConstraints({
    video: {
        send: {
            frameHeight: {
                max: 0
            }
        }
    }
});

Recevoir des contraintes vidéo

Pour contrôler la résolution côté récepteur à l’aide du kit de développement logiciel (SDK) d’appel web Azure Communication Services, vous pouvez adapter la taille du renderer de cette vidéo. Le kit de développement logiciel (SDK) appelant adapte automatiquement la résolution reçue en fonction des dimensions du renderer. Le kit de développement logiciel (SDK) ne demandera pas de flux vidéo entrant (largeur et hauteur) qui peut s’adapter à la fenêtre vidéo du renderer.

Utilisation de statiques médias pour comprendre l’impact des contraintes vidéo

Pour évaluer et comparer la qualité vidéo après avoir appliqué les contraintes vidéo, vous pouvez accéder à l’API MediaStats pour obtenir des informations de résolution et de débit vidéo du flux d’envoi. Les statistiques des médias incluent également d’autres statistiques granulaires liées aux flux, telles que la gigue, la perte de paquets, le temps d’aller-retour, etc.

const mediaStatsFeature = call.feature(Features.MediaStats);
const mediaStatsCollector = mediaStatsFeature.createCollector();

mediaStatsCollector.on('sampleReported', (sample: SDK.MediaStatsReportSample) => {
    // process the stats for the call.
    console.log(sample);
});