1dabb5110f
docs(help): bring the user guide back in line with the current app The help was written on 2026-10-14 and about forty user-visible changes merged since without touching it, so several pages described controls that no longer exist: Missions still listed four playbooks and a Save step for preferences that now save on each change, the depth editor kept its old names, notifications still had their former switches, and voice input pointed to a microphone button that is not in the composer. Every English page was re-checked claim by claim against the current labels (English UI messages) and behaviour, then the nine translations were updated to match, using each locale's own UI labels. Notable corrections: Missions (Compare two models, autosaving defaults with Apply to / Global / Reset, Subsession nesting depth, prepared hand-offs, retired-task interrupts, the named causes of "Mission Control is unavailable", standalone server support); conversations and history (reasoning/tool durations, token lines adding up the cleanup selection, presets including Nothing, timeline markers following Message content, in-place reveal of long text, Open in session, focus after send, Queue message / Steer now, Retrying); settings (notification routing table and defaults, Stats, Mode, info tips, Server setting badge, localized native menus); shortcuts (72 actions, Clear shortcut, Ctrl/Cmd+K); voice (More actions entries, Save status); files (live Workspace refresh, Show 200 more); OpenCode, install, server and updates (2.1.1 recommended, OpenCode 2 beside an older installation, version card first, private loopback listener for Missions, preview releases offered once all builds are published); providers, integrations, browser, SideCars, desktop and remote pages. Translations also repaired older drift, mainly the project-tab closing passages. The Chat settings table header (Default state, its title, item column, the thinking row and its accessible label) was still English in eight locales; it is now translated so the help can cite what users see. AGENTS.md now asks every PR changing user-visible behavior to update the affected help pages in the same PR, since CI validates structure and links but not whether the text still matches the UI; it also corrects the needs-input notification default. USER_HELP.md no longer claims native menus stay English. Validation: npm run test:help (all ten locales, 25 pages, heading ids unchanged), a full help build, and the i18n and transcript-visibility unit tests.
6.6 KiB
Voice input and playback
Configure speech
- Open Settings → Speech. The Speech card uses an OpenAI-compatible server-side adapter, independently of your conversation's model provider.
- Enter API key, optionally Base URL, Transcription model, Speech model and Default voice.
- If input and output need different services, enable Separate providers for input and output, then fill the input/output key, base URL and model fields.
- Choose Playback mode and Output format, then Save (available while changes are unsaved). Check the status beside the test buttons, Configured, Partially configured or Missing API key, before testing; a failed save shows Save failed.
Speech settings and keys belong to the connected CodeNomad server configuration, not the selected project or OpenCode provider connection. Other clients sharing it use those settings. Saved keys are hidden: a blank key field keeps the saved value; Clear saved key schedules its removal when saved. A direction with neither its own endpoint nor key can use shared settings; a separate endpoint needs its own key, and a separate key needs its endpoint. When changing an endpoint, explicitly supply the intended key and verify the saved configuration; endpoint changes clear the saved key for that slot rather than sending it to a different host.
The backend can also use OPENAI_API_KEY and OPENAI_BASE_URL for shared defaults. Clearing a saved key does not remove an environment-provided credential; change that environment at the backend and restart it if you intend to remove the fallback.
| Setting | Meaning / default |
|---|---|
| Base URL | OpenAI-compatible API root, default https://api.openai.com/v1. Input uses audio/transcriptions; output uses audio/speech. |
| Transcription model / Input model | Model accepted by the STT endpoint; default gpt-4o-mini-transcribe. |
| Speech model / Output model | Model accepted by the TTS endpoint; default gpt-4o-mini-tts. |
| Default voice | Provider voice identifier; default alloy. It is not an OS voice picker. |
| Streaming | Default. Begins playback as audio arrives, when provider and browser support the selected format. |
| Buffered | Waits for the complete audio response before playing. |
| Output format | mp3, wav, opus or aac; default mp3. Compatibility varies by browser/provider. |
These are requests to the configured service, not a guarantee that every compatible endpoint implements every model, voice or format. Failed saving leaves an error; inspect the configuration before making another change.
Test input and output
- Save endpoint, key, model and voice changes first.
- Choose Test input, grant microphone permission, speak, then Stop recording. Check the returned transcription.
- Choose Test playback to hear the sample; Stop sample ends it.
The playback test uses the selected playback mode/format immediately, but endpoint, key, model and voice come from saved settings. Test input does not send a conversation prompt. Tests still send audio/text to the configured speech provider and can incur its charges.
If streaming fails, select Buffered, try mp3, save and retest. “Configured” confirms settings, not successful provider authentication or codec playback. Check endpoint availability from the server host, provider model/voice names and quota before retrying.
Dictate a prompt
- Keep Prompt voice input enabled in Speech (it is on by default).
- In the composer, open More actions, choose Start voice input and allow microphone access on this device.
- When you finish speaking, choose Stop recording and transcribe in the same menu; Transcribing audio shows while it is processed.
- Review and edit the inserted text before sending the prompt normally.
Transcription inserts text at the current selection; it does not automatically submit it to OpenCode. The menu entry appears only when STT is configured and the client supports recording. Recording uses the client device's microphone, even when CodeNomad runs on a remote server.
For a missing entry, check the toggle and STT configuration. For permission errors, allow the microphone in both browser/OS privacy settings. Remote browser recording needs a secure context, normally trusted HTTPS; see Mobile access and Direct remote access. Switching away or closing the composer ends its recording lifecycle; do not rely on unsent audio being recoverable. Your typed draft remains the place to review the result.
Read messages aloud
- Use Speak message on a message, or the same action on a tool call, when TTS is available.
- Use Stop playback on the same control to end it; starting another reading stops the current one.
- Change the saved voice, model, mode or format in Speech for subsequent requests.
Playback uses CodeNomad's text projection, not a narrated screenshot: binary/image bytes and permission receipts are not speech content. It does not run a prompt or change the selected OpenCode model. Browser audio support and provider responses can still prevent playback even when a format is selectable.
For automatic conversation speech, use Enable conversation mode in the composer's More actions menu; it applies to that project tab and is not kept after a reload. While it is on, CodeNomad asks the agent, with each prompt you send, to begin its reply with a short fenced spoken summary. Only that completed block is read, in the active main session; it is not an automatic reading of every reply or subagent. Disable conversation mode stops its queue and no longer asks for the summary. Starting microphone input also stops active conversation speech. The toggle appears with voice input, or while conversation mode is already enabled, and requires working TTS to enable.
Data flow and privacy
Microphone audio travels from your client to the CodeNomad backend, then to the configured STT endpoint. Text selected for synthesis travels through that backend to the configured TTS endpoint; returned audio plays on the client. API keys stay server-side and are not returned as saved values to the settings form.
Use an endpoint you trust with the material being dictated or read. This is not an offline transcription guarantee, and OpenCode credentials do not authorize speech automatically. Stop recording/playback when finished; changing a key or endpoint affects future requests, not data already sent to a provider. See Security before exposing a server to other users.