amazon chime sdk js
Release amazon-chime-sdk-3.25.0
Amazon Chime SDK 專案板
Amazon Chime SDK React 元件
Amazon Chime SDK 是一組即時通訊元件，開發人員可以使用它們快速向其 Web 或行動應用程式添加訊息傳遞、音訊、視訊和螢幕共享功能。
開發人員可以在 AWS 的全球通訊基礎設施上構建，在其應用程式中提供引人入勝的體驗。例如，他們可以將影片添加到健康應用程式中，以便患者可以就健康問題遠端諮詢醫生，或者創建客製化的音訊提示以與公共電話網路整合。
Amazon Chime SDK for JavaScript 透過連接到您在 AWS 帳戶中建立的會議會話資源來運作。該SDK 擁有您在Web 應用程式中建立自訂呼叫和協作體驗所需的一切，包括配置會議會話、列出和選擇音訊和視訊設備、啟動和停止螢幕共享以及螢幕共享檢視、在媒體事件（例如，發生音量變化，並控制音訊靜音和視訊圖塊綁定等會議功能。
如果您正在建立 React 應用程序，請考慮使用 Amazon Chime SDK React 元件庫，該程式庫為音訊和視訊會議應用程式中使用的常見 Web 介面提供用戶端狀態管理和可重複使用 UI 元件。 Amazon Chime 還提供 iOS 的 Amazon Chime SDK 和適用於 Android 的 Amazon Chime SDK，用於本機行動應用程式開發。
Amazon Chime SDK 專案板可擷取我們所有儲存庫中社群功能請求的狀態。本指南中捕捉了板上各列的描述。
除了以下內容之外，這裡還列出了有關 Amazon Chime SDK 的所有部落格文章。
以下開發人員指南涵蓋了技術受眾的特定主題。
以下開發人員指南更廣泛地介紹了 Amazon Chime SDK。
.js檔案中的腳本查看自述文件中提供的資源，並使用我們的用戶端文件來取得如何在 Chime SDK for JavaScript 上進行開發的指導。此外，請搜尋我們的問題資料庫和常見問題解答，看看您的問題是否已解決。如果沒有，請使用提供的模板向我們解決問題。
部落格文章使用 Amazon Chime SDK 會議事件進行監控和故障排除詳細介紹如何透過登入 Amazon CloudWatch 使用會議事件對應用程式進行故障排除。
如果您有更多問題或需要業務支持，可以聯絡 AWS 客戶支援。您可以在此處查看我們的支援計劃。
適用於 JavaScript 的 Amazon Chime SDK 使用 WebRTC，這是大多數現代瀏覽器支援的即時通訊 API。以下是 WebRTC 上的一些常規資源。
確保您擁有 Node.js 版本 18 或更高版本。推薦並支援節點 20。
若要將適用於 JavaScript 的 Amazon Chime 開發工具包新增至現有應用程式中，請直接從 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 開發工具包、AWS 命令列介面 (AWS CLI) 或 REST API 進行 API 呼叫。在本部分中，您將在伺服器應用程式（例如 Node.js）中使用適用於 JavaScript 的 AWS 開發工具包。有關更多信息，請參閱 Amazon Chime SDK API 參考。
️ 伺服器應用程式不需要適用於 JavaScript 的 Amazon Chime SDK。
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 參數的值應設定為距離建立會議的使用者最近的媒體區域之一。可以在 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 事件，其中包括unread頻道prefetchSortBy頻道訊息、頻道會員資格等的資訊。值）或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();在摩卡文檔中。
若要產生 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.新增裝置更改觀察器以接收更新的裝置清單。例如，當您將藍牙耳機與電腦配對時，將使用包含耳機的裝置清單呼叫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>元素。會議開始後，您可以與與會者交談並聆聽。確保您已選擇麥克風和揚聲器（請參閱“設備”部分），並且至少有其他與會者已加入會議。
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
