Communitygithub.com

avatar-studio

Transforme UM retrato ilustrado (um personagem cartoon ou desenhado) mais um roteiro em um MP4 finalizado desse personagem falando, feito inteiramente nesta máquina. Constrói ou reutiliza uma cabeça 3D falante, dubla o roteiro localmente com Kokoro, controla piscadas, balanço de cabeça, acenos e boca a partir do áudio real, renderiza quadros deterministicamente no Chrome headless, com legendas embutidas, rótulo de computador e opcionais título, tarja de nome, painel lateral de pontos que aparecem nas palavras faladas e cartão final. Paisagem, vertical ou quadrado.

O que é avatar-studio?

O avatar-studio é uma habilidade avançada para agentes de IA (como Claude Code) que cria vídeos de avatar falante a partir de uma única ilustração de personagem e um roteiro. Ele executa todo o pipeline localmente, sem depender de serviços externos, utilizando Kokoro para síntese de voz, Blender para modelagem 3D da cabeça e headless Chrome com WebGL para renderização determinística quadro a quadro. O sistema sincroniza os movimentos da boca com a intensidade do áudio (não fonemas), controla piscadas, balanço e acenos da cabeça, e gera legendas embutidas, painéis de pontos e cartão final. É ideal para criar apresentadores animados, mascotes explicativos ou clipes de personagens lendo roteiros para mídias sociais ou web. Importante: não deve ser usado com fotos de pessoas reais sem consentimento, nem para deepfakes ou impersonação. O pipeline inclui comandos para verificação de dependências, criação de projetos, edição de roteiros com lint, geração de áudio, visualização de storyboard e renderização final em MP4 com legendas VTT/SRT.

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

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que avatar-studio faz?

Pipeline: cabeça (cabeça falante: retrato para head.glb + head.json) → áudio (voz Kokoro, tempos das palavras medidas, volume de cada quadro) → plano (boca a partir do volume, piscadas e balanço semeados, acenos em palavras estressadas, olhares para o painel lateral, layout ao longo do tempo) → renderização (cada quadro é uma função pura de t, desenhado em Chrome headless, canalizado para ffmpeg) → MP4 + legendas + cópia web.

Pasta da habilidade: ~/.claude/skills/avatar-studio/ (escrito $A abaixo). Cada comando é $A/avatar <comando> <projeto>. $A/avatar help lista todos. Precisa da habilidade talking-head instalada (padrão ~/.claude/skills/talking-head; defina TALKING_HEAD_DIR para usar outra pasta).

$A/avatar                  a linha de comando (check, new, lint, head, audio, sheet, stills, video, build, test)
$A/engine/gen_audio.py     voz, tempos das palavras, volume por quadro (executado por "avatar audio")
$A/engine/lib/             módulos puros e testados: envelope (boca), movimento, layout, plano, lint, legendas
$A/engine/page/frame.js    desenha um quadro: fundo, cabeça (visualizador do talking-head), título, painel, legendas, rótulo
$A/references/script.md    todos os campos do roteiro
$A/examples/juno/          um exemplo finalizado (Juno, um personagem fictício do talking-head)

Antes de tudo: as regras sobre rostos e palavras

Estas não são opcionais. Diga-as ao usuário quando se aplicarem.

  1. De quem é o rosto? Se o retrato mostra ou é desenhado a partir de uma pessoa real, essa pessoa deve ter concordado com este uso. Pergunte ao usuário. Se eles não puderem confirmar o consentimento, pare. Nunca faça um vídeo de uma figura pública, um colega, um ex-parceiro, uma criança ou qualquer pessoa pela qual o usuário não possa falar. No roteiro, defina "character": { "likeness": "real-person-with-consent", "consent": true } somente após o usuário confirmar; caso contrário, "likeness": "original" (um personagem inventado) ou "licensed".
  2. Nunca se passar por outro. O personagem não deve fingir ser uma pessoa real, e o roteiro não deve colocar palavras na boca de uma pessoa real ou apresentar falas como declarações, citações, endossos ou pedidos de desculpas reais de alguém. Se o usuário pedir isso, recuse essa parte e ofereça um personagem original ou uma estrutura claramente fictícia.
  3. Rotule-o. Cada quadro carrega um rótulo na tela (padrão "Personagem gerado por computador"; o lint recusa um rótulo vazio) e o cartão final diz que o personagem e a voz são gerados por computador. Diga ao usuário para manter uma nota semelhante onde quer que publique o vídeo (legenda, descrição, texto da página) e para seguir as regras da plataforma para mídia sintética.
  4. Liste as afirmações. Antes de renderizar, liste cada afirmação factual que o roteiro faz (números, capacidades do produto, preços, datas, comparações, declarações de saúde/legais/financeiras) e peça ao usuário para confirmar cada uma. O personagem diz com uma voz confiante; o usuário é quem a respalda.
  5. Nada sai da máquina exceto com o sim do usuário: avatar head --source space envia o retrato para um Hugging Face Space público e precisa de --yes após o usuário concordar (o SKILL.md do talking-head explica os limites da licença). A voz, os quadros e o vídeo são feitos localmente.

Fluxo de trabalho

  1. Verificação: $A/avatar check. Ele diz como corrigir o que está faltando (talking-head, three.js, Kokoro, ffmpeg, Playwright, um navegador com WebGL).
  2. Início: $A/avatar new <dir> --portrait imagem.png (uma cabeça será construída) ou --head <pasta com head.glb e head.json> (reutilize uma, como $A/examples/juno/head).
  3. Cabeça (apenas com um retrato): $A/avatar head <dir>. Executa talking-head (new, mark --auto, shape --source inflate, build, preview) em <dir>/build/head e copia o resultado para <dir>/head/. Se o retrato mudou desde que suas marcas foram feitas, ele para: execute novamente com --force (novas marcas automáticas) ou --marks FILE. Um processo Blender por vez; leva um ou dois minutos. Em seguida, Leia <dir>/build/head/out/preview.png e avalie-o conforme o SKILL.md do talking-head diz (olhos cobertos ao piscar, boca abrindo na linha dos lábios). Corrija as marcas com mark --page do talking-head, ou passe --marks FILE, e execute avatar head novamente.
  4. Roteiro: edite <dir>/script.json (campos em references/script.md). Mantenha as linhas em uma ou duas frases. Pontos têm de 2 a 6 palavras e são ancorados a uma palavra dita na mesma linha ("at": "palavra"). Marque uma palavra estressada por sentença como *esta* para um aceno. Então execute $A/avatar lint <dir> até que não haja erros (sheet, stills, video e build executam lint por conta própria e se recusam a renderizar com erros: sem character.likeness, uma pessoa real sem consent: true, um rótulo vazio ou muito longo, uma pasta de cabeça fora do projeto). Faça a regra 4 (liste as afirmações) agora.
  5. Voz: $A/avatar audio <dir>. Execute novamente após mudar qualquer coisa que molde a voz ou o tempo (linhas, voz, velocidade, idioma, pronúncia, fps, lead, gap, tail, pausa, adicionar ou alterar um título ou cartão final); os comandos de renderização recusam uma voz desatualizada e avisam. Ele imprime o início e a duração de cada linha e se os tempos das palavras foram medidos a partir do modelo ("a partir das durações de fonemas do modelo") ou estimados; com tempos estimados, os comandos de renderização avisam que pontos e legendas podem ficar ligeiramente desalinhados. Mire em 20 a 60 segundos.
  6. Visualização: $A/avatar sheet <dir>, então Leia stills/<nome>-sheet.png (um quadro por batida: título, cada linha no momento de boca mais aberta, cada ponto, uma piscada, o cartão final). Quaisquer linhas layout: impressas são texto que não coube: encurte-o. Verifique: nenhum texto sobre o rosto, legendas legíveis e não sobre a boca, texto do painel dentro de suas linhas, o rótulo visível, nada cortado na borda do quadro. Para detalhes, use $A/avatar stills <dir> 4.2 11 e Leia esses PNGs. Nunca diga que parece certo sem visualizá-lo.
  7. Renderização: $A/avatar video <dir> --web (ou avatar build <dir> para lint + audio + sheet + video + web + pré-visualização em loop). Ele imprime uma linha de sincronia medida a partir do arquivo finalizado: a correlação r entre a boca desenhada e a energia sonora decodificada de volta do MP4, e o melhor atraso em quadros. Espere r acima de 0.75 e um atraso de 0 ou -1 (a boca adianta um quadro propositalmente). Relate esses números; você não pode ouvir o áudio.
  8. Outros formatos: --format vertical ou --format square em sheet, stills, video e build. Os arquivos recebem -<formato> em seus nomes. Veja a folha novamente para cada formato.
  9. Diga ao usuário onde estão os arquivos (out/<nome>.mp4, .vtt, .srt, out/web/), os números de sincronia, os limites abaixo e as regras 3 e 4.

O que esperar, honestamente

  • A boca segue o volume, não os fonemas: abre em sons altos e fecha em pausas. Bom para cartoons, não para leitura labial.
  • Apenas cabeças frontais ilustradas funcionam bem (os limites do talking-head se aplicam: perfil inchado com a forma offline, lados simples além de cerca de 35 graus). As viradas de cabeça são mantidas pequenas por esse motivo.
  • Uma voz por vídeo na prática (uma linha pode definir sua própria voice, mas há um personagem na tela).
  • A renderização é WebGL por software: cerca de 4 a 5 quadros por segundo com 2 páginas, então um vídeo paisagem de 30 segundos leva cerca de 3 minutos.

Regras

  • No máximo 2 páginas do navegador (--workers 1|2) e um processo Blender por vez.
  • Não envie as pastas build/, stills/ ou out/ de um projeto a menos que o usuário queira manter as renderizações.
  • Após alterar qualquer coisa em engine/lib/, execute $A/avatar test.

Habilidades Relacionadas