qal-scribe 1.0.1

Press s in the window to change the common settings; each one saves at once. Everything else lives in config.toml: qal-scribe config --init writes a commented copy and qal-scribe config prints where it is.

Every setting, with its default, is in docs/settings.md, including your own word corrections (words.txt) and how the experimental punctuation behaves.

Translation goes sentence by sentence, and the speech model writes no punctuation, so qal-scribe takes a pause of half a second as the end of a sentence: pause briefly between sentences when you translate.

Pick the model on the setup screen, in the settings, or with translation_model in config.toml:

Bigger models are slower and need more memory. On a machine with little memory, turn translation off: the translation model is then never loaded.

Before installing, get PortAudio and the tools to build evdev (a keyboard library with no ready-made build):

sudo apt install libportaudio2 build-essential python3-dev      # Debian, Ubuntu
sudo dnf install portaudio gcc python3-devel kernel-headers      # Fedora
sudo pacman -S portaudio base-devel                             # Arch

Without an NVIDIA GPU, install the CPU build of PyTorch instead of the multi-GB CUDA one, and upgrade with the same line plus --upgrade (uv does not remember --torch-backend):

uv tool install --python 3.12 qal-scribe --torch-backend cpu

Text is typed with wtype (sway, Hyprland), xdotool (X11), or on GNOME and KDE Wayland pasted with wl-copy plus ydotool (needs ydotoold running). Without any of them the text goes to the clipboard and the window says so. Wayland gives programs no global hotkeys, so bind two keys in your desktop settings to qal-scribe toggle and qal-scribe toggle --translate.

Linux has only been tested in CI and with simulated tools so far. Please report what works and what does not.

Start with qal-scribe doctor: it checks the permissions, microphone, compute device, config and models, and prints the fix next to each problem.

• The keys do nothing while another app is in front. Turn on Input Monitoring for your terminal, then quit it with ⌘Q and reopen it.
• The text is not pasted. Turn on Accessibility for your terminal. The text is also on the history list: select it and press Enter to copy it.
• It pastes what you had copied before. Some apps paste slowly; raise restore_delay (default 0.5 seconds).
• The language model is off. qal-scribe doctor warns when Python is not 3.12: reinstall with uv tool install --python 3.12 --reinstall qal-scribe.
• A download stopped. Ctrl+C cancels a download; the next start, qal-scribe setup or qal-scribe models download --translation begins it again.

More answers in docs/faq.md.

Recording, transcription and translation all happen on your computer. qal-scribe sends no audio, no text and no usage data anywhere. It goes online only to fetch the models from Hugging Face (and to look up their download sizes on the setup screen), the first time or when you choose a new one. Pasting uses the clipboard: qal-scribe saves what you had copied and puts it back half a second later.

Measured on the 516 clips of the FLEURS Amharic test split with eval/evaluate.py (lower is better; scoring folds homophone letters and drops punctuation):

These are for read speech; expect more errors with background noise, fast speech, names and English words (add those to your words file). On an Apple GPU a 10 s clip takes about 0.15 s.

qal-scribe                     start dictating (terminal UI)
qal-scribe --plain             the same, one line per event
qal-scribe --no-translate      start without the translation model, for this run
qal-scribe setup               permissions, translation choice and model downloads
qal-scribe doctor              check permissions, microphone, device, config and models
qal-scribe models              list languages and whether each model is downloaded
qal-scribe models download [LANG] [--translation]
qal-scribe transcribe FILE [--translate]       an audio file (wav, flac, ogg, mp3; convert m4a first) to text
qal-scribe config [--init]     show (or create) the config file
qal-scribe toggle [--translate]                start/stop recording in the running instance
qal-scribe about               licences and model attribution

The code is MIT licensed. The models are downloaded at run time and keep their own licences: the Amharic speech model, snapwre/hohe-asr-amharic, is CC-BY-4.0; the NLLB translation models are CC-BY-NC-4.0, which allows non-commercial use only. qal-scribe about lists them all. The ቃል in the logo is drawn from Noto Sans Ethiopic (SIL Open Font License 1.1).

uv sync
uv run ruff check
uv run pytest                  # no model weights are loaded
uv run python scripts/gpu_lock.py -- uv run pytest -m model     # tests with the real models
uv run python scripts/screenshots.py                            # redraw docs/assets/screens and demo.svg
uv run python eval/fetch_fleurs.py && \
  uv run python scripts/gpu_lock.py -- uv run python eval/evaluate.py eval/data/fleurs-am-test --compare