YouTube Bilingual Hardburn
Transforme une vidéo en langue étrangère en une vidéo sous-titrée bilingue chinois-anglais. Les étapes déterministes sont des scripts ; l'étape de traduction est effectuée par l'agent (LLM) et constitue le seul point risqué.
LOI DE FER : UNE ligne chinoise par ligne anglaise. Ne JAMAIS diviser une ligne anglaise en deux lignes chinoises (ni fusionner deux lignes en une). Après chaque lot de traduction, exécutez verify_align.py. Un seul décalage d'une ligne décalera tous les sous-titres suivants — et vous ne le remarquerez qu'à la fin du brûlage.
Quand la source a une ponctuation vs. quand elle n'en a pas
- Les sous-titres automatiques YouTube (et la plupart des ASR) n'ont pratiquement pas de ponctuation → l'approche "split on
.!?" échoue (tout s'effondre en un seul segment). Cette compétence résout cela en fusionnant les phrases jusqu'à une limite de caractères. C'est le chemin par défaut. - Si la source a déjà des sous-titres ponctués propres, le même pipeline fonctionne toujours.
Prérequis
yt-dlp(téléchargement),ffmpeg(brûlage),python3(scripts). Aucun paquet Python nécessaire.- Une police compatible CJK installée. macOS :
PingFang SC(par défaut). Linux : passez--font "Noto Sans CJK SC". Windows :--font "Microsoft YaHei". SCRIPTS=le chemin absolu vers le répertoirescripts/de cette compétence. Définissez-le une fois et réutilisez-le.
Flux de travail
Progression du brûlage bilingue :
- [ ] Étape 1 : Obtenir la vidéo + les sous-titres ⚠️ OBLIGATOIRE
- [ ] Étape 2 : Extraire + re-segmenter les sous-titres en lignes lisibles
- [ ] Étape 3 : Traduire chaque ligne (1:1) — la partie délicate ⚠️ OBLIGATOIRE
- [ ] Étape 4 : verify_align.py == OK ⛔ BLOQUANT (ne peut pas continuer tant que ce n'est pas réussi)
- [ ] Étape 5 : Construire le .ass bilingue + confirmer le style sur UNE image de test ⚠️ OBLIGATOIRE
- [ ] Étape 6 : Brûler la vidéo complète (encodage long) + vérifier quelques images
Étape 1 : Obtenir la vidéo + les sous-titres ⚠️ OBLIGATOIRE
yt-dlp -o "%(upload_date)s_%(title)s.%(ext)s" \
-f "bestvideo[height<=1080][ext=mp4]+bestaudio[ext=m4a]/best[height<=1080]/best" \
--merge-output-format mp4 --write-subs --write-auto-subs --sub-langs "en" \
--no-mtime "<URL>"
- Si
--write-auto-subsne produit aucun fichier de sous-titres (certaines vidéos n'en ont pas), vous devez d'abord transcrire l'audio (par exemple avec whisper) en un fichier.vtt/.srt, puis continuer. - Notez les deux fichiers de sortie :
VIDEO.mp4etVIDEO.en.vtt.
Étape 2 : Extraire + re-segmenter ⚠️
python3 "$SCRIPTS/extract_phrases.py" "VIDEO.en.vtt" > phrases.json
python3 "$SCRIPTS/merge_lines.py" phrases.json lines.json # --max-chars 95 --gap 12
Cela produit lines.json ([{start,end,en}]) et lines_en.txt (un fichier numéroté idx<TAB>Anglais). Traduisez lines_en.txt. Ajustez plus tard si nécessaire :
- les sous-titres semblent trop longs à l'écran → réduisez
--max-chars(par exemple 70) - vous voulez des pauses aux pauses naturelles → réduisez
--gap(par exemple 2,5) — donne plus de lignes, plus courtes
Étape 3 : Traduire chaque ligne (1:1) ⚠️ OBLIGATOIRE — c'est la partie délicate
Lisez lines_en.txt (il est numéroté 0..N-1). Produisez un fichier ZH en texte brut : exactement une ligne chinoise pour chaque ligne anglaise, dans le même ordre. Écrivez du texte séparé par des sauts de ligne (PAS du JSON — les guillemets chinois cassent l'échappement JSON).
Règles qui empêchent la violation de la Loi de Fer :
- Une ligne en entrée → une ligne en sortie. Traduisez la ligne anglaise comme une unité indépendante. Si une ligne se coupe au milieu d'une phrase (c'est normal pour l'ASR), laissez le chinois se couper au même endroit. Ne corrigez pas en faisant chevaucher les lignes.
- Travaillez par lots d'environ 120 à 150 lignes. Après CHAQUE lot, écrivez son fichier et exécutez immédiatement
verify_align.pysur le résultat cumulé. - Conservez les noms propres sous leur forme correcte (ChatGPT, OpenAI, Claude, Gemini, Grok, DeepSeek…). L'ASR les déforme ("chpd"→ChatGPT, "grock"→Grok, "ha cou"→haiku) — corrigez-les avec le vrai nom.
- Chinois parlé naturel, pas une traduction rigide. Adaptez-vous au registre du locuteur.
Concaténez tous les fichiers de lots en un seul zh.txt (une ligne ZH par ligne EN, dans l'ordre).
Étape 4 : verify_align.py ⛔ BLOQUANT
python3 "$SCRIPTS/verify_align.py" lines.json zh.txt
- Affiche
OK→ continuez. - Affiche
MISMATCH+ un tableau côte à côte → trouvez la ligne où les significations EN et ZH cessent de correspondre. Cette ligne est une division (une ligne EN est devenue deux lignes ZH) ou une fusion. Corrigez-la (fusionnez les deux lignes ZH en une seule, ou divisez-en une en deux), puis relancez. Ne continuez pas avant d'avoirOK.
Étape 5 : Construire le .ass + confirmer sur UNE image de test ⚠️ OBLIGATOIRE
python3 "$SCRIPTS/build_bilingual_ass.py" lines.json zh.txt styled.ass
# Chinois en haut (blanc 44px) + anglais en dessous (gris 30px), centré en bas.
# Linux/Windows : ajoutez --font "Noto Sans CJK SC" / --font "Microsoft YaHei"
Rendez UNE image à un horodatage connu pour avoir un sous-titre, et REGARDEZ-LA avant le long encodage :
ffmpeg -ss 60 -i "VIDEO.mp4" -copyts -vf "ass=styled.ass" -frames:v 1 -y test_frame.png
Confirmez avec l'utilisateur : le chinois s'affiche (pas de carrés □□□), la disposition à deux niveaux semble correcte, la taille/position est acceptable. Ajustez --zh-size/--en-size/--margin/--font et reconstruisez si nécessaire. Ne commencez pas l'encodage complet tant que l'image de test n'est pas correcte.
Étape 6 : Brûler la vidéo complète + vérification ponctuelle
ffmpeg -y -i "VIDEO.mp4" -vf "ass=styled.ass" \
-c:v libx264 -preset fast -crf 22 -c:a copy -sn "VIDEO_中英双语.mp4"
Une vidéo 1080p de 2 heures prend ~15–40 min — lancez-la en arrière-plan. Une fois terminée, prenez des images au début, au milieu et vers la fin pour confirmer que les sous-titres restent synchronisés tout au long :
for t in 600 3900 7200; do ffmpeg -ss $t -i "VIDEO_中英双语.mp4" -frames:v 1 -y "chk_$t.png"; done
Si une image semble mal alignée, reconfirmez le même horodatage dans lines.json+zh.txt pour vérifier qu'il s'agit de la même ligne source avant de supposer un bug (les images basse résolution sont faciles à mal lire).
Anti-patrons
- Diviser/fusionner des lignes pendant la traduction — la cause n°1 de désynchronisation complète de la vidéo. Une ligne EN = une ligne ZH, toujours.
- Écrire les traductions en JSON — les guillemets chinois courbes “ ” et 「」 cassent silencieusement l'analyse JSON. Utilisez du texte brut séparé par des sauts de ligne.
- Se fier aux heures de fin des sous-titres pour l'ordre — les fins des sous-titres déroulants se chevauchent ;
merge_lines.pyséquence uniquement par START. Ne réordonnez pas par END. - Sauter l'image de test — brûler 2 heures puis découvrir des carrés □ ou une mauvaise police gâche tout l'encodage.
- Ré-encoder l'audio — utilisez
-c:a copy. Seule la piste vidéo change. - Utiliser l'ancien
build_bilingual.pyde la compétence de téléchargement vidéo sur les sous-titres automatiques — il divise sur la ponctuation et effondre tout le transcript en un seul segment. Cette compétence le remplace.
Liste de vérification avant livraison
-
verify_align.pya affichéOK(nombre EN == nombre ZH) avant de construire le .ass - Image de test inspectée : le chinois s'affiche, pas de □, disposition/taille correctes
- Vérification ponctuelle des images début/milieu/fin du mp4 final — sous-titres synchronisés
- Sortie nommée clairement (par exemple
<titre>_中英双语.mp4) ; vidéo originale non modifiée - Noms propres corrigés (plus de "chpd"/"grock"/"ha cou" dans le chinois)
Multi-plateforme (OpenAI Codex, etc.)
Tous les scripts sont en python3 pur + ffmpeg/yt-dlp — aucune dépendance spécifique à Claude. Pour exécuter ce flux de travail sous Codex (ou tout agent capable de shell), chargez references/codex-usage.md.