Voice

Voice input is dictation into the composer. Mercury transcribes a spoken take, the words land in the composer with the cursor at the end, and you edit or send them like typed text. Mercury never speaks aloud, and the composer is the only destination of a capture.

Voice controls

• /speak on: Turns voice input on for this machine.
• /speak off: Turns voice input off, which is the default.
• /speak: Shows the status, the transcriber the next take would use, the saved default and the capture backend.
• /voice: Starts a capture, or stops the one running. It is the same action as pressing Space.
• /speak options: Lists the transcribers this install can use and marks the one that would serve now. /speak options <name> makes one the default.
• /speak download: Fetches the on-device speech model.

Dictate into the composer

To dictate into the composer, follow these steps:

1. Enter /speak on.
2. Press Space in an empty composer.
3. Speak.
4. Press Space again.

Mercury sends the take to the transcriber and puts the words in the composer with the cursor at the end.

A terminal sees no key release, so a capture is press to start and press to stop. Esc cancels the capture, and nothing leaves the machine. With voice input off, Space is a space. The footer reads ● recording · space or esc to stop while a take runs and transcribing… while it is in flight. A take is bounded at five minutes; at the bound Mercury stops it, says so and transcribes what it has. Every refusal is a receipt with its reason.

Capture backends

A take is 16 kHz mono 16-bit audio held in memory. It is never written to disk unless MERCURY_VOICE_DEBUG_WAV_DIR asks for a copy. The backend is chosen in this order, and /speak and the doctor name the live one.

• Voice pack: Mercury's own native add-on over the platform's audio layer, CoreAudio on macOS, WASAPI on Windows and ALSA on Linux. It is built with cargo during bun run setup, and a machine without a Rust toolchain runs Mercury without it.
• A recorder on PATH: sox, arecord on Linux, or ffmpeg, used only when you have installed one.
• No backend: Pressing Space answers the receipt "no microphone backend" and names the remedy: the pack build on a source checkout, or a recorder on PATH.

On macOS the first capture makes the operating system ask whether the terminal application may use the microphone. A denied permission does not crash a capture: the take arrives as silence, and the receipt names the Microphone entry under Privacy & Security in System Settings.

Transcribers

A finished take goes to the first transcriber that can serve, in this order.

• On-device: Mercury's own transcriber, built from the repository's native/whisper sources during bun run setup with cargo and cmake, with a speech model in the config home. Nothing leaves the machine.
• OpenAI: An API key uses the transcription endpoint. A ChatGPT subscription sign-in does not transcribe.
• Google: An API key transcribes through a generate-content request with the audio inline. The Google account sign-in does not transcribe.
• Anthropic: Offers no speech-to-text endpoint.

Signed-in providers with a speech-to-text endpoint are tried in the order of the sign-in ledger. Nothing downloads on its own.

Download the on-device speech model

To download the on-device speech model, follow these steps:

1. Enter /speak download with the on-device pack present.

Mercury fetches the default 60 MB English model from its pinned address into <config-home>/models/whisper, verifying the size and the digest before the file takes its name.

With the pack present and no model, /speak on and /speak name the download, and a provider serves until it completes. /speak download <name> fetches one of the other listed models, English or multilingual. MERCURY_WHISPER_MODEL picks a model for a session, by name or by the path of a ggml file.

Select a default transcriber

To select a default transcriber, follow these steps:

1. Enter /speak options to list the transcribers this install can use.
2. Enter /speak options <name> with on-device, openai or gemini.

Mercury saves the choice in the config home, and it survives a restart.

/speak options default restores the shipped default. A saved choice that cannot serve is named in /speak, in the recording receipt and in the doctor row, and the shipped default serves. MERCURY_VOICE_TRANSCRIBER overrides the saved choice for one session with on-device, cloud for the ledger walk, or a provider id such as openai; a pin that cannot serve says so and never falls back silently.

Privacy and the doctor row

With the on-device transcriber, audio never leaves the machine. With a provider, audio leaves the machine only to that provider and only after the take stops; nothing is sent while you speak, and a cancelled take is dropped without a request. The doctor's INTERFACE section and /health carry a Voice input row naming the backend, the transcriber with its model and pack, and the permission words for this machine.

Related pages

Using Mercury, Providers and sign-in, Health check