Whisper Toaster

The simplest AK47-like toaster-like binary audio-to-text gobbler.

Drop in → pull the lever → get text.

---

simple

Why

Gigabytes of voice messages eating your disk? Backing up chats and want to keep the content but reclaim the space? Like feeding transcribed voice notes to LLMs for cleanup, then storing or sharing them compressed?

WhisperToaster is an offline tool that takes audio files and returns text. No cloud, no Python, no extra buttons. One binary, one job.

Installation

Dependencies

# Arch
sudo pacman -S qt6-base ffmpeg

ffmpeg is a runtime-only dependency — for pre-converting audio formats that whisper can't handle directly. Not needed for compilation, but without it only .wav works, and not every .wav.

Where to get models

Whisper models are hosted on HuggingFace: https://huggingface.co/ggerganov/whisper.cpp

Download the .bin file you need (ggml-medium-q8_0.bin is a solid balanced choice) and place it in the models folder:

mkdir -p ~/.local/share/pywhispercpp/models
wget -O ~/.local/share/pywhispercpp/models/ggml-medium-q8_0.bin \
    https://huggingface.co/ggerganov/whisper.cpp/resolve/main/ggml-medium-q8_0.bin

The app will automatically find models in this folder, plus:

• ~/.local/share/whisper-toaster/models/
• ~/whisper.cpp/models/

Building from source

git clone https://github.com/hopsayer/whisper-toaster whisper-toaster
cd whisper-toaster
git submodule add https://github.com/ggerganov/whisper.cpp third_party/whisper.cpp
git submodule update --init --recursive

mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . -j$(nproc)

GPU acceleration (Vulkan)

By default the build enables the Vulkan GPU backend for the bundled whisper.cpp (WHISPER_TOASTER_USE_VULKAN=ON in CMakeLists.txt). This is what makes the app's "Try GPU" toggle in Settings actually use the GPU instead of silently falling back to CPU.

Requirements: the Vulkan development packages must be installed (not just the runtime driver) — specifically the Vulkan headers/loader and the glslc shader compiler, so CMake's find_package(Vulkan) can find them. On common distros:

# Arch / Manjaro
sudo pacman -S vulkan-headers vulkan-icd-loader shaderc

# Debian / Ubuntu
sudo apt install libvulkan-dev glslang-tools

# Fedora
sudo dnf install vulkan-headers vulkan-loader-devel glslc

You also need a working Vulkan driver for your actual GPU (this is usually already present if vulkaninfo lists your device) — e.g. nvidia-utils (NVIDIA proprietary), vulkan-radeon (AMD, Mesa), or vulkan-intel (Intel, Mesa). Without a driver, the app builds fine but "Try GPU" will fail or silently do nothing at runtime.

If the dev packages above aren't found, the configure step prints a WARNING and builds CPU-only instead of failing — check the cmake .. output for a line like:

-- whisper-toaster: GGML_VULKAN = ON

To force a CPU-only build regardless of what's installed:

cmake .. -DCMAKE_BUILD_TYPE=Release -DWHISPER_TOASTER_USE_VULKAN=OFF

Note on paths: the Vulkan shader-generation step (vulkan-shaders-gen, part of ggml) does not fully shell-quote its generated build commands. Avoid parentheses, spaces, or other shell-special characters anywhere in the path to your build directory (e.g. project(binary)/ will break the build with a sh: syntax error near unexpected token '(') — use plain paths like project-binary/ instead.

Where to put the binary

The compiled binary — whisper-toaster — can be run from anywhere. Recommended:

cp whisper-toaster ~/.local/bin/

.desktop file

Copy the .desktop file from the repo (the /integration folder) to your local applications folder:

cp whisper-toaster.desktop ~/.local/share/applications/

If you placed the binary somewhere other than ~/.local/bin/, edit the Exec= line in the .desktop file accordingly.

Icons: /integration/whisper-toaster.png /integration/whisper-toaster.png Choose which you like. Place in ~/.icons or ~/.local/share/icons/. Specify in the .desktop file (Icon= line): the name of the icon without the extension, or if it fails to detect, the path to the icon (relative or absolute)

Usage

GUI

1. Launch whisper-toaster
2. Drag & drop audio files onto the drop zone, or click it to browse
3. Press Start Transcription
4. Wait for completion — text will appear in the window
5. Save: Save → "As single file" (one txt) or "As batch of files" (one txt next to each original)

#### CLI (batch) and GNOME Scripts integration (Not yet implemented)

Pass file paths as command-line arguments — the GUI will open with them pre-loaded:

whisper-toaster audio1.mp3 audio2.wav ~/Music/lecture.m4a

---

detailed

What's included

• Fully offline — no cloud APIs, everything runs on your hardware
• Drag & drop audio files (.wav, .mp3, .m4a, .aac, .flac, .ogg, .opus, .wma, .aiff)
• Auto-conversion of unsupported formats via ffmpeg to 16kHz 16-bit mono WAV
• Streaming results: text appears as it's transcribed, not all at the end
• Progress bars: overall and per-file
• Multiple files in one run — processed sequentially
• Save modes: single concatenated file or one txt next to each original
• Whisper model selection from a list (tiny → large-v3-turbo)
• GPU/CPU toggle
• Dark and light themes
• Auto-save of the last session — text survives app restarts
• Natural file sorting: file2 before file10

What's missing (for now, or on purpose)

• In-app model download — manual placement only for now
• Beam search — greedy only (faster, simpler, good enough for everyday use)
• Custom/non-standard models — only known quants from the official whisper.cpp repo
• Stop button during transcription — only process termination (coming later)
• Packaging (deb/rpm/pkg.tar.zst) — will come when the project stabilizes
• Log viewer — errors are shown in the status bar and dialogs

Known but not fixed (by choice)

• ffmpeg timeout: hangs indefinitely if ffmpeg freezes (rare, on corrupted files). Not critical — the worker runs in a background thread and doesn't block the GUI.
• Language: "auto" — the model auto-detects the language. Previously hardcoded to "ru", now fixed.
• WAV loader: 16-bit PCM only, no resampling. Everything else is auto-converted by ffmpeg.
• 4-year-old models: whisper is not the newest model, but there's no C++ alternative with comparable quality and speed yet. If one appears, I'll consider decoupling from whisper in both name and code.
• Help icon (?): currently a QLabel with "?" on a round background. Not ideal, but better than the native Qt icon on my system. If you know a better solution — PRs welcome.

Architecture notes

• TranscribeWorker runs in a separate QThread — UI stays responsive
• Progress and text streaming use native whisper.cpp callbacks (progress_callback, new_segment_callback)
• Cancellation (planned) — via abort_callback, which whisper checks between inference steps
• Model search order: ~/.local/share/pywhispercpp/models/ → ~/.local/share/whisper-toaster/models/ → ~/whisper.cpp/models/

Say thanks:

Star this project on GitHub: https://github.com/hopsayer/whisper-toaster

Star the whisper.cpp engine project: https://github.com/ggml-org/whisper.cpp