Voice Biometrics Configuration Reference
A voice biometrics deployment is a stream of risk decisions. Every verification weighs the cost of letting an impostor in against the cost of turning away a genuine customer, and every enrollment decides how much audio quality you demand before you trust a voiceprint. Voice biometric configurations are where you set those trade-offs: the score thresholds that accept or reject a speaker, the audio quality gates, the passphrase check, and whether the platform defends against recorded audio. This reference lists every setting in the enrollment, verification, and engine configurations, with what it does and the values in the standard sample configuration.
The values shown are examples, not guaranteed defaults. They come from the sample configuration for the US English “My voice is my password” model. Use them as a starting point, check the values in your own deployment, and test any change against representative audio before you use it in production.
This article covers active voice biometrics, where the speaker repeats a fixed or prompted phrase. For the concepts and the API call flow, see Voice Biometrics Concepts and Integration Flows. For an overview of all the voice biometrics articles, see Biometrics Functional Overview & API Integration. For the terms used here, such as false accept rate, false reject rate, liveness detection, and playback detection, see the Product Glossary.
How configurations work
Configurations are divided into three categories. Each configuration has a configuration symbol, a GUID that identifies it. Your application supplies the enrollment symbol when it enrolls a speaker and the verification symbol when it verifies one, so the thresholds in that configuration apply to that session.
| Category | Type value | What it controls |
|---|---|---|
| Enrollment | BiometricEnrollment | How a voiceprint is created: how many samples are required, how many quality errors are tolerated, and the session timeout. |
| Verification | BiometricVerification | How a speaker is accepted or rejected: the decision policy and its score thresholds, plus liveness thresholds. |
| Engine | BiometricEngine | The model and audio quality gates, anti-spoofing, the passphrase check, and the engine settings shared by enrollments and verifications. |
Settings are organized into groups under Attributes (for example Service, Policy, and Session). This article writes a setting’s location as a path, such as Attributes > Policy > SuccessThreshold. DialogTimeout can be set on all three kinds of configuration. A value set on an enrollment or verification configuration overrides the engine’s.
Reading and changing configurations
Voice biometric configurations are edited as JSON in the Deployment Portal, by clicking the configuration button. See the Portal Help Guide and Portals Overview for the portals.
The Management API provides the same access for scripted or restricted environments. Requests carry the x-deployment-id, x-operator-id, and x-scopes headers.
| Endpoint | Purpose |
|---|---|
GET /Management/ConfigurationSettings/BiometricConfiguration | Returns the deployment’s biometric configuration settings as JSON. Takes a configurationName query parameter. |
POST /Management/ConfigurationSettings/BiometricConfiguration | Updates the deployment’s biometric configuration settings. Takes a configurationName query parameter. |
POST /Management/ConfigurationSettings/Configuration/Filter | Returns a list of configurations that match a filter (name, configuration type, language, whether to include disabled or only global configurations). |
POST /Management/ConfigurationSettings/Configuration/{configurationSymbol} | Returns the detailed properties of one configuration. |
POST /Management/ConfigurationSettings/Configuration/Create | Creates a configuration. |
POST /Management/ConfigurationSettings/Configuration/Update | Updates one attribute of an existing configuration. The request names the configuration symbol, the attribute, its old value, and its new value. |
Settings common to every configuration
| Setting | Description | Example value |
|---|---|---|
ConfigurationSymbol | The GUID that identifies the configuration. Your application supplies it so the configured thresholds apply. | A GUID, for example a4521d62-fa34-488e-a127-94be59b1ac58 |
Type | The configuration type: BiometricEnrollment or BiometricVerification. | BiometricEnrollment |
Name | The name of the configuration set. It indicates the model being used. | vba_mvimp_en_US-2.1.13 - Enrollment |
Description | A free-text description of the configuration. | Enrollment for (My voice is my password) [en-US] |
IsGlobal | Whether the configuration can be used by more than one deployment. | false |
LanguageId | A numeric language identifier. The configuration is used for enrollments and verifications in that language. | 1033 (US English) |
Enrollment configuration
Enrollment settings live in Attributes > Service.
| Setting | Description | Example value |
|---|---|---|
DialogTimeout | The session timeout in seconds. Set at the enrollment level, it overrides the engine setting. | 300 |
MaxQualityRejections | The maximum number of times a speech quality error may occur before the session is rejected. | 2 |
TrainUtterances | The minimum number of audio samples required to create a voiceprint. | 3 |
LogAllScores | Whether to supply all detailed scores in the response message. | true |
Verification configuration
Service settings
These settings live in Attributes > Service.
| Setting | Description | Example value |
|---|---|---|
DialogTimeout | The session timeout in seconds. Set at the verification level, it overrides the engine setting. | 300 |
MaxQualityRejections | The maximum number of times speech quality errors may occur before the session is rejected. | 2 |
LogAllScores | Whether to supply all detailed scores in the response message. | true |
Policy settings
The policy decides when a speaker is accepted, rejected, or asked for more audio. These settings live in Attributes > Policy.
| Setting | Description | Example value |
|---|---|---|
SuccessThreshold | The score needed to be accepted immediately. | 0.9 |
FailureThreshold | Scores at or below this value cause immediate rejection. | 0.35 |
CompletionThreshold | The average score that must be achieved at the end of the verification. | 0.65 |
MaxBiometricSamples | The maximum number of biometric samples allowed before a decision must be made. | 1 |
MinBiometricSamples | The minimum number of biometric samples the speaker must repeat. With a value of 1, an immediate acceptance or rejection is possible. When it equals MaxBiometricSamples, the speaker always provides every sample. A value of 0 disables early decisions, so the speaker also performs all prompts. | 1 |
CompletionThresholdRandom1 | The threshold for the first random phrase, used for liveness detection. | 0.4 |
CompletionThresholdRandom2 | The threshold for the second random phrase, used for liveness detection. | 0.6 |
How the thresholds decide a result
| Consolidated score | Result |
|---|---|
Equal to or above SuccessThreshold | Successful |
Equal to or below FailureThreshold | Rejected |
| Between the two thresholds | InProgress. The system prompts for more audio until the maximum number of samples is reached. It then compares the result with CompletionThreshold to decide between Successful and Rejected. |
With the sample values, a score between 0.35 and 0.9 is not decided immediately. Because the sample maximum is one sample, CompletionThreshold then decides the outcome after that sample. If you raise MaxBiometricSamples, the speaker is asked for more phrases before the completion threshold applies.
Thresholds are a risk decision. Raising SuccessThreshold or CompletionThreshold reduces the false accept rate at the cost of a higher false reject rate and more re-prompts. Lowering them does the opposite. Set them from the risk of the transaction you are protecting, and revisit them against live results.
Engine configuration
Service settings
| Setting | Description | Example value |
|---|---|---|
DialogTimeout | The session timeout in seconds, applied to enrollments and verifications. A value set on an enrollment or verification configuration overrides it. | 300 |
Phrase | The phrase used for enrollment and verification. | My voice is my password |
Audio quality and anti-spoofing settings
These settings live in Attributes > Session. They decide whether a sample is good enough to use and whether it is a recording. A sample that fails a quality gate is reported with a status hint, so your application can ask the speaker to try again, and repeated failures count toward MaxQualityRejections.
| Setting | Description | Example value | Related status hint |
|---|---|---|---|
ConsistencyThreshold | The threshold used to compare the consistency between enrollment audio segments. | 0.610977 | InconsistentRepetition |
MaxClippedSamples | The maximum number of frames that may be clipped. Clipping can be caused by noise or by audio that is too loud. | 200 | TooManySamplesClipped |
MaxTooLoudDuration | A quality measure for loudness. Audio that is too loud for longer than this threshold is rejected. Measured in seconds. | 0.025 | VolumeTooHigh |
MaxUtteranceDuration | The maximum audio length for each audio sample. | 10 | SampleTooLong |
MinLoudEnoughDuration | A quality measure that ensures the audio is not too soft or silent. Audio that is too soft for longer than this threshold is rejected. Measured in seconds. | 0.1 | VolumeTooLow |
MinSignalToNoiseRatio | The minimum acceptable signal-to-noise ratio, meaning the voice must be louder than the background noise. | 15 | TooMuchNoise |
MinSpeechDuration | The minimum net audio duration for speech samples. | 1 | LengthTooShort |
PlaybackThreshold | The threshold that determines whether an audio sample is a recording. | 0.84 | PlaybackDetected |
PlaybackDetection | Enables the playback detection anti-spoofing measure. | false | PlaybackDetected |
PlaybackHashSamples | The number of enrollment and verification audio samples stored per speaker for playback matching. | 10 | – |
Playback detection is off in the sample configuration. A passphrase system is exposed to replay of recorded audio. Playback detection identifies audio that has already been received and processed, on the premise that a person never repeats a passphrase in exactly the same way. If recorded-voice replay is a realistic attack against your application, enable PlaybackDetection and size PlaybackHashSamples for your speakers. Note that, with it enabled, resubmitting the same recording during testing is reported as PlaybackDetected. For how the layered anti-fraud controls fit together, see Active Voice Biometrics Product Information.
Passphrase validation (ASR) settings
The engine can use the platform’s ASR to confirm what was said, independent of who said it, so a speaker who plays unrelated audio does not pass. These settings live in Attributes > Asr.
| Setting | Description | Example value |
|---|---|---|
Grammar | The grammar used to validate the fixed passphrase. See the example below. | An ABNF grammar |
IsEnabled | Enables text validation of the fixed and random passphrases using the ASR engine. | true |
Language | The language applied in the text validation engine. | en |
MinConfidence | The minimum confidence the ASR engine applies to validate the text spoken. | 0 |
The grammar is stored as a single string with line breaks. Written out, the sample grammar is:
| #ABNF 1.0 UTF-8; language en; mode voice; tag-format <lumenvox/1.0>; root $all; $main_phrase = {0}; $phrase = $GARBAGE $main_phrase $GARBAGE; $all = $phrase | $GARBAGE; |
The grammar accepts the passphrase surrounded by any other speech, or garbage alone. {0} marks where the passphrase is inserted.
The ASR text validation also has its own audio settings. These live in Attributes > Asr > Session Settings.
| Setting | Description | Example value |
|---|---|---|
AUDIO_CONSUME_MODE | The ASR mode used for text validation (group INTERACTION_AUDIO_CONSUME). | “BATCH” |
AUDIO_CONSUME_START_MODE | The ASR processing start mode (group INTERACTION_AUDIO_CONSUME). | “STREAM_BEGIN” |
USE_VAD | For text validation, whether the software should automatically detect when the audio is complete (group INTERACTION_VAD). | “false” |
Biometric and liveness engines
Two engine blocks configure the scoring models. EngineVB is the engine used for fixed-phrase validation. EngineLD is the engine used for random-phrase liveness detection. Each has the same set of settings.
| Setting | Description | Example value |
|---|---|---|
UseSNorm | Whether score normalization is applied. | true for EngineVB, false for EngineLD |
SNormPath | The file path to the cohort binary file. | See below |
DnnModelPath | The file path to the base DNN binary model. | See below |
BackendModelPath | The file path to the scoring backend binary model. | See below |
EngineConfiguration > data | Internal parameters for the engine. Leave these unchanged. | A data string |
In the sample configuration, the paths for the English model are:
| SNormPath (both engines): /etc/lumenvox/Lang/vb-active/vba_mvimp_en_US-2.1.13/vba_mvimp_en_US_cohort-2.1.0.bin DnnModelPath (both engines): /etc/lumenvox/Lang/vb-active/vba_mvimp_en_US-2.1.13/vba_mvimp_en_US_dnn-2.1.0.bin BackendModelPath (EngineVB): /etc/lumenvox/Lang/vb-active/vba_mvimp_en_US-2.1.13/vba_mvimp_en_US_backend-2.1.0.bin BackendModelPath (EngineLD): /etc/lumenvox/Lang/vb-active/vba_mvimp_en_US-2.1.13/vba_mvimp_en_US_liveness_backend-2.1.0.bin |
The model paths and version numbers depend on the voice biometric model installed in your deployment. Do not change them unless you are installing or switching models.
Troubleshooting
| Symptom | Likely cause and fix |
|---|---|
| Speakers are repeatedly asked to try again, then rejected | One of the quality gates is too strict for your audio, or the telephony path is poor. Check the statusHint your application receives, compare it with the audio quality settings, and review MaxQualityRejections. |
Enrollment keeps reporting InconsistentRepetition | The enrollment samples are not consistent with each other. Make sure the speaker repeats the same phrase and that the prompt does not change during enrollment. Review ConsistencyThreshold only after that. |
PlaybackDetected appears for genuine users or during testing | Playback detection flags audio that has already been processed. During testing, do not resubmit the same recording. For production, check how your application captures and retries audio. |
| Verification keeps prompting for more phrases | The score is between FailureThreshold and SuccessThreshold, so more audio is requested until MaxBiometricSamples is reached. Review the thresholds and the minimum and maximum sample counts. |
| Sessions end before the speaker finishes | The session reached DialogTimeout. Check the value on the enrollment or verification configuration, which overrides the engine value. |
| A speaker is rejected after saying the wrong or an unexpected phrase | Passphrase validation is enabled. Check Asr > IsEnabled, the Phrase, the grammar, and MinConfidence. |
| No configuration is found for a language | Each configuration has a LanguageId. Use the configuration symbol for the language the speaker uses. |
Related Articles
- Voice Biometrics Concepts and Integration Flows
- Biometrics Functional Overview & API Integration
- Active Voice Biometrics Product Information
- Active Voice Biometrics Product Overview
- Active Voice Biometrics Product Architecture
- Product Glossary
- Capacity Private Cloud Data Dictionary
- Portal Help Guide
- Portals Overview