amazon chime sdk js
Release amazon-chime-sdk-3.25.0
Junta de proyecto del SDK de Amazon Chime
Componentes de reacción del SDK de Amazon Chime
El SDK de Amazon Chime es un conjunto de componentes de comunicaciones en tiempo real que los desarrolladores pueden utilizar para agregar rápidamente capacidades de mensajería, audio, video y uso compartido de pantalla a sus aplicaciones web o móviles.
Los desarrolladores pueden aprovechar la infraestructura de comunicaciones global de AWS para ofrecer experiencias atractivas en sus aplicaciones. Por ejemplo, pueden agregar video a una aplicación de salud para que los pacientes puedan consultar remotamente con los médicos sobre temas de salud, o crear mensajes de audio personalizados para la integración con la red telefónica pública.
El SDK de Amazon Chime para JavaScript funciona conectándose a los recursos de sesiones de reuniones que crea en su cuenta de AWS. El SDK tiene todo lo que necesita para crear experiencias personalizadas de llamadas y colaboración en su aplicación web, incluidos métodos para configurar sesiones de reuniones, enumerar y seleccionar dispositivos de audio y video, iniciar y detener la pantalla compartida y la visualización de pantalla compartida, recibir devoluciones de llamadas cuando eventos multimedia como se producen cambios de volumen y controla las funciones de la reunión, como el silencio del audio y la vinculación de mosaicos de vídeo.
Si está creando una aplicación React, considere utilizar la biblioteca de componentes React del SDK de Amazon Chime que proporciona administración de estado del lado del cliente y componentes de interfaz de usuario reutilizables para interfaces web comunes utilizadas en aplicaciones de conferencias de audio y video. Amazon Chime también ofrece Amazon Chime SDK para iOS y Amazon Chime SDK para Android para el desarrollo de aplicaciones móviles nativas.
El tablero de proyectos del SDK de Amazon Chime captura el estado de las solicitudes de funciones de la comunidad en todos nuestros repositorios. Las descripciones de las columnas del tablero se recogen en esta guía.
Además de lo siguiente, aquí hay una lista de todas las publicaciones de blog sobre el SDK de Amazon Chime.
Las siguientes guías para desarrolladores cubren temas específicos para una audiencia técnica.
Las siguientes guías para desarrolladores cubren el SDK de Amazon Chime de manera más amplia.
.jsRevise los recursos proporcionados en el archivo README y utilice la documentación de nuestro cliente como guía sobre cómo desarrollar Chime SDK para JavaScript. Además, busque en nuestra base de datos de problemas y en las preguntas frecuentes para ver si su problema ya está solucionado. De lo contrario, déjenos un problema utilizando las plantillas proporcionadas.
La publicación del blog Monitoreo y solución de problemas con eventos de reuniones del SDK de Amazon Chime detalla cómo utilizar eventos de reuniones para solucionar problemas de su aplicación iniciando sesión en Amazon CloudWatch.
Si tiene más preguntas o necesita soporte para su negocio, puede comunicarse con el servicio de atención al cliente de AWS. Puede revisar nuestros planes de soporte aquí.
El SDK de Amazon Chime para JavaScript utiliza WebRTC, la API de comunicación en tiempo real compatible con la mayoría de los navegadores modernos. Aquí hay algunos recursos generales sobre WebRTC.
Asegúrate de tener Node.js versión 18 o superior. Se recomienda y admite el nodo 20.
Para agregar el SDK de Amazon Chime para JavaScript a una aplicación existente, instale el paquete directamente desde npm:
npm install amazon-chime-sdk-js --save
Tenga en cuenta que el SDK de Amazon Chime para JavaScript está destinado a ES2015, que es totalmente compatible con todos los navegadores compatibles.
Cree una sesión de reunión en su aplicación cliente.
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
) ; Puede utilizar un SDK de AWS, la interfaz de línea de comandos de AWS (AWS CLI) o la API REST para realizar llamadas a la API. En esta sección, utilizará AWS SDK para JavaScript en su aplicación de servidor, por ejemplo, Node.js. Consulte Referencia de la API del SDK de Amazon Chime para obtener más información.
️ La aplicación del servidor no requiere el SDK de Amazon Chime para 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 ( ) ; Ahora transfiera de forma segura los objetos meetingResponse y attendeeResponse a su aplicación cliente. Estos objetos contienen toda la información necesaria para que una aplicación cliente que utilice el SDK de Amazon Chime para JavaScript pueda unirse a la reunión.
Lo ideal es que el valor del parámetro MediaRegion en createMeeting() se establezca en la región de medios más cercana al usuario que crea una reunión. Puede encontrar una implementación en el tema "Elección de la región de medios más cercana" en la documentación de Regiones de medios del SDK de Amazon Chime.
Cree una sesión de mensajería en su aplicación cliente para recibir mensajes de Amazon Chime SDK para mensajería.
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 desea habilitar la función de captación previa al conectarse a una sesión de mensajería, puede seguir el código a continuación. La función de captación previa enviará el evento CHANNEL_DETAILS tras la conexión websocket, que incluye información sobre el canal, mensajes del canal, membresías del canal, etc. El orden de clasificación de la captación previa se puede ajustar con prefetchSortBy , configurándolo como unread (valor predeterminado si no se establece) o 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
Después de ejecutar npm run test por primera vez, puede usar npm run test:fast para acelerar el conjunto de pruebas.
Las etiquetas se recuperan para generar correctamente los metadatos de control de versiones.
Para ver los resultados de la cobertura del código, abra coverage/index.html en su navegador después de ejecutar npm run test .
Si ejecuta npm run test y las pruebas se están ejecutando pero el informe de cobertura no se genera, es posible que tenga un problema de limpieza de recursos. En Mocha v4.0.0 o posterior, se cambió la implementación para que los procesos de Mocha no fuercen la salida cuando se complete la ejecución de prueba.
Por ejemplo, si tiene un DefaultVideoTransformDevice en su prueba unitaria, debe llamar await device.stop(); para limpiar los recursos y no encontrarse con este problema. También puedes investigar el uso de done(); en la documentación de Mocha.
Para generar documentación de referencia de la API de JavaScript, ejecute:
npm run build
npm run doc
Luego abra docs/index.html en su navegador.
Si descubre un posible problema de seguridad en este proyecto, le solicitamos que notifique a AWS/Amazon Security a través de nuestra página de informes de vulnerabilidad. No cree un problema público de GitHub.
Nota: antes de iniciar una sesión, debes elegir tu micrófono, altavoz y cámara.
Caso de uso 1. Enumere los dispositivos de entrada de audio, salida de audio y entrada de video. El navegador solicitará permisos de micrófono y cámara.
Con el parámetro forceUpdate establecido en verdadero, la información del dispositivo almacenada en caché se descarta y se actualiza después de llamar al activador de etiqueta del dispositivo. En algunos casos, los constructores necesitan retrasar la activación de los cuadros de diálogo de permiso, por ejemplo, al unirse a una reunión en modo de solo visualización, y luego poder activar una solicitud de permiso para mostrar las etiquetas del dispositivo; especificar forceUpdate permite que esto ocurra.
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 } ` ) ;
} ) ; Caso de uso 2. Elija dispositivos de entrada y salida de audio pasando el deviceId de un objeto MediaDeviceInfo . Tenga en cuenta que primero debe llamar listAudioInputDevices y 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 ) ; Caso de uso 3. Elija un dispositivo de entrada de video pasando el deviceId de un objeto MediaDeviceInfo . Tenga en cuenta que primero debe llamar listVideoInputDevices .
Si hay una luz LED al lado de la cámara del asistente, se encenderá para indicar que ahora está capturando desde la cámara. Probablemente quieras elegir un dispositivo de entrada de vídeo cuando empieces a compartir tu vídeo.
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 ( ) ; Caso de uso 4. Agregue un observador de cambio de dispositivo para recibir la lista de dispositivos actualizada. Por ejemplo, cuando empareja unos auriculares Bluetooth con su computadora, se llama audioInputsChanged y audioOutputsChanged con la lista de dispositivos, incluidos los auriculares.
Puede utilizar la devolución de llamada audioInputMuteStateChanged para rastrear el estado de silencio del hardware subyacente en los navegadores y sistemas operativos que lo admiten.
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 ) ; Caso de uso 5. Iniciar una sesión. Para escuchar audio, debe vincular un dispositivo y transmitirlo a un elemento <audio> . Una vez iniciada la sesión podrás hablar y escuchar a los asistentes. Asegúrese de haber elegido su micrófono y altavoz (consulte la sección "Dispositivo") y que al menos otro asistente se haya unido a la sesión.
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 ( ) ;Caso de uso 6. Agregue un observador para recibir eventos del ciclo de vida de la sesión: conexión, inicio y detención.
Nota: Puede eliminar un observador llamando
meetingSession.audioVideo.removeObserver(observer). En una arquitectura basada en componentes (como React, Vue y Angular), es posible que deba agregar un observador cuando se monta un componente y eliminarlo cuando se desmonta.
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 ) ;Nota: Hasta ahora, ha agregado observadores para recibir eventos del ciclo de vida de sesiones y dispositivos. En los siguientes casos de uso, utilizará los métodos API en tiempo real para enviar y recibir indicadores de volumen y controlar el estado de silencio.
Caso de uso 7. Silenciar y reactivar una entrada de 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' ) ;
}Caso de uso 8. Para comprobar si el micrófono local está silenciado, utilice este método en lugar de realizar un seguimiento de su propio estado de silencio.
const muted = meetingSession . audioVideo . realtimeIsLocalAudioMuted ( ) ;
if ( muted ) {
console . log ( 'You are muted' ) ;
} else {
console . log ( 'Other attendees can hear your audio' ) ;
}Caso de uso 9. Desactivar activar el silencio. Si desea evitar que los usuarios activen el silencio (por ejemplo, durante una presentación), utilice estos métodos en lugar de realizar un seguimiento de su propio estado de activación del silencio.
meetingSession . audioVideo . realtimeSetCanUnmuteLocalAudio ( false ) ;
// Optional: Force mute.
meetingSession . audioVideo . realtimeMuteLocalAudio ( ) ;
const unmuted = meetingSession . audioVideo . realtimeUnmuteLocalAudio ( ) ;
console . log ( ` ${ unmuted } is false. You cannot unmute yourself` ) ;Caso de uso 10. Suscríbete a los cambios de volumen de un asistente específico. Puede utilizar esto para crear una interfaz de usuario de indicador de volumen en tiempo real.
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)
} ) ;
}
) ;Caso de uso 11. Suscríbase para silenciar o cambiar la intensidad de la señal de un asistente específico. Puede usar esto para crear una interfaz de usuario que solo silencie o solo cambie la intensidad de la señal.
// 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)
} ) ;
}
) ;Caso de uso 12. Detectar el hablante más activo. Por ejemplo, puede ampliar el elemento de vídeo del orador activo si 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
) ;Nota: En términos de Chime SDK, un mosaico de video es una
