Changelog → Vídeo com Marca
Entrada: um changelog .md (temas + itens, como o digest semanal do HyperFrames).
Saída: um projeto HyperFrames limpo e verificado em
projects/active/weekly-changelog-<range>/. Renderize somente quando solicitado.
Carregue primeiro, não negociável: motion-doctrine (+ cut-the-curve,
oversized-cursor se um cursor aparecer, seam-craft) e captions-overlay.
Esta skill fornece o pipeline específico do changelog; a doutrina fornece a
lei do movimento.
A diretriz principal: visualize, não liste
Cada tema é ilustrado por um mock animado da interface real ou um
análogo fiel que representa a mudança na experiência — nunca bullets de texto.
Encaminhe cada tema/item através de references/visualization-registry.md ANTES
de escrever o roteiro; o registro decide ui-recreate / ui-analog / terminal / checklist.
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 assets DESTA skill — não negociável
Faça isso antes de escrever qualquer HTML de composição. Pular isso sempre produz um vídeo que se parece com um projeto similar que você construiu antes, NÃO com a marca desta skill — esse é o erro mais comum que faz com que esta skill saia da marca. Os assets, fontes e scaffold da skill são a 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
Em seguida, leia references/build-spec.md de ponta a ponta (não 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 verde-tintadas, formato de pílula 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, narração) planejam o que vai no scaffold; o passo 5 preenche placeholders (<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 um vídeo anterior, ou escrevendo suas próprias declarações @font-face, ou projetando um shader WebGL de fundo em vez de usar o bg-pattern MP4 codificado acima: PARE. Exclua 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 retrofitting da marca no scaffold errado.
1 · Análise + corte editorial
- Extraia: 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 "digest completo" no encerramento. Cortar é a tarefa: um changelog com 30 itens ainda rende ≤14 beats falados.
- Ordene os temas pela história: funcionalidade principal → superfície do produto → desempenho → confiabilidade (o digest geralmente já segue essa ordem).
2 · Roteamento de 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 sequenciadas que o mock realiza, cada uma ligada a uma frase do roteiro. Se nenhuma superfície do registro se encaixar e nenhum análogo fiel existir, é uma cena de checklist — não invente uma interface falsa para algo que não podemos representar honestamente.
3 · Roteiro de duas camadas (falado vs. exibido)
Escreva o roteiro como linhas de token por references/script-voice.md:
registro conversacional, cada termo técnico carregando uma forma fonética spoken
de references/lexicon.json enquanto display mantém a grafia padrão.
As legendas mostram display; a narração 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 · Narração — Annie (HeyGen, fixa)
# apenas texto da camada falada; palavras JSON = timestamps verdadeiros do texto FALADO
# Caminho nativo do repositório: a skill changelog-video é executada a partir da raiz do repositório hyperframes,
# então ela usa o helper TTS hyperframes-media rastreado diretamente (sem `npx hyperframes
# skills install`). Se você copiou a skill para outro repositório, substitua pelo
# seu próprio caminho para o heygen-tts.mjs do hyperframes-media / media-use.
node skills/hyperframes-media/scripts/heygen-tts.mjs ./vo-spoken.txt \
-o voiceover.mp3 --words vo-words.json \
--voice 330290724a1b470fb63153f34d4c0183 # Annie — natural (não substitua)
Requer heygen CLI ≥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 falado).
O alinhador imprime avisos MISMATCH — resolva cada um antes de construir
(geralmente uma grafia de léxico que o TTS renderiza como múltiplas palavras). O áudio
é o relógio: todos os tempos dos beats vêm de vo-words.json; uma regeneração da narração reabre cada costura.
Os timings de palavras são um gate rígido. Antes de passar 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 faltando o array — um modo de falha conhecido
quando o provedor TTS retorna áudio mas sem payload de timestamp — NÃO PROSSIGA sem eles.
Alternativa: alinhe à força o á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)
Whisper interpreta mal renderizações 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.
Essa alternativa é a diferença entre uma construção legendada e uma
silenciosamente sem legendas.
5 · Construção
Siga references/build-spec.md exatamente: tokens da marca + fontes (incluídas em
<SKILL_DIR>/assets/), a codificação do fundo animado, scaffold da cena,
chrome, trilho de legendas, um momento de verde racionado por cena. Em seguida, a ordem
da doutrina: ledger.json (todas as costuras comuns cut-the-curve LEFT) → seam-stamp
→ beats internos nas palavras da narração → verificação seam-gate.
Legendas não são opcionais. O master-skeleton inclui uma IIFE do trilho de legendas
que lê um array LINES — deixar esse array vazio é um bug enviado, não uma
escolha de estilo. Popule-o a partir de captions.json antes de prosseguir para o passo 6:
// cole no lugar de "const LINES = /* … */ []" na IIFE do trilho de legendas:
const LINES = /* conteúdo de captions.json */ [
{ id: 0, end: 2.74, w: [["This", 0.0], ["week,", 0.30], …] },
…
];
Se align-captions.mjs foi pulado ou LINES é [], a verificação de quadro no
passo 6 falhará — não a esconda removendo #cap-line do scaffold.
6 · Gates (tudo verde antes de apresentar)
node packages/cli/bin/hyperframes.mjs check --caption-zone "x0=0;y0=.90;x1=1;y1=1;severity=error;seek=.02,.06,.10,.14,.18,.22,.26,.30,.34,.38,.42,.46,.50,.54,.58,.62,.66,.70,.74,.78,.82,.86,.90,.94,.98"(ou a CLIhyperframesinstalada da skillskills/hyperframes-cli/local do repositório) — 0 erros (contraste: texto escuro ≥ .66 alpha; conteúdo da cena permanece acima do trilho de legendas). NÃO usenpx hyperframes@latest; a CLI local rastreada do repositório é a fonte de verdade para o contrato de composição que esta skill produz.seam-gate.mjs verify— 0 falhas.- Reinicie o servidor de pré-visualização (ele armazena em cache o bundle), verifique 3-4 beats
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. - Gate de presença de legendas — falha rígida. Amostre 3-4 quadros espalhados
pela janela de fala da narração (ex:
t=3,t=15,t=30,t=42para uma narração de 48s) e confirme que o trilho de legendas emtop: 990renderiza texto visível em cada um. Se qualquer quadro em um intervalo de fala estiver sem legendas, a construção envia sem legendas — trate como um gate vermelho e re-verifique a população deLINESdo passo 5. Foi exatamente isso que deu errado na construção v4 de 13 a 20 de julho.
Layout do projeto
projects/active/weekly-changelog-<range>/
├── index.html # documento mestre único (cenas como slides, costuras carimbadas)
├── ledger.json # vetor ledger (entrada do seam-stamp)
├── script-tokens.json # roteiro de duas camadas (fonte de verdade para narração + 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 trilha da casa) a menos que o usuário forneça uma
└── assets/fonts/ + assets/bg-pattern-<dur>s.mp4
Anti-padrões
| Não faça | Em vez disso |
|---|---|
| Slides com bullets para mudanças de interface | Mock da superfície representando a mudança |
| Interface falsa para itens não representáveis | Cena de checklist honesta |
| "JSON"/"CLI" simples no texto 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 digest carrega o resto |
| Acentos verdes em todos os lugares | Um momento verde por cena (#5ef17c) |
| Começar a partir do index.html de um vídeo anterior | Passo 0 — copie examples/master-skeleton.html desta skill para project/index.html, sempre |
@font-face feito à mão / shader WebGL / BGM personalizado | Passo 0 — copie os assets/ desta skill literalmente; os assets da 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 S3 — o CDN armazena o arquivo antigo em cache caso contrário |
Enviado com o array LINES vazio no scaffold | O passo 4 deve produzir um captions.json populado; o passo 5 deve colá-lo na IIFE; o gate 5 do passo 6 deve confirmar legendas nos quadros renderizados. Um LINES vazio = envio sem legendas = refaça a execução |
Sem vo-words.json → pule legendas e envie mesmo assim | Recorra ao alinhamento forçado do whisper no áudio produzido; legendas não são opcionais |