Local speech-to-text toolkit for Arch Linux. Transcribes audio and video to clean Markdown. Clean text by default — timestamps optional.
scribe lecture.mp4
scribe interview.ogg --lang ru --save my-notes
scribe https://youtube.com/watch?v=... # coming in v0.3
dscribe dictate # coming in v0.5Platform: Arch Linux only (Wayland/Hyprland, PipeWire, AMD GPU via Vulkan/RADV).
On macOS use MacWhisper.
# Transcribe a file — result appears next to the source
scribe video.mp4
# → video.md
# Save to a specific folder
scribe video.mp4 --out ~/Documents/
# Process multiple files — shell glob, skips files already transcribed
scribe ~/Videos/*.mp4 --out ~/Documents/transcripts/That's it. No configuration required for basic use.
scribe video.mp4Output: video.md next to the source file.
Set your transcripts directory once:
# Add to ~/.zshrc
export SCRIBE_SAVE_DIR=~/Documents/transcriptsThen use --save to name the output:
scribe video.mp4 --save meeting-notes
# → ~/Documents/transcripts/meeting-notes.mdscribe ~/Videos/*.mp4 --out ~/Documents/transcripts/Files that already have a matching .md output are skipped; pass --force
to re-transcribe them. One failing file doesn't stop the rest — a summary
line at the end reports how many were transcribed, skipped, and failed.
--save only works with a single file (one name can't apply to many outputs).
scribe video.mp4 --dry-run # shows planned output path, does nothing
scribe video.mp4 --model large-v3 # use largest model for best accuracy| Version | Feature | Status |
|---|---|---|
| v0.1 | Local files (mp4, mp3, ogg, mkv, ...) | done |
| v0.1 | --timestamps — optional timestamped output |
done |
| v0.1 | Batch mode — multiple files via shell glob | done |
| v0.2 | Readable formatting — sentence/length-based paragraphs (wtpsplit), not one text block | done |
| v0.2 | --speakers — best-effort speaker labels (stereo diarization) |
done |
| v0.3 | Visual timeline — slide screenshots synced to transcript | planned |
| v0.4 | YouTube / web (yt-dlp) | planned |
| v0.5 | Telegram channels & chats (telethon) | planned |
| v0.6 | Dictation — mic → clipboard / type | planned |
| v0.7 | Meeting mode — mic + system audio | planned |
| v0.8 | Idea digest — local LLM summary (llama.cpp Vulkan) | planned |
| v1.0 | GTK4 GUI | planned |
- Arch Linux (primary platform)
- Python 3.12+
- ffmpeg
- whisper.cpp built with Vulkan support (see below)
- AMD GPU with RADV driver (RX 470/480/580 and newer recommended)
sudo pacman -S python python-pipx ffmpeg cmake vulkan-headers spirv-headers
pipx ensurepathbash scripts/build-whisper-cpp-vulkan.shThis clones whisper.cpp into ~/builds/whisper.cpp, builds with -DGGML_VULKAN=1, and installs whisper-cli to ~/.local/bin/.
mkdir -p ~/.local/share/dimarch-scribe/models
bash ~/builds/whisper.cpp/models/download-ggml-model.sh medium \
~/.local/share/dimarch-scribe/models/Available models: tiny, base, small, medium (default), large-v3.
pipx install dimarch-scribe --python /usr/bin/pythonFor development (editable install):
git clone https://github.com/dmitrax/dimarch-scribe
cd dimarch-scribe
pipx install -e . --python /usr/bin/pythonbash scripts/check-system.sh
scribe --help# Transcribe a file — output next to source
scribe video.mp4
# Save to custom directory
scribe video.mp4 --out ~/Desktop
# Save to configured save_dir as NAME.md
scribe video.mp4 --save my-notes
# Choose model and language
scribe audio.ogg --model large-v3 --lang ru
# Overwrite existing output
scribe video.mp4 --force
# Verbose mode (show progress)
scribe video.mp4 --verbose
# Show best-effort speaker labels (stereo diarization)
scribe meeting.mp4 --speakers
# Batch mode — multiple files, skips existing outputs unless --force
scribe ~/Videos/*.mp4 --out ~/Documents/transcripts/
# Full command equivalent
dscribe transcribe video.mp4
# System check
dscribe doctor--save NAME saves NAME.md to a directory you configure:
# via environment variable
export SCRIBE_SAVE_DIR=~/Documents/transcripts
# or in ~/.config/dimarch-scribe/config.toml
[paths]
save_dir = "~/Documents/transcripts"The environment variable takes priority if both are set.
Clean UTF-8 Markdown, no timestamps, broken into readable paragraphs by sentence boundaries and length (local model, wtpsplit — not a fixed pause timer, which doesn't work for continuous speech like a busy call). This groups sentences into human-sized blocks; it doesn't detect topic changes — recognized words are never altered, dropped, or reordered:
Привет, меня зовут Дима и я хочу рассказать вам о системе которая
изменила мой подход к рекрутингу...
Сегодня я покажу три конкретных шага, с которых можно начать уже сегодня...
With --speakers, paragraphs also break on a detected speaker change and get
a label — best-effort, based on whisper.cpp's stereo channel diarization
(-di), not real speaker-ID:
**Speaker 1:** Привет, меня зовут Дима...
**Speaker 2:** Круто, давай подробнее...
| Component | Tool |
|---|---|
| Transcription (GPU) | whisper.cpp with Vulkan/RADV |
| Transcription (CPU fallback) | faster-whisper |
| Audio processing | ffmpeg |
| YouTube / web | yt-dlp |
| Telegram | telethon |
| CLI | typer + rich |
| Installation | pipx |
Developed and tested on AMD RX 580 (Polaris, gfx803) via RADV.
ROCm is not used — it does not work reliably on gfx803 with ROCm 6.x.
Vulkan via RADV is the correct GPU path for this hardware.
pipx inject dimarch-scribe pytest mypy # or: pip install -e .[dev]
pytest
mypyIntegration tests that need whisper-cli + a downloaded model are skipped
automatically if either is missing.
dscribe and scribe are two separate Typer apps that each forward their
own arguments to _run_transcribe() — a parameter added to one and missed
in the other is a type error mypy catches immediately, and tests/test_cli.py
exercises both entry points for real (--dry-run, no whisper-cli needed) so
drift between them fails a test even without running mypy.
See CHANGELOG.md for release history.
MIT