翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 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-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-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 ウェブアプリケーションに統合するクライアント側 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) API および [https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API](https://developer.mozilla.org/en-US/docs/Web/API/WebRTC_API) API を活用して、会議への参加、音声や動画の交換、他の参加者とのコンテンツの共有を行えます。これは、さまざまな種類のメディアを管理したり、それらのリソースをアプリケーションのユーザーインターフェイスにバインドしたりするためのコントロールサーフェスになります。
+ ** AWS SDK**は、サーバーアプリケーションでウェブアプリケーションからの会議参加依頼を認証および認可するために使用する Amazon Chime SDK API です。 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 リソースと同様に、 AWS Identity and Access Management (IAM) サービスはこれらのアクションへのアクセスを設定します。 AWS SDK は[複数のプログラミング言語で](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 メディアサービス**では、JavaScript 用の Amazon Chime SDK クライアントライブラリで会議への接続に使用する音声、動画、シグナリングを提供します。メディアサービスは世界中で利用でき、音声ミキシング、動画転送、TURN リレーを使用した NAT トラバーサルをサポートしています。Amazon Chime サービスチームは、これらのサービスをデプロイ、監視、管理します。メディアサービスは 99.77.128.0/18 という単一の IP アドレス範囲でホストされ、ポート 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 リージョンのいずれかで会議を作成できます。会議を作成すると、メディア URL のリストが返されます。これらは会議に参加するうえで必要なデータの重要な部分であり、会議に参加しようとしているすべてのユーザーにそのデータを配布する必要があります。
** [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) – 会議で各ユーザーのセッションを表す JavaScript 用の Amazon Chime SDK クライアントライブラリのルートオブジェクト。ウェブアプリケーションでは、まず、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 コールの応答です。サーバーアプリケーションでこのデータをウェブアプリケーションに渡し、ウェブアプリケーションでそのデータを使用して `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) – 会議で使用される重要なインターフェイスです。会議の開始、制御、終了を行う API を提供します。さらに、参加または退出するユーザー、ミュートまたはミュート解除されているユーザー、活発に発言しているユーザー、接続状態が悪いユーザーを追跡することにより、ユーザーエクスペリエンスの変化を促す重要なイベント (参加者の一覧など) をリッスンする API も提供します。これらの API を使用して、音声コントロール 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) – コンテンツ共有の開始/停止、一時停止/一時停止解除を行う API。また、ライフサイクルイベントをリッスンしてコンテンツ共有のステータスを追跡する API としても利用できます。
**[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 のサービスアーキテクチャについて
この大まかなアーキテクチャ図は、[JavaScript 用 Amazon Chime SDK クライアントライブラリの重要な概念について](key-concepts.md) に記載されたコンポーネントが他の AWS サービスとどのようにやり取りし、連携するのかを示しています。
![\[JavaScript 用の Amazon Chime SDK クライアントライブラリが他の AWS のサービスとどのようにやり取りするかを示す図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/architecture-1.png)
# Amazon Chime SDK のウェブアプリケーションのアーキテクチャについて
コンテンツ配信ネットワークからウェブアプリケーションを提供し、ユーザーがブラウザで URL に移動した際に読み込むことができます。また、ユーザーがマシンにインストールするプラットフォームネイティブな Electron アプリケーションにラップすることもできます。
新規または既存の会議に参加するために、ウェブアプリケーションでサーバーアプリケーションに REST リクエストを出します。通常、リクエストには、アプリケーションで他の API リクエストに使用する認可トークンまたは Cookie が含まれます。また、リージョンヒントをサーバーに送信するようにウェブクライアントを設計することもできます。サーバーは、後に 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) API を提供します。認証情報を検証し、セッションがリクエストされたリージョンのデータプレーンでブートストラップされるようにします。
コントロールプレーンは、[Amazon EventBridge、Amazon Simple Queueing Service (SQS)、Amazon Simple Notification Service (SNS) などの通知メカニズムにも Amazon Chime SDK Events ](https://docs.aws.amazon.com/chime-sdk/latest/ag/automating-chime-with-cloudwatch-events.html) をトリガーします。 は、サービス AWS を常にモニタリングし、負荷の増加に応じて自動的にスケーリングします。 EventBridge API は、不透明なユーザー識別子のみを受け入れ、ユーザーデータを受け入れないように設計されているため、データ主権の要件に準拠しています。
# 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 のウェブアプリケーションコンポーネントのアーキテクチャについて
この図は、Amazon Chime SDK ウェブクライアントアプリケーションのアーキテクチャを示しています。
![\[Amazon Chime SDK ウェブアプリケーションのアーキテクチャを示す図。\]](http://docs.aws.amazon.com/ja_jp/chime-sdk/latest/dg/images/architecture-2.png)
ウェブアプリケーションは通常、アプリケーションのビジネスロジックレイヤーを基盤とする HTML および CSS のユーザーインターフェイスレイヤーで構成されています。プレーンな HTML や JavaScript でウェブアプリケーションを構築したり、React や Angular などの UI フレームワークを使用したりすることができます。
ウェブアプリケーションのビジネスロジックレイヤーは、一連の JavaScript API を通じて 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 クライアントライブラリは、他の 2 つのライブラリに依存しています。
+ [ Browser-Detect ](https://www.npmjs.com/package/browser-detect): ブラウザのタイプと機能を識別します。
+ [ ProtoBufJs ](https://www.npmjs.com/package/protobufjs): メディアセッションへの参加に必要なシグナリングコマンドとレスポンスをエンコードおよびデコードします。
また、Amazon Chime SDK では、ブラウザまたは Electron アプリケーションを活用して、音声および動画セッション用のデバイス管理 API と WebRTC 実装を提供しています。
JavaScript 用のソース Amazon Chime SDK クライアントライブラリは TypeScript にありますが、TypeScript コンパイラを使用して JavaScript にコンパイルすることが可能です。その後、Webpack などのモジュールバンドラーを使用してバンドルできます。ベストプラクティスとして、NPM レジストリから JavaScript 用の Amazon Chime SDK クライアントライブラリをインストールし、CommonJS 環境で使用します。また、HTML にスクリプトタグとして直接含める場合に備えて、Amazon Chime SDK を最小限の JS ファイルにバンドルするためのロールアップスクリプト AWS も用意されています。 [https://github.com/aws/amazon-chime-sdk-js/tree/master/demos/singlejs](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)
+ [Amazon Chime AWS SDK の APIs を呼び出すように SDK を設定する](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": "*"
}
]}
```
# Amazon Chime AWS SDK の APIs を呼び出すように SDK を設定する
このコードサンプルでは、 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 は、一意の `MeetingId` を含む Meeting オブジェクト、`MediaRegion`、一連のメディアの URL を含む `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`。ID システムからの不透明なユーザー識別子であればどれでも構いません。
例えば、Active Directory (AD) を使用する場合、これは AD 内のユーザーのオブジェクト ID である可能性があります。`ExternalUserId` は、クライアント SDK から参加者イベントを受信するとクライアントアプリケーションに返されるため、有用です。これにより、クライアントアプリケーションで会議に参加または退席した人物を把握し、表示名、メールアドレス、画像など、そのユーザーに関する追加情報をサーバーアプリケーションから取得することができます。
`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 でクライアントへのレスポンスを送信する
会議および参加者リソースを作成したら、サーバーアプリケーションで会議および参加者オブジェクトをエンコードしてクライアントアプリケーションに送り返す必要があります。クライアントでは、JavaScript 用の Amazon Chime SDK クライアントライブラリをブートストラップし、参加者がウェブまたは Electron ベースのアプリケーションから会議に正常に参加できるようにするために、これらの情報が必要です。
# Amazon Chime SDK でクライアントアプリケーションを構築する
クライアントアプリケーションを構築するには、GitHub の「[Amazon Chime JavaScript SDK API Overview](https://aws.github.io/amazon-chime-sdk-js/modules/apioverview.html)」に記載されたステップに従います。概要では、必要に応じてコード例が提供されています。
# Amazon Chime SDK で背景フィルタをクライアントアプリケーションに統合する
このセクションでは、背景ぼかし 2.0 と背景置換 2.0 を使用して動画の背景をプログラムでフィルタリングする方法について説明します。動画ストリームに背景フィルタを追加するには、`VideoFxConfig` オブジェクトを含む `VideoFxProcessor` を作成します。次に、そのプロセッサを `VideoTransformDevice` に挿入します。
背景フィルタプロセッサでは、TensorFlow Lite 機械学習モデル、JavaScript ウェブワーカー、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/ja_jp/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` オブジェクトでは、クライアントデバイスの GPU にアクセスするために WebGL2 をサポートしているブラウザが必要です。
## Amazon Chime SDK のコンテンツ配信と帯域幅
Amazon コンテンツ配信ネットワークでは、実行時に背景フィルタ用の機械学習モデルファイルを読み込みます。これにより、アプリケーションの一部としてファイル一式を提供することなく、低レイテンシーのグローバル配信が可能になります。ただし、モデルファイルを読み込むと、アプリケーションの一部にレイテンシーが追加される可能性があります。その影響を軽減するために、ブラウザではモデルファイルを無期限にキャッシュします。そのキャッシュにより、後続の読み込みが大幅に迅速化されます。ベストプラクティスとして、サポートされているブラウザを確認した後、ユーザーがレイテンシーに気付いていないと思われるときに背景フィルタリソースを作成することが挙げられます。例えば、ユーザーがロビーで待っている間や、デバイスピッカーを使用している間にモデルファイルをダウンロードすることができます。
アプリケーションを以下に接続する必要があります。
+ 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 以降 |
| Chromium ベースのブラウザと環境 (Edge や Electron を含む) | 78 以降 |
| Android Chrome | 110 以降 |
| macOS 版 Safari | 16.3 以降 |
| 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 クライアントライブラリでコンテンツセキュリティポリシーを使用する
最新のウェブアプリケーションでは、特定の種類の攻撃からユーザーを保護するために、コンテンツセキュリティポリシーが使用されています。`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:` では、オリジンをまたいでワーカーの JavaScript を読み込むために `blob: https://*.sdkassets.chime.aws` を追加します。
これらのエントリのいずれかを省略したり、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` ディレクティブを使用する必要があります。
### ワーカーポリシーディレクティブ
`VideoFxProcessor` では JavaScript クラスをブロブとして読み込んで、ウェブワーカースレッドを実行します。このスレッドでは、機械学習モデルを使用して動画を処理します。このワーカーを取得して使用するためのアクセス権をアプリケーションに付与するには、次のディレクティブを含めてください。
`worker-src 'self' blob: https://*.sdkassets.chime.aws`
### WebAssembly ポリシー
`VideoFxProcessor` では、Amazon が所有する同じコンテンツ配信ネットワークから WebAssembly (WASM) モジュールを読み込みます。Chrome 95 以降では、コンパイルされた WASM モジュールを複数のモジュール境界をまたいで渡すことはできません。これらのモジュールを取得してインスタンス化できるようにするには、`'wasm-unsafe-eval'` を `script-src` ディレクティブに含めてください。
WebAssembly のコンテンツセキュリティポリシーのドキュメントに関する詳細については、GitHub の [WebAssembly Content Security Policy](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` を優先して使用します。ただし、このためにはウェブセキュリティを慎重に設定する必要があります。アプリケーション 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` プロパティが一覧表示されています。
**背景ぼかしフィルタのプロパティ**
| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `isEnabled` | `boolean` | `true` の場合、フィルタで背景をぼかします。 |
| `strength` | `string` | ぼかしの度合いを決定します。有効な値: `low` \$1 `medium` \$1 `high` |
**背景置換フィルタのプロパティ**
| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `isEnabled` | `boolean` | `true` の場合、フィルタで背景が置換されます。 |
| `backgroundImageURL` | `string` | 背景画像の URL。フィルタでは、現在の画面の大きさに合わせて画像のサイズを動的に変更します。`https://...` などの文字列や、`data:image/jpeg;base64` などのデータ URL を使用できます。 |
| `defaultColor` | `string` | `000000` や `FFFFFF` などの 16 進数のカラー文字列、または `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` プロパティが一覧表示されています。表の下にある例は、一般的なランタイム設定を示しています。
**背景ぼかし**
背景ぼかしでは、以下のプロパティを取得します。
| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `isEnabled` | `boolean` | `true` の場合、フィルタで背景をぼかします。 |
| `strength` | `string` | ぼかしの度合いを決定します。有効な値: `low` \$1 `medium` \$1 `high`. |
**背景置換**
背景置換では、以下のパラメータを取得します。
| プロパティ | 型 | 説明 |
| --- | --- | --- |
| `isEnabled` | `boolean` | `true` の場合、フィルタで背景が置換されます。 |
| `backgroundImageURL` | `string` | 背景画像の URL。フィルタでは、現在の画面の大きさに合わせて画像のサイズを動的に変更します。`https://...` などの文字列や、`data:image/jpeg;base64` などのデータ URL を使用できます。 |
| `defaultColor` | `string` | `000000` や `FFFFFF` などの 16 進数のカラー文字列、または `black` や `white` などの文字列。画像 URL を指定しない場合、プロセッサでは `defaultColor` を背景として使用します。`defaultColor` を指定しない場合、プロセッサはデフォルトの黒になります。 |
**実行時に設定を変更する**
`videoFxProcessor.setEffectConfig` パラメータを使用して、実行時に `VideoFxProcessor` 設定を変更できます。次の例は、背景置換を有効にして、背景ぼかを無効にする方法を示しています。
**注記**
一度に 1 つのタイプの背景置換のみを指定できます。値を `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 フレーム/秒の動画キャプチャを目安に設定すると、合計のバジェットは 1000ms/15fps = 66 ミリ秒になります。上の例で示されているように、`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);
}
```