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:

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:

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:

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:

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:

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é

ffmpeg -version

Test de commande

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

   # Ubuntu/Debian
   sudo apt-get install ffmpeg libavcodec-extra
   

2. Fichier d'entrée invalide: Vérifier le format et l'intégrité

   ffprobe input.wav
   

3. Répertoire de sortie inaccessible: Vérifier les permissions

   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)

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)

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)

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
• HLS Specification
• AAC Encoding Guide
• MP3 Encoding Guide

---

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