Communitygithub.com

ffmpeg-captions-subtitles

Système complet de sous-titrage et de légendes pour FFmpeg 7.1 LTS et 8.0.1 (dernière version stable, publiée le 20/11/2025). ACTIVATION PROACTIVE pour : (1) Gravure de sous-titres (intégration SRT/ASS/VTT), (2) Ajout de pistes de sous-titres logicielles, (3) Extraction de sous-titres depuis une vidéo, (4) Conversion de formats de sous-titres, (5) Légendes stylisées (police, couleur, contour, ombre), (6) Positionnement et alignement des sous-titres, (7) Sous-titres cachés CEA-608/708, (8) Superpositions de texte avec drawtext, (9) Transcription automatique Whisper AI (FFmpeg 8.0+ avec VAD, multilingue, GPU), (10) Traitement par lots de sous-titres. Fournit : tableaux de référence des formats, guide des paramètres de style, tableaux d'alignement et de positionnement, comparatif des modèles Whisper, configuration VAD, exemples de texte dynamique, bonnes pratiques d'accessibilité. Garantit : des légendes professionnelles avec un style approprié et une conformité d'accessibilité.

Qu'est-ce que ffmpeg-captions-subtitles ?

Ce skill est un guide complet et une boîte à outils pour toutes les opérations de sous-titrage et de légendes avec FFmpeg, couvrant les versions stables récentes. Il permet de graver (hardcoder) des sous-titres dans une vidéo, d'ajouter des pistes logicielles, d'extraire des sous-titres existants, de convertir entre formats (SRT, ASS, VTT), d'appliquer des styles avancés (police, couleur, contour, ombre), de positionner précisément les sous-titres, de gérer les légendes cachées CEA-608/708, de créer des superpositions de texte animées avec drawtext, et d'utiliser la transcription automatique Whisper AI (disponible à partir de FFmpeg 8.0). Le skill fournit des références détaillées sous forme de tableaux, des exemples de commandes pour chaque tâche, et des conseils pour l'accessibilité et la performance. Il est conçu pour les développeurs, les monteurs vidéo et les créateurs de contenu qui ont besoin d'un contrôle précis et professionnel sur les sous-titres et les légendes dans leurs flux de production vidéo. Prend en charge les plateformes Windows, macOS et Linux.

Compatible avec~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Biel-developer/skills-videos/tree/HEAD/skills/ffmpeg-captions-subtitles

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

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âcheCommande
Graver SRTffmpeg -i video.mp4 -vf "subtitles=subs.srt" output.mp4
Graver ASSffmpeg -i video.mp4 -vf "ass=subs.ass" output.mp4
Ajouter sous-titre logicielffmpeg -i video.mp4 -i subs.srt -c copy -c:s mov_text output.mp4
Extraire sous-titreffmpeg -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"
FormatExtensionIdéal pour
SRT.srtSimple, universel
ASS.assStylisé, animé, anime
VTT.vttVidé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

FormatExtensionFonctionnalitésCas d'utilisation
SubRip.srtSynchronisation simple + texteUniversel, web
Advanced SubStation Alpha.ass/.ssaRiche en style, positionnement, effetsAnime, sous-titres stylisés
WebVTT.vttStandard web, repères, styleVidéo HTML5
TTML/DFXP.ttml/.dfxpDiffusion, accessibilitéServices de streaming
MOV Text.mov (intégré)Natif QuickTimeÉcosystème Apple
DVB Subtitle(intégré)Basé sur des bitmapsDiffusion européenne
PGS.supSous-titres bitmap Blu-rayBlu-ray
CEA-608/708(intégré)Légendes cachéesDiffusion 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ètreDescriptionExemple
FontNameFamille de policeFontName=Arial
FontSizeTaille en pointsFontSize=24
PrimaryColourCouleur du texte (AABBGGRR)PrimaryColour=&HFFFFFF
SecondaryColourCouleur karaokéSecondaryColour=&H00FFFF
OutlineColourCouleur du contour/bordureOutlineColour=&H000000
BackColourCouleur de l'ombre/arrière-planBackColour=&H80000000
BoldTexte en gras (0/1)Bold=1
ItalicTexte en italique (0/1)Italic=1
UnderlineTexte souligné (0/1)Underline=1
OutlineLargeur du contourOutline=2
ShadowProfondeur de l'ombreShadow=1
AlignmentPosition (style pavé numérique)Alignment=2
MarginL/R/VMarges en pixelsMarginV=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é

  1. Utiliser des couleurs à fort contraste (blanc sur fond sombre, jaune sur fond sombre)
  2. Taille de police minimale de 24 pt pour une vidéo standard
  3. Inclure l'identification du locuteur pour plusieurs intervenants
  4. Positionner les sous-titres pour éviter d'obstruer le contenu visuel important
  5. Garder les lignes courtes (42 caractères maximum par ligne)
  6. Durée d'affichage : minimum 1 seconde, maximum 7 secondes par légende

Qualité

  1. Utiliser le format ASS pour les sous-titres stylisés (anime, clips musicaux)
  2. Utiliser SRT pour les dialogues simples
  3. Utiliser WebVTT pour la diffusion sur le web
  4. Conserver le style d'origine lorsque c'est possible
  5. Tester sur les appareils cibles avant distribution

Performance

  1. Graver les sous-titres uniquement lorsque cela est nécessaire (streaming, compatibilité)
  2. Préférer les sous-titres logiciels pour l'archivage et la flexibilité
  3. Utiliser l'encodage matériel lors de la gravure de sous-titres sur des fichiers volumineux
  4. 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.

Skills associés