Developer Guide

🌐 Language: English | Français

Developer Guide

Everything you need to build, test, and contribute to dictee. The project combines Rust (ASR engine via ONNX Runtime), Python / PyQt6 (setup wizard + tray), QML (KDE plasmoid), and Bash (main orchestration script).

Build artifacts are packaged as .deb, .rpm, Arch PKGBUILD, and a portable tarball. This guide covers repo layout, Cargo features, build scripts, testing harnesses, i18n, and the contribution workflow.

Repo layout

dictee/                         # git repo root
├── Cargo.toml                  # Rust workspace
├── src/                        # Rust — moteur ASR (bibliothèque + binaires)
│   ├── lib.rs                  # Public API
│   ├── audio.rs                # WAV, STFT, mel-spectrograms
│   ├── parakeet_tdt.rs         # TDT model (25 languages)
│   ├── canary.rs               # Canary AED model
│   ├── nemotron.rs             # Nemotron streaming (EN only)
│   ├── sortformer.rs           # Diarization, streaming (4 speakers)
│   ├── diar/                   # Multi-speaker diarization engine (no cap, v1.4)
│   ├── model*.rs, decoder*.rs  # ONNX wrappers
│   ├── timestamps.rs           # Token→word→sentence alignment
│   └── bin/                    # Executables
│       ├── transcribe.rs               # CLI batch
│       ├── transcribe_daemon.rs        # Unix socket server
│       ├── transcribe_client.rs        # Daemon client + mic recording
│       ├── transcribe_diarize.rs       # TDT + Sortformer
│       ├── transcribe_stream_diarize.rs  # Nemotron + Sortformer
│       └── transcribe_diarize_batch.rs # Chunked pipeline (v1.3 final)
├── dictee                      # Main shell script (source of truth)
├── dictee-setup.py             # PyQt6 setup wizard
├── dictee-tray.py              # PyQt6 tray icon
├── plasmoid/                   # KDE Plasma 6 widget
│   └── package/
│       ├── metadata.json
│       └── contents/
│           ├── ui/             # QML (main.qml, CompactRepresentation, etc.)
│           ├── assets/         # SVG animations (bars, wave, pulse, dots, waveform)
│           └── locale/{fr,de,es,it,uk,pt}/
├── po/                         # gettext translations (setup + tray)
│   ├── dictee.pot              # Template
│   └── {fr,de,es,it,uk,pt}.po
├── pkg/                        # dpkg-deb tree (artifact, NOT source of truth)
├── tests/                      # Test suites
│   ├── test-postprocess.py     # 682 unittest cases
│   ├── test-pipeline.py        # 148 pipeline cases
│   └── test-wer.py             # WER benchmark harness
├── build-deb.sh                # .deb build (CPU + CUDA)
├── build-rpm.sh                # .rpm build (CPU + CUDA)
├── PKGBUILD                    # Arch package
└── install.sh / uninstall.sh

Source of truth

Files at the repo root (dictee, dictee-setup.py, dictee-tray.py) are the source of truth.

build-deb.sh copies them into pkg/ at build time. Never edit files in pkg/ directly — they will be overwritten on the next build.

Building from source

Rust ASR engine

git clone https://github.com/rcspam/dictee.git
cd dictee

# CPU-only (default)
cargo build --release

# CUDA + Sortformer diarization
cargo build --release --features "cuda,sortformer"

Output binaries in target/release/:

libparakeet_rs.so (library, for future bindings)
transcribe, transcribe-daemon, transcribe-client
transcribe-diarize, transcribe-stream-diarize, transcribe-diarize-batch

Cargo features

Declared in Cargo.toml:

Feature	Default	Purpose
`cpu`	✅	CPU execution provider
`ort-defaults`	✅	ONNX Runtime sensible defaults
`cuda`	❌	CUDA 12 execution provider
`tensorrt`	❌	TensorRT optimization (experimental)
`coreml`	❌	Apple CoreML (macOS-only, unused in dictee)
`directml`	❌	DirectX 12 (Windows-only, unused)
`openvino`	❌	Intel OpenVINO
`webgpu`	❌	WebGPU (browser use)
`nnapi`	❌	Android NNAPI (unused)
`sortformer`	❌	Speaker diarization via Sortformer

Typical combos:

Dev machine: --features cuda,sortformer
CI CPU build: (default, no features)
CI CUDA build: --features cuda,sortformer

Python UI

No build step — files at dictee-setup.py and dictee-tray.py are interpreted at runtime.

Dependencies (install for development):

pip install PyQt6 PyQt6-WebEngine text2num faster-whisper vosk

For PyQt6 on Ubuntu 22.04 (which ships 5.15):

pip install --user 'PyQt6>=6.5' 'PyQt6-Qt6>=6.5'

Plasma plasmoid

Dev install (doesn't require packaging):

kpackagetool6 -t Plasma/Applet -i plasmoid/package

Reinstall after edits:

kpackagetool6 -t Plasma/Applet -u plasmoid/package
# Restart plasmashell if the widget is already on a panel:
killall -15 plasmashell && kstart plasmashell &

Package builds

`.deb` build

./build-deb.sh

Produces:

dictee-cpu_1.3.1_amd64.deb
dictee-cuda_1.3.1_amd64.deb
dictee-plasmoid_1.3.1_all.deb
dictee-1.3.1_amd64.tar.gz (portable tarball)

Key steps:

cargo build --release (for CPU variant) + cargo build --release --features cuda,sortformer (for CUDA)
Copy Rust binaries to pkg/dictee/usr/bin/
Copy shell scripts (dictee, dictee-postprocess, etc.) to pkg/dictee/usr/bin/
Copy Python scripts (dictee-setup.py → /usr/bin/dictee-setup) — note: renamed without .py
Copy plasmoid to pkg/dictee-plasmoid/usr/share/dictee/dictee.plasmoid
Build CUDA variant: bundle CUDA libs via pip venv (since v1.3)
dpkg-deb --build pkg/dictee-cpu etc.

`.rpm` build

./build-rpm.sh

Same outputs but .rpm. Uses rpmbuild with a spec file.

Arch

makepkg -si

Uses PKGBUILD in the repo root. Builds from source, no prebuilt binaries.

Common gotchas

See the memory note feedback-cuda-build-flags: certain cargo flags combinations have been problematic 5+ times. Always double-check:

LIBTORCH not set globally
ORT_STRATEGY=download for CI
ORT_DYLIB_PATH set at runtime in the systemd unit

Audio pipeline internals

Microphone (PipeWire)
   ↓ parecord --format=s16le --rate=48000 --channels=1
   ↓
/dev/shm/.dictee_rec.wav  (raw capture)
   ↓ sox resample to 16 kHz mono
   ↓
/dev/shm/.dictee_rec_16k.wav
   ↓ transcribe-client sends via Unix socket
   ↓
Unix socket: $XDG_RUNTIME_DIR/transcribe.sock
   ↓
transcribe-daemon (Rust)
   ↓
src/audio.rs: preemphasis(0.97) → STFT(n_fft=512, hop=160, win=400, Hann)
   ↓
Mel filterbank (128 bins, Slaney, log guard 5.96e-8)
   ↓
ONNX tensor (1 × 128 × T)
   ↓
Encoder (FastConformer) → Decoder (TDT)
   ↓
Text (with native punctuation)
   ↓
Unix socket response
   ↓
dictee shell script → dictee-postprocess → dotool type

Full source: src/audio.rs (Rust side), pkg/dictee/usr/bin/dictee-transcribe (Python wrapper).

Runtime state & IPC

State files

See CLI-Reference#state-files for the full list. Multi-user safe via $UID suffix.

Socket protocol

Daemon listens on $XDG_RUNTIME_DIR/transcribe.sock. Protocol is line-based:

Request:

TRANSCRIBE /path/to/audio.wav [lang=fr] [translate_to=en]

Response:

OK <json-payload>

Payload includes: transcription text, word-level timestamps, speaker labels (if diarization), language detected, confidence.

Implementation in src/bin/transcribe_daemon.rs.

Testing

Unit tests (Rust)

cargo test
cargo test --features sortformer

Post-processing tests (Python)

682 tests in tests/test-postprocess.py — 12 pipeline steps × 7 languages × edge cases:

cd tests
python -m unittest test-postprocess.py -v

Pipeline tests (Python)

148 tests in tests/test-pipeline.py — full transcription pipeline with mocked ASR:

python -m unittest test-pipeline.py -v

WER benchmark

python tests/test-wer.py --backend parakeet --lang fr --corpus commonvoice

Manual UI tests

docs/test-checklist-ui-pipeline.md — 39 UI checks
docs/test-protocol-vocal.md — 38 vocal dictations to verify

CI

GitHub Actions runs all automated tests on every push:

Post-processing (isolated XDG_CONFIG_HOME)
Pipeline
Rust unit tests
msgfmt --check on all .po files

Internationalization

gettext (setup + tray)

dictee-setup.py and dictee-tray.py use gettext with domain dictee and catalogs in po/:

po/dictee.pot — template (regenerated from source strings via xgettext)
po/{fr,de,es,it,uk,pt}.po — translations
po/{lang}/LC_MESSAGES/dictee.mo — compiled (generated by msgfmt)

Workflow:

# Extract new strings into the template
xgettext -L Python -o po/dictee.pot dictee-setup.py dictee-tray.py

# Update existing translations
msgmerge --update po/fr.po po/dictee.pot

# Compile to .mo
msgfmt po/fr.po -o po/fr/LC_MESSAGES/dictee.mo

Plasmoid translations

Separate domain plasma_applet_com.github.rcspam.dictee:

plasmoid/package/contents/locale/{fr,de,es,it,uk,pt}/LC_MESSAGES/plasma_applet_com.github.rcspam.dictee.mo

Built by the plasmoid packager.

`.desktop` translations

Inline, e.g.:

Name=Dictée
Name[fr]=Dictée
Name[de]=Diktat
GenericName=Voice dictation
GenericName[fr]=Dictée vocale

Contributing

Workflow

Fork the repo at github.com/rcspam/dictee
Create a feature branch: git checkout -b feat/my-feature
Commit with conventional commits: feat(scope): description / fix(scope): description
Push and open a PR against master
CI must be green
Code review by maintainer

Commit style

Examples from git log:

feat(plasmoid): combo langue compact + popup wide + close on deactivate
fix(setup): wizard trans sync + langues cibles complètes + largeur combos
docs(wiki): scaffold 20 pages (stubs)
chore(version): bump 1.3.0~beta5 → 1.3.0~rc1

Adding an ASR backend

Create src/<backend>.rs with the ONNX model wrapper
Add a binary in src/bin/ or extend transcribe_daemon to support it
Create a systemd unit at pkg/dictee/usr/lib/systemd/user/dictee-<backend>.service
Update dictee-switch-backend to recognize the new backend name
Add UI support in dictee-setup.py (ASR backend combo + model download logic)
Document in ASR-Backends and CLI-Reference

Adding a new language

Add regex rules in pkg/dictee/usr/share/dictee/rules.conf.default with [xx] prefix
Add continuation trigger word in continuation.conf.default
Add .po translation for setup + tray: po/xx.po
Add plasmoid translation: plasmoid/package/contents/locale/xx/
Test manually against test-protocol-vocal.md

Next steps

CLI-Reference — all binaries documented
ASR-Backends — backends overview
Changelog — release notes and roadmap
Troubleshooting — debug common issues

📖 dictee Wiki

🇬🇧 Home · 🇫🇷 Accueil

Getting started / Premiers pas

Installation · 🇬🇧 · 🇫🇷
Setup-Wizard · 🇬🇧 · 🇫🇷
Configuration · 🇬🇧 · 🇫🇷
Plasmoid-Widget · 🇬🇧 · 🇫🇷
Tray-Icon · 🇬🇧 · 🇫🇷
Keyboard-Shortcuts · 🇬🇧 · 🇫🇷
Voice-Commands · 🇬🇧 · 🇫🇷
GPU-Setup · 🇬🇧 · 🇫🇷
Diarization · 🇬🇧 · 🇫🇷
LLM-Diarization · 🇬🇧 · 🇫🇷

Speech recognition / ASR

ASR-Backends · 🇬🇧 · 🇫🇷
Parakeet-TDT-Deep-Dive · 🇬🇧 · 🇫🇷
Canary-1B-Deep-Dive · 🇬🇧 · 🇫🇷

Translation / Traduction

Translation · 🇬🇧 · 🇫🇷
Ollama-Setup · 🇬🇧 · 🇫🇷

Post-processing / Post-traitement

Overview · 🇬🇧 · 🇫🇷
Rules-and-Dictionary · 🇬🇧 · 🇫🇷
LLM-Correction · 🇬🇧 · 🇫🇷
Numbers-Dates-Continuation · 🇬🇧 · 🇫🇷

CLI

CLI-Reference · 🇬🇧 · 🇫🇷

Reference / Référence

Troubleshooting · 🇬🇧 · 🇫🇷
FAQ · 🇬🇧 · 🇫🇷
Developer-Guide · 🇬🇧 · 🇫🇷
Changelog · 🇬🇧 · 🇫🇷

🏠 Repo · 📦 Releases · 🐛 Issues

Developer Guide

Developer Guide

Table of Contents

Repo layout

Source of truth

Building from source

Rust ASR engine

Cargo features

Python UI

Plasma plasmoid

Package builds

.deb build

.rpm build

Arch

Common gotchas

Audio pipeline internals

Runtime state & IPC

State files

Socket protocol

Testing

Unit tests (Rust)

Post-processing tests (Python)

Pipeline tests (Python)

WER benchmark

Manual UI tests

CI

Internationalization

gettext (setup + tray)

Plasmoid translations

.desktop translations

Contributing

Workflow

Commit style

Adding an ASR backend

Adding a new language

Next steps

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

`.deb` build

`.rpm` build

`.desktop` translations