Abrir uma conexão

Você chama o método /v1/synthesize por meio do protocolo WebSocket Secure (WSS) para estabelecer uma conexão com o serviço. O método está disponível no terminal a seguir:

wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}/v1/synthesize

em que {location} indica onde seu aplicativo está hospedado:

• us-south para Dallas
• us-east para Washington, D.C.
• eu-de para Frankfurt
• au-syd para Sydney
• jp-tok para Tóquio
• eu-gb para Londres
• kr-seo para Seul

E {instance_id} é o identificador único da instância de serviço.

Os exemplos na documentação abreviam wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id} para {ws_url}. Portanto, todos os exemplos do WebSocket chamam o método como {ws_url}/v1/synthesize.

Um cliente WebSocket chama o método /v1/synthesize com os seguintes parâmetros de consulta para estabelecer uma conexão autenticada com o serviço:

access_token (sequência necessária)

Passe um token de acesso válido para autenticar com o serviço. Deve-se usar o token de acesso antes de sua expiração.

• IBM Cloud Passe um token de acesso Identity and Access Management (IAM) para se autenticar no serviço. Você transmite um token de acesso do IAM em vez de uma chave de API com a chamada. Para obter mais informações, consulte Autenticando para IBM Cloud.
• IBM Cloud Pak for DataIBM Software Hub Passe um token de acesso como você faria com o cabeçalho Authorization de uma solicitação HTTP. Para obter mais informações, consulte Autenticação em IBM Cloud Pak for Data.

voice (sequência opcional)

Especifica a voz na qual o texto deve ser falado no áudio. Use o método /v1/voicespara obter a lista atual de vozes suportadas. Omita o parâmetro para usar a voz padrão. Para obter mais informações, consulte Idiomas e vozes e Usar a voz padrão.

customization_id (sequência opcional)

Especifica o Identificador Exclusivo Global (GUID) para um modelo customizado que deve ser utilizado para a síntese. Um modelo customizado especificado deve corresponder à linguagem da voz que é usada para a síntese. Se você incluir um ID de customização, deverá fazer a solicitação com credenciais para a instância do serviço que tem o modelo customizado. Omita o parâmetro para usar a voz especificada sem a customização. Para obter mais informações, consulte Entendendo a customização.

rate_percentage (opcional integer)

Especifica a taxa de fala global para toda a solicitação de síntese. A taxa de fala é a velocidade na qual o serviço fala o texto que ele sintetiza em fala. Uma taxa mais alta faz com que o texto seja falado mais rapidamente; uma taxa mais baixa faz com que o texto seja falado mais lentamente. O parâmetro altera a taxa padrão por voz para uma solicitação inteira. Para obter mais informações, consulte Modificação da taxa de fala.

pitch_percentage (opcional integer)

Especifica o tom de voz global para toda a solicitação de síntese. O tom da fala representa o tom da fala que o serviço sintetiza. Representa o quão alto ou baixo o tom da voz é percebido pelo ouvinte. Um tom mais alto resulta em uma fala que é pronunciada em um tom mais alto; um tom mais baixo resulta em uma fala que é pronunciada em um tom mais baixo. O parâmetro altera o tom padrão por voz para uma solicitação inteira. Para obter mais informações, consulte Modificação do tom de voz.

spell_out_mode (sequência opcional)

Para vozes alemãs, especifica como os caracteres individuais de uma string devem ser soletrados. Por padrão, o serviço soletra caracteres individuais na mesma velocidade em que sintetiza o texto para um idioma. Você pode usar o parâmetro para instruir o serviço a soletrar caracteres individuais mais lentamente, em grupos de um singles), dois pairs) ou três triples). Para obter mais informações, consulte Especificação de como as cadeias de caracteres são soletradas.

x-watson-metadata (sequência opcional)

Associa um ID do cliente aos dados transmitidos pela conexão. O parâmetro aceita o argumento customer_id={id}, em que id é uma sequência aleatória ou genérica que deve ser associada aos dados. Deve-se codificar a URL do argumento para o parâmetro, por exemplo, customer_id%3dmy_customer_ID. Por padrão, nenhum ID do cliente está associado aos dados. Para obter mais informações, consulte Segurança de informações.

x-watson-learning-opt-out (booleano opcional)

IBM Cloud Indica se o serviço registra solicitações e resultados que são enviados pela conexão. Para evitar que a IBM acesse seus dados para melhorias gerais de serviço, especifique true para o parâmetro. A desativação faz com que a IBM não grave em disco dados do usuário (texto ou áudio) para sua solicitação. Você também pode optar por não participar no nível da conta. Para obter mais informações, consulte Criação de log de solicitação.

O fragmento do código JavaScript a seguir abre uma conexão com o serviço. A chamada para o método /v1/synthesize transmite os parâmetros de consulta voice e access_token, o primeiro deles para direcionar o serviço para o uso da voz Allison em inglês americano. Uma vez estabelecida a conexão, os listeners do evento (onOpen(), onClose() e assim por diante) são definidos para responder a eventos do serviço.

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/synthesize'
  + '?access_token=' + access_token
  + '&voice=en-US_AllisonV3Voice';
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };
websocket.onclose = function(evt) { onClose(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };

Enviar o texto de entrada

Para sintetizar texto, o cliente passa uma mensagem de texto JSON simples para o serviço com os seguintes parâmetros:

text (sequência necessária)

Fornece o texto que deve ser sintetizado. O cliente pode transmitir um texto sem formatação ou anotado com o Speech Synthesis Markup Language (SSML). O cliente pode transmitir um máximo de 5 KB de texto de entrada com a solicitação. O limite inclui qualquer SSML especificado. Para obter mais informações, consulte Especificando o texto de entrada e as seções seguintes. (entrada SSML também pode incluir o elemento <mark>. Para obter mais informações, consulte Especificando uma marca SSML.)

accept (sequência necessária)

Especifica o formato solicitado (tipo MIME) do áudio. Use */* para solicitar o formato de áudio padrão, audio/ogg;codecs=opus. Para obter mais informações, consulte Usando formatos de áudio.

O formato de áudio Ogg não é compatível com o navegador Safari. Se você estiver usando o serviço Text to Speech com o navegador Safari, deverá especificar um formato diferente no qual deseja que o serviço retorne o áudio.

timings (sequência opcional[ ])

Especifica que o serviço deve retornar informações de sincronização de palavra para todas as sequências do texto de entrada. O serviço retorna o horário de início e de término de cada token da entrada. Especifique words como o elemento lone da matriz para solicitar sincronizações de palavra. Especifique uma matriz vazia ou omita o parâmetro para não receber sincronizações de palavra. Para obter mais informações, consulte Geração de temporizações de palavras. Não suportado para texto de entrada em japonês.

O fragmento a seguir do código JavaScript transmite uma mensagem "Hello world" simples como o texto de entrada e solicita o formato padrão para o áudio. As chamadas estão incluídas na função onOpen() que é definida para o cliente para garantir que elas sejam enviadas somente após a conexão ser estabelecida.

function onOpen(evt) {
  var message = {
    text: 'Hello world',
    accept: '*/*'
  };
  websocket.send(JSON.stringify(message));
}

O serviço responde essa mensagem enviando uma mensagem de texto que confirma o formato da resposta de áudio. A resposta a seguir confirma o formato de áudio padrão.

{
  'binary_streams': [
    {
      content_type: 'audio/ogg;codecs=opus'
    }
  ]
}

Receber uma resposta

Depois de confirmar o formato de áudio, o serviço envia o áudio sintetizado como um fluxo binário de dados no formato indicado. Para formatos de áudio que incluem um cabeçalho (por exemplo, audio/wav e audio/ogg), o serviço retorna o cabeçalho antes de enviar os dados de áudio. O cabeçalho pode abranger diversas respostas binárias. Para todos os formatos de áudio, o cliente precisa anexar todas as respostas binárias do serviço para montar a resposta de áudio completa.

Além de enviar uma mensagem de texto que confirme o formato de áudio solicitado, o serviço também pode enviar mensagens de texto com avisos ou erros. O serviço também enviará uma ou mais mensagens de texto que incluirão informações de sincronização se

• O texto de entrada inclui um ou mais elementos SSML <mark>.
• Você especificar o parâmetro timings com a solicitação.

O cliente poderá manipular as mensagens de texto por meio da resposta, da exibição ou da captura delas para o uso pelo aplicativo (por exemplo, se elas contiverem locais de marca).

Quando finaliza a sintetização do texto de entrada e o envio de todas as mensagens binárias e de texto, o serviço fecha automaticamente a conexão do WebSocket. A seguinte função onMessage() simples anexa texto e mensagens binárias que são recebidas do serviço para as variáveis apropriadas com base em seu tipo. Quando a função onClose() for executada, o fluxo de áudio inteiro terá sido recebido e o serviço não enviará mais mensagens binárias ou de texto.

var messages;
var audioStream;

function onMessage(evt) {
  if (typeof evt.data === string) {
    messages += evt.data;
  } else {
    console.log('Received ' + evt.data.size() + ' binary bytes');
    audioStream += evt.data;
  }
}

function onClose(evt) {
  // The service's response is complete.
}

Códigos de retorno do WebSocket

O serviço pode enviar os códigos de retorno a seguir para o cliente por meio da conexão do WebSocket:

• 1000 indica encerramento normal da conexão, o que significa que o propósito para o qual a conexão foi estabelecida foi atendido.
• 1002 indica que o serviço está fechando a conexão devido a um erro de protocolo.
• 1006 indica que a conexão foi fechada anormalmente.
• 1009 indica que o tamanho do quadro excedeu o limite de 4 MB.
• 1011 indica que o serviço está encerrando a conexão porque encontrou uma condição inesperada que o impede de preencher a solicitação, como um argumento inválido. O código de retorno também pode indicar que o texto de entrada era muito grande.

Se o soquete fechar com um erro, o serviço enviará ao cliente uma mensagem informativa do formulário {"error": "Specific error message"}antes de fechar. O serviço também pode enviar mensagens de aviso não fatais para parâmetros desconhecidos. Para obter mais informações sobre os códigos de retorno do site WebSocket, consulte a IETF (Internet Engineering Task Force) Request for Comments(RFC)6455.

As implementações de WebSocket dos SDKs podem retornar códigos de resposta diferentes ou adicionais.

{
  "warnings": "Unknown arguments: invalid-parameter."
}