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.

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:

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:

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

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

{
  "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

Platform Examples

macOS

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

Linux (ALSA)

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

Windows

{
  "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:

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