Compartilhar via

Início Rápido: Definir restrições de vídeo em seu aplicativo de chamada

  • Artigo

Importante

A funcionalidade descrita neste artigo está atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Visão geral

A API de Restrições de Vídeo permite que os desenvolvedores controlem a qualidade do vídeo de dentro de suas chamadas de vídeo. Neste guia de início rápido, ilustramos como usar a API para definir as restrições.

Pré-requisitos

Consulte o guia de Início Rápido de Chamada de Voz para configurar um aplicativo de exemplo com chamada de voz.

Classes

Nome Descrição
VideoConstraints Usado para manter restrições de vídeo de entrada e restrições de vídeo de saída.
OutgoingVideoConstraints Usado para especificar restrições (MaxWidth | MaxHeight | MaxFrameRate) para fluxos de vídeo de saída.
IncomingVideoConstraints Usado para especificar restrições (MaxWidth | MaxHeight) para fluxos de vídeo de entrada.

Usando restrições de vídeo

As seções a seguir explicam como as restrições de vídeo podem ser definidas para fluxos de vídeo de entrada e/ou saída em diferentes momentos de uma chamada.

Definir restrições de vídeo antes de iniciar uma chamada

Para fluxos de vídeo de entrada, é necessário adicionar um IncomingVideoConstraints ao IncomingVideoOptions.

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

Para fluxos de vídeo de saída, é necessário adicionar um OutgoingVideoConstraints ao OutgoingVideoOptions.

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

Como as opções são usadas para iniciar/ingressar em uma chamada, as restrições podem ser aplicadas aos fluxos automaticamente. Por exemplo:

    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);

Definir restrições de vídeo durante uma chamada

Em vez de definir as restrições de vídeo antes de iniciar uma chamada, você também pode ajustar dinamicamente as restrições de vídeo durante uma chamada. Você precisa chamar SetVideoConstraints em sua Call classe de tipo e fornecer as restrições.


    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);

Para redefinir/remover as restrições de vídeo definidas anteriormente, você precisa seguir o padrão acima e fornecer 0 como um valor de restrição. Fornecer null valores para ou IncomingVideoConstraintsOutgoingVideoConstraints não redefinirá/removerá as restrições e as restrições com um null valor serão ignoradas.

Limitações

Observação

Verifique se você está ciente dessas limitações ao usar a API de Restrições de Vídeo. Algumas das limitações serão removidas em versões futuras.

Há algumas limitações conhecidas para a API de Restrições de Vídeo atual.

  • A restrição é uma restrição máxima , o que significa que o valor de restrição possível pode ser o valor especificado ou menor. Não há garantia de que o valor real permaneça o mesmo que especificado pelo usuário.

  • Quando o usuário define um valor de restrição muito pequeno, o SDK usará o menor valor disponível com suporte.

  • Para definir OutgoingVideoConstraints durante uma chamada, o fluxo de vídeo em andamento atual não coleta automaticamente as restrições especificadas. Para fazer com que as restrições entrem em vigor, você precisa parar e reiniciar o vídeo de saída.

  • IncomingVideoConstraints atualmente é uma restrição preferencial do usuário em vez de uma restrição rígida, o que significa que, dependendo da rede e do hardware, o valor real recebido ainda pode exceder o conjunto de restrições.

Estatísticas de mídia

Para avaliar e comparar a qualidade do vídeo depois de aplicar as restrições de vídeo, você pode acessar a API MediaStats para obter informações de resolução de vídeo e taxa de bits do fluxo. As estatísticas de mídia também incluem outras estatísticas granulares relacionadas aos fluxos, como tremulação, perda de pacotes, tempo de viagem de ida e volta, etc.

Importante

A funcionalidade descrita neste artigo está atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Visão geral

A API de Restrições de Vídeo permite que os desenvolvedores controlem a qualidade do vídeo de dentro de suas chamadas de vídeo. Neste guia de início rápido, ilustramos como usar a API para definir as restrições.

Pré-requisitos

Consulte o guia de Início Rápido de Chamada de Voz para configurar um aplicativo de exemplo com chamada de voz.

Classes

Nome Descrição
VideoConstraints Usado para manter restrições de vídeo de entrada e restrições de vídeo de saída.
OutgoingVideoConstraints Usado para especificar restrições (maxWidth | maxHeight | maxFrameRate) para fluxos de vídeo de saída.
IncomingVideoConstraints Usado para especificar restrições (maxWidth | maxHeight) para fluxos de vídeo de entrada.

Usando restrições de vídeo

As seções a seguir explicam como as restrições de vídeo podem ser definidas para fluxos de vídeo de entrada e/ou saída em diferentes momentos de uma chamada.

Definir restrições de vídeo antes de iniciar uma chamada

Para fluxos de vídeo de entrada, é necessário adicionar um IncomingVideoConstraints ao IncomingVideoOptions.

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

    // ...

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

Para fluxos de vídeo de saída, é necessário adicionar um OutgoingVideoConstraints ao OutgoingVideoOptions.

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

Como as opções são usadas para iniciar/ingressar em uma chamada, as restrições podem ser aplicadas aos fluxos automaticamente. Por exemplo:

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

Definir restrições de vídeo durante uma chamada

Em vez de definir as restrições de vídeo antes de iniciar uma chamada, você também pode ajustar dinamicamente as restrições de vídeo durante uma chamada. Você precisa chamar setVideoConstraints em sua Call classe de tipo e fornecer as restrições.


    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);

Para redefinir/remover as restrições de vídeo definidas anteriormente, você precisa seguir o padrão acima e fornecer 0 como um valor de restrição. Fornecer null valores para ou IncomingVideoConstraintsOutgoingVideoConstraints não redefinirá/removerá as restrições e as restrições com um null valor serão ignoradas.

Limitações

Observação

Verifique se você está ciente dessas limitações ao usar a API de Restrições de Vídeo. Algumas das limitações serão removidas em versões futuras.

Há algumas limitações conhecidas para a API de Restrições de Vídeo atual.

  • A restrição é uma restrição máxima , o que significa que o valor de restrição possível pode ser o valor especificado ou menor. Não há garantia de que o valor real permaneça o mesmo que especificado pelo usuário.

  • Quando o usuário define um valor de restrição muito pequeno, o SDK usará o menor valor disponível com suporte.

  • Para definir OutgoingVideoConstraints durante uma chamada, o fluxo de vídeo em andamento atual não coleta automaticamente as restrições especificadas. Para fazer com que as restrições entrem em vigor, você precisa parar e reiniciar o vídeo de saída.

  • IncomingVideoConstraints atualmente é uma restrição preferencial do usuário em vez de uma restrição rígida, o que significa que, dependendo da rede e do hardware, o valor real recebido ainda pode exceder o conjunto de restrições.

Estatísticas de mídia

Para avaliar e comparar a qualidade do vídeo depois de aplicar as restrições de vídeo, você pode acessar a API MediaStats para obter informações de resolução de vídeo e taxa de bits do fluxo. As estatísticas de mídia também incluem outras estatísticas granulares relacionadas aos fluxos, como tremulação, perda de pacotes, tempo de viagem de ida e volta, etc.

Importante

A funcionalidade descrita neste artigo está atualmente em versão prévia pública. Essa versão prévia é fornecida sem um contrato de nível de serviço e não é recomendada para cargas de trabalho de produção. Alguns recursos podem não ter suporte ou podem ter restrição de recursos. Para obter mais informações, consulte Termos de Uso Complementares de Versões Prévias do Microsoft Azure.

Visão geral

A API de Restrições de Vídeo permite que os desenvolvedores controlem a qualidade do vídeo de dentro de suas chamadas de vídeo. Neste guia de início rápido, ilustramos como usar a API para definir as restrições.

Pré-requisitos

Consulte o guia de Início Rápido de Chamada de Voz para configurar um aplicativo de exemplo com chamada de voz.

Classes

Nome Descrição
VideoConstraints Usado para manter restrições de vídeo de entrada e restrições de vídeo de saída.
OutgoingVideoConstraints Usado para especificar restrições (maxWidth | maxHeight | maxFrameRate) para fluxos de vídeo de saída.
IncomingVideoConstraints Usado para especificar restrições (maxWidth | maxHeight) para fluxos de vídeo de entrada.

Usando restrições de vídeo

As seções a seguir explicam como as restrições de vídeo podem ser definidas para fluxos de vídeo de entrada e/ou saída em diferentes momentos de uma chamada.

Definir restrições de vídeo antes de iniciar uma chamada

Para fluxos de vídeo de entrada, é necessário adicionar um IncomingVideoConstraints ao IncomingVideoOptions.

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

Para fluxos de vídeo de saída, é necessário adicionar um OutgoingVideoConstraints ao OutgoingVideoOptions.

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

    let outgoingVideoOptions = OutgoingVideoOptions()
    outgoingVideoOptions.constraints = outgoingVideoConstraints

Como as opções são usadas para iniciar/ingressar em uma chamada, as restrições podem ser aplicadas aos fluxos automaticamente. Por exemplo:

    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);

Definir restrições de vídeo durante uma chamada

Em vez de definir as restrições de vídeo antes de iniciar uma chamada, você também pode ajustar dinamicamente as restrições de vídeo durante uma chamada. Você precisa chamar set(videoConstraints) em sua Call classe de tipo e fornecer as restrições.


    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)

Para redefinir/remover as restrições de vídeo definidas anteriormente, você precisa seguir o padrão acima e fornecer 0 como um valor de restrição. Fornecer null valores para ou IncomingVideoConstraintsOutgoingVideoConstraints não redefinirá/removerá as restrições e as restrições com um null valor serão ignoradas.

Limitações

Observação

Verifique se você está ciente dessas limitações ao usar a API de Restrições de Vídeo. Algumas das limitações serão removidas em versões futuras.

Há algumas limitações conhecidas para a API de Restrições de Vídeo atual.

  • A restrição é uma restrição máxima , o que significa que o valor de restrição possível pode ser o valor especificado ou menor. Não há garantia de que o valor real permaneça o mesmo que especificado pelo usuário.

  • Quando o usuário define um valor de restrição muito pequeno, o SDK usará o menor valor disponível com suporte.

  • Para definir OutgoingVideoConstraints durante uma chamada, o fluxo de vídeo em andamento atual não coleta automaticamente as restrições especificadas. Para fazer com que as restrições entrem em vigor, você precisa parar e reiniciar o vídeo de saída.

  • IncomingVideoConstraints atualmente é uma restrição preferencial do usuário em vez de uma restrição rígida, o que significa que, dependendo da rede e do hardware, o valor real recebido ainda pode exceder o conjunto de restrições.

Estatísticas de mídia

Para avaliar e comparar a qualidade do vídeo depois de aplicar as restrições de vídeo, você pode acessar a API MediaStats para obter informações de resolução de vídeo e taxa de bits do fluxo. As estatísticas de mídia também incluem outras estatísticas granulares relacionadas aos fluxos, como tremulação, perda de pacotes, tempo de viagem de ida e volta, etc.

Você pode definir restrições de vídeo nas suas chamadas para controlar a qualidade do vídeo com base em resolution, frameRate ou bitrate nas chamadas de vídeo. Neste guia de início rápido, ilustramos como definir restrições de vídeo no início de uma chamada e como usar nosso método setConstraints no objeto de chamada para definir restrições de vídeo dinamicamente durante a chamada.

Enviar restrições de vídeo

O SDK de Chamada Web dos Serviços de Comunicação do Azure dá suporte à definição da resolução máxima de vídeo, taxa de quadros ou taxa de bits que um cliente envia. As restrições de vídeo do remetente têm suporte em navegadores da área de trabalho (Chrome, Edge, Firefox) e ao usar o navegador móvel iOS Safari ou o navegador móvel Android Chrome.

Restrições com suporte
Vídeo de entrada: resolução
Vídeo de saída: resolução, taxa de quadros, taxa de bits

Definindo restrições de vídeo no início de uma chamada - vídeo de saída (enviar)

A configuração de restrições de vídeo é implementada na interface Call. Para usar as Restrições de Vídeo, especifique as restrições em CallOptions ao fazer, aceitar uma chamada ou ingressar em uma. Você deve especificar localVideoStreams em videoOptions.
Observe que as restrições não funcionarão se você ingressar em uma chamada com a opção somente áudio e ativar a câmera mais tarde. Nesse caso, você pode definir restrições de vídeo dinamicamente usando o método setConstraints na 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)

Os tipos de restrições de vídeo são descritos da seguinte maneira:

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 constraint
     */
    bitrate?: MediaConstraintRange;
};

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

Ao definir restrições de vídeo, o SDK escolhe o valor mais próximo que se enquadra no conjunto de restrições para impedir que os valores de resolução, taxa de quadros e taxa de bits não excedam o conjunto máximo de valores de restrição. Além disso, quando o valor da restrição de resolução é muito pequeno, o SDK escolhe a menor resolução disponível. Nesse caso, a altura da resolução escolhida pode ser maior que o valor da restrição.

Observação

Em bitrate, frameHeight e frameRate, o valor da restrição é uma restrição max, o que significa que o valor real na chamada pode ser o valor especificado ou menor. Não há garantia de que a resolução do vídeo enviado permanecerá na resolução especificada.

O frameHeight em VideoSendConstraints tem um significado diferente quando um dispositivo móvel está no modo retrato. No modo retrato, esse valor indica o lado mais curto do dispositivo. Por exemplo, especificando frameHeight.max o valor com 240 em um dispositivo 1080(W) x 1920(H) no modo retrato, a altura da restrição está no lado 1080(W). Quando o mesmo dispositivo está no modo paisagem (1920(W) x 1080(H)), a restrição está no lado 1080(H).

Se você usar a API MediaStats para acompanhar a resolução de vídeo enviada, poderá descobrir que a resolução enviada pode ser alterada durante a chamada. Ele pode ir para cima e para baixo, mas deve ser igual ou menor do que o valor de restrição fornecido. Essa alteração de resolução é um comportamento esperado. O navegador também tem alguma regra de degradação para ajustar a resolução enviada com base nas condições de cpu ou de rede.

Definindo restrições de vídeo durante a chamada – vídeo de saída (enviar)

Você pode definir restrições de vídeo durante a chamada usando o método setConstraints no objeto 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
            }
        }
    }
});

Observação

Definir o valor da restrição como 0 removerá a definição das restrições definidas anteriormente. Use essa maneira para redefinir ou remover restrições.


Receber restrições de vídeo

Para controlar a resolução no lado do receptor usando o SDK de Chamada Web dos Serviços de Comunicação do Azure, você pode ajustar o tamanho do renderizador desse vídeo. O SDK de chamada ajusta automaticamente a resolução recebida com base nas dimensões do renderizador. O SDK não solicitará um fluxo de vídeo de entrada (largura e altura) que possa caber na janela de vídeo do renderizador.

Usando a estática de mídia para entender o impacto das restrições de vídeo

Para avaliar e comparar a qualidade do vídeo depois de aplicar as restrições de vídeo, você pode acessar a API MediaStats para obter informações de resolução de vídeo e taxa de bits do fluxo de envio. As estatísticas de mídia também incluem outras estatísticas granulares relacionadas aos fluxos, como tremulação, perda de pacotes, tempo de viagem de ida e volta, 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);
});

Próximas etapas

Para obter mais informações, consulte os seguintes artigos: