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)

// 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)

// 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)

// 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)

// 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