Que fait Traducteur de sous-titres YouTube ?
Télécharge des vidéos YouTube, extrait et traite les sous-titres (relecture + ponctuation + traduction), puis les incruste dans la vidéo. Prend en charge les sous-titres automatiques et les téléchargements manuels, avec recours à l'ASR lorsque aucun sous-titre n'existe.
Règles strictes
- Utilisez au maximum 3 sous-agents simultanés pour le traitement par fragments de sous-titres. Lorsqu'il y a plus de 3 fragments, exécutez-les par vagues et lancez le fragment suivant seulement après la fin d'un sous-agent.
- Le nombre de fragments n'est pas la simultanéité. Vous pouvez diviser en 10 fragments, mais vous ne devez pas lancer 10 processus/sous-agents Codex à la fois ; exécutez au maximum 3 travailleurs actifs à tout moment.
- Téléchargez toujours uniquement la piste de sous-titres source : anglais si disponible, sinon la langue originale de la vidéo. Ne téléchargez pas les sous-titres automatiques traduits par YouTube dans la langue cible ; traduisez à partir du sous-titre source.
- N'utilisez jamais une piste de sous-titres en langue cible fournie par YouTube comme raccourci, même pour les vidéos longues et même si
zh-Hansou une autre langue cible est listé dansautomatic_captions. - Le téléchargement de la vidéo par défaut se fait en 1080p. Si la 1080p n'est pas disponible, téléchargez la meilleure version disponible en dessous de 1080p.
- La traduction doit être effectuée par des sous-agents sur des fichiers fragments. N'utilisez pas d'assistants de modèle locaux pour la traduction.
- Avant d'écrire du SRT/ASS, supprimez les caractères de sous-titres illégaux du texte, en particulier les barres obliques inverses (
\) parasites qui s'affichent visiblement dans la vidéo.
Aperçu du flux de travail
Phase 1 : Télécharger → Obtenir les infos vidéo, télécharger la vidéo, extraire les sous-titres
Phase 2 : Préparer → Si pas de sous-titres : extraire l'audio → exécuter l'ASR
Phase 3 : Traiter → Diviser en fragments → relecture + traduction par agent parallèle
Phase 4 : Fusionner → Combiner les fragments → générer les fichiers SRT/ASS
Phase 5 : Rendre → Incruster les sous-titres sur la vidéo avec ffmpeg
Phase 1 : Téléchargement
1.1 Obtenir les informations vidéo
Utilisez l'outil YouTube MCP pour récupérer les métadonnées :
youtube_get_video_info(videoId="...", detail="standard")
Enregistrez : titre, durée, chaîne, disponibilité des sous-titres.
1.2 Créer le répertoire de sortie
Nommez le répertoire d'après le titre de la vidéo. Nettoyez-le pour le système de fichiers :
mkdir -p "/output/path/<Titre Vidéo>"
1.3 Télécharger la vidéo
youtube_download(videoId="...", outputPath="<dir>/video.mp4", quality="1080p", force=true)
Si vous utilisez yt-dlp, préférez la 1080p et repliez-vous sur le meilleur format en dessous de 1080p :
yt-dlp -f "bv*[height<=1080]+ba/b[height<=1080]/best" --merge-output-format mp4 \
-o "<dir>/video.%(ext)s" "<url>"
1.4 Extraire uniquement les sous-titres sources
youtube_get_transcript(videoId="...", language="<langue-source>")
Si le résultat dépasse les limites de jetons, il est enregistré dans un fichier de résultats d'outil — lisez-le par fragments.
Ceci est une politique de sous-titres source non négociable :
- Préférez les sous-titres anglais lorsqu'ils sont disponibles.
- Si l'anglais n'est pas disponible, utilisez la langue parlée originale de la vidéo.
- Ignorez
zh-Hans,zh-Hantet toutes les autres pistes en langue cible affichées par YouTube, y compris les pistes traduites automatiquement. - Ne demandez, ne réessayez, ne fusionnez et ne rendez pas une piste de sous-titres en langue cible fournie par YouTube.
- Les sous-titres en langue cible doivent être produits uniquement par traduction par sous-agent à partir du sous-titre source.
Si un outil renvoie une liste telle que en-orig, zh-Hans, choisissez uniquement en-orig. N'incluez pas zh-Hans dans une commande de téléchargement.
Si vous utilisez yt-dlp, écrivez uniquement le sous-titre source :
yt-dlp --skip-download --write-auto-subs --write-subs \
--sub-langs "en.*" --sub-format srt --convert-subs srt \
-o "<dir>/video.%(ext)s" "<url>"
Incorrect, ne pas exécuter :
yt-dlp --write-auto-subs --sub-langs "en-orig,zh-Hans" ...
Si le téléchargement du sous-titre anglais/original réussit mais qu'une demande en langue cible échoue avec une erreur HTTP 429, ne réessayez pas la demande en langue cible. Cette demande n'aurait pas dû être faite ; continuez à partir du sous-titre source et traduisez-le via la Phase 3.
Si les sous-titres existent : Enregistrez les segments bruts au format JSON, passez à la Phase 3. Si PAS de sous-titres (404/erreur) : Passez à la Phase 2 (recours ASR).
Enregistrez les données brutes :
raw_segments.json— tous les segments avec texte/décalage/duréeraw_subtitles.srt— conversion SRT initiale
Phase 2 : Recours ASR (aucun sous-titre disponible)
Lorsque la vidéo n'a pas de légendes/transcriptions :
-
Extraire l'audio de la vidéo avec ffmpeg :
ffmpeg -i video.mp4 -vn -acodec pcm_s16le -ar 16000 -ac 1 audio.wav -
Exécuter l'ASR — l'utilisateur a spécifié qwen3-asr mais tout modèle compatible whisper fonctionne :
qwen3-asr audio.wav --output-format srt > raw_subtitles.srtOu utilisez l'approche intégrée via la commande transcribe du skill hyperframes-media.
-
Analysez la sortie SRT dans le format JSON de segments attendu par la Phase 3.
Phase 3 : Relecture et traduction parallèles
C'est l'étape la plus longue pour les vidéos longues. La stratégie : diviser en fragments et les traiter avec des sous-agents, avec une limite stricte de 3 sous-agents simultanés.
Effectuez cette phase même pour les vidéos très longues. La longueur n'est pas une raison pour télécharger ou utiliser les sous-titres automatiques en langue cible de YouTube. Le raccourci correct pour les vidéos longues est le découpage en fragments plus la simultanéité de 3 sous-agents, pas la réutilisation des sous-titres cibles.
3.1 Diviser les segments en fragments
Utilisez la logique inverse de scripts/merge-chunks.py — divisez raw_segments.json en N fichiers fragments :
# Diviser en fragments dimensionnés pour révision/traduction.
n = len(segments)
chunk_count = min(10, max(1, (n + 75) // 76))
chunk_size = n // chunk_count + 1
for i in range(0, n, chunk_size):
save_chunk(i, segs[i:i+chunk_size])
Enregistrez sous chunk_00.json, chunk_01.json, etc. Chacun contient {"chunk_id", "start_idx", "end_idx", "segments": [...]}.
3.2 Lancer les agents parallèles
Pour chaque fragment, lancez un sous-agent en arrière-plan. Ne lancez pas plus de 3 sous-agents en même temps. S'il y a 10 fragments, commencez par les fragments 00, 01, et 02 ; quand l'un se termine, lancez le fragment suivant en attente. Ne lancez jamais les 10 fragments à la fois. Donnez à chaque agent :
- Le chemin vers son
chunk_XX.json - Les instructions pour lire references/subtitle-proofreading.md pour le cahier des charges complet
- Chemin de sortie :
result_XX.jsondans le même répertoire
L'agent doit :
- Lire chaque segment de son fragment
- Relire l'anglais (corriger les erreurs ASR, ajouter la ponctuation)
- Traduire en chinois simplifié naturel (garder les termes techniques en anglais)
- Enregistrer sous forme de tableau JSON avec
{index, start, end, en, zh}par segment - Supprimer les caractères de sous-titres illégaux de
enetzh, en particulier les barres obliques inverses (\) parasites, les caractères de contrôle et les accolades brutes de remplacement ASS.
Important : La simultanéité maximale est de 3 sous-agents/processus. S'il y a plus de 3 fragments, exécutez-les par vagues. Ne lancez pas 10 processus enfants Codex pour 10 fragments.
3.3 Attendre la fin
Surveillez quels fichiers result_XX.json apparaissent. Ne continuez pas avant que tous les fragments soient terminés.
Phase 4 : Fusionner et générer les fichiers de sortie
Exécutez le script de fusion :
python3 scripts/merge-chunks.py <output_dir>
Ceci découvre automatiquement tous les fichiers result_*.json et produit :
| Fichier | Contenu |
|---|---|
final_subtitles.json | JSON fusionné, trié par horodatage |
subtitles_bilingual.srt | Lignes anglais + chinois |
subtitles_zh.srt | Chinois uniquement |
subtitles_en.srt | Anglais uniquement |
4.2 Valider la qualité des données
Avant le rendu, validez toujours les données fusionnées. Le traitement par agent parallèle peut produire une corruption des horodatages :
# Vérifier les durées anormales (>120s = presque certainement corrompues)
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
print(f'Durées anormales : {len(bad)} / {len(segs)}')
for s in bad: print(f' [{s[\"index\"]}] {s[\"start\"]:.1f}->{s[\"end\"]:.1f} ({s[\"end\"]-s[\"start\"]:.0f}s)')
"
Si des durées anormales sont trouvées, corrigez-les (plafonnez end à start + 6) et régénérez les SRT/ASS. merge-chunks.py et srt-to-ass.py incluent une détection et une correction automatiques pour ce problème.
Vérifiez la sortie : vérifiez que les premières et dernières entrées ont des horodatages corrects et un texte lisible.
Vérifiez également l'assainissement du texte :
python3 -c "
import json
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if '\\\\' in s.get('en','') or '\\\\' in s.get('zh','')]
print(f'Artefacts de barre oblique inverse : {len(bad)}')
for s in bad[:10]: print(s['index'], s.get('en',''), s.get('zh',''))
"
Phase 5 : Incruster les sous-titres sur la vidéo
C'est là que les choses se compliquent. N'utilisez PAS le ffmpeg système directement — voir les écueils ci-dessous.
5.1 Exécuter le script de rendu
bash scripts/render-subtitles.sh <video.mp4> <subtitles_bilingual.srt> [output.mp4]
Le script gère tout :
- Détecte/construit ffmpeg natif ARM64 avec support libass
- Convertit SRT → ASS avec configuration de police CJK appropriée
- Copie les fichiers vers /tmp pour éviter les problèmes de chemins avec caractères spéciaux
- Effectue le rendu avec le filtre ass de ffmpeg
- Valide la sortie
5.2 Vérifier la sortie
Vérifiez que :
- Le fichier de sortie existe et fait > 10 Mo (pas seulement audio)
- La durée correspond à la vidéo originale (utilisez ffprobe)
- Lisez la première et la dernière minute pour confirmer que les sous-titres apparaissent
Écueils et leçons apprises
Ce sont des leçons durement acquises lors d'une utilisation réelle. Suivez-les pour éviter de perdre des heures.
Inadéquation d'architecture ffmpeg (CRITIQUE)
Problème : Le ffmpeg de Homebrew sur macOS est compilé SANS libass, libfreetype et fontconfig. Les filtres ass, subtitles et drawtext n'existent tout simplement pas.
Pire : Les builds statiques ffmpeg de evermeet.cx sont des binaires x86_64 (Intel). Sur les Mac Apple Silicon, ils s'exécutent via l'émulation Rosetta 2, environ 8 à 10 fois plus lentement. Une vidéo de 1h30 a pris plus de 2 heures.
Solution : Utilisez scripts/ensure-ffmpeg.sh. Il détecte ces problèmes et compile ffmpeg natif ARM64 à partir des sources avec toutes les bibliothèques nécessaires. La première construction prend environ 5 minutes ; les reconstructions suivantes sont instantanées (fichiers objets mis en cache).
Indicateurs de configuration requis pour le support complet des sous-titres :
--enable-libass --enable-libfreetype --enable-fontconfig --enable-libdav1d
Décodage AV1 manquant
Problème : De nombreuses vidéos YouTube modernes sont encodées en AV1 (codec_name: av1). Un ffmpeg construit sans --enable-libdav1d échouera avec des erreurs "Function not implemented" lors du décodage, produisant un fichier audio uniquement de 68 Mo.
Solution : Incluez toujours --enable-libdav1d lors de la construction de ffmpeg.
Les caractères spéciaux dans les chemins cassent les filtres ffmpeg
Problème : Lorsque le chemin de la vidéo ou du sous-titre contient des caractères comme des tirets cadratins (—), des guillemets courbes ou des caractères non ASCII, l'analyseur de filtres de ffmpeg échoue avec des erreurs "No option name near...". Cela se produit même avec un quoting shell approprié.
Solution : Copiez les fichiers de sous-titres vers /tmp/subs_<pid>.ass avant de les passer à ffmpeg. Le script de rendu le fait automatiquement.
Conflits d'API TextClip de moviepy (À ÉVITER)
Problème : La classe TextClip de moviepy 2.x a des conflits de paramètres entre les arguments positionnels et kwargs (font apparaît deux fois en interne). Plusieurs variantes d'erreur, aucune évidente à partir du message d'erreur.
Recommandation : N'utilisez pas moviepy pour le rendu de sous-titres en production. Utilisez plutôt le filtre ass de ffmpeg — il est plus rapide, plus fiable et gère correctement les polices CJK via libass/fontconfig.
SRT vs ASS pour ffmpeg
Problème : Le filtre subtitles de ffmpeg (qui lit le SRT directement) souffre également de problèmes d'analyse de chemin sur certaines builds. Le filtre ass est plus fiable.
Solution : Convertissez d'abord SRT → ASS avec scripts/srt-to-ass.py, puis utilisez le filtre ass. Le format ASS vous donne également un contrôle fin sur la police, la taille, le positionnement et le style.
Caractères de sous-titres illégaux
Problème : Le texte des sous-titres bruts ou traduits peut contenir des barres obliques inverses (\) parasites ou des caractères de remplacement ASS. Dans le rendu ASS, une barre oblique inverse littérale peut apparaître à l'écran ou interagir accidentellement avec la syntaxe d'échappement ASS.
Solution : Assainissez le texte des sous-titres avant d'écrire le SRT/ASS :
- Supprimez les barres obliques inverses du texte des sous-titres visible par l'utilisateur
- Supprimez les caractères de contrôle à l'exception des espaces normaux
- Supprimez les accolades
{et}brutes du texte des sous-titres - Laissez
srt-to-ass.pyajouter uniquement les séquences de contrôle ASS qu'il possède, comme\Nentre les lignes bilingues
Durées de sous-titres anormales provenant du traitement par agent parallèle
Problème : Lors du traitement des sous-titres en fragments parallèles (Phase 3), des agents individuels peuvent produire des entrées avec des horodatages corrompus — en particulier, des valeurs end beaucoup plus grandes que start (par exemple, durée de 2600s ou 4800s au lieu d'environ 6s). Cela fait que ces lignes de sous-titres restent visibles à l'écran pendant la majeure partie de la vidéo, chevauchant tout autre contenu.
Cause racine : Les agents attribuent parfois mal les heures de fin lors de la consolidation des fragments ASR fragmentés à travers les limites des fragments. Le problème est au niveau des données, pas un problème de rendu — donc il ne sera pas détecté par les erreurs ffmpeg.
Solution : Trois couches de défense :
scripts/srt-to-ass.pydétecte automatiquement les entrées avec une durée > 120s et les plafonne à 6s avec un avertissement- Validation de la Phase 4 : Après la fusion des fragments, recherchez toujours les entrées où
(end - start) > 120secondes - Vérification avant rendu : Avant d'exécuter ffmpeg, greppez le fichier ASS pour les lignes Dialogue suspectement longues
# Vérification rapide avant rendu : trouver tout sous-titre durant > 2 minutes
python3 -c "
import json, sys
segs = json.load(open('final_subtitles.json'))
bad = [s for s in segs if s['end'] - s['start'] > 120]
if bad: print(f'ATTENTION : {len(bad)} durées anormales trouvées !'); sys.exit(1)
else: print('Vérification des durées réussie')
"
Réglage de la taille de police
Problème : Les tailles de police par défaut (16-20px) peuvent être trop petites sur les vidéos haute résolution 1080p+, surtout lorsqu'elles sont visionnées sur des écrans plus petits ou à distance.
Solution : Utilisez le drapeau --font-size pour ajuster. Tailles de base recommandées :
- Vidéo 1080p :
--font-size 24(bilingue) ou--font-size 28(monolingue) - Vidéo 4K :
--font-size 36ou plus - Le script
render-subtitles.shtransmet ceci àsrt-to-ass.py
Dépendances
- Outils YouTube MCP :
mcp__plugin_youtube_youtube__*(téléchargement vidéo, transcription, informations) - ffmpeg : Auto-construit par
scripts/ensure-ffmpeg.sh - Python 3 : Scripts de fusion, conversion SRT→ASS, validation
- qwen3-asr ou autre modèle compatible whisper : Pour le recours ASR