本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。 # 使用 Amazon Chime 软件开发工具包客户端库用于 JavaScript 本指南提供了 Amazon Chime SDK 客户端库的概念性概述 JavaScript，以及关键服务器和客户端组件的示例代码。 **Topics** + [了解 Amazon Chime SDK 应用程序的组件](components.md) + [了解适用于 Amazon Chime 软件开发工具包客户端库的关键概念 JavaScript](key-concepts.md) + [了解 Amazon Chime SDK 的服务架构](service-architecture-java.md) + [了解 Amazon Chime SDK 的 Web 应用程序架构](web-architecture.md) + [了解 Amazon Chime SDK 的服务器应用程序架构](server-app-architecture.md) + [了解 Amazon Chime SDK 媒体控制面板](media-control-plane-java.md) + [了解 Amazon Chime SDK 媒体数据面板](media-data-plane.md) + [了解 Amazon Chime SDK 的 Web 应用程序架构组件](web-app-comp-arch-java.md) + [为 Amazon Chime SDK 构建服务器应用程序](build-server-app.md) + [为 Amazon Chime SDK 构建客户端应用程序](build-client-app.md) + [为 Amazon Chime SDK 将背景筛选器集成至客户端应用程序](background-filters.md) # 了解 Amazon Chime SDK 应用程序的组件 要将实时音频、视频和屏幕共享功能嵌入到您的 Amazon Chime SDK 应用程序中，您可以使用以下组件： + **Amazon Chime SDK 客户端库 JavaScript**，即你集成到浏览器或 Electron 网络应用程序中的客户端 SDK。你可以通过添加适用于 [ JavaScript NPM 包的 Amazon Chime 软件开发工具包作为依赖项](https://www.npmjs.com/package/amazon-chime-sdk-js)来做到这一点。此套餐利用[https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices](https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices)和[https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API) APIs 加入会议、交换音频、视频以及与其他与会者共享内容。它为您提供了管理不同类型媒体的控制界面，并能够将这些资源绑定到应用程序的用户界面。 + ** AWS 软件开发工具包**，Amazon Chime SDK API，您的服务器应用程序使用它来对来自您的网络应用程序的会议请求进行身份验证和授权。该 AWS SDK 为您提供了 API 操作，例如 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html) 和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html)，用于创建和管理会议和与会者资源。 与任何其他 AWS 资源一样， AWS Identity and Access Management (IAM) 服务配置对这些操作的访问权限。该 AWS 软件开发工具包有[多种编程语言版本](https://aws.amazon.com/tools/)，可减少从服务器应用程序调用 AWS SDK Chime API 的复杂性。如果您的应用程序当前未使用服务器应用程序，则可以从 [demos/serverless](https://github.com/aws/amazon-chime-sdk-js/tree/master/demos/serverless) 文件夹中包含的 CloudFormation 模板开始。该演示向您展示了如何使用 S AWS DK Chime API 构建 AWS Lambda基于服务器的无服务器应用程序。 + **Amazon Chime SDK 媒体服务**提供 Amazon Chime SDK 客户端库中的音频、视频和信号， JavaScript 用于连接会议。媒体服务可在全球范围内使用，支持音频混合、视频转发和使用 TURN 中继的 NAT 遍历。Amazon Chime 服务团队可部署、监控和管理这些服务。媒体服务托管在单个 IP 地址范围 (99.77.128.0/18) 中，并使用端口 TCP/443 和 UDP/3478 简化 IT 管理员的防火墙配置。最后，这些服务利用 [AWS 全球云基础架构](https://aws.amazon.com/about-aws/global-infrastructure/)。 # 了解适用于 Amazon Chime 软件开发工具包客户端库的关键概念 JavaScript 要完全了解如何创建和管理会议和用户，您需要了解以下概念： **[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_Meeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_Meeting.html)** — 多方媒体会话。每个会议都具有唯一的会议标识符。您可以在其中一个支持的 AWS 区域创建会议。创建会议时，将返回媒体 URLs 列表。这些是加入会议所需数据的关键部分，您需要将这些数据传播给所有尝试加入会议的用户。 **[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_Attendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_Attendee.html)** — 试图加入多方媒体会话的用户。每个与会者都有一个唯一的标识符，一个可以传入该标识符以将与会者映射到开发人员系统中用户的外部用户标识符，以及一个授予其会议访问权限的签名加入令牌。 **[https://aws.github.io/amazon-chime-sdk-js/interfaces/meetingsession.html](https://aws.github.io/amazon-chime-sdk-js/interfaces/meetingsession.html)**和 [https://aws.github.io/amazon-chime-sdk-js/classes/defaultmeetingsession.html](https://aws.github.io/amazon-chime-sdk-js/classes/defaultmeetingsession.html)— Amazon Chime 软件开发工具包客户端库的根对象 JavaScript ，它代表每位用户在会议中的会话。Web 应用程序首先实例化 MeetingSession 并使用正确的会议和与会者信息对其进行配置。 **[https://aws.github.io/amazon-chime-sdk-js/classes/meetingsessionconfiguration.html](https://aws.github.io/amazon-chime-sdk-js/classes/meetingsessionconfiguration.html)**— 存储加入会议会话所需的会议和与会者数据。该数据是服务器应用程序发出的 `CreateMeeting` 和 `CreateAttendee` API 调用的响应。服务器应用程序将这些数据传递给 Web 应用程序，而 Web 应用程序使用它来实例化 `MeetingSession`。 **[https://aws.github.io/amazon-chime-sdk-js/interfaces/devicecontroller.html](https://aws.github.io/amazon-chime-sdk-js/interfaces/devicecontroller.html)**(DefaultDeviceController) — 用于枚举用户系统上可用音频和视频设备列表。您还可以在会议期间使用设备控制器切换活动设备。 **[https://aws.github.io/amazon-chime-sdk-js/interfaces/audiovideofacade.html](https://aws.github.io/amazon-chime-sdk-js/interfaces/audiovideofacade.html)**(DefaultAudioVideoFacade) — 为会议提供支持的关键界面。它提供了开始、控制和结束会议的功能。 APIs 它还 APIs 允许通过跟踪用户加入或离开、静音或取消静音、积极说话或连接不佳来监听推动用户体验变化的关键事件（例如与会者名单）。您还可以使用它们将音频控制 HTML 元素绑定 APIs 到会议的音频输出，然后通过选定的音频输出设备进行播放。 **[https://aws.github.io/amazon-chime-sdk-js/interfaces/activespeakerdetectorfacade.html](https://aws.github.io/amazon-chime-sdk-js/interfaces/activespeakerdetectorfacade.html)**(DefaultActiveSpeakerDetector) — 订阅活跃发言人事件的 API。定期返回一段时间内按麦克风音量排序的与会者列表。您可以根据需要覆盖和调整当前发言人策略。 **[https://aws.github.io/amazon-chime-sdk-js/interfaces/contentsharecontroller.html](https://aws.github.io/amazon-chime-sdk-js/interfaces/contentsharecontroller.html)**(DefaultContentShareController)— APIs 开始-停止和暂停-取消暂停内容共享。它还提供 APIs 监听生命周期事件以跟踪内容共享状态的功能。 **[https://aws.github.io/amazon-chime-sdk-js/interfaces/logger.html](https://aws.github.io/amazon-chime-sdk-js/interfaces/logger.html)**[https://aws.github.io/amazon-chime-sdk-js/interfaces/logger.html](https://aws.github.io/amazon-chime-sdk-js/interfaces/logger.html) — 该接口用于利用控制台日志，或传入记录器对象来覆盖当前的日志实现并从 Amazon Chime SDK 获取不同级别的日志。 # 了解 Amazon Chime SDK 的服务架构 此高级架构图显示 [了解适用于 Amazon Chime 软件开发工具包客户端库的关键概念 JavaScript](key-concepts.md) 中列出的组件如何与其他 AWS 服务交互和协作： ![\[该图显示了用于使用的 Amazon Chime 软件开发工具包客户端库如何与其他服务进行 JavaScript 交互。 AWS\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/architecture-1.png) # 了解 Amazon Chime SDK 的 Web 应用程序架构 您可以从内容分发网络提供您的 Web 应用程序，并当用户在浏览器中导航至 URL 时加载该应用程序。您也可以将其封装在平台自带的 Electron 应用程序中，由用户安装在他们的设备上。 要加入新的或现有会议，Web 应用程序会向服务器应用程序发出 REST 请求。通常，这些请求会携带授权令牌或 Cookie，您的应用程序将其用于其他 API 请求。您还可以将 Web 客户端设计为向服务器发送区域提示，服务器在向服务器提供 MediaRegion 参数时可以使用该提示[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html)。您的 Web 应用程序可以通过向 htt [ps://nearest-media-region.l.chime.a](https://nearest-media-region.l.chime.aws/) ws 终端节点发出 HTTP GET 请求来确定最近的媒体服务区域。 # 了解 Amazon Chime SDK 的服务器应用程序架构 当服务器收到来自客户端的请求时，它首先确保用户有权限开始或加入会议。服务器使用所选语言的嵌入式 AWS SDK 对全球媒体控制平面进行[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html)和 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html)API 调用。这样做是为了在支持的 AWS 区域之一创建会议和与会者。要提出这些请求，该服务需要相应的 IAM 用户或角色。反过来，IAM 用户和角色需要[ AmazonChime软件开发工具包](https://docs.aws.amazon.com/chime-sdk/latest/ag/security_iam_id-based-policy-examples.html)策略。 # 了解 Amazon Chime SDK 媒体控制面板 Amazon Chime SDK 媒体控制平面是全球性的，由 us-east-1 托管，[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html) APIs 用于跨数据平面创建和管理会议和与会者资源。[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html)它会验证凭证并确保会话在请求区域的数据面板被引导。 控制平面还会触发通知机制的 [Amazon Chime SDK 事件](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)，例如亚马逊、亚马逊简单队列服务 (SQS) 或 EventBridge亚马逊简单通知服务 (SNS) Simple Notification Service。 AWS 持续监控服务，它们会随着负载的增加而自动扩展。 APIs 它们旨在仅接受不透明的用户标识符而不接受用户数据，因此它们符合数据主权要求。 # 了解 Amazon Chime SDK 媒体数据面板 您可以使用任何控制平面区域在所有 AWS 区域创建会议。媒体数据平面在所有 AWS 地区都可用。它包括音频混合服务、视频转发服务、TURN 服务和会话初始协议 (SIP) 互操作性服务。这些服务受到持续监控，旨在随着负载的增加而自动扩展。要了解更多信息，请参阅 [Amazon Chime SDK 媒体区域](https://docs.aws.amazon.com/chime-sdk/latest/dg/chime-sdk-meetings-regions.html)。 有关区域和可用区的现有列表，请参阅[区域和可用区](https://aws.amazon.com/about-aws/global-infrastructure/regions_az/)。 # 了解 Amazon Chime SDK 的 Web 应用程序架构组件 显示 Amazon Chime SDK Web 客户端应用程序的架构的图表。 ![\[Amazon Chime SDK Web 应用程序架构示意图。\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/architecture-2.png) Web 应用程序通常由应用程序业务逻辑层提供支持的 HTML 和 CSS 用户界面层组成。你可以用纯HTML来构建 Web 应用程序 JavaScript，也可以使用 React 和 Angular 等用户界面框架。 Web 应用程序的业务逻辑层通过一组与 Amazon Chime SDK 客户端库 JavaScript 进行交互。 JavaScript APIs[https://aws.github.io/amazon-chime-sdk-js/classes/defaultmeetingsession.html](https://aws.github.io/amazon-chime-sdk-js/classes/defaultmeetingsession.html) 是 SDK 的根对象。在构建服务器应用程序时，您可以通过 [https://aws.github.io/amazon-chime-sdk-js/classes/meetingsessionconfiguration.html](https://aws.github.io/amazon-chime-sdk-js/classes/meetingsessionconfiguration.html) 使用会议和与会者信息对其进行初始化并加入会议。 DefaultMeetingSession 还公开了 [https://aws.github.io/amazon-chime-sdk-js/interfaces/audiovideofacade.html](https://aws.github.io/amazon-chime-sdk-js/interfaces/audiovideofacade.html)，它使业务逻辑层能够采取行动，并注册在会话底层状态发生变化时更新用户界面的回调。 适用于 Amazon Chime SDK 的客户端库 JavaScript 是开源的，具有一组可自定义的组件，您可以根据需要覆盖这些组件。默认实现允许您构建完整的统一通信应用程序，例如我们演示 MeetingV2 应用程序。适用的 Amazon Chime 软件开发工具包客户端库 JavaScript 依赖于另外两个库： + [Browser-Detect](https://www.npmjs.com/package/browser-detect) 用于识别浏览器类型和功能。 + [ ProtoBufJs ](https://www.npmjs.com/package/protobufjs)对加入媒体会话所需的信号命令和响应进行编码和解码。 Amazon Chime SDK 还依赖浏览器或 Electron 应用程序为音频视频会话提供设备 APIs 管理和WebRTC实现。 Amazon Chime SDK 的源代码客户端库 JavaScript 已在 TypeScript，但你可以使用编译器将其编 TypeScript 译为。 JavaScript然后，您可以使用诸如 Webpack 等模块捆绑器将其捆绑。作为最佳实践，请 JavaScript 从 NPM 注册表中安装适用的 Amazon Chime SDK 客户端库，然后在 CommonJS 环境中使用它。 AWS 还提供了一个汇总脚本，用于将 Amazon Chime SDK 捆绑到缩小的 JS 文件中，以便您想将其[作为脚本](https://github.com/aws/amazon-chime-sdk-js/tree/master/demos/singlejs)标签直接包含在 HTML 中。 # 为 Amazon Chime SDK 构建服务器应用程序 以下部分中的信息说明了如何构建 Amazon Chime SDK 服务器应用程序。每个部分都根据需要提供了示例代码，您可以调整该代码以满足您的需求。 **Topics** + [为 Amazon Chime SDK 创建 IAM 用户或角色](create-iam-users-roles.md) + [配置 AWS 软件开发工具包以调用 Amazon Chime 软件开发工具包的 APIs](invoke-apis.md) + [为 Amazon Chime SDK 创建会议](create-meeting.md) + [为 Amazon Chime SDK 创建与会者](create-attendee.md) + [为 Amazon Chime SDK 向客户端发送响应](send-response-to-client.md) # 为 Amazon Chime SDK 创建 IAM 用户或角色 您可以将用户创建为 IAM 用户或适合您的使用案例的角色。然后，您可以为其分配以下策略。这样可以确保您拥有服务器应用程序中嵌入的 AWS SDK 的必要权限。反过来，这允许您对会议和与会者资源执行生命周期操作。 ``` // Policy ARN: arn:aws:iam::aws:policy/AmazonChimeSDK // Description: Provides access to Amazon Chime SDK operations { "Version": "2012-10-17", "Statement": [ { "Action": [ "chime:CreateMeeting", "chime:DeleteMeeting", "chime:GetMeeting", "chime:ListMeetings", "chime:CreateAttendee", "chime:BatchCreateAttendee", "chime:DeleteAttendee", "chime:GetAttendee", "chime:ListAttendees" ], "Effect": "Allow", "Resource": "*" } ]} ``` # 配置 AWS 软件开发工具包以调用 Amazon Chime 软件开发工具包的 APIs 此代码示例向您展示如何向 AWS SDK 传递凭证以及如何设置区域和终端节点。 ``` AWS.config.credentials = new AWS.Credentials(accessKeyId, secretAccessKey, null); const chime = new AWS.Chime({ region: 'us-east-1' }); chime.endpoint = new AWS.Endpoint('https://service.chime.aws.amazon.com/console'); ``` # 为 Amazon Chime SDK 创建会议 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateMeeting.html) API 调用接受一个必需参数，即 `ClientRequestToken`，该参数允许开发人员在唯一性上下文中传递内容。它还接受可选参数，例如代表要为会议选择的媒体服务数据面板区域的 `MediaRegion`、用于传递不透明标识符来代表会议主机的 `MeetingHostId`（如果适用），以及用于接收会议生命周期事件的 `NotificationsConfiguration`。默认情况下，Amazon 会 EventBridge 交付事件。或者，您也可以通过在 `NotificationsConfiguration` 中传递 SQS 队列 ARN 或 SNS 主题 ARN 来接收事件。API 返回一个 Meeting 对象`MeetingId`，该对象包含一个唯一的，`MediaRegion`以及带有一组媒体的`MediaPlacement`对象 URLs。 ``` meeting = await chime.createMeeting({ ClientRequestToken: clientRequestToken, MediaRegion: mediaRegion, MeetingHostId: meetingHostId, NotificationsConfiguration: { SqsQueueArn: sqsQueueArn, SnsTopicArn: snsTopicArn } }).promise(); ``` # 为 Amazon Chime SDK 创建与会者 创建会议后，您可以创建代表每个尝试加入媒体会话的用户的与会者资源。[https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_CreateAttendee.html) API 包含以下参数： + 要向其中添加用户的会议的 `MeetingId`。 + `ExternalUserId`，可以是身份系统中任何不透明用户标识符。 例如，如果您使用 Active Directory（AD），则可以是 AD 中用户的 Object ID。之所以`ExternalUserId`有价值，是因为当客户端应用程序收到来自客户端的与会者事件时，它会传回给他们。 SDKs这使客户端应用程序了解谁加入或离开会议，并从服务器应用程序中检索有关该用户的其他信息，例如显示名称、电子邮件或图片。 调用 `CreateAttendee` API 会生成一个 `Attendee` 对象。该对象包含由服务生成的唯一 `AttendeeId`、传入的 `ExternalUserId`，以及允许与会者在会议期间或在 [https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_DeleteAttendee.html](https://docs.aws.amazon.com/chime-sdk/latest/APIReference/API_meeting-chime_DeleteAttendee.html) API 删除与会者之前访问会议的签名 `JoinToken`。 ``` attendee = await chime.createAttendee({ MeetingId: meeting.MeetingId, ExternalUserId: externalUserId, }).promise(); ``` # 为 Amazon Chime SDK 向客户端发送响应 创建会议和与会者资源后，服务器应用程序应对会议和与会者对象进行编码并将其发送回客户端应用程序。客户需要这些信息来引导 Amazon Chime SDK 客户端库，并使与会者能够通过基 JavaScript于 Web 或 Electron 的应用程序成功加入会议。 # 为 Amazon Chime SDK 构建客户端应用程序 要构建客户端应用程序，请按照 [Amazon Chime JavaScript 软件开发工具包 API 概述](https://aws.github.io/amazon-chime-sdk-js/modules/apioverview.html)中列出的步骤进行操作。 GitHub概述提供所需的示例代码。 # 为 Amazon Chime SDK 将背景筛选器集成至客户端应用程序 本部分介绍如何使用背景模糊 2.0 和背景替换 2.0 以编程方式筛选视频背景。要将背景筛选器添加至视频流，创建包含 `VideoFxConfig` 对象的 `VideoFxProcessor`。然后将该处理器插入到 `VideoTransformDevice`。 后台过滤器处理器使用 TensorFlow 精简版机器学习模型 JavaScript Web Workers，并 WebAssembly 对视频流中每帧的背景应用过滤器。这些资产是在您创建 `VideoFxProcessor` 时的运行过程中下载。 [上的浏览器演示应用程序 GitHub](https://github.com/aws/amazon-chime-sdk-js/tree/main/demos/browser)使用了新的背景模糊和替换滤镜。若要试用，使用 `npm run start` 启动演示，加入会议，然后点击摄像头启用视频。打开**应用筛选器**菜单 (![\[Button with a circle and a downward arrow.\]](http://docs.aws.amazon.com/zh_cn/chime-sdk/latest/dg/images/blur-apply-filter-initial.png))，然后选择**背景模糊 2.0**或**背景替换 2.0**选项。 **Topics** + [关于使用适用于 Amazon Chime SDK 的背景筛选器](about-bg-filters.md) + [在 Amazon Chime 软件开发工具包客户端库中使用内容安全策略 JavaScript](content-security.md) + [为 Amazon Chime SDK 将背景筛选器添加到您的应用程序](add-filters.md) + [Amazon Chime SDK 的背景筛选器示例](example-bg-filter.md) # 关于使用适用于 Amazon Chime SDK 的背景筛选器 背景筛选器可以是 CPU 密集型，也可以是 GPU 密集型。某些移动设备和低规格笔记本电脑或台式机可能无法同时运行筛选器和多个视频流。 ## Amazon Chime SDK 的 SIMD 支持 在支持单指令、多数据 (SIMD) 的环境中，背景筛选器的效率更高。启用 SIMD 后，在给定的复杂度级别下，筛选器占用的 CPU 资源会更少。运行不支持 SIMD 的浏览器的低功耗设备可能无法运行背景筛选器。 ## Amazon Chime 软件开发工具包的网络GL2 支持 该`VideoFxProcessor`对象需要支持 Web GL2 的浏览器才能访问客户端设备上的 GPU。 ## Amazon Chime SDK 的内容分发和带宽 Amazon 内容分发网络会在运行时加载背景过滤 machine-learning-model文件。这可提供低延迟的全局分发，而无需提供一整套文件作为应用程序的一部分。但是，加载模型文件可能会增加应用程序某些部分的延迟。为了帮助减轻这种影响，浏览器会无限期缓存模型文件。该缓存使后续加载速度大大加快。作为最佳实践，请检查受支持的浏览器，然后在用户可能没有注意到任何延迟时创建背景筛选器资源。例如，您可以在用户在大厅等候或使用设备选择器时下载模型文件。 您的应用程序必须连接以下应用： + Amazon Chime SDK 媒体服务。 + 亚马逊 CloudFront 通过 HTTPS（端口 443）。 所有请求都发送到 `sdkassets.chime.aws` 的子域。无法访问内容分发网络或[内容安全策略](content-security.md)中未包含正确域名的应用程序将不能通过支持检查且无法使用筛选器。 有关的 IP 地址范围 CloudFront的更多信息，请参阅 *Amazon CloudFront 开发者指南*中的[ CloudFront 边缘服务器的位置和 IP 地址范围](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/LocationsOfEdgeServers.html)。 ## Amazon Chime SDK 的浏览器兼容性 下表列出了支持背景筛选器的浏览器和版本。 | 浏览器 | 支持的最低版本 | | --- | --- | | Firefox | 76\$1 | | 基于 Chromium 的浏览器和环境，包括 Edge 和 Electron | 78\$1 | | Android Chrome | 110\$1 | | macOS 上的 Safari | 16.3\$1 | | iOS（iPhone、iPad）上的 Safari | 16.x | | iOS 上的 Chrome | 110.0.0.x.x | | iOS 上的 Firefox (iPhone iPad) | 16.x | `VideoFxProcessor` 对象的 3.14 版本支持安卓系统。要获得 3.14 之前版本的 Android 设备支持，请使用 `BackgroundBlurVideoFrameProcessor` 和 `BackgroundReplacementVideoFrameProcessor` 对象。有关使用它们的更多信息，请参阅上的[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)页面 GitHub。 # 在 Amazon Chime 软件开发工具包客户端库中使用内容安全策略 JavaScript 现代 Web 应用程序使用内容安全策略保护用户免受某些类别的攻击。使用 `VideoFxProcessor` 的应用程序必须包含本节描述的策略指令。这些指令允许 Amazon Chime SDK 在运行时访问其所需的资源。 **Topics** + [所需的内容安全策略指令](#required-csp) + [内容安全策略示例](#example-csp) + [内容安全策略错误](#csp-errors) + [跨源开启器内容安全政策](#cross-origin-policy) ## 所需的内容安全策略指令 您必须使用以下内容安全策略指令。 + 对于 `script-src:`，添加 `blob: https://*.sdkassets.chime.aws` 以加载视频处理代码，并添加 `wasm-unsafe-eval` 以允许运行该代码。 + 对于 `script-src-elem:`，添加 `blob:` `https://*.sdkassets.chime.aws` 以从来源加载视频处理代码。 + 用于`worker-src:``blob: https://*.sdkassets.chime.aws`添加 JavaScript 跨源加载工作人员。 如果您忽略这些条目中的任何一个，或者您使用 HTTP 标头和 `http-equiv` 元标签指定策略，但意外通过交叉排除其中任何一个条目，则背景筛选器将无法初始化。该筛选器似乎不受支持，或者创建了一个无操作视频帧处理器。您将在浏览器控制台中看到错误，例如： ``` Refused to connect to 'https://static.sdkassets.chime.aws/bgblur/workers/worker.js…' because it violates the document's content security policy. ``` ### 必需的脚本策略指令 要正常运行，该`VideoFxProcessor`类必须在运行时从 Amazon 内容分发网络加载 JavaScript 类。这些类使用 Web GL2 实现视频的后期处理。要允许应用程序获取和运行这些类别，必须包含以下指令： + `script-src 'self' blob: https://*.sdkassets.chime.aws` + `script-src-elem 'self' blob: https://*.sdkassets.chime.aws` **注意** 要在 Safari 和 Firefox 上获得全面支持，必须使用 `script-src` 和 `script-src-elem` 指令。 ### 工作线程策略指令 将 JavaScript 类作为 blob `VideoFxProcessor` 加载以运行 Web 工作线程。该线程使用机器学习模型处理视频。要授予应用程序获取和使用此工作线程的访问权限，请包含以下指令： `worker-src 'self' blob: https://*.sdkassets.chime.aws` ### WebAssembly 政策 从亚马逊拥有的同一个内容交付网络`VideoFxProcessor`加载一个 WebAssembly (WASM) 模块。在 Chrome 95 及更高版本中，编译后的 WASM 模块无法跨越多个模块边界。要允许获取和实例化这些模块，请在 `script-src` 指令中包含 `'wasm-unsafe-eval'`。 有关内容安全政策文档的更多信息 WebAssembly，请参阅上的[WebAssembly 内容安全政策](https://github.com/WebAssembly/content-security-policy/blob/main/proposals/CSP.md) GitHub。 ### （可选）背景图片策略指令 要将动态加载的背景图像与背景替换筛选器一起使用，`VideoFxProcessor` 必须能够访问该图像。为此，请在托管图像的域中加入 `connect-src` 指令。 ## 内容安全策略示例 以下示例策略允许使用 `VideoFxProcessor`。`connect-src` 定义并不特定于 `VideoFxProcessor`。相反，它们与 Amazon Chime SDK 会议中的音频和视频有关。 ``` ``` ## 内容安全策略错误 如果省略任何必需指令，则 `VideoFxProcessor` 不会实例化且将不受支持。在这种情况下，浏览器控制台中会出现以下（或类似）错误： ``` Refused to connect to 'https://static.sdkassets.chime.aws/ml_media_fx/otherassets/worker.js' because it violates the document's content security policy. ``` ## 跨源开启器内容安全政策 为了限制内存使用量，该模块倾向于使用 `SharedArrayBuffer` 进行处理。但是，这需要您仔细配置 Web 安全。在为应用程序 HTML 提供服务时，必须设置以下标头： ``` Cross-Origin-Opener-Policy: same-origin Cross-Origin-Embedder-Policy: require-corp ``` 服务器必须设置这些，因为它们没有等效元标签。如果您不设置这些标头，则背景筛选器可能会占用稍多的 RAM。 背景筛选器可以是 CPU 密集型，也可以是 GPU 密集型。某些移动设备和低规格笔记本电脑或台式机可能无法同时运行筛选器和多个视频流。 # 为 Amazon Chime SDK 将背景筛选器添加到您的应用程序 添加背景筛选器的过程要遵循以下主要步骤： + 检查是否有支持的浏览器。 + 使用您要使用的配置创建 `VideoFxConfig` 对象。 + 使用配置对象创建 `VideoFxProcessor` 对象。 + 将 `VideoFxProcessor` 对象包含在 `VideoTransformDevice`。 + 使用 `VideoTransformDevice` 启动视频输入。 **注意** 要完成这些步骤，您必须先执行以下操作： 创建 `Logger`。 选择 `MediaDeviceInfo` 类视频设备。 成功加入 `MeetingSession`。 以下部分介绍如何完成流程的每个步骤。 **Topics** + [为 Amazon Chime SDK 在提供筛选器之前先检查是否受支持](support-check.md) + [为 Amazon Chime SDK 创建 VideoFxConfig 对象](create-videofxconfig.md) + [为 Amazon Chime SDK 创建 VideoFxProcessor 对象](create-videofxprocessor.md) + [为 Amazon Chime SDK 配置 VideoFxProcessor 对象](configure-videofxprocessor.md) + [为 Amazon Chime SDK 创建 VideoTransformDevice 对象](create-video-transform.md) + [为 Amazon Chime SDK 开始视频输入](start-video-input.md) + [为 Amazon Chime SDK 微调资源利用率](tuning.md) # 为 Amazon Chime SDK 在提供筛选器之前先检查是否受支持 Amazon Chime SDK 提供了一种异步静态方法，用于检查受支持的浏览器并尝试下载所需资产。但是，它不检查设备性能。作为最佳实践，在提供筛选器之前，始终确保用户的浏览器和设备可以支持筛选器。 ``` import { VideoFxProcessor } from 'amazon-chime-sdk-js'; if (!await VideoFxProcessor.isSupported(logger)) { // logger is optional for isSupported } ``` # 为 Amazon Chime SDK 创建 VideoFxConfig 对象 您可以在同一个对象中为 `backgroundBlur` 和 `backgroundReplacement` 定义配置。但是，不能同时为两个筛选器将 `isEnabled` 设置为 `true`。这是一个无效配置。 `VideoFxConfig` 类本身不进行验证。验证将在下一步骤中进行。 以下示例显示有效的 `VideoFxConfig`。 ``` const videoFxConfig: VideoFxConfig = { backgroundBlur: { isEnabled: false, strength: 'medium' }, backgroundReplacement: { isEnabled: false, backgroundImageURL: 'space.jpg', defaultColor: undefined, } } ``` 下表列出了您可以在 `VideoFxConfig` 对象中指定的 `VideoFxProcessor` 属性。 **背景模糊筛选器属性** | 属性 | Type | 说明 | | --- | --- | --- | | `isEnabled` | `boolean` | 当为 `true` 时，筛选器会模糊背景。 | | `strength` | `string` | 确定模糊程度。有效值：`low` \$1 `medium` \$1 `high`。 | **背景替换筛选器属性** | 属性 | Type | 说明 | | --- | --- | --- | | `isEnabled` | `boolean` | 当为 `true` 时，筛选器会替换背景。 | | `backgroundImageURL` | `string` | 背景图片的 URL。筛选器根据当前屏幕的尺寸动态调整图像大小。您可以使用诸如 `https://...` 等字符串或诸如 `data:image/jpeg;base64` 等 URL。 | | `defaultColor` | `string` | 十六进制颜色字符串，例如 `000000` 或 `FFFFFF`，或 `black` 或 `white` 等字符串。如果未指定图像 URL，则处理器会使用 `defaultColor` 作为背景。如果未指定 `defaultColor`，则处理器默认为黑色。 | # 为 Amazon Chime SDK 创建 VideoFxProcessor 对象 创建`VideoFxProcessor`对象时， AWS 服务器会下载运行时资源，或者浏览器缓存加载资源。如果网络或 CSP 配置阻止访问资产，则 `VideoFx.create` 操作会引发异常。结果 VideoFxProcessor 被配置为无操作处理器，这不会影响视频流。 ``` let videoFxProcessor: VideoFxProcessor | undefined = undefined; try { videoFxProcessor = await VideoFxProcessor.create(logger, videoFxConfig); } catch (error) { logger.warn(error.toString()); } ``` `VideoFxProcessor.create` 还会尝试从 `backgroundReplacement.backgroundImageURL` 中加载图像。如果图像加载失败，处理器会抛出异常。处理器还会出于其他原因抛出异常，例如配置无效、浏览器不受支持或硬件性能不足。 # 为 Amazon Chime SDK 配置 VideoFxProcessor 对象 下表列出可以配置的 `VideoFxProcessor` 属性。表下方的示例显示典型的运行时系统配置。 **背景模糊** 背景模糊具有以下属性： | 属性 | Type | 说明 | | --- | --- | --- | | `isEnabled` | `boolean` | 当为 `true` 时，筛选器会模糊背景。 | | `strength` | `string` | 确定模糊程度。有效值：`low` \$1`medium` \$1`high`. | **背景替换** 背景替换使用以下参数： | 属性 | Type | 说明 | | --- | --- | --- | | `isEnabled` | `boolean` | 当为 `true` 时，筛选器会替换背景。 | | `backgroundImageURL` | `string` | 背景图片的 URL。筛选器根据当前屏幕的尺寸动态调整图像大小。您可以使用诸如 `https://...` 等字符串或诸如 `data:image/jpeg;base64` 等 URL。 | | `defaultColor` | `string` | 十六进制颜色字符串，例如 `000000` 或 `FFFFFF`，或 `black` 或 `white` 等字符串。如果未指定图像 URL，则处理器会使用 `defaultColor` 作为背景。如果未指定 `defaultColor`，则处理器默认为黑色。 | **运行时更改配置** 您可以使用 `videoFxProcessor.setEffectConfig` 参数在运行时更改 `VideoFxProcessor` 配置。以下示例显示如何启用背景替换和禁用背景模糊。 **注意** 一次只能指定一种类型的背景替换。指定 `backgroundImageURL` 或 `defaultColor` 的值，但不能同时指定两者。 ``` videoFxConfig.backgroundBlur.isEnabled = false; videoFxConfig.backgroundReplacement.isEnabled = true; try { await videoFxProcessor.setEffectConfig(videoFxConfig); } catch(error) { logger.error(error.toString()) } ``` 如果 `setEffectConfig` 抛出异常，则之前的配置仍然有效。`setEffectConfig` 会在与导致 `VideoFxProcessor.create` 抛出异常的类似条件下抛出异常。 以下示例显示如何在视频运行时更改背景图像。 ``` videoFxConfig.backgroundReplacement.backgroundImageURL = "https://my-domain.com/my-other-image.jpg"; try { await videoFxProcessor.setEffectConfig(videoFxConfig); } catch(error) { logger.error(error.toString()) } ``` # 为 Amazon Chime SDK 创建 VideoTransformDevice 对象 以下示例显示如何创建包含 `VideoFxProcessor` 的 `VideoTransformDevice` 对象。 ``` // assuming that logger and videoInputDevice have already been set const videoTransformDevice = new DefaultVideoTransformDevice( logger, videoInputDevice, [videoFxProcessor] ); ``` # 为 Amazon Chime SDK 开始视频输入 以下示例演示如何使用 `VideoTransformDevice` 对象开始视频输入。 ``` // assuming that meetingSession has already been created await meetingSession.audioVideo.startVideoInput(videoTransformDevice); meetingSession.audioVideo.start(); meetingSession.audioVideo.startLocalVideoTile(); ``` # 为 Amazon Chime SDK 微调资源利用率 创建 `VideoFxProcessor` 时，您可以提供可选 `processingBudgetPerFrame` 参数并控制筛选器占用 CPU 和 GPU 量。 ``` let videoFxProcessor: VideoFxProcessor | undefined = undefined; const processingBudgetPerFrame = 50; try { videoFxProcessor = await VideoFxProcessor.create(logger, videoFxConfig, processingBudgetPerFrame); } catch (error) { logger.warn(error.toString()); } ``` `VideoFxProcessor` 需要时间处理帧。时间长短取决于设备、浏览器以及浏览器或设备上正在运行的其他程序。处理器使用*预算*的概念确定处理和渲染每帧所用的时间。 处理时间以毫秒为单位。举个如何使用预算的示例，1 秒有 1000 毫秒。将每秒 15 帧的视频捕获作为目标，总预算为 1000 毫秒/15fps = 66 毫秒。通过在 `processingBudgetPerFrame` 参数中提供值 `50`，您可以将预算设置为其中的 50% 或 33ms，如上例所示。 然后 `VideoFxProcessor` 尝试在指定的预算范围内处理帧。如果处理超出预算，处理器会降低视觉质量使其保持在预算范围内。处理器继续将视觉质量降低到最低限度后，它会停止降低。这种处理持续时间是持续测量的，因此，如果有更多资源可用，例如关闭另一个应用程序并释放 CPU，处理器会再次提高视觉质量，直到达到预算或者达到最高的视觉质量。 如果您未向 `processingBudgetPerFrame` 提供值，则 `VideoFxProcessor` 默认为 `50`。 # Amazon Chime SDK 的背景筛选器示例 以下示例显示如何实施筛选器 ``` 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); } ```