Guia de início rápido: definir restrições de vídeo em seu aplicativo de chamada

Importante

A funcionalidade descrita neste artigo está atualmente em visualização pública. Esta versão de pré-visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Descrição geral

A API de restrições de vídeo permite que os desenvolvedores controlem a qualidade do vídeo a partir 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 chamadas de voz para configurar um aplicativo de exemplo com chamadas de voz.

Classes

Nome	Descrição
VideoRestrições	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 , um IncomingVideoConstraints precisa ser adicionado ao IncomingVideoOptions.

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

Para fluxos de vídeo de saída, um OutgoingVideoConstraints precisa ser adicionado 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/participar de 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 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 que você definiu anteriormente, você tem que 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á ignorado.

Limitações

Nota

Certifique-se de estar 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.

Existem 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 especificado pelo usuário.

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

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

• IncomingVideoConstraints atualmente é uma restrição preferida pelo usuário em vez de uma restrição rígida, o que significa que, dependendo da sua rede e hardware, o valor real recebido ainda pode exceder a restrição definida.

Estatísticas da 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 a resolução de vídeo e informações de taxa de bits do fluxo. As estatísticas de mídia também incluem outras estatísticas granulares relacionadas aos fluxos, como desvios, perda de pacotes, tempo de ida e volta, etc.

Importante

A funcionalidade descrita neste artigo está atualmente em visualização pública. Esta versão de pré-visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Descrição geral

A API de restrições de vídeo permite que os desenvolvedores controlem a qualidade do vídeo a partir 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 chamadas de voz para configurar um aplicativo de exemplo com chamadas de voz.

Classes

Nome	Descrição
VideoRestrições	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 , um IncomingVideoConstraints precisa ser adicionado 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, um OutgoingVideoConstraints precisa ser adicionado 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/participar de 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 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 que você definiu anteriormente, você tem que 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á ignorado.

Limitações

Nota

Certifique-se de estar 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.

Existem 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 especificado pelo usuário.

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

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

• IncomingVideoConstraints atualmente é uma restrição preferida pelo usuário em vez de uma restrição rígida, o que significa que, dependendo da sua rede e hardware, o valor real recebido ainda pode exceder a restrição definida.

Estatísticas da 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 a resolução de vídeo e informações de taxa de bits do fluxo. As estatísticas de mídia também incluem outras estatísticas granulares relacionadas aos fluxos, como desvios, perda de pacotes, tempo de ida e volta, etc.

Importante

A funcionalidade descrita neste artigo está atualmente em visualização pública. Esta versão de pré-visualização é fornecida sem um contrato de nível de serviço e não a recomendamos para cargas de trabalho de produção. Algumas funcionalidades poderão não ser suportadas ou poderão ter capacidades limitadas. Para obter mais informações, veja Termos Suplementares de Utilização para Pré-visualizações do Microsoft Azure.

Descrição geral

A API de restrições de vídeo permite que os desenvolvedores controlem a qualidade do vídeo a partir 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 chamadas de voz para configurar um aplicativo de exemplo com chamadas de voz.

Classes

Nome	Descrição
VideoRestrições	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 , um IncomingVideoConstraints precisa ser adicionado 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, um OutgoingVideoConstraints precisa ser adicionado 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/participar de 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) 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 que você definiu anteriormente, você tem que 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á ignorado.

Limitações

Nota

Certifique-se de estar 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.

Existem 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 especificado pelo usuário.

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

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

• IncomingVideoConstraints atualmente é uma restrição preferida pelo usuário em vez de uma restrição rígida, o que significa que, dependendo da sua rede e hardware, o valor real recebido ainda pode exceder a restrição definida.

Estatísticas da 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 a resolução de vídeo e informações de taxa de bits do fluxo. As estatísticas de mídia também incluem outras estatísticas granulares relacionadas aos fluxos, como desvios, perda de pacotes, tempo de ida e volta, etc.

Você pode definir restrições de vídeo em suas chamadas para controlar a qualidade do vídeo com base na resolução ou taxa de quadros ou taxa de bits em suas 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 setConstraints método 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 são suportadas em navegadores de desktop (Chrome, Edge, Firefox) e ao usar o navegador móvel iOS Safari ou o navegador móvel Android Chrome.

Restrições suportadas
Vídeo recebido: resolução Vídeo de saída: resolução, framerate, bitrate

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

A configuração de restrições de vídeo é implementada Call na interface. Para usar as Restrições de vídeo, você pode especificar as restrições de dentro CallOptions quando fizer uma chamada, aceitar uma chamada ou participar de uma chamada. Você deve especificar localVideoStreams em videoOptions.
Observe que as restrições não funcionam se você participar de uma chamada com a opção somente áudio e ligar a câmera mais tarde. Nesse caso, você pode definir restrições de vídeo dinamicamente usando o setConstraintsCall método na interface.

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 forma:

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

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, frameRate e bitrate não excedam os valores máximos de restrição definidos. 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 do que o valor da restrição.

Nota

Para todos bitrate, frameHeight e frameRate, o valor de restrição é uma max restrição, 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 de vídeo enviada permanecerá na resolução especificada.

O frameHeight in 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 rastrear a resolução de vídeo enviada, poderá descobrir que a resolução enviada pode mudar durante a chamada. Ele pode subir e descer, mas deve ser igual ou menor do que o valor de restrição fornecido. Esta 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 na CPU ou nas condições da rede.

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

Você pode definir restrições de vídeo durante a chamada usando o setConstraints método no Call objeto.

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

Nota

Definir o valor de restrição como 0 irá desdefinir quaisquer restrições definidas anteriormente. Você pode usar essa maneira para redefinir ou remover restrições.

Receber restrições de vídeo

Para controlar a resolução no lado do recetor usando o SDK de Chamada na 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 a resolução de vídeo e informações de taxa de bits do fluxo de envio. As estatísticas de mídia também incluem outras estatísticas granulares relacionadas aos fluxos, como desvios, perda de pacotes, tempo 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óximos passos

Para obter mais informações, consulte os seguintes artigos que podem estar em inglês:

• Saiba mais sobre o documento de conceito de Restrições de vídeo
• Saiba mais sobre os recursos do SDK de chamada