API WebSocket

A API WebSocket permite a integração de aplicações com as funções de síntese de fala, com um canal de comunicação de baixa latência e pequeno overhead para a transferência de stream de áudio.

Este documento tem como objetivo detalhar o mecanismo de comunicação da API WebSocket do servidor de síntese de fala do CPqD, visando facilitar a integração de aplicações que façam uso de suas funcionalidades.

Visão geral

Para utilizar a interface de integração WebSocket, o servidor WebSocket/REST do CPqD Texto Fala deve estar instalado e disponível através de uma URL.

URL padrão

ws://<SERVER>/ws/v1/synthesize

A conexão entre aplicação e servidor é estabelecida de maneira padrão para essa tecnologia, ou seja, através de uma mensagem HTTP de handshake enviada pelo cliente, com indicação de upgrade da conexão para o protocolo WebSocket. O servidor irá responder o handshake e abrir uma conexão socket com o cliente. A partir desse momento, mensagens podem ser trocadas entre os dois endpoints.

Mensagens

A API WebSocket utiliza um conjunto de mensagens para acionar as funções do Texto Fala. Ela é composta pelas seguintes mensagens:

SET PARAMS Define parâmetros de configuração da síntese de fala para a sessão websocket, como voz, codificação, volume e ritmo da fala.
GET PARAMS Obtém os parâmetros de configuração da síntese de fala para a sessão websocket.
TEXT TO SPEECH Realiza a síntese de fala a partir de um texto ou XML/SSML.
STOP Interrompe o stream de áudio, após o início da síntese.
ENCODERS Obtém os nomes dos encoders de voz.
VOICES Obtém os nomes das vozes disponíveis.
  • Formato: as mensagens possuem formato JSON e devem ser enviadas pela aplicação no socket aberto. Dependendo da mensagem, o servidor poderá responder uma mensagem em formato texto (JSON) ou o stream de áudio em formato binário. O corpo da requisição deve possuir os seguintes atributos:
mType indica a mensagem. Valores: «get-param», «set-param», «text-to-speech», «stop», «encoders», «voices»
text (opcional) o texto a ser convertido em áudio
voice (opcional) o nome da voz. Veja valores válidos em “/rest/v2/voices”
encoder (opcional) o nome do encoder de áudio. Veja valores válidos em “/rest/v2/encoders”
volume (opcional) define o volume padrão. Valores aceitos: 0.0 (mudo) a 2.0 (alto). O valor padrão é 1.0.
rate (opcional) define o ritmo padrão. Valores aceitos: 0.3 (lento) a 3.0 (rápido). O valor padrão é 1.0.
cache (opcional) indica se o áudio pode ser recuperado de memória cache ou se a síntese deve ser realizada (boolean)
autoclose (opcional) indica se o socket deve ser fechado após a síntese

Exemplos de mensagens:

Mensagem de configuração de parâmetros da sessão

Mensagem:

{
  "mType": "set-param"
  "voice": "rosana-highquality.voice",
  "encoder": "wav/16000/8/1",
  "volume": 1.0,
  "rate": 0.8
}

Resposta do servidor:

{
  "voice":"rosana-highquality.voice",
  "volume":1.0,
  "rate":0.8,
  "encoder":"wav/16000/8/1"
}

Mensagem de leitura dos parâmetros da sessão

Mensagem:

{
  "mType": "get-param"
}

Resposta do servidor:

{
  "voice":"rosana-highquality.voice",
  "volume":1.0,
  "rate":0.8,
  "encoder":"wav/16000/8/1"
}

Mensagem de síntese de fala com configuração de parâmetros da sessão

Mensagem:

{
  "mType": "text-to-speech"
  "text": "Alô mundo",
  "voice": "adriana-highquality.voice",
  "cache": true
  "autoclose": false
}

Resposta do servidor: stream de áudio binário. O socket poderá fechar automaticamente ao final do stream caso o parâmetro autoclose esteja definido como true na mensagem de text-to-speech.

Mensagem interrupção do *stream* de áudio

Mensagem:

{
  "mType": "stop"
}

Resposta do servidor: fim do stream.

<?xml version="1.0" encoding="UTF-8"?>
<speak version="1.1" xmlns="http://www.w3.org/2001/10/synthesis" xml:lang="pt-BR">
        <expressive>Olá!</expressive>
        <expressive>Boa tarde!</expressive>
        Eu sou Rosana, a voz feminina do CPqD, para o português.
        Você pode mudar minha voz como quiser. Por exemplo:
        <prosody pitch="+30%"> Eu consigo falar mais fino, </prosody>
        <prosody pitch="-30%"> ou mais grosso. </prosody>
        <prosody rate="70%"> Consigo falar mais lento, </prosody>
        <prosody rate="180%"> ou mais rápido que o normal. </prosody>
        <prosody volume="+12dB"> Também consigo falar mais alto, </prosody>
        <prosody volume="-12dB"> e bem mais baixo. </prosody>
        Nessa nova versão de texto fala, podemos usar, por exemplo,
        <voice name="carlos-highquality.voice"> a voz do Carlos em português junto com a voz da Rosana. </voice>
        Bacana,
        <expressive>Não acha?</expressive>
        <expressive>Agradecemos sua visita! </expressive>
        <expressive>Até a próxima!</expressive>
</speak>

Erros

Caso ocorra algum erro na requisição de síntese, o servidor irá enviar uma mensagem com os seguinte atributos:

code código numérico indicando o erro.
message mensagem descritiva

Exemplo:

{
  "code": "3",
  "message": "No suitable plugin found"
}