Quality scoring - VoiceMark

Before storing a voiceprint, /v1/enroll runs a 3-layer quality gate. If any layer fails, the request returns a 400 error. If all pass, quality_score indicates how strong the enrollment was.

Three-layer gate

Check	Minimum	Error code
Duration	≥ 2.0 seconds	`AUDIO_TOO_SHORT`
RMS energy	≥ 0.004	`AUDIO_TOO_QUIET`
Embedding norm	≥ 0.30	`LOW_VOICE_SIGNAL`

Quality score

quality_score is a 0–1 composite returned when all three checks pass:

quality_score = min(1, duration_s / 5.0) × min(1, rms / 0.02)

Score	Meaning	Action
0.8–1.0	Excellent	Proceed
0.4–0.8	Acceptable	Proceed; optionally prompt improvement
< 0.4	Poor	Prompt re-record

UI guidance

const enroll = await vm.enroll(blob, userId);

if (enroll.quality_score < 0.4) {
  showMessage("Recording too quiet — move closer to the mic and try again.");
} else if (enroll.quality_score < 0.8) {
  showMessage("Good. For best results, record 5+ seconds in a quiet space.");
} else {
  showMessage("Voice enrolled successfully.");
}

Why it matters

A low-quality voiceprint raises the false rejection rate on future verifications. Users enrolled in noisy environments or with very short clips are more likely to fail verification later, even when their voice is genuine.

⌘I