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

🎯 DESIGN - Pipeline d'encodage audio minimal mais robuste

Date: 2025-01-27
Mission: P0 - Rendre le stream-server fonctionnel

---

1. ARCHITECTURE

1.1 Vue d'ensemble

┌─────────────────┐
│   API Routes    │
│  /transcode     │
│  /job/{id}      │
│  /hls/{id}/...  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ TranscodingEngine│
│  - Queue         │
│  - JobManager    │
│  - WorkerPool    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Worker Pool    │
│  (N workers)    │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  FFmpeg Process │
│  (HLS output)   │
└─────────────────┘

1.2 Composants principaux

TranscodingEngine

• Responsabilité: Orchestrer le transcodage
• Composants:
  • PriorityQueue: File d'attente des jobs
  • JobManager: Stockage et suivi des jobs
  • WorkerPool: Pool de workers parallèles

JobManager

• Responsabilité: Stocker et suivre l'état des jobs
• Stockage: HashMap<Uuid, TranscodingJob> (en mémoire pour P0)
• Méthodes:
  • enqueue(job) -> Uuid
  • get_status(job_id) -> Option<JobStatus>
  • update_status(job_id, status)

WorkerPool

• Responsabilité: Traiter les jobs en parallèle
• Implémentation: Tokio tasks avec canal async
• Workers: N workers (configurable, défaut: num_cpus())

Pipeline

• Responsabilité: Exécuter FFmpeg et gérer les erreurs
• Fonction: transcode_to_hls(input_path, output_dir, codec, bitrate) -> Result<TranscodeResult>

---

2. PIPELINE D'ENCODAGE

2.1 Fonction principale

async fn transcode_to_hls(
    input_path: &Path,
    output_dir: &Path,
    codec: AudioCodec,
    bitrate: u32,
    profile: &QualityProfile,
) -> Result<TranscodeResult, TranscodeError>

Étapes:

1. Créer le répertoire de sortie {output_dir}/{job_id}/
2. Construire la commande FFmpeg
3. Exécuter FFmpeg avec timeout
4. Vérifier que index.m3u8 et segments existent
5. Retourner TranscodeResult avec chemins

2.2 Structure de sortie HLS

{output_dir}/
  {job_id}/
    index.m3u8          # Master playlist HLS
    segment_00001.ts
    segment_00002.ts
    segment_00003.ts
    ...

2.3 Format du manifest HLS

#EXTM3U
#EXT-X-VERSION:3
#EXT-X-TARGETDURATION:6
#EXT-X-MEDIA-SEQUENCE:0
#EXTINF:6.0,
segment_00001.ts
#EXTINF:6.0,
segment_00002.ts
...
#EXT-X-ENDLIST

---

3. COMMAND BUILDER FFMPEG

3.1 Arguments par codec

AAC

ffmpeg -i input.wav \
  -c:a aac \
  -b:a 192k \
  -ar 44100 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8

MP3

ffmpeg -i input.wav \
  -c:a libmp3lame \
  -b:a 192k \
  -ar 44100 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8

Opus

ffmpeg -i input.wav \
  -c:a libopus \
  -b:a 192k \
  -ar 48000 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8

FLAC

ffmpeg -i input.wav \
  -c:a flac \
  -compression_level 5 \
  -ar 44100 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8

3.2 Améliorations du builder

• ✅ Ajouter -hls_list_size 0 pour VOD (liste complète)
• ✅ Valider que FFmpeg est installé au démarrage
• ✅ Gérer les erreurs de construction de commande

---

4. GESTION DES ERREURS

4.1 Types d'erreurs

#[derive(Debug, thiserror::Error)]
pub enum TranscodeError {
    #[error("Input file not found: {0}")]
    InputNotFound(PathBuf),
    
    #[error("FFmpeg execution failed: {0}")]
    FfmpegError(String),
    
    #[error("Transcoding timed out after {0} seconds")]
    Timeout(u64),
    
    #[error("Output directory creation failed: {0}")]
    OutputDirError(String),
    
    #[error("HLS manifest not generated")]
    ManifestMissing,
    
    #[error("Insufficient disk space")]
    DiskSpaceError,
}

4.2 Gestion du timeout

• Timeout: 5 minutes par défaut
• Action: Tuer le processus FFmpeg si timeout
• Implémentation: Utiliser Command::kill() sur le child process

4.3 Retry logic

• Max retries: 3
• Conditions de retry:
  • Erreur temporaire (timeout, IO error)
  • Pas de retry sur erreur permanente (fichier corrompu)

---

5. API REST

5.1 POST /v1/stream/transcode

Request:

{
  "file": "<multipart file>",
  "codec": "aac",
  "bitrate": 192000,
  "quality_profile": "high"
}

Response:

{
  "job_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "queued",
  "message": "Job submitted successfully"
}

5.2 GET /v1/stream/job/{id}

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "progress": 45.5,
  "created_at": "2025-01-27T10:00:00Z",
  "started_at": "2025-01-27T10:00:05Z",
  "completed_at": null,
  "error": null
}

5.3 GET /v1/stream/hls/{job_id}/index.m3u8

Response: Contenu du fichier index.m3u8 avec Content-Type: application/vnd.apple.mpegurl

5.4 GET /v1/stream/hls/{job_id}/{segment}

Response: Contenu binaire du segment .ts avec Content-Type: video/mp2t

---

6. INTÉGRATION DANS APPSTATE

6.1 Ajout de TranscodingEngine

pub struct AppState {
    // ... existing fields ...
    pub transcoding_engine: Arc<TranscodingEngine>,
}

6.2 Initialisation dans AppState::new()

let transcoding_engine = Arc::new(
    TranscodingEngine::new(num_cpus::get())
);
transcoding_engine.start();

---

7. LOGS STRUCTURÉS

7.1 Événements à logger

• job_queued: Job soumis
• job_started: Worker commence le traitement
• job_progress: Progression (toutes les 10%)
• job_completed: Job terminé avec succès
• job_failed: Job échoué avec erreur

7.2 Format des logs

tracing::info!(
    job_id = %job.id,
    status = "queued",
    priority = ?job.priority,
    "Job queued for transcoding"
);

---

8. TESTS

8.1 Tests unitaires

• ✅ Test command builder pour chaque codec
• ✅ Test pipeline avec fichier WAV de test
• ✅ Test job manager en mémoire

8.2 Tests d'intégration

• ✅ Upload fichier → job → index.m3u8 généré
• ✅ Vérification existence segments
• ✅ Test timeout FFmpeg

---

9. LIMITATIONS P0

• ❌ Pas de multi-bitrate adaptatif (ABR)
• ❌ Pas de DRM
• ❌ Pas de persistance en base de données (mémoire uniquement)
• ❌ Pas de métriques Prometheus détaillées
• ❌ Pas de cleanup automatique des anciens jobs

---

Prochaine étape: Phase 3 - Implémentation