lilei0311/skill-digital-human-video

Vídeo de Humano Digital · Skill do Agente

Objetivo

Receber um tópico ou um roteiro pronto e produzir um vídeo vertical de apresentação digital humana com IA: Script -> MiniMax TTS -> HeyGen Avatar Lip Sync -> FFmpeg (legendas, título, identificação de IA, picture-in-picture/BGM opcionais) -> MP4 + Texto de Publicação. Na primeira execução, apenas criar o ID do Avatar digital pessoal (Look ID) e clonar a voz (Voice ID); em execuções futuras, reutilizar esses IDs sem recriação. Oferecer um preview de 15 segundos com custo via HeyGen; por padrão, o usuário precisa visualizar o preview antes da versão completa. Somente com aprovação explícita do usuário para aprovação automática é que as duas etapas (preview + completo) são executadas em sequência.

Instalação e Verificação

• Coloque a skill em ~/.codex/skills/digital-human-video ou ~/.claude/skills/digital-human-video, garantindo que SKILL.md esteja na raiz da pasta.
• Python 3.10+, pip install -r requirements.txt, sistema com ffmpeg/ffprobe instalados (incluindo libass e codec H.264), fonte chinesa disponível para melhores resultados.
• Copie .env.example para .env, configure as chaves de forma local e segura; não peça ao usuário para colar chaves de API, fotos ou áudio no chat. Nunca inclua .env no Git.
• Primeiro execute: python scripts/dhv.py doctor, depois python scripts/dhv.py run --topic '...' --out ./outputs/example --dry-run.

Fluxo de Operação (em ordem)

1. Confirmar permissões e materiais. Aceitar apenas imagem/voz da própria pessoa ou de terceiros com autorização explícita; proibido replicar, personificar ou enganar sem consentimento. Verificar autorização separadamente para fotos/vídeos e áudio reais; vídeos sintetizados por IA devem manter identificação clara. Música e materiais de picture-in-picture devem ter licença.
2. Configuração única. Amostra de voz limpa de 30 a 60 segundos é ideal (MiniMax oficial aceita de 10 segundos a 5 minutos, ≤20MB, mp3/m4a/wav). Enviar vídeo/foto no HeyGen v3 para criar Avatar; foto deve ser frontal e de alta resolução; treinamento de vídeo pode exigir consentimento/verificação separada da pessoa real, que deve ser concluída, e o treinamento é assíncrono. Usar avatars para consultar Look IDs já treinados. Fornecer MINIMAX_VOICE_ID e HEYGEN_AVATAR_ID para o pipeline subsequente.
3. Escrever o roteiro primeiro. Se o usuário não fornecer o texto, o LLM escreve automaticamente: gancho de 3 segundos → 2 a 3 argumentos → resumo, explicitando público-alvo, plataforma e duração estimada. Não inventar dados não verificáveis. Decisões de edição/criatividade podem ser tratadas pelo Claude Opus 5.5 ou pelo Codex; o modelo é responsável pelo script e orquestração, o processamento real de mídia é executado pelo FFmpeg.
4. Preview. run --mode preview: prioriza reutilizar state.json e script.txt; sintetiza áudio e aciona o avatar digital para os primeiros ~55 caracteres (aproximadamente 15 segundos), gerando preview_final.mp4. A duração do preview pode não ser estritamente 15 segundos dependendo da velocidade da fala.
5. Plano de direção/edição. Se o agente atual for Claude Opus 5.5 ou puder delegar ao Opus, passar script.txt, tópico, marca e lista de materiais para ele, que deve gerar edit-plan.json, estritamente seguindo as chaves JSON em examples/edit-plan.json: headline, brand, key_points[{text,start,end}], pip_start/end, subtitle_font_size, music_volume (0~0.3). Os tempos de início/fim devem estar dentro da duração total do vídeo. --edit-plan faz o FFmpeg executar animações de cartões de texto, cronograma de picture-in-picture, estilo de legenda e volume BGM; sem Opus, o Codex/agente atual gera o mesmo JSON. O modelo apenas decide, não finge renderizar o vídeo.
6. Revisão e execução. O usuário verifica sincronia labial, nitidez, direitos autorais, legendas, realismo. Após aprovação: run --mode full --approve; com autorização e seleção explícita de revisão humana opcional: run --mode full --auto-approve para produção automática das duas etapas. Não publicar diretamente em redes sociais sem autorização.
7. Validação e entrega. Verificar duração de full_final.mp4, sincronia áudio-vídeo, legendas, sobreposição de título, volume da música, identificação de IA, e entregar publish.md. Antes de publicar externamente, exigir verificação factual e conformidade com regras AIGC da plataforma.

Uso via CLI (na raiz da Skill)

# Inicialização: própria imagem e áudio; permitir uso da flag consent apenas com autorização legal conhecida
python scripts/dhv.py avatar --file ./myself.mp4 --kind digital_twin --name 'Meu Apresentador' --i-own-the-likeness
python scripts/dhv.py avatars  # treinamento pode exigir espera e verificação oficial
python scripts/dhv.py clone --file ./myvoice.wav --voice-id MinhaVozMarca2026 --i-own-the-voice

# Preview: por padrão, MiniMax escreve o roteiro; também possível passar --script-file para bypass do LLM
python scripts/dhv.py run --topic 'Como a IA ajuda empresas a reduzir processos repetitivos' --out ./outputs/fluxo-ia --mode preview --edit-plan ./examples/edit-plan.json

# Executar versão completa somente após revisão do usuário
python scripts/dhv.py run --topic 'Como a IA ajuda empresas a reduzir processos repetitivos' --out ./outputs/fluxo-ia --mode full --approve

# Com consentimento explícito para modo não assistido, um comando gera preview + completo (as chamadas de API de vídeo são cobradas separadamente para cada etapa)
python scripts/dhv.py run --topic 'Entenda o humano digital em um minuto' --out ./outputs/demo --mode full --auto-approve

# Materiais opcionais
python scripts/dhv.py run --script-file ./script.txt --out ./outputs/manual --mode preview --music ./bgm-licenciado.mp3 --broll ./b-roll-proprio.mp4

Diretrizes de Execução do Agente

• Não descrever --dry-run ou testes de unidade como "execução real no HeyGen/MiniMax". Sem chaves de API pagas válidas e materiais autorizados, é possível apenas validar renderização offline/formato da requisição.
• Em caso de timeout de chamadas assíncronas de API, exibir o video_id do state.json e reutilizá-lo; não recriar diretamente para evitar cobrança duplicada.
• Clonagem de voz requer autenticação real no MiniMax; se voice_id não for usado para TTS oficial em 7 dias, pode expirar; priorizar tentar usar timbre existente, não clonar silenciosamente.
• Arquivos de legenda da plataforma podem não ser palavra por palavra precisos; se nenhum SRT utilizável for retornado, a ferramenta gera legendas estimadas e marca approximate no state.json. Necessário revisar antes da entrega; para precisão palavra por palavra, recomenda-se alinhamento adicional com ASR.
• Ao encontrar limites de tamanho de vídeo/política de treinamento/autenticação/cota, reportar o erro específico, não afirmar que foi concluído automaticamente.
• Não fazer login automático ou publicar diretamente no TikTok, Kuaishou, WeChat Video, Xiaohongshu, Bilibili etc., pois não há integração com APIs de autorização dessas plataformas; gerar apenas publish.md para revisão antes da publicação.
• Evitar enviar chaves de API, arquivos originais de gravação, timbres de voz semelhantes e ativos gerados originais para repositórios de código público.

Referências

• Detalhes das interfaces de API e configuração regional em references/api.md.
• Entrega e solução de problemas em README.md.