Métodos

Nesta seção detalharemos os métodos existentes na API ASR REST.

RECOGNIZE

Realiza o reconhecimento de fala de um áudio enviado para o serviço. O conteúdo do áudio deve ser enviado no corpo da mensagem HTTP. O reconhecimento é realizado de forma síncrona e o resultado vem na resposta HTTP.

Requisição

POST /asr-server/rest/recognize

HTTP Headers

Accept	(Opcional) Tipo de conteúdo do resultado do reconhecimento. Valores válidos: application/xml application/json Valor padrão: application/json.
User-Agent	Identificação do dispositivo e/ou aplicação que está gerando o áudio. Útil para fins de log de aplicação.
Content-Length	Indica o número de bytes do conteúdo
Content-Type	Indica o formato do áudio enviado. Formatos válidos: audio/wav – arquivos no formato WAV audio/raw – áudio puro sem cabeçalho application/octet-stream – áudio puro sem cabeçalho application/x-www-form-urlencode

O reconhecimento de fala pode ser configurado para se adaptar às características específicas da aplicação. A configuração é feita através de parâmetros definidos como headers da requisição HTTP. A lista completa dos parâmetros é mostrada na seção Configuração. O exemplo a seguir mostra a configuração dos parâmetros endpointer.levelThreshold e decoder.confidenceThreshold:

POST /asr-server/rest/recognize?lm=builtin:slm/general HTTP/1.1
Host: 127.0.0.1:8025
User-Agent: curl/7.47.0
Accept: */*
Content-Type: audio/wav
endpointer.levelThreshold: 10
decoder.confidenceThreshold: 30
Content-Length: ...

[binary content]

Parâmetros da requisição

lm

URI do modelo de língua. Caso não seja informada, será retornado um erro. A URI deve possuir um dos prefixos abaixo: builtin - modelo interno (ex. builtin:slm/general). file - modelo localizado no servidor (ex. file:///opt/grammar/menu, file:///opt/grammar/menu.gram). http - modelo localizado na rede (ex. http://acme.com/grammar/menu.gram).

Resultado (HTTP status = 200)

Se a requisição HTTP retorna status code “200”, o corpo da resposta possui a estrutura abaixo. O formato da resposta pode ser definido através do header HTTP “Accept”, selecionando JSON (Accept: application/json) ou XML (Accept: application/xml). O formato padrão é JSON.

recognition_result

• alternatives
• result_status

alternatives: lista com os resultados prováveis do reconhecimento

• index: índice da alternativa de resultado
• text: texto reconhecimento
• score: pontuação ou índice de confiança
• interpretations: lista com os resultados da interpretação, conforme definido na gramática. Em caso de modelo de língua de fala livre, essa lista é vazia.

result_status: estado do reconhecimento. Pode ser um dos valores abaixo:

result_status	Descrição
RECOGNIZED	reconhecimento realizado com sucesso
NO_MATCH	reconhecimento realizado com sucesso mas sem correspondência na gramática
NO_INPUT_TIMEOUT	o reconhecimento não detectou o início de fala antes do vencimento do temporizador
EARLY_SPEECH	o áudio recebido não possui trecho de silêncio inicial (a fala começou antes do início do reconhecimento)
MAX_SPEECH	o servidor recebeu uma quantidade de áudio maior do que a capacidade de processamento
RECOGNITION_TIMEOUT	não foi possível gerar um resultado final antes do vencimento do temporizador
NO_SPEECH	não foi possível detectar fala no áudio enviado
CANCELED	o reconhecimento foi cancelado
FAILURE	falha não específica no servidor

Resultado (HTTP status <> 200)

Se a requisição HTTP retorna erro, com status code diferente de “200”, a resposta possui a estrutura abaixo.

ErrorResponse

• code: Código de erro (Códigos de erro).
• message: Mensagem complementar que indica o motivo da falha.

Exemplos

Chamada REST com resultado JSON:

curl -X POST \
  --header "Content-Type: audio/wav" \
  --header "decoder.maxSentences: 1" \
  --data-binary '@/opt/cpqd/asr/samples/audio/ptbr/87431_8k.wav' \
  http://127.0.0.1:8025/asr-server/rest/recognize?lm=builtin:grammar/digits

Resultado:

[{
  "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"
}]

Chamada REST com resultado XML:

curl -X POST \
  --header "Content-Type: audio/wav" \
  --header "Accept: application/xml" \
  --header "decoder.maxSentences: 1" \
  --data-binary '@/opt/cpqd/asr/samples/audio/ptbr/87431_8k.wav' \
  http://127.0.0.1:8025/asr-server/rest/recognize?lm=builtin:grammar/digits

Resultado:

<ArrayList>
  <item>
    <segment_index>0</segment_index>
    <last_segment>true</last_segment>
    <final_result>true</final_result>
    <start_time>0.24</start_time>
    <end_time>3.52</end_time>
    <result_status>RECOGNIZED</result_status>
    <alternatives>
      <alternative>
        <text>oito sete quatro três um</text>
        <score>100</score>
        <lm>builtin:grammar/digits</lm>
        <interpretations>
          <interpretation>87431</interpretation>
        </interpretations>
        <interpretation_scores>
          <interpretation_score>100</interpretation_score>
        </interpretation_scores>
        <words>
          <word>
            <text>oito</text>
            <score>100</score>
            <start_time>0.3901258</start_time>
            <end_time>0.95921737</end_time>
          </word>
          <word>
            <text>sete</text>
            <score>100</score>
            <start_time>0.99</start_time>
            <end_time>1.7068772</end_time>
          </word>
          <word>
            <text>quatro</text>
            <score>100</score>
            <start_time>1.74</start_time>
            <end_time>2.28</end_time>
          </word>
          <word>
            <text>três</text>
            <score>100</score>
            <start_time>2.2800772</start_time>
            <end_time>2.8498623</end_time>
          </word>
          <word>
            <text>um</text>
            <score>100</score>
            <start_time>2.9167345</start_time>
            <end_time>3.210177</end_time>
          </word>
        </words>
      </alternative>
    </alternatives>
  </item>
</ArrayList>

Resultado com erro (JSON):

{
  "code":"ERR_LM_NOT_FOUND",
  "message":"Language Model not found: builtin:grammar/booh"
}

Resultado com erro (XML):

<ErrorResponse>
  <code>ERR_LM_NOT_FOUND</code>
  <message>Language Model not found: builtin:grammar/booh</message>
</ErrorResponse>

INTERPRET

Realiza a interpretação semântica de um texto fornecido pelo cliente, usando a gramática indicada, de forma similar a RECOGNIZE. O texto deve ser enviado no corpo da mensagem HTTP. O reconhecimento é realizado de forma síncrona e o resultado vem na resposta HTTP.

Requisição

POST /asr-server/rest/interpret

HTTP Headers

Accept	(Opcional) Tipo de conteúdo do resultado do reconhecimento. Valores válidos: application/xml application/json Valor padrão: application/json.
User-Agent	Identificação do dispositivo e/ou aplicação que está gerando o áudio. Útil para fins de log de aplicação.
Content-Length	Indica o número de bytes do conteúdo
Content-Type	Indica o formato do áudio enviado. Formatos válidos: text/plain – conteúdo de texto

Parâmetros da requisição

lm

URI do modelo de língua. Caso não seja informada, será retornado um erro. A URI deve possuir um dos prefixos abaixo: builtin - modelo interno (ex. builtin:slm/general). file - modelo localizado no servidor (ex. file:///opt/grammar/menu, file:///opt/grammar/menu.gram). http - modelo localizado na rede (ex. http://acme.com/grammar/menu.gram).

Resultado

O resultado do reconhecimento é um objeto que possui a mesma estrutura do “recognize” mas apenas alguns campos fazem sentido e devem ser usados:

recognition_result

• alternatives
• result_status

alternatives: lista com os resultados prováveis do reconhecimento

• text: texto reconhecimento
• score: pontuação ou índice de confiança
• interpretations: lista com os resultados da interpretação, conforme definido na gramática. Em caso de modelo de língua de fala livre, essa lista é vazia.

result_status: estado do reconhecimento. Pode ser um dos valores abaixo:

result_status	Descrição
RECOGNIZED	reconhecimento realizado com sucesso
NO_MATCH	reconhecimento realizado com sucesso mas sem correspondência na gramática
CANCELED	o reconhecimento foi cancelado
FAILURE	falha não específica no servidor

Exemplos

Chamada REST com resultado JSON:

curl -X POST \
  --header "Content-Type: text/plain" \
  --data 'oito sete quatro três um' \
  http://127.0.0.1:8025/asr-server/rest/interpret?lm=builtin:grammar/digits

Resultado:

{
  "alternatives": [{
    "text": "oito sete quatro três um",
    "interpretations": ["87431"],
    "score": 100,
    "lm": "builtin:grammar/digits",
    "interpretation_scores": [100]
  }],
  "result_status": "RECOGNIZED"
}

Chamada REST com resultado XML:

curl -X POST \
  --header "Content-Type: application/xml"
  --data 'oito sete quatro três um' \
  http://127.0.0.1:8025/asr-server/rest/interpret?lm=builtin:grammar/digits

Resultado:

<recognition_result>
  <result_status>RECOGNIZED</result_status>
  <alternatives>
    <alternative>
      <text>oito sete quatro três um</text>
      <score>100</score>
      <lm>builtin:grammar/digits</lm>
      <interpretations>
        <interpretation>87431</interpretation>
      </interpretations>
      <interpretation_scores>
        <interpretation_score>100</interpretation_score>
      </interpretation_scores>
    </alternative>
  </alternatives>
</recognition_result>