Módulo 4.1 — YouTube & Shorts | HyperFrames

🖥️ Vídeo 16:9 para YouTube

O formato padrão do YouTube é 1920 × 1080 px. Com HyperFrames, você escreve cenas em HTML + GSAP e renderiza o MP4 em alta qualidade — sem abrir editor de vídeo.

Conceito principal

O gerador build-index.mjs escreve um index.html com viewport fixo em 1920 × 1080. O HyperFrames usa Chrome headless para capturar cada frame e o FFmpeg monta o MP4. Sem flag, o output é sempre 16:9.

✓ FAZER em vídeos YouTube

✓ Usar --quality high no render final
✓ Manter narração ≈ 100s de fala (≈ 1:50 de vídeo)
✓ Incluir thumbnail de alta contraste na cena 1
✓ Gerar MP4 com codec H.264, 60fps fluído

✗ NÃO FAZER em vídeos YouTube

✗ Publicar render --quality draft (resolução baixa)
✗ Ultrapassar 15 min sem capítulos (queda de retenção)
✗ Usar fonte menor que 32px (ilegível em mobile)
✗ Omitir cena de CTA (perda de conversão)

Render 16:9 — comando exato

# Gera index.html 1920×1080, depois renderiza

node build-index.mjs &&

npx hyperframes render --quality high \

--output renders/meu-tutorial-16x9.mp4

Conceitos-chave

Viewport fixo

O index.html tem width/height hard-coded em 1920×1080 — o Chrome captura exatamente isso.

H.264 + FFmpeg

HyperFrames chama FFmpeg internamente. MP4 gerado é aceito pelo upload do YouTube sem re-encode.

Cenas GSAP

Cada sceneN() retorna HTML estático; anim() recebe o GSAP timeline e anima os elementos.

📱 Shorts/Reels/TikTok em 9:16

O mesmo projeto HTML vira um vídeo 1080 × 1920 px com o flag --vertical. O HyperFrames recompõe o layout e renderiza o frame alto — sem duplicar código.

📊 Dimensões e destinos

16:9 — Horizontal

Resolução: 1920 × 1080 px

Destino: YouTube, Vimeo, LinkedIn

Flag: node build-index.mjs (sem flag)

9:16 — Vertical

Resolução: 1080 × 1920 px

Destino: YouTube Shorts, Instagram Reels, TikTok

Flag: node build-index.mjs --vertical

💡

Layout adaptativo com CSS

No modo --vertical, o HyperFrames injeta a classe .vertical no <body>. Use seletores .vertical .sua-classe no CSS das cenas para reposicionar elementos — coluna em vez de linha, texto maior, margens menores.

✓ FAZER em Shorts/Reels

✓ Usar fontes ≥ 48px no modo vertical (safe zone menor)
✓ Manter CTA e legenda na metade inferior da tela
✓ Validar layout com npx hyperframes inspect --samples 16
✓ Limitar a ≤ 60 s para Shorts/Reels (≤ 180 s para TikTok)

✗ NÃO FAZER em Shorts/Reels

✗ Reutilizar layout 16:9 sem ajustes .vertical
✗ Colocar texto importante na faixa superior (coberta pela UI do app)
✗ Ignorar o lint antes do render — erros de layout aparecem ampliados
✗ Publicar sem legenda (maioria assiste sem som)

Conceitos-chave

Flag --vertical

Injeta classe e reescreve viewport para 1080×1920 sem alterar as funções de cena.

Safe zone

Reserve ~15% superior e inferior para UI dos apps — só conteúdo na faixa central.

Reels vs Shorts

O mesmo MP4 9:16 serve para Instagram Reels e YouTube Shorts — upload em ambos.

60 s limite

Shorts exige ≤ 60 s para aparecer na aba dedicada. Acima disso vira vídeo comum.

⏱️ Por que ~110s prende a retenção

100 segundos de fala equivalem a ~1:50 de vídeo. Esse intervalo é longo o suficiente para ensinar um conceito completo e curto o suficiente para manter atenção — o ponto ideal para Shorts e tutoriais YouTube.

Timeline de retenção típica

0 – 5 s

Hook — não feche

5 – 30 s

Contexto rápido

30 – 90 s

Conteúdo central

90 – 110 s

CTA — conversão

> 180 s

Queda acentuada

⚡

A narração é o metrônomo

Cada cena do SCRIPT.md tem ≈ 15–18 s de narração (medido com ffprobe). Com 6–7 cenas você chega exatamente em ~100 s de fala. Voz: pf_dora --speed 0.98 no Kokoro. Guarde as durações no array AUDIO[] do build-index.mjs.

📊 Equação duração × retenção

~100s

de fala (TTS pf_dora)

≈ 1:50

de vídeo renderizado

> 65%

retenção média esperada

Conceitos-chave

Hook nos 5s

A cena 1 determina se o viewer fica. Comece com a promessa ou o problema — nunca com intro de marca.

AUDIO[] real

Preencha com as durações exatas de ffprobe assets/audio/sN.wav — o HyperFrames sincroniza animação e áudio.

speed 0.98

Velocidade ligeiramente abaixo de 1.0 deixa a fala mais natural no PT-BR com a voz pf_dora.

💬 Legendas/captions sempre on

85 % dos vídeos em feeds são assistidos no mudo. Legendas queimadas (burned-in) no frame garantem acessibilidade e leitura mesmo sem som — e ainda reforçam a identidade visual dark premium.

Como funciona no HyperFrames

O array CAPTIONS[] em build-index.mjs define textos sincronizados com o áudio. O template injeta um <div class="caption"> fixo no rodapé de cada cena. O CSS padrão usa Inter 600, 36px, fundo rgba(0,0,0,0.55), padding 12px — legível em qualquer fundo.

Estilo de caption (house style)

/* caption queimada no frame */

.caption {

position: absolute;

bottom: 72px; /* acima da safe zone */

left: 50%; transform: translateX(-50%);

font-family: 'Inter', sans-serif;

font-weight: 600;

font-size: 36px;

color: #F0EBD8;

background: rgba(0,0,0,0.55);

border-radius: 8px;

padding: 10px 20px;

max-width: 80%; text-align: center;

}

⚠️

Caption não é legenda de arquivo

A caption do HyperFrames é burned-in — ela faz parte do frame do vídeo. Isso é intencional: garante que apareça em qualquer plataforma, mesmo quando o player está no mudo e sem suporte a SRT/VTT. Para SEO, adicione também uma legenda separada no upload do YouTube.

💡

Vertical: ajuste o font-size

No modo --vertical, use .vertical .caption { font-size: 52px; bottom: 160px; } — a resolução 1080×1920 é muito maior e a caption precisa escalar.

Conceitos-chave

CAPTIONS[]

Array de strings no build-index.mjs — cada item corresponde a uma cena e é injetado no frame.

Acessibilidade

Burned-in caption serve usuários surdos e quem está em ambiente sem áudio (ônibus, trabalho).

rgba translúcido

Fundo semi-transparente preserva o visual do frame enquanto garante contraste mínimo WCAG 2.1 AA.

🏁 CTA no fim

A última cena é o CTA — Call to Action. No padrão INEMA.CLUB, ela exibe "CONTINUA EM" + domínio em destaque + URL legível. Já vem pronta no template do HyperFrames como scene9().

Cena de CTA padrão INEMA.CLUB

A cena final mostra "CONTINUA EM" + INEMA.CLUB com glow âmbar, URL 🌐 inema.club e narração curta: "Isso é conteúdo do INEMA ponto CLUB. Acesse: inema ponto club.". Ela é a scene9() no template — não remova.

Prompt de exemplo — acionando o skill video-explicativo

# Cole no Claude Code (skill video-explicativo instalado)

Crie um vídeo explicativo sobre "como funciona o Kokoro TTS".

Gere 16:9 e 9:16. CTA para INEMA.CLUB.

Voz pf_dora, speed 0.98, PT-BR.

Paleta dark premium, accent âmbar #FFC300.

O skill segue o fluxo: SCRIPT.md → init → fetch-fonts → narração WAV → build-index.mjs → lint → render ×2.

Onde o CTA cai na estrutura do vídeo

Cenas 1–7: conteúdo

Roteiro, exemplos, animações — o valor real do vídeo.

Cena 8: resumo

Recap rápido (3–5 s) dos pontos principais — ancora a memória.

Cena 9: CTA INEMA.CLUB ← obrigatório

INEMA.CLUB com glow + URL + narração curta. Já inclusa no template.

✓ FAZER no CTA

✓ Manter a cena de CTA em TODOS os vídeos
✓ URL legível e URL falada na narração
✓ Adaptar para sua marca (troque INEMA.CLUB pelo seu domínio)
✓ Manter glow âmbar — identidade visual consistente

✗ NÃO FAZER no CTA

✗ Remover a cena final (perde conversão e identidade)
✗ Colocar CTA longo (> 8 s) — viewer abandona
✗ URL ilegível ou fundo que compete com o texto
✗ Esquecer de falar a URL na narração

Conceitos-chave

scene9()

Função pré-construída no template — não reescreva do zero, apenas ajuste o domínio e o glow.

Glow âmbar

drop-shadow âmbar #FFC300 pulsa na marca — sinaliza "clique aqui" sem precisar de botão.

Duplo canal

URL visual + URL narrada = reforço bimodal. Quem assistiu com som e quem assistiu no mudo captura o destino.

♻️ Um roteiro, dois formatos

Um único SCRIPT.md + um único build-index.mjs produzem os dois MP4s. É o fluxo completo de publicação do HyperFrames — nenhum código duplicado.

Princípio DRY aplicado a vídeo

Escreva o roteiro uma vez. Adapte o CSS das cenas com seletores .vertical. Rode o gerador duas vezes. O resultado são dois MP4s prontos para publicação no YouTube (16:9) e no YouTube Shorts / Instagram Reels / TikTok (9:16).

Sequência completa de render (ambos os formatos)

# 1. Render 16:9 — YouTube (1920×1080)

node build-index.mjs && \

npx hyperframes render --quality high \

--output renders/kokoro-tts-16x9.mp4

# 2. Render 9:16 — Shorts/Reels (1080×1920)

node build-index.mjs --vertical && \

npx hyperframes render --quality high \

--output renders/kokoro-tts-9x16.mp4

# 3. Validar antes de publicar

npx hyperframes lint # 0 erros

npx hyperframes inspect --samples 16 # 0 layout issues

💡

Sempre renderize o draft primeiro

Use --quality draft para conferir timing e layout antes de gastar tempo no render final. Extraia frames com npx hyperframes inspect --samples 16 e revise os 16 prints antes de executar --quality high.

Pipeline resumido

📄

SCRIPT.md

6–9 cenas, ~100s fala

→

🔧

build-index.mjs

sceneN() + anim()

→

🎬

16x9.mp4

9x16.mp4

prontos p/ upload

✓ FAZER no fluxo dual

✓ Renderizar 16:9 primeiro, validar, depois 9:16
✓ Guardar os dois MP4s em renders/ com nomes distintos
✓ Testar --quality draft nos dois modos antes do high
✓ Adicionar seletores .vertical no CSS de cenas com texto longo

✗ NÃO FAZER no fluxo dual

✗ Manter dois arquivos build-index separados (viola DRY)
✗ Publicar sem fazer lint — bugs de layout aparecem no player
✗ Sobrescrever renders/ sem versionamento
✗ Ignorar safe zone no modo vertical

Conceitos-chave

DRY

Don't Repeat Yourself — um código fonte, dois outputs. Manutenção zero duplicada.

renders/

Pasta de saída padrão. Nomeie sempre com sufixo -16x9 e -9x16 para não confundir.

lint + inspect

Dois passes de qualidade: lint verifica HTML/JS; inspect extrai frames e mostra overflow visual.

draft → high

Render draft é rápido (~20s). High pode levar minutos. Sempre valide no draft primeiro.

📋 Resumo do Módulo 4.1

✓ 16:9 (1920×1080) = YouTube. Sem flag no build-index.mjs.

✓ 9:16 (1080×1920) = Shorts/Reels/TikTok. Flag --vertical.

✓ ~100s de fala (≈ 1:50) maximiza retenção. Voz pf_dora speed 0.98.

✓ Captions burned-in: Inter 600, 36px, rgba(0,0,0,0.55). Sempre ligadas.

✓ CTA final (scene9) obrigatório — INEMA.CLUB ou sua marca.

✓ Um SCRIPT.md → dois MP4s. Lint + inspect antes de publicar.

Próximo módulo:

4.2 🚀 Onboarding, aulas & lançamentos

Aplique o HyperFrames em vídeos de boas-vindas de curso, aulas gravadas e lançamentos de produto — com variações de CTA por contexto.

← Voltar para Trilha 4 Próximo Módulo: 4.2 Onboarding →