Repository navigation
FAQ and Troubleshooting
Do I need to install anything on the TeamSpeak server? No. WebSpeak3 connects to any reachable TeamSpeak 3 or TeamSpeak 6 server exactly as a native client would, through the WebSpeak3 gateway. The server doesn't need to be modified, and doesn't need to be run by you.
"Connection failed" / it just hangs on connect.
- Double-check the server address and port.
- If you're self-hosting WebSpeak3, make sure the gateway can actually reach the TeamSpeak server (firewalls, Docker networking).
- Some servers reject connections without a valid identity/UID — WebSpeak3 keeps a persistent identity across sessions automatically, so this is normally not an issue, but a corrupted local identity could cause it. Try creating a fresh identity in Tools → Identities; export the old one first if you want to keep it (see Identities).
Can I connect to more than one server at once? Yes. Use In new tab in the connect dialog: each server gets its own tab inside WebSpeak3 and stays connected while you switch between them.
The address field is a dropdown / greyed out and I can't type a server.
The admin of this instance has limited it to specific servers (ALLOWED_SERVERS), so you can only pick one of those. See Configuration & Environment Variables.
I opened a link and it connected me automatically without asking — what happened?
Someone sent you an auto-connect link (a URL with a ?connect=... parameter), or you're on an instance set up to auto-connect to one server by default. This is intentional — see Auto-Connect Links in the README. If the connection fails, the connect dialog opens prefilled so you can fix it and retry by hand.
My microphone doesn't work / no prompt appears.
See the Audio Settings page — this is almost always either a browser permission that needs resetting, or a non-HTTPS self-hosted deployment (mic access requires a secure context; it's blocked on plain http:// except on localhost).
Nobody can hear me / I can't hear anyone.
- Check Options → Playback for the right output device, and Options → Capture for the right input device.
- Check the voice-activation threshold isn't set so high that you never key up — see Audio Settings.
- Confirm you're not muted/deafened (menu bar icons top-left).
Voice cuts off at the start/end of what I say. Adjust the hangover delay and/or activation threshold — see Audio Settings.
Which browser should I use? Chrome, Edge, and other Chromium-based browsers are the primary target and get the most complete audio/device support. Firefox is fully supported for core client and voice functionality. Safari and Mobile Safari are experimental — the UI works, but audio/microphone behavior is still being validated across devices. See the beta roadmap.
Does it work on mobile? Yes — the layout is responsive on mobile Chromium browsers, with microphone support over HTTPS. Mobile Safari is experimental (see above).
How do I get my own notification sounds in? See Soundpacks & Custom Notification Sounds.
Which formatting works in chat?
TeamSpeak BBCode ([b], [i], [u], [s], [color], [size], [left]/[center]/[right], [list], [hr], [url], [img], [noparse]) and the Markdown TeamSpeak 6 sends (**bold**, *italic*, ~~strike~~, `code`, [label](url), > quotes, lists, # headings). Images are shown as links unless you turn on Options → Application → Load images in chat; it's off by default because loading an image shows your IP address to whoever hosts it.
Can I change how WebSpeak3 looks? Yes — see Creating a Custom Design. You can also just switch to the built-in Nova design in Options → Appearance without writing any CSS.
Where do I find deployment instructions? The main README covers Docker (recommended) and manual installation in detail, including the architecture (browser ↔ gateway ↔ Rust connector ↔ TeamSpeak server).
I'm self-hosting and something doesn't work that works on the official demo/client.
Check that you're serving over HTTPS if you need microphone access from anywhere other than localhost, and that your reverse proxy (if any) passes WebSocket connections through correctly (the gateway uses a WebSocket, not plain HTTP, for the browser connection). Working nginx, Caddy and Traefik configurations are on Running behind a Reverse Proxy.
I restarted/redeployed the gateway and clients briefly dropped, then came back on their own — is that expected?
Yes. On SIGTERM (e.g. docker compose up -d --force-recreate or any other container restart), the gateway gracefully disconnects every live TeamSpeak session first, instead of just killing the process — this avoids the target server briefly rejecting a fast client-side reconnect with ClientTooManyClonesConnected (stale duplicate identity). The browser then auto-reconnects with exponential backoff and resumes the same session. Nothing to configure; this is built in as of v0.12.3-beta.3.
Can I make my instance auto-connect visitors to a specific server, so they don't have to type anything in?
Yes — see Auto-Connect Links in the README. Either send out a ?connect=... share link (works on any deployment, no rebuild), or set DEFAULT_SERVER (and optionally DEFAULT_CHANNEL) on the container so every visitor auto-connects with no link needed at all. See Configuration & Environment Variables.
Can I stop visitors from connecting to servers other than mine?
Yes. Set ALLOWED_SERVERS to your server(s); the gateway refuses everything else. The connect dialog then offers only those servers as a dropdown, or a locked field if there's just one (turn that off with SERVER_PICKER=0). See Configuration & Environment Variables.
My TeamSpeak server is on the same network as the gateway and connecting fails.
The gateway refuses private/LAN addresses by default. Set ALLOW_PRIVATE_TARGETS=1.
Where's the full list of settings? On the Configuration & Environment Variables page.
Please use GitHub Issues. Include your browser and version, operating system, how you're running WebSpeak3 (official client/demo vs. self-hosted), and whether the issue is about voice, microphone access, or just the interface — see the roadmap's feedback section for details.