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:
|
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:
Gramática SRGS XML:
Gramática SRGS ABNF:
|
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 (ver estados da sessão em Estados da sessão de reconhecimento). Os parâmetros devem ser enviados como headers da mensagem, e a sua definição está descrita em Parâmetros de reconhecimento. 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: ver relação em Parâmetros de reconhecimento.
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 – ver lista de parâmetros em Parâmetros de reconhecimento. 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: ver relação em Parâmetros de reconhecimento.
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 (ver estados da sessão em Estados da sessão de reconhecimento). 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. 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:
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:
Gramática SRGS XML:
Gramática SRGS ABNF:
|
Obs: ver headers de parâmetros de reconhecimento em Parâmetros de reconhecimento.
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 (ver estados da sessão em Estados da sessão de reconhecimento). 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:
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:
Gramática SRGS XML:
Gramática SRGS ABNF:
|
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 deve ser sempre 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. A codificação do áudio deve ser RAW (sem cabeçalho). 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:
Valor padrão: application/octet-stream |
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 gerado pela operação, em caso de falha – ver Códigos de erro. |
Message | Mensagem complementar que indica o motivo da falha ou de mensagem inválida. |
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:
|
Content-Length | Indica o número de bytes do conteúdo |
Content-Type | Descreve o tipo do conteúdo. Valores válidos:
|
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:
|
- 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":"transfira seis mil novecentos e trinta e sete reais para a conta corrente", "interpretations":[{ "action":"TRANSFERENCIA", "money":6937, "to_account_type":"CONTA_CORRENTE" }], "words":[ {"text":"transfira","score":100,"start_time":2.26,"end_time":3.0099998}, {"text":"seis","score":100,"start_time":3.0099998,"end_time":3.37}, {"text":"mil","score":100,"start_time":3.37,"end_time":3.61}, {"text":"novecentos","score":100,"start_time":3.61,"end_time":4.33}, {"text":"e","score":100,"start_time":4.33,"end_time":4.39}, {"text":"trinta","score":100,"start_time":4.39,"end_time":4.7499404}, {"text":"e","score":99,"start_time":4.7499404,"end_time":4.810059}, {"text":"sete","score":100,"start_time":4.810059,"end_time":5.2}, {"text":"reais","score":100,"start_time":5.2,"end_time":5.709542}, {"text":"para","score":90,"start_time":5.71106,"end_time":5.988702}, {"text":"a","score":45,"start_time":5.990944,"end_time":6.0397873}, {"text":"conta","score":100,"start_time":6.0425696,"end_time":6.4599996}, {"text":"corrente","score":100,"start_time":6.4599996,"end_time":7.1797533} ], "score":95, "lm":"file:///opt/cpqd/asr/tools/grammar/samples/ptbr/bank.gram", "interpretation_scores":[94] }, { "text":"transfira seis mil novecentos e trinta e sete reais para conta corrente", "interpretations":[{ "action":"TRANSFERENCIA", "money":6937, "to_account_type":"CONTA_CORRENTE" }], "words":[ {"text":"transfira","score":100,"start_time":2.26,"end_time":3.0099998}, {"text":"seis","score":100,"start_time":3.0099998,"end_time":3.37}, {"text":"mil","score":100,"start_time":3.37,"end_time":3.61}, {"text":"novecentos","score":100,"start_time":3.61,"end_time":4.33}, {"text":"e","score":100,"start_time":4.33,"end_time":4.39}, {"text":"trinta","score":100,"start_time":4.39,"end_time":4.7499404}, {"text":"e","score":99,"start_time":4.7499404,"end_time":4.810059}, {"text":"sete","score":100,"start_time":4.810059,"end_time":5.2}, {"text":"reais","score":100,"start_time":5.2,"end_time":5.709542}, {"text":"para","score":90,"start_time":5.7138157,"end_time":6.011838}, {"text":"conta","score":100,"start_time":6.0425696,"end_time":6.4599996}, {"text":"corrente","score":100,"start_time":6.4599996,"end_time":7.1797533} ], "score":95, "lm":"file:///opt/cpqd/asr/tools/grammar/samples/ptbr/bank.gram", "interpretation_scores":[99] }, { "text":"transfira seis mil novecentos e trinta e sete reais pra conta corrente", "interpretations":[{ "action":"TRANSFERENCIA", "money":6937, "to_account_type":"CONTA_CORRENTE" }], "words":[ {"text":"transfira","score":100,"start_time":2.26,"end_time":3.0099998}, {"text":"seis","score":100,"start_time":3.0099998,"end_time":3.37}, {"text":"mil","score":100,"start_time":3.37,"end_time":3.61}, {"text":"novecentos","score":100,"start_time":3.61,"end_time":4.33}, {"text":"e","score":100,"start_time":4.33,"end_time":4.39}, {"text":"trinta","score":100,"start_time":4.39,"end_time":4.7499404}, {"text":"e","score":99,"start_time":4.7499404,"end_time":4.810059}, {"text":"sete","score":100,"start_time":4.810059,"end_time":5.2}, {"text":"reais","score":100,"start_time":5.2,"end_time":5.709542}, {"text":"pra","score":9,"start_time":5.7180476,"end_time":6.012299}, {"text":"conta","score":100,"start_time":6.0425696,"end_time":6.4599996}, {"text":"corrente","score":100,"start_time":6.4599996,"end_time":7.1797533} ], "score":92, "lm":"file:///opt/cpqd/asr/tools/grammar/samples/ptbr/bank.gram", "interpretation_scores":[92]} ], "segment_index":0, "last_segment":true, "final_result":true, "start_time":1.93, "end_time":7.38, "result_status":"RECOGNIZED" }Resultado XML:
<?xml version="1.0" encoding="UTF-8"?> <recognition_result> <segment_index>0</segment_index> <last_segment>true</last_segment> <final_result>true</final_result> <start_time>1.93</start_time> <end_time>7.38</end_time> <result_status>RECOGNIZED</result_status> <alternatives> <alternative> <text>transfira seis mil novecentos e trinta e sete reais para a conta corrente</text> <score>95</score> <lm>file:///opt/cpqd/asr/tools/grammar/samples/ptbr/bank.gram</lm> <interpretations> <interpretation> <action>TRANSFERENCIA</action> <money>6937</money> <to_account_type>CONTA_CORRENTE</to_account_type> </interpretation> </interpretations> <interpretation_scores> <interpretation_score>94</interpretation_score> </interpretation_scores> <words> <word><text>transfira</text><score>100</score><start_time>2.26</start_time><end_time>3.0099998</end_time></word> <word><text>seis</text><score>100</score><start_time>3.0099998</start_time><end_time>3.37</end_time></word> <word><text>mil</text><score>100</score><start_time>3.37</start_time><end_time>3.61</end_time></word> <word><text>novecentos</text><score>100</score><start_time>3.61</start_time><end_time>4.33</end_time></word> <word><text>e</text><score>100</score><start_time>4.33</start_time><end_time>4.39</end_time></word> <word><text>trinta</text><score>100</score><start_time>4.39</start_time><end_time>4.749938</end_time></word> <word><text>e</text><score>99</score><start_time>4.749938</start_time><end_time>4.8100615</end_time></word> <word><text>sete</text><score>100</score><start_time>4.8100615</start_time><end_time>5.2</end_time></word> <word><text>reais</text><score>100</score><start_time>5.2</start_time><end_time>5.7095466</end_time></word> <word><text>para</text><score>90</score><start_time>5.711042</start_time><end_time>5.9897656</end_time></word> <word><text>a</text><score>45</score><start_time>5.991897</start_time><end_time>6.039843</end_time></word> <word><text>conta</text><score>100</score><start_time>6.0425854</start_time><end_time>6.4599996</end_time></word> <word><text>corrente</text><score>100</score><start_time>6.4599996</start_time><end_time>7.179733</end_time></word> </words> </alternative> <alternative> <text>transfira seis mil novecentos e trinta e sete reais para conta corrente</text> <score>95</score> <lm>file:///opt/cpqd/asr/tools/grammar/samples/ptbr/bank.gram</lm> <interpretations> <interpretation> <action>TRANSFERENCIA</action> <money>6937</money> <to_account_type>CONTA_CORRENTE</to_account_type> </interpretation> </interpretations> <interpretation_scores> <interpretation_score>99</interpretation_score> </interpretation_scores> <words> <word><text>transfira</text><score>100</score><start_time>2.26</start_time><end_time>3.0099998</end_time></word> <word><text>seis</text><score>100</score><start_time>3.0099998</start_time><end_time>3.37</end_time></word> <word><text>mil</text><score>100</score><start_time>3.37</start_time><end_time>3.61</end_time></word> <word><text>novecentos</text><score>100</score><start_time>3.61</start_time><end_time>4.33</end_time></word> <word><text>e</text><score>100</score><start_time>4.33</start_time><end_time>4.39</end_time></word> <word><text>trinta</text><score>100</score><start_time>4.39</start_time><end_time>4.749938</end_time></word> <word><text>e</text><score>99</score><start_time>4.749938</start_time><end_time>4.8100615</end_time></word> <word><text>sete</text><score>100</score><start_time>4.8100615</start_time><end_time>5.2</end_time></word> <word><text>reais</text><score>100</score><start_time>5.2</start_time><end_time>5.7095466</end_time></word> <word><text>para</text><score>91</score><start_time>5.713287</start_time><end_time>6.0115943</end_time></word> <word><text>conta</text><score>100</score><start_time>6.0425854</start_time><end_time>6.4599996</end_time></word> <word><text>corrente</text><score>100</score><start_time>6.4599996</start_time><end_time>7.179733</end_time></word> </words> </alternative> <alternative> <text>transfira seis mil novecentos e trinta e sete reais pra conta corrente</text> <score>92</score> <lm>file:///opt/cpqd/asr/tools/grammar/samples/ptbr/bank.gram</lm> <interpretations> <interpretation> <action>TRANSFERENCIA</action> <money>6937</money> <to_account_type>CONTA_CORRENTE</to_account_type> </interpretation> </interpretations> <interpretation_scores> <interpretation_score>92</interpretation_score> </interpretation_scores> <words> <word><text>transfira</text><score>100</score><start_time>2.26</start_time><end_time>3.0099998</end_time></word> <word><text>seis</text><score>100</score><start_time>3.0099998</start_time><end_time>3.37</end_time></word> <word><text>mil</text><score>100</score><start_time>3.37</start_time><end_time>3.61</end_time></word> <word><text>novecentos</text><score>100</score><start_time>3.61</start_time><end_time>4.33</end_time></word> <word><text>e</text><score>100</score><start_time>4.33</start_time><end_time>4.39</end_time></word> <word><text>trinta</text><score>100</score><start_time>4.39</start_time><end_time>4.749938</end_time></word> <word><text>e</text><score>99</score><start_time>4.749938</start_time><end_time>4.8100615</end_time></word> <word><text>sete</text><score>100</score><start_time>4.8100615</start_time><end_time>5.2</end_time></word> <word><text>reais</text><score>100</score><start_time>5.2</start_time><end_time>5.7095466</end_time></word> <word><text>pra</text><score>8</score><start_time>5.7179365</start_time><end_time>6.0120983</end_time></word> <word><text>conta</text><score>100</score><start_time>6.0425854</start_time><end_time>6.4599996</end_time></word> <word><text>corrente</text><score>100</score><start_time>6.4599996</start_time><end_time>7.179733</end_time></word> </words> </alternative> </alternatives> </recognition_result>