Compartir vía

Inicio rápido: establecimiento de restricciones de vídeo en la aplicación de llamadas

  • Artículo

Importante

La funcionalidad descrita en este artículo se encuentra actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin un Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Información general

La API de restricciones de vídeo permite a los desarrolladores controlar la calidad del vídeo desde sus videollamadas. En esta guía de inicio rápido, se muestra cómo usar la API para establecer las restricciones.

Requisitos previos

Consulte el inicio rápido de llamadas de voz para configurar una aplicación de ejemplo con llamadas de voz.

Clases

NOMBRE Descripción
VideoConstraints Se usa para contener restricciones de vídeo entrantes y restricciones de vídeo salientes.
OutgoingVideoConstraints Se usa para especificar restricciones (MaxWidth | MaxHeight | MaxFrameRate) para secuencias de vídeo salientes.
IncomingVideoConstraints Se usa para especificar restricciones (MaxWidth | MaxHeight) para secuencias de vídeo entrantes.

Uso de las restricciones de vídeo

En las secciones siguientes se explica cómo establecer las restricciones de vídeo para las secuencias de vídeo entrantes o salientes en diferentes momentos de una llamada.

Establecimiento de restricciones de vídeo antes de iniciar una llamada

En el caso de las secuencias de vídeo entrantes, hay que agregar IncomingVideoConstraints a IncomingVideoOptions.

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

En el caso de las secuencias de vídeo salientes, hay que agregar OutgoingVideoConstraints a OutgoingVideoOptions.

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

Dado que las opciones se usan para iniciar una llamada o unirse a ella, las restricciones se pueden aplicar automáticamente a las secuencias. Por ejemplo:

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

Establecimiento de restricciones de vídeo durante una llamada

En lugar de establecer las restricciones de vídeo antes de iniciar una llamada, también se pueden ajustar dinámicamente las restricciones de vídeo durante la llamada. Debe llamar a SetVideoConstraints en la clase de tipo Call y proporcionar las restricciones.


    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 restablecer o quitar las restricciones de vídeo establecidas anteriormente, debe seguir el patrón anterior y proporcionar 0 como valor de restricción. Si se proporciona valores null para IncomingVideoConstraints o OutgoingVideoConstraints, no se restablecerán ni quitarán las restricciones, pero se omitirán las restricciones con valor null.

Limitaciones

Nota:

Tenga en cuenta estas limitaciones al usar la API de restricciones de vídeo. Algunas de las limitaciones se quitarán en futuras versiones.

Hay algunas limitaciones conocidas en la API de restricciones de vídeo actual.

  • La restricción es una restricción máxima, lo que significa que el valor de restricción posible puede ser el valor especificado o uno menor. No hay ninguna garantía de que el valor real siga siendo el mismo que el especificado por el usuario.

  • Si el usuario establece un valor de restricción demasiado pequeño, el SDK usará el valor disponible más pequeño que se admita.

  • Para establecer OutgoingVideoConstraints durante una llamada, la secuencia de vídeo en curso actual no recoge automáticamente las restricciones especificadas. Para que las restricciones surtan efecto, debe detener y reiniciar el vídeo saliente.

  • IncomingVideoConstraints es actualmente una restricción preferida por el usuario en lugar de una restricción estricta, lo que significa que, en función de la red y el hardware, el valor real recibido puede superar la restricción establecida.

Estadísticas multimedia

Para evaluar y comparar la calidad del vídeo tras aplicar las restricciones de vídeo, se puede acceder a la API de MediaStats para obtener la información de velocidad de bits y resolución de vídeo de la secuencia. Las estadísticas multimedia también incluyen otras estadísticas pormenorizadas relacionadas con las secuencias, como inestabilidad, pérdida de paquetes, recorrido de ida y vuelta, etc.

Importante

La funcionalidad descrita en este artículo se encuentra actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin un Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Información general

La API de restricciones de vídeo permite a los desarrolladores controlar la calidad del vídeo desde sus videollamadas. En esta guía de inicio rápido, se muestra cómo usar la API para establecer las restricciones.

Requisitos previos

Consulte el inicio rápido de llamadas de voz para configurar una aplicación de ejemplo con llamadas de voz.

Clases

NOMBRE Descripción
VideoConstraints Se usa para contener restricciones de vídeo entrantes y restricciones de vídeo salientes.
OutgoingVideoConstraints Se usa para especificar restricciones (maxWidth | maxHeight | maxFrameRate) para secuencias de vídeo salientes.
IncomingVideoConstraints Se usa para especificar restricciones (maxWidth | maxHeight) para secuencias de vídeo entrantes.

Uso de las restricciones de vídeo

En las secciones siguientes se explica cómo establecer las restricciones de vídeo para las secuencias de vídeo entrantes o salientes en diferentes momentos de una llamada.

Establecimiento de restricciones de vídeo antes de iniciar una llamada

En el caso de las secuencias de vídeo entrantes, hay que agregar IncomingVideoConstraints a IncomingVideoOptions.

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

    // ...

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

En el caso de las secuencias de vídeo salientes, hay que agregar OutgoingVideoConstraints a OutgoingVideoOptions.

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

Dado que las opciones se usan para iniciar una llamada o unirse a ella, las restricciones se pueden aplicar automáticamente a las secuencias. Por ejemplo:

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

Establecimiento de restricciones de vídeo durante una llamada

En lugar de establecer las restricciones de vídeo antes de iniciar una llamada, también se pueden ajustar dinámicamente las restricciones de vídeo durante la llamada. Debe llamar a setVideoConstraints en la clase de tipo Call y proporcionar las restricciones.


    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 restablecer o quitar las restricciones de vídeo establecidas anteriormente, debe seguir el patrón anterior y proporcionar 0 como valor de restricción. Si se proporciona valores null para IncomingVideoConstraints o OutgoingVideoConstraints, no se restablecerán ni quitarán las restricciones, pero se omitirán las restricciones con valor null.

Limitaciones

Nota:

Tenga en cuenta estas limitaciones al usar la API de restricciones de vídeo. Algunas de las limitaciones se quitarán en futuras versiones.

Hay algunas limitaciones conocidas en la API de restricciones de vídeo actual.

  • La restricción es una restricción máxima, lo que significa que el valor de restricción posible puede ser el valor especificado o uno menor. No hay ninguna garantía de que el valor real siga siendo el mismo que el especificado por el usuario.

  • Si el usuario establece un valor de restricción demasiado pequeño, el SDK usará el valor disponible más pequeño que se admita.

  • Para establecer OutgoingVideoConstraints durante una llamada, la secuencia de vídeo en curso actual no recoge automáticamente las restricciones especificadas. Para que las restricciones surtan efecto, debe detener y reiniciar el vídeo saliente.

  • IncomingVideoConstraints es actualmente una restricción preferida por el usuario en lugar de una restricción estricta, lo que significa que, en función de la red y el hardware, el valor real recibido puede superar la restricción establecida.

Estadísticas multimedia

Para evaluar y comparar la calidad del vídeo tras aplicar las restricciones de vídeo, se puede acceder a la API de MediaStats para obtener la información de velocidad de bits y resolución de vídeo de la secuencia. Las estadísticas multimedia también incluyen otras estadísticas pormenorizadas relacionadas con las secuencias, como inestabilidad, pérdida de paquetes, recorrido de ida y vuelta, etc.

Importante

La funcionalidad descrita en este artículo se encuentra actualmente en versión preliminar pública. Esta versión preliminar se ofrece sin un Acuerdo de Nivel de Servicio y no se recomienda para cargas de trabajo de producción. Es posible que algunas características no sean compatibles o que tengan sus funcionalidades limitadas. Para más información, consulte Términos de uso complementarios de las Versiones Preliminares de Microsoft Azure.

Información general

La API de restricciones de vídeo permite a los desarrolladores controlar la calidad del vídeo desde sus videollamadas. En esta guía de inicio rápido, se muestra cómo usar la API para establecer las restricciones.

Requisitos previos

Consulte el inicio rápido de llamadas de voz para configurar una aplicación de ejemplo con llamadas de voz.

Clases

NOMBRE Descripción
VideoConstraints Se usa para contener restricciones de vídeo entrantes y restricciones de vídeo salientes.
OutgoingVideoConstraints Se usa para especificar restricciones (maxWidth | maxHeight | maxFrameRate) para secuencias de vídeo salientes.
IncomingVideoConstraints Se usa para especificar restricciones (maxWidth | maxHeight) para secuencias de vídeo entrantes.

Uso de las restricciones de vídeo

En las secciones siguientes se explica cómo establecer las restricciones de vídeo para las secuencias de vídeo entrantes o salientes en diferentes momentos de una llamada.

Establecimiento de restricciones de vídeo antes de iniciar una llamada

En el caso de las secuencias de vídeo entrantes, hay que agregar IncomingVideoConstraints a IncomingVideoOptions.

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

En el caso de las secuencias de vídeo salientes, hay que agregar OutgoingVideoConstraints a OutgoingVideoOptions.

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

    let outgoingVideoOptions = OutgoingVideoOptions()
    outgoingVideoOptions.constraints = outgoingVideoConstraints

Dado que las opciones se usan para iniciar una llamada o unirse a ella, las restricciones se pueden aplicar automáticamente a las secuencias. Por ejemplo:

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

Establecimiento de restricciones de vídeo durante una llamada

En lugar de establecer las restricciones de vídeo antes de iniciar una llamada, también se pueden ajustar dinámicamente las restricciones de vídeo durante la llamada. Debe llamar a set(videoConstraints) en la clase de tipo Call y proporcionar las restricciones.


    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 restablecer o quitar las restricciones de vídeo establecidas anteriormente, debe seguir el patrón anterior y proporcionar 0 como valor de restricción. Si se proporciona valores null para IncomingVideoConstraints o OutgoingVideoConstraints, no se restablecerán ni quitarán las restricciones, pero se omitirán las restricciones con valor null.

Limitaciones

Nota:

Tenga en cuenta estas limitaciones al usar la API de restricciones de vídeo. Algunas de las limitaciones se quitarán en futuras versiones.

Hay algunas limitaciones conocidas en la API de restricciones de vídeo actual.

  • La restricción es una restricción máxima, lo que significa que el valor de restricción posible puede ser el valor especificado o uno menor. No hay ninguna garantía de que el valor real siga siendo el mismo que el especificado por el usuario.

  • Si el usuario establece un valor de restricción demasiado pequeño, el SDK usará el valor disponible más pequeño que se admita.

  • Para establecer OutgoingVideoConstraints durante una llamada, la secuencia de vídeo en curso actual no recoge automáticamente las restricciones especificadas. Para que las restricciones surtan efecto, debe detener y reiniciar el vídeo saliente.

  • IncomingVideoConstraints es actualmente una restricción preferida por el usuario en lugar de una restricción estricta, lo que significa que, en función de la red y el hardware, el valor real recibido puede superar la restricción establecida.

Estadísticas multimedia

Para evaluar y comparar la calidad del vídeo tras aplicar las restricciones de vídeo, se puede acceder a la API de MediaStats para obtener la información de velocidad de bits y resolución de vídeo de la secuencia. Las estadísticas multimedia también incluyen otras estadísticas pormenorizadas relacionadas con las secuencias, como inestabilidad, pérdida de paquetes, recorrido de ida y vuelta, etc.

Puede establecer restricciones de vídeo en las llamadas para controlar la calidad del vídeo en función de la resolución, frameRate o velocidad de bits en las videollamadas. En esta guía de inicio rápido, se muestra cómo establecer restricciones de vídeo al principio de una llamada y cómo usar nuestro método setConstraints en el objeto de llamada para establecer restricciones de vídeo dinámicamente durante la llamada.

Restricciones de envío de vídeo

El SDK de llamadas web de Azure Communication Services admite la configuración de la resolución máxima de vídeo, la velocidad de fotogramas o la velocidad de bits que envía un cliente. Las restricciones de vídeo del emisor se admiten en exploradores de escritorio (Chrome, Edge, Firefox) y cuando se usa el explorador móvil iOS Safari o el explorador móvil Android Chrome.

Restricciones admitidas
Vídeo entrante: resolución
Vídeo saliente: resolución, velocidad de fotogramas, velocidad de bits

Establecimiento de restricciones de vídeo al principio de una llamada: vídeo saliente (envío)

La configuración de restricciones de vídeo se implementa en la interfaz de Call. Para usar las restricciones de vídeo, puede especificar las restricciones desde dentro CallOptions cuando realice una llamada, acepte una llamada o unirse a una llamada. Debe especificar localVideoStreams en videoOptions.
Tenga en cuenta que las limitaciones no funcionarán si se une a una llamada con la opción de solo audio y activa la cámara más adelante. En este caso, puede establecer restricciones de vídeo dinámicamente mediante el método setConstraints en la interfaz 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)

Los tipos de restricciones de vídeo se describen de la siguiente manera:

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

Al establecer restricciones de vídeo, el SDK elegirá el valor más cercano que se encuentra dentro del conjunto de restricciones (para evitar que los valores de resolución, frameRate y velocidad de bits no superen los valores máximos de restricción establecidos). Además, cuando el valor de restricción de resolución sea demasiado pequeño, el SDK elegirá la resolución más pequeña disponible. En este caso, la altura de resolución elegida puede ser mayor que el valor de restricción.

Nota:

Para todosbitrate, frameHeight y frameRate, el valor de la restricción es unamaxrestricción, lo que significa que el valor real en la llamada puede ser el valor especificado o menor. No hay ninguna garantía de que la resolución de vídeo enviada permanecerá en la resolución especificada.

frameHeight en VideoSendConstraints tiene un significado diferente si el dispositivo móvil está en modo vertical. En el modo vertical, este valor indica el lado más corto del dispositivo. Por ejemplo, si se especifica el valor frameHeight.max en 240 para un dispositivo de 1080 (ancho) x 1920 (alto) en modo vertical, la altura de restricción se aplicará al lado de 1080 (ancho). Si el mismo dispositivo está en modo horizontal, 1920 (ancho) x 1080 (alto), la restricción se aplicará al lado de 1080 (alto).

Si usa la API de MediaStats para realizar un seguimiento de la resolución de vídeo enviada, es posible que descubra que la resolución enviada puede cambiar durante la llamada. Puede aumentar y disminuir, pero debería ser igual o menor que el valor de restricción que proporcione. Este cambio de resolución es un comportamiento esperado. El explorador también tiene alguna regla de degradación para ajustar la resolución enviada en función de las condiciones de red o de la CPU.

Establecimiento de restricciones de vídeo durante la llamada: vídeo saliente (envío)

Puede establecer restricciones de vídeo durante la llamada mediante el setConstraints método en el 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:

Al establecer el valor de restricción como 0 se anularán las restricciones establecidas anteriormente. Puede usar esta manera de restablecer o quitar restricciones.


Restricciones de recepción de vídeo

Si quiere controlar la resolución del receptor mediante el SDK de llamadas web de Azure Communication Services, puede ajustar el tamaño del representador de ese vídeo. El SDK de llamada ajusta automáticamente la resolución recibida en función de las dimensiones del representador. El SDK no solicitará una secuencia de vídeo entrante (ancho y alto) que pueda caber en la ventana de vídeo del representador.

Uso de estáticas multimedia para comprender el impacto de las restricciones de vídeo

Para evaluar y comparar la calidad del vídeo tras aplicar las restricciones de vídeo, se puede acceder a la API de MediaStats para obtener la información de velocidad de bits y resolución de vídeo de la secuencia de envío. Las estadísticas multimedia también incluyen otras estadísticas pormenorizadas relacionadas con las secuencias, como inestabilidad, pérdida de paquetes, recorrido de ida y vuelta, 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);
});

Pasos siguientes

Para más información, consulte los siguientes artículos.