frankhzh-source/digital-human-video-pipeline

Pipeline de Produção de Vídeo com Avatar Digital Humano (Validação Completa Local ✅)

Testado em 21/22/09/2026: fluxo completo de 74,8s de narração → 15,6s de vídeo de teste (aparência A7 + dublagem clonada MiniMax + embalagem HyperFrames) com 0 falhas. Todos os scripts em D:\workbuddy\Claw\Claw, executados com D:/Anaconda3/envs/ai/python.exe -X utf8 (faster_whisper neste ambiente). Atualização em 29/09/2026: [0] Portão de Consistência de Texto — slogans/frases finais foram reescritas duas vezes (consulte a seção do portão), agora é etapa obrigatória com veto absoluto.

Visão Geral do Fluxo (Portão + Seis Etapas)

[0] Portão de Texto (obrigatório) → [1] Áudio Mestre → [2] Transcrição ASR + Tabela de Corte → [3] Dublagem Clonada MiniMax (Receita B2)
    → [4] HeyGen photo avatar + lipsync → [5] Camada de Sobreposição Transparente HyperFrames (ProRes4444)
    → [6] Composição ffmpeg (legendas/efeitos sonoros/BGM/loudness) → Vídeo Final + Capa

[0] Portão de Consistência de Texto (Obrigatório, Veto Absoluto, Antes de Qualquer Geração)

Contexto: Slogans/FRASES FINAIS foram reescritas duas vezes (28/09/2026: as quatro perguntas iniciais foram redirecionadas + slogan perdido, retrabalho de 24 créditos; 29/09/2026: "ocupar a fonte" no final foi alterado para "curso obrigatório"). Lição: confiar na memória/autodisciplina não é confiável — as regras são escritas na memória, a violação ocorre no meio da tarefa, quando as regras já não estão mais no contexto. A solução é substituir "autodisciplina" por "mecanismo": registro + verificação rígida via script + portão de aprovação manual.

Três Regras de Ferro:

1. Slogans/FRASES FINAIS/Trechos de Encerramento/Assinatura devem ser verificados caractere por caractere com o texto original — texto original = segmento ANCHOR do script TTS ou fonte de legendas do vídeo final. Proibido criar próprio texto, proibido "ajustes para narração oral";
2. Rascunho primeiro, depois mostre o original: após redigir qualquer novo parágrafo, cole o texto original contendo o slogan caractere por caractere para o usuário aprovar; só então permita a entrada em geração;
3. Antes de gerar conteúdo pago, passe pelo portão obrigatoriamente: antes de ações que consomem créditos (TTS/HeyGen etc.), a verificação do slogan deve ser APROVADA.

Operação (Kit Duplo):

• Registro: 文案规范_定稿.json (única fonte oficial; novas frases finais devem ser registradas após aprovação do usuário);
• Verificação: D:/Anaconda3/envs/ai/python.exe -X utf8 工具_口号校验.py <arquivo_alvo...>
  • Suporta .md/.txt/.json (leitura direta), .ass (remove tags para obter texto de legenda), .py (extrai literais de string, cobrindo constantes de texto TTS);
  • Normaliza pontuação/espaços automaticamente e faz correspondência de substring; alvos closed_targets são apenas sugeridos, não bloqueados;
  • exit 0 = APROVADO, pode continuar; exit 1 = REPROVADO, proibido entrar em geração paga; --self-test para autoverificação.
• Documentação detalhada do mecanismo: references/copy-slogan-gate.md (versão para publicação).

Pontos de Inserção do Portão (executar um a um a cada período):

Momento	Ação
Após rascunho, antes do TTS	工具_口号校验.py 工具_第XX期TTS.py → deve APROVAR
Antes de enviar para HeyGen	Verificar novamente (evitar desvios devido a alterações no meio do caminho)
Após montagem final, antes da publicação	工具_口号校验.py <sub.ass> <texto_publicacao.md> → APROVADO só então permite enviar para Feishu/publicar
Em caso de falha	Reinserir caractere por caractere do texto original; se for realmente uma nova frase final → aprovação do usuário → atualizar registro → reexecutar até APROVAR

[1] Requisitos do Áudio Mestre

• Finalização completa no final da frase (não usar versão cortada); loudness alvo -16 LUFS; gravação limpa de 30–90s pode servir como material de registro para clonagem.
• Para clonagem registrada, usar 音频_口播原声_092211_句末收尾_69秒.m4a (não usar a versão de 74,8s com meia frase).

[2] Transcrição ASR + Tabela de Corte

D:/Anaconda3/envs/ai/python.exe -X utf8 工具_播客ASR转写.py <áudio> --md 转写_xxx.md

• Saída com timestamps no nível de palavra (.asr_cache/*.json com cache, reexecução instantânea); com base na transcrição, cortar cerca de 5 segmentos, marcar como S1–S5 e pontos de informação;
• Segmento de teste selecione 18–30s: parágrafos com leitura mista chinês/inglês e pausas são os mais representativos.

[3] Clonagem de Voz MiniMax + Dublagem

Ferramenta: 工具_MiniMax声音克隆_通用.py (chave .secrets/minimax.key + minimax_group.txt, conexão direta com site nacional, não precisa de proxy).

• --check gratuito → --clone --yes clonagem (regra voice_id: ≥8 caracteres alfanuméricos, começando com letra, usar haifengv1) → --t2a dublagem;
• Receita de dublagem finalizada como "B2": speech-2.8-hd + speed:0.95, sem rótulo de emoção (aprovado pelo usuário: timbre aceitável, tom da B2 aceitável);
• Prioridade de ajuste para tom robótico: tornar texto mais coloquial > speed 0,95 > emotion=happy > clonagem com material mais longo;
• Referência de custo: HD 3,5 yuans/10 mil caracteres, uma frase < 1 centavo.

[4] Avatar Digital HeyGen

Pré-requisito: proxy deve estar ligado (verificar escuta em 127.0.0.1:7890 + teste de conectividade mcp.heygen.com).

• Ferramentas: 工具_播客测试片A7_准备_2026-09-21.py (grátis: verificação de crédito/schema/aparência/envio de áudio) → 工具_播客测试片A7_提交_2026-09-21.py (--yes portão);
• Aparência A7 + mecanismo avatar_v; saída em ~2 minutos, verificar após download;
• ⚠️ Custo real ~0,85 crédito/segundo (vídeo de 15,7s testado em 13 créditos, 559→546). Antes de enviar vídeo completo, pegue um segmento de 30s do meio para verificar o preço.

[5] Camada de Sobreposição Transparente HyperFrames (Animações de Cartão/Gráfico)

Projeto: _cards_hf/compositions/v2_testcard.html (para alterar texto, só mexer no texto + timestamps).

• Modo de acionamento: gsap.timeline({paused:true}) registrado em window.__timelines["main-video"] + elementos com data-start/data-duration;
• Renderização (cerca de 4,5–5 minutos de máquina, overlay_v2.mov de 172MB manter até versão final, não excluir no meio — excluir uma vez refaz render de 5 minutos):

export PATH="/d/ffmpeg:/c/Users/admin/.workbuddy/binaries/PortableGit/versions/1.2.0/usr/bin:$PATH"
cd _cards_hf && npx hyperframes render -c compositions/v2_testcard.html -f 25 --format mov \
  -o "../_v2/overlay_v2.mov"

• ⚠️ Quatro armadilhas (todas testadas e resolvidas):
  1. O elemento raiz deve ter data-composition-id="...", caso contrário HF_DE_COMPOSITION_ROOT_MISSING;
  2. Use data-width/data-height para dimensões (data-composition-width não é lido → saída em retrato 1080×1920);
  3. O PATH da máquina de renderização deve ter ffmpeg e ffprobe (D:\ffmpeg faltava ffprobe → npm i ffprobe-static --registry=https://registry.npmmirror.com resolve em um minuto; não baixe pacote de 114MB do gyan.dev — na China ~20KB/s e instável);
  4. Renderização sai em 1920×1080, na composição escalonar para 1072 para alinhar com o vídeo final.

[6] Composição Final ffmpeg

Ferramenta: 工具_测试片v2合成_2026-09-22.py (copiar a cada período, só alterar constantes SRC/OV/legendas/pontos no topo).

• Cadeia: zoompan punch-in (8,45/13,25s com 5% cada) → overlay ProRes4444 → legendas ASS (caminho ass= deve ser relativo com barras normais, barras invertidas são escapadas e engolidas) → pacote de três efeitos sonoros (adelay para alinhamento) → BGM de fundo (sidechaincompress para ducking da voz) → loudnorm -14 LUFS;
• Legendas: divisão de frases com timestamps no nível de palavra, palavras destacadas {\c&H6ABEE9&}palavra{\r} (BGR dourado); capa a partir do frame 13,8s.

BGM / Padrões de Efeitos Sonoros (Documentado: 整理_知识类视频BGM与音效范式_2026-09-22.md)

Narração de conhecimento = Padrão BGM B "Companhia de Informação": BGM é a luz da sala de aula, não a trilha sonora do palco.

1. Sem melodia (pluck/palhetada, não "cantar"); 2. Registro médio-alto a partir de C4 (legato longo em registro grave = drone de atmosfera = sensação de opressão, lição da v2.2); 3. Staccato com espaço; 4. BPM 88–104 alinhado com velocidade de fala; 5. Faixa de frequência evita voz 300Hz–3,4kHz; nível -28~-32 LUFS relativo à voz + sidechain ducking (threshold 0,028 / ratio 7 / attack 180ms / release 1000ms).

• Dois presets em make_bgm_pluck (padrão) / make_bgm_pad (A/B reserva), alterna com uma palavra BGM_STYLE; para mudar estilo, só alterar tabela de acordes.

Pacote de Três Efeitos Sonoros (receita fixa, só trocar pontos): whoosh de transição (lowpass ≤2400) → tick de feedback (1,2–1,6kHz, volume mínimo) → thump de ênfase (≤2 vezes por vídeo inteiro, pontos de exclamação); proporção de volume: ênfase 0,24 : transição 0,22 : feedback 0,165; em qualquer janela de 2s, ≤1 ponto.

Registro de Custos (Medido na Prática)

Item	Custo
ASR / ffmpeg / HyperFrames / Composição BGM	0
Clonagem MiniMax	9,9 yuans/timbre (cobrado apenas na primeira síntese); TTS ≈0,02 yuans/frase
Vídeo de Teste HeyGen	13 créditos / 15,7s; estimativa para 69s completo ~59 créditos, versão 2:44 ~140

Lista de Verificação (Verificar Item por Item Após a Saída do Vídeo)

0. Portão de slogan: 工具_口号校验.py <sub.ass> <texto_publicacao.md> APROVADO (frases finais caractere por caractere no lugar, conforme regras da seção [0]);
1. volumedetect: mean ≈ -17dB / max ≤ -2,5dB (sem clipping);
2. Amostrar 3 frames (nos momentos do cartão de gráfico / cartão de palavra-chave / cartão de conclusão): rosto e mãos sem sobreposição zero (zona segura: cartão esquerdo 56–546px, cartão direito 1150–1860px, título superior 84px, legendas inferiores 200px);
3. Três pontos de audição: energia nos primeiros 3s, voz proeminente, sensação de pausa no final.

Pendências (Resolver Antes da Versão Final)

• Aprovação do áudio mestre completo: versão de 69s com finalização de frase ou recorte completo de 2:44 (versão de 74,8s com meia frase proibida);
• Incrementos do vídeo completo: cartão de capítulo A7 ×5 segmentos, S4 frase por frase na tela, BGM expandido para loop de 4–8 compassos + final, cartão de atenção de 3s.