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

# 🎬 Commandes FFmpeg - Documentation technique

**Date**: 2025-01-27  
**Version**: 0.2.0

---

## Vue d'ensemble

Ce document décrit les commandes FFmpeg générées par le `FfmpegCommandBuilder` pour chaque codec et format de sortie.

---

## Format HLS (HTTP Live Streaming)

### Structure générale

Toutes les commandes HLS suivent cette structure:

```bash
ffmpeg -y \
  -hide_banner \
  -nostats \
  -i {input_file} \
  -c:a {codec} \
  -b:a {bitrate} \
  -ar {sample_rate} \
  -ac {channels} \
  -f hls \
  -hls_time {segment_duration} \
  -hls_playlist_type vod \
  -hls_list_size 0 \
  -hls_segment_filename {segment_pattern} \
  {output_playlist}
```

### Options HLS

- `-f hls`: Format de sortie HLS
- `-hls_time {seconds}`: Durée de chaque segment (défaut: 6 secondes)
- `-hls_playlist_type vod`: Type VOD (Video On Demand) - liste complète
- `-hls_list_size 0`: Liste complète des segments (0 = tous)
- `-hls_segment_filename {pattern}`: Pattern de nommage des segments

---

## Codecs supportés

### AAC (Advanced Audio Coding)

**Commande complète**:
```bash
ffmpeg -y -hide_banner -nostats \
  -i input.wav \
  -c:a aac \
  -b:a 192000 \
  -ar 44100 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_list_size 0 \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8
```

**Paramètres**:
- Codec: `aac` (encodeur natif FFmpeg)
- Bitrate: 64-320 kbps (selon profil)
- Sample rate: 22.05-48 kHz
- Channels: 1 (mono) ou 2 (stéréo)

**Avantages**:
- Compatibilité maximale (iOS, Safari, Chrome, Firefox)
- Bonne qualité à bas débit
- Support HE-AAC pour très bas débit

---

### MP3 (MPEG-1 Audio Layer 3)

**Commande complète**:
```bash
ffmpeg -y -hide_banner -nostats \
  -i input.wav \
  -c:a libmp3lame \
  -b:a 192000 \
  -ar 44100 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_list_size 0 \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8
```

**Paramètres**:
- Codec: `libmp3lame` (encodeur LAME)
- Bitrate: 64-320 kbps
- Sample rate: 44.1 kHz (standard)
- Channels: 2 (stéréo)

**Avantages**:
- Compatibilité universelle
- Support VBR (Variable Bitrate)
- Qualité acceptable à 192+ kbps

**Limitations**:
- Pas de support natif dans certains navigateurs modernes
- Qualité inférieure à AAC à même bitrate

---

### Opus

**Commande complète**:
```bash
ffmpeg -y -hide_banner -nostats \
  -i input.wav \
  -c:a libopus \
  -b:a 192000 \
  -ar 48000 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_list_size 0 \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8
```

**Paramètres**:
- Codec: `libopus` (encodeur Opus)
- Bitrate: 64-320 kbps
- Sample rate: 48 kHz (recommandé)
- Channels: 2 (stéréo)

**Avantages**:
- Excellente qualité à bas débit
- Latence très faible
- Support natif dans Chrome, Firefox, Edge

**Limitations**:
- Pas de support natif dans Safari/iOS (nécessite WebM)
- HLS avec Opus nécessite container WebM (non standard)

**Note**: Pour HLS standard, Opus n'est pas recommandé. Utiliser AAC à la place.

---

### FLAC (Free Lossless Audio Codec)

**Commande complète**:
```bash
ffmpeg -y -hide_banner -nostats \
  -i input.wav \
  -c:a flac \
  -compression_level 5 \
  -ar 44100 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_list_size 0 \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8
```

**Paramètres**:
- Codec: `flac` (lossless)
- Compression level: 0-8 (5 = équilibre vitesse/compression)
- Sample rate: 44.1-96 kHz
- Channels: 2 (stéréo)

**Avantages**:
- Qualité lossless (sans perte)
- Compression efficace
- Support métadonnées

**Limitations**:
- Taille de fichiers importante
- Pas de support natif dans tous les navigateurs
- HLS avec FLAC non standard (utiliser MP4/FLAC à la place)

**Note**: Pour HLS, FLAC n'est pas recommandé. Utiliser AAC haute qualité ou MP3 à la place.

---

## Patterns de nommage

### Segments

Le pattern `segment_%05d.ts` génère:
- `segment_00001.ts`
- `segment_00002.ts`
- `segment_00003.ts`
- ...

**Format**: `%05d` = 5 chiffres avec zéros à gauche

### Playlist

Le fichier playlist est toujours nommé `index.m3u8` dans le répertoire de sortie.

---

## Options globales

### `-y`
Écrase les fichiers existants sans demander confirmation.

### `-hide_banner`
Masque la bannière d'information FFmpeg.

### `-nostats`
Désactive l'affichage des statistiques (on parse manuellement si besoin).

### `-i {input_file}`
Fichier d'entrée (WAV, MP3, FLAC, etc.).

---

## Options audio

### `-c:a {codec}`
Codec audio à utiliser.

### `-b:a {bitrate}`
Bitrate audio en bps (bits par seconde).

**Exemples**:
- `-b:a 64000` = 64 kbps
- `-b:a 128000` = 128 kbps
- `-b:a 192000` = 192 kbps
- `-b:a 320000` = 320 kbps

### `-ar {sample_rate}`
Sample rate (fréquence d'échantillonnage) en Hz.

**Valeurs courantes**:
- `22050` = 22.05 kHz (qualité téléphone)
- `44100` = 44.1 kHz (qualité CD)
- `48000` = 48 kHz (qualité professionnelle)

### `-ac {channels}`
Nombre de canaux.

**Valeurs**:
- `1` = Mono
- `2` = Stéréo

---

## Validation et erreurs

### Vérification FFmpeg installé

```bash
ffmpeg -version
```

### Test de commande

```bash
ffmpeg -y -hide_banner -nostats \
  -i test.wav \
  -c:a aac \
  -b:a 192000 \
  -ar 44100 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_list_size 0 \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8
```

### Erreurs communes

1. **Codec non disponible**: Installer les codecs manquants
   ```bash
   # Ubuntu/Debian
   sudo apt-get install ffmpeg libavcodec-extra
   ```

2. **Fichier d'entrée invalide**: Vérifier le format et l'intégrité
   ```bash
   ffprobe input.wav
   ```

3. **Répertoire de sortie inaccessible**: Vérifier les permissions
   ```bash
   chmod 755 output_dir
   ```

---

## Optimisations

### Qualité vs Vitesse

- **Vitesse**: `-preset fast` (non utilisé actuellement, à ajouter)
- **Qualité**: Multi-pass encoding (non implémenté P0)

### Parallélisation

FFmpeg utilise automatiquement tous les cores disponibles pour l'encodage.

### Mémoire

- **Buffer size**: Ajustable via `-bufsize` (non utilisé actuellement)
- **Threads**: Ajustable via `-threads` (auto par défaut)

---

## Exemples par profil

### Profil "high" (192 kbps AAC)

```bash
ffmpeg -y -hide_banner -nostats \
  -i input.wav \
  -c:a aac \
  -b:a 192000 \
  -ar 44100 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_list_size 0 \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8
```

### Profil "medium" (128 kbps AAC)

```bash
ffmpeg -y -hide_banner -nostats \
  -i input.wav \
  -c:a aac \
  -b:a 128000 \
  -ar 44100 \
  -ac 2 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_list_size 0 \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8
```

### Profil "low" (64 kbps AAC mono)

```bash
ffmpeg -y -hide_banner -nostats \
  -i input.wav \
  -c:a aac \
  -b:a 64000 \
  -ar 22050 \
  -ac 1 \
  -f hls \
  -hls_time 6 \
  -hls_playlist_type vod \
  -hls_list_size 0 \
  -hls_segment_filename segment_%05d.ts \
  index.m3u8
```

---

## Références

- [FFmpeg Documentation](https://ffmpeg.org/documentation.html)
- [HLS Specification](https://tools.ietf.org/html/rfc8216)
- [AAC Encoding Guide](https://trac.ffmpeg.org/wiki/Encode/AAC)
- [MP3 Encoding Guide](https://trac.ffmpeg.org/wiki/Encode/MP3)

---

**Note**: Pour des optimisations avancées (multi-pass, hardware acceleration), voir la roadmap P1/P2.