agent-caption : sous-titres locaux dans toutes les langues

agent-caption — Compétence

Vous êtes un agent de sous-titrage IA. Ce dépôt ajoute des légendes/sous-titres précis et parfaitement synchronisés à toute vidéo ou audio, dans n'importe quelle langue (anglais par défaut), pour la parole comme la musique, avec un support de premier ordre pour le Hinglish / code-switching. Fonctionne sur Windows, macOS et Linux.

Dépôt : https://github.com/ahkamboh/agent-caption — clonez : git clone https://github.com/ahkamboh/agent-caption Ce fichier, brut (pour les agents de chat) : https://raw.githubusercontent.com/ahkamboh/agent-caption/master/SKILL.md

Principe fondamental : les mots proviennent de la reconnaissance vocale, mais le TIMING vient de l'alignement forcé sur la forme d'onde — jamais des horodatages bruts de l'ASR. Ainsi, les sous-titres ne dérivent jamais (en avance ou en retard), même si la transcription contient des fautes d'orthographe.

Configuration unique (Windows / macOS / Linux)

Nécessite : Python 3.10+, ffmpeg, environ 4 Go d'espace disque. (torch fournit des wheels jusqu'à Python 3.14 ; si whisperx n'a pas de wheel pour une version très récente de Python, utilisez 3.11–3.12.)

python setup.py        # multiplateforme : crée ./.venv-whisperx et installe tout
# macOS/Linux pratique : bash setup.sh      ·      Windows pratique : setup.bat

ffmpeg : macOS brew install ffmpeg · Ubuntu sudo apt install ffmpeg · Windows winget install ffmpeg. Les modèles (Whisper large-v3 — le défaut — MMS_FA, whisperX) se téléchargent automatiquement au premier lancement.

Chemin le plus simple — le wrapper en une commande (À PRÉFÉRER)

Pour les requêtes « sous-titrer cette vidéo », exécutez simplement le wrapper de premier niveau. Il effectue la transcription → l'alignement → l'incrustation avec des sous-titres auto-proportionnés (taille, espacement, alignement corrects pour toute résolution), et utilise un rendu sans libass (Pillow + overlay) si le ffmpeg de l'utilisateur ne supporte pas les sous-titres :

python caption.py <video>                                  # Anglais, propre, proportionné -> <video>.captioned.mp4
python caption.py <video> --hinglish --style tiktok        # Hinglish + boîte TikTok
python caption.py <video> --lang ur --pos center --size 6  # Autre langue / placement / taille
python caption.py <video> --srt                            # écrire uniquement un .srt (sans incrustation)
python caption.py <video> --from-srt FILE                  # incruster un .srt existant, proportionné

15 styles (polices fournies) : clean (défaut) bold hormozi green beast impact bebas tiktok pill boxed yellow neon gradient minimal subtitle. Utilisez les scripts individuels ci-dessous uniquement lorsque vous avez besoin de la transcription brute, d'un rendu personnalisé ou d'une traduction.

Modèle : large-v3 est le DÉFAUT (meilleure précision) — aucun indicateur nécessaire ; setup.py le pré-télécharge. Vous voulez de la rapidité sur un anglais clair ? ajoutez --fast (petit modèle). --accurate existe encore mais est redondant maintenant. Le chemin Hinglish utilise toujours large-v3.

Style personnalisé — construisez N'IMPORTE QUEL aspect que l'utilisateur décrit. Associez les mots de l'utilisateur à ces indicateurs (ils remplacent --style) :

• --font <nom|chemin> — une police fournie (Poppins-Bold, Poppins-Black, Anton-Regular, BebasNeue-Regular, ArchivoBlack-Regular) ou tout chemin .ttf
• --fill #hex (couleur du texte) · --outline #hex · --box #hex|#hexAA|none (fond derrière le texte)
• --caps / --no-caps · --gradient "#hex,#hex,#hex" · --glow · --ow N (épaisseur du contour)
• --size <pct> (hauteur) · --pos bottom|center|top

Exemple — l'utilisateur dit « hot-pink en majuscules dans une boîte sombre arrondie, grand, police Anton » →

python caption.py v.mp4 --fill "#ff3da6" --box "#10141ae0" --caps --font Anton-Regular.ttf --size 6

Pour rendre un nouveau style nommé permanent, ajoutez une entrée dans le dictionnaire STYLES dans caption.py.

Précision — éliminez les mots mal entendus (gratuit, sans tokens, sans intervention humaine)

L'alignement forcé rend le timing correct par construction. La seule chose qu'il ne peut pas corriger est de savoir si un mot a été entendu correctement (« leur »/« là », noms, argot). Trois leviers gratuits réduisent cela à zéro :

• --glossary "..." — fournissez des noms/marques/argot (une liste ou un chemin .txt). Cela oriente l'incitation initiale de l'ASR pour que les noms propres cessent d'être mal entendus. Le plus gros gain sur les noms. Liste unique.

  python caption.py talk.mp4 --glossary "Xaibridge, Hinglish, Xotion, Kamboh"
  

• --script FILE — si les mots corrects existent déjà (paroles, un script), passez-les. L'outil ignore complètement l'ASR et ne fait qu'aligner par force les mots donnés → précision du contenu à 100 %.

  python caption.py song.mp4 --script lyrics.txt
  

• --grammar — un passage hors ligne sur les homophones/grammaire des sous-titres (« leur »→« là », « ta »→« t'a »). Exécute LanguageTool localement (pas d'envoi, pas de tokens) ; le timing n'est jamais touché. Dépendance optionnelle — activez une fois avec python setup.py --grammar (nécessite Java/JRE 8+) ; ignoré proprement si absent.

  python caption.py talk.mp4 --accurate --glossary names.txt --grammar    # cumulez-les
  

Ordre d'efficacité : --glossary (noms) → --script (quand le texte existe) → --grammar (homophones). Le modèle de base est déjà large-v3 par défaut. Les seuls résidus que ces leviers ne peuvent pas rattraper nécessitent un humain ou un LLM — c'est le seul coût qui vaut la peine de dépenser des tokens, et uniquement sur les mots signalés, pas sur l'intégralité de la transcription.

Chansons — isolez d'abord la voix (--content)

Pour la musique, séparer la piste vocale avant l'ASR rend la transcription des paroles bien plus propre (Whisper arrête de lutter contre l'accompagnement). C'est conditionnel — inutile/lent sur une parole claire — donc c'est verrouillé :

python caption.py song.mp4 --content music                 # forcer l'isolation vocale (demucs)
python caption.py clip.mp4                                  # --content auto (défaut) : détecte la musique, isole seulement si nécessaire
python caption.py podcast.mp4 --content speech              # ne jamais isoler (ou --no-isolate)
python caption.py song.mp4 --content music --script lyrics.txt   # chansons les plus propres : mots connus, synchronisés sur la piste vocale

auto exécute un sondage rapide musique/parole et n'isole QUE lorsqu'il détecte de la musique — ainsi les podcasts/interviews ne sont jamais ralentis. L'incrustation utilise toujours la vidéo originale ; seul ce que nous transcrivons/alignons est la piste isolée. Nécessite demucs (installé par python setup.py) ; utilise l'audio original en son absence.

Exécutez toujours les scripts avec le python du venv — noté ici PY :

• macOS / Linux : PY = ./.venv-whisperx/bin/python
• Windows : PY = .venv-whisperx\Scripts\python

Les scripts

• transcribe.py — Whisper → transcription au niveau du mot (anglais par défaut ; --lang xx pour d'autres).
• align.py — alignement forcé pour un timing image-par-image. --code-switch pour le Hinglish/mixte.
• cs_transcribe.py — reconnaissance de mots robuste au code-switching (identification de la langue par segment).
• mms_align.py — aligneur forcé universel MMS_FA (1100+ langues, toute écriture).
• validate_timing.py — vérification de la cohérence temporelle utilisée par le chemin code-switch.
• export-subs.py — transcription → .srt + .vtt.
• multilang-subs.py — traduisez les sous-titres en plusieurs langues, hors ligne.
• grammar_fix.py — correction hors ligne des homophones/grammaire sur un .srt (timing préservé) ; utilisé par --grammar.
• isolate_vocals.py — isolation vocale Demucs pour les chansons + un sondage musique-vs-parole ; utilisé par --content.
• qa.py — porte de qualité déterministe rapide (vérification de la validité des cues + sortie ffprobe) → work/<base>.qa.json. S'exécute automatiquement après chaque incrustation ; --strict fait sortir un code non nul en cas de résultat défectueux.
• footprint.py — génère <base>.footprint.svg : une carte de santé des sous-titres en un coup d'œil (chaque mot coloré selon la confiance de l'alignement forcé + marqueurs d'écart + verdict). S'exécute automatiquement après chaque caption ; --no-footprint pour ignorer.
• benchmark.py — mesurez le gain réel de précision : WER de l'ancien défaut (petit) vs le nouveau défaut (large-v3 [+ Demucs]) par rapport à une transcription de référence. PY scripts/benchmark.py CLIP --ref truth.txt [--music] [--hinglish].
• caption.py — tout-en-un pour les sous-titres stylés (karaoké/mot/ligne ; Hormozi/TikTok/neon…) → captions.js animé.

Sous-titrez une vidéo (la tâche principale) — langue par défaut = anglais

Pour une autre langue, passez --lang <code>. Pour le Hinglish / mixte, utilisez --code-switch.

1) Timings des mots image-par-image

Parole (dialogue, podcast, contenu UGC) :

PY scripts/align.py INPUT --lang en --out work/transcript.json

Hinglish / hindi-anglais mixte (ou tout audio avec code-switching) :

PY scripts/align.py INPUT --code-switch --dual hi en --out work/transcript.json

Toute autre langue (ourdou, espagnol, arabe, chinois, …) :

PY scripts/align.py INPUT --lang ur --out work/transcript.json

2a) Sous-titres (.srt / .vtt) + incrustation dans la vidéo

PY scripts/export-subs.py work/transcript.json --out work/subs
ffmpeg -i INPUT -vf "subtitles=work/subs.srt" -c:a copy captioned.mp4

Le .srt est également parfait à télécharger directement sur YouTube (sélectionnable + SEO).

2b) Sous-titres stylés / animés (Hormozi, TikTok, karaoké — format court)

PY scripts/caption.py INPUT --lang en --content speech --style karaoke --preset hormozi --out out/

Préréglages : hormozi, beast, pill, neon, gradient, minimal, tiktok. Utilisez --content music pour les chansons/paroles. Voir docs/caption-styles.md.

3) Traduisez les sous-titres dans n'importe quelle langue (optionnel)

PY scripts/multilang-subs.py work/subs.srt --to "hi,ur,es,fr,ar,de" [--burn INPUT]

Règles (intégrées — ne pas remplacer)

• Le timing est TOUJOURS l'alignement forcé, jamais les horodatages bruts de l'ASR (pas d'avance/retard).
• Langue par défaut des sous-titres = anglais ; passez --lang pour toute autre langue.
• Musique/chant → --content music ; parole/dialogue → --content speech.
• Exécutez chaque script avec PY (le python du venv) pour qu'il ait whisperx/torch.
• Avant de livrer, vérifiez quelques sous-titres à leurs débuts de mots pour confirmer la synchronisation.

Codes de langue

en (défaut), hi, ur, pa, es, fr, de, pt, ar, zh, ja, ko, ru, it, tr, id, nl, pl, uk, … — Whisper supporte ~99 langues ; MMS_FA aligne 1100+.