digital-human-video

Génération de vidéo avec avatar digital

Ce que fait cette compétence

Entrez trois éléments – un script, une photo d'identité, un échantillon vocal – et obtenez une vidéo verticale où la personne parle : Clonage de la voix pour lire le script, Seedance 2.0-mini anime la photo en synchronisation labiale, Suno génère une musique de fond, un sous-titrage enrichi avec surbrillance des mots-clés et effet karaoké est incrusté, et ffmpeg assemble le tout. Seules des API documentées sont utilisées, tout agent capable d'exécuter Python et ffmpeg peut appliquer cette compétence, sans dépendre d'un client spécifique.

Chaque paramètre et chaque piège de cette pipeline ont été validés sur des projets réels (voir references/), ce n'est pas une solution théorique.

Entrées obligatoires à demander à l'utilisateur avant de commencer

1. Script : enregistré sous script.md à la racine du projet, une phrase par ligne, format « 1. Texte » « 2. Texte ». Chaque phrase est une unité de génération de segment. Si une phrase est trop longue (plus de 15 secondes), la diviser en deux phrases.
2. Photo d'identité : sous assets/, format vertical 9:16 de préférence (ex. 1152×2048). La qualité de la photo détermine directement la qualité du résultat : visage de face, éclairage uniforme, pas de lunettes de soleil ni masque. Si l'utilisateur n'a pas de photo appropriée, utiliser GPT Image 2 pour en générer une (voir references/api-reference.md), et demander à l'utilisateur de confirmer son apparence avant de passer à l'étape vidéo.
3. Échantillon vocal : sous assets/, 15 à 30 secondes de voix propre (sans musique de fond, sans réverbération), pour le clonage Fish Audio.
4. Deux clés API : une pour Fish Audio et une pour APIMART. Transmises via des variables d'environnement, interdites dans tout fichier, interdites dans les retours de commandes. Les scripts lisent depuis les variables d'environnement, affichent une invite et quittent si une clé manque, et ne l'écrivent jamais sur le disque.

Coûts et comptes

Composant	Mode	Coût (yuan)	Source du modèle	Remarque	Lien d'invitation
Personne	GPT image 2	0.1	API APIMART	Uniquement si pas de photo	https://apimart.ai/register?aff=QVui
Vidéo	Seedance 2.0-mini	10	API APIMART	720x1280, facturation à la seconde	https://apimart.ai/register?aff=QVui
BGM	Suno	0.35	API APIMART	Mode instrumental, deux pistes à la fois
Clonage vocal	s2.1-pro-free	0	API Fish Audio	Niveau gratuit, voice_id réutilisable à vie	https://fish.audio/?aff=X7QT3YAX3N4Q4
Sous-titres	whisperx small	0	Local	Environnement à installer une fois

Estimation réelle : Seedance 2.0-mini 720p environ 0,039 $/seconde, une vidéo de 30 secondes coûte environ 12 yuans ; le clonage Fish Audio nécessite que le compte ait un solde (un quota de 0/0 renvoie une erreur 403), le TTS via le niveau gratuit est sans frais ; Suno coûte 0,05 $ par piste. Le coût réel d'une vidéo complète est d'environ 10 à 13 yuans.

Pipeline en cinq étapes

Chaque étape a une porte de contrôle : si les conditions ne sont pas remplies, on ne passe pas à l'étape suivante. L'état est stocké dans output/state.json, les scripts peuvent reprendre après interruption.

Étape A – Voix (Fish Audio)

1. python scripts/avatar_voice.py clone : télécharge l'échantillon vocal pour créer un modèle de clonage privé, récupère le voice_id.
2. python scripts/avatar_voice.py tts : synthétise le script phrase par phrase en WAV.
3. python scripts/avatar_voice.py fixwav : corrige l'en-tête du fichier WAV en flux (l'en-tête renvoyé par Fish déclare une longueur supérieure à la réalité, certains décodeurs tronqueraient l'audio sans cette correction).
4. python scripts/avatar_voice.py qc : vérifie phrase par phrase la durée, le volume moyen, l'écrêtage.

Porte de contrôle : toutes les phrases ont un volume non inférieur à -30 dBFS, sans écrêtage. La durée estimée n'est qu'une référence, pas un objectif impératif – modifier la vitesse pour atteindre une durée cible est strictement interdit (voir règles absolues). L'utilisateur écoute et confirme que le timbre ressemble bien au sien, pour valider l'étape.

Étape B – Vidéo (Seedance 2.0-mini)

1. python scripts/avatar_video.py upload-image : télécharge la photo sur APIMART pour obtenir une URL publique.
2. python scripts/avatar_video.py host-audio : héberge chaque fichier WAV via tmpfiles.org, extrait le lien direct /dl/ (APIMART n'a pas de point de terminaison pour le téléchargement audio ; les liens directs expirent après 60 minutes, soumettre immédiatement après le téléchargement).
3. python scripts/avatar_video.py submit : soumet phrase par phrase, paramètre clé generate_audio=False (vidéo muette, synchronisation labiale pilotée par l'audio externe – c'est le commutateur pour la voie avatar digital). duration arrondie à l'entier supérieur en fonction de la durée audio, si le coût estimé d'un segment dépasse 1 $, la fusion est automatique.
4. python scripts/avatar_video.py poll + download : interrogation et téléchargement.

Porte de contrôle : vérification image par image que le personnage ne se déforme pas, ne change pas de visage ; la bouche s'ouvre et se ferme. Si l'audio change, il faut refaire cette étape – l'ancienne vidéo a été synchronisée sur l'ancien audio, remplacer la piste audio ne garantit pas la synchronisation.

Étape C – BGM (Suno)

1. Lire le script et rédiger un brief musical (style/émotion/BPM/courbe d'énergie/éléments à éviter), paradigme dans references/prompts.md.
2. python scripts/avatar_bgm.py generate : génère deux candidats en mode instrumental pur.
3. python scripts/avatar_bgm.py mix : rogne, fondu, compresse sous la voix à environ -16 dB, sidechain compression, mixe dans le résultat final.
4. L'utilisateur écoute et choisit une piste. Le goût musical est subjectif, l'automatisation s'arrête à « proposer des candidats acceptables », le choix revient à l'humain.

Étape D – Sous-titres (ASS enrichi, local et gratuit)

Aucun service en ligne requis, utilise ASS/libass pour un rendu proche des logiciels de montage professionnels. Les six capacités de avatar_caption.py (chacune vérifiée pixel par pixel, pas une simple spécification théorique) :

Capacité	Configuration	Description
Regroupement de Cue	écrire `
Surbrillance des mots-clés	spec.keywords	Exemple : IA en cyan, 5000 personnes en or, correspondance exacte inter-langues
Effet karaoké progressif	spec.karaoke.enabled	Le mot lu s'allume, ceux déjà lus ne s'éteignent pas
Dual Text	spec.dual_text	Dire « dix yuans » afficher « 10¥ », séparation oral/écrit
Changement de style temporel	spec.emphasis	Spécifier 3–6 secondes avec une police plus grande ou une autre couleur, pour les phrases importantes
Double piste chinois/anglais + animation	spec.points	Piste principale chinoise + piste secondaire anglaise, avec \fad fondu, \t zoom pop

python scripts/avatar_caption.py spec    # Génère le template output/caption-spec.json
python scripts/avatar_caption.py all     # Génère ASS + incruste dans digital-human-captioned.mp4

Priorité des sources de texte de sous-titres : --srt spécifié > whisperx output/digital-human.srt > durée de voice/qc.json + texte original de script.md. Utiliser le texte original du script quand il est disponible (avec --prefer-script), il est plus précis que la transcription ASR et ne nécessite pas d'installer whisperx.

Deux conventions libass essentielles (déjà rencontrées, voir references/pitfalls.md) : la couleur non lue du karaoké est SecondaryColour, la couleur lue est PrimaryColour et reste stable ; l'unité de \k est la centiseconde et la somme doit être exactement égale à la durée de ce Cue, les pourcentages feraient défiler le karaoké en une seconde.

Si l'utilisateur utilise un outil comme CapCut pour les sous-titres, cette étape peut être ignorée, mais il faut le mentionner clairement dans les instructions de livraison.

Étape E – Composition et contrôle qualité

Les quatre segments vidéo sont rognés pour correspondre à la durée audio, redimensionnés en 1080×1920, 30 ips, la piste audio utilise le TTS de l'étape A (la piste audio vidéo native est supprimée), composés avec ffmpeg. Le modèle de commande de composition est dans references/prompts.md. Contrôle qualité : la durée totale correspond à la somme des segments, la forme d'onde est alignée avec la voix, pas d'écrêtage, décodage complet.

Règles absolues (chacune est le fruit d'erreurs réelles)

1. Interdiction d'utiliser atempo ou tout post-traitement pour étirer l'audio afin d'atteindre une durée cible. L'étirement ralentit considérablement le débit, rendant l'écoute traînante. Pour ajuster le débit, utiliser le paramètre natif prosody.speed de Fish TTS pour ré-enregistrer (ex. s3=0.85, s4=0.9), ou accepter la durée naturelle.
2. Les clés API sont uniquement stockées en mémoire de processus. Transmises via variables d'environnement, le script les efface avec atexit, toute chaîne ressemblant à une clé dans la sortie est remplacée par un espace réservé. Aucune clé ne doit apparaître dans les fichiers de projet, rapports ou logs.
3. Si la même opération échoue deux fois de suite, elle s'arrête, un rapport est écrit avec la raison, pas de tentatives infinies. Une erreur HTTP 401 arrête immédiatement (problème de clé). Si le coût estimé d'un segment vidéo dépasse 1 $, fusion.
4. La durée estimée est une référence, pas un objectif. Les critères de contrôle qualité pour l'exécutant ne peuvent pas être de « faire du remplissage ».
5. L'écoute utilisateur prime sur les statistiques automatiques. Durée, volume, écrêtage validés ne garantissent pas une écoute satisfaisante ; si l'utilisateur dit que ça sonne faux à partir de la 10e seconde, c'est qu'il y a un problème, à investiguer à partir de ce point temporel.
6. Ce qui n'a pas été validé manuellement ne peut pas être qualifié de produit fini. Lors de la livraison, lister clairement les éléments vérifiés et ceux qui ne le sont pas.

Pièges d'environnement

Quatre pièges avérés sur Windows, à lire avant de commencer dans references/pitfalls.md : Les requêtes Python doivent utiliser trust_env=False sinon elles se connectent au mauvais proxy, le bac à sable et le système de fichiers réel sont deux vues différentes, les liens directs de tmpfiles nécessitent d'analyser la page de visualisation, l'en-tête WAV en flux de Fish doit être corrigé. Chaque piège a sa cause racine et sa solution.

Utilisation des scripts

export APIMART_API_KEY=... FISH_API_KEY=...   # ou laisser le script demander à l'invite
python scripts/avatar_voice.py all     # Étape A complète
python scripts/avatar_video.py all     # Étape B complète
python scripts/avatar_bgm.py all       # Étape C
python scripts/avatar_caption.py all   # Étape D (pas besoin de clé)

Script	Étape	Nécessite une clé	Rôle
avatar_voice.py	A	Fish Audio	Clonage vocal, TTS phrase par phrase, correction d'en-tête WAV, contrôle qualité
avatar_video.py	B	APIMART	Téléchargement d'image, hébergement audio, soumission de vidéo labiale, interrogation et téléchargement
avatar_bgm.py	C	APIMART (generate oui, mix non)	Génération de BGM Suno, sidechain compression et mixage
avatar_caption.py	D	Non	Génération et incrustation de sous-titres enrichis
avatar_compose.py	E	Non	Assemblage, redimensionnement, transcription, contrôle final

Les scripts lisent script.md et assets/ depuis le répertoire courant, produisent dans output/, l'état est stocké dans output/state.json, en cas d'interruption, relancer la même commande reprend là où ça s'est arrêté. Chaque script supporte --help pour voir les sous-commandes.

Périmètre de sécurité (engagement envers les distributeurs)

• Les scripts se connectent uniquement à quatre points de terminaison documentés : api.fish.audio, api.apimart.ai, tmpfiles.org, et le ffmpeg/whisperx local. Aucune télémétrie, mise à jour automatique ou statistique anonyme.
• Ils ne lisent ni n'écrivent aucun chemin en dehors du répertoire du projet.
• Les clés API restent en mémoire de processus, effacées à la sortie ; tout texte écrit sur le disque est filtré contre les formes de clé.
• L'ensemble du package est entièrement auditable : SKILL.md + references/ + scripts/, aucun binaire, aucune étape d'installation exécutable.