amazon chime sdk js
Release amazon-chime-sdk-3.25.0
Совет проекта Amazon Chime SDK
Компоненты React Amazon Chime SDK
Amazon Chime SDK — это набор компонентов связи в реальном времени, которые разработчики могут использовать для быстрого добавления возможностей обмена сообщениями, аудио, видео и совместного использования экрана в свои веб-приложения или мобильные приложения.
Разработчики могут использовать глобальную коммуникационную инфраструктуру AWS, чтобы предоставлять привлекательные возможности в своих приложениях. Например, они могут добавить видео в приложение для здравоохранения, чтобы пациенты могли удаленно консультироваться с врачами по вопросам здоровья, или создать индивидуальные звуковые подсказки для интеграции с телефонной сетью общего пользования.
Amazon Chime SDK для JavaScript работает путем подключения к ресурсам сеанса собрания, которые вы создаете в своем аккаунте AWS. В SDK есть все, что вам нужно для создания пользовательских возможностей звонков и совместной работы в вашем веб-приложении, включая методы настройки сеансов собраний, составления списка и выбора аудио- и видеоустройств, запуска и остановки совместного использования экрана и просмотра совместного использования экрана, получения обратных вызовов при мультимедийных событиях, таких как происходят изменения громкости и управляются такими функциями собрания, как отключение звука и привязка фрагментов видео.
Если вы создаете приложение React, рассмотрите возможность использования библиотеки компонентов React Amazon Chime SDK, которая предоставляет управление состоянием на стороне клиента и повторно используемые компоненты пользовательского интерфейса для распространенных веб-интерфейсов, используемых в приложениях аудио- и видеоконференций. Amazon Chime также предлагает Amazon Chime SDK для iOS и Amazon Chime SDK для Android для разработки собственных мобильных приложений.
Доска проекта Amazon Chime SDK фиксирует статус запросов сообщества на функции во всех наших репозиториях. Описания столбцов на доске приведены в этом руководстве.
Помимо приведенного ниже, здесь приведен список всех сообщений в блогах об Amazon Chime SDK.
Следующие руководства для разработчиков охватывают конкретные темы для технической аудитории.
Следующие руководства для разработчиков описывают Amazon Chime SDK более широко.
.jsПросмотрите ресурсы, приведенные в README, и воспользуйтесь нашей клиентской документацией для получения инструкций по разработке Chime SDK для JavaScript. Кроме того, выполните поиск по нашей базе данных проблем и разделу часто задаваемых вопросов, чтобы узнать, решена ли ваша проблема уже. Если нет, пожалуйста, сообщите нам о проблеме, используя предоставленные шаблоны.
В записи блога «Мониторинг и устранение неполадок с помощью Amazon Chime SDK Meeting Events» подробно описывается, как использовать события собраний для устранения неполадок в приложении путем входа в Amazon CloudWatch.
Если у вас есть дополнительные вопросы или вам требуется поддержка для вашего бизнеса, вы можете обратиться в службу поддержки клиентов AWS. Вы можете ознакомиться с нашими планами поддержки здесь.
Amazon Chime SDK для JavaScript использует WebRTC, API связи в реальном времени, поддерживаемый в большинстве современных браузеров. Вот некоторые общие ресурсы по WebRTC.
Убедитесь, что у вас Node.js версии 18 или выше. Узел 20 рекомендуется и поддерживается.
Чтобы добавить Amazon Chime SDK для JavaScript в существующее приложение, установите пакет непосредственно из npm:
npm install amazon-chime-sdk-js --save
Обратите внимание, что Amazon Chime SDK для 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
) ; Для выполнения вызовов API можно использовать AWS SDK, интерфейс командной строки AWS (AWS CLI) или REST API. В этом разделе вы будете использовать AWS SDK для JavaScript в своем серверном приложении, например Node.js. Дополнительную информацию см. в справочнике по API Amazon Chime SDK.
️ Серверному приложению не требуется Amazon Chime SDK для 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 для JavaScript, для присоединения к собранию.
Значение параметра MediaRegion в createMeeting() в идеале должно быть установлено в тот из медиа-регионов, который находится ближе всего к пользователю, создающему собрание. Реализацию можно найти в разделе «Выбор ближайшего медиа-региона» документации по медиа-регионам 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 ) ; Если вы хотите включить функцию предварительной выборки при подключении к сеансу обмена сообщениями, вы можете следовать приведенному ниже коду. Функция предварительной выборки будет отправлять событие 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 , чтобы ускорить выполнение набора тестов.
Теги извлекаются для правильного создания метаданных управления версиями.
Чтобы просмотреть результаты покрытия кода, откройте coverage/index.html в своем браузере после запуска npm run test .
Если вы запускаете npm run test и тесты выполняются, но отчет о покрытии не создается, возможно, у вас возникла проблема с очисткой ресурсов. В Mocha v4.0.0 или новее реализация была изменена таким образом, чтобы процессы Mocha не завершались принудительно после завершения тестового запуска.
Например, если в вашем модульном тесте есть DefaultVideoTransformDevice , вам необходимо вызвать await device.stop(); чтобы очистить ресурсы и не столкнуться с этой проблемой. Вы также можете изучить использование done(); в документации Mocha.
Чтобы создать справочную документацию по API JavaScript, выполните:
npm run build
npm run doc
Затем откройте docs/index.html в своем браузере.
Если вы обнаружите потенциальную проблему безопасности в этом проекте, мы просим вас уведомить AWS/Amazon Security через нашу страницу отчетов об уязвимостях. Пожалуйста, не создавайте публичную задачу на 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. Выберите устройства ввода и вывода звука, передав deviceId из объекта MediaDeviceInfo . Обратите внимание, что сначала вам нужно вызвать 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. Выберите устройство видеовхода, передав deviceId объекта MediaDeviceInfo . Обратите внимание, что сначала вам нужно вызвать listVideoInputDevices .
Если рядом с камерой участника есть светодиодный индикатор, он загорится, указывая на то, что сейчас ведется съемка с камеры. Вероятно, вы захотите выбрать устройство видеовхода, когда начнете делиться своим видео.
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> . После начала сеанса вы можете разговаривать и слушать участников. Убедитесь, что вы выбрали микрофон и динамик (см. раздел «Устройство») и к сеансу присоединился хотя бы еще один участник.
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. Подписаться на изменения громкости конкретного участника. Вы можете использовать это для создания пользовательского интерфейса индикатора объема в реальном времени.
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. Подпишитесь на отключение звука или изменение уровня сигнала конкретного посетителя. Вы можете использовать это для создания пользовательского интерфейса только для отключения звука или только для изменения уровня сигнала.
// 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 видеоячейка — это
