Troubleshooting

Voice mode toggles but mic does nothing

Press F7 to enable voice mode, then run /voiceapproval in chat. The browser permission popup appears. Click Allow. Make sure your microphone is actually connected.

If you've denied permission, you'll need to clear the FiveM CEF cache or use /voicemic to switch devices.

Voice mode is on but nothing happens when I talk

Check the server console while speaking. You should see:

[stratis-voice][groq.js] HTTP 200 in XXXms

If you see HTTP 401: your token is wrong or expired. Replace it in server/config.lua.

If you see HTTP 429: you've hit the API rate limit. Lower Config.RateLimit.transcribeMax or upgrade your plan.

If you see no log lines at all: the upload bridge isn't firing. Check the F8 (NUI dev tools) console for [stratis-voice] errors.

Commands fire on the wrong phrase

The matcher uses word-boundary matching with case-insensitive normalization. If "hands up" fires when you say "hands", you've set allowRecognitionInReverse = true and the matcher is treating each word independently. Set it to false for stricter matching.

Whisper transcribes correctly but my action doesn't fire

Check minimumConfidence on the action. Whisper typically returns 0.7-0.95. If you've set the threshold to 0.99, almost nothing will pass. Drop to 0.4 to be permissive.

"could not process file" error

The audio reaching the API is malformed. Usually means the AudioWorklet failed to load. Check the F8 console for errors loading audio-worklet.js.

Cost is higher than expected

Run stratisvoice_quota to see who's using transcription. If one player has hundreds, lower ServerConfig.GroqDailyPerPlayer. If your total is high but distributed, lower ServerConfig.GroqDailyTotal.

Whisper hallucinates words from the prompt on silence

Tighten the VAD: bump Config.STT.energyThresholdMul from 3.5 to 4.5. Now only louder speech triggers transcription.

If players in noisy environments still trigger false positives, you can also raise Config.STT.minUtteranceMs to require longer speech segments.

Microphone picker shows generic labels like "Microphone (xxx12345)"

The browser only labels devices after permission is granted. The first time a player allows the mic, labels are populated. They will appear correctly on the next picker open.

Player keeps getting kicked for blacklisted words

Confidence threshold is too low. Raise Config.MinimumConfidenceForBlacklistedWords to 0.85 or higher. The default 0.80 catches almost all real cases without false positives.

Server log spammed with "Throttled" or "duplicate" messages

Players are pressing the talk key too fast or holding it down repeatedly. This is the rate limit doing its job. The notifications go to debug log only and do not bother the player.