Twilio Voice JS SDK: Twilio.Device

O objeto Twilio.Device está disponível quando o twilio.js estiver incluído na sua página. Ele representa um software device, o client (cliente) que fornece conexões à Twilio.

• Referência à API
  • Twilio.Device – O Twilio.Device é o principal ponto de entrada para fazer e receber chamadas usando o twilio.js.
  • Twilio.Device.audio – O Twilio.Device.audio permite configurar o roteamento de áudio e o comportamento de reprodução de som do seu Twilio.Device.
• Métodos descontinuados

Referência de método

Twilio.Device

A seguir está uma lista de métodos disponíveis no Twilio.Device:

constructor([token], [params])

A partir da versão 1.5.0, a classe Twilio.Device pode ser construída diretamente em vez de ser usada como um singleton por meio do Twilio.Device global. Usando este método, várias instâncias de Device podem operar simultaneamente na mesma página. Em caso de passagem de um token, oDevice.setup() será executado em construção com token e options passados. Caso contrário, o novo Device aguardará a chamada do Device.setup(token, options) antes de iniciar uma conexão de sinalização.

const device = new Twilio.Device();
device.setup(token, options);

// ou (comportamento singleton descontinuado)...

Twilio.Device.setup(token, options);

.setup( token, [params] )

Inicialize o Twilio.Device com um Access Token (Token de acesso (consulte Access Tokens (Tokens de acesso) da Twilio). O token fornecido ativa e fornece uma identidade ao dispositivo, além de conceder privilégios para fazer e receber chamadas de entrada e/ou outbound e associá‐lo a um aplicativo Twilio específico. Você deve ligar antes de qualquer outra coisa. Se o token permitir conexões de entrada do client (cliente), o dispositivo começará a escutar novas conexões quando você chamar o .setup().

Observação de melhores práticas

Os navegadores estão reprimindo o áudio de fundo injustificado. Como resultado, os navegadores estão indo em direção a exigir um gesto do usuário antes de permitir que o áudio seja reproduzido em uma página. A Twilio recomenda chamar o Device.setup() em resposta a um gesto do usuário, como um clique. Uma maneira popular e intuitiva de implementar isso é adicionar um botão "ready" que inicia o Device e mostra o discador quando clicado.

O argumento params do .setup() usa um objeto JavaScript contendo definições de configuração. As configurações disponíveis estão listadas abaixo:

Por exemplo:

Twilio.Device.setup(token); // use os parâmetros padrão

Ou usando params:

// habilite o registro de log de depuração e use os valores padrão para todos os outros parâmetros 
Twilio.Device.setup(token, { debug: true }); 

Ou usando sons personalizados:

Twilio.Device.setup(token, {
  sounds: {
    incoming: 'http://mysite.com/incoming.mp3',
    outgoing: 'http://mysite.com/outgoing.mp3',
    dtmf8: 'http://mysite.com/funny_noise.mp3'
  }
}

Ou especifique um Edge location (local de borda) ao qual se conectar:

// edge (borda) como uma matriz
Twilio.Device.setup(token, { edge: 'ashburn' });

// edge (borda) com funcionalidade de fallback automático
Twilio.Device.setup(token, { edge: ['ashburn', 'sydney' ] });

// edge (borda) com funcionalidade de fallback automático para interconnect privado
Twilio.Device.setup(token, { edge: ['ashburn', 'san-jose-ix' ] });

.connect( [params [, audioConstraints]] )

Tenta uma nova conexão com o aplicativo da Twilio que você associou ao Access Token (Token de acesso) do Device quando chamou o .setup() (consulte o Access Tokens [Tokens de acesso] para obter mais informações).

O argumento opcional params é um objeto JavaScript que será passado para o seu aplicativo como parâmetros POST/GET. Observe que o comprimento total de todos os parâmetros passados não deve exceder 800 bytes. Consulte Como compartilhar informações entre seus aplicativos para obter mais informações.

Por exemplo, o seguinte código passará os parâmetros agent=Smith e location=Matrixao aplicativo Twilio associado ao Access Token (Token de acesso) deste dispositivo.

var connection = Twilio.Device.connect({
  agent: "Smith",
  location: "Matrix"
});

Você também pode especificar um objeto audioConstraints para alterar o comportamento do fluxo de mídia local durante esta chamada. Você pode usar isso para selecionar um microfone específico ou desativar recursos como controle de ganho automático. Cada navegador da Internet implementa um conjunto diferente de restrições 'MediaTrackConstraints' que pode ser utilizado como 'audioConstraints'. Por isso, consulte a implementação do seu navegador de 'getUserMedia' para obter mais informações.

var audioConstraints = {
  optional: [{ sourceId: 'XXX' }]
};

var connection = Twilio.Device.connect(null, audioConstraints);

O método .connect() retorna um objeto Twilio.Connection. Você pode encerrar a conexão chamando o método .disconnect().

Exemplo de VoiceUrl no TwiML

Ao chamar o comando .connect(), o client (cliente) tenta uma nova conexão com o aplicativo Twilio usado no AccessToken (Token de acesso) do Twilio.Device. Este aplicativo pode fazer o que você quiser: fazer uma chamada telefônica para um número de telefone ou um endereço de um Twilio Client, iniciar uma chamada em conferência, interagir com uma URA, etc.

Por exemplo, se o VoiceUrl do aplicativo retorna com o seguinte TwiML:

<Response>
  <Dial callerId="+1888XXXXXXX">
    415-867-5309
  </Dial>
</Response>

então seu dispositivo fará uma chamada para 415-867-5309 sempre que você chamar .connect().

Todos os TwiML estão disponíveis para seus aplicativos client (cliente).

Você pode usar o params passado para o aplicativo no .connect() para gerar dinamicamente o TwiML correto para seu app. Por exemplo, você pode fazer o seguinte no código JavaScript:

var number = '5558675309';
var connection = Twilio.Device.connect({
  phone: number
});

E no aplicativo da Web que gera seu TwiML, recuperar o parâmetro phone da solicitação HTTP e inseri‐lo em seu TwiML da seguinte forma:

<Response>
  <Dial callerId="+1888XXXXXXX">
    5558675309
  </Dial>
</Response>

.activeConnection()

Retorna o [objeto de conexão] ativo(/docs/client/connection). Os objetos de conexão podem ser usados para executar operações na conexão, como ativar e desativar o som, enviar dígitos DTMF, etc.

.destroy()

Destrói o dispositivo. Ele encerra conexões ativas e pendentes e limpa todos os ouvintes de eventos conectados ao dispositivo após acionar o manipulador de eventos off‐line. O dispositivo não poderá fazer ou receber novas conexões até que você ligue o Device.setup() novamente.

.disconnectAll()

A conexão ativa é encerrada. Isso aciona o manipulador de eventos de desconexão. Isso não impede novas conexões de entrada.

.status()

Retorna o status do dispositivo. O status será uma das seguintes strings:

Métodos estáticos

.runPreflight(token, options)

Retorna um objeto PreflightTest que representa uma chamada de teste à Twilio, que fornece informações para ajudar a resolução de problemas relacionados a chamadas. Por exemplo:

import { Device, PreflightTest } from 'twilio-client';

const preflightTest = Device.runPreflight(token, options);

preflightTest.on(PreflightTest.Events.Completed, (report) => {
  console.log(report);
});

preflightTest.on(PreflightTest.Events.Failed, (error) => {
  console.log(error);
});

O parâmetro tokené passado diretamente ao constructor do dispositivo e é utilizado para se conectar a um app TwiML que você associou ao seu token. Para obter melhores resultados, o aplicativo TwiML deve ser capaz de gravar áudio de um microfone e reproduzi-lo no navegador. Consulte Apps do TwiML para o Preflight Test para obter mais detalhes.

O parâmetro options é um objeto de JavaScript que contém definições de configuração. As configurações disponíveis estão listadas abaixo:

Eventos

Observe que todos os manipuladores de eventos aqui definidos serão removidos ao chamar o Device.destroy().

.on('cancel', handler(connection))

Isto é acionado quando uma conexão de entrada é cancelada pelo autor da chamada antes de ser aceita pelo dispositivo do Twilio Client.

A função de manipulador recebe um objeto Twilio.Connection como argumento. Já que este objeto Connection representa uma conexão inativa, você provavelmente usará o evento para atualizar a interface do usuário do aplicativo e, em seguida, eliminar o Connection e aguardar a próxima chamada.

.on('connect', handler(connection))

É acionado quando uma conexão é aberta, quer seja iniciada usando .connect() através de uma conexão de entrada aceita.

A função de manipulador recebe um objeto Twilio.Connection como argumento.

.on('disconnect', handler(connection))

Acionado sempre que um Connection é fechado. A função de manipulador recebe o objeto Twilio.Connection` que foi fechado recentemente como um argumento.

.on('error', handler(error))

Emitido quando ocorre algum erro de dispositivo. Podem ser erros na solicitação, no token, erros de conexão ou outros erros de aplicativo. Consulte a Referência de códigos de erro do Twilio Client para obter mais informações. Usar o manipulador de erros é uma ótima maneira de depurar o aplicativo e ajudar a detectar erros no código.

A função de manipulador recebe um objeto error como argumento. O objeto de erro pode incluir as seguintes propriedades:

Twilio.Device.on('error', function(error) {
  console.log(error.message);
});

.on('incoming', handler(connection))

Isto é acionado sempre que uma conexão de entrada de uma chamada de REST outbound ou uma <Dial> do TwiML foir feita a este dispositivo.

A função de manipulador recebe um objeto Twilio.Connection como argumento. Esta conexão fica no estado pending até que você chame o .accept().

Twilio.Device.on('incoming', function(connection) {
  connection.accept();
  // faça coisas incríveis de interface do usuário aqui
  // $('#call-status').text("você está em uma chamada!");
});

.on('offline', function(device))

É acionado quando uma conexão com a Twilio cai ou quando o token do dispositivo está inválido/expirado. Em qualquer um desses cenários, o dispositivo não consegue receber conexões de entrada nem fazer conexões de saída. Se o token expirar durante uma conexão ativa, o evento offline será disparado, mas a conexão não será encerrada. Nesta situação, você terá que ligar para Twilio.Device.setup() com um token válido antes de tentar ou receber a próxima conexão.

A função de manipulador recebe o objeto Twilio.Device como seu único argumento.

.on('ready', function(device))

É inicialmente acionado quando todas as operações em .setup() estiverem concluídas e o dispositivo estiver pronto e on‐line. Ele será acionado novamente se o dispositivo ficar off‐line e voltar a ficar on‐line (ou seja, se a conexão cair e retornar).

A função de manipulador recebe o objeto Twilio.Device como seu único argumento.

Twilio.Device.on('ready', function(device) {
  // O dispositivo está pronto
  console.log("Twilio.Device está pronto para conexões");
});

Referência de propriedade

Campos estáticos

.isSupported

O Device.isSupported é um valor booleano que indica se o WebRTC é ou não compatível com seu navegador. Se definido como false, é um indicador de que oDevice.setup` não deve ser chamado ou então lançará uma exceção não compatível.

.packageName

O Device.packageName retorna o nome do pacote npm. Isso pode ser usado para obter a instância do agente usada pelo SDK. Consulte o [Agente do SDK] (#sdk-logger) para obter mais detalhes.

Exemplo:

import { getLogger } from 'loglevel';
const logger = getLogger(Device.packageName);

.version

A Device.version retorna a versão atual do SDK.

Fallback de edge (borda)

Por padrão, o SDK reconecta automaticamente a conexão WebSocket ao mesmo edge location (local de borda) quando ele não pode ser alcançado ou quando o SDK encontra um erro de rede que resulta em uma desconexão do WebSocket. Mas se o parâmetro Twilio.Device.Options.edge for fornecido como uma matriz de nomes de edge (borda), o SDK ativará a funcionalidade de fallback de edge (borda) automático. O diagrama abaixo ilustra a lógica que é executada para realizar o fallback.

Durante a inicialização, o SDK usará o primeiro nome de edge (borda) na matriz do Twilio.Device.Options.edge. Se o SDK encontrar um erro que resulte em uma desconexão do WebSocket com código de erro 1006 ou 1015, o SDK tentará se reconectar ao próximo edge (borda) na matriz usando um temporizador de retirada exponencial com um valor inicial de 1+aleatório(5) e um máximo de 20 segundos. Esse atraso máximo pode ser configurado por meio do parâmetro Twilio.Device.Options.backoffMaxMs.

Se o SDK encontrar um erro enquanto já estiver conectado a um servidor de edge (borda), ele tentará se reconectar ao mesmo edge (borda) uma vez antes de tentar se conectar ao próximo edge (borda).

A tabela a seguir fornece cenários comuns para quando um fallback pode ocorrer:

É importante observar que 'inalcançável' nesses cenários significa que o SDK falhou em estabelecer uma conexão WebSocket com o ponto de extremidade do edge (borda), o que resultou no código de erro 1006 ou 1015. O código de erro 1015 é um evento de fechamento do WebSocket que é gerado quando a conexão falha ao executar um handshake TLS. Isso acontece se o certificado do servidor for inválido ou não puder ser verificado. Enquanto o código de erro 1006 é gerado quando a conexão foi interrompida inesperadamente e não há nenhum quadro de fechamento recebido do servidor. A seguir estão problemas comuns que causam o erro 1006:

• O nome do domínio não pode ser resolvido pelo DNS
• A rede não pode alcançar o endpoint devido, por exemplo, a um firewall configurado incorretamente
• O client (client) fica off‐line devido, por exemplo, ao dispositivo local perder a conetividade de rede
• Em um cenário improvável e muito raro, os servidores de Edge (borda) e em espera não estão ativos

Agente do SDK

Antes da versão 1.10.0, o registro de log do Voice Client JS só podia ser configurado durante o Device.setup usando os sinalizadores debug e warnings. A partir da versão 1.10.0, o Voice Client SP expõe um agente baseado em logLevel que permite a configuração de registro de log em tempo de execução, que inclui definir o nível de log como “trace”, “debug”, “info”, “warn” e “error”. O logLevel é uma biblioteca de agentes versátil que inclui filtragem e registro de log baseado em nível e fornece uma API de plug‐in para habilitar funcionalidades como o envio de mensagens de log para um servidor de log.

Por exemplo, para ativar o registro de log:

import { getLogger } from 'loglevel';

const logger = getLogger(Device.packageName);
// Defina o nível de log nos carregamentos e atualizações de página subsequentes
logger.setLevel('DEBUG');

Twilio.Device.audio

O objeto Device.audio permite controlar a forma como o Twilio Client interage com os recursos do alto‐falante e do microfone. O Device.audio é um EventEmitter e, como tal, os seus eventos podem ser cadastrados através do Device.audio.on(eventName, handler).

Suporte ao navegador

OBSERVAÇÃO: muitos recursos audio dependem do navegador.

Atualmente, o Chrome 49+ é o único navegador que é totalmente compatível com o Twilio.Device.audio.

A seleção de saída de áudio requer suporte para setSinkId. Na data desta publicação, esse método só tem suporte no Chrome 49 ou versões superiores e no Microsoft Edge. À medida que o Firefox adicionar suporte a essas APIs, o twilio.js será atualizado para oferecer suporte. Embora o Edge ofereça suporte a setSinkId, ele ainda não é totalmente suportado nesta API.

A seleção da entrada de áudio requer suporte para AudioContext. Esse recurso é compatível com os navegadores modernos mais recentes (Chrome, Firefox, Edge); entretanto, o twilio.js não concluiu a implementação no Firefox e no Edge. O suporte estará disponível em breve.

Se esses recursos forem usados em um navegador que não os suporta, o método get retornará um Set vazio, enquanto os métodos set e test retornarão uma Promessa rejeitada.*

Métodos

.audio.setAudioConstraints(audioConstraints)

Defina as MediaTrackConstraints a serem aplicadas em cada chamada getUserMedia para o novo dispositivo de entrada de áudio. Qualquer deviceId especificado aqui será ignorado. Em vez disso, os IDs de dispositivo devem ser especificados usando .audio.setInputDevice(). A Promessa retornada resolve quando a mídia é readquirida com êxito ou imediatamente se nenhum dispositivo de entrada for definido.

Exemplo

device.audio.setAudioConstraints({ echoCancellation: true });
await device.audio.setInputDevice('default');
// Agora temos uma faixa de áudio de entrada ao vivo, aberta com echoCancellation:true
device.audio.setAudioConstraints({
  autoGainControl: false,
  echoCancellation: false,
  noiseSuppression: false,
}).then(() => {
  // Aplicamos com sucesso as novas restrições e devemos ouvir a diferença automaticamente.
  // As chamadas futuras para setInputDevice também usarão essas restrições até serem apagadas.
}, err => {
  // Algo deu errado; provavelmente err é um OverconstrainedError.  Vamos voltar.
  await device.audio.unsetAudioConstraints();
  // Agora devemos ter uma faixa de áudio de entrada em funcionamento novamente
});

.audio.setInputDevice(id)

Define o dispositivo de entrada atual por deviceId. Uma vez definido, o dispositivo de entrada será usado na chamada atual, se houver, e usado por padrão para quaisquer chamadas subsequentes. Além disso, sempre que um inputDevice for definido, o evento Device.audio#inputVolume será disparado em cada quadro de animação. Retorna uma Promessa que é resolvida se o dispositivo de entrada foi definido com êxito.

Observação: isso não é compatível com o Firefox (tão recente quanto a versão 51) devido à falta de suporte para vários dispositivos de entrada.

Exemplo

Twilio.Device.audio.setInputDevice('default').then(function() {
  console.info('Success!');
});

.audio.unsetAudioConstraints()

Remove as definições de MediaTrackConstraints a serem aplicadas em cada chamada getUserMedia para o novo dispositivo de entrada de áudio. A Promessa retornada resolve quando a mídia é readquirida com êxito ou imediatamente se nenhum dispositivo de entrada for definido.

.audio.unsetInputDevice(id)

Desconfigura o dispositivo de entrada ativo. Isso interrompe a sondagem do Device.audio#inputVolume e interrompe o fluxo de entrada.

Exemplo

Twilio.Device.audio.unsetInputDevice().then(function() {
  console.info('Success!');
});

Propriedades

.audio.audioConstraints

O MediaTrackConstraints do áudio de entrada definido atualmente por setAudioConstraints(). Inicia como nulo.

.audio.availableOutputDevices

Um Mapa contendo o objeto MediaDeviceInfo de todos os dispositivos de saída disponíveis (dispositivos de hardware capazes de enviar áudio), indexados por deviceId.

Observação: devido a restrições de segurança impostas pelos navegadores, os MediaDeviceInfo disponíveis em availableOutputDevices podem conter rótulos gerados automaticamente (por exemplo “Dispositivo de saída de áudio desconhecido 1”), ou uma lista incompleta/vazia de dispositivos até que o usuário conceda acesso ao aplicativo para esses recursos em resposta a uma chamada para a API do [getUserMedia()] (https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) do navegador. Em um esforço para reduzir a impressão digital de dispositivos, todos os principais navegadores estão ficando mais rígidos a esse respeito. É altamente recomendável que seu aplicativo chame o getUserMedia() antes de renderizar sua interface do usuário de seleção de dispositivo de entrada/saída para obter uma experiência do usuário mais suave.

Também observe: o Firefox (tão recente quanto a versão 51) não lista nenhum dispositivo audiooutput e o Edge (tão recente quanto a versão 38) não rotula os dispositivos audiooutput mesmo depois de o usuário conceder permissão.

Após o usuário aceitar o prompt getUserMedia(), o evento AudioHelper#deviceChange será disparado para indicar que a interface do usuário do aplicativo deve ser atualizada.

Example

Twilio.Device.audio.availableOutputDevices.forEach(function(device, id) {
  console.info('Available device:', id, '(labeled', device.label, ')');
});

.audio.availableInputDevices

Um [Mapa] (https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) contendo o objeto MediaDeviceInfo de todos os dispositivos de entrada disponíveis (dispositivos de hardware capazes de fornecer um fluxo de áudio de entrada), indexados por deviceId.

Observação: Devido a restrições de segurança impostas pelos navegadores, os MediaDeviceInfo disponíveis em availableInDevices podem conter rótulos gerados automaticamente (por exemplo “Dispositivo de entrada de áudio desconhecido 1”), ou uma lista incompleta/vazia de dispositivos até que o usuário conceda acesso ao aplicativo para esses recursos em resposta a uma chamada para a API do [getUserMedia()] (https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/getUserMedia) do navegador. Em um esforço para reduzir a impressão digital de dispositivos, todos os principais navegadores estão ficando mais rígidos a esse respeito. É altamente recomendável que seu aplicativo chame o getUserMedia() antes de renderizar sua interface do usuário de seleção de dispositivo de entrada/saída para obter uma experiência do usuário mais suave.

Após o usuário aceitar o prompt getUserMedia(), o evento AudioHelper#deviceChange será disparado para indicar que a interface do usuário do aplicativo deve ser atualizada.

.audio.inputDevice

Um MediaDeviceInfo que representa o dispositivo de entrada selecionado por .audio.setInputDevice(), ou null.

Twilio.Device.audio.speakerDevices

O speakerDevices é um AudioOutputCollection que controla quais dispositivos de saída são usados para reproduzir sons de alto‐falante padrão: o toque que você ouve ao iniciar uma chamada, o som de desconexão, tons DTMF que o usuário pode pressionar e o áudio recebido do participante remoto. A alteração desse conjunto de dispositivos alternará os dispositivos usados para esses sons. Se você alterá‐los durante uma chamada ativa, o áudio do participante remoto será imediatamente reproduzido através do novo conjunto de saídas.

Observação: isso não é compatível com o Firefox (tão recente quanto a versão 51) ou com o Edge (tão recente quanto a versão 38) devido à falta de suporte para HTMLAudioElement.setSinkId().

Referência à API Quick

// Retorna um Set<MediaDeviceInfo> dos atuais speakerDevices
Twilio.Device.audio.speakerDevices.get(); 
// Define o dispositivo ativo para o padrão
Twilio.Device.audio.speakerDevices.set('default');
// Define os dispositivos ativos para o padrão e ABC123
Twilio.Device.audio.speakerDevices.set(['default', 'ABC123']); 

Twilio.Device.audio.ringtoneDevices

OringtoneDevices é um AudioOutputCollection que controla quais dispositivos de saída são usados para reproduzir o som de toque ao receber uma chamada. A alteração desse conjunto de dispositivos alternará os dispositivos usados para o som de chamada recebida.

Observação: isso não é compatível com o Firefox (tão recente quanto a versão 51) ou com o Edge (tão recente quanto a versão 38) devido à falta de suporte para HTMLAudioElement.setSinkId().

Referência à API Quick

Twilio.Device.audio.ringtoneDevices.get(); // Retorna um Set<MediaDeviceInfo>
Twilio.Device.audio.ringtoneDevices.set('default'); // Define o dispositivo ativo
Twilio.Device.audio.ringtoneDevices.set(['default', 'ABC123']); // Define os dispositivos ativos
Twilio.Device.audio.ringtoneDevices.test(); // Testar com o som de 'saída'
Twilio.Device.audio.ringtoneDevices.test('cowbell.mp3'); // Testar com som personalizado

Twilio.Device.audio.speakerDevices.test() e Twilio.Device.audio.ringtoneDevices.test()

Use o método test() nas coleções speakderDevices ou ringtoneDevices para reproduzir um som de teste. Essa é uma ótima maneira de permitir que o usuário avalie se o dispositivo está funcionando conforme o esperado, fornecendo feedback audível sobre a configuração do dispositivo.

// Teste se os dispositivos foram configurados corretamente reproduzindo um som de ‘saída’...
Twilio.Device.audio.speakerDevices.test(); 
// ...ou teste a reprodução usando um som personalizado
Twilio.Device.audio.speakerDevices.test('cowbell.mp3'); 

event: Twilio.Device.audio#deviceChange

.audio.on('deviceChange', handler(lostActiveDevices))

Registre um manipulador que será acionado sempre que: um novo dispositivo de áudio for encontrado, um dispositivo de áudio existente for perdido ou o rótulo de um dispositivo existente for alterado. Isso normalmente acontece quando o usuário conecta ou desconecta um dispositivo de áudio, como um fone de ouvido ou um microfone. Isso também será acionado depois que o cliente tiver permitido o acesso à mídia do usuário por meio do getUserMedia pela primeira vez, à medida que os rótulos forem preenchidos. Se quiser permitir que os usuários escolham um dispositivo de áudio específico na interface do usuário do aplicativo, anexe um ouvinte a este evento.

Observe que ele não detecta um cliente conetando fones de ouvido ou outros alto‐falantes através da entrada para fones de ouvido, pois a entrada para fones de ouvido só redireciona o áudio do dispositivo de áudio interno.

O parâmetro , lostActiveDevices, é uma matriz de objetos MediaDeviceInfo que representa todos os dispositivos que estavam ativos no momento no .speakerDevices ou no .ringtoneDevices no momento em que foram perdidos, se houver. Uma matriz não vazia é um indicador de que a experiência do usuário provavelmente foi afetada por este evento.

event: Twilio.Device.audio#inputVolume

.audio.on('inputVolume', handler(volume))

Registra um manipulador que será acionado a cada quadro de animação com o volume atual do dispositivo de entrada selecionado, se houver um definido. O manipulador será chamado até 60 vezes por segundo e será diminuído gradualmente de forma dinâmica em dispositivos mais lentos para preservar o desempenho. O manipulador recebe volume como uma percentagem do volume máximo representado por um número de ponto flutuante entre 0.0 e 1.0, inclusivo. Esse valor representa uma faixa de valores de decibéis relativos de -100dB a -30dB.

Observação: isso nunca ocorrerá no Firefox (tão recente quanto a versão 51), pois não há uma maneira de suporte para definir o dispositivo de entrada.

Twilio.AudioOutputCollection

Tanto speakerDevices quanto ringtoneDevices são instâncias de AudioOutputCollection. Um AudioOutputCollection representa dispositivos de áudio ativos e pode ser atualizado para redirecionar os sons de alto‐falante e de toque para diferentes dispositivos em tempo real.

audioOutputCollection.get()

Obtenha um Set contendo objetos MediaDeviceInfo representando os dispositivos ativos na coleção.

audioOutputCollection.set( deviceId | deviceIds )

Substitui os dispositivos ativos na coleção passando um ou mais IDs de dispositivo. Retorna um Promise, que é cumprido se o(s) dispositivo(s) foi(ram) configurado(s) com sucesso e rejeitado(s) se:

• A seleção de saída não é compatível com o navegador ou
• Um deviceId especificado não foi encontrado ou
• Nenhum deviceId foi especificado

audioOutputCollection.test( soundUrl )

Teste os dispositivos ativos tocando um som através deles. Opcionalmente, um URL pode ser passado para reproduzir um som de teste personalizado. Retorna um Promise, que é cumprido se os dispositivos foram configurados com sucesso e rejeitados se:

• A seleção de saída não é suportada pelo navegador ou
• Não há dispositivos ativos ou
• O client (cliente) detecta falha na reprodução em um ou mais dispositivos

Exemplo de uso

var speakerDeviceSelect = document.getElementById('speaker-devices');

// Quando um dispositivo for encontrado ou perdido, atualize um elemento de seleção múltipla com o
// novo conjunto de dispositivos disponíveis.
Twilio.Device.audio.on('deviceChange', function updateAvailableDevices() {
  speakerDeviceSelect.innerHtml = '';

  Twilio.Device.audio.availableOutputDevices.forEach(function(device, id) {
    var deviceOption = document.createElement('option');
    deviceOption.label = device.label;
    deviceOption.setAttribute('data-id', id);

    // Se o dispositivo estiver presente em Device.audio.speakerDevices, então está
    // ativo no momento e deve ser selecionado no elemento de seleção múltipla.
    var speakerDevices = Twilio.Device.audio.speakerDevices.get();
    speakerDevices.forEach(function(spkDev) {
        if (spkDev.deviceId === id) {
          deviceOption.setAttribute('selected', 'selected');
        }
    });

    speakerDeviceSelect.appendChild(deviceOption);
  });
});

// Quando um dispositivo for selecionado ou não selecionado, atualize o Device.audio.speakerDevices
// com os dispositivos que o usuário selecionou para mudar imediatamente de onde o áudio
// está sendo reproduzido.
speakerDeviceSelect.addEventListener('change', function() {
  var selectedDeviceIds = [].slice.call(speakerDevices.childNodes)
    .filter(function(node) { return node.selected; })
    .map(function(node) { return node.getAttribute('data-id'); });

  Twilio.Device.audio.speakerDevices.set(selectedDeviceIds);
});

Rótilos de som

Esses getters/setters foram movidos da API Device.sounds preterida. Se um som estiver desativado, ele não será reproduzido por nenhum dispositivo de saída.

.audio.incoming( [bool] ) 

Habilita ou desabilita o som de entrada do evento.

.audio.incoming() 

Retorna um booleano que indica se o som de entrada está habilitado ou desabilitado.

.audio.outgoing( [bool] ) 

Habilita ou desabilitar o som de saída do evento.

.audio.outgoing() 

Retorna um booleano que indica se o som de saída está habilitado ou desabilitado.

.audio.disconnect( [bool] ) 

Habilita ou desabilita o som de desconexão do evento.

.audio.disconnect() 

Retorna um booleano que indica se o som de desconexão está habilitado ou desabilitado.

Métodos descontinuados

O twilio.js 1.3 e anteriores expôs um objeto sounds no dispositivo. A partir do twilio.js 1.4 e superior, o sounds e todos os métodos definidos no sounds foram movidos para o audio. O sounds e as versões antigas desses métodos permanecem disponíveis no twilio.js 1.4, mas chamar os métodos em sounds gerará um aviso de descontinuidade. Incentivamos que você passe a usar o audio.

Além disso, o Twilio Client está avançando para a interface padrão do EventEmitter, o que significa que os eventos devem ser gerenciados com o .on(eventName, handler) e .removeListener(eventName, handler), substituindo os nossos manipuladores legado (como .accept(handler), .error(handler), etc...). Os seguintes métodos foram desaprovados:

Device.cancel(handler)
Device.connect(handler)
Device.disconnect(handler)
Device.error(handler)
Device.incoming(handler)
Device.offline(handler)
Device.ready(handler)

Esses foram substituídos pelos seguintes eventos:

Device.on('cancel', handler)
Device.on('connect', handler)
Device.on('disconnect', handler)
Device.on('error', handler)
Device.on('incoming', handler)
Device.on('offline', handler)
Device.on('ready', handler)