otter-transcribe

otter-transcribe is Otter Shell’s on-device speech-to-text tool. It runs as a background daemon, records your microphone through PipeWire, and transcribes with a locally embedded Parakeet model. No network or cloud service involved.

otter-transcribe is part of otter-shell-extras, not the base otter-shell metapackage. Install with pikman install otter-shell-extras.

Starting the Daemon

otter-transcribe    # start the transcription daemon

To use an alternate GGUF model file instead of the default embedded model, pass the --model flag:

otter-transcribe --model /path/to/model.gguf

The daemon hot-reloads config changes via inotify. You do not need to restart it after editing otter-transcribe.conf. Theme colors and transcription settings apply immediately. After a model unload, the daemon restarts itself once recording is idle.

Controlling with Hotkeys

Use otter-transcribectl to send commands to the running daemon:

otter-transcribectl toggle  # start or stop recording
otter-transcribectl start   # begin recording (hold-to-capture start)
otter-transcribectl stop    # end recording (hold-to-capture stop)
otter-transcribectl status  # check daemon status

Bind otter-transcribectl toggle in your compositor config. Wayland clients cannot grab global hotkeys directly, so compositor-level binding is required for reliable capture from any focused window.

Output Modes

otter-transcribe supports three output modes that control where transcribed text goes after each utterance:

Mode	Behaviour
`focused`	Types the transcript into the currently focused input via Wayland virtual keyboard injection
`clipboard`	Copies the transcript to the clipboard via `wl-copy`
`stdout`	Prints the transcript from the daemon process

Use clipboard or stdout if virtual keyboard injection is blocked by your compositor or application. Chromium and Electron apps use physical evdev keycodes, which focused mode handles for better compatibility.

Recording Indicator

While recording is active, a bottom-center layer-shell indicator shows live PCM level bars so you know when the microphone is open. Set show_indicator = false in the config file to hide it.

Configuration

Edit transcription settings in otter-settings under the Transcribe tab, or in ~/.config/otter-shell/otter-transcribe.conf:

output = focused
stream = true
show_indicator = true
sample_rate = 16000
target = "@DEFAULT_SOURCE@"
max_seconds = 300
width = 120
height = 48
margin_bottom = 36
graph_height = 28
graph_bars = 24

stream: true emits each finalized utterance chunk in real time. false returns one final value for the entire recording
target: PipeWire audio source. @DEFAULT_SOURCE@ uses the system default microphone
max_seconds: maximum recording length in seconds. When reached, the daemon finalizes and stays alive for future commands
show_indicator: controls the bottom-center PCM level indicator

The indicator’s colors (background_color, border_color, graph_color, graph_peak_color, text_color) inherit from otter-theme when left unset in the config file.

Get Started

Desktop Shell

Core Apps

Productivity

Utilities

Configuration

Starting the Daemon

Controlling with Hotkeys

Output Modes

Recording Indicator

Configuration

​Starting the Daemon

​Controlling with Hotkeys

​Output Modes

​Recording Indicator

​Configuration

Starting the Daemon

Controlling with Hotkeys

Output Modes

Recording Indicator

Configuration