---
title: Voice Input
url: https://arcana.otnelhq.com/docs/voice-input
---

New in v0.4.0 

This feature is part of the incoming v0.4.0 release from the `arcanagov` branch.

# Voice Input

Arcana's TUI supports **fully local voice input** — speak your prompt instead of typing it. The pipeline runs entirely on your machine: microphone recording, speech-to-text transcription, and transcript cleanup all happen locally with no cloud services.

## Quick Start

Press `Ctrl+X V` (leader key, then `V`) to toggle voice input while in the TUI prompt. Speak your prompt, and the transcribed text replaces the input field automatically.

             Privacy-first 

Voice input is 100% local. No audio leaves your machine. Transcription uses whisper.cpp and cleanup uses a local Ollama model.

## How It Works

The voice pipeline has four stages:

1. **Recording** — An external recorder captures your microphone to a 16 kHz mono WAV file.
2. **Transcription** — A local whisper.cpp binary transcribes the WAV to raw text.
3. **Normalization** — A local Ollama model cleans up the transcript (removes filler words, fixes punctuation and casing).
4. **Submission** — The cleaned text replaces the prompt input and is submitted automatically (unless you disable auto-submit).

## Requirements

You need three local components:

### 1. Audio Recorder

One of the following:

| Tool | Platform | Install |
| --- | --- | --- |
| `ffmpeg` | All | `brew install ffmpeg` / `apt install ffmpeg` / `winget install ffmpeg` |
| `sox` / `rec` | macOS / Linux | `brew install sox` / `apt install sox` |
| `arecord` | Linux | Pre-installed on most Linux distros (ALSA utils) |

`ffmpeg` is preferred. Arcana auto-detects which recorder is available.

### 2. Speech-to-Text (whisper.cpp)

A whisper.cpp binary and a GGML/GGUF model file:

```bash
# Install whisper.cpp (example — build from source or use a package manager)
brew install whisper-cpp    # macOS
# or build from source: https://github.com/ggerganov/whisper.cpp

# Download a model
whisper-cli --model ~/.local/share/whisper/models/base.bin --help  # verify binary
```

Supported binary names: `whisper-cli`, `whisper.cpp`, or `main`. Arcana searches your `PATH` for any of these.

### 3. Transcript Cleanup (Ollama)

A local Ollama instance with the normalization model:

```bash
# Install Ollama: https://ollama.com
ollama pull superwhisper/s1-mini
```

This small model removes filler words ("um", "uh"), fixes punctuation, and normalizes casing. It runs entirely on your machine.

## Configuration

Add a `voice` block to your TUI config at `~/.config/arcana/tui.json`:

```json
{
  "voice": {
    "enabled": true,
    "auto_submit": true,
    "recorder": {
      "binary": "ffmpeg",
      "args": ["-y", "-f", "avfoundation", "-i", ":0", "-ar", "16000", "-ac", "1", "{output}"]
    },
    "asr": {
      "backend": "whisper.cpp",
      "binary": "whisper-cli",
      "model": "~/.local/share/whisper/models/base.bin",
      "language": "en"
    },
    "normalizer": {
      "provider": "ollama",
      "host": "http://localhost:11434",
      "model": "superwhisper/s1-mini",
      "prompt": "Clean up this voice transcript. Remove filler words, fix punctuation and casing, and return ONLY the concise prompt text.\n\nTranscript:\n{text}"
    }
  }
}
```

### Configuration Options

| Key | Type | Default | Description |
| --- | --- | --- | --- |
| `voice.enabled` | boolean | `false` | Enable voice input |
| `voice.auto_submit` | boolean | `true` | Auto-submit transcribed text as your prompt |
| `voice.recorder.binary` | string | auto-detect | Recorder binary path (auto-detects ffmpeg/sox/rec/arecord if omitted) |
| `voice.recorder.args` | string[] | — | Recorder arguments. `{output}` is replaced with the temp WAV path |
| `voice.asr.backend` | string | `whisper.cpp` | ASR backend (only `whisper.cpp` supported today) |
| `voice.asr.binary` | string | auto-detect | whisper.cpp binary path (auto-detects `whisper-cli`/`whisper.cpp`/`main`) |
| `voice.asr.model` | string | — | Path to GGML/GGUF model file |
| `voice.asr.language` | string | `en` | Transcription language code |
| `voice.normalizer.provider` | string | `ollama` | Normalizer provider (only `ollama` supported today) |
| `voice.normalizer.host` | string | `http://localhost:11434` | Ollama API host |
| `voice.normalizer.model` | string | `superwhisper/s1-mini` | Ollama model for transcript cleanup |
| `voice.normalizer.prompt` | string | (built-in) | Cleanup prompt. `{text}` is replaced with the raw transcript |

## Platform Examples

### macOS

```json
{
  "voice": {
    "enabled": true,
    "recorder": {
      "binary": "ffmpeg",
      "args": ["-y", "-f", "avfoundation", "-i", ":0", "-ar", "16000", "-ac", "1", "{output}"]
    }
  }
}
```

### Linux (ALSA)

```json
{
  "voice": {
    "enabled": true,
    "recorder": {
      "binary": "arecord",
      "args": ["-f", "S16_LE", "-r", "16000", "-c", "1", "{output}"]
    }
  }
}
```

### Windows

```json
{
  "voice": {
    "enabled": true,
    "recorder": {
      "binary": "ffmpeg",
      "args": ["-y", "-f", "dshow", "-i", "audio=Microphone", "-ar", "16000", "-ac", "1", "{output}"]
    }
  }
}
```

## Troubleshooting

### No recorder found

If the first voice toggle shows a setup toast, Arcana couldn't find a recorder binary. Install `ffmpeg` and ensure it's on your `PATH`.

### whisper.cpp not found

Ensure `whisper-cli`, `whisper.cpp`, or `main` is on your `PATH`, or set `voice.asr.binary` to the full path.

### Ollama not running

Start Ollama and pull the model:

```bash
ollama serve                    # start Ollama (if not running as a service)
ollama pull superwhisper/s1-mini  # pull the cleanup model
```

### Poor transcription quality

- Use a larger whisper.cpp model (e.g., `medium` or `large` instead of `base`)
- Ensure your microphone is working and not muted
- Reduce background noise
- Set `voice.asr.language` to match your spoken language

## Related

- [Themes](/docs/themes) — Customize the TUI appearance with 11 built-in themes
- [Configuration](/docs/configuration) — Full config file reference and environment variables
- [Troubleshooting](/docs/troubleshooting) — Common issues and debugging