amazon chime sdk js
Release amazon-chime-sdk-3.25.0
Tableau de projet du SDK Amazon Chime
Composants React du SDK Amazon Chime
Le SDK Amazon Chime est un ensemble de composants de communication en temps réel que les développeurs peuvent utiliser pour ajouter rapidement des fonctionnalités de messagerie, audio, vidéo et de partage d'écran à leurs applications Web ou mobiles.
Les développeurs peuvent s'appuyer sur l'infrastructure de communication mondiale d'AWS pour offrir des expériences attrayantes dans leurs applications. Par exemple, ils peuvent ajouter une vidéo à une application de santé afin que les patients puissent consulter à distance des médecins sur des problèmes de santé, ou créer des invites audio personnalisées pour l'intégration au réseau téléphonique public.
Le SDK Amazon Chime pour JavaScript fonctionne en se connectant aux ressources de session de réunion que vous créez dans votre compte AWS. Le SDK contient tout ce dont vous avez besoin pour créer des expériences d'appel et de collaboration personnalisées dans votre application Web, y compris des méthodes pour configurer des sessions de réunion, répertorier et sélectionner des appareils audio et vidéo, démarrer et arrêter le partage d'écran et l'affichage du partage d'écran, recevoir des rappels lorsque des événements multimédias tels que des changements de volume se produisent et contrôlent les fonctionnalités de réunion telles que la sourdine audio et les liaisons de vignettes vidéo.
Si vous créez une application React, envisagez d'utiliser la bibliothèque de composants Amazon Chime SDK React qui fournit une gestion de l'état côté client et des composants d'interface utilisateur réutilisables pour les interfaces Web courantes utilisées dans les applications de conférence audio et vidéo. Amazon Chime propose également le SDK Amazon Chime pour iOS et le SDK Amazon Chime pour Android pour le développement d'applications mobiles natives.
Le tableau de projet Amazon Chime SDK capture l'état des demandes de fonctionnalités de la communauté dans tous nos référentiels. Les descriptions des colonnes du tableau sont capturées dans ce guide.
En plus de ce qui suit, voici une liste de tous les articles de blog sur le SDK Amazon Chime.
Les guides de développement suivants couvrent des sujets spécifiques destinés à un public technique.
Les guides du développeur suivants couvrent le SDK Amazon Chime de manière plus large.
.jsConsultez les ressources fournies dans le README et utilisez notre documentation client pour obtenir des conseils sur la façon de développer sur le SDK Chime pour JavaScript. De plus, recherchez dans notre base de données de problèmes et dans notre FAQ pour voir si votre problème est déjà résolu. Sinon, veuillez nous signaler un problème en utilisant les modèles fournis.
L'article de blog Surveillance et dépannage avec les événements de réunion du SDK Amazon Chime explique en détail comment utiliser les événements de réunion pour dépanner votre application en vous connectant à Amazon CloudWatch.
Si vous avez d'autres questions ou avez besoin d'assistance pour votre entreprise, vous pouvez contacter le support client AWS. Vous pouvez consulter nos plans de support ici.
Le SDK Amazon Chime pour JavaScript utilise WebRTC, l'API de communication en temps réel prise en charge dans la plupart des navigateurs modernes. Voici quelques ressources générales sur WebRTC.
Assurez-vous d'avoir Node.js version 18 ou supérieure. Le nœud 20 est recommandé et pris en charge.
Pour ajouter le SDK Amazon Chime pour JavaScript dans une application existante, installez le package directement depuis npm :
npm install amazon-chime-sdk-js --save
Notez que le SDK Amazon Chime pour JavaScript cible ES2015, qui est entièrement compatible avec tous les navigateurs pris en charge.
Créez une session de réunion dans votre application client.
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
) ; Vous pouvez utiliser un kit SDK AWS, l'interface de ligne de commande AWS (AWS CLI) ou l'API REST pour effectuer des appels d'API. Dans cette section, vous utiliserez le kit AWS SDK pour JavaScript dans votre application serveur, par exemple Node.js. Consultez la référence de l'API du SDK Amazon Chime pour plus d'informations.
️ L'application serveur ne nécessite pas le SDK Amazon Chime pour 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 ( ) ; Transférez désormais en toute sécurité les objets meetingResponse et attendeeResponse vers votre application client. Ces objets contiennent toutes les informations nécessaires pour qu'une application client utilisant le SDK Amazon Chime pour JavaScript puisse rejoindre la réunion.
La valeur du paramètre MediaRegion dans createMeeting() doit idéalement être définie sur celle des régions multimédias les plus proches de l'utilisateur créant une réunion. Une implémentation est disponible sous la rubrique « Choisir la région multimédia la plus proche » dans la documentation Régions multimédias du SDK Amazon Chime.
Créez une session de messagerie dans votre application client pour recevoir des messages du SDK Amazon Chime pour la messagerie.
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 ) ; Si vous souhaitez activer la fonction de prélecture lors de la connexion à une session de messagerie, vous pouvez suivre le code ci-dessous. La fonction de prélecture enverra l'événement CHANNEL_DETAILS lors de la connexion au websocket, qui comprend des informations sur le canal, les messages du canal, les adhésions au canal, etc. L'ordre de tri de prélecture peut être ajusté avec prefetchSortBy , en le définissant sur unread (valeur par défaut si non défini) ou 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
Après avoir exécuté npm run test pour la première fois, vous pouvez utiliser npm run test:fast pour accélérer la suite de tests.
Les balises sont récupérées afin de générer correctement les métadonnées de versionnage.
Pour afficher les résultats de la couverture du code, ouvrez coverage/index.html dans votre navigateur après avoir exécuté npm run test .
Si vous exécutez npm run test et que les tests sont en cours d'exécution mais que le rapport de couverture n'est pas généré, vous pourriez avoir un problème de nettoyage des ressources. Dans Mocha v4.0.0 ou version ultérieure, l'implémentation a été modifiée afin que les processus Mocha ne forcent pas la sortie une fois le test terminé.
Par exemple, si vous avez un DefaultVideoTransformDevice dans votre test unitaire, vous devez appeler await device.stop(); pour nettoyer les ressources et ne pas rencontrer ce problème. Vous pouvez également examiner l'utilisation de done(); dans la documentation Moka.
Pour générer la documentation de référence de l'API JavaScript, exécutez :
npm run build
npm run doc
Ensuite, ouvrez docs/index.html dans votre navigateur.
Si vous découvrez un problème de sécurité potentiel dans ce projet, nous vous demandons d'en informer AWS/Amazon Security via notre page de rapport de vulnérabilité. Veuillez ne pas créer de problème GitHub public.
Remarque : Avant de démarrer une session, vous devez choisir votre microphone, votre haut-parleur et votre caméra.
Cas d'utilisation 1. Répertoriez les périphériques d'entrée audio, de sortie audio et d'entrée vidéo. Le navigateur demandera les autorisations du microphone et de la caméra.
Avec le paramètre forceUpdate défini sur true, les informations sur le périphérique mises en cache sont supprimées et mises à jour après l'appel du déclencheur d'étiquette de périphérique. Dans certains cas, les constructeurs doivent retarder le déclenchement des boîtes de dialogue d'autorisation, par exemple lorsqu'ils rejoignent une réunion en mode visualisation seule, puis pouvoir déclencher ultérieurement une invite d'autorisation afin d'afficher les étiquettes des appareils ; spécifier forceUpdate permet que cela se produise.
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 } ` ) ;
} ) ; Cas d'utilisation 2. Choisissez les périphériques d'entrée et de sortie audio en transmettant le deviceId d'un objet MediaDeviceInfo . Notez que vous devez d’abord appeler listAudioInputDevices et 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 ) ; Cas d'utilisation 3. Choisissez un périphérique d'entrée vidéo en transmettant le deviceId d'un objet MediaDeviceInfo . Notez que vous devez d’abord appeler listVideoInputDevices .
S'il y a une lumière LED à côté de la caméra du participant, elle s'allumera pour indiquer qu'elle est en train de capturer à partir de la caméra. Vous souhaiterez probablement choisir un périphérique d'entrée vidéo lorsque vous commencerez à partager votre vidéo.
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 ( ) ; Cas d'utilisation 4. Ajoutez un observateur de changement d'appareil pour recevoir la liste des appareils mise à jour. Par exemple, lorsque vous associez des casques Bluetooth à votre ordinateur, audioInputsChanged et audioOutputsChanged sont appelés avec la liste des appareils comprenant les casques.
Vous pouvez utiliser le rappel audioInputMuteStateChanged pour suivre l'état de sourdine du matériel sous-jacent sur les navigateurs et les systèmes d'exploitation qui le prennent en charge.
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 ) ; Cas d'utilisation 5. Démarrez une session. Pour entendre l'audio, vous devez lier un appareil et diffuser à un élément <audio> . Une fois la session commencée, vous pouvez parler et écouter les participants. Assurez-vous d'avoir choisi votre microphone et votre haut-parleur (voir la section « Appareil ») et qu'au moins un autre participant a rejoint la session.
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 ( ) ;Cas d'utilisation 6. Ajoutez un observateur pour recevoir les événements du cycle de vie de la session : connexion, démarrage et arrêt.
Remarque : Vous pouvez supprimer un observateur en appelant
meetingSession.audioVideo.removeObserver(observer). Dans une architecture basée sur des composants (telle que React, Vue et Angular), vous devrez peut-être ajouter un observateur lorsqu'un composant est monté et le supprimer lorsqu'il est démonté.
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 ) ;Remarque : Jusqu'à présent, vous avez ajouté des observateurs pour recevoir les événements du cycle de vie des appareils et des sessions. Dans les cas d'utilisation suivants, vous utiliserez les méthodes API en temps réel pour envoyer et recevoir des indicateurs de volume et contrôler l'état de sourdine.
Cas d'utilisation 7. Couper et réactiver une entrée audio.
// 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' ) ;
}Cas d'utilisation 8. Pour vérifier si le microphone local est coupé, utilisez cette méthode plutôt que de suivre votre propre état de sourdine.
const muted = meetingSession . audioVideo . realtimeIsLocalAudioMuted ( ) ;
if ( muted ) {
console . log ( 'You are muted' ) ;
} else {
console . log ( 'Other attendees can hear your audio' ) ;
}Cas d'utilisation 9. Désactivez la activation du son. Si vous souhaitez empêcher les utilisateurs de réactiver le son (par exemple lors d'une présentation), utilisez ces méthodes plutôt que de suivre votre propre état de réactivation du son.
meetingSession . audioVideo . realtimeSetCanUnmuteLocalAudio ( false ) ;
// Optional: Force mute.
meetingSession . audioVideo . realtimeMuteLocalAudio ( ) ;
const unmuted = meetingSession . audioVideo . realtimeUnmuteLocalAudio ( ) ;
console . log ( ` ${ unmuted } is false. You cannot unmute yourself` ) ;Cas d'utilisation 10. Abonnez-vous aux changements de volume d'un participant spécifique. Vous pouvez l'utiliser pour créer une interface utilisateur d'indicateur de volume en temps réel.
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)
} ) ;
}
) ;Cas d'utilisation 11. Abonnez-vous aux changements de sourdine ou de force du signal d'un participant spécifique. Vous pouvez l'utiliser pour créer une interface utilisateur uniquement pour les changements de sourdine ou uniquement pour la force du signal.
// 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)
} ) ;
}
) ;Cas d'utilisation 12. Détecter l'orateur le plus actif. Par exemple, vous pouvez agrandir l'élément vidéo de l'intervenant actif s'il est disponible.
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
) ;Remarque : en termes du SDK Chime, une vignette vidéo est un o
