Changelog → Vídeo com Marca
Entrada: um changelog .md (temas + itens, como o resumo semanal HyperFrames).
Saída: um projeto HyperFrames limpo, com portão verde e sem erros, em
projects/active/weekly-changelog-<range>/. Renderize apenas quando solicitado.
Carregue primeiro, sem negociação: motion-doctrine (+ cut-the-curve,
oversized-cursor se um cursor aparecer, seam-craft) e captions-overlay.
Este skill fornece o pipeline específico para changelog; a doutrina fornece a
lei do movimento.
A diretriz principal: visualize, não liste
Cada tema é ilustrado por um mock animado da UI real ou de um análogo fiel representando a mudança na experiência — nunca marcadores de texto. Roteie cada tema/item através de references/visualization-registry.md ANTES de escrever o roteiro; o registro decide ui-recreate / ui-analog / terminal / checklist. O checklist de texto é o ÚLTIMO recurso, reservado para itens genuinamente não visuais (listas de correções de confiabilidade).
Pipeline
0 · Inicialize o projeto a partir dos ativos DESTE skill — sem negociação
Faça isso antes de escrever qualquer HTML de composição. Pular esta etapa sempre produz um vídeo que se parece com um projeto similar que você construiu antes, NÃO com a marca deste skill — essa é a maneira mais comum de este skill perder a identidade da marca. Os ativos, fontes e scaffold do skill são o skill; o prompt SKILL.md é um roteador.
mkdir -p project/assets/fonts
cp <SKILL_DIR>/assets/fonts/*.woff2 project/assets/fonts/
cp <SKILL_DIR>/assets/bgm.mp3 project/bgm.mp3
ffmpeg -y -stream_loop 15 -i <SKILL_DIR>/assets/bg-pattern.mp4 -t <TOTAL> \
-vf "scale=1080:1080,fps=30,eq=saturation=0.72,[email protected]:t=fill" \
-an -c:v libx264 -crf 20 -pix_fmt yuv420p project/assets/bg-pattern-<TOTAL>s.mp4
cp <SKILL_DIR>/examples/master-skeleton.html project/index.html
Depois leia references/build-spec.md do início ao fim (sem ler superficialmente) — ele define os tokens da marca (TT Norms Pro + ABC Solar Display + TT Norms Mono, creme #f5f6f4, verde racionado #5ef17c, cartões de vidro com bordas verdes, formato de pílula para kicker/sec-chip, trilho de legendas de 32px em top: 990) que cada cena herda do scaffold.
Só ENTÃO comece os passos 1-6 abaixo. Os passos 1-4 (analisar, rotear, roteiro, VO) planejam o que vai no scaffold; o passo 5 preenche os espaços reservados (<RANGE>, <TOTAL>, <CUT_N>, <DUR_N>, corpos das cenas) dentro do project/index.html já copiado — você NÃO reescreve o chrome, fontes, paleta ou layout do scaffold.
Se você se pegar usando cp em um index.html de vídeo anterior, ou escrevendo suas próprias declarações @font-face, ou projetando um fundo de shader WebGL em vez de usar o bg-pattern MP4 codificado acima: PARE. Delete o index.html atual e recomece no cp do scaffold master-skeleton. Reconstruir o conteúdo da cena no scaffold correto é mais barato do que adaptar a marca ao scaffold errado.
1 · Analisar + corte editorial
- Extrair: intervalo da semana, estatísticas principais (lançamentos, commits), temas, itens.
- Orçamento: 45-60s no total. Título ≤2s, encerramento ≤3,5s, 4 temas ≈ 9-12s cada.
- Por tema, mantenha UMA visualização principal + no máximo 3 itens falados. Todo o resto existe apenas como o ponteiro de "resumo completo" do encerramento. Cortar é a função: um changelog com 30 itens ainda rende ≤14 compassos falados.
- Ordene os temas por história: recurso principal → superfície do produto → desempenho → confiabilidade (o resumo geralmente já está assim).
2 · Roteamento da visualização
Para cada tema, escolha a superfície de references/visualization-registry.md e escreva uma linha: tema → superfície → as 2-4 ações sequenciais que o mock executa, cada uma ligada a uma frase do roteiro. Se nenhuma superfície do registro se encaixa e nenhum análogo fiel existe, é uma cena de checklist — não invente UI falsa para algo que não podemos representar honestamente.
3 · Roteiro de duas camadas (fala vs. exibição)
Escreva o roteiro como linhas de token conforme references/script-voice.md:
registro conversacional, cada termo técnico carregando uma forma spoken
fonética de references/lexicon.json enquanto display mantém a grafia padrão.
As legendas mostram display; o VO lê spoken. Qualquer termo que não esteja no léxico:
PARE e pergunte ao usuário como se pronuncia, depois adicione ao léxico.
Salve como script-tokens.json no projeto.
4 · VO — Annie (HeyGen, fixa)
# texto da camada falada apenas; words JSON = timestamps de verdade do texto FALADO
# Caminho nativo do repositório: o skill changelog-video é executado a partir da raiz do repositório hyperframes,
# então ele usa o auxiliar TTS hyperframes-media rastreado diretamente (sem etapa de instalação `npx hyperframes
# skills`). Se você copiou o skill para outro repositório, substitua pelo
# seu próprio caminho para o script heygen-tts.mjs do hyperframes-media.
node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt \
-o voiceover.mp3 --words vo-words.json \
--voice 330290724a1b470fb63153f34d4c0183 # Annie — realista (não substitua)
Requer CLI heygen ≥0.3.0 autenticado (heygen auth login --oauth).
Em seguida, alinhe os timestamps falados de volta aos tokens de exibição:
node <SKILL_DIR>/scripts/align-captions.mjs \
--tokens script-tokens.json --words vo-words.json --out captions.json
captions.json é a entrada do trilho de legendas (grafia de exibição, tempo de fala).
O alinhador imprime avisos MISMATCH — resolva cada um antes de construir
(geralmente uma grafia do léxico que o TTS renderiza como várias palavras). O áudio
é o relógio: todos os tempos dos compassos vêm de vo-words.json; uma regeração do VO reabre
cada costura.
Os timestamps das palavras são um portão rigoroso. Antes de prosseguir para o passo 5, verifique
se vo-words.json não está vazio e tem um array words: [...] com start/end
por palavra. Se estiver vazio (0 bytes) ou faltar o array — um modo de falha conhecido
quando o provedor TTS retorna áudio, mas sem payload de timestamp — NÃO PROSSIGA
sem eles. Fallback: alinhamento forçado do áudio produzido contra o roteiro
de exibição usando whisper local:
uvx --from openai-whisper whisper voiceover.mp3 \
--model base.en --language en --word_timestamps True \
--output_format json --output_dir .
# depois execute align-captions.mjs com --words voiceover.json (mesma forma)
O Whisper ouve mal as renderizações do TTS ("gee-sap" → "gsap", "heyjen" → "hey Jen",
etc.) — as legendas ainda usam a grafia DISPLAY de script-tokens.json;
whisper fornece apenas os timestamps. align-captions.mjs lida com a junção.
Este fallback é a diferença entre uma construção legendada e uma silenciosamente
não legendada.
5 · Construir
Siga references/build-spec.md exatamente: tokens da marca + fontes (empacotadas em
<SKILL_DIR>/assets/), a codificação do fundo animado, scaffold da cena,
chrome, trilho de legendas, um momento verde racionado por cena. Depois, a ordem
da doutrina: ledger.json (todas as costuras comuns cut-the-curve LEFT) → carimbo de costura →
compassos internos nas palavras do VO → verificação de portão de costura.
Legendas são obrigatórias. O master-skeleton envia um IIFE de trilho de legendas
que lê um array LINES — deixar esse array vazio é um bug enviado, não uma
escolha de estilo. Preencha-o a partir de captions.json antes de prosseguir para o passo 6:
// cole no lugar de "const LINES = /* … */ []" no IIFE do trilho de legendas:
const LINES = /* conteúdo de captions.json */ [
{ id: 0, end: 2.74, w: [["Esta", 0.0], ["semana,", 0.30], …] },
…
];
Se align-captions.mjs foi pulado ou LINES estiver [], a verificação de quadro no
passo 6 falhará — não ignore removendo #cap-line do
scaffold.
6 · Portões (tudo verde antes de apresentar)
bun run --cwd packages/cli hyperframes check(ou o CLIhyperframesinstalado do skillskills/hyperframes-cli/local ao repositório) — 0 erros (contraste: texto escuro ≥ 0,66 alpha). NÃO usenpx hyperframes@latest; o CLI rastreado local ao repositório é a fonte de verdade para o contrato de composição que este skill produz.seam-gate.mjs verify— 0 falhas.- Reinicie o servidor de visualização (ele armazena em cache o pacote), verifique 3-4 compassos
via
__player.seekna página de composição bruta. - NÃO renderize a menos que o usuário peça. Após uma renderização solicitada, verifique
quadros do MP4 (
ffmpeg -ss <t> … -frames:v 1): legendas presentes, vídeo de fundo não preto, sem quadros pequenos/congelados. - Portão de presença de legendas — falha grave. Amostre 3-4 quadros distribuídos
pela janela de fala do VO (por exemplo,
t=3,t=15,t=30,t=42para um VO de 48s) e confirme que o trilho de legendas emtop: 990renderiza texto visível em cada um. Se algum quadro em um intervalo de fala estiver sem legendas, a construção envia vídeo não legendado — trate como um portão vermelho e verifique novamente a população deLINESdo passo 5. É exatamente isso que deu errado na construção da v4 de 13 a 20 de julho.
Layout do projeto
projects/active/weekly-changelog-<range>/
├── index.html # mestre de documento único (cenas como slides, costuras carimbadas)
├── ledger.json # ledger vetorial (entrada do carimbo de costura)
├── script-tokens.json # roteiro de duas camadas (fonte de verdade para VO + legendas)
├── vo-spoken.txt # gerado: camada falada, uma linha
├── voiceover.mp3 + vo-words.json + captions.json
├── bgm.mp3 # cópia de <SKILL_DIR>/assets/bgm.mp3 (a faixa principal) a menos que o usuário forneça uma
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4
Anti-padrões
| Não | Em vez disso |
|---|---|
| Slides com marcadores para mudanças de UI | Simule a superfície representando a mudança |
| UI falsa para itens não representáveis | Cena de checklist honesta |
| "JSON"/"CLI" simples no texto do TTS | Formas faladas do léxico; exibição permanece padrão |
| Grafias fonéticas nas legendas | Legendas sempre renderizam a camada de exibição |
| Adivinhar a pronúncia de um termo desconhecido | Pergunte, depois aumente o léxico |
| Falar cada item do changelog | ≤3 por tema; o link do resumo carrega o resto |
| Destaques verdes em todo lugar | Um momento verde por cena (#5ef17c) |
| Começar de um index.html de vídeo anterior | Passo 0 — copie examples/master-skeleton.html deste skill para project/index.html, sempre |
@font-face / shader WebGL / BGM personalizado | Passo 0 — copie os assets/ deste skill literalmente; os ativos do skill SÃO a marca |
| Entregue sem invalidação do CloudFront | Execute aws cloudfront create-invalidation na distribuição E2BSLVSZ7FG3U0 para o caminho exato após qualquer substituição no S3 — o CDN armazena o arquivo antigo |
Enviar com o array LINES vazio no scaffold | Passo 4 deve produzir um captions.json preenchido; passo 5 deve colá-lo no IIFE; passo 6, portão 5 deve confirmar legendas nos quadros renderizados. Um LINES vazio = envio sem legendas = refazer a execução |
Sem vo-words.json → pular legendas e enviar | Recurso ao alinhamento forçado com whisper no áudio produzido; legendas são obrigatórias |