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:

  • enroll

  • verify

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.

Min-Utterances

(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). E o valor máximo é 10.

Max-Utterances

(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 e valor máximo é 10 (valor padrão).

Min-Speech

(Opcional) Define o valor mínimo de tempo de fala para a verificação. É um valor inteiro e o valor mínimo é 1000 (valor padrão) e valor máximo é 120000.

Max-Speech

(Opcional) Define o valor máximo de tempo de fala para a verificação. É um valor inteiro e o valor mínimo é 1000 e valor máximo é 120000 (valor padrão).

Media-Type

(Opcional) Indica o formato da mídia (áudio) a ser enviado.

Valores:

  • application/octet-stream (áudio com cabeçalho em formato suportado)

  • audio/wav;

  • audio/mp3;

  • audio/ogg;

  • audio/flac;

  • audio/raw (padrão);

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.

Min-Utterances

(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).

Max-Utterances

(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).

Min-Speech

(Opcional) Define o valor mínimo de tempo de fala para a verificação. É um valor inteiro e o valor mínimo é 1000 (valor padrão) e valor máximo é 120000.

Max-Speech

(Opcional) Define o valor máximo de tempo de fala para a verificação. É um valor inteiro e o valor mínimo é 1000 e valor máximo é 120000 (valor padrão).

Media-Type

(Opcional) Indica o formato da mídia (áudio) a ser enviado. Valores:

  • application/octet-stream (áudio com cabeçalho em formato suportado)

  • audio/wav;

  • audio/mp3;

  • audio/ogg;

  • audio/flac;

  • audio/raw (padrão);

Start-Input-Timers

(Opcional) Indica se o sistema deve iniciar os temporizadores de início de fala e verificação. Valores:

  • true (padrão)

  • false

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:

  • true

  • false (padrão)

Start-Input-Timers

(Opcional) Indica se o sistema deve iniciar os temporizadores de início de fala e verificação. Valores:

  • true (padrão)

  • false

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:

  • application/octet-stream;

  • audio/wav;

  • audio/mp3;

  • audio/ogg;

  • audio/flac;

  • audio/raw (padrão);

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 seja executada mais de uma vez aparece o erro: 414 - rollback-not-allowed

Para enviar esta mensagem, o estado da sessão deve ser NONE ou IDLE.

Linha Inicial:

SPEAKVERIFY 1.0 VERIFY_ROLLBACK

Headers:

Não há.

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

415

invalid-token

Token é inválido

430

audio-too-long

O audio enviado é maior que 5 minutos

431

insufficient-speech

Tempo de fala é muito curto

432

too-much-speech

O tempo de fala é muito grande

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:

  • PROCESSING

  • ACCEPTED

  • REJECTED

  • UNDECIDED

  • TIMEOUT

  • NO_SPEECH

  • CANCELED

  • FAILURE

Content-Length

Indica o número de bytes do conteúdo

Content-Type

Indica o formato do conteúdo. Valores válidos:

  • application/json

O resultado do reconhecimento é um objeto que contém os seguintes campos:

Verification_result

Campo

Descrição

Tipo do Campo

voiceprint

Informação do resultado da verificação com o voiceprint biométrico

Lista de elementos Voiceprint. Pode haver mais de um elemento em caso de identificação ou multi-verificação

audio_info

Informações do audio

Lista contendo as informações dos áudios utilizados

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

(Obrigatório) Indica o score do áudio acumulado das interações da sessão.

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 (válido tanto para o modo verify quanto para o modo enroll).

Valores:

  • accepted

  • rejected

  • undecided

verification_score

score biométrico da amostra de áudio

Double

Audio_info

Campo

Descrição

Tipo do Campo

audio_duration

Duração do áudio em ms

Numérico

speech duration

Duração de fala do áudio em ms

Numérico

channel

Indica o tipo de canal do qual o audio se originou

String

zeroed_removed

Indica se quadros com amostras zeradas foram removidos

Bool

dtmf_removed

Indica se quadros com DTMF foram removidos

Bool

power

Potência do sinal

Float

dc_level

Nível DC do sinal, que foi removido

Float

clipping_rate

Proporção de quadros do sinal clipados

Float

dynamic_range

Variação do range de amostras do sinal

List

effective_bits

Número de bits efetivamente necessários para codificar o sinal**

Int

effective_bandwidth

Largura de banda efetiva do sinal

Float

amplitude_factor

Fator multiplicativo aplicado ao sinal

Float

lzc_rate

Proporção de quadros do sinal com baixa taxa de cruzamentos por zero.

Float

active_lzc_rate

Idem ao ‘lzc_rate’, mas considerando apenas os quadros de fala do sinal

Float

active_clipping_rate

Idem ao ‘clipping_rate’, mas considerando apenas os quadros de fala do sinal

Float

snr

Relação sinal ruído

Float

Regras de parâmetros

Enquanto o usuário não tiver atingido o min_utterances E o min_speech, o campo DECISION do verification result será UNDECIDED.

Após o usuário atingir o min_speech E o min_utterances e NÃO tiver atingido o max_utterances:

Caso o score da verificação não tenha atingido o MIN_VERIFICATION_SCORE, o campo DECISION do verification result continuará sendo UNDECIDED;

Caso o score da verificação seja maior ou igual ao MIN_VERIFICATION_SCORE, o campo DECISION do verification result será ACCEPTED;

Quando o usuário atingir o max_utterances:

Caso o score da verificação não tenha atingido o MIN_VERIFICATION_SCORE, o campo DECISION do verification result será REJECTED;

Caso o score da verificação seja maior ou igual ao MIN_VERIFICATION_SCORE, o campo DECISION do verification result será ACCEPTED;

Caso o usuário ultrapasse max_utterances ou max_speech, o usuário continuará recebendo os resultados da verificação, sendo o campo DECISION preenchido como REJECTED ou ACCEPTED, a depender do MIN_VERIFICATION_SCORE.

Regras para geração de CDR

Será gerado CDR apenas quando a API retornar sucesso e gerar um resultado no Verification Result.