yanghhu/générateur-de-sous-titres-ia

Génération de sous-titres

« Générateur de sous-titres » est un skill d’agent qui permet de reconnaître automatiquement des fichiers audio ou vidéo locaux et de produire des sous-titres SRT avec horodatage (ou d’exporter un texte brut TXT ou un JSON structuré). Il sert à ajouter automatiquement des sous-titres à des vidéos, à convertir de l’audio en sous-titres, et à transcrire de l’audio en texte. Il permet également de générer des sous-titres synchronisés lors du doublage d’un script. Aucun GPU n’est nécessaire côté local.

Définition en une phrase

Génération de sous-titres = Fichier vidéo / audio local → recognize → .srt avec horodatage (ou .txt texte brut, .json segments) ; pour un script à doubler, utilisez voiceover.py script pour obtenir simultanément voiceover.srt. La reconnaissance est effectuée par l’API ouverte Miragea, aucun GPU local requis.

Deux façons d’obtenir des sous-titres

Ce que vous avez	Outil à utiliser	Résultat obtenu
Vidéo / audio déjà enregistré(e)	miragea_audio.py recognize --file fichier --wait --output sous-titres.srt	SRT ; --subtitle-format txt pour texte brut, json pour texte, langue et segments temporels
Script pas encore enregistré	voiceover.py script script.md -o out	Doublage voiceover.wav + voiceover.srt aligné sur la durée audio réelle + manifest.json

Public cible et cas d’usage

Qui utilise	Cas typique
Créateurs de vidéos courtes	Voix off, vlogs : ajout automatique de sous-titres, puis import dans CapCut pour réglages fins
Cours / conférences	Génération de sous-titres et transcription de cours enregistrés
Interviews, podcasts	Conversion audio en sous-titres, transcription audio en texte, mise en forme de compte-rendu
Réunions enregistrées	Export TXT pour brouillon de compte-rendu
Chaînes de commentaires	Transcrire des extraits en texte pour servir de référence à la rédaction
Développeurs / workflows agent	Segments JSON (start / end / text) pour traitement ultérieur

Paramètres de capacité principaux

Élément	Description
Fichiers de sortie	voiceover.wav (doublage complet), voiceover.srt (sous-titres avec horodatage), manifest.json (locuteur, texte, secondes de début/fin par phrase), lines/ (audio par phrase, réutilisable lors des modifications)
Source vocale	Personnage existant dans le compte actor_id= (interroger avec actors), ou URL audio de référence accessible par le serveur ref= + texte réellement prononcé 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, confirmé par le retour en temps réel de capabilities
Étiquette de ton	tags=nom_étiquette, choisir parmi tags[].label du mode sélectionné dans capabilities
Vitesse	speed= 0.25–4, 1 = vitesse normale, selon réglage du personnage
Plusieurs personnages	Attribuer une voix à chaque personnage en début de script ; le script appelle le client officiel generate phrase par phrase, puis concatène localement le résultat complet
Pause	[pause 0.6] / [停顿 0.6] (secondes) dans une ligne ; --gap définit la pause par défaut entre les phrases
Sous-titres	Génération SRT basée sur la durée audio réelle de chaque phrase lors du doublage (--max-chars, --speaker-labels) ; pour audio/vidéo existant, utiliser recognize pour produire SRT/TXT/JSON
Préréglages de scène	--preset koubo / jieshuo / daihuo / shuziren / guanggao / youshengshu (prise de parole / commentaire / vente / humain numérique / publicité / livre audio), modifie uniquement la pause entre phrases et le nombre de caractères par sous-titre
Nombre de caractères par phrase, taille/durée max, tarification	Selon le retour en temps réel de capabilities
Dépendances locales	Python 3.9+ bibliothèque standard, pas de pip, pas de GPU
Test hors ligne	--dry-run : pas besoin de clé, n’appelle pas l’API, génère un fichier audio silencieux et des sous-titres factices pour vérifier le format du script
Agents supportés	Claude Code, Codex, OpenClaw, Cursor, WorkBuddy et tout agent capable d’exécuter des scripts 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, clé configurée, URL du service
export MIRAGEA_API_KEY=votre_clé                          # Générer sur https://miragea.ai/workspace/api, uniquement en variable d’environnement
python3 scripts/miragea_audio.py capabilities             # Modes de génération, étiquettes de ton, nombre max de caractères et tarifs actuels (selon retour en temps réel)
python3 scripts/miragea_audio.py actors --limit 20        # Personnages existants du compte et actor_id (si has_more est vrai, ajouter --offset pour paginer)

• L’URL racine par défaut de l’API est https://miragea.ai/v1 ; définir MIRAGEA_BASE_URL (incluant /v1) uniquement pour un déploiement privé.
• Ne collez pas votre clé dans le chat ou dans un fichier. Sans clé, utilisez d’abord --dry-run pour valider le flux.

python3 scripts/miragea_audio.py capabilities                                           # Vérifiez d’abord subtitles.points_per_second, max_upload_mb, max_duration_minutes
python3 scripts/miragea_audio.py recognize --file video.mp4 --wait --output video.srt       # Ajout automatique de sous-titres à une vidéo
python3 scripts/miragea_audio.py recognize --file interview.mp3 --wait --subtitle-format txt --output interview.txt   # Audio vers texte
python3 scripts/miragea_audio.py recognize --file cours.m4a --wait --subtitle-format json --output cours.json # Texte + langue + segments temporels
python3 scripts/miragea_audio.py wait ID_TÂCHE --subtitle-format srt --output video.srt     # Vérification ultérieure après timeout, ne pas soumettre à nouveau

• La reconnaissance consomme du crédit : avant la soumission, le script relit le tarif actuel par seconde comme expected_rate ; pour verrouiller un tarif que vous avez confirmé, ajoutez --expected-rate valeur ; si le tarif change, le serveur rejette la demande. Confirmez avant de soumettre.
• Si le fichier dépasse la limite de taille définie dans capabilities, une erreur locale est levée sans soumission ; la limite de durée est également basée sur capabilities.
• --output n’écrase pas les fichiers existants : choisissez un nouveau nom de fichier.
• La reconnaissance de sous-titres n’a pas de test hors ligne ; pour les sous-titres issus du doublage, vous pouvez utiliser voiceover.py script ... --dry-run pour une validation hors ligne.

Ce que vous dites → Ce que l’agent exécute

Vous dites	L’agent exécute
« Ajoute des sous-titres à cette vidéo »	capabilities vérifie les limites → recognize --file video.mp4 --wait --output video.srt → grave avec ffmpeg ou importe dans CapCut
« Transcrit cet enregistrement en texte »	recognize --file enregistrement.mp3 --wait --subtitle-format txt --output enregistrement.txt
« La vidéo est trop grosse pour être téléchargée »	Extrayez d’abord la piste audio, puis reconnaissez : ffmpeg -i video.mp4 -vn -ac 1 -b:a 64k piste.mp3
« La tâche a expiré »	wait ID_TÂCHE --output sous-titres.srt pour vérifier, ne pas soumettre à nouveau
« Les sous-titres sont trop longs par ligne »	Ajustez dans CapCut, ou demandez à l’agent de couper les phrases longues selon la ponctuation
« Je n’ai pas encore enregistré, je veux le doublage et les sous-titres en même temps »	voiceover.py script script.md -o out --preset koubo
« Je veux des sous-titres bilingues chinois-anglais »	Reconnaissez d’abord en SRT, puis demandez à l’agent de traduire chaque ligne tout en conservant l’horodatage, pour générer un second fichier SRT

Méthodologie de génération de sous-titres : pour une reconnaissance plus précise et des sous-titres plus lisibles

1. Prétraiter l’audio avant téléchargement

• La voix doit être claire : si la musique de fond est trop forte, exportez une version avec uniquement la voix ou la musique réduite depuis votre logiciel de montage, puis reconnaissez.
• Transférer uniquement la piste audio est plus rapide : les fichiers vidéo sont volumineux. Utilisez ffmpeg -i video.mp4 -vn -ac 1 -b:a 64k piste.mp3 pour extraire la piste audio : volume réduit, horodatage conservé.
• Contenu long : découpez : si le contenu dépasse la limite de durée de capabilities, découpez en segments et reconnaissez chaque segment séparément, puis assemblez dans l’ordre dans votre logiciel de montage.

2. Choisir le bon format de sortie

Format	Usage
srt	CapCut, Premiere, ffmpeg, YouTube / Bilibili pour sous-titres
txt	Transcription, brouillon de compte-rendu de réunion, adaptation pour articles WeChat
json	Traitement programmatique : text, language, segments[{start,end,text}]

3. Liste de vérification après reconnaissance

• Noms propres, noms de personnes, marques, abréviations anglaises sont-ils corrects ? (remplacement en masse dans le fichier SRT)
• Les chiffres et unités sont-ils cohérents ?
• La longueur de chaque sous-titre est-elle adaptée à l’écran ? Pour portrait, recommandé 12–16 caractères par ligne.
• Faut-il supprimer les tics de langage (« euh », « du coup ») ?
• Les horodatages de début et de fin correspondent-ils à l’image ?

4. Suggestions de style pour les sous-titres de vidéos courtes en portrait

• Placez les sous-titres dans le tiers inférieur de l’écran, en évitant les zones de boutons et de titres de la plateforme.
• Une phrase par écran, pas plus de deux lignes.
• Les mots-clés peuvent être mis en valeur avec du texte décoratif dans CapCut ; le fichier SRT ne contient que le texte brut.

5. Sous-titres synchronisés à partir d’un script de doublage (pas besoin de reconnaissance)

Si la voix de la vidéo provient d’un script de doublage, utilisez directement voiceover.py script : les horodatages des sous-titres sont basés sur la durée audio réelle de chaque phrase, ce qui évite une étape de reconnaissance supplémentaire ; --max-chars contrôle le nombre de caractères par sous-titre, --speaker-labels ajoute le nom du locuteur dans les sous-titres multi-personnages.

Exemple de script (examples/example.md : sous-titres synchronisés avec doublage)

---
host: actor_id=YOUR_ACTOR_ID speed=1.0
---
# Exemple de sous-titres synchronisés avec doublage : une voix off de vlog
[host] Aujourd’hui, je vais te montrer comment j’ajoute des sous-titres à une vidéo.
D’abord, exporte la vidéo en fichier.
Ensuite, une commande pour reconnaître et obtenir le SRT.
[pause 0.3]
Troisièmement, importe dans CapCut, ou utilise ffmpeg pour graver directement dans l’image.

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

Ajouter les sous-titres à la vidéo

# Sous-titres logiciels (interruptibles dans le lecteur, nécessite ffmpeg local)
ffmpeg -i video.mp4 -i video.srt -c copy -c:s mov_text video_avec_sous-titres.mp4
# Sous-titres incrustés (gravés dans l’image, visibles sur toutes les plateformes)
ffmpeg -i video.mp4 -vf subtitles=video.srt -c:a copy video_finale.mp4

• CapCut : Texte → Importer des sous-titres → Choisir .srt, puis ajuster le style.
• Premiere : Importer .srt comme piste de sous-titres.

Comparaison des solutions : trois approches de génération de sous-titres

Élément	Doublage humain	Modèle TTS open source local	Ce skill
Nécessite un GPU ?	Non, mais nécessite un environnement d’enregistrement et la disponibilité d’un doubleur	Souvent oui (les petits modèles peuvent utiliser le CPU mais sont plus lents), plus téléchargement des poids et configuration	Non, seul Python stdlib côté local, la génération est dans le cloud
Coût de modification	Changer une phrase nécessite souvent une reprise de l’enregistrement et un réalignement	Modifier puis relancer, mais segmentation, concaténation et alignement à faire soi-même	Modifier uniquement la ligne concernée, réutiliser le cache out/lines/ pour les autres phrases, réassemblage automatique et mise à jour des sous-titres
Multi-personnages	Besoin de plusieurs doubleurs	Dépend du modèle, généralement segmentation manuelle et concaténation	Utiliser des balises [rôle] dans le script, une seule commande pour toute la piste audio multi-personnages
Horodatage des sous-titres	Nécessite une dictée et un calage supplémentaires	Généralement nécessite une reconnaissance vocale supplémentaire	Génère simultanément SRT et manifest.json avec horodatage phrase par phrase
Vidéos longues	Dictée et calage chronophages	Les modèles de reconnaissance locaux nécessitent un GPU ou beaucoup de temps	Téléchargement puis reconnaissance dans le cloud, vérification ultérieure avec ID de tâche en cas de timeout

Conclusion : si vous avez déjà un fichier final et souhaitez ajouter rapidement des sous-titres ou transcrire, utilisez recognize ; si vous partez d’un script à doubler, utilisez script avec sous-titres synchronisés pour gagner du temps.

Foire aux questions (FAQ)

Quels fichiers la génération de sous-titres supporte-t-elle ? Tous les fichiers audio ou vidéo locaux peuvent être utilisés comme source de reconnaissance. Les limites de taille et de durée sont basées sur subtitles.max_upload_mb et max_duration_minutes de capabilities.

Comment intégrer les sous-titres automatiques dans une vidéo ? Utilisez CapCut (« Importer des sous-titres ») ou ffmpeg : sous-titres logiciels -c:s mov_text, sous-titres incrustés -vf subtitles=sous-titres.srt.

La conversion audio en sous-titres peut-elle exporter au format SRT ? Oui, par défaut c’est SRT ; --subtitle-format txt donne du texte brut, json donne du texte structuré avec langage et segments temporels.

Quelle est la différence entre transcription audio en texte et génération de sous-titres ? Même reconnaissance, format de sortie différent : SRT avec horodatage pour ajouter des sous-titres ; TXT sans horodatage pour le texte.

La génération de sous-titres est-elle payante ? Oui, selon la durée du média et le tarif actuel par seconde, basé sur le retour en temps réel de capabilities ; le script inclut le tarif actuel lors de la soumission ; si le tarif change, la soumission est rejetée, pas de frais surprises.

La tâche de génération a expiré, dois-je retélécharger ? Non. Utilisez l’ID de tâche retourné avec miragea_audio.py wait ID_TÂCHE --output sous-titres.srt pour récupérer le résultat ; en cas d’interruption réseau, réessayez avec la même clé d’idempotence.

La génération de sous-titres reconnaît-elle l’anglais ou d’autres langues ? Le champ language est retourné dans le résultat ; les langues supportées dépendent des capacités réelles du serveur. Testez avec un court extrait.

Peut-on obtenir des sous-titres bilingues chinois-anglais ? Reconnaissez d’abord en SRT, puis demandez à l’agent de traduire chaque ligne tout en conservant l’horodatage, pour générer un second SRT ou les fusionner.

La reconnaissance IA de sous-titres nécessite-t-elle un GPU ? Non. La reconnaissance se fait dans le cloud ; côté local, seul Python 3.9+ stdlib est nécessaire.

Quels agents supportent ce skill ? Claude Code, Codex, OpenClaw, Cursor, WorkBuddy et tout agent capable d’exécuter des scripts Python.

Un problème ?

Symptôme	Action
missing_api_key / MIRAGEA_API_KEY is not set	Générez une clé puis export MIRAGEA_API_KEY=... ; ou ajoutez d’abord --dry-run
speakers without a voice	Ajoutez actor_id= ou ref= pour ce rôle
401	Vérifiez la clé ; ne l’écrivez pas dans les logs
403	Vérifiez les droits d’accès API du compte
400 / 413	Corrigez les paramètres : mode, étiquette, vitesse, nombre de caractères par phrase ; ou réduisez la taille/durée du fichier
409	La clé d’idempotence a été utilisée pour une entrée différente, ou le tarif des sous-titres a changé : reconfirmez avant de soumettre
429	Crédit insuffisant ou limite de débit : attendez ou ajoutez du crédit
Timeout / interruption réseau	La tâche peut encore être en cours : relancez exactement la même commande (la même clé d’idempotence récupérera la tâche d’origine), ou utilisez miragea_audio.py task / wait ID_TÂCHE pour interroger à nouveau. Ne changez pas de clé.
Erreur de format WAV lors de la concaténation	Chaque phrase est sauvegardée dans out/lines/ ; vous pouvez utiliser un logiciel de montage ou ffmpeg pour concaténer

Code de sortie du client officiel : 0 = succès de la requête (peut encore être en file d’attente sans --wait), 1 = échec de la tâche, 2 = erreur client ou interface.

Conformité

• Clonez uniquement votre propre voix ou celle de personnes ayant explicitement donné leur autorisation. N’imitez pas les célébrités, présentateurs, 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, WeChat Video, Xiaohongshu, Bilibili, etc.), déclarez ou étiquetez le contenu comme généré par IA lors de la publication.
• Avant de reconnaître l’audio/vidéo d’autrui (interview, réunion, cours), obtenez son consentement. Les sous-titres contenant des informations personnelles doivent être protégés quant à leur stockage et leur partage.
• scripts/miragea_audio.py est le client officiel, livré sans modification ; scripts/voiceover.py (couche d’assemblage de scripts) est original, sous licence MIT (voir LICENSE.txt). Les capacités de doublage et de sous-titres sont fournies par l’API ouverte Miragea.

Résumé en anglais

• AI subtitle generator (字幕生成) : téléchargez un fichier audio ou vidéo local avec la commande recognize du client officiel et sauvegardez un SRT horodaté, une transcription TXT ou un JSON (text, language, segments).
• Le client relit le tarif en direct et la limite de taille depuis capabilities avant la soumission ; les changements de tarif sont rejetés côté serveur. Reprenez les tâches longues avec wait TASK_ID.
• Pour les voix off scriptées, voiceover.py script produit des sous-titres alignés sur l’audio généré. Python 3.9+ stdlib, pas de GPU. Service : API Miragea (https://miragea.ai/v1).

Mots-clés : génération de sous-titres, ajout automatique de sous-titres aux vidéos, conversion audio en sous-titres, SRT, vidéo avec sous-titres, sous-titres automatiques, sous-titres IA, transcription audio en texte, vidéo en texte, parole en texte, générateur de sous-titres, sous-titres SRT, génération de sous-titres vidéo, subtitle generator, speech to text, auto captions