digital-human-video

Geração de Vídeo com Avatar Digital

O que esta skill faz

Insira três elementos — um roteiro, uma foto de perfil e uma amostra de voz — e produza um vídeo curto vertical onde você aparece falando: Clone sua voz para ler o roteiro, use Seedance 2.0-mini para sincronizar os lábios da pessoa na foto com o áudio, adicione BGM gerado pelo Suno, queime legendas estilizadas com destaque de palavras-chave e avanço estilo karaokê, e por fim monte tudo com ffmpeg. Todo o processo utiliza apenas APIs públicas documentadas, e qualquer agente que rode Python e ffmpeg pode executar esta skill, sem dependência de cliente específico.

Cada parâmetro e cada armadilha de todo o pipeline foram validados em projetos reais (consulte references/), não é uma solução teórica.

Entradas necessárias (obter do usuário antes de começar)

1. Roteiro: Salve como script.md na raiz do projeto, uma frase por linha, no formato "1. Fala" "2. Fala". As frases são a unidade de geração por segmento; se uma frase for muito longa (mais de 15 segundos), divida em duas.
2. Foto de perfil: Imagem em assets/, de preferência vertical 9:16 (ex.: 1152×2048). A qualidade da foto determina diretamente a qualidade do vídeo final: rosto frontal, iluminação uniforme, sem óculos escuros ou máscara. Se o usuário não tiver uma foto adequada, gere uma com GPT Image 2 (consulte references/api-reference.md) e peça confirmação antes de prosseguir para a etapa de vídeo.
3. Amostra de voz: Arquivo em assets/ com 15–30 segundos de voz limpa (sem música de fundo, sem reverberação), para clonagem no Fish Audio.
4. Duas chaves de API: Uma do Fish Audio e outra do APIMART. Use variáveis de ambiente para fornecê-las. Proibido escrever em qualquer arquivo ou aparecer em eco de comando. Os scripts leem de variáveis de ambiente; se faltar chave, exibem aviso e saem, sem persistência.

Custos e contas

Componente	Modo	Custo (R$)	Fonte do modelo	Observações	Link de convite
Pessoa	GPT image 2	0,10	API APIMART	Apenas se não houver foto	https://apimart.ai/register?aff=QVui
Vídeo	Seedance 2.0-mini	10,00	API APIMART	720x1280, cobrado por segundo	https://apimart.ai/register?aff=QVui
BGM	Suno	0,35	API APIMART	Modo instrumental, duas faixas por vez
Clonagem de voz	s2.1-pro-free	0	API Fish Audio	Camada gratuita, voice_id reutilizável permanentemente	https://fish.audio/?aff=X7QT3YAX3N4Q4
Legendas	whisperx small	0	Local	Ambiente configurado uma vez

Estimativa real: Seedance 2.0-mini 720p custa cerca de US$ 0,039/segundo; um vídeo de 30 segundos custa aproximadamente R$ 12,00. A clonagem do Fish Audio exige que a conta tenha saldo (saldo 0/0 retorna 403); o TSS na camada gratuita não é cobrado. Suno custa US$ 0,05 por faixa. O custo real de um vídeo completo é de aproximadamente R$ 10–13.

Processo em cinco etapas

Cada etapa possui um gate: se não for atendido, não avança para a próxima. O estado é salvo em output/state.json, permitindo pausa e retomada.

Etapa A — Voz (Fish Audio)

1. python scripts/avatar_voice.py clone: Envia a amostra de voz para criar um modelo de clonagem privado e obtém o voice_id.
2. python scripts/avatar_voice.py tts: Sintetiza cada frase do script.md em arquivos WAV.
3. python scripts/avatar_voice.py fixwav: Corrige o cabeçalho dos arquivos WAV de stream (o cabeçalho retornado pelo Fish declara tamanho maior que o real; sem correção, alguns decodificadores truncam o áudio).
4. python scripts/avatar_voice.py qc: Verifica duração, volume médio e clipe de cada frase.

Gate: Todas as frases devem ter volume ≥ -30dBFS e sem clipe. A duração estimada é apenas referência, não meta — é proibido fazer compressão de tempo para ajustar duração (veja regras rígidas). O usuário deve ouvir e confirmar que o timbre está parecido com o original para prosseguir.

Etapa B — Vídeo (Seedance 2.0-mini)

1. python scripts/avatar_video.py upload-image: Envia a foto para APIMART e obtém uma URL pública.
2. python scripts/avatar_video.py host-audio: Hospeda cada WAV via tmpfiles.org e extrai o link direto real /dl/ (APIMART não possui endpoint para upload de áudio; links diretos expiram em 60 minutos, então envie imediatamente).
3. python scripts/avatar_video.py submit: Envia cada frase, com parâmetro chave generate_audio=False (vídeo mudo, lábios sincronizados por áudio externo — este é o interruptor da rota de avatar digital). A duração é arredondada para cima com base na duração do áudio; se o custo estimado de um único segmento ultrapassar US$ 1, interrompe automaticamente.
4. python scripts/avatar_video.py poll + download: Faz polling e baixa.

Gate: Verifique quadro a quadro se a pessoa não se deforma nem troca de rosto; os lábios devem abrir e fechar. Se o áudio for alterado, esta etapa deve ser refeita — o vídeo antigo foi sincronizado com o áudio antigo; trocar a trilha de áudio não garante sincronia.

Etapa C — BGM (Suno)

1. Leia o roteiro e crie um resumo musical (estilo/emoção/BPM/curva de energia/itens a evitar); veja o paradigma em references/prompts.md.
2. python scripts/avatar_bgm.py generate: Modo instrumental, gera duas faixas candidatas.
3. python scripts/avatar_bgm.py mix: Corta, fade in/out, reduz o volume para cerca de -16dB abaixo da voz, aplica sidechain compression e mistura no vídeo final.
4. O usuário ouve e escolhe uma. Gosto musical é subjetivo; a automação vai até "gerar candidatos aceitáveis", a escolha fica com a pessoa.

Etapa D — Legendas (ASS estilo rico, local e gratuito)

Não depende de serviços online; usa ASS/libass para implementar legendas com qualidade próxima a softwares de edição profissionais. Seis capacidades do avatar_caption.py (cada uma verificada pixel a pixel em quadros reais, não apenas descrição teórica):

Capacidade	Como configurar	Descrição
Agrupamento de Cue	Escreva `
Destaque de palavras-chave	spec.keywords	Ex.: AI → ciano, 5000人 → dourado, acerta palavras inteiras em chinês e ocidentais
Avanço karaokê letra por letra	spec.karaoke.enabled	Ilumina a letra sendo lida; as já lidas não voltam
Texto duplo	spec.dual_text	Diz "dez reais" e exibe "R$ 10", separando fala da escrita
Mudança de estilo por janela de tempo	spec.emphasis	Especifica 3–6 segundos com fonte maior ou cor diferente para frases de destaque
Duas trilhas (chinês + inglês) com animação de layout	spec.points	Trilha principal em chinês + trilha de pontos-chave em inglês, com \fad fade in, \t zoom

python scripts/avatar_caption.py spec    # Gera o template output/caption-spec.json
python scripts/avatar_caption.py all     # Gera ASS + queima em digital-human-captioned.mp4

Prioridade da fonte do texto da legenda: --srt especificado > output/digital-human.srt do whisperx > duração de voice/qc.json + texto original do script.md. Quando há texto original do roteiro, use-o primeiro (adicione --prefer-script), pois é mais preciso que transcrição ASR e não requer whisperx.

Duas convenções obrigatórias do libass (já enfrentadas, veja references/pitfalls.md): A cor não lida do karaokê é SecondaryColour; a cor lida muda para PrimaryColour e permanece; a unidade de \k é centissegundos e a soma total deve ser igual à duração daquele Cue; usar percentuais fará o karaokê terminar em um segundo.

Se o usuário for usar ferramentas como CapCut para legendas, esta etapa pode ser pulada, mas deve ser explicado na entrega.

Etapa E — Montagem e controle de qualidade

Corte os quatro segmentos de vídeo para alinhar com a duração do áudio, redimensione para 1080×1920, 30 fps, use a trilha de áudio da Etapa A (descarte a trilha de áudio original do vídeo), monte com ffmpeg. O template do comando de montagem está em references/prompts.md. Controle de qualidade: duração total igual à soma dos segmentos, forma de onda sem desvio em relação à voz, sem clipe, decodificação completa.

Regras rígidas (cada uma vem de lições reais)

1. Proibido usar atempo ou qualquer pós-processamento para esticar áudio e ajustar duração. Esticar reduz drasticamente a velocidade da fala e torna a audição arrastada. Para ajustar a velocidade, use o parâmetro nativo proposody.speed do Fish TTS para regravar (ex.: s3=0,85, s4=0,9) ou aceite a duração natural.
2. Chaves de API apenas na memória do processo. Fornecidas por variáveis de ambiente; o script as limpa no atexit. Qualquer string que pareça chave na saída deve ser substituída por placeholder. Nenhum arquivo do projeto, relatório ou log pode conter chaves.
3. Pare após duas falhas consecutivas na mesma operação, escreva um relatório explicando o motivo, sem tentativas infinitas. HTTP 401 para imediatamente (problema de chave). Interrompa se o custo estimado de um único segmento de vídeo ultrapassar US$ 1.
4. Duração estimada é referência, não meta. O padrão de qualidade para o executor não pode ser "do tipo que completa números".
5. A percepção do usuário tem prioridade sobre estatísticas automáticas. Mesmo que duração, volume e clipe estejam OK, se o usuário disser que algo está errado a partir do 10º segundo, está errado — investigue a partir desse ponto.
6. O que não passar na aceitação manual não pode ser chamado de produto final. Na entrega, liste claramente quais itens foram verificados e quais não foram.

Guia rápido de armadilhas do ambiente

No Windows, há quatro problemas confirmados ao executar este pipeline; leia references/pitfalls.md antes de começar: Requisições Python devem ter trust_env=False para evitar conectar no proxy errado; sandbox e sistema de arquivos real são duas visualizações diferentes; links diretos do tmpfiles exigem a página de visualização para extrair; cabeçalho WAV de stream do Fish precisa ser corrigido. Cada problema tem causa raiz e solução.

Uso dos scripts

export APIMART_API_KEY=... FISH_API_KEY=...   # Ou deixe o script pedir na execução
python scripts/avatar_voice.py all     # Etapa A completa
python scripts/avatar_video.py all     # Etapa B completa
python scripts/avatar_bgm.py all       # Etapa C
python scripts/avatar_caption.py all   # Etapa D (não precisa de chave)

Script	Etapa	Precisa de chave?	Função
avatar_voice.py	A	Fish Audio	Clonagem de voz, TTS por frase, correção de cabeçalho WAV, controle de qualidade
avatar_video.py	B	APIMART	Upload de imagem, hospedagem de áudio, envio de vídeo com sincronização labial, polling e download
avatar_bgm.py	C	APIMART (generate sim, mix não)	Geração de candidatos BGM Suno, mixagem com sidechain compression
avatar_caption.py	D	Não	Geração e queima de legendas com estilo rico
avatar_compose.py	E	Não	Montagem, redimensionamento, transcrição, verificação final

Os scripts leem script.md e assets/ do diretório atual, produzem saída em output/ e salvam estado em output/state.json. Se interrompidos, execute o mesmo comando novamente para retomar. Cada script suporta --help para ver subcomandos.

Limites de segurança (compromisso ao distribuir para outros)

• Os scripts se conectam apenas a quatro endpoints documentados: api.fish.audio, api.apimart.ai, tmpfiles.org, e ffmpeg/whisperx local. Não há telemetria, atualização automática ou estatísticas anônimas.
• Não leem ou escrevem em nenhum caminho fora do diretório do projeto.
• Chaves de API existem apenas na memória do processo e são limpas ao sair; todo texto persistido passa por filtro de padrões de chave.
• O pacote completo pode ser auditado: SKILL.md + references/ + scripts/; sem binários ou etapas de instalação executáveis.