fr Developer Guide

🌐 Langue : English | Français

Guide Développeur

Tout ce qu'il faut pour compiler, tester et contribuer à dictée. Le projet combine Rust (moteur ASR via ONNX Runtime), Python / PyQt6 (assistant de configuration + tray), QML (plasmoid KDE), et Bash (script d'orchestration principal).

Les artefacts de build sont packagés en .deb, .rpm, PKGBUILD Arch, et un tarball portable. Ce guide couvre la structure du dépôt, les features Cargo, les scripts de build, les harnais de test, l'i18n et le workflow de contribution.

Structure du dépôt

dictee/                         # racine du dépôt git
├── Cargo.toml                  # Workspace Rust
├── src/                        # Rust — moteur ASR (bibliothèque + binaires)
│   ├── lib.rs                  # API publique
│   ├── audio.rs                # WAV, STFT, mel-spectrogrammes
│   ├── parakeet_tdt.rs         # Modèle TDT (25 langues)
│   ├── canary.rs               # Modèle Canary AED
│   ├── nemotron.rs             # Streaming Nemotron (EN seul)
│   ├── sortformer.rs           # Diarisation (4 locuteurs)
│   ├── model*.rs, decoder*.rs  # Wrappers ONNX
│   ├── timestamps.rs           # Alignement token→mot→phrase
│   └── bin/                    # Exécutables
│       ├── transcribe.rs               # CLI batch
│       ├── transcribe_daemon.rs        # Serveur socket Unix
│       ├── transcribe_client.rs        # Client daemon + enregistrement micro
│       ├── transcribe_diarize.rs       # TDT + Sortformer
│       ├── transcribe_stream_diarize.rs  # Nemotron + Sortformer
│       └── transcribe_diarize_batch.rs # Pipeline chunked (v1.3 finale)
├── dictee                      # Script shell principal (source de vérité)
├── dictee-setup.py             # Assistant de configuration PyQt6
├── dictee-tray.py              # Icône tray PyQt6
├── plasmoid/                   # Widget KDE Plasma 6
├── po/                         # Traductions gettext (setup + tray)
├── pkg/                        # Arbre dpkg-deb (artefact, PAS source de vérité)
├── tests/                      # Suites de tests
├── build-deb.sh                # Build .deb (CPU + CUDA)
├── build-rpm.sh                # Build .rpm (CPU + CUDA)
├── PKGBUILD                    # Paquet Arch
└── install.sh / uninstall.sh

Source de vérité

Les fichiers à la racine du dépôt (dictee, dictee-setup.py, dictee-tray.py) sont la source de vérité.

build-deb.sh les copie dans pkg/ au moment du build. Ne jamais éditer les fichiers dans pkg/ directement — ils seront écrasés au prochain build.

Compiler depuis les sources

Moteur ASR Rust

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

# CPU seul (défaut)
cargo build --release

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

Binaires de sortie dans target/release/ :

libparakeet_rs.so (bibliothèque, pour futurs bindings)
transcribe, transcribe-daemon, transcribe-client
transcribe-diarize, transcribe-stream-diarize, transcribe-diarize-batch

Features Cargo

Déclarées dans Cargo.toml :

Feature	Défaut	But
`cpu`	✅	Execution provider CPU
`ort-defaults`	✅	Défauts sensés ONNX Runtime
`cuda`	❌	Execution provider CUDA 12
`tensorrt`	❌	Optimisation TensorRT (expérimental)
`coreml`	❌	Apple CoreML (macOS-only, inutilisé dans dictée)
`directml`	❌	DirectX 12 (Windows-only, inutilisé)
`openvino`	❌	Intel OpenVINO
`webgpu`	❌	WebGPU (usage navigateur)
`nnapi`	❌	Android NNAPI (inutilisé)
`sortformer`	❌	Diarisation locuteurs via Sortformer

Combos typiques :

Machine dev : --features cuda,sortformer
Build CI CPU : (défaut, pas de features)
Build CI CUDA : --features cuda,sortformer

UI Python

Pas d'étape de build — les fichiers dictee-setup.py et dictee-tray.py sont interprétés à l'exécution.

Dépendances (installer pour développement) :

pip install PyQt6 PyQt6-WebEngine text2num faster-whisper vosk

Plasmoid Plasma

Install dev (pas besoin de packaging) :

kpackagetool6 -t Plasma/Applet -i plasmoid/package

Réinstaller après édition :

kpackagetool6 -t Plasma/Applet -u plasmoid/package
# Redémarrer plasmashell si le widget est déjà sur un panneau :
killall -15 plasmashell && kstart plasmashell &

Builds de paquets

Build `.deb`

./build-deb.sh

Produit :

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 (tarball portable)

Étapes clés :

cargo build --release (variante CPU) + cargo build --release --features cuda,sortformer (variante CUDA)
Copier les binaires Rust dans pkg/dictee/usr/bin/
Copier les scripts shell (dictee, dictee-postprocess, etc.) dans pkg/dictee/usr/bin/
Copier les scripts Python (dictee-setup.py → /usr/bin/dictee-setup) — note : renommé sans .py
Copier le plasmoid dans pkg/dictee-plasmoid/usr/share/dictee/dictee.plasmoid
Build variante CUDA : intégrer les libs CUDA via venv pip (depuis v1.3)
dpkg-deb --build pkg/dictee-cpu etc.

Build `.rpm`

./build-rpm.sh

Mêmes sorties mais .rpm. Utilise rpmbuild avec un fichier spec.

Arch

makepkg -si

Utilise PKGBUILD à la racine du dépôt. Build depuis les sources, pas de binaires pré-compilés.

Internes du pipeline audio

Microphone (PipeWire)
   ↓ parecord --format=s16le --rate=48000 --channels=1
   ↓
/dev/shm/.dictee_rec.wav  (capture brute)
   ↓ rééchantillonnage sox à 16 kHz mono
   ↓
/dev/shm/.dictee_rec_16k.wav
   ↓ transcribe-client envoie via socket Unix
   ↓
Socket Unix : $XDG_RUNTIME_DIR/transcribe.sock
   ↓
transcribe-daemon (Rust)
   ↓
src/audio.rs : preemphasis(0.97) → STFT(n_fft=512, hop=160, win=400, Hann)
   ↓
Banque filtres mel (128 bins, Slaney, garde log 5.96e-8)
   ↓
Tenseur ONNX (1 × 128 × T)
   ↓
Encodeur (FastConformer) → Décodeur (TDT)
   ↓
Texte (avec ponctuation native)
   ↓
Réponse socket Unix
   ↓
Script shell dictee → dictee-postprocess → dotool type

Source complète : src/audio.rs (côté Rust), pkg/dictee/usr/bin/dictee-transcribe (wrapper Python).

État runtime & IPC

Fichiers d'état

Voir CLI-Reference#fichiers-détat pour la liste complète. Sûr multi-utilisateur via suffixe $UID.

Protocole socket

Le daemon écoute sur $XDG_RUNTIME_DIR/transcribe.sock. Le protocole est line-based :

Requête :

TRANSCRIBE /chemin/vers/audio.wav [lang=fr] [translate_to=en]

Réponse :

OK <payload-json>

Le payload inclut : texte de transcription, timestamps word-level, labels locuteurs (si diarisation), langue détectée, confiance.

Implémentation dans src/bin/transcribe_daemon.rs.

Tests

Tests unitaires (Rust)

cargo test
cargo test --features sortformer

Tests post-traitement (Python)

682 tests dans tests/test-postprocess.py — 12 étapes pipeline × 7 langues × cas limites :

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

Tests pipeline (Python)

148 tests dans tests/test-pipeline.py — pipeline transcription complet avec ASR mocké :

python -m unittest test-pipeline.py -v

Benchmark WER

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

Tests manuels UI

docs/test-checklist-ui-pipeline.md — 39 checks UI
docs/test-protocol-vocal.md — 38 dictées vocales à vérifier

CI

GitHub Actions lance tous les tests automatisés à chaque push :

Post-traitement (XDG_CONFIG_HOME isolé)
Pipeline
Tests unitaires Rust
msgfmt --check sur tous les .po

Internationalisation

gettext (setup + tray)

dictee-setup.py et dictee-tray.py utilisent gettext avec domaine dictee et catalogues dans po/ :

po/dictee.pot — template (régénéré depuis les chaînes source via xgettext)
po/{fr,de,es,it,uk,pt}.po — traductions
po/{lang}/LC_MESSAGES/dictee.mo — compilé (généré par msgfmt)

Workflow :

# Extraire nouvelles chaînes dans le template
xgettext -L Python -o po/dictee.pot dictee-setup.py dictee-tray.py

# Mettre à jour les traductions existantes
msgmerge --update po/fr.po po/dictee.pot

# Compiler en .mo
msgfmt po/fr.po -o po/fr/LC_MESSAGES/dictee.mo

Traductions plasmoid

Domaine séparé 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

Buildé par le packager plasmoid.

Traductions `.desktop`

Inline, p. ex. :

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

Contribuer

Workflow

Fork le dépôt sur github.com/rcspam/dictee
Créer une branche feature : git checkout -b feat/ma-feature
Commit avec commits conventionnels : feat(scope): description / fix(scope): description
Push et ouvrir une PR contre master
CI doit être verte
Review de code par le mainteneur

Style de commit

Exemples du 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

Ajouter un backend ASR

Créer src/<backend>.rs avec le wrapper du modèle ONNX
Ajouter un binaire dans src/bin/ ou étendre transcribe_daemon pour le supporter
Créer une unité systemd à pkg/dictee/usr/lib/systemd/user/dictee-<backend>.service
Mettre à jour dictee-switch-backend pour reconnaître le nouveau nom de backend
Ajouter le support UI dans dictee-setup.py (combo backend ASR + logique téléchargement modèle)
Documenter dans ASR-Backends et CLI-Reference

Ajouter une nouvelle langue

Ajouter règles regex dans pkg/dictee/usr/share/dictee/rules.conf.default avec préfixe [xx]
Ajouter mot déclencheur de continuation dans continuation.conf.default
Ajouter traduction .po pour setup + tray : po/xx.po
Ajouter traduction plasmoid : plasmoid/package/contents/locale/xx/
Tester manuellement contre test-protocol-vocal.md

Étapes suivantes

CLI-Reference — tous les binaires documentés
ASR-Backends — vue d'ensemble des backends
Changelog — notes de release et roadmap
Troubleshooting — déboguer les problèmes courants

📖 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

fr Developer Guide

Guide Développeur

Table des matières

Structure du dépôt

Source de vérité

Compiler depuis les sources

Moteur ASR Rust

Features Cargo

UI Python

Plasmoid Plasma

Builds de paquets

Build .deb

Build .rpm

Arch

Internes du pipeline audio

État runtime & IPC

Fichiers d'état

Protocole socket

Tests

Tests unitaires (Rust)

Tests post-traitement (Python)

Tests pipeline (Python)

Benchmark WER

Tests manuels UI

CI

Internationalisation

gettext (setup + tray)

Traductions plasmoid

Traductions .desktop

Contribuer

Workflow

Style de commit

Ajouter un backend ASR

Ajouter une nouvelle langue

Étapes suivantes

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!

Uh oh!

Build `.deb`

Build `.rpm`

Traductions `.desktop`