Communitygithub.com

avatar-studio

Transformez un portrait illustré (dessin animé ou personnage) et un script en une vidéo MP4 de ce personnage parlant, le tout réalisé localement sur votre machine.

Qu'est-ce que avatar-studio ?

Avatar-Studio est un pipeline local de création de vidéos animées à partir d'un portrait illustré et d'un script. Il construit ou réutilise une tête 3D parlante, génère la voix avec Kokoro, synchronise les mouvements (clignement des yeux, hochements, balancement de la tête, ouverture de la bouche) à partir de l'audio réel, et rend chaque image de manière déterministe dans un navigateur headless Chrome. Les vidéos produites incluent des sous-titres incrustés, un label indiquant la génération par ordinateur, et des options de mise en page (paysage, portrait, carré) avec un panneau latéral de points clés, un titre, un carton de nom, et une carte de fin. Destiné aux créateurs de contenu, développeurs ou marketeurs, il permet de produire un présentateur animé, un mascotte expliquant un concept, ou un clip de personnage lisant un script, sans aucune donnée quittant la machine. Il s'utilise en ligne de commande via `avatar` dans un dossier de projet, avec des étapes de vérification, création de tête, édition du script, génération audio, prévisualisation sous forme de planche d'images, et rendu final MP4. Le système impose des règles strictes : interdiction d'utiliser des visages réels sans consentement, pas d'usurpation d'identité, étiquetage obligatoire de la nature générée par ordinateur, et vérification des affirmations factuelles du script.

Compatible avec✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/VinVirtual/avatar-studio/tree/HEAD

Demander à votre IA préférée

Ouvre une nouvelle conversation avec cette compétence d'agent déjà préchargée.

Documentation

Que fait avatar-studio ?

Pipeline : tête (tête parlante : portrait vers head.glb + head.json) → audio (voix Kokoro, temps des mots, volume sonore de chaque image) → plan (bouche d'après le volume, clignements et balancement aléatoires déterminés par une graine, hochements sur les mots accentués, regards vers le panneau latéral, mise en page dans le temps) → rendu (chaque image est une fonction pure de t, rendue dans un navigateur headless Chrome, transmise à ffmpeg) → MP4 + sous-titres + copie web.

Dossier de la compétence : ~/.claude/skills/avatar-studio/ (écrit $A ci-dessous). Chaque commande est $A/avatar <commande> <projet>. $A/avatar help les liste. Il nécessite la compétence talking-head installée (par défaut ~/.claude/skills/talking-head ; définissez TALKING_HEAD_DIR pour utiliser un autre dossier).

$A/avatar                  la ligne de commande (check, new, lint, head, audio, sheet, stills, video, build, test)
$A/engine/gen_audio.py     voix, temps des mots, volume par image (exécuté par "avatar audio")
$A/engine/lib/             modules purs testés unitairement : enveloppe (bouche), mouvement, mise en page, plan, lint, sous-titres
$A/engine/page/frame.js    dessine une image : arrière-plan, tête (visionneuse de talking-head), titre, panneau, sous-titres, étiquette
$A/references/script.md    tous les champs du script
$A/examples/juno/          un exemple complet (Juno, un personnage fictif de talking-head)

Avant toute chose : les règles concernant les visages et les paroles

Elles ne sont pas optionnelles. Dites-les à l'utilisateur lorsqu'elles s'appliquent.

  1. De qui est ce visage ? Si le portrait représente ou est tiré d'une personne réelle, cette personne doit avoir accepté cette utilisation. Demandez à l'utilisateur. S'il ne peut pas confirmer le consentement, arrêtez-vous. Ne créez jamais une vidéo d'une personnalité publique, d'un collègue, d'un ex, d'un enfant, ou de quiconque pour qui l'utilisateur ne peut pas parler. Dans le script, définissez "character": { "likeness": "real-person-with-consent", "consent": true } seulement après confirmation de l'utilisateur ; sinon "likeness": "original" (un personnage inventé) ou "licensed".
  2. N'usurpez jamais l'identité de quelqu'un. Le personnage ne doit pas prétendre être une personne réelle, et le script ne doit pas mettre de mots dans la bouche d'une personne réelle ni présenter des lignes comme des déclarations réelles, citations, approbations ou excuses de quelqu'un. Si l'utilisateur le demande, refusez cette partie et proposez un personnage original ou un cadrage clairement fictif.
  3. Étiquetez-le. Chaque image porte une étiquette à l'écran (par défaut "Personnage généré par ordinateur" ; lint refuse une étiquette vide) et la carte de fin indique que le personnage et la voix sont générés par ordinateur. Dites à l'utilisateur de conserver une mention similaire partout où il publie la vidéo (légende, description, texte de la page) et de respecter les règles de la plateforme concernant les médias synthétiques.
  4. Listez les affirmations. Avant le rendu, listez chaque affirmation factuelle du script (chiffres, capacités du produit, prix, dates, comparaisons, déclarations médicales/juridiques/financières) et demandez à l'utilisateur de confirmer chacune. Le personnage la dit d'une voix assurée ; c'est l'utilisateur qui en répond.
  5. Rien ne quitte la machine sauf avec l'accord de l'utilisateur : avatar head --source space téléverse le portrait vers un espace public Hugging Face et nécessite --yes après que l'utilisateur a accepté (le SKILL.md de talking-head explique les limites de licence). La voix, les images et la vidéo sont toutes produites localement.

Flux de travail

  1. Vérification : $A/avatar check. Il indique comment corriger ce qui manque (talking-head, three.js, Kokoro, ffmpeg, Playwright, un navigateur avec WebGL).
  2. Démarrage : $A/avatar new <dossier> --portrait image.png (une tête sera construite) ou --head <dossier contenant head.glb et head.json> (réutiliser une tête existante, par exemple $A/exemples/juno/head).
  3. Tête (uniquement avec un portrait) : $A/avatar head <dossier>. Exécute talking-head (new, mark --auto, shape --source inflate, build, preview) dans <dossier>/build/head et copie le résultat dans <dossier>/head/. Si le portrait a changé depuis la création des marques, il s'arrête : relancez avec --force (nouvelles marques automatiques) ou --marks FICHIER. Un seul processus Blender à la fois ; cela prend une minute ou deux. Ensuite, Lisez <dossier>/build/head/out/preview.png et jugez-la comme indiqué dans le SKILL.md de talking-head (yeux couverts lors du clignement, bouche ouverte sur la ligne des lèvres). Corrigez les marques avec mark --page de talking-head, ou passez --marks FICHIER, et relancez avatar head.
  4. Script : éditez <dossier>/script.json (champs dans references/script.md). Limitez les lignes à une ou deux phrases. Les points font 2 à 6 mots et sont accrochés à un mot prononcé dans la même ligne ("at": "mot"). Marquez un mot accentué par phrase comme *ceci* pour un hochement de tête. Ensuite $A/avatar lint <dossier> jusqu'à ce qu'il n'y ait plus d'erreurs (sheet, stills, video et build exécutent lint eux-mêmes et refusent le rendu en cas d'erreur : pas de character.likeness, une personne réelle sans consent: true, une étiquette vide ou trop longue, un dossier de tête en dehors du projet). Appliquez la règle 4 (listez les affirmations) maintenant.
  5. Voix : $A/avatar audio <dossier>. Relancez-la après avoir modifié quoi que ce soit qui affecte la voix ou le timing (lignes, voix, vitesse, langue, prononciation, fps, lead, gap, tail, pause, ajout ou modification d'un titre ou d'une carte de fin) ; les commandes de rendu refusent une voix obsolète et le signalent. Elle imprime le début et la durée de chaque ligne, et indique si les temps des mots ont été mesurés à partir du modèle ("à partir des durées de phonèmes du modèle") ou estimés ; avec des temps estimés, les commandes de rendu avertissent que les points et les sous-titres peuvent être légèrement décalés. Visez 20 à 60 secondes.
  6. Aperçu : $A/avatar sheet <dossier>, puis Lisez stills/<nom>-sheet.png (une image par temps fort : titre, chaque ligne à la bouche la plus ouverte, chaque point, un clignement, la carte de fin). Toutes les lignes layout: qu'il imprime sont du texte qui n'a pas tenu : raccourcissez-le. Vérifiez : pas de texte sur le visage, sous-titres lisibles et pas sur la bouche, texte du panneau à l'intérieur de ses lignes, étiquette visible, rien coupé au bord de l'image. Pour plus de détails, utilisez $A/avatar stills <dossier> 4.2 11 et lisez ces PNG. Ne dites jamais que ça a l'air correct sans l'avoir vu.
  7. Rendu : $A/avatar video <dossier> --web (ou avatar build <dossier> pour lint + audio + sheet + video + web + aperçu en boucle). Il imprime une ligne sync mesurée à partir du fichier final : la corrélation r entre la bouche dessinée et l'énergie sonore décodée à partir du MP4, et le meilleur décalage en images. Attendez-vous à un r supérieur à 0.75 et un décalage de 0 ou -1 (la bouche devance d'une image intentionnellement). Signalez ces nombres ; vous ne pouvez pas entendre l'audio.
  8. Autres formats : --format vertical ou --format square sur sheet, stills, video et build. Les fichiers reçoivent -<format> dans leur nom. Revoyez la planche pour chaque format.
  9. Dites à l'utilisateur où se trouvent les fichiers (out/<nom>.mp4, .vtt, .srt, out/web/), les nombres de synchronisation, les limites ci-dessous, et les règles 3 et 4.

À quoi s'attendre, honnêtement

  • La bouche suit le volume sonore, pas les phonèmes : elle s'ouvre sur les sons forts et se ferme dans les pauses. Bon pour les dessins animés, pas pour la lecture labiale.
  • Seules les têtes de face illustrées fonctionnent bien (les limites de talking-head s'appliquent : profil gonflé avec la forme hors ligne, côtés plats au-delà d'environ 35 degrés). Les rotations de tête sont donc limitées.
  • Une seule voix par vidéo en pratique (une ligne peut définir sa propre voice, mais il n'y a qu'un seul personnage à l'écran).
  • Le rendu utilise WebGL logiciel : environ 4 à 5 images par seconde avec 2 pages, donc une vidéo paysage de 30 secondes prend environ 3 minutes.

Règles

  • Au maximum 2 pages de navigateur (--workers 1|2) et un seul processus Blender à la fois.
  • Ne committez pas les dossiers build/, stills/ ou out/ d'un projet sauf si l'utilisateur souhaite conserver les rendus.
  • Après avoir modifié quoi que ce soit dans engine/lib/, exécutez $A/avatar test.

Skills associés