Changelog → Vídeo com Marca
Entrada: um changelog .md (temas + itens, como o digest semanal do HyperFrames).
Saída: um projeto HyperFrames limpo e sem erros em
projects/active/weekly-changelog-<range>/. Renderize apenas quando solicitado.
Carregue primeiro, sem exceção: 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 de movimento.
A diretriz principal: visualize, não liste
Cada tema é ilustrado por um mock animado da interface real ou um análogo fiel que encena 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. A lista 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 — sem exceção
Faça isso antes de escrever qualquer HTML de composição. Ignorar isso sempre produz um vídeo que se parece com um projeto similar que você construiu antes, NÃO com a marca desta skill — essa é a forma mais comum de esta skill sair 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 do começo ao fim (sem pular) — ele define os tokens da marca (TT Norms Pro + ABC Solar Display + TT Norms Mono, creme #f5f6f4, verde controlado #5ef17c, cartões de vidro com bordas verdes, formato de pílula kicker/seção, 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, roteirizar, narração) planejam o que vai no scaffold; o passo 5 preenche os 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 tentando cp de um index.html de vídeo anterior, ou escrevendo suas próprias declarações @font-face, ou projetando um fundo shader WebGL 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 adaptar a marca ao scaffold errado.
1 · Análise + corte editorial
- Extraia: intervalo da semana, estatísticas do título (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 herói + no máximo 3 itens falados. Todo o resto existe apenas como ponteiro para o "digest completo" no encerramento. Cortar é o trabalho: um changelog com 30 itens ainda produz ≤14 batidas faladas.
- Ordene os temas por história: recurso principal → superfície do produto → performance → confiabilidade (o digest geralmente já lê assim).
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 executa, cada uma vinculada a uma frase do roteiro. Se nenhuma superfície do registro se encaixar e não existir um análogo fiel, é uma cena de checklist — não invente uma 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 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 não
no léxico: PARE e pergunte ao usuário como se pronuncia, depois adicione-
o ao léxico. Salve como script-tokens.json no projeto.
4 · Narração — Annie (HeyGen, fixa)
# Texto da camada falada apenas; words 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 auxiliar TTS hyperframes-media rastreado diretamente (sem passo `npx hyperframes
# skills install`). Se você copiou a skill para outro repositório, substitua pelo
# seu próprio caminho para o script heygen-tts.mjs do media-use / 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 autenticada (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 múltiplas palavras). O áudio
é o relógio: todos os tempos das batidas vêm de vo-words.json; uma regeração da narração reabre
cada costura.
Os tempos das palavras são uma barreira rígida. 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. Alternativa: 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 .
# então execute align-captions.mjs com --words voiceover.json (mesma forma)
Whisper entende mal as 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 verde controlado por cena. Então a ordem
da doutrina: ledger.json (todas as costuras comuns cut-the-curve LEFT) → carimbo de costura →
batidas internas nas palavras da narração → verificação da barreira de costura.
Legendas não são opcionais. O master-skeleton inclui uma 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 = /* … */ []" 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 está [], a verificação de quadro no
passo 6 falhará — não tente esconder isso removendo #cap-line do
scaffold.
6 · Barreiras (todas verdes antes de apresentar)
bun run --cwd packages/cli hyperframes check(ou a CLIhyperframesinstalada a partir da skillskills/hyperframes-cli/local do repositório) — 0 erros (contraste: texto escuro ≥ .66 de alfa). NÃO usenpx hyperframes@latest; a CLI local rastreada do repositório é a fonte da 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 pacote), verifique 3-4 batidas
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 minúsculos/congelados. - Barreira de presença de legendas — falha rígida. Amostre 3-4 quadros distribuídos
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 é enviada sem legendas — trate como uma barreira vermelha e re-verifique a população deLINESdo passo 5. Isso é exatamente o que deu errado na construção 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 # vetor de ledger (entrada do carimbo de costura)
├── script-tokens.json # roteiro de duas camadas (fonte da 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 faixa padrão) 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 marcadores para mudanças de UI | Crie um mock da superfície encenando a mudança |
| UI 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 e depois aumente o léxico |
| Falar de cada item do changelog | ≤3 por tema; o link do digest carrega o resto |
| Destaques verdes em todos os lugares | Um momento verde por cena (#5ef17c) |
| Começar de um index.html de vídeo anterior | Passo 0 — copie examples/master-skeleton.html desta skill para project/index.html, sempre |
@font-face / shader WebGL / BGM personalizado feito à mão | Passo 0 — copie os assets/ desta skill na íntegra; 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 no S3 — o CDN armazena em cache o arquivo antigo caso contrário |
Enviar com o array LINES vazio no scaffold | O passo 4 deve produzir um captions.json preenchido; o passo 5 deve colar no IIFE; a barreira 6 do passo 6 deve confirmar legendas nos quadros renderizados. Um LINES vazio = envio sem legendas = refazer a execução |
Sem vo-words.json → pular legendas e enviar mesmo assim | Use o alinhamento forçado whisper no áudio produzido; legendas não são opcionais |