amazon chime sdk js
Release amazon-chime-sdk-3.25.0
Amazon Chime SDK プロジェクト委員会
Amazon Chime SDK React コンポーネント
Amazon Chime SDK は、開発者がメッセージング、オーディオ、ビデオ、画面共有機能をウェブまたはモバイルアプリケーションに迅速に追加するために使用できるリアルタイム通信コンポーネントのセットです。
開発者は、AWS のグローバル通信インフラストラクチャ上に構築して、アプリケーションで魅力的なエクスペリエンスを提供できます。たとえば、健康アプリケーションにビデオを追加して、患者が健康上の問題について医師に遠隔から相談したり、公衆電話ネットワークと統合するためにカスタマイズされた音声プロンプトを作成したりできます。
Amazon Chime SDK for JavaScript は、AWS アカウントで作成した会議セッションのリソースに接続することで機能します。 SDK には、会議セッションの構成、オーディオおよびビデオ デバイスの一覧表示と選択、画面共有と画面共有表示の開始と停止、メディア イベント時のコールバックの受信など、Web アプリケーションでカスタムの通話およびコラボレーション エクスペリエンスを構築するために必要なすべての機能が含まれています。音量の変更が発生し、音声のミュートやビデオ タイルのバインドなどの会議機能を制御します。
React アプリケーションを構築している場合は、クライアント側の状態管理と、音声およびビデオ会議アプリケーションで使用される一般的な Web インターフェイス用の再利用可能な UI コンポーネントを提供する Amazon Chime SDK React コンポーネント ライブラリの使用を検討してください。 Amazon Chime は、ネイティブモバイルアプリケーション開発用に、iOS 用 Amazon Chime SDK および Android 用 Amazon Chime SDK も提供しています。
Amazon Chime SDK プロジェクトボードは、すべてのリポジトリにわたるコミュニティ機能リクエストのステータスをキャプチャします。ボード上の列の説明は、このガイドに記載されています。
以下に加えて、Amazon Chime SDK に関するすべてのブログ投稿のリストを次に示します。
次の開発者ガイドでは、技術的な対象者向けの特定のトピックについて説明します。
次の開発者ガイドでは、Amazon Chime SDK をより広範に説明しています。
.jsファイルにバンドルするスクリプトREADME に記載されているリソースを確認し、Chime SDK for JavaScript での開発方法に関するガイダンスとしてクライアント ドキュメントを使用してください。さらに、問題データベースと FAQ を検索して、問題がすでに解決されているかどうかを確認してください。そうでない場合は、提供されたテンプレートを使用して問題を解決してください。
ブログ投稿「Amazon Chime SDK 会議イベントのモニタリングとトラブルシューティング」では、会議イベントを使用して、Amazon CloudWatch にログインしてアプリケーションのトラブルシューティングを行う方法について詳しく説明しています。
さらに質問がある場合、またはビジネスのサポートが必要な場合は、AWS カスタマーサポートにお問い合わせください。ここでサポート プランを確認できます。
Amazon Chime SDK for JavaScript は、ほとんどの最新ブラウザでサポートされているリアルタイム通信 API である WebRTC を使用します。 WebRTC に関する一般的なリソースをいくつか紹介します。
Node.js バージョン 18 以降を使用していることを確認してください。ノード 20 が推奨され、サポートされています。
Amazon Chime SDK for JavaScript を既存のアプリケーションに追加するには、npm からパッケージを直接インストールします。
npm install amazon-chime-sdk-js --save
Amazon Chime SDK for JavaScript は ES2015 をターゲットにしており、サポートされているすべてのブラウザと完全な互換性があることに注意してください。
クライアント アプリケーションで会議セッションを作成します。
import {
ConsoleLogger ,
DefaultDeviceController ,
DefaultMeetingSession ,
LogLevel ,
MeetingSessionConfiguration
} from 'amazon-chime-sdk-js' ;
const logger = new ConsoleLogger ( 'MyLogger' , LogLevel . INFO ) ;
const deviceController = new DefaultDeviceController ( logger ) ;
// You need responses from server-side Chime API. See below for details.
const meetingResponse = /* The response from the CreateMeeting API action */ ;
const attendeeResponse = /* The response from the CreateAttendee or BatchCreateAttendee API action */ ;
const configuration = new MeetingSessionConfiguration ( meetingResponse , attendeeResponse ) ;
// In the usage examples below, you will use this meetingSession object.
const meetingSession = new DefaultMeetingSession (
configuration ,
logger ,
deviceController
) ; AWS SDK、AWS コマンドラインインターフェイス (AWS CLI)、または REST API を使用して API 呼び出しを行うことができます。このセクションでは、サーバー アプリケーション (Node.js など) で AWS SDK for JavaScript を使用します。詳細については、「Amazon Chime SDK API リファレンス」を参照してください。
️ サーバーアプリケーションには、Amazon Chime SDK for JavaScript は必要ありません。
const AWS = require ( 'aws-sdk' ) ;
const { v4 : uuid } = require ( 'uuid' ) ;
// You must use "us-east-1" as the region for Chime API and set the endpoint.
const chime = new AWS . ChimeSDKMeetings ( { region : 'us-east-1' } ) ;
const meetingResponse = await chime
. createMeeting ( {
ClientRequestToken : uuid ( ) ,
MediaRegion : 'us-west-2' , // Specify the region in which to create the meeting.
} )
. promise ( ) ;
const attendeeResponse = await chime
. createAttendee ( {
MeetingId : meetingResponse . Meeting . MeetingId ,
ExternalUserId : uuid ( ) , // Link the attendee to an identity managed by your application.
} )
. promise ( ) ;ここで、 meetingResponseオブジェクトとattendeeResponseオブジェクトをクライアント アプリケーションに安全に転送します。これらのオブジェクトには、Amazon Chime SDK for JavaScript を使用して会議に参加するクライアントアプリケーションに必要なすべての情報が含まれています。
createMeeting() の MediaRegion パラメーターの値は、理想的には、会議を作成しているユーザーに最も近いメディア領域の 1 つに設定する必要があります。実装は、Amazon Chime SDK メディアリージョンドキュメントのトピック「最も近いメディアリージョンの選択」にあります。
クライアントアプリケーションでメッセージングセッションを作成し、Amazon Chime SDK for Messaging からメッセージを受信します。
import { ChimeSDKMessagingClient } from '@aws-sdk/client-chime-sdk-messaging' ;
import {
ConsoleLogger ,
DefaultMessagingSession ,
LogLevel ,
MessagingSessionConfiguration ,
} from 'amazon-chime-sdk-js' ;
const logger = new ConsoleLogger ( 'SDK' , LogLevel . INFO ) ;
// You will need AWS credentials configured before calling AWS or Amazon Chime APIs.
const chime = new ChimeSDKMessagingClient ( { region : 'us-east-1' } ) ;
const userArn = /* The userArn */ ;
const sessionId = /* The sessionId */ ;
const configuration = new MessagingSessionConfiguration ( userArn , sessionId , undefined , chime ) ;
const messagingSession = new DefaultMessagingSession ( configuration , logger ) ;メッセージング セッションに接続するときにプリフェッチ機能を有効にしたい場合は、以下のコードに従ってください。プリフェッチ機能は、WebSocket 接続時に CHANNEL_DETAILS イベントを送信します。これには、チャネル、チャネル メッセージ、チャネル メンバーシップなどに関する情報が含まれます。プリフェッチの並べ替え順序は、 prefetchSortByで調整でき、 unread (設定されていない場合はデフォルト値) またはlastMessageTimestampに設定できます。
configuration . prefetchOn = Prefetch . Connect ;
configuration . prefetchSortBy = PrefetchSortBy . Unread ; git fetch --tags https://github.com/aws/amazon-chime-sdk-js
npm run build
npm run test
初めてnpm run test実行した後、 npm run test:fastを使用してテスト スイートを高速化できます。
タグは、バージョン管理メタデータを正しく生成するために取得されます。
コード カバレッジの結果を表示するには、 npm run test実行した後、ブラウザでcoverage/index.htmlを開きます。
npm run test実行し、テストは実行されているがカバレッジ レポートが生成されない場合は、リソースのクリーンアップの問題が発生している可能性があります。 Mocha v4.0.0 以降では、テスト実行の完了時に Mocha プロセスが強制終了しないように実装が変更されました。
たとえば、単体テストにDefaultVideoTransformDeviceがある場合は、 await device.stop();を呼び出す必要があります。リソースをクリーンアップして、この問題が発生しないようにします。また、 done();の使用法を調べることもできます。 Mocha のドキュメントに記載されています。
JavaScript API リファレンス ドキュメントを生成するには、次のコマンドを実行します。
npm run build
npm run doc
次に、ブラウザでdocs/index.htmlを開きます。
このプロジェクトで潜在的なセキュリティ問題を発見した場合は、脆弱性レポート ページから AWS/Amazon セキュリティに通知するようお願いします。公開 GitHub 問題を作成しないでください。
注: セッションを開始する前に、マイク、スピーカー、カメラを選択する必要があります。
使用例 1.オーディオ入力、オーディオ出力、およびビデオ入力デバイスをリストします。ブラウザはマイクとカメラの許可を求めます。
forceUpdateパラメータを true に設定すると、キャッシュされたデバイス情報は破棄され、デバイス ラベル トリガーが呼び出された後に更新されます。場合によっては、ビルダーは、たとえば表示専用モードで会議に参加する場合など、権限ダイアログのトリガーを遅らせる必要があり、後でデバイス ラベルを表示するために権限プロンプトをトリガーできるようにする必要があります。 forceUpdate指定すると、これが可能になります。
const audioInputDevices = await meetingSession . audioVideo . listAudioInputDevices ( ) ;
const audioOutputDevices = await meetingSession . audioVideo . listAudioOutputDevices ( ) ;
const videoInputDevices = await meetingSession . audioVideo . listVideoInputDevices ( ) ;
// An array of MediaDeviceInfo objects
audioInputDevices . forEach ( mediaDeviceInfo => {
console . log ( `Device ID: ${ mediaDeviceInfo . deviceId } Microphone: ${ mediaDeviceInfo . label } ` ) ;
} ) ;使用例 2. MediaDeviceInfoオブジェクトのdeviceId渡して、オーディオ入力デバイスとオーディオ出力デバイスを選択します。最初にlistAudioInputDevicesとlistAudioOutputDevices呼び出す必要があることに注意してください。
const audioInputDeviceInfo = /* An array item from meetingSession.audioVideo.listAudioInputDevices */ ;
await meetingSession . audioVideo . startAudioInput ( audioInputDeviceInfo . deviceId ) ;
const audioOutputDeviceInfo = /* An array item from meetingSession.audioVideo.listAudioOutputDevices */ ;
await meetingSession . audioVideo . chooseAudioOutput ( audioOutputDeviceInfo . deviceId ) ;使用例 3. MediaDeviceInfoオブジェクトのdeviceId渡して、ビデオ入力デバイスを選択します。最初にlistVideoInputDevicesを呼び出す必要があることに注意してください。
出席者のカメラの隣に LED ライトがある場合は、カメラからキャプチャ中であることを示すために点灯します。ビデオの共有を開始するときは、おそらくビデオ入力デバイスを選択することになるでしょう。
const videoInputDeviceInfo = /* An array item from meetingSession.audioVideo.listVideoInputDevices */ ;
await meetingSession . audioVideo . startVideoInput ( videoInputDeviceInfo . deviceId ) ;
// Stop video input. If the previously chosen camera has an LED light on,
// it will turn off indicating the camera is no longer capturing.
await meetingSession . audioVideo . stopVideoInput ( ) ;使用例 4.デバイス変更オブザーバーを追加して、更新されたデバイス リストを受信します。たとえば、Bluetooth ヘッドセットをコンピュータとペアリングすると、ヘッドセットを含むデバイス リストを使用してaudioInputsChangedおよびaudioOutputsChangedが呼び出されます。
audioInputMuteStateChangedコールバックを使用すると、それをサポートするブラウザおよびオペレーティング システム上で、基礎となるハードウェアのミュート状態を追跡できます。
const observer = {
audioInputsChanged : freshAudioInputDeviceList => {
// An array of MediaDeviceInfo objects
freshAudioInputDeviceList . forEach ( mediaDeviceInfo => {
console . log ( `Device ID: ${ mediaDeviceInfo . deviceId } Microphone: ${ mediaDeviceInfo . label } ` ) ;
} ) ;
} ,
audioOutputsChanged : freshAudioOutputDeviceList => {
console . log ( 'Audio outputs updated: ' , freshAudioOutputDeviceList ) ;
} ,
videoInputsChanged : freshVideoInputDeviceList => {
console . log ( 'Video inputs updated: ' , freshVideoInputDeviceList ) ;
} ,
audioInputMuteStateChanged : ( device , muted ) => {
console . log ( 'Device' , device , muted ? 'is muted in hardware' : 'is not muted' ) ;
} ,
} ;
meetingSession . audioVideo . addDeviceChangeObserver ( observer ) ;使用例 5.セッションを開始します。オーディオを聞くには、デバイスとストリームを<audio>要素にバインドする必要があります。セッションが開始されたら、参加者と話したり、話を聞いたりすることができます。マイクとスピーカーを選択していること (「デバイス」セクションを参照) と、少なくとも 1 人の他の出席者がセッションに参加していることを確認してください。
const audioElement = /* HTMLAudioElement object e.g. document.getElementById('audio-element-id') */ ;
meetingSession . audioVideo . bindAudioElement ( audioElement ) ;
const observer = {
audioVideoDidStart : ( ) => {
console . log ( 'Started' ) ;
}
} ;
meetingSession . audioVideo . addObserver ( observer ) ;
meetingSession . audioVideo . start ( ) ;使用例 6.セッション ライフサイクル イベント (接続、開始、停止) を受信するオブザーバーを追加します。
注: オブザーバーを削除するには、
meetingSession.audioVideo.removeObserver(observer)を呼び出します。コンポーネントベースのアーキテクチャ (React、Vue、Angular など) では、コンポーネントがマウントされるときにオブザーバーを追加し、アンマウントされるときにオブザーバーを削除する必要がある場合があります。
const observer = {
audioVideoDidStart : ( ) => {
console . log ( 'Started' ) ;
} ,
audioVideoDidStop : sessionStatus => {
// See the "Stopping a session" section for details.
console . log ( 'Stopped with a session status code: ' , sessionStatus . statusCode ( ) ) ;
} ,
audioVideoDidStartConnecting : reconnecting => {
if ( reconnecting ) {
// e.g. the WiFi connection is dropped.
console . log ( 'Attempting to reconnect' ) ;
}
} ,
} ;
meetingSession . audioVideo . addObserver ( observer ) ;注: これまでに、デバイスとセッションのライフサイクル イベントを受信するオブザーバーを追加しました。次の使用例では、リアルタイム API メソッドを使用して、音量インジケーターを送受信し、ミュート状態を制御します。
使用例 7.オーディオ入力をミュートおよびミュート解除します。
// Mute
meetingSession . audioVideo . realtimeMuteLocalAudio ( ) ;
// Unmute
const unmuted = meetingSession . audioVideo . realtimeUnmuteLocalAudio ( ) ;
if ( unmuted ) {
console . log ( 'Other attendees can hear your audio' ) ;
} else {
// See the realtimeSetCanUnmuteLocalAudio use case below.
console . log ( 'You cannot unmute yourself' ) ;
}使用例 8.ローカルのマイクがミュートされているかどうかを確認するには、自分のミュート状態を追跡するのではなく、この方法を使用します。
const muted = meetingSession . audioVideo . realtimeIsLocalAudioMuted ( ) ;
if ( muted ) {
console . log ( 'You are muted' ) ;
} else {
console . log ( 'Other attendees can hear your audio' ) ;
}使用例 9.ミュート解除を無効にします。ユーザーが自分でミュートを解除できないようにしたい場合 (プレゼンテーション中など)、自分自身のミュート解除可能状態を追跡するのではなく、これらの方法を使用してください。
meetingSession . audioVideo . realtimeSetCanUnmuteLocalAudio ( false ) ;
// Optional: Force mute.
meetingSession . audioVideo . realtimeMuteLocalAudio ( ) ;
const unmuted = meetingSession . audioVideo . realtimeUnmuteLocalAudio ( ) ;
console . log ( ` ${ unmuted } is false. You cannot unmute yourself` ) ;使用例 10.特定の出席者の音量変更をサブスクライブします。これを使用して、リアルタイムの音量インジケーター UI を構築できます。
import { DefaultModality } from 'amazon-chime-sdk-js' ;
// This is your attendee ID. You can also subscribe to another attendee's ID.
// See the "Attendees" section for an example on how to retrieve other attendee IDs
// in a session.
const presentAttendeeId = meetingSession . configuration . credentials . attendeeId ;
meetingSession . audioVideo . realtimeSubscribeToVolumeIndicator (
presentAttendeeId ,
( attendeeId , volume , muted , signalStrength ) => {
const baseAttendeeId = new DefaultModality ( attendeeId ) . base ( ) ;
if ( baseAttendeeId !== attendeeId ) {
// See the "Screen and content share" section for details.
console . log ( `The volume of ${ baseAttendeeId } 's content changes` ) ;
}
// A null value for any field means that it has not changed.
console . log ( ` ${ attendeeId } 's volume data: ` , {
volume , // a fraction between 0 and 1
muted , // a boolean
signalStrength , // 0 (no signal), 0.5 (weak), 1 (strong)
} ) ;
}
) ;使用例 11.特定の出席者のミュートまたは信号強度の変更をサブスクライブします。これを使用して、ミュートのみまたは信号強度の変更のみを行う UI を構築できます。
// This is your attendee ID. You can also subscribe to another attendee's ID.
// See the "Attendees" section for an example on how to retrieve other attendee IDs
// in a session.
const presentAttendeeId = meetingSession . configuration . credentials . attendeeId ;
// To track mute changes
meetingSession . audioVideo . realtimeSubscribeToVolumeIndicator (
presentAttendeeId ,
( attendeeId , volume , muted , signalStrength ) => {
// A null value for volume, muted and signalStrength field means that it has not changed.
if ( muted === null ) {
// muted state has not changed, ignore volume and signalStrength changes
return ;
}
// mute state changed
console . log ( ` ${ attendeeId } 's mute state changed: ` , {
muted , // a boolean
} ) ;
}
) ;
// To track signal strength changes
meetingSession . audioVideo . realtimeSubscribeToVolumeIndicator (
presentAttendeeId ,
( attendeeId , volume , muted , signalStrength ) => {
// A null value for volume, muted and signalStrength field means that it has not changed.
if ( signalStrength === null ) {
// signalStrength has not changed, ignore volume and muted changes
return ;
}
// signal strength changed
console . log ( ` ${ attendeeId } 's signal strength changed: ` , {
signalStrength , // 0 (no signal), 0.5 (weak), 1 (strong)
} ) ;
}
) ;使用例 12.最も活発な発言者を検出します。たとえば、利用可能な場合は、アクティブな発言者のビデオ要素を拡大できます。
import { DefaultActiveSpeakerPolicy } from 'amazon-chime-sdk-js' ;
const activeSpeakerCallback = attendeeIds => {
if ( attendeeIds . length ) {
console . log ( ` ${ attendeeIds [ 0 ] } is the most active speaker` ) ;
}
} ;
meetingSession . audioVideo . subscribeToActiveSpeakerDetector (
new DefaultActiveSpeakerPolicy ( ) ,
activeSpeakerCallback
) ;注: Chime SDK の用語では、ビデオ タイルは「o」です。
