enroll¶

Efetua um cadastro biométrico com um ou mais áudios do mesmo locutor.

Requisição¶

A requisição deve estar estruturada como multipart (Content-Type definido como multipart/form-data). O primeiro boundary, denominado enroll, deve conter um objeto JSON (application/json) com os seguintes campos:

repository_uri

string URL do repositório biométrico.

scenario

string Identificador único do cenário, incluindo o modelo. Campo obrigatório.

user_id

string Identificador único de usuário, para atualizar um voiceprint existente. Se fornecido, mas nenhum voiceprint existir no cenário indicado, um erro será retornado. Se omitido, um novo usuário será criado.

media_type

string Formato do áudio que será fornecido. Os valores válidos para este campo são:

auto: O formato é detectado automaticamente através do cabeçalho presente no conteúdo binário. Os formatos suportados são: FLAC, Waveform (cabeçalho RIFF), MPEG-Layer 3 (MP3) e Ogg Vorbis.
pcm/8000/16/mono: PCM Linear 8kHz 16bps Mono
pcm/16000/16/mono: PCM Linear 16kHz 16bps Mono

min_enrollment_score

float Limiar de aceitação ao comparar os áudios fornecidos no cadastro. O valor deve ser de -1.0 até 1.0. Se o score calculado durante o cadastro for maior ou igual a este limiar, o voiceprint do usuário será criado ou atualizado. Caso contrário a operação de cadastro resultará em erro. Para mais informações, consulte o campo score na resposta.

configuration

object Parâmetros de configuração da operação biométrica. Todos os campos são opcionais.

split_mode: string Define a forma na qual o serviço deve cortar os áudios de entrada para obter as frases. Para mais detalhes, consulte a seção Modos de corte. Os valores válidos são AUTO, NONE e UTTERANCE para a interface REST. Se AUTO for informado o serviço decide qual modo de corte será utilizado. O valor padrão é AUTO.
min_speech: integer Duração mínima, em milissegundos, de fala. O valor deve ser de 1000 até 120000. O valor padrão é 1000. Se esse limiar não for atingido, a operação encerra com erro.

max_speech: integer Duração máxima, em milissegundos, de fala. O valor deve ser de 1000 até 120000. O valor padrão é 120000. Se esse limiar for ultrapassado, o comportamento resultante é definido por max_contraint_behavior.

min_utterances: integer Define o número mínimo de frases que devem ser transmitidas para que o serviço comece a gerar uma decisão. O serviço não irá gerar uma decisão até que o número mínimo de frases seja atingido. O valor deve ser de 1 até 20. O valor padrão é 1. Se esse limiar não for atingido, a operação encerra com erro.

max_utterances: integer Define o número máximo de frases que o serviço aceitará. Ao atingir esse limite, o serviço responderá a decisão com algum valor que não seja «undecided». O valor deve ser de 1 até 20, e deve ser maior ou igual ao valor de min_utterances. O valor padrão é o mesmo valor de min_utterances. Se esse limiar for ultrapassado, o comportamento resultante é definido por max_contraint_behavior.

max_constraint_behavior

string Indica o comportamento quando o valor definido max_speech e/ou max_utterances for ultrapassado. O valor padrão é trim. Os valores válidos são:

trim - Descarta áudio para que o total aproxime-se do limite superior. O áudio pode ser cortado em algum silêncio. O processo continua normalmente (sem erro);
abort - Aborta todo o processo e retorna um erro para o usuário.

logging_tag

string Tag a ser inserida nos logs do serviço para rastreio de requisições. O valor deve ser uma string contendo até 32 caracteres e os caracteres válidos são: letras (não acentuadas), números, traços (-) e sublinhas (_).

account_tag

string Tag a ser inserida no registro de tarifação, permitindo segregar o consumo em categorias. O valor deve ser uma string contendo até 32 caracteres e os caracteres válidos são: letras (não acentuadas), números, traços (-) e sublinhas (_).

Os demais boundaries devem conter, cada um deles, um áudio a ser utilizado na operação biométrica. São permitidos o envio de até 10 áudios, cada qual com tamanho de até 5MB. O formato dos áudios depende do valor indicado em media_type, no primeiro boundary. Não é permitido misturar áudios PCM Linear com áudios contendo cabeçalho.

Resposta¶

A resposta é um objeto JSON contendo os seguintes campos:

transaction_id: string Identificador único da transação.
user_id: string Identificador único do usuário. Se a operação foi de atualização, este identificador será igual ao informado no campo homônimo da requisição.
user_updated: bool Indica se a operação alterou um usuário existente (true) ou se foi criado um novo usuário na base (false).
voiceprint_updated: bool Indica se a operação atualizou um voiceprint existente de um usuário (true) ou se foi criado um novo voiceprint (false). Esse campo poderá ser true somente se a operação atualizou um usuário (i.e. o campo user_updated possui o valor true).
score: float Score de cadastro, resultante da comparação entre os áudios fornecidos no cadastro. No caso de uma atualização, também considera o voiceprint anterior. Este valor pode ser utilizado para detectar casos onde áudios de diferentes locutores são fornecidos. Para mais informações, consulte o campo min_enrollment_score da requisição.

utterances

array Lista de objetos contendo informações sobre as frases identificadas nos áudios fornecidos pelo usuário.

audio_counter
integer Contador de áudios, indicando o áudio de entrada correspondente. O primeiro áudio de entrada é representado pelo valor 0 (zero). Quando é utilizado o modo de corte S_UTTERANCE ou S_FIXED, podem existir várias frases com o mesmo valor para esse campo.

total_duration
integer Duração total da frase, em milissegundos.

speech_duration
integer Quantidade de fala na frase, em milissegundos.

rejected
bool Indica se a frase foi rejeitada (true) ou não (false) durante o processamento da operação.

rejected_cause
string Caso o valor do campo rejected seja true, este campo indica o motivo pelo qual a frase foi rejeitada.

start_time
float Marcação temporal do início da fala, em segundos, relativo ao áudio de entrada.

end_time
float Marcação temporal do fim da fala, em segundos, relativo ao áudio de entrada.

Exemplo 1¶

Chamada REST enviando o audio via multipart:

 curl --request POST \
--url http://speechd.cpqd.com.br/bio/bmt/rest/v3/enroll \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--cookie dtCookie=<cookie> \
--form 'enroll={
      "repository_uri": "10.245.15.14:9090",
      "scenario": "exemplo1@sr8khz",

      "configuration": {
              "split_mode": "utterance",
              "min_speech": 1000,
              "max_speech": 120000,
              "min_utterances": 1,
              "max_utterances": 20,
              "max_constraint_behavior": "trim",
              "logging_tag": "exemplo_ENROLL",
              "account_tag":"ACCOUNT_exemplo_ENROLL"
      }
  }
  '\
  --form audio=@<path-to-file>/audio1.wav

Exemplo 2¶

Chamada REST enviando o audio via multipart:

 curl --request POST \
--url http://speechd.cpqd.com.br/bio/bmt/rest/v3/enroll \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: multipart/form-data' \
--cookie dtCookie=<cookie> \
--form 'enroll={
      "repository_uri": "10.245.15.14:9090",
      "scenario": "exemplo2@sr8khz",
      "min_enrollment_score": -1,

      "configuration": {
            "split_mode": "auto",
             "min_speech":"1000",
             "max_speech":"120000"
             "max_utterances": "20",
             "max_constraint_behavior": "abort",
             "logging_tag": "exemplo_ENROLL_REST",
             "account_tag": "exemplo_ACCOUNT_Enroll"
      }
  }
  ' \
  --form 'audio=@C:\IC\BIOMETRIA\AUDIOS\diversos\Alfredo_08_d6101_s3510.wav' \
  --form 'audio=@C:\IC\BIOMETRIA\AUDIOS\diversos\Alfredo_09_d4712_s4250.wav'

Exemplo de resposta - 1:

{
    "transaction_id": "170952487879051776",
    "user_id": "170952489489664000",
    "user_updated": false,
    "voiceprint_updated": false,
    "utterances": [
        {
            "audio_counter": 0,
            "total_duration": 7251,
            "speech_duration": 4360,
            "rejected": false,
            "start_time": 1.46,
            "end_time": 6.37
        }
    ]
}

Exemplo de resposta - 2 :

{
	"transaction_id": "204211614264595968",
	"user_id": "204211620405053440",
	"user_updated": false,
	"voiceprint_updated": false,
	"score": 0.57035404,
	"utterances": [
		{
			"audio_counter": 0,
			"total_duration": 6101,
			"speech_duration": 3510,
			"rejected": false,
			"start_time": 0.0,
			"end_time": 6.101375
		},
		{
			"audio_counter": 1,
			"total_duration": 4713,
			"speech_duration": 4250,
			"rejected": false,
			"start_time": 0.0,
			"end_time": 4.7129374
		}
	]
}