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¶

Para realizar uma síntese de fala, a aplicação deve enviar o texto pelo socket em uma mensagem nos formatos abaixo. O servidor irá responder com o stream de áudio.

JSON: o corpo da requisição deve ser um objeto JSON com os seguintes atributos:

text o texto a ser convertido em áudio, codificado como URL

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”

cache (opcional) indica se o áudio pode ser recuperado de memória cache ou se a síntese deve ser realizada (boolean)

Exemplo:
{
  "text": "Alô mundo",
  "voice": "rosana-highquality.voice",
  "encoder": "wav/16000/8/1",
  "cache": true
}

SSML/XML: neste caso, o conteúdo deve ser um documento XML no padrão SSML (veja: https://www.w3.org/TR/speech-synthesis11 ). Exemplo:

<?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. Valores:

400 - Encoder inválido

401 - Erro interno na sessão

402 - Voz inválida

message mensagem descritiva

Exemplo:
{
  "code": 400,
  "message": "abcd encoder not found"
}

.