yyert123/video-captions

Sous-titres vidéo

Une seule commande transforme un fichier vidéo (ou audio) en sous-titres agréables à lire, et éventuellement en un MP4 sous-titré. Les segments bruts de reconnaissance vocale coupent souvent les mots en deux et sont trop longs ; cette compétence reconstruit les mots complets et les reformate en signaux temporels appropriés.

Quand l'utiliser

• « Ajoute des sous-titres à cette vidéo », « crée un SRT pour mon exposé », « grave des sous-titres ».
• « Fais des sous-titres style TikTok/Reels/Shorts » → utiliser --style shorts --burn.
• L'utilisateur a besoin d'un fichier .vtt pour une balise <track> de site web ou un téléchargement YouTube.

Étapes

1. Vérifier que MIRAGEA_API_KEY est définie (ne jamais l'afficher). Si absente, dire à l'utilisateur de créer une clé sur https://miragea.ai et export MIRAGEA_API_KEY=....

2. Lancer le script sur le fichier de l'utilisateur :

   python3 scripts/captions.py chemin/vers/video.mp4                 # → video.srt + video.vtt
   python3 scripts/captions.py chemin/vers/video.mp4 --burn          # + video.captioned.mp4
   python3 scripts/captions.py chemin/vers/short.mp4 --style shorts --burn   # sous-titres pop, centrés
   

3. Lire le JSON affiché (srt, vtt, video, cues) et donner les chemins à l'utilisateur.

4. Si l'utilisateur souhaite modifier le texte, éditer le fichier .srt (garder les horodatages) et relancer avec --burn : la transcription est mise en cache dans <fichier>.transcript.json, donc les ré-exécutions sont gratuites.

Options

Option	Par défaut	Effet
--style standard	oui	2 lignes x 42 caractères, 1 à 7 s par signal (conventions de diffusion)
--style shorts		1 à 3 mots par signal, MAJUSCULES, centrés lors du gravage
--burn	désactivé	Écrit <nom>.captioned.mp4 (H.264, piste audio originale copiée)
--upper	désactivé	Met en majuscules les sous-titres standards
--out-dir DIR	à côté de l'entrée	Répertoire de sortie
--force	désactivé	Ignore le cache de transcription et retranscrit

Coût et limites

Seule une piste audio mono 16 kHz est téléchargée (pas la vidéo), jusqu'à 90 minutes / 1 Go par fichier. Miragea facture 3 points par seconde d'audio ; les ré-exécutions en cache sont gratuites. Vérifier les tarifs en direct avec GET https://miragea.ai/v1/capabilities.

Dépannage

• ffmpeg not found → installer ffmpeg (brew install ffmpeg, sudo apt install ffmpeg, winget install ffmpeg).
• 401 → la clé est erronée ; 402 → recharger le compte sur miragea.ai ; 429 → attendre et relancer (sûr de réessayer).
• Sous-titres légèrement en avance/retard sur les clips très musicaux : relancer avec --force après avoir coupé les intros.

Voir examples/ pour des exemples de sortie.