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. 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:
|
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:
|
Infer-age-enabled |
Para a utilização deste parâmetro e dos demais abaixo, é necessário a instalação dos classificadores. Veja mais em Instalação dos classificadores. (Opcional) Habilita a classificação da idade do usuário. Valores válidos:
|
Infer-gender-enabled |
(Opcional) Habilita a classificação do gênero do usuário. Valores válidos:
|
Infer-emotion-enabled |
(Opcional) Habilita a classificação do tom emocional do usuário. Valores válidos:
|
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:
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 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:
|
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:
|
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": "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" }
Exemplo de conteúdo com classificadores ativados:
Resultado JSON:
{ "alternatives": [ { "text":"eu quero uma pizza vegetariana", "words": [ { "text":"eu", "score":100, "start_time":2.07, "end_time":2.22 }, { "text":"quero", "score":100, "start_time":2.22, "end_time":2.46 }, { "text":"uma", "score":100, "start_time":2.46, "end_time":2.55 }, { "text":"pizza", "score":100, "start_time":2.58, "end_time":2.9699998 }, { "text": "vegetariana", "score":99, "start_time":2.9699998, "end_time":3.81 } ], "score":100, "lm":"builtin:slm/general" } ], "segment_index":0, "last_segment":true, "final_result":true, "start_time":1.89, "end_time":4.11, "result_status":"RECOGNIZED", "age_scores": { "event":"AGE RESULT", "age":40, "p": { "0-10":0.01081965242528771, "10-20":0.029900746517022576, "20-30":0.2310176922930421, "30-40":0.2953949414741132, "40-50":0.3094747860254778, "50-60":0.09031702121414274, "60-70":0.03307379757374083, "70-80":7.580366987119501e-09, "80-90":2.7472638163325944e-11, "90-100":1.3548693335123092e-06 }, "confidence":"low" }, "gender_scores": { "event":"GENDER RESULT", "p": [ 0.6919918723783355, 0.3080081276216645 ], "gender":"M" }, "emotion_scores": { "event":"EMOTION RESULT", "emotion":"frustrado", "group":"negativo_desativado", "p": { "enojado":0.016020191833376884, "frustrado":0.004789985250681639, "triste":0.06701598316431046, "ansioso":0.004265608265995979, "entusiasmado":0.014406840316951275, "feliz":0.0023290086537599564, "surpreso":0.001975081628188491, "amedrontado":0.010442364029586315, "neutro":0.873554527759552, "irritado":0.005200384650379419 }, "p_groups": { "negativo_desativado":0.5334398560225964, "positivo":0.18596377968788147, "neutro":0.18708890676498413, "negativo_ativado":0.09350738674402237 } } }