Dictation

Dictation lets you speak a message into the conversation composer instead of typing it. You dictate in the app. The hansard dictation command sets up and checks the engines that turn your speech into text.

App

Conversation composer → Dictate

CLI

hansard dictation

Dictate in the app

1. Open a conversation that shows a composer, or start a new conversation. See Continue in another harness.
2. Press and hold the microphone button in the composer (Hold to dictate) and speak.
3. Release the button. The composer shows Transcribing…, then inserts the text where the cursor was. When the browser’s own speech recognition is in use, words appear while you speak instead.
4. Edit the text if needed and send it.

The first time you dictate, the Mac app or your browser asks for permission to use the microphone.

To start and stop with separate clicks instead of holding, open Dictation options (the arrow beside the microphone) and turn off Hold to record. The button then reads Dictate: select it once to start and again to stop. With the button focused, Enter or Space also starts and stops recording.

Dictation options also lists your microphones under Microphone, and its last line names the engine that will transcribe your speech. The app remembers your microphone and Hold to record choice in this browser or app.

Dictation needs the app running on the same machine as Hansard. It is not available when the app is served read-only or reached from another machine.

Set up dictation from the CLI

Check which engines are ready:

hansard dictation status

Unless you choose an engine, Hansard uses the first one that is ready, in this order:

Engine	Setup	Where your audio goes	Punctuation
apple	Built into the Mac app on macOS 26 or later. For hansard web, run hansard dictation setup.	Stays on this Mac	Yes
whisper	Install whisper.cpp, then run hansard dictation setup --whisper.	Stays on this machine	Yes
openai	Set OPENAI_API_KEY in the environment that runs the app.	Sent to OpenAI	Yes
command	Set dictation.command to your own program.	Wherever your program sends it	Depends on the program

When none of these is ready, the composer uses the browser’s own speech recognition. It has no punctuation and can need a network connection.

On-device Apple speech

The Mac app includes the speech helper. To use Apple speech with hansard web, build the helper into ~/.hansard/bin:

hansard dictation setup

This needs macOS 26 or later and Xcode or its command line tools. Audio never leaves the Mac.

whisper.cpp

Install whisper.cpp, then download a model into ~/.hansard/models:

brew install whisper-cpp
hansard dictation setup --whisper

The default model is base.en. To download a different one, add --model <name>, for example --model small. Models download from the whisper.cpp model repository on Hugging Face. Transcription then runs on this machine.

OpenAI transcription

Set OPENAI_API_KEY in the environment of the process that serves the app, for example the shell that runs hansard web:

export OPENAI_API_KEY=<your-key>
hansard web

The default model is gpt-4o-mini-transcribe. To use another OpenAI transcription model, run hansard config set dictation.model <model>.

OpenAI receives your recordings

With the openai engine, each recording is sent to OpenAI with your API key. Use apple or whisper to keep audio on your machine.

Your own command

Set dictation.command to a program that reads an audio file and prints the transcript. Hansard replaces {file} in the command with the path of a 16 kHz mono WAV recording, or adds the path at the end when {file} is absent. The command runs without a shell and must finish within two minutes.

Choose an engine

AppleOn-device speech recognition on macOS 26

If unavailable

Whisperwhisper.cpp with a local model

If unavailable

OpenAIOnly with OPENAI_API_KEY set

If unavailable

CommandAny local command you configure

To use one engine and never fall back to another, set dictation.backend:

hansard config set dictation.backend whisper

Value	Effect
auto	Use the first ready engine, then the browser. The default.
apple, whisper, openai, command	Use only that engine.
browser	Use only the browser’s own speech recognition.
off	Turn dictation off and hide the microphone.

To set the language, use a locale such as en-US:

hansard config set dictation.locale en-US

The app reads these settings when it loads. Reload the browser tab or reopen the app after a change.

Troubleshooting

The microphone button is missing. dictation.backend is off, or the browser cannot open a microphone. Run hansard dictation status.

Dictation needs a transcription backend. No engine is ready and the browser has no speech recognition. Set up an engine with hansard dictation setup.

Microphone access was denied. Allow microphone access for the Mac app or the browser in your system or browser settings, then try again.

Dictated text has no punctuation. The browser’s recognizer is in use. Set up apple or whisper for punctuated text.

No speech was recognized. The recording was silent or too short. Hold the button a little longer and speak closer to the microphone.