Troubleshooting¶
Who this is for: admins (event producers).
This page covers the problems you can fix from the browser while using captions. Start with the message shown on the capture page. If you run the software yourself and the service will not start, see Running your own stack troubleshooting. Unfamiliar words are explained in the glossary.
The page asks for a token, or says 401¶
The speech service is protected by a service access token
(CAPTION_API_KEY). Ask the service operator for the token. It is a local
password, not an OpenAI, Google or Gemini key. The page forgets it when you
reload, so you may need to enter it again.
The microphone is unavailable or refused¶
- Allow microphone permission in the browser when it asks, and pick the correct device afterwards. Device names may only appear once permission is granted.
- Open the page from
https://orlocalhost. A remote plainhttp://address is not a secure context, so the browser hides your microphones. - If the browser refuses local-network access, use the capture page your admin provided rather than changing browser security settings.
The wrong input is being used¶
Check the Microphone selector and choose the input you meant. Useful options:
| Situation | What to do |
|---|---|
| You hear nothing captured | Pick a different device; confirm it is not muted. |
| You want another app's audio | Route that audio into an input the browser can select. It is not captured on its own. |
| Captions are duplicated | Do not send the same mixed audio to several producers; give each its own input. |
No captions appear¶
| What you see | What to try |
|---|---|
| Meter moves but no words | Speak for several seconds, choose the language explicitly, and try Quiet speech sensitivity. Voice detection can suppress noise or very quiet audio. |
| Nothing at all | Confirm the page is connected to the speech service; if it is, the service may still be starting. |
| The page will not open | During first start, wait for the model download and warm-up; the first download can take several minutes. |
Captions are wrong¶
Automatic captions mishear names, accents, quiet speech, background noise and
overlapping speakers. Check the source audio, the language and the model, and
rehearse names and overlapping speakers. The faster base preset is not suitable
for the supplied Spanish quality test; use small with human review for
multilingual work.
The translation language is wrong¶
This stack translates into English only. For any other target language you
need a separate translation system. English-only models whose names end in .en
cannot translate at all.
Captions are stuck behind¶
If the buffer keeps growing, the service cannot keep up:
- Stop and drain an unused capture page. Abandoned idle sessions expire after 120 seconds, and each producer needs a different stream.
- Reduce translation work or competing CPU load on the machine.
- Do not increase the buffer to hide a machine that cannot keep up. The app stops capture once buffered audio passes thirty seconds and finishes what it already captured.
- After fixing the cause, choose Retry pending audio to process retained audio.
The relay is disconnected¶
Local captions still work without the relay. If the relay is disconnected, check the network connection and the editor's source room. Delivery through an external relay is not guaranteed, so keep a local fallback in mind.
Still stuck?¶
Give your captioner or admin the exact message from the capture page. For software-level problems, point them to Running your own stack troubleshooting.