As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá. # Integrar filtros de plano de fundo em uma aplicação cliente do SDK do Amazon Chime Esta seção explica como filtrar planos de fundo de vídeo programaticamente usando o desfoque de plano de fundo 2.0 e a substituição de plano de fundo 2.0. Para adicionar um filtro de plano de fundo a uma transmissão de vídeo, você cria um `VideoFxProcessor` que contém um objeto `VideoFxConfig`. Em seguida, você insere esse processador em um `VideoTransformDevice`. O processador de filtro de fundo usa um modelo de aprendizado de máquina TensorFlow Lite, o JavaScript Web Workers, WebAssembly para aplicar um filtro ao plano de fundo de cada quadro no stream de vídeo. Esses ativos são baixados em runtime quando você cria um `VideoFxProcessor`. O [aplicativo de demonstração do navegador GitHub](https://github.com/aws/amazon-chime-sdk-js/tree/main/demos/browser) usa o novo desfoque de fundo e filtros de substituição. Para experimentá-los, inicie a demonstração com `npm run start`, participe da reunião e clique na câmera para ativar o vídeo. Abra o menu **Aplicar filtro** (![\[Button with a circle and a downward arrow.\]](http://docs.aws.amazon.com/pt_br/chime-sdk/latest/dg/images/blur-apply-filter-initial.png)) e escolha uma das opções **Desfoque de fundo 2.0** ou **Substituição de fundo 2.0**. **Topics** + [Sobre o uso de filtros de plano de fundo do SDK do Amazon Chime](about-bg-filters.md) + [Usando uma política de segurança de conteúdo com a biblioteca cliente do Amazon Chime SDK para JavaScript](content-security.md) + [Adicionar filtros de plano de fundo à sua aplicação do SDK do Amazon Chime](add-filters.md) + [Exemplo de filtro de plano de fundo do SDK do Amazon Chime](example-bg-filter.md) # Sobre o uso de filtros de plano de fundo do SDK do Amazon Chime Os filtros de plano de fundo podem ser intensivos em CPU e GPU. Alguns dispositivos móveis e notebooks ou desktops com especificações mais baixas podem não ter a capacidade de executar os filtros junto com várias transmissões de vídeo. ## Suporte SIMD para o SDK do Amazon Chime Os filtros de plano de fundo são mais eficientes em ambientes que oferecem suporte a Single Instruction, Multiple Data (SIMD). Os filtros usam menos CPU para um determinado nível de complexidade quando você ativa o SIMD. Dispositivos de baixa potência que executam navegadores sem suporte a SIMD podem não executar filtros de plano de fundo. ## GL2 Suporte web para o Amazon Chime SDK O `VideoFxProcessor` objeto requer navegadores compatíveis com a Web GL2 para acessar a GPU no dispositivo cliente. ## Fornecimento de conteúdo e largura de banda do SDK do Amazon Chime Uma rede de distribuição de conteúdo da Amazon carrega os machine-learning-model arquivos para filtros em segundo plano em tempo de execução. Isso fornece distribuição global de baixa latência sem a necessidade de fornecer um conjunto completo de arquivos como parte do seu aplicativo. No entanto, carregar arquivos de modelo pode adicionar latência a partes do seu aplicativo. Para ajudar a mitigar esse impacto, os navegadores armazenam em cache os arquivos do modelo indefinidamente. Esse cache torna os carregamentos subsequentes significativamente mais rápidos. Como prática recomendada, verifique se há navegadores compatíveis e, em seguida, crie os recursos de filtro de plano de fundo quando os usuários não perceberem nenhuma latência. Por exemplo, você pode baixar arquivos de modelo enquanto os usuários esperam em um lobby ou enquanto usam um seletor de dispositivos. Seu aplicativo deve se conectar ao seguinte: + Serviços de mídia do SDK do Amazon Chime. + Amazon CloudFront via HTTPS (porta 443). Todas as solicitações são para subdomínios de `sdkassets.chime.aws`. Os aplicativos que não conseguirem acessar a rede de distribuição de conteúdo ou não incluírem o domínio correto em sua [política de segurança de conteúdo](content-security.md) falharão nas verificações de suporte e não conseguirão usar os filtros. Para obter mais informações sobre os intervalos CloudFront de endereços IP da, consulte [Localizações e intervalos de endereços IP dos servidores de CloudFront borda](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html) no *Amazon CloudFront Developer Guide*. ## Compatibilidade de navegador do SDK do Amazon Chime A tabela a seguir lista os navegadores e versões compatíveis com filtros de plano de fundo. | Navegador | Versão mínima compatível | | --- | --- | | Firefox | Posterior a 76 | | Navegadores e ambientes baseados em Chromium, incluindo Edge e Electron | Posterior a 78 | | Android Chrome | Posterior a 110 | | Safari no macOS | Posterior a 16.3 | | Safari no iOS (iPhone, iPad) | 16.x | | Chrome no iOS | 110.0.0.x.x | | Firefox no iOS (iPhone iPad) | 16.x | A versão 3.14 do objeto `VideoFxProcessor` é compatível com Android. Para suporte a dispositivos Android em versões anteriores à 3.14, use os objetos `BackgroundBlurVideoFrameProcessor` e `BackgroundReplacementVideoFrameProcessor`. Para obter mais informações sobre como usá-los, consulte a [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 em GitHub. # Usando uma política de segurança de conteúdo com a biblioteca cliente do Amazon Chime SDK para JavaScript Os aplicativos web modernos usam uma política de segurança de conteúdo para proteger os usuários de determinadas classes de ataques. As aplicações que usam o `VideoFxProcessor` devem incluir as diretivas de políticas descritas nesta seção. As diretivas dão ao SDK do Amazon Chime acesso aos recursos necessários em runtime. **Topics** + [Diretivas de política de segurança de conteúdo necessárias](#required-csp) + [Exemplo de política de segurança de conteúdo](#example-csp) + [Erros na política de segurança de conteúdo](#csp-errors) + [Política de segurança de conteúdo de abertura de origem cruzada](#cross-origin-policy) ## Diretivas de política de segurança de conteúdo necessárias Você deve usar as seguintes diretivas de política de segurança de conteúdo. + Com relação a `script-src:`, adicione `blob: https://*.sdkassets.chime.aws` para carregar o código de processamento de vídeo, e `wasm-unsafe-eval` para permitir sua execução. + Com relação a `script-src-elem:`, adicione `blob:` `https://*.sdkassets.chime.aws` para carregar o código de processamento de vídeo da origem. + Para `worker-src:` adicionar `blob: https://*.sdkassets.chime.aws` ao load worker JavaScript em todas as origens. Se você omitir qualquer uma dessas entradas ou usar cabeçalhos HTTP e metatags `http-equiv` para especificar uma política e excluir inadvertidamente qualquer uma delas por interseção, um filtro de plano de fundo não poderá ser inicializado. O filtro parece não ser suportado ou cria um processador de quadros de vídeo autônomo. Você verá erros no console do seu navegador, como: ``` Refused to connect to 'https://static.sdkassets.chime.aws/bgblur/workers/worker.js…' because it violates the document's content security policy. ``` ### Diretivas de política de script necessárias Para funcionar, a `VideoFxProcessor` classe deve carregar JavaScript classes em tempo de execução de uma rede de distribuição de conteúdo da Amazon. Essas classes usam GL2 a Web para implementar o pós-processamento de vídeo. Para permitir que um aplicativo busque e execute essas classes, você deve incluir as seguintes diretivas: + `script-src 'self' blob: https://*.sdkassets.chime.aws` + `script-src-elem 'self' blob: https://*.sdkassets.chime.aws` **nota** Para obter suporte completo no Safari e no Firefox, você deve usar as diretivas `script-src` e `script-src-elem`. ### Diretiva de política do operador O `VideoFxProcessor` carrega JavaScript classes como um blob para executar um thread de web worker. O tópico usa modelos de machine learning para processar vídeos. Para conceder acesso a um aplicativo para buscar e usar esse operador, inclua a seguinte diretiva: `worker-src 'self' blob: https://*.sdkassets.chime.aws` ### WebAssembly política O `VideoFxProcessor` carrega um módulo WebAssembly (WASM) da mesma rede de distribuição de conteúdo de propriedade da Amazon. No Chrome 95 e versões posteriores, os módulos WASM compilados não podem ser transmitidos pelos limites de vários módulos. Para permitir a busca e a instanciação desses módulos, inclua `'wasm-unsafe-eval'` na diretiva `script-src`. Para obter mais informações sobre a documentação da Política de Segurança de Conteúdo WebAssembly, consulte a [Política de Segurança de WebAssembly Conteúdo](https://github.com/WebAssembly/content-security-policy/blob/main/proposals/CSP.md) em GitHub. ### (Opcional) Diretiva de política de imagem de plano de fundo Para usar uma imagem de plano de fundo carregada dinamicamente com um filtro de substituição de plano de fundo, o `VideoFxProcessor` deve ter acesso à imagem. Para fazer isso, inclua uma diretiva `connect-src` com o domínio que hospeda a imagem. ## Exemplo de política de segurança de conteúdo O exemplo de política a seguir permite que você use o `VideoFxProcessor`. As definições `connect-src` não são específicas para um `VideoFxProcessor`. Em vez disso, eles estão relacionados ao áudio e ao vídeo de uma reunião do SDK do Amazon Chime. ``` ``` ## Erros na política de segurança de conteúdo Se você omitir qualquer uma das diretivas necessárias, o `VideoFxProcessor` não instanciará e não terá suporte. Nesse caso, o erro a seguir (ou similar) aparece no console do 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 segurança de conteúdo de abertura de origem cruzada Para limitar o uso de memória, o módulo prefere usar o `SharedArrayBuffer` para processamento. No entanto, isso requer que você configure cuidadosamente a segurança da web. Você deve definir os seguintes cabeçalhos ao servir o HTML do seu aplicativo: ``` Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp ``` O servidor deve configurá-los porque eles não têm equivalentes de meta-tag. Se você não definir esses cabeçalhos, os filtros de plano de fundo poderão usar um pouco mais de RAM. Os filtros de plano de fundo podem ser intensivos em CPU e GPU. Alguns dispositivos móveis e notebooks ou desktops com especificações mais baixas podem não ter a capacidade de executar os filtros junto com várias transmissões de vídeo. # Adicionar filtros de plano de fundo à sua aplicação do SDK do Amazon Chime O processo de adição de filtros de plano de fundo segue estas etapas gerais: + Verifique se há navegadores compatíveis. + Crie um objeto `VideoFxConfig` com a configuração que você deseja usar. + Use o objeto de configuração para criar um objeto `VideoFxProcessor`. + Inclua o objeto `VideoFxProcessor` em um `VideoTransformDevice`. + Use o `VideoTransformDevice` para iniciar a entrada de vídeo. **nota** Para concluir essas etapas, você deve primeiro: Crie um `Logger`. Escolher um dispositivo de vídeo da classe `MediaDeviceInfo`. Participar com sucesso em uma `MeetingSession`. As etapas nas seções a seguir explicam como concluir o processo. **Topics** + [Conferir o suporte antes de oferecer um filtro para o SDK do Amazon Chime](support-check.md) + [Criar um objeto VideoFxConfig do SDK do Amazon Chime](create-videofxconfig.md) + [Criar um objeto VideoFxProcessor do SDK do Amazon Chime](create-videofxprocessor.md) + [Configurar o objeto VideoFxProcessor do SDK do Amazon Chime](configure-videofxprocessor.md) + [Criar o objeto VideoTransformDevice do SDK do Amazon Chime](create-video-transform.md) + [Iniciar a entrada de vídeo do SDK do Amazon Chime](start-video-input.md) + [Ajustar a utilização de recursos do SDK do Amazon Chime](tuning.md) # Conferir o suporte antes de oferecer um filtro para o SDK do Amazon Chime O SDK do Amazon Chime fornece um método estático assíncrono que verifica os navegadores compatíveis e tenta baixar os ativos necessários. No entanto, ele não verifica o desempenho do dispositivo. Como prática recomendada, sempre garanta que os navegadores e dispositivos dos usuários sejam compatíveis com os filtros antes de oferecer os filtros. ``` import { VideoFxProcessor } from 'amazon-chime-sdk-js'; if (!await VideoFxProcessor.isSupported(logger)) { // logger is optional for isSupported } ``` # Criar um objeto VideoFxConfig do SDK do Amazon Chime Você pode definir configurações para `backgroundBlur` e `backgroundReplacement` no mesmo objeto. No entanto, você não pode configurar `isEnabled` como `true` para os dois filtros ao mesmo tempo. Essa é uma configuração inválida. A classe `VideoFxConfig` não faz validação própria. A validação ocorre na próxima etapa. O exemplo a seguir mostra uma `VideoFxConfig` válida. ``` const videoFxConfig: VideoFxConfig = { backgroundBlur: { isEnabled: false, strength: 'medium' }, backgroundReplacement: { isEnabled: false, backgroundImageURL: 'space.jpg', defaultColor: undefined, } } ``` As tabelas a seguir listam as propriedades do `VideoFxProcessor` que você pode especificar no objeto `VideoFxConfig`. **Propriedades do filtro de desfoque de plano de fundo** | Propriedade | Tipo | Description | | --- | --- | --- | | `isEnabled` | `boolean` | Quando `true`, o filtro desfoca o plano de fundo. | | `strength` | `string` | Determina a extensão do desfoque. Valores válidos: `low` \$1 `medium` \$1 `high`. | **Propriedades do filtro de substituição de plano de fundo** | Propriedade | Tipo | Description | | --- | --- | --- | | `isEnabled` | `boolean` | Quando `true`, o filtro substitui o plano de fundo\$1. | | `backgroundImageURL` | `string` | A URL da imagem do plano de fundo. O filtro redimensiona a imagem dinamicamente para as dimensões da tela atual. Você pode usar uma string, como `https://...` ou uma URL de dados, como `data:image/jpeg;base64`. | | `defaultColor` | `string` | Uma string de cor hexadecimal, como `000000` ou `FFFFFF`, ou uma string como `black` ou `white`. Se você não especificar uma URL da imagem, o processador usará a `defaultColor` como plano de fundo. Se você não especificar uma `defaultColor`, o processador usará o padrão preto. | # Criar um objeto VideoFxProcessor do SDK do Amazon Chime Ao criar o `VideoFxProcessor` objeto, os AWS servidores baixam os ativos de tempo de execução ou o cache do navegador carrega os ativos. Se as configurações de rede ou CSP impedirem o acesso aos ativos, a operação `VideoFx.create` gerará uma exceção. O resultado VideoFxProcessor é configurado como um processador autônomo, o que não afetará a transmissão de vídeo. ``` let videoFxProcessor: VideoFxProcessor | undefined = undefined; try { videoFxProcessor = await VideoFxProcessor.create(logger, videoFxConfig); } catch (error) { logger.warn(error.toString()); } ``` `VideoFxProcessor.create` também tenta carregar a imagem do `backgroundReplacement.backgroundImageURL`. Se a imagem não for carregada, o processador lançará uma exceção. O processador também gera exceções por outros motivos, como configurações inválidas, navegadores sem suporte ou hardware de baixa potência. # Configurar o objeto VideoFxProcessor do SDK do Amazon Chime A tabela a seguir lista as propriedades do `VideoFxProcessor` que você pode configurar. O exemplo abaixo das tabelas mostra uma configuração típica de runtime. **Desfoque de plano de fundo** O desfoque de plano de fundo assume as seguintes propriedades: | Propriedade | Tipo | Description | | --- | --- | --- | | `isEnabled` | `boolean` | Quando `true`, o filtro desfoca o plano de fundo. | | `strength` | `string` | Determina a extensão do desfoque. Valores válidos: `low` \$1 `medium` \$1 `high`. | **Substituição de plano de fundo** A substituição de plano de fundo considera os seguintes parâmetros: | Propriedade | Tipo | Description | | --- | --- | --- | | `isEnabled` | `boolean` | Quando `true`, o filtro substitui o plano de fundo. | | `backgroundImageURL` | `string` | A URL da imagem do plano de fundo. O filtro redimensiona a imagem dinamicamente para as dimensões da tela atual. Você pode usar uma string, como `https://...` ou uma URL de dados, como `data:image/jpeg;base64`. | | `defaultColor` | `string` | Uma string de cor hexadecimal, como `000000` ou `FFFFFF`, ou uma string como `black` ou `white`. Se você não especificar uma URL da imagem, o processador usará a `defaultColor` como plano de fundo. Se você não especificar uma `defaultColor`, o processador usará o padrão preto. | **Como alterar uma configuração em runtime** Você pode alterar uma configuração do `VideoFxProcessor` em runtime usando o parâmetro `videoFxProcessor.setEffectConfig`. O exemplo a seguir mostra como habilitar a substituição de plano de fundo e desabilitar o desfoque de plano de fundo. **nota** Você só pode especificar um tipo de substituição de plano de fundo por vez. Especifique um valor para `backgroundImageURL` ou `defaultColor`, mas não para os dois. ``` videoFxConfig.backgroundBlur.isEnabled = false; videoFxConfig.backgroundReplacement.isEnabled = true; try { await videoFxProcessor.setEffectConfig(videoFxConfig); } catch(error) { logger.error(error.toString()) } ``` Se a `setEffectConfig` gerar uma exceção, a configuração anterior permanecerá em vigor. A `setEffectConfig` lança exceções em condições semelhantes às que fazem o `VideoFxProcessor.create` lançar exceções. O exemplo a seguir mostra como alterar uma imagem de plano de fundo enquanto o vídeo é executado. ``` videoFxConfig.backgroundReplacement.backgroundImageURL = "https://my-domain.com/my-other-image.jpg"; try { await videoFxProcessor.setEffectConfig(videoFxConfig); } catch(error) { logger.error(error.toString()) } ``` # Criar o objeto VideoTransformDevice do SDK do Amazon Chime O exemplo a seguir mostra como criar um objeto `VideoTransformDevice` que contém o `VideoFxProcessor`. ``` // assuming that logger and videoInputDevice have already been set const videoTransformDevice = new DefaultVideoTransformDevice( logger, videoInputDevice, [videoFxProcessor] ); ``` # Iniciar a entrada de vídeo do SDK do Amazon Chime O exemplo a seguir mostra como usar o objeto `VideoTransformDevice` para iniciar a entrada de vídeo. ``` // assuming that meetingSession has already been created await meetingSession.audioVideo.startVideoInput(videoTransformDevice); meetingSession.audioVideo.start(); meetingSession.audioVideo.startLocalVideoTile(); ``` # Ajustar a utilização de recursos do SDK do Amazon Chime Ao criar o `VideoFxProcessor`, você pode fornecer o parâmetro `processingBudgetPerFrame` opcional e controlar a quantidade de CPU e GPU que os filtros usam. ``` let videoFxProcessor: VideoFxProcessor | undefined = undefined; const processingBudgetPerFrame = 50; try { videoFxProcessor = await VideoFxProcessor.create(logger, videoFxConfig, processingBudgetPerFrame); } catch (error) { logger.warn(error.toString()); } ``` O `VideoFxProcessor` requer tempo para processar um quadro. A quantidade de tempo depende do dispositivo, do navegador e do que mais está sendo executado no navegador ou no dispositivo. O processador usa o conceito de um *orçamento* para definir a quantidade de tempo usada para processar e renderizar cada quadro. O tempo de processamento é em milissegundos. Como exemplo de como usar um orçamento, 1 segundo tem 1000 ms. A meta de 15 quadros por segundo de captura de vídeo resulta em um orçamento total de 1000 ms/15 fps = 66 ms. Você pode definir um orçamento de 50% disso, ou 33 ms, fornecendo o valor `50` no parâmetro `processingBudgetPerFrame`, conforme mostrado no exemplo acima. O `VideoFxProcessor` em seguida tenta processar os quadros dentro do orçamento especificado. Se o processamento ultrapassar o orçamento, o processador reduz a qualidade visual para ficar dentro do orçamento. O processador continua reduzindo a qualidade visual ao mínimo e, nesse momento, ele para de reduzir. Essa duração do processamento é medida continuamente, portanto, se mais recursos forem disponibilizados, como outro aplicativo fechando e liberando a CPU, o processador aumentará a qualidade visual novamente até atingir o orçamento ou atingir a qualidade visual máxima. Se você não fornecer um valor para `processingBudgetPerFrame`, o `VideoFxProcessor` padrão será `50`. # Exemplo de filtro de plano de fundo do SDK do Amazon Chime O exemplo a seguir mostra como implementar os 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); } ```