Skip to main content
Overdeck has two voice features, and they work on their own:
  • Dictation turns your speech into text in the conversation composer.
  • Text-to-speech (TTS) speaks short announcements about agent activity, such as “Work agent started for pan 123” or “pan 123 merged to main”.
You can use either one without the other.

Dictate into the composer

  1. Open a conversation whose session is running.
  2. Click the microphone button at the right of the composer, next to Send. Or press Ctrl+Shift+M (Cmd+Shift+M on macOS), which opens the Voice input panel and starts listening at once.
  3. Click Start if the panel is not listening yet. Pick a microphone in the Mic list first if you do not want the default one.
  4. Speak. The waveform moves and the live transcript appears in the preview box.
  5. Finish with Insert transcript, or click Listening to stop. Click Discard to throw the transcript away.
The panel has two modes: Some limits apply:
  • The microphone button is disabled while the conversation’s session is not running and while a message is being sent.
  • The phone app has no microphone button.
  • Only one voice session runs at a time across the whole dashboard. A second one fails with “Another voice transcription session is already active”. AutoPreso uses the same voice connection, so close it before you dictate.
  • Your browser asks for microphone permission the first time. Browsers allow the microphone only on https:// pages and on localhost.

Choose the speech-to-text provider

Open Settings → Voice. The STT provider setting picks the engine that turns speech into text, for dictation and for AutoPreso. Overdeck saves these settings in ~/.overdeck/voice-settings.json and applies a change to an open voice session right away.

Moonshine needs a sidecar

Moonshine runs as a small sidecar program on the dashboard machine. The sidecar exists only for Linux on x64. pan install builds it when you run it from an Overdeck source checkout and python3 is installed; the first build takes 2 to 3 minutes. Add --skip-moonshine to skip it. If you installed Overdeck with npm or the install script, pan install cannot build the sidecar yet (#5576). Dictation then shows “Moonshine sidecar binary not found”. Choose Google Cloud STT instead. On macOS and Windows, Google Cloud STT is the only provider.

How text-to-speech works

Overdeck components emit a short announcement when something happens: a planning session starts, a work agent finishes, a pull request merges, an agent waits for your input. Issue IDs are rewritten so they read well aloud: PAN-123 becomes “pan 123”. When Enable TTS is on, the dashboard server queues each announcement and sends it to the local Qwen3-TTS daemon. The daemon keeps the Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice model loaded on the GPU, turns the text into speech, and plays it through the default PipeWire output with pw-play. The sound comes from the speakers of the machine that runs the daemon. The browser plays nothing. The daemon needs:
  • Linux on x64.
  • An NVIDIA GPU with CUDA that nvidia-smi can see.
  • PipeWire, for pw-play.

Set up text-to-speech

  1. Install the daemon. Run pan install. On Linux x64 with a CUDA GPU it creates a Python environment for the daemon and downloads PyTorch for CUDA, which is a large download. On other machines it skips this step and says why. Add --skip-tts-daemon to skip it on purpose.
  2. Start the daemon. Run pan tts start. It waits until the daemon answers its health check. You can also click Start daemon in Settings → TTS. The Daemon status badge at the top of that section shows whether the daemon is running.
  3. Check the audio. Run pan tts test. It speaks a test phrase with your System Voice, or with the built-in Vivian preset if you have not chosen one. Pass your own text in quotes to speak something else, and add --status to use the Status Voice.
  4. Save a voice and make it the System Voice. In Settings → TTS, open CustomVoice Presets, select a preset, and click Save Selected Preset…. Then select the saved voice under System Voice. From the terminal, pan tts voices set-default "<name>" does the same, but a running dashboard picks it up only after a restart (see When changes apply).
  5. Turn it on. Switch on Enable TTS. This sets tts.enabled: true in ~/.overdeck/config.yaml.
pan tts test falls back to the Vivian preset, so a working test does not prove that announcements will play. The dashboard speaks nothing until a saved voice is set as the System Voice.

Keep the daemon running

The daemon does not start with the dashboard unless you ask, because loading the model is slow and uses GPU memory.
  • Set tts.daemon.autoStart: true in ~/.overdeck/config.yaml and pan up starts the daemon too.
  • The Overdeck supervisor restarts a crashed daemon, up to 3 times in 10 minutes. It does this when tts.daemon.autoStart is true or when Overdeck started the daemon, and never after you stop it with pan tts stop. Set OVERDECK_TTS_WATCHDOG=0 to turn this off.
  • pan tts install-systemd writes the user unit ~/.config/systemd/user/overdeck-qwen-tts.service. Turn it on with systemctl --user enable --now overdeck-qwen-tts.service.
  • pan tts status shows the daemon’s state, pan tts restart restarts it, and pan tts stop stops it. See pan tts for every option.

Voices

Overdeck keeps your saved voices in ~/.overdeck/tts-voices.json. Settings → TTS lists them under My Saved Voices. A saved voice has one of three kinds:

System Voice and Status Voice

Each announcement has a priority. Merges, merge failures, auto-merge changes, finalized plans and requests for your input are high priority. Planning sessions and work agents starting or finishing, and the dashboard starting or stopping, are status priority.
  • The System Voice (tts.voice) speaks high-priority announcements.
  • The Status Voice (tts.statusVoice) speaks status announcements. If you leave it unset, the System Voice speaks them too.
  • A voice-map entry for the announcement’s event type overrides both. See Control what is spoken.

Manage voices from the terminal

set-default sets the System Voice. The Status Voice has no terminal command; set it in Settings → TTS or with tts.statusVoice.

Control what is spoken

These settings are in Settings → TTS and in the tts block of ~/.overdeck/config.yaml:

Voices and wording per event type

Every announcement carries an event type. Map an event type to a saved voice with tts.voiceMap, or replace its words with tts.utteranceTemplates. A template can include {issueId}, which becomes the issue ID. These are the event types Overdeck emits: Set these with pan tts voices map <event> <name> or in the config file:
voice and the voiceMap values are voice IDs, which pan tts voices show "<name>" prints. The Voice Map and Utterance Templates controls in Settings → TTS offer event keys that Overdeck does not emit yet (#5575), so set these two from the terminal or the config file.

When changes apply

The dashboard reads the tts settings when it starts and each time you save a change in Settings. A change made with pan tts voices set-default, pan tts voices map or by editing ~/.overdeck/config.yaml reaches a running dashboard only after you restart it with pan restart. New saved voices work at once, because the dashboard reads ~/.overdeck/tts-voices.json for each announcement.

Spoken summaries

The TTS summarizer batches recent activity log entries and asks an OpenAI model for a one-sentence spoken summary. It emits the result as an announcement with the source tts-summarizer. It needs all of these:
  • tts.summarizer.enabled: true in ~/.overdeck/config.yaml. The dashboard reads this when it starts.
  • TTS activity narration switched on in Settings → Background AI, and Low-cost mode off.
  • An OpenAI API key, from api_keys.openai in the config file or the OPENAI_API_KEY environment variable.
tts.summarizer.model picks the model (default gpt-5.4-mini), and tts.summarizer.batch_window_seconds sets how often it summarizes (default 15). Model presets do not change this model; see Model presets.

Speak announcements somewhere else

An external sidecar is any program that reads Overdeck’s announcements and speaks them itself, for example on another machine or with another TTS engine. Overdeck does not ship one. Two interfaces let you build one. The event stream. GET /events/stream?types=activity.tts on the dashboard streams each announcement as Server-Sent Events. Each event’s payload carries utterance, priority (0 and 1 are high priority, 2 is status), issueId, source and eventType. activity.tts is part of the public catalog that GET /events/version returns.
A process on the same machine can connect without a credential, unless you set OVERDECK_EVENTS_TOKEN. From another machine, use a scoped token: pan token create <name> --scopes read:events. See Remote access. The daemon’s speak endpoint. A sidecar can also play text through the Overdeck daemon with POST http://127.0.0.1:8787/speak and a JSON body such as {"text": "Build is green", "voice": "Vivian"}. Every POST must carry the daemon token from ~/.overdeck/secrets/qwen-tts.token in an X-Overdeck-TTS-Token header or as Authorization: Bearer <token>; without it the daemon answers 401. The daemon holds at most 6 waiting requests and answers 429 when its queue is full. tts.daemonHost and tts.daemonPort (default 127.0.0.1 and 8787) set the address the daemon listens on and the dashboard sends to. If your sidecar speaks on the same machine as the dashboard, leave Enable TTS off so you do not hear each announcement twice.

Troubleshooting

  • Nothing is spoken. Run pan tts status, and check the Daemon status badge in Settings → TTS. Then check that Enable TTS is on and a saved voice is set as the System Voice.
  • A clone voice stopped working. Clones made with an older model are rejected. Make the clone again from its VoiceDesign description.
  • Dictation says “Moonshine sidecar binary not found”. Switch STT provider to Google Cloud STT, or build the sidecar from a source checkout with npm run build:sidecar.
  • Dictation says “Another voice transcription session is already active”. Close the other voice panel or the AutoPreso page, then try again.

Known issues

  • Dictation sends each sentence to AutoPreso too. When AutoPreso is not open, the panel shows “AutoPreso transcript processing is not live”. Dictation through Google Cloud STT can also be transcribed at the wrong speed. Both are tracked in #5204.
  • Rate has no effect (#5574).
  • The Settings Voice Map and Utterance Templates list event keys that are never emitted (#5575).
  • npm installs cannot build the Moonshine sidecar (#5576).
  • Input device, Output device and Voice volume in Settings → Voice are not used (#5577).

Get help