amazon chime sdk js
Release amazon-chime-sdk-3.25.0
Quadro do projeto SDK do Amazon Chime
Componentes do React do SDK do Amazon Chime
O SDK do Amazon Chime é um conjunto de componentes de comunicação em tempo real que os desenvolvedores podem usar para adicionar rapidamente recursos de mensagens, áudio, vídeo e compartilhamento de tela a aplicativos móveis ou da Web.
Os desenvolvedores podem aproveitar a infraestrutura de comunicações globais da AWS para oferecer experiências envolventes em seus aplicativos. Por exemplo, podem adicionar vídeo a uma aplicação de saúde para que os pacientes possam consultar médicos remotamente sobre questões de saúde ou criar avisos de áudio personalizados para integração com a rede telefónica pública.
O SDK do Amazon Chime para JavaScript funciona conectando-se a recursos de sessão de reunião criados em sua conta da AWS. O SDK tem tudo o que você precisa para criar experiências personalizadas de chamada e colaboração em seu aplicativo Web, incluindo métodos para configurar sessões de reunião, listar e selecionar dispositivos de áudio e vídeo, iniciar e parar o compartilhamento de tela e a visualização do compartilhamento de tela, receber retornos de chamada quando eventos de mídia, como ocorrem alterações de volume e controlam recursos de reunião, como silenciamento de áudio e vinculações de blocos de vídeo.
Se você estiver criando um aplicativo React, considere usar a biblioteca de componentes React do SDK do Amazon Chime, que fornece gerenciamento de estado do lado do cliente e componentes de UI reutilizáveis para interfaces da Web comuns usadas em aplicativos de conferência de áudio e vídeo. O Amazon Chime também oferece Amazon Chime SDK para iOS e Amazon Chime SDK para Android para desenvolvimento de aplicativos móveis nativos.
O Amazon Chime SDK Project Board captura o status das solicitações de recursos da comunidade em todos os nossos repositórios. As descrições das colunas no quadro são capturadas neste guia.
Além do que está abaixo, aqui está uma lista de todas as postagens de blog sobre o SDK do Amazon Chime.
Os guias do desenvolvedor a seguir cobrem tópicos específicos para um público técnico.
Os guias do desenvolvedor a seguir abordam o SDK do Amazon Chime de forma mais ampla.
.jsRevise os recursos fornecidos no README e use a documentação do cliente para obter orientação sobre como desenvolver no Chime SDK para JavaScript. Além disso, pesquise nosso banco de dados de problemas e perguntas frequentes para ver se o seu problema já foi resolvido. Caso contrário, envie-nos um problema usando os modelos fornecidos.
A postagem do blog Monitoramento e solução de problemas com eventos de reunião do SDK do Amazon Chime detalha como usar eventos de reunião para solucionar problemas do seu aplicativo registrando-se no Amazon CloudWatch.
Se você tiver mais dúvidas ou precisar de suporte para sua empresa, entre em contato com o suporte ao cliente da AWS. Você pode revisar nossos planos de suporte aqui.
O SDK do Amazon Chime para JavaScript usa WebRTC, a API de comunicação em tempo real compatível com a maioria dos navegadores modernos. Aqui estão alguns recursos gerais sobre WebRTC.
Certifique-se de ter o Node.js versão 18 ou superior. O nó 20 é recomendado e compatível.
Para adicionar o SDK do Amazon Chime para JavaScript a um aplicativo existente, instale o pacote diretamente do npm:
npm install amazon-chime-sdk-js --save
Observe que o SDK do Amazon Chime para JavaScript é direcionado ao ES2015, que é totalmente compatível com todos os navegadores compatíveis.
Crie uma sessão de reunião em seu aplicativo 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
) ; Você pode usar um AWS SDK, a AWS Command Line Interface (AWS CLI) ou a API REST para fazer chamadas de API. Nesta seção, você usará o AWS SDK para JavaScript em seu aplicativo de servidor, por exemplo, Node.js. Consulte Referência da API do SDK do Amazon Chime para obter mais informações.
️ O aplicativo de servidor não requer o SDK do 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 ( ) ; Agora transfira com segurança os objetos meetingResponse e attendeeResponse para seu aplicativo cliente. Esses objetos contêm todas as informações necessárias para que um aplicativo cliente que usa o SDK do Amazon Chime para JavaScript participe da reunião.
O valor do parâmetro MediaRegion em createMeeting() deve idealmente ser definido como aquela das regiões de mídia mais próxima do usuário que está criando uma reunião. Uma implementação pode ser encontrada no tópico “Escolher a região de mídia mais próxima” na documentação das regiões de mídia do SDK do Amazon Chime.
Crie uma sessão de mensagens no aplicativo cliente para receber mensagens do 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 ) ; Se desejar ativar o recurso de pré-busca ao conectar-se a uma sessão de mensagens, você pode seguir o código abaixo. O recurso de pré-busca enviará o evento CHANNEL_DETAILS na conexão do websocket, que inclui informações sobre o canal, mensagens do canal, associações de canais, etc. A ordem de classificação da pré-busca pode ser ajustada com prefetchSortBy , configurando-o como unread (valor padrão se não definido) 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
Depois de executar npm run test pela primeira vez, você pode usar npm run test:fast para acelerar o conjunto de testes.
As tags são buscadas para gerar corretamente os metadados de versionamento.
Para visualizar os resultados da cobertura de código, abra coverage/index.html em seu navegador após executar npm run test .
Se você executar npm run test e os testes estiverem em execução, mas o relatório de cobertura não estiver sendo gerado, poderá haver um problema de limpeza de recursos. No Mocha v4.0.0 ou mais recente, a implementação foi alterada para que os processos do Mocha não forcem a saída quando a execução do teste for concluída.
Por exemplo, se você tiver um DefaultVideoTransformDevice em seu teste de unidade, deverá chamar await device.stop(); para limpar os recursos e não se deparar com esse problema. Você também pode analisar o uso de done(); na documentação do Mocha.
Para gerar a documentação de referência da API JavaScript, execute:
npm run build
npm run doc
Em seguida, abra docs/index.html no seu navegador.
Se você descobrir um possível problema de segurança neste projeto, pedimos que notifique a AWS/Amazon Security por meio de nossa página de relatórios de vulnerabilidades. Por favor, não crie um problema público no GitHub.
Observação: antes de iniciar uma sessão, você precisa escolher seu microfone, alto-falante e câmera.
Caso de uso 1. Liste dispositivos de entrada de áudio, saída de áudio e entrada de vídeo. O navegador solicitará permissões de microfone e câmera.
Com o parâmetro forceUpdate definido como true, as informações do dispositivo armazenadas em cache são descartadas e atualizadas depois que o acionador de rótulo do dispositivo é chamado. Em alguns casos, os construtores precisam atrasar o acionamento de caixas de diálogo de permissão, por exemplo, ao ingressar em uma reunião no modo somente visualização e, posteriormente, poder acionar um prompt de permissão para mostrar os rótulos dos dispositivos; especificar forceUpdate permite que isso ocorra.
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. Escolha dispositivos de entrada e saída de áudio passando o deviceId de um objeto MediaDeviceInfo . Observe que você precisa chamar listAudioInputDevices e listAudioOutputDevices primeiro.
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. Escolha um dispositivo de entrada de vídeo passando o deviceId de um objeto MediaDeviceInfo . Observe que você precisa chamar listVideoInputDevices primeiro.
Se houver uma luz LED próxima à câmera do participante, ela acenderá indicando que agora está capturando da câmera. Você provavelmente desejará escolher um dispositivo de entrada de vídeo ao começar a compartilhar seu 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. Adicione um observador de alteração de dispositivo para receber a lista de dispositivos atualizada. Por exemplo, quando você emparelha fones de ouvido Bluetooth com seu computador, audioInputsChanged e audioOutputsChanged são chamados com a lista de dispositivos, incluindo fones de ouvido.
Você pode usar o retorno de chamada audioInputMuteStateChanged para rastrear o estado mudo do hardware subjacente em navegadores e sistemas operacionais que oferecem suporte a isso.
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. Inicie uma sessão. Para ouvir áudio, você precisa vincular um dispositivo e transmitir a um elemento <audio> . Depois que a sessão for iniciada, você poderá falar e ouvir os participantes. Certifique-se de ter escolhido seu microfone e alto-falante (consulte a seção "Dispositivo") e de que pelo menos um outro participante tenha ingressado na sessão.
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. Adicione um observador para receber eventos do ciclo de vida da sessão: conexão, início e parada.
Nota: Você pode remover um observador chamando
meetingSession.audioVideo.removeObserver(observer). Em uma arquitetura baseada em componentes (como React, Vue e Angular), pode ser necessário adicionar um observador quando um componente for montado e removê-lo quando for desmontado.
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 ) ;Observação: até agora, você adicionou observadores para receber eventos de ciclo de vida de dispositivos e sessões. Nos casos de uso a seguir, você usará os métodos de API em tempo real para enviar e receber indicadores de volume e controlar o estado mudo.
Caso de uso 7. Ative e desative o som de uma entrada de áudio.
// 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 verificar se o microfone local está mudo, use este método em vez de monitorar seu próprio estado mudo.
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. Desative o som. Se você quiser evitar que os usuários ativem o som (por exemplo, durante uma apresentação), use estes métodos em vez de acompanhar seu próprio estado de ativação do som.
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. Assine as alterações de volume de um participante específico. Você pode usar isso para construir uma IU de indicador de volume em tempo 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. Inscreva-se para receber alterações no modo mudo ou na intensidade do sinal de um participante específico. Você pode usar isso para criar uma interface de usuário apenas para silenciar ou apenas alterar a intensidade do sinal.
// 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. Detecte o locutor mais ativo. Por exemplo, você pode ampliar o elemento de vídeo do locutor ativo, se disponível.
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
) ;Observação: nos termos do Chime SDK, um bloco de vídeo é um o
