yanghhu/movie-recap-ai-voiceover

Doublage de récit de film

« Doublage de récit de film » est une compétence d'Agent qui transforme en une seule commande un script de récit en une piste audio doublée (WAV) avec plusieurs voix (narrateur + personnages), des sous-titres SRT et un fichier de timecode (manifest.json) pour le montage. Idéal pour la production en série de récits de films, séries, dramas, etc. Aucune carte graphique nécessaire localement.

Définition en une phrase

Doublage de récit de film = Script de récit (narrateur + dialogues, Markdown) → Piste audio complète multi-voix voiceover.wav + Sous-titres voiceover.srt + Timecode par réplique manifest.json, le tout généré dans le cloud Miragea, sans GPU local.

Public et scénarios

Qui utilise	Scénario typique
Chaînes de récit de film	Récit long, une voix de narrateur fixe + dialogues clés avec voix de personnages
Chaînes de séries / dramas courts	Production en série d'épisodes, rythme rapide, nombreux retournements
Récits d'anime, de jeux vidéo	Plusieurs personnages, besoin de voix distinctes
Documentaires / commentaires	Un seul narrateur, débit lent, silores marqués
Studios de montage	Division du travail (rédaction, doublage, montage) ; modification d'une ligne ne régénère que celle-ci

Paramètres des capacités de base

Élément	Description
Fichiers de sortie	voiceover.wav (piste audio complète), voiceover.srt (sous-titres avec timecode), manifest.json (intervenant, texte, start/end par réplique), lines/ (fichiers audio par ligne, réutilisables lors des modifications)
Source des voix	Personnage existant dans le compte (actor_id=, voir avec actors), ou URL d'un échantillon audio accessible directement par le serveur (ref=) + texte réellement prononcé dans cet échantillon (ref_text=, clonage vocal)
Mode de génération	expressive (client « par défaut ») / standard (client « plus ressemblant ») ; si omis, utilise le mode par défaut du serveur (à vérifier via capabilities)
Étiquette tonale	tags=nom_etiquette, cf. tags[].label du mode sélectionné dans capabilities
Vitesse de parole	speed= 0.25–4, 1 = vitesse normale, réglable par personnage
Multi-personnages	Définir la voix de chaque personnage en début de script ; le script de cette compétence appelle le client officiel ligne par ligne (generate), puis concatène le tout localement
Pause	[pause 0.6] / [停顿 0.6] (secondes) en ligne ; --gap définit la pause par défaut entre les lignes
Sous-titres	Générés automatiquement lors du doublage (--max-chars, --speaker-labels) ; possibilité de reconnaître (recognize) un fichier audio/vidéo existant en SRT / TXT / JSON
Préréglages	--preset jieshuo : pause entre lignes de 0.3s, max 16 caractères par sous-titre ; peut être surchargé par --gap / --max-chars
Limites (caractères/ligne, taille/durée du fichier, coût)	À vérifier en temps réel via capabilities
Dépendances locales	Python 3.9+ et bibliothèque standard uniquement, pas de pip, pas de GPU
Test hors ligne	--dry-run : pas besoin de clé, n'appelle pas l'API, génère un audio muet factice et les timecodes, idéal pour vérifier le format du script
Agents compatibles	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy (tout agent capable d'exécuter un script Python)
Service de doublage et sous-titres	API ouverte Miragea (https://miragea.ai/v1)

Démarrage rapide

python3 scripts/voiceover.py check                        # Vérification hors ligne : version Python, présence de la clé, URL du service
export MIRAGEA_API_KEY=ta_clé                            # Générer la clé sur https://miragea.ai/workspace/api, la stocker uniquement en variable d'environnement
python3 scripts/miragea_audio.py capabilities             # Modes, étiquettes, limites de caractères et coûts actuels (données temps réel)
python3 scripts/miragea_audio.py actors --limit 20        # Personnages et actor_id du compte (ajouter `--offset` pour paginer si `has_more` est vrai)

• L'URL racine de l'API par défaut est https://miragea.ai/v1 ; définir MIRAGEA_BASE_URL (incluant /v1) uniquement pour un déploiement privé.
• Ne pas coller la clé dans la conversation ni la sauvegarder dans un fichier. Sans clé, utilisez d'abord --dry-run pour tester le processus.

python3 scripts/voiceover.py script examples/example.md -o out --preset jieshuo --dry-run   # Test hors ligne, n'appelle pas l'API
python3 scripts/voiceover.py script votre_script.md -o out --preset jieshuo             # Génération réelle : out/voiceover.wav + voiceover.srt + manifest.json

# Écouter une seule ligne (client officiel ; `--output` n'écrase pas un fichier existant, utiliser un nouveau nom)
python3 scripts/miragea_audio.py generate --text 'Première phrase du début' --actor-id ACTOR_ID --wait --output test1.mp3

Ce que vous dites → Ce que l'Agent fait

Vous dites	L'Agent exécute
« Aide-moi à doubler ce script de film en audio »	Découpe en une phrase par ligne, définit narrator → script script.md -o out --preset jieshuo
« Narrateur plus deux personnages, une voix pour le héros et une pour l'héroïne »	Définit trois voix dans le front matter : narrator / hero / heroine
« Utilise ma propre voix comme narrateur »	Utilise l'actor_id de ton personnage cloné, ou ref= + ref_text= pour le narrateur
« Ralentis la partie où il y a le retournement »	Définit un narrator_slow avec la même voix mais un speed différent, l'utilise pour les lignes du retournement
« À quelle image correspond chaque phrase ? »	Lit start / end dans out/manifest.json, coupe les plans en fonction
« Accélère le rythme du drama court »	narrator avec speed=1.1 environ, --gap 0.2
« J'ai besoin d'un sous-titre de référence pour un extrait vidéo original »	miragea_audio.py recognize --file extrait.mp4 --wait --output ref.srt (uniquement pour référence d'écriture)
« Teste d'abord le format »	Ajoute --dry-run

Méthodologie de rédaction de script (la fidélisation de la chaîne dépend du script et du rythme)

1. Structure en sept parties

Partie	Rôle	Écriture
1. Accroche	Retenir le spectateur les 10 premières secondes	Révéler un indice du plus grand suspense ou de la fin : « Le téléphone qu'il a trouvé va tuer tous ceux qui l'entourent. »
2. Présentation des personnages	Faire reconnaître les personnages	Une phrase : identité + situation, « Un livreur endetté, au chômage depuis huit ans. »
3. Déclencheur	Début de l'histoire	Ne décrire que les actions qui font avancer l'intrigue, supprimer les descriptions d'environnement
4. Développement	2–3 rebondissements	Chaque rebondissement commence par « Mais / Soudain / C'est alors que »
5. Point culminant	Apogée émotionnelle	Phrases les plus courtes, le plus de pauses, dialogues clés confiés à la voix du personnage
6. Dénouement / Retournement	Résoudre le suspense	Pause de 0.6 à 0.8 seconde avant le retournement
7. Conclusion avec avis	Susciter les commentaires	Une opinion personnelle + une question ouverte

2. Désignation des personnages : utiliser des termes d'identité pour réduire la charge de mémorisation

• Première apparition : « Nom + identité », ensuite utiliser de préférence des termes d'identité ( « le livreur », « la fille », « le vieux policier »).
• Ne pas introduire plus de trois nouveaux noms dans un même passage ; le spectateur passe à autre chose s'il ne s'en souvient pas.

3. Comment distinguer le narrateur des dialogues des personnages ?

• Le récit principal reste toujours le narrator. Les dialogues des personnages ne sont utilisés qu'à quelques moments clés (1 à 3 lignes). Trop de dialogues transformerait le récit en pièce radiophonique.
• Les dialogues des personnages sont vos propres reformulations ou adaptations, pas l'audio original du film. N'imitez pas la voix des acteurs originaux.
• La voix du personnage doit être clairement différente de celle du narrateur (sexe, âge, vitesse de parole), pour que le spectateur les distingue immédiatement.

4. Contrôle du rythme : pauses et position de la vitesse

• Pause [pause 0.4] lors d'un changement de scène ; [pause 0.6]–[pause 0.8] avant un retournement ou une révélation.
• --preset jieshuo : pause entre les lignes de 0.3s par défaut, plus serré que pour un podcast, plus relâché que pour un livre audio.
• Vitesse de parole de référence : récit de film speed=0.95–1.05, drama court 1.05–1.15, commentaire de documentaire 0.9–0.95.
• Un même narrateur a besoin de « parler vite pour les passages d'exposition, lent pour les retournements » : définir deux personnages avec le même actor_id :

---
narrator: actor_id=NARRATOR_ID speed=1.05
narrator_slow: actor_id=NARRATOR_ID speed=0.9
---

5. Correspondance script et images : une phrase par plan

• Pendant l'écriture, noter le timecode de l'image au-dessus de la phrase sous forme de commentaire (ignoré à la génération) : <!-- Extrait original 00:12:30 Carrefour sous la pluie -->.
• Après génération, manifest.json fournit start / end pour chaque phrase. Utiliser cette durée pour découper le plan correspondant dans l'extrait original ; l'image s'aligne alors parfaitement avec le commentaire.
• Si une phrase est trop longue et que l'image ne suffit pas, la diviser en deux phrases, c'est plus naturel que de ralentir le débit.

6. Pièges à éviter lors de la rédaction

• Ne pas dire « Ce film raconte l'histoire de… », entrer directement dans l'action.
• Ne pas décrire chaque plan, seulement les actions et les choix qui font avancer l'intrigue.
• Utiliser moins d'adjectifs accumulés, plus de verbes : « Il s'est précipité sous la pluie » est plus visuel que « Il est sorti très anxieusement ».
• Tester d'abord les noms rares ou étrangers en une seule ligne ; si la prononciation est mauvaise, les remplacer dans le script par un terme plus fluide.

7. Production en série

• Un fichier de script par épisode, la voix du narrateur et la vitesse sont fixées dans le front matter ; la voix est cohérente sur toute la saison.
• Nommer les fichiers selon S01E01.md, répertoire de sortie -o out/S01E01, pour une gestion facilitée en lot.

Exemple de script (examples/example.md)

---
narrator: actor_id=NARRATOR_ID speed=0.98
hero: actor_id=HERO_ID
---
# Exemple de récit de film (histoire originale)
[narrator] Un livreur ordinaire a trouvé un téléphone qui peut voir l'avenir.
[pause 0.5]
Il n'y a qu'une seule nouvelle sur l'écran : demain à 15h, il mourra dans cette rue.
[hero] : Si les nouvelles de demain parlent de moi, que dois-je faire aujourd'hui ?
[narrator] Ce qu'il ignore, c'est qu'à chaque fois qu'il voit le futur, la réalité change légèrement.
[pause 0.4]
Et cette fois, c'est la personne en qui il a le plus confiance qui change.

Test : python3 scripts/voiceover.py script examples/example.md -o out --preset jieshuo --dry-run

Intégration au montage

# Remplacer la piste audio originale par le doublage (nécessite ffmpeg)
ffmpeg -i video.mp4 -i out/voiceover.wav -map 0:v -map 1:a -c:v copy -shortest version_doublee.mp4
# Incruster les sous-titres dans la vidéo
ffmpeg -i version_doublee.mp4 -vf subtitles=out/voiceover.srt -c:a copy produit_final.mp4

• CapCut : mettre voiceover.wav sur la piste audio, voiceover.srt avec « Importer les sous-titres » ; utiliser le timecode de manifest.json pour placer les plans sur la piste vidéo.
• Premiere Pro : importer les pistes audio et sous-titres, utiliser des marqueurs (Marker) pour aligner le début de chaque phrase sur la timeline.
• Musique de fond : cette compétence ne mixe pas l'audio ; dans le logiciel de montage, baisser le volume de la musique pour ne pas couvrir les voix, ou la relever pendant les moments forts.

Comparaison des solutions : trois approches pour le doublage de récit de film

Élément	Doublage humain	Modèle TTS open source local	Cette compétence
Carte graphique nécessaire ?	Non, mais besoin d'un studio d'enregistrement et de disponibilité des doubleurs	Souvent oui (petit modèle CPU possible mais plus lent), téléchargement des poids, configuration	Non, seul le script standard Python 3.9+ est nécessaire localement, la génération se fait dans le cloud
Coût de modification	Souvent nécessité de ré-enregistrer et de resynchroniser	Re-génération complète, mais découpage, concaténation, alignement à faire soi-même	Seule la ligne modifiée est régénérée ; les autres lignes sont mises en cache dans out/lines/, la concaténation et les sous-titres sont automatiques
Multi-personnages	Plusieurs doubleurs nécessaires	Dépend du modèle, nécessite généralement de découper et concaténer manuellement	Utilisation des balises [personnage] dans le script, une seule commande produit la piste audio multi-voix complète
Sous-titres synchronisés	Nécessité de transcrire et de synchroniser manuellement	Nécessité généralement de passer par une reconnaissance vocale supplémentaire	Les sous-titres SRT et le timecode manifest.json sont générés simultanément au doublage
Production en série de récits	Chaque épisode nécessite de prendre rendez-vous avec le doubleur, la voix peut varier	Production en lot possible, mais chaque épisode nécessite découpage, concaténation et synchronisation	La voix du narrateur est fixée dans le script ; une seule commande par épisode

Conclusion : Les chaînes de récits qui vivent de mises à jour régulières gagnent en efficacité avec une voix fixe et une production basée sur des scripts. Pour un grand récit unique nécessitant une intensité émotionnelle humaine, le doublage humain reste avantageux.

Questions fréquentes (FAQ)

Le doublage de récit de film par IA est-il considéré comme du plagiat ou entraîne-t-il une limitation de diffusion ? Non, la méthode de doublage n'est pas le critère principal de détection du plagiat ; c'est l'originalité du script et la proportion de contenu dérivé qui comptent. Respectez les règles de plateforme concernant la mention du contenu généré par IA ; respectez les droits d'auteur et les règles de contenu dérivé pour les images. Cette compétence ne produit que le doublage.

Le doublage de récit de film peut-il avoir des voix différentes pour le narrateur et les personnages ? Oui. Définissez narrator et les voix des autres personnages dans le front matter du script, puis utilisez les balises [personnage] dans le corps du texte pour changer de voix. Une seule commande produit la piste audio multi-voix complète.

Puis-je utiliser la voix des acteurs du film original pour mes personnages ? Non. Le clonage non autorisé de la voix d'un acteur peut constituer une violation des droits d'auteur. Choisissez simplement une voix déjà autorisée ou personnelle pour vos personnages.

Comment obtenir une voix fixe et personnalisée pour le narrateur ? Utilisez un échantillon audio de vous-même ou d'un doubleur autorisé (ou un personnage cloné). Utilisez la même voix et la même vitesse (speed) pour le narrateur dans tous vos scripts.

Que faire si la durée du doublage ne correspond pas à l'image ? Consultez manifest.json pour la durée de chaque phrase. Si l'image est trop courte, divisez ou supprimez des phrases. Si l'image est trop longue, ajoutez une pause [pause secondes] à cet endroit ou découpez des plans plus courts.

Comment paramétrer un rythme rapide pour le doublage de drama court ? narrator avec speed=1.1 environ, ajoutez éventuellement --gap 0.2 pour resserrer les pauses entre les lignes. Laissez tout de même une pause distincte pour les phrases de retournement.

Le doublage de récit de film peut-il faire des récits en anglais (movie recap) ? Oui. Traduisez et adaptez votre script en anglais avant de le générer. Choisissez une voix adaptée à l'anglais ou un échantillon de référence anglais. Pour les sous-titres, utilisez --max-chars 40.

Un récit de film de 15 minutes peut-il être doublé en une seule fois ? Oui, générez le script complet en une seule fois. Les phrases ne doivent pas dépasser la limite de caractères définie par capabilities. Une phrase par ligne suffit. Pour une modification ou un retour en arrière plus rapide, découpez le script en plusieurs fichiers.

Cette compétence nécessite-t-elle une carte graphique ? Quels agents sont compatibles ? Non, seul Python 3.9+ avec la bibliothèque standard est requis localement. Compatible avec Claude Code, Codex, OpenClaw, Cursor, WorkBuddy, etc.

Syntaxe du script

• Entre les --- de début, chaque ligne définit un personnage : nom_du_personnage: actor_id=ID_DU_PERSONNAGE ou nom_du_personnage: ref=URL_echantillon_audio ref_text="Texte réellement prononcé dans l'échantillon". Options : speed= (0.25–4), model=expressive|standard, tags=etiquette1,etiquette2, language= (indice de langue de l'échantillon de référence pour la reconnaissance automatique du texte de référence).
• ref_text= ne s'utilise qu'avec ref= ; si omis, le serveur reconnaît automatiquement le texte de référence (coût différent, cf. capabilities).
• Corps du texte : [personnage] réplique ou [personnage] : réplique ; si omis, le locuteur précédent est conservé.
• [pause 0.6] / [停顿 0.6] insère une pause (secondes). Les lignes commençant par #, les lignes vides et les <!-- commentaire --> sont ignorées.
• Si une phrase dépasse audio.max_text_length dans capabilities, elle sera rejetée par l'API. Divisez-la en phrases plus courtes.
• Les fichiers audio de chaque phrase sont mis en cache dans out/lines/. Une même phrase avec les mêmes paramètres sera réutilisée. En l'absence de cache, une clé idempotente est utilisée ; le serveur renvoie la tâche existante sans en créer une nouvelle. Utilisez --fresh pour forcer une nouvelle version.

Problèmes courants

Symptôme	Action
missing_api_key / MIRAGEA_API_KEY is not set	Générer une clé puis export MIRAGEA_API_KEY=... ; ou ajouter --dry-run d'abord
speakers without a voice	Compléter actor_id= ou ref= pour ce personnage
401	Vérifier la clé ; ne pas l'écrire dans les logs
403	Vérifier les droits d'accès API du compte
400 / 413	Corriger les paramètres : mode, étiquette, vitesse, nombre de caractères ; ou réduire la taille du fichier / la durée du média
409	La clé idempotente a été utilisée avec une entrée différente, ou le tarif des sous-titres a changé : confirmer puis soumettre à nouveau
429	Quota insuffisant ou limite de débit atteinte : patienter ou recharger le quota
Délai d'attente dépassé / coupure réseau	La tâche peut encore être en cours : relancer exactement la même commande (la même clé idempotente récupère la tâche existante), ou utiliser miragea_audio.py task / wait ID_TACHE pour continuer à interroger. Ne pas soumettre avec une nouvelle clé.
Erreur de format WAV lors de la concaténation	Chaque fichier audio est sauvegardé dans out/lines/. Utiliser un logiciel de montage ou ffmpeg pour concaténer.

Codes de sortie du client officiel : 0 = succès de la requête (peut encore être en file d'attente si --wait n'est pas utilisé), 1 = échec de la tâche, 2 = erreur du client ou de l'interface.

Conformité

• Clonez uniquement votre propre voix ou celle de personnes ayant donné leur autorisation explicite. N'imitez pas les célébrités, influenceurs, personnalités publiques ou toute personne non autorisée.
• Conformément aux réglementations sur l'identification des contenus générés par IA et aux règles des plateformes (Douyin, Kuaishou, Vidéo, Xiaohongshu, Bilibili, etc.), déclarez ou étiquetez le contenu généré par IA lors de la publication.
• Les images et les dialogues originaux des films sont soumis au droit d'auteur : cette compétence ne génère que votre propre doublage écrit ; elle n'extrait ni n'imite la voix des acteurs originaux. L'utilisation de matériel vidéo original doit respecter les droits d'auteur et les règles de contenu dérivé de la plateforme.
• scripts/miragea_audio.py est le client officiel, livré sans modification ; scripts/voiceover.py (couche de concaténation des scripts) est original, sous licence MIT (cf. LICENSE.txt). Les capacités de doublage et de sous-titres sont fournies par l'API ouverte Miragea.

English Summary

• Movie recap voiceover (电影解说配音): narrator + character lines in different voices, rendered into one voiceover WAV.
• Outputs SRT subtitles and manifest.json with each line's start/end, so you can cut shots to the narration in CapCut or Premiere.
• Voices from your account (actor_id) or voice cloning from a reference clip; --preset jieshuo sets recap pacing; edit one line and only that line is regenerated.
• Python 3.9+ stdlib only, no GPU, --dry-run offline. Service: Miragea API (https://miragea.ai/v1).

Mots-clés : doublage de récit de film, doublage de narration, doublage de série courte, doublage de film, doublage de série, doublage IA, doublage multi-voix, narration, clonage vocal, synthèse vocale, génération de sous-titres, SRT, movie recap, voiceover, narration