Mensagens¶

As mensagens da API são transmitidas pela conexão WebSocket em formato binário e podem ter no máximo 2MB de tamanho. Toda mensagem é formada por linhas separadas pela sequência CR (0x0D) e LF (0x10), onde são declarados o tipo da mensagem e seus parâmetros (headers), e opcionalmente o corpo da mensagem. As primeiras linhas são interpretadas como texto codificado em UTF-8, enquanto que o formato e tamanho do corpo são definidos pelos headers Content-Type e Content-Length. Deve existir uma linha vazia terminada em CRLF entre a seção de headers e o corpo da mensagem.

Linha inicial: ASR <versão> <nome da mensagem> CRLF
Zero ou mais headers seguidor por CRLF
Linha vazia (indicando o fim dos headers) CRLF
Conteúdo opcional

As mensagens do protocolo são detalhadas a seguir.

CREATE SESSION¶

Cria uma sessão de reconhecimento de fala. Deve ser enviada pelo cliente após o estabelecimento de uma conexão WebSocket com o servidor. O servidor irá gerar um identificador único da sessão (handle), que irá identificar as respostas enviadas para o cliente. A sessão possui um tempo máximo que pode ficar aberta e sem atividade, sem receber nenhuma mensagem. Se atingido esse tempo, ela será finalizada automaticamente pelo servidor.

Linha Inicial:

ASR 2.3 CREATE_SESSION

Headers:

User-Agent

(Opcional) Campo que contém informações sobre o dispositivo cliente e aplicação sendo executada. A informação pode ser utilizada para registro de log de execução. Para o caso de smartphones, por exemplo, o campo pode conter as seguintes informações:

model (xperia ZQ, iphone 6s)
manufacturer (sony, apple)
os (android, ios)
os_version (6.0, 9.2)
app_name (cpqd stt)
app_version (1.0)
phone_id (string)

Exemplo:

ASR 2.3 CREATE_SESSION
User-Agent: model=iphone 6s;manufacturer=apple;os=ios;os_version=9.3; app_name=cpqd stt;app_version=1.0;phone_id=1A23BB36740

DEFINE GRAMMAR¶

Carrega e compila uma gramática, permitindo que seja posteriormente usada no reconhecimento.

Linha Inicial:

ASR 2.3 DEFINE_GRAMMAR

Headers:

Content-ID

Indica o nome que será definido como referência para usar a gramática no reconhecimento.

Content-Length

Indica o número de bytes do conteúdo

Content-Type

Descreve o tipo da gramática. Valores válidos:

URI de gramática ou modelo de fala livre:

text/uri-list

Gramática SRGS XML:

application/grammar+xml
application/srgs+xml
application/xml

Gramática SRGS ABNF:

text/xml
application/srgs
text/plain

Exemplos:

ASR 2.3 DEFINE_GRAMMAR
Content-Type: text/uri-list
Content-Length: 19
Content-ID: menu2

builtin:slm/general

ASR 2.3 DEFINE_GRAMMAR
Content-Type: application/srgs
Content-Length: 105
Content-ID: yes_no

#ABNF 1.0 UTF-8;
language pt-BR;
tag-format <semantics/1.0>;
mode voice;

root $root;
$root = sim | não;

SET PARAMETERS¶

Permite definir parâmetros do reconhecimento para a sessão. Ela pode ser enviada sempre que a sessão estiver no estado IDLE. Os parâmetros devem ser enviados como headers da mensagem. A lista completa dos parâmetros é mostrada na seção Configuração. Na resposta a essa mensagem, o servidor irá retornar o estado atual de cada parâmetro, ou um código de erro caso tenha ocorrido algum problema com a definição do parâmetro.

Linha Inicial:

ASR 2.3 SET_PARAMETERS

Headers: (Configuração)

Exemplo:

ASR 2.3 SET_PARAMETERS
decoder.maxSentences: 3
noInputTimeout.enabled: true
noInputTimeout.value: 5000

GET PARAMETERS¶

Recupera os valores atuais dos parâmetros da sessão de reconhecimento. O cliente deve especificar na seção de headers os parâmetros que deseja obter, com valores vazios. Caso não especifique nenhum, o servidor irá retornar a lista de todos os parâmetros existentes com os valores atuais. A lista completa dos parâmetros é mostrada na seção Configuração. O servidor irá enviar os valores atuais dos parâmetros na seção header da mensagem RESPONSE.

Linha Inicial:

ASR 2.3 GET_PARAMETERS

Headers: (Configuração)

Exemplo:

ASR 2.3 GET_PARAMETERS
decoder.maxSentences:
noInputTimeout.enabled:
noInputTimeout.value:

START RECOGNITION¶

Inicia o reconhecimento. Deve ser enviado sempre que a sessão estiver no estado IDLE. O cliente deve informar o modelo de língua a ser utilizado no reconhecimento, seja um modelo de fala livre ou uma gramática. No caso de ser uma gramática, ela deve ter sido previamente instalada no servidor. O cliente pode também definir parâmetros do reconhecimento na seção de headers da mensagem (lista completa em Configuração). O início do reconhecimento também dispara a contagem dos temporizadores de início de fala (noInputTimeout) e de reconhecimento (recognitionTimeout), caso estejam habilitados.

Linha Inicial:

ASR 2.3 START_RECOGNITION

Headers:

Accept	(Opcional) Tipo de conteúdo do resultado do reconhecimento. Valores válidos: application/xml application/json Valor padrão: application/json.
Content-ID	Indica o nome que será definido como referência para usar a gramática no reconhecimento.
Content-Length	Indica o número de bytes do conteúdo
Content-Type	Descreve o tipo do modelo da língua. Valores válidos: URI de gramática ou modelo de fala livre: text/uri-list Gramática SRGS XML: application/grammar+xml application/srgs+xml application/xml Gramática SRGS ABNF: text/xml application/srgs text/plain

No caso de Content-Type igual a text/uri-list, a URI do modelo da língua deve possuir um dos prefixos abaixo:

builtin - modelo interno (ex. builtin:slm/general).

file - modelo localizado no servidor ASR (ex. file:///opt/grammar/menu, file:///opt/grammar/menu.gram).

http - modelo localizado na rede (ex. http://acme.com/grammar/menu.gram).

session - URI de referência definida através de DEFINE_GRAMMAR (ex. session:menu2).

Exemplos:

ASR 2.3 START_RECOGNITION
Accept: application/json
decoder.maxSentences: 3
noInputTimeout.enabled: true
noInputTimeout.value: 5000
Content-Type: text/uri-list
Content-Length: 19

builtin:slm/general

ASR 2.3 START_RECOGNITION
Accept: application/json
decoder.maxSentences: 3
noInputTimeout.enabled: true
noInputTimeout.value: 5000
Content-Type: text/uri-list
Content-Length: 13

session:menu2

ASR 2.3 START_RECOGNITION
Accept: application/json
decoder.maxSentences: 3
noInputTimeout.enabled: true
noInputTimeout.value: 5000
Content-Type: application/srgs
Content-ID: yes_no
Content-Length: 105

#ABNF 1.0 UTF-8;
language pt-BR;
tag-format <semantics/1.0>;
mode voice;

root $root;
$root = sim | não;

INTERPRET TEXT¶

Realiza a interpretação semântica de um texto fornecido pelo cliente, usando a gramática indicada, de forma similar à mensagem START RECOGNITION. Deve ser enviado sempre que a sessão estiver no estado IDLE. O cliente deve informar a gramática a ser utilizada no reconhecimento.

Linha Inicial:

ASR 2.3 INTERPRET_TEXT

Headers:

Accept	(Opcional) Tipo de conteúdo do resultado do reconhecimento. Valores válidos: application/xml application/json Valor padrão: application/json.
Content-ID	Indica o nome que será definido como referência para usar a gramática no reconhecimento.
Content-Length	Indica o número de bytes do conteúdo
Content-Type	Descreve o tipo da gramática. Valores válidos: URI de gramática: text/uri-list Gramática SRGS XML: application/grammar+xml application/srgs+xml application/xml Gramática SRGS ABNF: text/xml application/srgs text/plain

Exemplo:

ASR 2.3 INTERPRET_TEXT
Accept: application/json
Content-Type: application/srgs
Content-ID: yes_no
Content-Length: 105
Text: sim eu quero

#ABNF 1.0 UTF-8;
language pt-BR;
tag-format <semantics/1.0>;
mode voice;

root $root;
$root = sim [eu quero] {"yes"} | não [quero] {"no"};

START INPUT TIMERS¶

Inicia os temporizadores de início de fala e de reconhecimento, caso eles estejam habilitados. Para iniciar os temporizadores, a sessão de reconhecimento deve estar no estado ativo (LISTENING ou RECOGNIZING). O tempo de cada temporizador é definido respectivamente pelos parâmetros noInputTimeout e recognitionTimeout.

Linha Inicial:

ASR 2.3 START_INPUT_TIMERS

SEND AUDIO¶

Envia um bloco de amostras de áudio para o processo de reconhecimento. A sessão deve estar no estado LISTENING. O conteúdo de áudio deve ser enviado no corpo da mensagem, em formato binário, com tamanho máximo de 2 MB. O formato do áudio pode ser PCM Linear, amostras de 16 bits e taxa de amostragem de 8kHz ou 16kHz, de acordo com o Modelo Acústico (AM) instalado do servidor sem codificação (RAW) e sem cabeçalho, ou áudio codificado com ou sem compressão pelos Codecs MP3, OPUS, VORBIS, PCM aLaw/uLaw, GSM, FLAC e WAV. A mensagem também pode ser usada para sinalizar que a captura de áudio finalizou na aplicação cliente, e neste caso o parâmetro LastPacket deve conter o valor true, e o corpo da mensagem pode ser vazio. A partir desse momento, o servidor finaliza o reconhecimento e realiza o processamento final dos segmentos de fala recebidos.

Linha Inicial:

ASR 2.3 SEND_AUDIO

Headers:

LastPacket

Indica se a amostra enviada é a última amostra, e a sessão pode iniciar o reconhecimento. Valores: true ou false. Obrigatório.

Content-Length

Indica o número de bytes do conteúdo

Content-Type

Descreve o tipo do conteúdo. Valores válidos:

application/octet-stream – arquivo codificado num formato suportado
audio/wav – arquivo codificado num formato suportado
audio/raw – áudio PCM Linear sem cabeçalho

CANCEL RECOGNITION¶

Interrompe um reconhecimento em andamento. Deve ser enviado com a sessão de reconhecimento no estado LISTENING ou RECOGNIZING. Todos os dados do reconhecimento são descartados e a sessão retorna ao estado IDLE.

Linha Inicial:

ASR 2.3 CANCEL_RECOGNITION

RELEASE SESSION¶

Encerra uma sessão de reconhecimento, liberando os recursos alocados no servidor. A conexão WebSocket é encerrada.

Linha Inicial:

ASR 2.3 RELEASE_SESSION

RESPONSE¶

Mensagem de resposta gerada pelo servidor, indicando sucesso ou falha no processamento de uma mensagem recebida anteriormente. Contém o estado atual da sessão de reconhecimento e informações adicionais.

Linha Inicial:

ASR 2.3 RESPONSE

Headers:

Handle	Identificador da sessão de reconhecimento
Method	Nome da mensagem relacionada com a resposta.
Expires	Tempo de duração da sessão de reconhecimento. A temporização é reiniciada a cada mensagem recebida pelo servidor. Em caso de inatividade, ela será encerrada dentro do tempo informado (em segundos).
Result	Resultado da ação executada no servidor, se sucesso, falha ou inválida. Valores válidos: SUCCESS, FAILURE, INVALID_ACTION.
Session-Status	Estado da sessão de reconhecimento. Valores válidos: IDLE, LISTENING, RECOGNIZING.
Error-Code	Código de erro, em caso de falha (Códigos de erro).
Message	Mensagem complementar que indica o motivo da falha.

START OF SPEECH¶

Mensagem gerada pelo servidor quando o processo de reconhecimento detecta o início de um segmento de fala no fluxo de áudio recebido.

Linha Inicial:

ASR 2.3 START_OF_SPEECH

Headers:

Handle	Identificador da sessão de reconhecimento
Session-Status	Estado da sessão de reconhecimento.

END OF SPEECH¶

Mensagem gerada pelo servidor quando o processo de reconhecimento detecta o fim de um segmento de fala (silêncio) no fluxo de áudio recebido.

Linha Inicial:

ASR 2.3 END_OF_SPEECH

Headers:

Handle	Identificador da sessão de reconhecimento
Session-Status	Estado da sessão de reconhecimento.

RECOGNITION RESULT¶

Mensagem que contém o resultado do reconhecimento. Ela é enviada quando existe um resultado parcial ou final disponível. O resultado final é gerado após a detecção do fim da fala ou finalização do fluxo de áudio, quando o cliente envia uma mensagem SEND AUDIO com a indicação LastPacket = true. O resultado parcial do reconhecimento contém apenas uma frase que representa o texto reconhecimento a partir do áudio recebido até o momento. Já o reconhecimento final contém informações mais completas, como alternativas de resultados de reconhecimento, com índices de confiança e eventualmente resultados de interpretação gerados por gramáticas.

Linha Inicial:

ASR 2.3 RECOGNITION_RESULT

Headers:

Handle	Identificador da sessão de reconhecimento
Session-Status	Estado da sessão de reconhecimento.
Result-Status	Indica o estado do reconhecimento. Valores válidos: PROCESSING RECOGNIZED NO_MATCH NO_INPUT_TIMEOUT MAX_SPEECH EARLY_SPEECH RECOGNITION_TIMEOUT NO_SPEECH CANCELED FAILURE
Content-Length	Indica o número de bytes do conteúdo
Content-Type	Descreve o tipo do conteúdo. Valores válidos: application/json application/xml

O conteúdo do resultado de reconhecimento é formado pelos seguintes campos:

recognition_result

Nome do campo

Descrição

Tipo

alternatives

lista de alternativas de resultado de reconhecimento

ver elemento alternative

result_status

status do reconhecimento

valores válidos:

PROCESSING
RECOGNIZED
NO_MATCH
NO_INPUT_TIMEOUT
MAX_SPEECH
EARLY_SPEECH
RECOGNITION_TIMEOUT
NO_SPEECH
CANCELED
FAILURE

alternative

Nome do campo	Descrição	Tipo
text	texto reconhecido	texto
score	índice de confiança	numérico
interpretations	lista de resultados da interpretação gramatical	estrutura que representa a interpretação gerada pela gramática utilizada

Obs: o conteúdo do resultado do reconhecimento pode conter campos adicionais, devido a extensões futuras e novas funcionalidades. A aplicação que irá ler e analisar o resultado não deve gerar falha caso encontre campos adicionais no formato JSON ou XML.

Exemplo de conteúdo:

Resultado JSON:

{
  "alternatives": [{
    "text": "oito sete quatro três um",
    "interpretations": ["87431"],
    "words": [{
      "text": "oito",
      "score": 100,
      "start_time": 0.3901262,
      "end_time": 0.95921874
    }, {
      "text": "sete",
      "score": 100,
      "start_time": 0.99,
      "end_time": 1.7068747
    }, {
      "text": "quatro",
      "score": 100,
      "start_time": 1.74,
      "end_time": 2.28
    }, {
      "text": "três",
      "score": 100,
      "start_time": 2.2800765,
      "end_time": 2.8498626
    }, {
      "text": "um",
      "score": 100,
      "start_time": 2.9167604,
      "end_time": 3.2101758
    }],
    "score": 100,
    "lm": "builtin:grammar/digits",
    "interpretation_scores": [100]
  }],
  "segment_index": 0,
  "last_segment": true,
  "final_result": true,
  "start_time": 0.24,
  "end_time": 3.52,
  "result_status": "RECOGNIZED"
}