> ## Documentation Index
> Fetch the complete documentation index at: https://docs.otter-shell.org/llms.txt
> Use this file to discover all available pages before exploring further.

# otter-transcribe

> Transcribe microphone audio on-device via PipeWire. Requires the otter-shell-extras metapackage.

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.

<Note>
  `otter-transcribe` is part of **`otter-shell-extras`**, not the base `otter-shell` metapackage. Install with `pikman install otter-shell-extras`.
</Note>

## Starting the Daemon

```bash theme={null}
otter-transcribe    # start the transcription daemon
```

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

```bash theme={null}
otter-transcribe --model /path/to/model.gguf
```

<Note>
  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.
</Note>

## Controlling with Hotkeys

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

```bash theme={null}
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
```

<Tip>
  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.
</Tip>

## 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                                                |

<Note>
  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.
</Note>

## 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`:

```conf theme={null}
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.