minhhoasqtt-prog/hmhshare-mkt-bien-tap-vlog-hyperframes

Edição de vlog com HyperFrames

Transforme um vídeo de conversa bruto (com algumas cenas de preenchimento) em um vídeo 16:9 enxuto, objetivo, com belas cores e texto.

Filosofia / Fontes

• Walter Murch, Regra dos Seis (In the Blink of an Eye): emoção 51% > história 23% > ritmo 10% > direção do olhar > 2D > 3D. Selecione os trechos pela emoção e fluxo da história primeiro; corrija erros de imagem depois.
• Casey Neistat: introdução → contexto → conteúdo → conclusão; jump cuts intencionais; uso abundante de cenas de preenchimento.
• Talking-head: a fala é a espinha dorsal (L-cut), cenas de preenchimento sobrepostas, punch-in para ocultar jump cuts.
• Já testado: vlog gravado no carro 11:22 → 5:22, 23 trechos, 29 blocos de texto (plano de exemplo em references/vi-du-plan.json).

Quando usar / NÃO usar

• Usar: vídeo longo de uma pessoa falando (vlog, compartilhamento, livestream gravado, gravado no carro) que precisa ser encurtado + preenchido + textuado, quadro horizontal 16:9.
• Não usar: short vertical 9:16 estilo TikTok com legendas que passam palavra por palavra; vídeo de avatar IA / dublagem; apenas legendas mantendo o vídeo original (use /embedded-captions do HyperFrames).

Pré-requisitos

Siga HUONG-DAN-CAI-DAT.md, depois execute node <skill>/scripts/kiem-tra-may.mjs — deve mostrar tudo ✓.

• ffmpeg/ffprobe, Node ≥ 18, npx hyperframes (testado com 0.8.168–0.8.169).
• whisper-cli (whisper.cpp) + modelo ~/.whisper-models/ggml-large-v3-turbo.bin (pode ser alterado com as variáveis WHISPER_BIN, WHISPER_MODEL).
• Mac usa VideoToolbox para cortes rápidos (~2x o tempo real com 2.7K HEVC 10-bit); Windows/Linux convertem para libx264 (mais lento).
• Espaço em disco livre ≥ 0,6 GB por minuto de vídeo final + 3 GB. O primeiro render baixa chrome-headless-shell (~150 MB).
• Fonte Be Vietnam Pro disponível em assets/fonts/ (licença SIL OFL, sem necessidade de internet).

Fluxo de execução

S=<diretoria do skill>/scripts (normalmente .claude/skills/hmhshare-mkt-bien-tap-vlog-hyperframes/scripts) W=<diretoria de trabalho>, ex. ~/vlog-lam-viec/<slug>. Mantenha a mídia pesada aqui, NÃO em pastas sincronizadas na nuvem (Google Drive, OneDrive, Dropbox…), pois será lento e propenso a erros.

Passo 1 — Preparação (máquina, ~1–3 minutos).

node $S/01-chuan-bi.mjs --work $W --main "<video principal>" --broll "<trám1>,<trám2>,..."

Resultado: probe.json, contact.jpg, loi-thoai.txt (marcas de cada palavra), main_clean.wav, proxy das cenas de preenchimento hfproj/media/bNN*.mp4 + broll.json. Se executar novamente, ignora as partes já feitas (use --force para refazer).

Passo 2 — Edição por IA (leia atentamente references/chon-doan-bien-tap.md). Veja contact.jpg (posição do orador → tam_zoom, local para colocar texto), leia todo loi-thoai.txt, defina público + mensagem (pergunte ao usuário se não souber), depois escreva $W/plan.json seção doan conforme references/plan-json.md. Teste rápido a duração total:

node $S/02-cat-doan.mjs --work $W --main "<video principal>" --chi-tinh   # apenas imprime ban-cat.txt, não corta

→ Ponto de revisão (humano): se o usuário quiser revisar antes, envie a tabela ban-cat.txt e pare. Padrão: continue, inclua a tabela de fluxo no relatório final.

Passo 3 — Corte + filtragem de áudio + verificação de emendas (máquina).

node $S/02-cat-doan.mjs --work $W --main "<video principal>"

Gera hfproj/media/main_cut.mp4/.wav, segs.json, kiem-tra-noi.json. Se houver trechos com aviso de palavras cortadas, confira cut-words.json (Whisper às vezes erra); se for erro real, adicione lui_dau/them_cuoi e execute novamente.

Passo 4 — Escrever textos + criar composição (IA). Leia ban-cat.txt, escreva plan.json seção chu (seguindo doan + sau), canh_tram (padrão {"nhip":20}), depois:

node $S/03-dung-hyperframes.mjs --work $W
cd $W/hfproj && npx hyperframes check --json        # deve: lint 0 erros, layout 0, contraste tudo ok
npx hyperframes snapshot --at <marcos impressos pelo script>  # IA VEJA contact sheet: texto quebrado, cobrindo rosto, cor

Corrija plan/texto → execute 03 novamente até o quadro estar limpo (textos longos devem ser encurtados, não diminuir a fonte).

Passo 5 — Render + exportar (máquina, ~1,5x a duração do vídeo no Mac M1 Pro).

node $S/04-render-xuat.mjs --work $W --out "<pasta de destino>" --quality delivery

Verifique duração, áudio, LUFS, obtenha soat.jpg, copie o vídeo + du-an-hyperframes/ + plan/segs/transcrição para a pasta de destino. IA veja soat.jpg pela última vez.

Passo 6 — Relatório. Entregue ao usuário: caminho do vídeo, duração antes/depois, tabela de fluxo por marcos (trechos mantidos, ideias principais), o que foi removido, onde editar em plan.json para ajustes. Limpe o cache de render (veja Observações).

Referências

• scripts/lib.mjs: ffmpeg/whisper/busca de frases, seleção de codec por máquina.
• scripts/01-chuan-bi.mjs · 02-cat-doan.mjs · 03-dung-hyperframes.mjs · 04-render-xuat.mjs · kiem-tra-may.mjs.
• scripts/template.tpl: HTML + GSAP (9 tipos de texto, punch-in, fusão de cenas, Ken Burns).
• references/plan-json.md: formato do plan + tabela de tipos de texto · references/vi-du-plan.json: plan real com 23 trechos / 29 textos.
• references/chon-doan-bien-tap.md: regras de seleção de trechos, estrutura de fluxo, ritmo visual.
• Documentação HyperFrames: https://hyperframes.heygen.com (se a máquina tiver a skill hyperframes, hyperframes-cli, leia também).

Observações / armadilhas

• Marcas de texto do Whisper atrasam ~0,3–0,5s em relação ao áudio real: o script já recua o ponto de entrada em 0,3s; se ainda faltar, adicione lui_dau.
• Não crie proxy do vídeo original inteiro em 2.7K/4K (11 minutos levam ~40 min): corte apenas os trechos selecionados (passo 3).
• Não deixe um segundo arquivo .html na raiz de hfproj/: HyperFrames reporta multiple_root_compositions. O template fica em scripts/.
• Avisos de lint nested_structure_needs_subcomposition / timeline_track_too_dense são sugestões de organização, podem ser ignorados.
• Render salva cache de decodificação em pasta temporária ($TMPDIR/hyperframes-extract-cache-* no Mac/Linux, %TEMP% no Windows; ~2 GB para 5 min de vídeo): apague após o render.
• A fase "Checking browser" que dura alguns minutos na primeira vez é o download do navegador, não é travamento.
• Transcrição com muitos erros: o texto na tela deve estar ortograficamente correto, não copie a transcrição literal. Legendas completas ainda não estão implementadas nesta skill.
• Vídeos HDR/LOG: converta para SDR antes (passo 1 avisará); o corretor de cor em tempo real só lida com Rec.709.
• O cartão de memória da câmera deve estar conectado do passo 1 ao fim do passo 3 (passo 3 lê o arquivo original). Melhor copiar o vídeo para a máquina antes.
• Windows: caminhos com espaços devem sempre estar entre aspas.

Saída

<pasta de destino>/: <slug>.mp4, du-an-hyperframes/ (index.html + config, sem mídia), plan.json, segs.json, ban-cat.txt, loi-thoai.txt, kiem-tra-noi.json, broll.json, soat.jpg.