# 🎙️ TranscribeStation

**Gestionnaire de transcription audio** avec support natif des pédaliers Olympus.  
Interface inspirée de Philips SpeechExec et Olympus ODMS.

> **JT-Tools by Johnny** — développé pour **H3Campus**

![Python](https://img.shields.io/badge/Python-3.10%2B-blue?logo=python)
![PyQt6](https://img.shields.io/badge/PyQt6-6.5%2B-green?logo=qt)
![Licence](https://img.shields.io/badge/Licence-MIT-yellow)
![Version](https://img.shields.io/badge/Version-1.0.0-informational)
![Plateforme](https://img.shields.io/badge/Plateforme-Linux%20%7C%20Windows-lightgrey)

---

## Sommaire

- [Fonctionnalités](#fonctionnalités)
- [Capture d'écran](#capture-décran)
- [Prérequis](#prérequis)
- [Installation](#installation)
- [Configuration du pédalier](#configuration-du-pédalier-udev)
- [Utilisation](#utilisation)
- [Raccourcis clavier](#raccourcis-clavier)
- [Formats audio supportés](#formats-audio-supportés)
- [Paramètres](#paramètres)
- [Compilation en binaire](#compilation-en-binaire)
- [Architecture](#architecture)
- [Limitations connues](#limitations-connues)
- [Dépannage](#dépannage)

---

## Fonctionnalités

| Catégorie | Détails |
|-----------|---------|
| **Lecteur audio** | Lecture, pause, stop, rembobinage, avance rapide, vitesse (0.5× → 2.0×) |
| **Volume** | Slider toolbar + muet, raccourcis `+` / `-` / `M` |
| **Forme d'onde** | Waveform interactive (clic pour se positionner) via NumPy + SoundFile |
| **Navigation** | Fichier précédent / suivant depuis la toolbar et le clavier |
| **Gestion fichiers** | Navigation par dossiers, ajout manuel, filtres par statut |
| **Statuts** | À faire · En cours · Suspendu · Terminé — persistés entre sessions |
| **Pédaliers** | RS27H/N · RS28H/N · RS31H/N — reconnexion automatique si débranché |
| **Persistance** | Base de données JSON locale (`.transcribe_station.json`) par dossier |
| **Interface** | Thème sombre, toolbar emoji, séparateur redimensionnable, barre de statut |
| **Raccourcis** | 15 raccourcis clavier couvrant transport, volume, vitesse et navigation |
| **Compilation** | Binaire autonome Linux + Windows via `build.py` (PyInstaller) |
| **Raccourcis OS** | Entrée GNOME (`.desktop` + icône XDG) et menu Démarrer Windows (`.lnk`) |

---

## Capture d'écran

```
┌──────────────────────────────────────────────────────────────────────────────┐
│  📂 ➕ 💾  │  ⏮️ ⏪️ ▶️ ⏩️ ⏭️ ⏹️  │  ⏫ ⏬  │  🔇 ══════  │  ⚙️ ❓   🦶 Connecté │
├─────────────┬────────────────────────────────────────────────────────────────┤
│ 📋 Dictées  │  Nom du fichier     N°   Auteur   Type    Durée   Statut       │
│  📥 À faire │  ▌ DICT0070.wav     69   DUPONT   LETTRE  05:00   À faire      │
│  🔵 En cours│  ▌ DICT0007.wav     55   MARTIN   GEN.    12:30   Terminé      │
│  ✅ Terminé │  ▌ DICT0008.wav     56   MARTIN   GEN.    08:15   En cours     │
│  ⏸ Suspendu │                                                                │
│             │                                                                │
│ 📨 Dossiers │                                                                │
│  📂 2024-Q4 │                                                                │
│  📂 2025-Q1 │                                                                │
├─────────────┴────────────────────────────────────────────────────────────────┤
│  ▓▓▓▓▓▒▒▒░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░  ← waveform interactive      │
│  01:23 ────────●─────────────────────────────── 05:00                        │
│  Vitesse: 1.0×   Volume: ████████░░░   🦶 RS27H/N connecté                  │
└──────────────────────────────────────────────────────────────────────────────┘
```

---

## Prérequis

### Système (Debian 12 / 13)

```bash
sudo apt-get install -y \
    python3 python3-pip python3-venv \
    libhidapi-dev libhidapi-hidraw0 libusb-1.0-0 \
    gstreamer1.0-plugins-good \
    gstreamer1.0-plugins-bad \
    gstreamer1.0-plugins-ugly \
    gstreamer1.0-libav \
    fonts-noto-color-emoji
```

> **GStreamer** est requis par PyQt6 QtMultimedia pour lire l'audio sous Linux.  
> **fonts-noto-color-emoji** assure le rendu des emojis dans la toolbar.

### Dépendances Python

| Paquet | Version min | Rôle | Optionnel |
|--------|-------------|------|-----------|
| `PyQt6` | 6.5 | Interface graphique + lecteur audio | Non |
| `numpy` | 1.24 | Traitement du signal pour la waveform | Oui |
| `soundfile` | 0.12 | Lecture des fichiers audio (waveform) | Oui |
| `hid` | 1.0.5 | Communication USB HID avec le pédalier | Oui |
| `Pillow` | 9.0 | Génération des icônes (compilation uniquement) | Oui |

> Sans `numpy`/`soundfile` : la waveform ne s'affiche pas, le reste fonctionne.  
> Sans `hid` : le support pédalier est désactivé (avertissement au démarrage).

---

## Installation

### Méthode rapide (script automatisé)

```bash
git clone https://github.com/h3campus/transcribe-station.git
cd transcribe-station
chmod +x install.sh
./install.sh
```

Le script `install.sh` effectue 6 étapes avec sortie colorée :

1. Installation des dépendances système (`apt-get`) incluant `libhidapi` et `fonts-noto-color-emoji`
2. Création de l'environnement virtuel Python (`.venv/`)
3. Mise à jour de `pip`
4. Installation des paquets Python — `PyQt6`, `numpy`, `soundfile`, `hid` (avec fallback `hidapi`)
5. Configuration udev pour le pédalier + ajout au groupe `plugdev`
6. Création du script `launch.sh`

### Méthode manuelle

```bash
# 1. Environnement virtuel
python3 -m venv .venv
source .venv/bin/activate

# 2. Dépendances Python
pip install PyQt6 numpy soundfile hid

# 3. Lancer
python transcribe_station.py
```

### Lancement

```bash
./launch.sh
# ou
source .venv/bin/activate && python transcribe_station.py
```

---

## Configuration du pédalier (udev)

Sans règle udev, l'accès au périphérique HID nécessite les droits root.

### Créer la règle

```bash
sudo tee /etc/udev/rules.d/99-olympus-pedal.rules << 'EOF'
SUBSYSTEM=="hidraw", ATTRS{idVendor}=="07b4", MODE="0666", GROUP="plugdev"
EOF

sudo udevadm control --reload-rules
sudo udevadm trigger
```

### Ajouter votre utilisateur au groupe `plugdev`

```bash
sudo usermod -aG plugdev $USER
# Déconnectez-vous et reconnectez-vous pour que le groupe soit actif
```

### Vérifier la détection

```bash
python3 -c "
import hid
for d in hid.enumerate():
    if d['vendor_id'] == 0x07B4:
        print(f\"PID={hex(d['product_id'])}  {d.get('product_string','?')}\")
"
```

Ou depuis l'application : **Périphérique → Détecter les périphériques**.

### Correspondance VID/PID

| Modèle | Vendor ID | Product ID |
|--------|-----------|------------|
| RS27H/N | `0x07B4` | `0x0110` |
| RS28H/N | `0x07B4` | `0x0111` |
| RS31H/N | `0x07B4` | `0x0112` |

> ⚠️ Ces Product IDs sont approximatifs. Utilisez la détection automatique puis
> ajustez dans **Outils → Paramètres → Pédalier**.

### Comportement des pédales

| Pédale | Appui court | Maintenu |
|--------|-------------|---------|
| **Gauche** (rewind) | Reculer 3 s | Rembobinage continu — pause auto, reprise au relâché |
| **Centre** (play) | Lecture / Pause | — |
| **Droite** (forward) | Avancer 3 s | Avance rapide continue |

---

## Utilisation

### Toolbar

| Bouton | Action |
|--------|--------|
| 📂 | Ouvrir un dossier (`Ctrl+O`) |
| ➕ | Ajouter des fichiers (`Ctrl+Shift+O`) |
| 💾 | Enregistrer la liste (`Ctrl+S`) |
| ⏮️ | Aller au début (`Home`) |
| ⏪️ | Reculer 3 s (`←`) |
| ▶️ | Lecture / Pause (`Espace`) |
| ⏩️ | Avancer 3 s (`→`) |
| ⏭️ | Aller à la fin (`End`) |
| ⏹️ | Stop (`S`) |
| ⏫ | Fichier précédent (`Ctrl+↑`) |
| ⏬ | Fichier suivant (`Ctrl+↓`) |
| 🔇 | Muet / Actif (`M`) |
| `══` | Slider volume (`+` / `-`) |
| ⚙️ | Paramètres (`Ctrl+,`) |
| ❓ | À propos |

### Ouvrir un dossier

**Fichier → Ouvrir un dossier** ou `Ctrl+O`

L'application scanne automatiquement les fichiers audio du dossier.  
Un fichier `.transcribe_station.json` est créé pour mémoriser les statuts.

### Lire un fichier

**Double-clic** sur une ligne du tableau, ou sélection + `Espace`.  
Le statut passe automatiquement à **En cours** à l'ouverture.

### Changer le statut d'un fichier

**Clic droit** sur une ligne → **Changer le statut**

| Couleur | Statut | Description |
|---------|--------|-------------|
| 🟡 | À faire | Non encore traité |
| 🔵 | En cours | Appliqué automatiquement à l'ouverture |
| ⚪ | Suspendu | Traitement interrompu |
| 🟢 | Terminé | Transcription complète |

### Sauvegarder

`Ctrl+S` ou **Fichier → Enregistrer la liste**.  
Sauvegarde automatique également à la fermeture de l'application.

---

## Raccourcis clavier

### Transport

| Raccourci | Action |
|-----------|--------|
| `Espace` | Lecture / Pause |
| `S` | Stop |
| `←` | Reculer de 3 s |
| `→` | Avancer de 3 s |
| `Home` | Aller au début |
| `End` | Aller à la fin |

### Volume & Vitesse

| Raccourci | Action |
|-----------|--------|
| `+` | Volume + 10 % |
| `-` | Volume − 10 % |
| `M` | Muet / Actif |
| `]` | Vitesse + (0.5× → 2.0×) |
| `[` | Vitesse − |

### Navigation fichiers

| Raccourci | Action |
|-----------|--------|
| `Ctrl+↑` | Fichier précédent dans la liste |
| `Ctrl+↓` | Fichier suivant dans la liste |

### Application

| Raccourci | Action |
|-----------|--------|
| `Ctrl+O` | Ouvrir un dossier |
| `Ctrl+Shift+O` | Ajouter des fichiers |
| `Ctrl+S` | Enregistrer la liste |
| `Ctrl+,` | Paramètres |
| `Ctrl+Q` | Quitter |

---

## Formats audio supportés

| Format | Extension | Waveform | Lecture |
|--------|-----------|----------|---------|
| WAV | `.wav` | ✅ | ✅ |
| MP3 | `.mp3` | ✅ | ✅ |
| FLAC | `.flac` | ✅ | ✅ |
| OGG Vorbis | `.ogg` | ✅ | ✅ |
| MP4 / M4A | `.mp4` `.m4a` | ✅ | ✅ |
| Olympus DSS | `.dss` | ❌ | ⚠️ selon codec GStreamer |
| Olympus DS2 | `.ds2` | ❌ | ⚠️ selon codec GStreamer |

> Conversion DSS/DS2 recommandée avant utilisation :
> ```bash
> ffmpeg -i fichier.dss fichier.wav
> ```

---

## Paramètres

**Outils → Paramètres** (`Ctrl+,`)

### Onglet Pédalier

| Paramètre | Description |
|-----------|-------------|
| Activer le support pédalier | Active/désactive la lecture HID au démarrage |
| Modèle | Profil VID/PID prédéfini (RS27H/N, RS28H/N, RS31H/N) |
| Vendor ID / Product ID | Valeurs hexadécimales personnalisables |
| Délai rembobinage/avance | Durée du saut clavier en ms (défaut : 3 000 ms) |
| Détecter | Lance la détection des périphériques Olympus connectés |

### Onglet Général

| Paramètre | Description |
|-----------|-------------|
| Auteur par défaut | Pré-rempli pour les nouveaux fichiers importés |
| Lecture auto à la sélection | Lance la lecture dès qu'un fichier est sélectionné |

---

## Compilation en binaire

Le script `build.py` produit un **exécutable autonome** (PyInstaller `--onefile`) et installe les raccourcis système sur Linux et Windows.

### Prérequis supplémentaires

```bash
pip install pyinstaller Pillow
```

### Commandes disponibles

```bash
# Build + installation raccourcis (OS auto-détecté)
python build.py

# Build Linux uniquement + raccourci GNOME
python build.py --linux

# Build Windows uniquement + raccourci Menu Démarrer
python build.py --windows

# Les deux (Linux natif + Windows via Wine si disponible)
python build.py --both

# Build sans créer de raccourcis
python build.py --no-install

# Installer le raccourci sans recompiler (binaire déjà présent)
python build.py --install-only

# Supprimer le raccourci GNOME
python build.py --uninstall

# Nettoyer les artefacts (build/ dist/ icon.*)
python build.py --clean
```

### Raccourcis créés — Linux (GNOME)

| Élément | Emplacement |
|---------|-------------|
| Icône PNG 256 px | `~/.local/share/icons/hicolor/256x256/apps/TranscribeStation.png` |
| Entrée applications | `~/.local/share/applications/TranscribeStation.desktop` |
| Raccourci bureau | `~/Bureau/TranscribeStation.desktop` |

Le fichier `.desktop` contient `Exec`, `Icon`, `Categories=Audio;AudioVideo;`, `StartupWMClass` et `Keywords`. Les caches `update-desktop-database` et `gtk-update-icon-cache` sont mis à jour automatiquement.

### Raccourcis créés — Windows (Menu Démarrer & Bureau)

| Raccourci | Emplacement |
|-----------|-------------|
| Menu Démarrer | `%APPDATA%\Microsoft\Windows\Start Menu\Programs\TranscribeStation.lnk` |
| Bureau | `%USERPROFILE%\Desktop\TranscribeStation.lnk` |

Les fichiers `.lnk` sont créés via **PowerShell + WScript.Shell** avec l'icône embarquée dans l'`.exe` (`IconLocation = exe,0`).

En cross-compilation depuis Linux, un script `dist/windows/install_shortcut.ps1` est généré pour exécution sur la machine cible :

```powershell
powershell -ExecutionPolicy Bypass -File dist\windows\install_shortcut.ps1
```

### Build Windows sans Wine (machine Windows native)

Copiez `transcribe_station.py` + `dist/build_windows.bat` sur la machine Windows et double-cliquez sur `build_windows.bat`. Le script fait tout en 4 étapes : dépendances pip, génération icône, PyInstaller, raccourcis.

---

## Architecture

```
transcribe_station.py
│
├── APP_NAME / APP_VERSION / APP_AUTHOR   Métadonnées (v1.0.0, Mars 2026)
├── PEDAL_PROFILES                        VID/PID RS27H · RS28H · RS31H
├── COLORS / STYLESHEET                   Thème sombre centralisé
│
├── DictationStatus (Enum)    TODO / IN_PROGRESS / SUSPENDED / DONE
├── DictationFile (dataclass) Modèle fichier + sérialisation JSON
│
├── FootPedalWorker (QThread) Boucle HID non-bloquante, reconnexion auto ×2 s
├── WaveformWidget (QWidget)  Rendu QPainter, seek par clic souris
├── PlayerPanel (QWidget)     QMediaPlayer + transport + volume + vitesse + pédalier
│   ├── toggle_play / stop_playback / toggle_mute
│   ├── volume_up / volume_down / set_volume
│   └── speed_up / speed_down
├── DictationTable            Table + monospace sur colonnes numériques + menu clic droit
├── FolderTree (QTreeWidget)  Arbre navigation + compteurs statuts (TODO/EN COURS/DONE)
├── SettingsDialog (QDialog)  Onglets Pédalier + Général
└── MainWindow (QMainWindow)  Orchestration, persistance, raccourcis clavier
    ├── _prev_file / _next_file   Navigation Ctrl+↑/↓
    └── _build_toolbar()          14 boutons emoji Noto Color Emoji + slider volume

build.py
├── generate_icons()               icon.png (256 px XDG) + icon.ico (multi-tailles)
├── build_linux()                  PyInstaller onefile → dist/linux/
├── build_windows()                PyInstaller windowed → dist/windows/
├── install_linux_shortcut()       .desktop + icône XDG + Bureau + mise à jour caches
└── install_windows_shortcut()     PowerShell WScript.Shell → .lnk ×2
```

**Source de vérité unique** : `DictationTable._files` — toutes les opérations
(ajout, sauvegarde, stats, affichage) passent par cette seule liste.

---

## Limitations connues

- **DSS/DS2** : formats propriétaires sans codec libre standard. Conversion recommandée : `ffmpeg -i in.dss out.wav`

- **Waveform** : le chargement de fichiers > 200 MB peut bloquer l'UI quelques secondes (pas de thread dédié dans cette version).

- **Reconnaissance vocale** : non intégrée. Compatible avec tout moteur externe (Whisper, Vosk, DeepSpeech…) en copier-coller.

- **Multi-fenêtre** : une seule instance par processus.

- **PID pédalier** : les Product IDs inclus sont approximatifs — à confirmer avec la détection automatique.

---

## Dépannage

### Le pédalier n'est pas détecté

```bash
# Vérifier que le device USB est visible
lsusb | grep -i "07b4\|olympus"

# Vérifier les permissions hidraw
ls -la /dev/hidraw*

# Tester en root (contournement udev)
sudo python transcribe_station.py
```

### Pas de son

```bash
# Vérifier les codecs GStreamer
gst-inspect-1.0 | grep -i "mp3\|wav\|flac"

# Installer les codecs manquants
sudo apt-get install gstreamer1.0-plugins-ugly gstreamer1.0-libav
```

### Les emojis toolbar ne s'affichent pas

```bash
sudo apt-get install fonts-noto-color-emoji
# Redémarrer l'application
```

### Erreur à l'import de `hid`

```bash
sudo apt-get install libhidapi-dev libhidapi-hidraw0
pip install hid
# Alternative :
pip install hidapi
```

### La waveform ne s'affiche pas

```bash
pip install numpy soundfile
```

### Le raccourci GNOME n'apparaît pas dans les applications

```bash
update-desktop-database ~/.local/share/applications
gtk-update-icon-cache -f -t ~/.local/share/icons/hicolor
# Déconnectez-vous / reconnectez-vous si nécessaire
```

### Le binaire PyInstaller ne se lance pas

```bash
# Vérifier les librairies manquantes
ldd dist/linux/TranscribeStation | grep "not found"

# Lancer avec logs
dist/linux/TranscribeStation 2>&1 | head -50
```

---

## Licence

MIT — © Mars 2026 H3Campus / JT-Tools by Johnny  
Voir [LICENSE](LICENSE) pour les détails.