Voice: dictate and hear replies
Use the microphone on the chat input to dictate instead of typing. Speech is an optional service, separate from your chat model: selecting a chat provider or signing in with a ChatGPT subscription does not configure audio or pay for speech usage.
Open Voice keyboard shortcut
Press Ctrl+Shift+V (or Cmd+Shift+V on macOS) to open voice for the current conversation in your selected docked (minimized control panel) or full-screen view. This is a fixed shortcut: the minimized panel's voice settings do not offer a keyboard-binding editor or an option to disable it.
The shortcut works outside text fields and modal dialogs, when voice input is available and voice is not already open. It does not close or toggle an active voice session. In push-to-talk mode, Space remains the recording key; Open Voice only opens the voice controls.
Set up speech in Community
- Open your configuration file. For a normal Community user-home installation, edit
$CODUMENTOR_HOME/config.yaml(by default~/.codumentor/config.yaml). See Community setup if you use a project configuration instead. - Add or merge this top-level block, then restart Codumentor:
``yaml``
speech:
enabled: true
base_url: "https://api.openai.com/v1"
allow_user_api_key: true
user_api_key_secret: speech_api_key
enabled: true is required: speech defaults to off. The endpoint must support the configured audio models; the defaults are whisper-1 for transcription and tts-1 / alloy for spoken replies. Other OpenAI-compatible providers may need different models or a different base_url.
- Open Settings → Extensions → User Secrets and add
speech_api_key, with your speech provider's actual API key as its value. Host-only is recommended: the host can use it for speech without exposing it to the agent or shell-tool bindings. Ordinary stored secrets also work. Do not enter a${secret:…}placeholder as the value. - Return to a conversation and try the microphone. Allow microphone access when your browser asks.
The User Secrets plugin is enabled in the personal default configuration for newly generated configurations. This does not add it to existing configurations. If the Settings pane is missing, enable User Secrets in your existing plugin list, then restart:
plugins:
# Keep your other plugin entries.
- module: codumentor.plugins.user_secrets
class: UserSecretsPlugin
priority: 3
args:
enabled: true
Your account also needs user_secrets:manage permission (included in the power_user and admin roles). On a managed server, ask the deployment administrator rather than editing the deployment configuration.
Which key is used?
A usable deployment speech.api_key wins. For example, a deployment can set api_key: "${OPENAI_API_KEY}" and supply that environment variable to the server. Only when no usable deployment key is available does the web speech service fall back to the authenticated user's own stored secret, subject to speech.allow_user_api_key and the permission above. It does not borrow another user's key. A provider rejecting a deployment key does not trigger a retry with your personal key.
allow_user_api_keydefaults totruein Community,falsein Enterprise; administrators can override it explicitly.user_api_key_secretdefaults tospeech_api_key. If the deployment configuration changes it, save your key under that exact name.- Speech must still be explicitly enabled for the personal-key fallback. Saving a key does not turn it on.
This is a dedicated speech credential policy, not new support for resolving arbitrary ${secret:…} placeholders outside agent turns. Leave speech.api_key unset for the personal-key setup above. Telegram voice keeps its own credential semantics: this new web fallback, including Host-only speech keys, does not enable Telegram voice.
Choose a voice feature
| Feature | What it needs |
|---|---|
| Push to talk: hold the chat microphone to dictate one message | Configured, enabled speech only; no voice_mode plugin required. |
| Read aloud: play an assistant reply | Enabled speech and the Read Aloud plugin. |
| Live voice: realtime spoken conversation | The Voice Mode plugin enabled, its live.enabled: true, and a provider/key supporting the live model. Optional advanced setup, not needed for dictation. |
Tap the microphone to open the Voice panel; hold it for push to talk. You can still type while voice is unavailable. Push-to-talk is independent of hands-free. Hands-free is optional and requires the enabled Voice Mode plugin; it is not needed for dictation or read-aloud. Advanced Voice Mode configuration is documented in the plugin catalog.
Before voice is set up: browser dictation
The chat input has a single microphone. If voice cannot run yet (no speech key, or no live voice), the microphone opens a small Set up voice mode panel instead of the voice controls. The panel shows what is missing, with Open User Secrets and the setup guide. On desktop browsers that support it, the panel also offers Use browser dictation: your browser types what you say into the text box. Your browser's speech service handles the audio, not Codumentor.
This choice is remembered on the device. After that, the microphone (labeled Dictate (browser)) starts dictation directly. The dictation panel keeps a Set up voice mode link, where you can also turn the choice off. Once voice is set up, the remembered choice is dropped and the microphone opens voice again. On phones, the panel offers only setup, since the phone keyboard already has dictation.
Cost, privacy and browser requirements
- Speech usage is billed by the audio provider associated with the selected key, separately from chat-model usage. A deployment key charges the deployment's provider account; the personal fallback charges yours. Live voice has its own audio billing and can cost more; check your provider's prices and limits.
- Microphone recordings used for transcription are sent through the Codumentor server to the configured speech provider. Read-aloud sends the reply text to that provider for audio generation. In live mode, audio flows directly between the browser and the live provider after server-side call setup. Consider sensitive speech and reply content before using an external provider; Host-only protects key exposure, not the audio or text sent to that provider.
- Microphone capture needs a secure browser origin: HTTPS, or localhost. Plain HTTP on a remote host is not sufficient. Allow microphone access in browser/site settings and check your selected input device.
- If setup is still unavailable, check
speech.enabled, the endpoint and models, the exact secret name, User Secrets plugin/permission, and the deployment's personal-key policy. An unresolved environment placeholder is not a usable key. A configured key can still fail if the provider rejects it, has no credit, or lacks the requested audio model.
See also: Settings, speech configuration reference.