Las traducciones son generadas a través de traducción automática. En caso de conflicto entre la traducción y la version original de inglés, prevalecerá la version en inglés. # Integración de filtros de fondo en una aplicación de cliente para Amazon Chime SDK En esta sección se explica cómo filtrar fondos de video mediante programación mediante el desenfoque de fondo 2.0 y el reemplazo de fondo 2.0. Para añadir un filtro de fondo a una transmisión de video, debe crear un `VideoFxProcessor` que contenga un objeto. `VideoFxConfig`. A continuación, inserte ese procesador en un `VideoTransformDevice`. El procesador de filtros de fondo utiliza TensorFlow un modelo de aprendizaje automático ligero, JavaScript Web Workers, y WebAssembly aplica un filtro al fondo de cada fotograma de la transmisión de vídeo. Estos recursos se descargan en tiempo de ejecución cuando se crea un `VideoFxProcessor`. La [aplicación de demostración del navegador GitHub utiliza el](https://github.com/aws/amazon-chime-sdk-js/tree/main/demos/browser) nuevo desenfoque de fondo y los filtros de reemplazo. Para probar, inicie la demostración con `npm run start`, únase a la reunión y, a continuación, haga clic en la cámara para activar el video. Abra el menú **Aplicar filtro** (![\[Button with a circle and a downward arrow.\]](http://docs.aws.amazon.com/es_es/chime-sdk/latest/dg/images/blur-apply-filter-initial.png)) y elija una de las opciones **Desenfoque de fondo 2.0 o** **Reemplazo de fondo 2.0**. **Topics** + [Acerca del uso de filtros de fondo para Amazon Chime SDK](about-bg-filters.md) + [Uso de una política de seguridad de contenido con la biblioteca cliente del SDK de Amazon Chime para JavaScript](content-security.md) + [Incorporación de filtros de fondo a la aplicación para Amazon Chime SDK](add-filters.md) + [Ejemplo de filtros de fondo para Amazon Chime SDK](example-bg-filter.md) # Acerca del uso de filtros de fondo para Amazon Chime SDK Los filtros de fondo pueden hacer un uso intensivo de la CPU o de la GPU. Es posible que algunos dispositivos móviles y computadoras portátiles o de sobremesa con especificaciones inferiores no tengan la potencia necesaria para ejecutar los filtros junto con varias transmisiones de video. ## Soporte de SIMD para Amazon Chime SDK Los filtros de fondo son más eficientes en entornos que admiten una sola instrucción, varios datos (SIMD). Los filtros utilizan menos CPU para un nivel de complejidad determinado cuando se habilita el SIMD. Es posible que los dispositivos de baja potencia que ejecutan navegadores sin compatibilidad con SIMD no ejecuten filtros en segundo plano. ## GL2 Soporte web para el SDK de Amazon Chime El `VideoFxProcessor` objeto requiere navegadores compatibles con GL2 la Web para acceder a la GPU del dispositivo cliente. ## Distribución de contenido y ancho de banda para Amazon Chime SDK Una red de entrega de contenido de Amazon carga los machine-learning-model archivos para los filtros de fondo durante el tiempo de ejecución. Esto proporciona una distribución global de baja latencia sin necesidad de incluir un conjunto completo de archivos como parte de la aplicación. Sin embargo, cargar archivos de modelo puede añadir latencia a algunas partes de la aplicación. Para ayudar a mitigar ese impacto, los navegadores almacenan en caché los archivos del modelo de forma indefinida. Esa caché hace que las cargas posteriores sean significativamente más rápidas. Como práctica recomendada, compruebe si hay navegadores compatibles y, a continuación, cree los recursos del filtro en segundo plano cuando los usuarios no noten ninguna latencia. Por ejemplo, puede descargar los archivos de los modelos mientras los usuarios esperan o mientras utilizan un selector de dispositivos. Su aplicación debe conectarse a: + Servicios multimedia de Amazon Chime SDK. + Amazon CloudFront a través de HTTPS (puerto 443). Todas las solicitudes se dirigen a los subdominios de `sdkassets.chime.aws`. Las aplicaciones que no puedan acceder a la red de entrega de contenido o que no incluyan el dominio correcto en su [política de seguridad de contenido](content-security.md) no superarán las comprobaciones de soporte y no podrán usar los filtros. Para obtener más información sobre los rangos CloudFront de direcciones IP, consulte [Ubicaciones e intervalos de direcciones IP de los servidores CloudFront perimetrales](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html) en la *Guía para CloudFront desarrolladores de Amazon*. ## Compatibilidad de navegadores para Amazon Chime SDK En la siguiente tabla se enumeran los navegadores y la versión compatible con los filtros de fondo. | Navegador | Versión mínima compatible | | --- | --- | | Firefox | 76\$1 | | Navegadores y entornos basados en Chromium, incluidos Edge y Electron | 78\$1 | | Android Chrome | 110\$1 | | Safari en macOS | 16.3\$1 | | Safari en iOS (iPhone, iPad) | 16.x | | Chrome en iOS | 110.0.0.x.x | | Firefox en iOS (iPhone iPad) | 16.x | La versión 3.14 del objeto `VideoFxProcessor` es compatible con Android. Para que los dispositivos Android sean compatibles con versiones anteriores a la 3.14, use los objetos `BackgroundBlurVideoFrameProcessor` y`BackgroundReplacementVideoFrameProcessor`. Para obtener más información sobre su uso, consulte la [https://aws.github.io/amazon-chime-sdk-js/modules/backgroundfilter_video_processor.html](https://aws.github.io/amazon-chime-sdk-js/modules/backgroundfilter_video_processor.html)página en GitHub. # Uso de una política de seguridad de contenido con la biblioteca cliente del SDK de Amazon Chime para JavaScript Las aplicaciones web modernas utilizan una política de seguridad de contenido para proteger a los usuarios de determinadas clases de ataques. Las aplicaciones que utilicen el `VideoFxProcessor` deben incluir las directivas de políticas que se describen en esta sección. Las directivas otorgan a Amazon Chime SDK acceso a los recursos que necesita en tiempo de ejecución. **Topics** + [Directivas de política de seguridad de contenido obligatorias](#required-csp) + [Ejemplo de política de seguridad de contenido](#example-csp) + [Errores de la política de seguridad del contenido](#csp-errors) + [Política de seguridad del contenido de apertura de origen cruzado](#cross-origin-policy) ## Directivas de política de seguridad de contenido obligatorias Debe utilizar las siguientes directivas de política de seguridad de contenido. + Para `script-src:` añada `blob: https://*.sdkassets.chime.aws` para cargar el código de procesamiento de video y `wasm-unsafe-eval` para permitir su ejecución. + Para `script-src-elem:` añada `blob:` `https://*.sdkassets.chime.aws` para cargar el código de procesamiento de video desde la fuente. + Para `worker-src:` añadir o `blob: https://*.sdkassets.chime.aws` cargar trabajadores JavaScript en todos los orígenes. Si omite alguna de estas entradas, o si utiliza encabezados HTTP y metaetiquetas de `http-equiv` para especificar una política y excluye inadvertidamente alguna de estas entradas por intersección, no se podrá inicializar un filtro en segundo plano. Parece que el filtro no es compatible o crea un procesador de fotogramas de video no operativo. Verá errores en la consola de su navegador, como los siguientes: ``` Refused to connect to 'https://static.sdkassets.chime.aws/bgblur/workers/worker.js…' because it violates the document's content security policy. ``` ### Directivas de política de scripts requeridas Para funcionar, la `VideoFxProcessor` clase debe cargar JavaScript las clases en tiempo de ejecución desde una red de entrega de contenido de Amazon. Estas clases utilizan la Web GL2 para implementar el posprocesamiento de vídeo. Para permitir que una aplicación busque y ejecute estas clases, debe incluir las siguientes directivas: + `script-src 'self' blob: https://*.sdkassets.chime.aws` + `script-src-elem 'self' blob: https://*.sdkassets.chime.aws` **nota** Para obtener una compatibilidad total con Safari y Firefox, debes usar las directivas `script-src` y `script-src-elem`. ### Directiva de política de trabajo `VideoFxProcessor`Carga las JavaScript clases como un blob para ejecutar un hilo de trabajo web. El hilo utiliza modelos de machine learning para procesar el video. Para conceder a una aplicación el acceso necesario para recuperar y utilizar este programa de trabajo, incluye la siguiente directiva: `worker-src 'self' blob: https://*.sdkassets.chime.aws` ### WebAssembly política `VideoFxProcessor`Carga un módulo WebAssembly (WASM) desde la misma red de entrega de contenido propiedad de Amazon. En Chrome 95 y versiones posteriores, los módulos WASM compilados no se pueden transferir a través de varios límites de módulos. Para poder recuperar e instanciar estos módulos, incluya `'wasm-unsafe-eval'` en la directiva `script-src`. Para obtener más información sobre la documentación de la Política de seguridad de contenido WebAssembly, consulte la Política de [seguridad de WebAssembly contenido](https://github.com/WebAssembly/content-security-policy/blob/main/proposals/CSP.md) en. GitHub ### (Opcional) Política de imágenes de fondo Para utilizar una imagen de fondo cargada dinámicamente con un filtro de reemplazo de fondo, `VideoFxProcessor` debe tener acceso a la imagen. Para ello, incluya una directiva de `connect-src` con el dominio que aloja la imagen. ## Ejemplo de política de seguridad de contenido La siguiente política de ejemplo le permite usar el `VideoFxProcessor`: Las definiciones de `connect-src` no son específicas de un `VideoFxProcessor`. En cambio, se relacionan con el audio y el video de una reunión de Amazon Chime SDK. ``` ``` ## Errores de la política de seguridad del contenido Si omite alguna de las directivas obligatorias, `VideoFxProcessor` no se instanciará ni será compatible. En ese caso, aparece el siguiente error (o uno similar) en la consola del navegador: ``` Refused to connect to 'https://static.sdkassets.chime.aws/ml_media_fx/otherassets/worker.js' because it violates the document's content security policy. ``` ## Política de seguridad del contenido de apertura de origen cruzado Para limitar el uso de memoria, el módulo prefiere usar una `SharedArrayBuffer` para el procesamiento. Sin embargo, esto requiere que configure cuidadosamente la seguridad web. Debe configurar los siguientes encabezados al publicar el código HTML de su aplicación: ``` Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp ``` El servidor debe configurarlos porque no tienen equivalentes en metaetiquetas. Si no configura estos encabezados, es posible que los filtros de fondo consuman un poco más de RAM. Los filtros de fondo pueden hacer un uso intensivo de la CPU o de la GPU. Es posible que algunos dispositivos móviles y computadoras portátiles o de sobremesa con especificaciones inferiores no tengan la potencia necesaria para ejecutar los filtros junto con varias transmisiones de video. # Incorporación de filtros de fondo a la aplicación para Amazon Chime SDK El proceso de añadir filtros de fondo sigue estos pasos generales: + Compruebe si hay navegadores compatibles. + Cree un objeto de `VideoFxConfig` con la configuración que desee usar. + Utilice el objeto de configuración para crear un objeto de `VideoFxProcessor`. + Incluya el objeto de `VideoFxProcessor` en un `VideoTransformDevice`. + Utilice `VideoTransformDevice` para iniciar la entrada de video. **nota** Para completar estos pasos, primero debe: Creación de una `Logger`. Elegir un dispositivo de video de la clase `MediaDeviceInfo`. Unirse a `MeetingSession`. Los pasos de las siguientes secciones explican cómo completar el proceso. **Topics** + [Comprobación de soporte antes de ofrecer un filtro para Amazon Chime SDK](support-check.md) + [Creación de un objeto VideoFxConfig para Amazon Chime SDK](create-videofxconfig.md) + [Creación de un objeto VideoFxProcessor para Amazon Chime SDK](create-videofxprocessor.md) + [Configuración del objeto VideoFxProcessor para Amazon Chime SDK](configure-videofxprocessor.md) + [Creación del objeto VideoTransformDevice para Amazon Chime SDK](create-video-transform.md) + [Inicio de la entrada de video para Amazon Chime SDK](start-video-input.md) + [Ajuste de la utilización de recursos de Amazon Chime SDK](tuning.md) # Comprobación de soporte antes de ofrecer un filtro para Amazon Chime SDK Amazon Chime SDK proporciona un método estático asíncrono que comprueba los navegadores compatibles e intenta descargar los activos necesarios. Sin embargo, no comprueba el rendimiento del dispositivo. Como práctica recomendada, asegúrate siempre de que los navegadores y dispositivos de los usuarios sean compatibles con los filtros antes de ofrecerlos. ``` import { VideoFxProcessor } from 'amazon-chime-sdk-js'; if (!await VideoFxProcessor.isSupported(logger)) { // logger is optional for isSupported } ``` # Creación de un objeto VideoFxConfig para Amazon Chime SDK Puede definir configuraciones para `backgroundBlur` y `backgroundReplacement` en el mismo objeto. Sin embargo, no puede configurar `isEnabled` como `true` para ambos filtros al mismo tiempo. Esa configuración no es válida. La clase `VideoFxConfig` no realiza ninguna validación propia. La validación se produce en el paso siguiente. En el siguiente ejemplo se muestra un registro de `VideoFxConfig`. ``` const videoFxConfig: VideoFxConfig = { backgroundBlur: { isEnabled: false, strength: 'medium' }, backgroundReplacement: { isEnabled: false, backgroundImageURL: 'space.jpg', defaultColor: undefined, } } ``` En las siguientes tablas, se enumeran las propiedades de la `VideoFxProcessor` que puede especificar en el objeto `VideoFxConfig`. **Propiedades del filtro de desenfoque de fondo** | Propiedad | Tipo | Description (Descripción) | | --- | --- | --- | | `isEnabled` | `boolean` | Cuando `true`, el filtro difumina el fondo. | | `strength` | `string` | Determina el grado de desenfoque. Valores válidos: `low` \$1 `medium` \$1 `high`. | **Propiedades del filtro de reemplazo de fondo** | Propiedad | Tipo | Description (Descripción) | | --- | --- | --- | | `isEnabled` | `boolean` | Cuando `true`, el filtro sustituye el fondo. | | `backgroundImageURL` | `string` | La URL de la imagen de fondo. El filtro cambia el tamaño de la imagen de forma dinámica a las dimensiones de la pantalla actual. Puede utilizar una cadena, por ejemplo, `https://...` o una URL de datos, por ejemplo `data:image/jpeg;base64`. | | `defaultColor` | `string` | Una cadena de colores hexadecimales como `000000` o `FFFFFF`, o una cadena como `black` o `white`. Si no especifica la URL de una imagen, el procesador utilizará la `defaultColor` como fondo. Si no especifica una `defaultColor`, el procesador usa por defecto el color negro. | # Creación de un objeto VideoFxProcessor para Amazon Chime SDK Al crear el `VideoFxProcessor` objeto, AWS los servidores descargan los activos en tiempo de ejecución o los carga la memoria caché del navegador. Si las configuraciones de red o de CSP impiden el acceso a los activos, la operación de `VideoFx.create` genera una excepción. El resultado VideoFxProcessor se configura como un procesador no operativo, lo que no afectará a la transmisión de vídeo. ``` let videoFxProcessor: VideoFxProcessor | undefined = undefined; try { videoFxProcessor = await VideoFxProcessor.create(logger, videoFxConfig); } catch (error) { logger.warn(error.toString()); } ``` `VideoFxProcessor.create` también intenta cargar la imagen desde `backgroundReplacement.backgroundImageURL`. Si la imagen no se carga, el procesador lanza una excepción. El procesador también ofrece excepciones por otros motivos, como configuraciones no válidas, navegadores no compatibles o hardware con poca potencia. # Configuración del objeto VideoFxProcessor para Amazon Chime SDK En la siguiente lista se describen las propiedades de `VideoFxProcessor` que puede configurar. El ejemplo que aparece debajo de las tablas muestra una configuración de tiempo de ejecución típica. **Desenfoque de fondo** El desenfoque del fondo toma las siguientes propiedades: | Propiedad | Tipo | Description (Descripción) | | --- | --- | --- | | `isEnabled` | `boolean` | Cuando `true`, el filtro difumina el fondo. | | `strength` | `string` | Determina el grado de desenfoque. Valores válidos: `low` \$1 `medium` \$1 `high`. | **Reemplazo de fondo** El reemplazo del fondo toma los siguientes parámetros: | Propiedad | Tipo | Description (Descripción) | | --- | --- | --- | | `isEnabled` | `boolean` | Cuando `true`, el filtro sustituye el fondo. | | `backgroundImageURL` | `string` | La URL de la imagen de fondo. El filtro cambia el tamaño de la imagen de forma dinámica a las dimensiones de la pantalla actual. Puede utilizar una cadena, por ejemplo, `https://...` o una URL de datos, por ejemplo `data:image/jpeg;base64`. | | `defaultColor` | `string` | Una cadena de colores hexadecimales como `000000` o `FFFFFF`, o una cadena como `black` o `white`. Si no especifica la URL de una imagen, el procesador utilizará la `defaultColor` como fondo. Si no especifica una `defaultColor`, el procesador usa por defecto el color negro. | **Cambiar una configuración en tiempo de ejecución** Puede cambiar una configuración de `VideoFxProcessor` en tiempo de ejecución mediante el parámetro `videoFxProcessor.setEffectConfig`. En el siguiente ejemplo se muestra cómo activar la sustitución del fondo y desactivar el desenfoque del fondo. **nota** Solo puede especificar un tipo de reemplazo de fondo a la vez. Debe especificar un valor para `backgroundImageURL` o `defaultColor`, pero no ambos. ``` videoFxConfig.backgroundBlur.isEnabled = false; videoFxConfig.backgroundReplacement.isEnabled = true; try { await videoFxProcessor.setEffectConfig(videoFxConfig); } catch(error) { logger.error(error.toString()) } ``` Si `setEffectConfig` produce una excepción, la configuración anterior permanece en vigor. `setEffectConfig` lanza excepciones en condiciones similares a las que provoca que `VideoFxProcessor.create` genere excepciones. En el siguiente ejemplo se muestra cómo cambiar una imagen de fondo mientras se reproduce el video. ``` videoFxConfig.backgroundReplacement.backgroundImageURL = "https://my-domain.com/my-other-image.jpg"; try { await videoFxProcessor.setEffectConfig(videoFxConfig); } catch(error) { logger.error(error.toString()) } ``` # Creación del objeto VideoTransformDevice para Amazon Chime SDK En el ejemplo siguiente se muestra cómo crear un objeto `VideoTransformDevice` y un objeto `VideoFxProcessor`. ``` // assuming that logger and videoInputDevice have already been set const videoTransformDevice = new DefaultVideoTransformDevice( logger, videoInputDevice, [videoFxProcessor] ); ``` # Inicio de la entrada de video para Amazon Chime SDK En el siguiente ejemplo se muestra cómo usar el objeto `VideoTransformDevice` para iniciar la entrada de video. ``` // assuming that meetingSession has already been created await meetingSession.audioVideo.startVideoInput(videoTransformDevice); meetingSession.audioVideo.start(); meetingSession.audioVideo.startLocalVideoTile(); ``` # Ajuste de la utilización de recursos de Amazon Chime SDK Al crear el `VideoFxProcessor`, puede proporcionar el parámetro opcional `processingBudgetPerFrame` y controlar la cantidad de CPU y GPU que utilizan los filtros. ``` let videoFxProcessor: VideoFxProcessor | undefined = undefined; const processingBudgetPerFrame = 50; try { videoFxProcessor = await VideoFxProcessor.create(logger, videoFxConfig, processingBudgetPerFrame); } catch (error) { logger.warn(error.toString()); } ``` `VideoFxProcessor` requiere tiempo para procesar un fotograma. La cantidad de tiempo depende del dispositivo, del navegador y de cualquier otra cosa que se esté ejecutando en el navegador o en el dispositivo. El procesador utiliza el concepto de *presupuesto* para determinar la cantidad de tiempo que se utiliza para procesar y renderizar cada fotograma. El tiempo de procesamiento se expresa en milisegundos. Como ejemplo de cómo usar un presupuesto, 1 segundo tiene 1000 ms. Con una captura de video de 15 fotogramas por segundo, el presupuesto total es de 1000 ms/15 fps = 66 ms. Puede establecer un presupuesto del 50 %, o 33 ms, proporcionando el valor `50` del parámetro `processingBudgetPerFrame`, como se muestra en el ejemplo anterior. A continuación, `VideoFxProcessor` intenta procesar los fotogramas dentro del presupuesto especificado. Si el procesamiento supera el presupuesto, el procesador reduce la calidad visual para mantenerse dentro del presupuesto. El procesador sigue reduciendo la calidad visual al mínimo, momento en el que deja de reducirse. Esta duración del procesamiento se mide continuamente, por lo que si hay más recursos disponibles (por ejemplo, si se cierra otra aplicación y se libera la CPU), el procesador vuelve a aumentar la calidad visual hasta que se ajuste al presupuesto o se alcance la máxima calidad visual. Si no especifica un valor para `processingBudgetPerFrame`, el valor `VideoFxProcessor` predeterminado es `50`. # Ejemplo de filtros de fondo para Amazon Chime SDK El siguiente ejemplo muestra cómo implementar los filtros. ``` import { VideoFxConfig, VideoFxTypeConversion, VideoTransformDevice, DefaultVideoTransformDevice, Logger, VideoFxProcessor, MeetingSession } from 'amazon-chime-sdk-js'; let videoTransformDevice: VideoTransformDevice | undefined = undefined; let videoFxProcessor: VideoFxProcessor | undefined = undefined; const videoFxConfig: VideoFxConfig = { backgroundBlur: { isEnabled: false, strength: "medium" }, backgroundReplacement: { isEnabled: false, backgroundImageURL: 'space.jpg', defaultColor: undefined, } } export const addEffectsToMeeting = async (videoInputDevice: MediaDeviceInfo, meetingSession: MeetingSession, logger: Logger): Promise => { try { videoFxProcessor = await VideoFxProcessor.create(logger, videoFxConfig); } catch (error) { logger.error(error.toString()); return; } videoTransformDevice = new DefaultVideoTransformDevice( logger, videoInputDevice, [videoFxProcessor] ); await meetingSession.audioVideo.startVideoInput(videoTransformDevice); } export const enableReplacement = async (logger: Logger) => { videoFxConfig.backgroundBlur.isEnabled = false; videoFxConfig.backgroundReplacement.isEnabled = true; await updateVideoFxConfig(videoFxConfig, logger); } export const enableBlur = async (logger: Logger) => { videoFxConfig.backgroundReplacement.isEnabled = false; videoFxConfig.backgroundBlur.isEnabled = true; await updateVideoFxConfig(videoFxConfig, logger); } export const pauseEffects = async (logger: Logger) => { videoFxConfig.backgroundReplacement.isEnabled = false; videoFxConfig.backgroundBlur.isEnabled = false; await updateVideoFxConfig(videoFxConfig, logger); } export const setReplacementImage = async (newImageUrl: string, logger: Logger) => { videoFxConfig.backgroundReplacement.backgroundImageURL = newImageUrl; videoFxConfig.backgroundReplacement.defaultColor = undefined; await updateVideoFxConfig(videoFxConfig, logger); } export const setReplacementDefaultColor = async (newHexColor: string, logger: Logger) => { videoFxConfig.backgroundReplacement.defaultColor = newHexColor; videoFxConfig.backgroundReplacement.backgroundImageURL = undefined; await updateVideoFxConfig(videoFxConfig, logger); } export const setBlurStrength = async (newStrength: number, logger: Logger) => { videoFxConfig.backgroundBlur.strength = VideoFxTypeConversion.useBackgroundBlurStrengthType(newStrength); await updateVideoFxConfig(videoFxConfig, logger); } export const updateVideoFxConfig = async (config: VideoFxConfig, logger: Logger) => { try { await videoFxProcessor.setEffectConfig(videoFxConfig); } catch (error) { logger.error(error.toString()) } } export const turnOffEffects = () => { const innerDevice = await videoTransformDevice?.intrinsicDevice(); await videoTransformDevice?.stop(); videoTransformDevice = undefined; videoFxProcessor = undefined; await meetingSession.audioVideo.startVideoInput(innerDevice); } ```