Architecture
Structure interne du projet et modules Python.
Stack technique
murmurai est construit avec :
• Python 3.9+ — Langage principal (99.2% du code)
• faster-whisper — Transcription vocale (CTranslate2)
• pyobjc-framework-Quartz — Détection de touches macOS
• sounddevice + soundfile — Capture et traitement audio
• numpy — Traitement numérique des signaux audio
• rumps — Menu bar macOS
• Ollama (optionnel) — Modèles AI locaux pour le Mode Agent
• PyInstaller — Packaging en app standalone
Modules source
Le code source est organisé en modules dans le répertoire murmurai/ :
murmurai/ ├── __init__.py # Point d'entrée du package ├── app.py # Application principale, boucle push-to-talk │ # Détection hotkey, orchestration des modules ├── recorder.py # Capture audio via sounddevice │ # Gestion du microphone et du buffer ├── transcriber.py # Transcription via faster-whisper │ # Configuration du modèle, streaming ├── paster.py # Collage automatique via System Events │ # Simulation de Cmd+V à la position curseur ├── agent.py # Mode Agent — communication avec Ollama │ # Streaming réponses, annulation ├── hud.py # HUD overlay — affichage statut │ # (recording, transcribing, processing) ├── jargon.py # Fusion bilingue FR/EN │ # Dictionnaire de ~100 termes techniques └── (pyproject.toml) # Métadonnées, dépendances, entry point
Pipeline audio — Mode Transcript
Le flux de données du Mode Transcript suit un pipeline linéaire :
1. recorder.py — Capture l'audio du microphone en temps réel via sounddevice. L'audio est bufferisé en segments.
2. transcriber.py — Reçoit les segments audio et les transcrit via faster-whisper en mode streaming. Les résultats partiels sont accumulés.
3. jargon.py — Applique la fusion bilingue FR/EN et corrige les termes techniques via le dictionnaire de jargon.
4. paster.py — Prend le texte transcrit final et simule un Cmd+V pour le coller à la position du curseur.
5. app.py — Orchestre tout le pipeline : détecte l'appui/relâchement de la touche, démarre/arrête l'enregistrement, lance la transcription et déclenche le collage.
Pipeline audio — Mode Agent
Le Mode Agent étend le pipeline avec une étape Ollama :
1. recorder.py — Capture l'audio de l'instruction vocale.
2. transcriber.py — Transcrit l'instruction vocale.
3. agent.py — Récupère le texte sélectionné dans l'application active, construit un prompt combinant l'instruction vocale et la sélection, envoie le tout au modèle Ollama local. La réponse est streamée en temps réel.
4. paster.py — Remplace la sélection originale par la réponse d'Ollama.
5. hud.py — Affiche l'état du traitement (recording, transcribing, processing) tout au long du pipeline. L'utilisateur peut annuler à tout moment.
Système de jargon
Le module jargon.py gère la fusion bilingue FR/EN en post-traitement :
1. Le texte transcrit par Whisper est analysé mot par mot.
2. Chaque mot est comparé au dictionnaire de ~100 termes techniques intégrés.
3. Les termes français correspondant à du jargon technique anglais sont remplacés (ex. "commettre" → "commit").
4. La structure de phrase française est préservée — seuls les termes techniques sont corrigés.
Le dictionnaire intégré couvre les termes courants du développement logiciel, DevOps, et de l'infrastructure. Les utilisateurs peuvent ajouter leurs propres termes via ~/.config/murmurai/config.json.
Dépendances
Les dépendances principales :
• pyobjc-framework-Quartz (>=9.0) — Accès bas niveau à macOS (événements clavier, écran)
• sounddevice (>=0.4.6) — Interface Python vers PortAudio pour la capture audio
• soundfile (>=0.12.1) — Lecture/écriture de fichiers audio
• numpy (>=1.24.0) — Tableaux numériques pour le traitement du signal
• faster-whisper (>=1.0.0) — Implémentation CTranslate2 de Whisper
• rumps (>=0.4.0) — Menu bar macOS natif
Dépendances optionnelles :
• ollama — Client Python pour communiquer avec Ollama (Mode Agent)
• pyinstaller (>=6.0.0) — Pour la création d'apps standalone