Soniox v4 to v5 migration guide for voice-input apps

soniox-v4-to-v5-migration-guide.md

Soniox v4 → v5 Migration Guide for Voice-Input Apps

Short version: do not migrate by only changing the model name. For multilingual or accented speakers, the biggest risk is strict language gating.

Recommended config

{
  "model": "stt-rt-v5",
  "sample_rate": 16000,
  "num_channels": 1,
  "audio_format": "pcm_s16le",
  "language_hints": ["vi", "en"]
}

Key point: keep language_hints as a soft bias, but remove language_hints_strict unless you have proven it helps your exact users.

Why

In our voice-input app, the first v5 trial sounded much worse for mixed Vietnamese/English coder speech. The problem was not v5 itself; it was sending multilingual hints with strict gating:

{
  "model": "stt-rt-v5",
  "language_hints": ["vi", "en"],
  "language_hints_strict": true
}

After switching to v5 while removing language_hints_strict, quality became dramatically better.

Migration checklist

1. Commit your current v4 config first so rollback is one command.
2. Change only the model to stt-rt-v5.
3. Keep useful soft language_hints for expected languages.
4. Remove language_hints_strict for mixed-language / non-native-accent users.
5. Keep your custom vocabulary/context terms unchanged at first.
6. Log stt_model with each transcript so you can compare v4 vs v5.
7. Test with real user speech, not just clean English samples.
8. Keep a fast rollback path to v4 until live samples pass.

Test phrases to include

Use samples that match real usage:

• Mixed native + English technical terms.
• Names of tools, repos, agents, files, and acronyms.
• Long rambling commands with corrections and filler words.
• Non-native pronunciation of English technical words.
• Domain-specific vocabulary that generic dictation usually misses.

Rule of thumb

For multilingual voice-input software, language_hints should guide the model; language_hints_strict can accidentally fight the speaker. Start soft, measure, then only add strict mode if your real transcripts prove it is better.