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 事件，其中包括有关频道、频道消息、频道会员资格等的信息。预取排序顺序可以通过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();在摩卡文档中。
要生成 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
