Shoki

Voice recording and transcription tool using whisper.cpp.

Records audio from your microphone, visualizes the waveform in real time, and transcribes speech to text using local Whisper models.

Requirements

• Python 3.11+
• whisper.cpp binary (whisper-cli, whisper, or main) on your PATH
• A Whisper model file (downloaded automatically with --download-model)
• Linux (macOS/Windows support planned)

Installation

# Clone the repository
git clone <repo-url> && cd shoki

# Create virtual environment and install
./scripts/setup-venv.sh
source .venv/bin/activate

# Download a Whisper model (required before first use)
shoki --download-model base

# Verify whisper.cpp is installed
which whisper-cli   # or whisper, or main

Usage

# Record with waveform visualization (default)
shoki

# Record without GUI (terminal mode)
shoki --no-gui

# List available microphones
shoki --list-devices

# Record from a specific device
shoki --device 1

# Use a different model
shoki --whisper-model small

# Specify a language (auto-detected if omitted)
shoki --language en

# Custom output directory
shoki --output-dir ~/Desktop

# Custom whisper binary path
shoki --whisper-bin /opt/whisper/main

# Disable desktop notifications
shoki --no-notify

CLI Options

Option	Description
--list-devices	List all audio input devices and exit
--device INDEX	Audio input device index
--output-dir PATH	Output directory (default: ~/Documents)
--whisper-model SIZE	Model size: tiny, base, small, medium, large (default: base)
--whisper-bin PATH	Path to whisper.cpp executable
--model-dir PATH	Directory containing model files
--language CODE	Language code (e.g. en, fr; auto-detect if unset)
--download-model SIZE	Download a model and exit
--no-gui	Terminal-only recording (no waveform window)
--no-notify	Disable desktop notification

Output

Transcriptions are saved to ~/Documents/transcript_YYYY-MM-DD_HH.MM.SS.txt with a metadata header:

# Shoki Transcription
# Date: 2024-01-15 14:30:00
# Device: default
# Model: base

Transcribed text appears here...

Troubleshooting

"whisper.cpp binary not found"

Install whisper.cpp from https://github.com/ggerganov/whisper.cpp or use --whisper-bin.

"Model not found"

Run shoki --download-model base to download the base model.

"No audio data captured"

Ensure your microphone is working and selected. Use --list-devices to find the correct device index.

"Failed to record"

Check that no other application is using the microphone. Try --device INDEX with a different device.

Project Structure

src/shoki/          # Package source
  cli.py            # CLI entry point and argument parsing
  audio.py          # Audio recording (sounddevice) and device enumeration
  core.py           # Transcription orchestration
  gui.py            # Qt6 waveform visualization
  whisper.py        # whisper.cpp binary detection, model management, subprocess
  output.py         # Timestamped filename generation and file writing
tests/              # Test suite
  unit/             # Unit tests
scripts/            # Utility scripts