yanghhu/ai-voiceover

Voix Off IA

Utilisez la CLI voiceover (paquet ai-voiceover-studio, Python 3.9+) pour générer une narration.

Vérification de configuration

1. voiceover --version — si manquant : pip install -e "<repo>[edge]" ([edge] = voix gratuites, [yaml] = voices.yaml).
2. Exécutez voiceover doctor --json et corrigez tout fail signalé (il n'affiche jamais les clés).
3. Moteurs : sans clés le moteur gratuit edge est utilisé (internet nécessaire, pas de compte). MIRAGEA_API_KEY bascule le défaut vers Miragea (clonage vocal, modèles expressifs) ; OPENAI_API_KEY active --provider openai. Ne demandez jamais à l'utilisateur de coller une clé dans le chat, ne l'affichez jamais, ne l'écrivez jamais dans des fichiers.
4. La sortie MP3 et la vidéo nécessitent ffmpeg (avec libass pour les légendes incrustées).

Workflow : voix d'un script

1. Préparez le script (Markdown ou TXT). Une balise de locuteur par ligne ou paragraphe :

   [NARRATEUR] : Ligne d'ouverture.
   Les lignes non balisées continuent le locuteur actuel.
   
   [ALEX](tags=excited, speed=1.1) : Un personnage différent.
   [pause 1]
   

   Les titres, commentaires HTML, blocs de code et tableaux sont ignorés.
2. Voix (optionnel). Sans fichier de voix, chaque locuteur reçoit automatiquement sa propre voix, choisie dans la langue du script. Pour choisir : voiceover voices --json (ajoutez --provider edge --filter en-GB pour les voix Edge comme en-GB-SoniaNeural ; pour Miragea voice_id = identifiant de l'acteur). Si deux voix partagent un nom, demandez à l'utilisateur laquelle. Avec Miragea, une voix peut aussi être une URL audio de référence publique plus sa transcription exacte (reference_text). Clonez uniquement les voix que l'utilisateur possède ou a la permission d'utiliser.
3. Écrivez voices.json si l'utilisateur a choisi des voix (clés en majuscules) :

   {"NARRATEUR" : {"actor_id": "en-US-AndrewNeural"}, "ALEX" : {"actor_id": "en-US-AvaNeural", "speed": 1.05}}
   

4. Dry run (hors ligne, valide les locuteurs et le timing) : voiceover script script.md -o out/ --dry-run --json
5. Générer : voiceover script script.md [--voices voices.json] -o out/ --json Produit out/voiceover.mp3, out/voiceover.srt, out/manifest.json, out/segments/.
6. Signalez les chemins sauvegardés et la durée. Ne déclarez pas le succès sauf si la commande s'est terminée avec le code 0.

Autres commandes

• Une ligne : voiceover say "texte" [--voice <voice id|https://ref.wav>] [--ref-text "..."] [--lang en] -o line.mp3
• Vidéo sans visage : voiceover video [--images slides/] --script script.md -o video.mp4 [--style clean|box|bold|minimal] [--size 1080x1920] [--speaker-labels] [--subtitles burn|sidecar|none] Les légendes sont incrustées par défaut. Une image par segment donne un timing de diapositive exact ; sans --images un fond dégradé est utilisé. Pour les Shorts, utilisez --size 1080x1920 --style bold.
• Sous-titres par reconnaissance vocale au lieu du timing (Miragea) : ajoutez --subtitles recognize (un appel API supplémentaire).
• Reprendre une tâche après un délai d'attente : voiceover task <task_id> --wait -o out.mp3.

Règles

• Réexécuter la même commande est sûr : les segments inchangés proviennent du cache et les requêtes distantes utilisent des clés d'idempotence. Utilisez --fresh uniquement lorsque l'utilisateur souhaite une nouvelle prise.
• En cas de délai d'attente, conservez le task_id signalé et reprenez avec voiceover task ; ne soumettez pas à nouveau.
• Codes de sortie : 0 ok, 1 échec du fournisseur de tâche, 2 erreur d'utilisation/config/API. Avec --json, les erreurs sont {"error" : {"code", "message", "http_status", "retryable"}, "task_id"?}.
• 401 : clé rejetée → l'utilisateur vérifie la variable de clé. 403 : le compte n'a pas accès à l'API. 429 : quota/limite de débit → attendez, ne bouclez pas. 400 : corrigez le texte/la voix/la vitesse/les balises.
• proxy_unsupported (edge) : définissez VOICEOVER_EDGE_PROXY ou désactivez HTTPS_PROXY pour la commande.
• Langues : edge couvre 75 langues ; Miragea couvre le chinois, l'anglais, le japonais, le coréen, l'allemand, le français, le russe, le portugais, l'espagnol, l'italien (avec clonage vocal).