本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。 # 使用適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫 本指南提供適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫的概念概觀，以及關鍵伺服器和用戶端元件的範例程式碼。 **Topics** + [了解 Amazon Chime SDK 應用程式的元件](components.md) + [了解適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫的重要概念](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 應用程式，您可以使用下列元件： + 適用於** JavaScript 的 Amazon Chime SDK 用戶端程式庫**，這是您整合到瀏覽器或 Electron Web 應用程式的用戶端 SDK。您可以新增 [ Amazon Chime SDK for JavaScript NPM 套件](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 開發套件**，您的伺服器應用程式用來驗證和授權來自 Web 應用程式的會議請求的 Amazon Chime SDK API。 AWS 開發套件為您提供 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 更為複雜。如果您的應用程式目前未使用伺服器應用程式，您可以從[示範/無伺服器](https://github.com/aws/amazon-chime-sdk-js/tree/master/demos/serverless)資料夾中包含的 CloudFormation 範本開始。該示範說明如何建置使用 AWS SDK 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/)。 # 了解適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫的重要概念 若要完全了解如何建立和管理會議和使用者，您需要了解這些概念： ** [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 SDK 用戶端程式庫的根物件，適用於 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 應用程式，該應用程式會使用它來執行個體化 `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，透過追蹤加入或離開的使用者、靜音或取消靜音、主動說話或連線能力不佳，來接聽推動使用者體驗變更的關鍵事件，例如出席者名單。您也可以使用這些 APIs 將音訊控制 HTML 元素繫結至會議的音訊輸出，並透過選取的音訊輸出裝置播放。 ** [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 的服務架構 此高階架構圖顯示 中列出的元件如何與其他 AWS 服務[了解適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫的重要概念](key-concepts.md)互動和運作： ![\[顯示 Amazon Chime SDK JavaScript 用戶端程式庫如何與其他 AWS 服務互動的圖表。\]](http://docs.aws.amazon.com/zh_tw/chime-sdk/latest/dg/images/architecture-1.png) # 了解 Amazon Chime SDK 的 Web 應用程式架構 您可以從內容交付網路提供 Web 應用程式，並在使用者導覽至瀏覽器中的 URL 時載入。您也可以將其包裝在使用者在其機器上安裝的平台原生 Electron 應用程式中。 若要加入新的或現有的會議，Web 應用程式會對伺服器應用程式發出 REST 請求。一般而言，請求會攜帶授權字符或您的應用程式用於其他 API 請求的 Cookie。您也可以設計 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 應用程式可以透過向 [https://nearest-media-region.l.chime.aws ](https://nearest-media-region.l.chime.aws/)端點提出 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 使用者和角色也需要 [ AmazonChimeSDK ](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_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) APIs。它會驗證登入資料，並確保在請求區域中的資料平面中引導工作階段。 控制平面也會觸發 [ Amazon Chime SDK 事件](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html)至通知機制，例如 Amazon EventBridge、Amazon Simple Queueing Service (SQS) 或 Amazon Simple Notification Service (SNS)。 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_tw/chime-sdk/latest/dg/images/architecture-2.png) Web 應用程式通常包含由應用程式商業邏輯層支援的 HTML 和 CSS 使用者介面層。您可以使用純 HTML 和 JavaScript 建置 Web 應用程式，也可以使用 React 和 Angular 等 UI 架構。 Web 應用程式的商業邏輯層會透過一組 JavaScript APIs 與適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫互動。[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)，這可讓商業邏輯層採取動作，並在工作階段的基礎狀態變更時註冊更新使用者介面的回呼。 適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫是開放原始碼，具有一組您可以視需要覆寫的可自訂元件。預設實作可讓您建置完整的統一通訊應用程式，例如我們的示範 MeetingV2 應用程式。適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫取決於其他兩個程式庫： + [ 瀏覽器偵測](https://www.npmjs.com/package/browser-detect)用於識別瀏覽器類型和功能。 + [ ProtoBufJs ](https://www.npmjs.com/package/protobufjs) 可對加入媒體工作階段所需的訊號命令和回應進行編碼和解碼。 Amazon Chime SDK 也依賴瀏覽器或 Electron 應用程式為音訊視訊工作階段提供 Device Management APIs和 WebRTC 實作。 適用於 JavaScript 的來源 Amazon Chime SDK 用戶端程式庫位於 TypeScript 中，但您可以使用 TypeScript 編譯器將其編譯至 JavaScript。然後，您可以使用諸如 Webpack 的模組綁定器來綁定它。最佳實務是，從 NPM 登錄檔安裝適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫，然後在 CommonJS 環境中使用它。 AWS 也提供彙總指令碼，用於將 Amazon Chime SDK 綁定到小型 JS 檔案，以防您想要直接將其作為[指令碼標籤包含在 HTML 中](https://github.com/aws/amazon-chime-sdk-js/tree/master/demos/singlejs)。 # 為 Amazon Chime SDK 建置伺服器應用程式 下一節中的資訊說明如何建置 Amazon Chime SDK 伺服器應用程式。每個區段都會視需要提供範例程式碼，而且您可以調整該程式碼以符合您的需求。 **Topics** + [為 Amazon Chime SDK 建立 IAM 使用者或角色](create-iam-users-roles.md) + [設定 AWS SDK 以叫用 Amazon Chime SDK 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 SDK 以叫用 Amazon Chime SDK 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 會交付事件。或者，您也可以在 中傳遞 SQS 佇列 ARN 或 SNS 主題 ARN 來接收事件`NotificationsConfiguration`。API 傳回包含唯一 的會議物件`MeetingId`，以及具有一組媒體 URLs的 `MediaRegion`和 `MediaPlacement` 物件。 ``` 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 中使用者的物件 ID。`ExternalUserId` 很有價值，因為它會在從用戶端 SDKs 接收出席者事件時傳回給用戶端應用程式。這可讓用戶端應用程式知道誰加入或離開會議，並從伺服器應用程式擷取有關該使用者的其他資訊，例如顯示名稱、電子郵件或圖片。 呼叫 `CreateAttendee` API 會導致 `Attendee` 物件。物件包含由服務`AttendeeId`產生的唯一 、傳入`ExternalUserId`的 ，以及`JoinToken`允許出席者在其持續時間內存取會議的已簽署 ，或直到 [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 刪除出席者為止。 ``` attendee = await chime.createAttendee({ MeetingId: meeting.MeetingId, ExternalUserId: externalUserId, }).promise(); ``` # 傳送回應給 Amazon Chime SDK 的用戶端 建立會議和出席者資源後，伺服器應用程式應編碼並將會議和出席者物件傳回用戶端應用程式。用戶端需要這些資訊才能引導適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫，並讓出席者能夠從 Web 或 Electron 型應用程式成功加入會議。 # 為 Amazon Chime SDK 建置用戶端應用程式 若要建置用戶端應用程式，請遵循 GitHub 上的 [Amazon Chime JavaScript SDK API 概觀](https://aws.github.io/amazon-chime-sdk-js/modules/apioverview.html)中列出的步驟。概觀會視需要提供範例程式碼。 # 將背景篩選條件整合至 Amazon Chime SDK 的用戶端應用程式 本節說明如何使用背景模糊 2.0 和背景替換 2.0，以程式設計方式篩選影片背景。若要將背景篩選條件新增至影片串流，您可以建立包含`VideoFxConfig`物件`VideoFxProcessor`的 。然後，將該處理器插入 `VideoTransformDevice`。 背景篩選條件處理器使用 TensorFlow Lite 機器學習模型、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_tw/chime-sdk/latest/dg/images/blur-apply-filter-initial.png))，然後選擇其中一個**背景模糊 2.0** 或**背景替換 2.0 **選項。 **Topics** + [關於使用 Amazon Chime SDK 的背景篩選條件](about-bg-filters.md) + [搭配適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫使用內容安全政策](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 SDK 的 WebGL2 支援 `VideoFxProcessor` 物件需要支援 WebGL2 的瀏覽器，才能存取用戶端裝置上的 GPU。 ## Amazon Chime SDK 的內容交付和頻寬 Amazon 內容交付網路會在執行時間載入背景篩選條件的machine-learning-model檔案。這可提供低延遲的全域分佈，而不需要在應用程式中提供完整的檔案套件。不過，載入模型檔案可能會為應用程式的某些部分增加延遲。為了協助減輕影響，瀏覽器會無限期快取模型檔案。該快取可大幅加快後續載入速度。最佳實務是檢查支援的瀏覽器，然後在使用者可能不會注意到任何延遲時建立背景篩選條件資源。例如，您可以在使用者在大廳等待時或使用裝置挑選器時下載模型檔案。 您的應用程式必須連線至下列項目： + Amazon Chime SDK 媒體服務。 + 透過 HTTPS （連接埠 443) 的 Amazon CloudFront。 所有請求都是 的子網域`sdkassets.chime.aws`。無法存取內容交付網路或在其[內容安全政策](content-security.md)中未包含正確網域的應用程式，將無法通過其支援檢查，也無法使用篩選條件。 如需 CloudFront IP 地址範圍的詳細資訊，請參閱《*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 上的 Safari (iPhone、iPad) | 16.x | | iOS 上的 Chrome | 110.0.0.x.x | | iOS 上的 Firefox (iPhone iPad) | 16.x | `VideoFxProcessor` 物件的 3.14 版支援 Android。對於 3.14 之前版本的 Android 裝置支援，請使用 `BackgroundBlurVideoFrameProcessor`和 `BackgroundReplacementVideoFrameProcessor` 物件。如需有關使用它們的詳細資訊，請參閱 GitHub 上的 [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)頁面。 # 搭配適用於 JavaScript 的 Amazon Chime SDK 用戶端程式庫使用內容安全政策 現代 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 類別。這些類別使用 WebGL2 實作影片的後置處理。若要允許應用程式擷取和執行這些類別，您必須包含下列指令： + `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 類別`VideoFxProcessor`載入為 Blob，以執行 Web 工作者執行緒。執行緒使用機器學習模型來處理視訊。若要授予應用程式存取權以擷取和使用此工作者，請包含下列指令： `worker-src 'self' blob: https://*.sdkassets.chime.aws` ### WebAssembly 政策 會從相同的 Amazon 擁有的內容交付網路`VideoFxProcessor`載入 WebAssembly (WASM) 模組。在 Chrome 95 和更新版本中，編譯的 WASM 模組無法跨多個模組邊界傳遞。若要允許擷取和執行個體化這些模組，請在 `script-src` 指令`'wasm-unsafe-eval'`中包含 。 如需 WebAssembly 內容安全政策文件的詳細資訊，請參閱 GitHub 上的 [WebAssembly 內容安全政策](https://github.com/WebAssembly/content-security-policy/blob/main/proposals/CSP.md)。 ### （選用） 背景映像政策指令 若要搭配背景取代篩選條件使用動態載入的背景影像， `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`物件。 + 在 `VideoTransformDevice` 中包含 `VideoFxProcessor` 物件。 + 使用 `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物件 您可以在同一個物件`backgroundReplacement`中定義 `backgroundBlur`和 的組態。不過，您無法同時`true`針對兩個篩選條件`isEnabled`將 設定為 。這是無效的組態。 `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`，篩選條件會取代背景\$1。 | | `backgroundImageURL` | `string` | 背景映像的 URL。篩選條件會將影像動態調整為目前畫面的維度。您可以使用字串，例如 `https://...`或資料 URL，例如 `data:image/jpeg;base64`。 | | `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://...`或資料 URL，例如 `data:image/jpeg;base64`。 | | `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物件 下列範例示範如何建立包含 的`VideoTransformDevice`物件`VideoFxProcessor`。 ``` // 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 個影格的影片擷取，總預算為 1000ms/15fps = 66ms。您可以在 `processingBudgetPerFrame` 參數`50`中提供 值，以設定預算的 50% 或 33 毫秒，如上述範例所示。 `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); } ```