Mensagens¶
CREATE SESSION¶
Cria uma sessão de um recurso de verificação biométrica. O cliente deve inicialmente abrir uma conexão Websocket com o servidor e então enviar a mensagem. 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, ou seja, sem receber nenhuma mensagem. Se atingido esse tempo, ela será finalizada automaticamente pelo servidor. Para enviar esta mensagem, o estado da sessão deve ser NONE ou IDLE. Se estiver no estado IDLE, o servidor irá encerrar a sessão atual e criar uma nova. O estado da sessão transita para IDLE.
Linha Inicial:
SPEAKVERIFY 1.0 CREATE_SESSION
Headers:
Channel-Identifier |
Identificação da sessão no MRCP para compartilhamento de recursos. |
Repository-URI |
Define o repositório dos voiceprints biométricos que será usado na sessão. |
Voiceprint-Identifier |
Define a identificação do voiceprint a ser utilizado na verificação biométrica. Pode conter uma lista de identificadores separadas por ponto-e-vírgula, em cenários de multi-verificações. |
Verification-Mode |
Define se o recurso de biometria deve ser utilizado para cadastrar/atualizar ou verificar/identificar um voiceprint. Valores:
|
Min-Verification-Score |
(Opcional) Define o valor mínimo do score da verificação biométrica para gerar uma decisão “accepted”. É um valor float entre -1.0 e 1.0. Quando ausente, a decisão é sempre undecided. |
Num-Min-Verification-Phrases |
(Opcional) Define o número mínimo de frases antes de o servidor gerar uma decisão. O servidor não irá gerar uma decisão até que o número mínimo de interações ocorra. É um valor inteiro e o valor mínimo é 1 (valor padrão). |
Num-Max-Verification-Phrases |
(Opcional) Define o número máximo de frases válidas antes de o servidor gerar uma decisão. O servidor não poderá gerar uma decisão “undecided” quando o número máximo de iterações ocorrer. É um valor inteiro e o valor mínimo é 1 (valor padrão). |
Media-Type |
(Opcional) Indica o formato da mídia (áudio) a ser enviado. Valores:
|
SET PARAMETERS¶
Permite definir parâmetros para a sessão. Os parâmetros devem ser enviados como headers da mensagem. 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. Para enviar esta mensagem, o estado da sessão deve ser IDLE. O servidor processa os parâmetros recebidos e gera uma mensagem de resposta contendo os parâmetros que foram efetivamente processados (parâmetros incorretos são ignorados).
Linha Inicial:
SPEAKVERIFY 1.0 SET_PARAMETERS
Headers:
Min-Verification-Score |
(Opcional) Define o valor mínimo do score da verificação biométrica para gerar uma decisão “accepted”. É um valor float entre -1.0 e 1.0. Quando ausente, a decisão é sempre undecided. |
Num-Min-Verification-Phrases |
(Opcional) Define o número mínimo de frases antes de o servidor gerar uma decisão. O servidor não irá gerar uma decisão até que o número mínimo de interações ocorra. É um valor inteiro e o valor mínimo é 1 (valor padrão). |
Num-Max-Verification-Phrases |
(Opcional) Define o número máximo de frases válidas antes de o servidor gerar uma decisão. O servidor não poderá gerar uma decisão “undecided” quando o número máximo de iterações ocorrer. É um valor inteiro e o valor mínimo é 1 (valor padrão). |
Media-Type |
(Opcional) Indica o formato da mídia (áudio) a ser enviado. Valores:
|
Start-Input-Timers |
(Opcional) Indica se o sistema deve iniciar os temporizadores de início de fala e verificação. Valores:
|
No-Input-Timeout |
(Opcional) Duração do tempo entre o início da verificação e a detecção do início da fala (ms). |
Verification-Timeout |
(Opcional) Duração máxima da verificação em ms. |
Speech-Complete-Timeout |
(opcional) Duração de silêncio após a fala do usuário antes da finalização do segmento de fala (ms). |
Logging-Tag |
(Opcional) Identificação fornecida pela aplicação cliente que é registrada em todas as linhas de log do sistema, com o objetivo de rastrear uma determinada interação com o usuário. |
GET PARAMETERS¶
Recupera os valores atuais dos parâmetros da sessão. 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 todos os parâmetros existentes com os valores atuais. Para enviar esta mensagem, o estado da sessão deve ser IDLE. O servidor processa os parâmetros recebidos e gera uma mensagem de resposta contendo os parâmetros que foram efetivamente processados (parâmetros incorretos são ignorados).
Linha Inicial:
SPEAKVERIFY 1.0 GET_PARAMETERS
Headers: ver headers da mensagem SET PARAMETERS
VERIFY¶
Inicia a operação de verificação ou cadastro de um voiceprint. A operação, o repositório e identificador do voiceprint devem ter sido definidos previamente na sessão (ver mensagem CREATE SESSION). Para enviar esta mensagem, o estado da sessão deve ser IDLE. O estado da sessão transita para LISTENING.
Linha Inicial:
SPEAKVERIFY 1.0 VERIFY
Headers:
Verify-Buffer-Utterance |
(Opcional) Indica se o áudio deve ser armazenado no buffer de verificação biométrica, para ser considerado em operações subsequentes. Valores:
|
Start-Input-Timers |
(Opcional) Indica se o sistema deve iniciar os temporizadores de início de fala e verificação. Valores:
|
No-Input-Timeout |
(Opcional) Duração do tempo entre o início da verificação e a detecção do início da fala (ms). |
Verification-Timeout |
(Opcional) Duração máxima da verificação em ms. |
Speech-Complete-Timeout |
(opcional) Duração de silêncio após a fala do usuário antes da finalização do segmento de fala (ms). |
Media-Type |
(Opcional) Indica o formato da mídia (áudio) a ser enviado. Valores:
|
START INPUT TIMERS¶
Inicia os temporizadores de início de fala e de verificação, caso eles estejam habilitados (parâmetro Start-Input-Timers). O tempo de cada temporizador é definido respectivamente pelos parâmetros No-Input-Timeout e Speech-Complete-Timeout.
Para enviar esta mensagem, o estado da sessão deve ser LISTENING ou VERIFING.
Linha Inicial:
SPEAKVERIFY 1.0 START_INPUT_TIMERS
Headers:
Não há.
SEND AUDIO¶
Envia um bloco de amostras de áudio para o processo de verificação. 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 sem cabeçalho, com amostras de 16 bits e taxa de 8kHz ou 16kHz, de acordo com o Modelo Acústico (AM) instalado do servidor. Outros formatos são suportados, com indicação de cabeçalho, conforme indicado no parâmetro Media Type. 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 Last-Packet deve conter o valor true, e o corpo da mensagem pode ser vazio. Para enviar esta mensagem, o estado da sessão deve ser LISTENING.
Linha Inicial:
SPEAKVERIFY 1.0 SEND_AUDIO
Headers:
Last-Packet
(Opcional) Indica se este é o último pacote do áudio. Valores válidos:
true
false (padrão)
Content-Length
Indica o número de bytes do conteúdo da mensagem.
Content-Type
(Opcional) Indica o formato da mídia (áudio) a ser enviado. Valores:
application/octet-stream;
audio/wav;
audio/mp3;
audio/ogg;
audio/flac;
audio/raw (padrão);
STOP¶
Interrompe uma verificação biométrica em andamento. Para enviar esta mensagem, o estado da sessão deve ser LISTENING.
Linha Inicial:
SPEAKVERIFY 1.0 STOP
Headers:
Não há.
VERIFY FROM BUFFER¶
Inicia a operação de verificação ou cadastro de um voiceprint utilizando áudios armazenados no buffer de verificação. A operação, o repositório e identificador do voiceprint devem ter sido definidos previamente na sessão (ver mensagem CREATE SESSION). Para enviar esta mensagem, o estado da sessão deve ser IDLE. O estado da sessão transita para LISTENING.
Linha Inicial:
SPEAKVERIFY 1.0 VERIFY_FROM_BUFFER
Headers:
Não há.
VERIFY ROLLBACK¶
Descarta o último áudio armazenado no buffer. Esse método não afeta a sequência de áudios armazenados, executá-lo repetidamente não tem efeito, caso não existam novos áudios armazenados. Para enviar esta mensagem, o estado da sessão deve ser NONE ou IDLE.
Linha Inicial:
SPEAKVERIFY 1.0 VERIFY_ROLLBACK
Headers:
Channel-Identifier
Identificação da sessão no MRCP para compartilhamento de recursos.
CLEAR BUFFER¶
Apaga o conteúdo do buffer de verificação, que é utilizado para armazenar os áudios das operações de verificação biométrica e reconhecimento de fala. Para enviar esta mensagem, o estado da sessão deve ser NONE ou IDLE.
Linha Inicial:
SPEAKVERIFY 1.0 CLEAR_BUFFER
Headers:
Channel-Identifier
Identificação da sessão no MRCP para compartilhamento de recursos.
QUERY VOICEPRINT¶
Verifica se um voiceprint existe em um repositório. Indica se ele existe e se foi treinado. Para enviar esta mensagem, o estado da sessão deve ser NONE.
Linha Inicial:
SPEAKVERIFY 1.0 QUERY_VOICEPRINT
Headers:
Repository-URI
Indica o repositório dos voiceprints que será usado na consulta.
Voiceprint-Identifier
Identificador do voiceprint.
DELETE VOICEPRINT¶
Apaga um voiceprint existe em um repositório. Para enviar esta mensagem, o estado da sessão deve ser NONE.
Linha Inicial:
SPEAKVERIFY 1.0 DELETE_VOICEPRINT
Headers:
Repository-URI
Indica o repositório dos voiceprints.
Voiceprint-Identifier
Identificador do voiceprint.
RELEASE SESSION¶
Encerra uma sessão e desaloca os recursos. O estado da sessão transita para NONE. A conexão Websocket não é encerrada pelo servidor. O buffer de verificação mantém o áudio disponível para futuras verificações.
Linha Inicial:
SPEAKVERIFY 1.0 RELEASE_SESSION
Headers:
Não há.
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 e informações adicionais.
Handle |
Identificador da sessão. |
Method |
Nome da mensagem relacionada com a resposta. |
Expires |
Tempo de duração da sessão. 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, IN_PROGRESS. |
Session-Status |
Estado da sessão. Valores válidos: NONE, IDLE, LISTENING, RECOGNIZING, VERIFYING. |
Error-Code |
(Opcional) Código de erro, em caso de falha. |
Message |
(Opcional) Mensagem complementar. |
A tabela abaixo detalha os valores e significados do campo Error-Code:
Error-Code |
Causa |
Descrição |
|---|---|---|
000 |
sucess |
O método foi executado com sucesso. |
001 |
error |
O método encontrou um erro durante a execução |
002 |
no-input-timeout |
O método VERIFY foi encerrado devido ao temporizador |
003 |
too-much-speech-timeout |
O método foi encerrado devido a excesso de fala |
004 |
speech-too-early |
O método VERIFY foi encerrado porque o usuário falou muito cedo |
005 |
buffer-empty |
O método VERIFY-FROM-BUFFER foi encerrado porque o buffer de áudio está vazio |
006 |
out-of-sequence |
O método falhou pois foi enviado fora de sequência esperada. Por ex, enviar VERIFY antes de START-SESSION |
007 |
repository-uri-failure |
Ocorreu uma falha ao acessar o Repository-URI indicado |
008 |
repository-uri-missing |
O campo Repository-URI não foi especificado |
009 |
voiceprint-id-missing |
O campo Voiceprint-id não foi especificado |
010 |
voiceprint-id-not-exist |
O valor indicado no campo Voiceprint-id não existe no repositório |
011 |
channel-identifer-missing |
O campo Channel-Identifier não foi preenchido |
012 |
verification-mode-missing |
O campo Verification-Mode não foi preenchido |
013 |
voiceprint-in-use |
O Voiceprint está em uso e não pode ser alterado |
404 |
illegal-header-value |
O header contém um valor inválido |
403 |
unsupported-header-field |
O header não é suportado |
407 |
grammar-compile-error |
Erro na compilação da gramática |
409 |
unsupported-header-value |
O header contém um valor não suportado |
410 |
token-feats-header |
The authorization feats token is required |
411 |
token-date-expiration |
Retrieved expiration datetime:<valor_da_data>. |
412 |
token-is-required |
The authorization token is required |
413 |
buffer-client-error |
Erro genérico do buffer client |
414 |
rollback-not-allowed |
O uso do verify rollback não é permitido |
START OF SPEECH¶
Mensagem gerada pelo servidor quando o processo de reconhecimento ou verificação detecta o início da fala no áudio recebido.
Headers:
Handle |
Identificação da sessão |
Session-Status |
Estado da sessão |
END OF SPEECH¶
Mensagem gerada pelo servidor quando o processo de reconhecimento ou verificação detecta o fim da fala (silêncio) no áudio recebido.
Headers:
Handle |
Identificação da sessão |
Session-Status |
Estado da sessão |
VERIFICATION RESULT¶
Mensagem que contém o resultado da verificação. Ela é gerada pelo servidor quando existe um resultado final disponível. O resultado final é gerado após atingir o número máximo de interações válidas definidas para a sessão.
Headers:
Handle |
Identificador da sessão |
Session-Status |
Estado da sessão |
Result-Status |
Indica o estado do reconhecimento. Valores válidos:
|
Content-Length |
Indica o número de bytes do conteúdo |
Content-Type |
Indica o formato do conteúdo. Valores válidos:
|
O resultado do reconhecimento é um objeto que contém uma lista de elementos do tipo voiceprint. A lista pode conter mais de um elementos nos casos de verificação em lotes.
Voiceprint¶
Indica o quanto uma amostra de áudio é comparável ao voiceprint biométrico.
Campo
Descrição
Tipo do Campo
id
Identificação do voiceprint
Texto
adapted
Presente no primeiro elemento voiceprint dos resultados. Indica se o voiceprint foi atualizado como consequência da análise das interações. Não está presente durante o treinamento.
Boolean
cumultative
(Opcional) Indica o score do áudio recebido acumuladamente
Elemento Score
Score¶
O elemento score detalha o resultado da verificação biométrica.
Campo
Descrição
Tipo do Campo
utterance_length
Indica o tamanho (em milis) da última interação ou do acumulado
Numérico
decision
Indica a decisão da verificação.
Valores:
accepted
rejected
undecided
verification_score
score biométrico da amostra de áudio
Double