yyert123/voix-off-enregistrement-écran

Voix-off d'enregistrement d'écran

La partie lente de la narration d'un enregistrement d'écran n'est pas la voix, c'est le calage : aligner chaque phrase avec le clic qu'elle décrit, et corriger les endroits où la phrase est plus longue que l'action. Cette compétence fait les deux automatiquement et ne laisse jamais la narration dériver ou se chevaucher.

Quand l'utiliser

• « Ajoute une voix-off à cette démo / tutoriel / enregistrement d'écran. »
• « J'ai enregistré mon écran en silence, narre-le » ou « Je ne veux pas utiliser ma propre voix / mon accent. »
• « Fais correspondre la narration à ce qui se passe à l'écran. »

Étapes

1. Vérifie que MIRAGEA_API_KEY est défini (ne l'affiche jamais). Voix : demande une fois l'identifiant vocal Miragea de l'utilisateur, ou une URL publique d'un extrait de sa voix plus ses mots exacts. Suggère export MIRAGEA_VOICE_ID=... pour ne plus jamais le redemander. Ne clone une voix que si l'utilisateur en est propriétaire ou a l'autorisation de l'utiliser.

2. Trouve les étapes et crée un modèle de script :

   python3 scripts/scenes.py demo.mp4      # -> demo.frames/*.jpg, demo.frames/steps.json, demo.script.txt
   

3. Regarde les images dans demo.frames/ (tu peux lire les images) et écris une phrase claire par étape dans demo.script.txt après chaque horodatage, en remplaçant le commentaire # step. Reste dans la limite de ~N mots pour que la ligne tienne avant l'étape suivante. Fusionne, déplace ou supprime librement les étapes. Si l'utilisateur a fourni son propre script, place ses phrases aux horodatages correspondants.

4. Vérifie le timing sans rien dépenser :

   python3 scripts/voiceover.py demo.mp4 demo.script.txt --dry-run
   

   Raccourcis toute ligne marquée will freeze si l'utilisateur ne veut aucune image figée.

5. Rendu :

   python3 scripts/voiceover.py demo.mp4 demo.script.txt --voice VOICE_ID            # sous-titres en fichiers
   python3 scripts/voiceover.py demo.mp4 demo.script.txt --burn --music bed.mp3      # sous-titres incrustés + musique ducking
   

6. Donne à l'utilisateur les chemins depuis le JSON imprimé : video (MP4 narré), voice_track (WAV pour son éditeur), srt/vtt. Mentionne frozen_seconds si c'est supérieur à zéro.

7. Pour changer une ligne, édite le script et relance l'étape 5 : les lignes inchangées proviennent du cache gratuitement.

Format du script

[00:00] Bienvenue sur Acme. Voici le tableau de bord que vous voyez après vous être connecté.
[00:04] Cliquez sur Nouveau projet, tapez un nom et choisissez l'équipe qui doit le posséder.
[01:02.5] Voilà. Votre projet est prêt.

Horodatages acceptés : [mm:ss], [h:mm:ss], mm:ss.s, 12.5s. Les lignes commençant par # sont des commentaires.

Comment fonctionne le calage

• Chaque ligne commence exactement à son horodatage ; 0,25 s de respiration est conservée avant l'étape suivante.
• Une ligne plus longue que son créneau est accélérée, au maximum --max-speed (par défaut 1,15x, toujours naturel).
• Si elle ne tient toujours pas, la vidéo maintient la dernière image de cette étape jusqu'à la fin de la phrase, puis continue. Les lignes suivantes se décalent du même montant, donc le calage n'est jamais perdu.
• Les sous-titres sont chronométrés en fonction de la durée réelle de parole de chaque ligne (2 lignes x 42 caractères max).
• Le volume est normalisé à environ -16 LUFS (norme YouTube/web). La musique, si présente, est réduite (ducked) sous la parole.

Options

Option	Défaut	Rôle
--voice ID / --ref-url URL --ref-text TEXT	env	Voix Miragea enregistrée, ou clonage depuis un clip public (texte exact = taux 1x moins cher)
--model	expressive	ou standard
--max-speed	1,15	Accélération max avant de figer les images
--burn	désactivé	Incruster les sous-titres dans la vidéo
--music FILE	aucun	Musique de fond, en boucle et avec ducking automatique
--keep-audio	désactivé	Conserver le son original de l'enregistrement, en sourdine, sous la voix
--dry-run		Afficher le plan des créneaux avec un débit de parole estimé ; aucun appel API
-o FILE	VIDEO.voiceover.mp4	Chemin de sortie ; l'original n'est jamais modifié

Coût et limites

La parole est facturée au caractère par Miragea (1x avec une voix enregistrée ou un texte de référence exact ; tarifs en direct à GET https://miragea.ai/v1/capabilities). Une démo de 3 minutes fait généralement 2 000 à 3 000 caractères. Chaque ligne ne doit pas dépasser 2 000 caractères. Les clips de référence doivent être des URLs publiques jusqu'à ce que le point de terminaison de téléversement de Miragea soit disponible.

Dépannage

• pas d'horodatage / pas après la ligne précédente -> corrige la ligne du script mentionnée dans l'erreur.
• aucune voix choisie -> passe --voice ou définis MIRAGEA_VOICE_ID.
• 401 clé erronée, 402 recharger sur miragea.ai, 429 attendre et réexécuter (les lignes en cache ne sont pas refacturées).
• Trop ou trop peu d'étapes de la part de scenes.py -> --threshold 0.02 (plus) / 0.08 (moins), --min-gap.

Voir examples/ pour un script réel, le JSON du plan et les sous-titres produits.