veza/veza-stream-server/docs/AUDIT_STREAM_PIPELINE.md

# 🔍 AUDIT STRUCTURÉ - Moteur d'encodage audio veza-stream-server

**Date**: 2025-01-27  
**Mission**: P0 - Rendre le stream-server fonctionnel (encodage audio & pipeline FFmpeg)

---

## 1. FONCTIONNALITÉS ACTUELLES

### 1.1 Ce qui est réellement implémenté

#### ✅ `src/transcoding/pipeline/queue.rs`
- **File d'attente prioritaire** avec 3 niveaux (Urgent, Normal, Background)
- Utilise `tokio::sync::mpsc` avec capacité configurable (défaut: 100)
- Méthode `submit()` avec backpressure (retourne `QueueFull` si saturée)
- Méthode `next_job()` avec stratégie de priorité stricte (Urgent > Normal > Background)
- **État**: ✅ **Fonctionnel**

#### ✅ `src/transcoding/pipeline/job.rs`
- Structure `TranscodingJob` complète avec:
  - ID, track_id, input_path, output_dir
  - QualityProfile, priority, status
  - Timestamps (created_at, started_at, completed_at)
  - Retry logic (retry_count, can_retry)
  - Progress tracking (progress_percent)
- États: `Pending`, `Processing`, `Completed`, `Failed(String)`, `Cancelled`
- Méthodes: `mark_started()`, `mark_completed()`, `mark_failed()`
- **État**: ✅ **Fonctionnel**

#### ✅ `src/transcoding/pipeline/worker.rs`
- Structure `TranscodingWorker` avec ID
- Méthode `process()` qui:
  - Construit la commande FFmpeg via `FfmpegCommandBuilder`
  - Exécute avec timeout (5 minutes)
  - Gère les erreurs et retry
- **État**: ⚠️ **Partiellement fonctionnel** (TODOs présents)

#### ✅ `src/transcoding/ffmpeg/command_builder.rs`
- Builder pattern pour commandes FFmpeg
- Support: input, output, codec, bitrate, sample_rate, channels, container
- Support HLS basique: `-f hls`, `-hls_time`, `-hls_playlist_type vod`
- Génération de noms de segments: `segment_%05d.ts`
- **État**: ⚠️ **Partiellement fonctionnel** (HLS incomplet)

#### ✅ `src/transcoding/engine.rs`
- `TranscodingEngine` avec:
  - Queue prioritaire (capacité 1000)
  - Worker pool (configurable)
  - Méthode `start()` qui lance les workers en arrière-plan
  - Méthode `submit()` pour enqueue un job
- **État**: ⚠️ **Partiellement fonctionnel** (pas de notification de résultats)

#### ✅ `src/transcoding/codecs/profiles.rs`
- `QualityProfile` avec profils prédéfinis:
  - `hi_res()`: 320kbps, 48kHz, Stereo, AAC
  - `high()`: 192kbps, 44.1kHz, Stereo, AAC
  - `medium()`: 128kbps, 44.1kHz, Stereo, AAC
  - `low()`: 64kbps, 22.05kHz, Mono, AAC
- Tous configurés pour HLS avec `hls_segment_time: Some(6)`
- **État**: ✅ **Fonctionnel**

#### ✅ `src/transcoding/codecs/mod.rs`
- Enum `AudioCodec`: MP3, AAC, OPUS, FLAC, WAV
- Enum `ContainerFormat`: MP3, MP4, OGG, FLAC, WAV, HLS
- Implémentation `Display` pour conversion en noms FFmpeg
- **État**: ✅ **Fonctionnel**

### 1.2 Ce qui est déclaré comme TODO

#### ❌ `src/core/encoder.rs` (ligne 253)
```rust
// TODO: Implémentation réelle des encodeurs
```
- Pool d'encodeurs initialisé mais **vide**
- Aucun encodeur réel (Opus, AAC, MP3, FLAC) n'est instancié

#### ❌ `src/core/encoder.rs` (ligne 459)
```rust
// TODO: Implémenter le thread de traitement en temps réel
```
- `EncoderPipeline::start_processing()` ne fait rien
- Aucun traitement audio réel

#### ⚠️ `src/transcoding/pipeline/worker.rs` (ligne 74)
```rust
// TODO: Kill process ? Command::status() wait for completion.
```
- En cas de timeout, le processus FFmpeg n'est pas tué
- Risque de fuite de processus

#### ⚠️ `src/transcoding/engine.rs` (ligne 38)
```rust
// TODO: Notifier le résultat via EventBus ou Callback
```
- Les résultats des jobs ne sont pas notifiés
- Pas de callback pour mettre à jour l'état

### 1.3 Ce qui est incorrect ou incohérent

#### 🔴 Problème majeur: Routes API manquantes
- **Aucune route** `/v1/stream/transcode` dans `main.rs`
- **Aucune route** `/v1/stream/job/{id}` pour récupérer l'état
- **Aucune route** `/v1/stream/hls/{job_id}/index.m3u8` pour servir HLS
- La route `/internal/jobs/transcode` existe mais utilise `compression_engine` au lieu de `transcoding_engine`

#### 🔴 Problème: TranscodingEngine non intégré dans AppState
- `AppState` ne contient **pas** de `TranscodingEngine`
- Impossible d'accéder au moteur depuis les routes

#### 🔴 Problème: Command Builder HLS incomplet
- Le builder génère `segment_%05d.ts` mais ne configure pas correctement:
  - Le pattern de nommage des segments
  - La structure du répertoire de sortie
  - Le manifest HLS (`index.m3u8`) n'est pas correctement configuré

#### ⚠️ Problème: Pas de stockage d'état des jobs
- Les jobs sont traités mais leur état n'est **pas persisté**
- Impossible de récupérer l'état d'un job après soumission
- Pas de base de données ou de cache pour stocker les jobs

#### ⚠️ Problème: Worker ne met pas à jour le job correctement
- Le worker retourne un `TranscodingJob` modifié mais:
  - Il n'est pas stocké nulle part
  - L'appelant ne peut pas récupérer le résultat

---

## 2. MANQUES FONCTIONNELS CRITIQUES (P0)

### 2.1 FFmpeg non utilisé correctement
- ❌ Le command builder génère des commandes mais:
  - Le format HLS n'est pas complet (manque `-hls_list_size 0` pour VOD)
  - Pas de gestion des segments existants
  - Pas de validation que FFmpeg est installé

### 2.2 Pipeline inactif
- ❌ Le `TranscodingEngine` n'est **jamais démarré** dans `main.rs`
- ❌ Aucun job n'est jamais soumis
- ❌ Les workers tournent mais ne traitent rien

### 2.3 Absence de retour asynchrone
- ❌ Pas de mécanisme pour:
  - Récupérer l'état d'un job après soumission
  - Recevoir une notification quand un job est terminé
  - Gérer les erreurs de manière centralisée

### 2.4 Absence d'événements d'état
- ❌ Pas de transitions d'état visibles:
  - `Queued → Processing → Done`
  - `Queued → Processing → Error`
- ❌ Pas de logs structurés pour suivre les jobs

### 2.5 Dossier d'output HLS non structuré
- ❌ Pas de structure claire pour les outputs:
  - Où sont stockés les segments `.ts`?
  - Où est le manifest `index.m3u8`?
  - Comment servir les fichiers via HTTP?

---

## 3. CONTRAT MANQUANT

### 3.1 API REST incomplète

#### ❌ POST `/v1/stream/transcode`
**Manquant**: Route pour upload + paramètres de transcodage
- Input: `file` (multipart), `codec`, `bitrate`, `quality_profile`
- Output: `{ "job_id": "uuid", "status": "queued" }`

#### ❌ GET `/v1/stream/job/{id}`
**Manquant**: Route pour récupérer l'état d'un job
- Output: `{ "id": "uuid", "status": "processing", "progress": 45.5, ... }`

#### ❌ GET `/v1/stream/hls/{job_id}/index.m3u8`
**Manquant**: Route pour servir le manifest HLS
- Output: Contenu du fichier `index.m3u8`

#### ❌ GET `/v1/stream/hls/{job_id}/{segment}`
**Manquant**: Route pour servir les segments `.ts`
- Output: Contenu binaire du segment

### 3.2 Absence d'API pour récupérer l'état du transcodage
- Pas de mécanisme pour:
  - Lister tous les jobs
  - Filtrer par statut
  - Récupérer l'historique

### 3.3 Manque de dossier d'output structuré HLS
- Structure attendue:
```
output_dir/
  {job_id}/
    index.m3u8          # Master playlist
    segment_00001.ts
    segment_00002.ts
    ...
```
- Actuellement: **Non défini**

---

## 4. RÉSUMÉ DES BLOQUANTS P0

| Bloquant | Fichier | Description | Impact |
|----------|---------|------------|--------|
| 🔴 **P0** | `main.rs` | TranscodingEngine non initialisé dans AppState | Aucun transcodage possible |
| 🔴 **P0** | `main.rs` | Routes API `/v1/stream/transcode` et `/v1/stream/job/{id}` manquantes | Impossible de soumettre/récupérer des jobs |
| 🔴 **P0** | `src/transcoding/engine.rs` | Pas de stockage d'état des jobs | Impossible de suivre l'état |
| 🔴 **P0** | `src/transcoding/pipeline/worker.rs` | FFmpeg timeout ne tue pas le processus | Fuite de ressources |
| 🔴 **P0** | `src/transcoding/ffmpeg/command_builder.rs` | Configuration HLS incomplète | Segments mal générés |
| 🟠 **P1** | `src/core/encoder.rs` | Pool d'encodeurs vide | Pas d'encodage natif (mais FFmpeg fonctionne) |
| 🟠 **P1** | `src/transcoding/engine.rs` | Pas de notification de résultats | Pas de callback/EventBus |

---

## 5. RECOMMANDATIONS

### 5.1 Actions immédiates (P0)
1. ✅ Intégrer `TranscodingEngine` dans `AppState`
2. ✅ Créer routes API `/v1/stream/transcode` et `/v1/stream/job/{id}`
3. ✅ Implémenter stockage d'état des jobs (HashMap en mémoire pour P0)
4. ✅ Compléter command builder HLS
5. ✅ Fixer timeout FFmpeg (kill process)

### 5.2 Actions secondaires (P1)
1. Implémenter notification de résultats (EventBus ou callback)
2. Ajouter validation FFmpeg installé
3. Structurer dossier output HLS
4. Ajouter logs structurés

### 5.3 Actions futures (P2)
1. Implémenter encodeurs natifs (Opus, AAC) dans `encoder.rs`
2. Ajouter support multi-bitrate adaptatif
3. Persister jobs en base de données
4. Ajouter métriques Prometheus pour jobs

---

**Prochaine étape**: Phase 2 - Design du pipeline minimal mais robuste