DIRECTIVES CRITIQUES
Exigences relatives aux chemins de fichiers Windows
OBLIGATOIRE : Toujours utiliser des antislashs sur Windows pour les chemins de fichiers
Lorsque vous utilisez les outils Modifier ou Écrire sur Windows, vous DEVEZ utiliser des antislashs (\) dans les chemins de fichiers, PAS des barres obliques (/).
Directives de documentation
NE JAMAIS créer de nouveaux fichiers de documentation sauf demande explicite de l'utilisateur.
Référence rapide
| Tâche | Commande |
|---|---|
| Graver SRT | ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4 |
| Graver ASS | ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4 |
| Ajouter sous-titre logiciel | ffmpeg -i video.mp4 -i subs.srt -c copy -c:s mov_text output.mp4 |
| Extraire sous-titre | ffmpeg -i video.mkv -map 0:s:0 output.srt |
| Styliser sous-titres | -vf "subtitles=s.srt:force_style='FontSize=24,PrimaryColour=&HFFFFFF'" |
| Superposition de texte | -vf "drawtext=text='Bonjour':x=10:y=10:fontsize=24:fontcolor=white" |
| Format | Extension | Idéal pour |
|---|---|---|
| SRT | .srt | Simple, universel |
| ASS | .ass | Stylisé, animé, anime |
| VTT | .vtt | Vidéo Web/HTML5 |
Quand utiliser ce skill
À utiliser pour les opérations de sous-titres et de légendes :
- Gravure (intégration) de sous-titres dans la vidéo
- Ajout de pistes de sous-titres logicielles dans des conteneurs
- Extraction de sous-titres depuis MKV/MP4
- Stylisation des légendes (police, couleur, position)
- Superpositions de texte dynamiques
Sous-titres et légendes FFmpeg (2025)
Guide complet pour travailler avec les sous-titres, les légendes cachées et les superpositions de texte à l'aide de FFmpeg.
Référence des formats de sous-titres
Formats pris en charge
| Format | Extension | Fonctionnalités | Cas d'utilisation |
|---|---|---|---|
| SubRip | .srt | Synchronisation simple + texte | Universel, web |
| Advanced SubStation Alpha | .ass/.ssa | Riche en style, positionnement, effets | Anime, sous-titres stylisés |
| WebVTT | .vtt | Standard web, repères, style | Vidéo HTML5 |
| TTML/DFXP | .ttml/.dfxp | Diffusion, accessibilité | Services de streaming |
| MOV Text | .mov (intégré) | Natif QuickTime | Écosystème Apple |
| DVB Subtitle | (intégré) | Basé sur des bitmaps | Diffusion européenne |
| PGS | .sup | Sous-titres bitmap Blu-ray | Blu-ray |
| CEA-608/708 | (intégré) | Légendes cachées | Diffusion américaine, streaming |
Caractéristiques des formats
SRT (SubRip) :
- Format texte simple
- Prend en charge les balises HTML de base (<b>, <i>, <u>)
- Largement compatible
- Pas de positionnement ni de style avancé
ASS/SSA :
- Style avancé (polices, couleurs, contours)
- Positionnement précis n'importe où sur l'écran
- Prise en charge de l'animation et des effets
- Synchronisation karaoké
WebVTT :
- Format standard HTML5
- Style de type CSS
- Paramètres de repère pour le positionnement
- Identification du locuteur
Graver des sous-titres (Intégration)
Gravure de base des sous-titres
# Graver des sous-titres SRT
ffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4
# Graver des sous-titres ASS/SSA (conserve le style)
ffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4
# Graver des sous-titres depuis un conteneur MKV
ffmpeg -i video.mkv -vf "subtitles=video.mkv" output.mp4
# Graver une piste de sous-titres spécifique (index 0)
ffmpeg -i video.mkv -vf "subtitles=video.mkv:si=0" output.mp4
# Graver des sous-titres avec un index de flux
ffmpeg -i video.mkv -vf "subtitles=video.mkv:stream_index=1" output.mp4
Gravure de sous-titres stylisés
# Forcer le style (remplace le style des sous-titres)
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='FontName=Arial,FontSize=24,PrimaryColour=&HFFFFFF,OutlineColour=&H000000,Outline=2,Shadow=1'" \
output.mp4
# Sous-titres jaunes avec contour noir
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='FontSize=28,PrimaryColour=&H00FFFF,OutlineColour=&H000000,Outline=3'" \
output.mp4
# Police plus grande pour l'accessibilité
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='FontSize=36,Bold=1'" \
output.mp4
Paramètres de style ASS
| Paramètre | Description | Exemple |
|---|---|---|
| FontName | Famille de police | FontName=Arial |
| FontSize | Taille en points | FontSize=24 |
| PrimaryColour | Couleur du texte (AABBGGRR) | PrimaryColour=&HFFFFFF |
| SecondaryColour | Couleur karaoké | SecondaryColour=&H00FFFF |
| OutlineColour | Couleur du contour/bordure | OutlineColour=&H000000 |
| BackColour | Couleur de l'ombre/arrière-plan | BackColour=&H80000000 |
| Bold | Texte en gras (0/1) | Bold=1 |
| Italic | Texte en italique (0/1) | Italic=1 |
| Underline | Texte souligné (0/1) | Underline=1 |
| Outline | Largeur du contour | Outline=2 |
| Shadow | Profondeur de l'ombre | Shadow=1 |
| Alignment | Position (style pavé numérique) | Alignment=2 |
| MarginL/R/V | Marges en pixels | MarginV=50 |
Format des couleurs (ASS)
ASS utilise le format &HAABBGGRR (Alpha, Bleu, Vert, Rouge) :
- Blanc : &HFFFFFF ou &H00FFFFFF
- Noir : &H000000 ou &H00000000
- Jaune : &H00FFFF (00-Bleu, FF-Vert, FF-Rouge)
- Rouge : &H0000FF
- Bleu : &HFF0000
- Noir transparent à 50 % : &H80000000
Ajouter des pistes de sous-titres (Sous-titres logiciels)
Intégrer SRT en tant que piste
# Ajouter SRT à MP4 (texte MOV)
ffmpeg -i video.mp4 -i subs.srt \
-c copy -c:s mov_text \
output.mp4
# Ajouter SRT à MKV
ffmpeg -i video.mp4 -i subs.srt \
-c copy -c:s srt \
output.mkv
# Ajouter SRT à WebM (WebVTT)
ffmpeg -i video.webm -i subs.srt \
-c copy -c:s webvtt \
output.webm
Plusieurs pistes de sous-titres
# Ajouter plusieurs langues
ffmpeg -i video.mp4 -i subs_en.srt -i subs_es.srt -i subs_fr.srt \
-map 0:v -map 0:a -map 1 -map 2 -map 3 \
-c copy -c:s mov_text \
-metadata:s:s:0 language=eng -metadata:s:s:0 title="Anglais" \
-metadata:s:s:1 language=spa -metadata:s:s:1 title="Espagnol" \
-metadata:s:s:2 language=fra -metadata:s:s:2 title="Français" \
output.mp4
# Ajouter des sous-titres ASS à MKV (conserve le style)
ffmpeg -i video.mp4 -i styled.ass \
-map 0 -map 1 \
-c copy -c:s ass \
output.mkv
Définir la piste de sous-titres par défaut
# Définir le sous-titre comme par défaut
ffmpeg -i video.mp4 -i subs.srt \
-c copy -c:s mov_text \
-disposition:s:0 default \
output.mp4
# Définir des sous-titres forcés (toujours affichés)
ffmpeg -i video.mp4 -i forced.srt \
-c copy -c:s mov_text \
-disposition:s:0 forced \
output.mp4
Extraire des sous-titres
Extraire vers un fichier externe
# Extraire la première piste de sous-titres vers SRT
ffmpeg -i video.mkv -map 0:s:0 output.srt
# Extraire un flux de sous-titres spécifique
ffmpeg -i video.mkv -map 0:s:1 output.srt
# Extraire au format ASS
ffmpeg -i video.mkv -map 0:s:0 output.ass
# Extraire au format WebVTT
ffmpeg -i video.mkv -map 0:s:0 output.vtt
# Extraire toutes les pistes de sous-titres
ffmpeg -i video.mkv -map 0:s subs_%d.srt
Lister les pistes de sous-titres disponibles
# Afficher tous les flux, y compris les sous-titres
ffprobe -v error -show_entries stream=index,codec_name,codec_type:stream_tags=language,title \
-of csv=p=0 video.mkv
# Afficher uniquement les flux de sous-titres
ffprobe -v error -select_streams s \
-show_entries stream=index,codec_name:stream_tags=language,title \
-of csv=p=0 video.mkv
Convertir les formats de sous-titres
# SRT vers ASS
ffmpeg -i subs.srt subs.ass
# ASS vers SRT (perd le style)
ffmpeg -i subs.ass subs.srt
# SRT vers WebVTT
ffmpeg -i subs.srt subs.vtt
# WebVTT vers SRT
ffmpeg -i subs.vtt subs.srt
Superpositions drawtext et intégration Whisper AI
Des exemples détaillés pour les superpositions drawtext (polices, positionnement, échappement, expressions temporelles, boîtes, contours, texte animé) et les workflows de transcription / génération de sous-titres Whisper AI se trouvent dans references/drawtext-and-whisper.md. Chargez cette référence lors de la création de graphiques textuels intégrés ou de la génération de sous-titres à partir de la parole.
Légendes cachées CEA-608/708
Extraire les légendes cachées
# Extraire les légendes CEA-608 d'un flux ATSC
ffmpeg -f lavfi -i "movie=broadcast.ts[out0+subcc]" -map 0:1 captions.srt
# Extraire d'une vidéo avec CC intégré
ffmpeg -i video_with_cc.mp4 \
-filter_complex "[0:v]format=yuv420p[v];[0:v]crop=1:1:0:0[c]" \
-map "[c]" -c:v libx264 -f null - 2>&1 | grep -A 1 "Closed caption"
Ajouter des légendes CEA-608
# Intégrer des légendes CEA-608 (nécessite une ligne eia608)
ffmpeg -i video.mp4 -i captions.scc \
-c:v libx264 -c:a copy \
-vf "movie=captions.scc[captions];[0:v][captions]overlay" \
output.mp4
Positionnement des sous-titres
Valeurs d'alignement ASS
7 (haut-gauche) 8 (haut-centre) 9 (haut-droit)
4 (milieu-gauche) 5 (milieu-centre) 6 (milieu-droit)
1 (bas-gauche) 2 (bas-centre) 3 (bas-droit)
Exemples de positionnement
# Sous-titres en haut au centre
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='Alignment=8,MarginV=20'" \
output.mp4
# Sous-titres alignés à gauche
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='Alignment=1,MarginL=50,MarginV=30'" \
output.mp4
# Côté droit pour l'identification du locuteur
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:force_style='Alignment=3,MarginR=50'" \
output.mp4
Plusieurs positions de sous-titres
# Deux pistes de sous-titres à différentes positions
ffmpeg -i video.mp4 \
-vf "[in]subtitles=speaker1.srt:force_style='Alignment=1,MarginL=50'[tmp];\
[tmp]subtitles=speaker2.srt:force_style='Alignment=3,MarginR=50'" \
output.mp4
Traitement par lots
Graver des sous-titres sur plusieurs vidéos
#!/bin/bash
# burn_subs_batch.sh
for video in *.mp4; do
base="${video%.mp4}"
if [ -f "${base}.srt" ]; then
ffmpeg -i "$video" \
-vf "subtitles=${base}.srt:force_style='FontSize=24,Outline=2'" \
-c:a copy \
"output/${base}_subbed.mp4"
fi
done
Convertir le format de sous-titres par lots
#!/bin/bash
# convert_subs.sh
for srt in *.srt; do
base="${srt%.srt}"
ffmpeg -i "$srt" "${base}.vtt"
done
Dépannage
Problèmes courants
"Impossible de trouver un format de sortie approprié"
# Spécifier explicitement le format de sortie
ffmpeg -i video.mkv -map 0:s:0 -f srt output.srt
Caractères illisibles dans les sous-titres
# Forcer l'encodage UTF-8
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:charenc=UTF-8" \
output.mp4
Police non trouvée
# Spécifier le répertoire des polices
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:fontsdir=/path/to/fonts" \
output.mp4
# Lister les polices disponibles
fc-list : family | sort | uniq
Décalage temporel des sous-titres
# Retarder les sous-titres de 2 secondes
ffmpeg -i video.mp4 \
-vf "subtitles=subs.srt:itsoffset=2" \
output.mp4
# Ou utiliser setpts pour ajuster
ffmpeg -i subs.srt -itsoffset 2 delayed.srt
Les sous-titres ne s'affichent pas sur une vidéo haute résolution
# Adapter le rendu des sous-titres à la résolution de la vidéo
ffmpeg -i video_4k.mp4 \
-vf "subtitles=subs.srt:force_style='FontSize=48,Outline=3'" \
output.mp4
Commandes de vérification
# Vérifier si des sous-titres sont présents
ffprobe -v error -select_streams s -show_entries stream=codec_name -of default=nw=1 video.mp4
# Compter les lignes de sous-titres
grep -c "^[0-9]" subs.srt
# Valider le format SRT
ffmpeg -i subs.srt -f null -
Bonnes pratiques
Accessibilité
- Utiliser des couleurs à fort contraste (blanc sur fond sombre, jaune sur fond sombre)
- Taille de police minimale de 24 pt pour une vidéo standard
- Inclure l'identification du locuteur pour plusieurs intervenants
- Positionner les sous-titres pour éviter d'obstruer le contenu visuel important
- Garder les lignes courtes (42 caractères maximum par ligne)
- Durée d'affichage : minimum 1 seconde, maximum 7 secondes par légende
Qualité
- Utiliser le format ASS pour les sous-titres stylisés (anime, clips musicaux)
- Utiliser SRT pour les dialogues simples
- Utiliser WebVTT pour la diffusion sur le web
- Conserver le style d'origine lorsque c'est possible
- Tester sur les appareils cibles avant distribution
Performance
- Graver les sous-titres uniquement lorsque cela est nécessaire (streaming, compatibilité)
- Préférer les sous-titres logiciels pour l'archivage et la flexibilité
- Utiliser l'encodage matériel lors de la gravure de sous-titres sur des fichiers volumineux
- Traiter en parallèle pour les opérations par lots
Ce guide couvre les opérations de sous-titres et de légendes FFmpeg. Pour les superpositions de texte avec des formes et des graphiques, consultez le skill shapes-graphics.