Módulo 2.3 — Roteiro & Narração TTS | HyperFrames

🎬 SCRIPT ponto M D com 6–9 cenas

O SCRIPT ponto M D é o coração do seu vídeo. Ele descreve cada cena em texto — o que aparece na tela e o que é falado. Um arco bem estruturado garante retenção máxima em vídeos curtos.

Conceito Principal

O SCRIPT ponto M D segue um arco dramático de 8 etapas: hook → primeiro princípio → mecânica → conceito-chave → aplicação → avançado → exemplo real → fecho → CTA. Cada etapa é uma cena. O arco existe para prender a atenção do início ao CTA de inema ponto club.

Vídeos de ~100 segundos de fala (≈ 1:50 de vídeo) performam melhor em retenção e cabem como Shorts. Cada cena deve ter 1–3 frases, nunca um monólogo.

Arco das 8–9 cenas

Hook — a promessa

Primeira frase chama atenção imediata. Pergunta, afirmação ousada ou dado surpreendente. Ex: "E se você pudesse criar vídeos profissionais sem pagar nada?"

Primeiro princípio — fundação

Explica o conceito mais básico. Sem jargão. Um parágrafo que qualquer pessoa entende. Aqui nasce o entendimento.

Mecânica — como funciona

Detalha o mecanismo interno: Chrome captura frames, FFmpeg encoda, Kokoro fala. Técnico mas direto.

Conceito-chave — o insight

A ideia que muda a forma de ver o problema. Normalmente uma frase memorável. Ex: "O navegador é uma câmera de cinema."

Aplicação — na prática

Primeiro comando ou passo concreto. O espectador vê como usar. Ex: "Rode npx hyperframes init e o projeto já está configurado."

Avançado — nível superior

Recurso que separa iniciante do usuário avançado. Hooks, flags, vozes alternativas, dois formatos. Gera curiosidade e valor.

Exemplo real — prova social

Este vídeo foi feito com a própria ferramenta. Ou um link, screenshot, resultado concreto. Quebra ceticismo.

Fecho — síntese

Uma frase que fecha o loop do hook. Reforça a transformação que o espectador vai ter. Curto e firme.

CTA — inema ponto club

Chama para o curso completo em inema ponto club. Sempre a última cena. Direto e com ação clara: "Acesse inema ponto club agora."

Estrutura do SCRIPT ponto M D

# SCRIPT.md — exemplo para vídeo sobre HyperFrames Skills

## Cena 1 — Hook

**Tela:** título "Skills no Claude Code" fadeIn

**Fala:** "O que são, de verdade, as Skills no Claude Code?"

## Cena 2 — Primeiro princípio

**Tela:** diagrama pasta + SKILL.md

**Fala:** "Uma Skill é só uma pasta com um arquivo chamado SKILL ponto M D."

## ... (cenas 3–8)

## Cena 9 — CTA

**Tela:** logo INEMA.CLUB + URL

**Fala:** "Curso completo em inema ponto club."

✓ Boas práticas de roteiro

✓ Cada cena tem foco único — não misture dois conceitos
✓ Narração de 1–3 frases por cena (≤15 segundos)
✓ Total de fala ≈ 100s para vídeo de ~1:50
✓ Sempre terminar com CTA explícito

✗ Erros de roteiro

✗ Cenas longas demais — a atenção cai depois de 15s
✗ Hook sem tensão — não promete uma transformação
✗ Pular do fundamento direto para avançado
✗ Esquecer o CTA — sem ele o vídeo não converte

Conceitos-chave

🎯

Arco dramático

8–9 etapas

⏱️

~100s de fala

≈ 1:50 vídeo

📌

1–3 frases/cena

Retenção máxima

📣

CTA final

inema.club

✂️ Narração curta por cena

Cada cena recebe de 1 a 3 frases de narração. O total de ~100 segundos de fala produz aproximadamente 1 minuto e 50 segundos de vídeo — ideal para retenção e compatível com Shorts.

Regra dos 100 Segundos

Humanos retêm mais informação em vídeos curtos. Com ~100s de fala no total, cada cena fica com ≈11–17 segundos — tempo suficiente para absorver uma ideia, rápido o suficiente para não entediar.

8 cenas

×12,5s média

~100s

de fala total

≈1:50

de vídeo final

Exemplo real — 8 cenas do narration-template ponto sh

# assets/narration.sh — trecho com write() por cena

write s1 "O que são, de verdade, as Skills no Claude Code?"

write s2 "Uma Skill é só uma pasta com um arquivo chamado SKILL ponto M D."

write s3 "Todo SKILL ponto M D começa com duas linhas: name e description."

write s4 "Divulgação progressiva: o Claude carrega só o que precisa, quando precisa."

write s5 "Skills vivem em ponto claude barra skills do seu projeto ou na pasta global."

write s6 "No nível avançado, uma Skill traz scripts, paletas e templates completos."

write s7 "Este vídeo foi feito pela Skill HyperFrames. Uma skill, um fluxo, um resultado."

write s8 "Comece simples. Curso completo em inema ponto club."

💡

Frase curta = fala natural

O TTS Kokoro performa melhor com frases simples e diretas. Evite gerundismo excessivo, subordinadas longas ou listas faladas. Se precisar de pausa, quebre em duas frases separadas por ponto final.

Comparativo: distribuição de tempo por cena

Cena 1

~8s

Cenas 2–7

~72s

Cena 8

~6s

CTA final

~5s

Narração

CTA/Fecho

Conceitos-chave

✂️

1–3 frases

por cena

📐

~12s/cena

média ideal

⏱️

100s total

fala acumulada

📱

Cabe em Shorts

≤60s na tela

🗣️ Expandir siglas para fala

O Kokoro TTS lê o texto literalmente. Siglas, extensões de arquivo e URLs precisam ser escritas como são faladas — ou o TTS vai pronunciar de forma estranha ou incompreensível.

Regra de Expansão

O texto do arquivo sN.txt é escrito para ouvidos, não para olhos. Qualquer símbolo, sigla ou path que não seja uma palavra falável precisa ser substituído pela sua pronúncia exata.

Tabela de expansões obrigatórias

Texto escrito	Fala no sN.txt	Razão
SKILL.md	SKILL ponto M D	extensão de arquivo
.claude/skills	ponto claude barra skills	path com símbolos
inema.club	inema ponto club	URL / domínio
build-index.mjs	build hífen index ponto M J S	nome de arquivo
s1.txt	S um ponto T X T	nome de arquivo
--speed 0.98	speed zero ponto noventa e oito	flag CLI com número
pf_dora	P F underscore dora	identificador de voz
npx hyperframes	N P X hyperframes	sigla + comando

Exemplo: s2.txt — texto expandido para TTS

# assets/txt/s2.txt — versão para leitura do TTS

"Comece pelo essencial. Uma Skill é só uma pasta com um arquivo chamado

SKILL ponto M D. Dentro dele, instruções em Markdown que ensinam o Claude

a fazer algo específico: criar vídeos, revisar código, desenhar interfaces.

É conhecimento empacotado."

# NÃO escreva: "SKILL.md" → o TTS leria "esquil ponto md" ou erraria

# NÃO escreva: ".claude/skills" → leria "ponto claude barra skills" errado

✓ Expansões corretas

✓ "ponto claude barra skills" para .claude/skills
✓ "inema ponto club" para inema.club
✓ "SKILL ponto M D" para SKILL.md
✓ Teste a pronúncia em voz alta antes de salvar

✗ Erros de expansão

✗ Deixar SKILL.md sem expandir
✗ Usar URL literal https://inema.club
✗ Escrever comandos bash como npx --help
✗ Colocar listas com hífens — TTS lê o hífen em voz

💡

Dica: dois arquivos, dois propósitos

Mantenha o SCRIPT ponto M D com o texto "visual" (com siglas, paths, URLs normais) para referência humana. O arquivo sN.txt é a versão "para ouvidos" — texto já expandido que vai para o TTS. São documentos diferentes com propósitos diferentes.

Conceitos-chave

👁️

Texto visual

SCRIPT.md

👂

Texto falado

sN.txt

🔤

Expansão

ponto, barra, hífen

🎤

Teste oral

Leia em voz alta

🔊 Gerar WAV com Kokoro

Com os arquivos sN.txt prontos e expandidos, o comando npx hyperframes tts gera os WAVs localmente. A primeira execução baixa ~340 MB do modelo Kokoro automaticamente.

Comando exato — npx hyperframes tts

# Gera narração para a cena 1

npx hyperframes tts "assets/txt/s1.txt" \

--voice pf_dora \

--speed 0.98 \

--output assets/audio/s1.wav

# Loop para todas as cenas (narration.sh)

for i in 1 2 3 4 5 6 7 8; do

npx hyperframes tts "assets/txt/s$i.txt" \

--voice pf_dora --speed 0.98 \

--output "assets/audio/s$i.wav"

done

⚠️

Primeira execução: download de ~340 MB

Na primeira vez que você roda npx hyperframes tts, o Kokoro baixa o modelo de voz (~340 MB) automaticamente. Sem chave, sem espeak-ng, sem config. Após o download, os próximos runs são instantâneos. Certifique-se de ter conexão na primeira vez.

Por que --speed 0.98?

A velocidade padrão do Kokoro soa ligeiramente rápida demais para narrativas técnicas em português. Com --speed 0.98 a voz fica natural, sem soar lenta. Não suba acima de 1.05 — a voz fica metálica.

0.80

Muito devagar

0.98 ✓

Ideal PT-BR

1.05+

Metálico

💡

Gere um WAV de teste antes do loop completo

Rode só a cena 1 primeiro. Ouça o resultado. Se a pronúncia de alguma expansão ficou estranha, corrija o s1.txt antes de gerar os outros 7 arquivos. Retrabalho cena a cena é muito mais rápido que refazer tudo.

Conceitos-chave

🔊

npx hyperframes tts

comando gerador

🎙️

pf_dora

voz padrão PT-BR

⚡

--speed 0.98

natural e fluido

📦

~340 MB

download único

📏 Medir durações com ffprobe

Antes de montar as cenas no build-index.mjs, você precisa saber exatamente quantos segundos cada narração dura. O ffprobe retorna a duração do WAV em segundos com uma linha.

Por que medir antes de montar?

O build-index.mjs define quanto tempo cada cena fica na tela via LEAD, TAIL e a duração do áudio. Se você não souber a duração exata do WAV, o texto vai sumir da tela antes da fala terminar — ou vai ficar parado demais.

Comandos ffprobe — duração de um WAV e loop completo

# Duração de um arquivo único

ffprobe -v error \

-show_entries format=duration \

-of default=noprint_wrappers=1:nokey=1 \

assets/audio/s1.wav

# Saída: 12.384000

# Loop — medir todas as cenas de uma vez

for i in 1 2 3 4 5 6 7 8; do

d=$(ffprobe -v error -show_entries format=duration \

-of default=noprint_wrappers=1:nokey=1 \

"assets/audio/s$i.wav" 2>/dev/null)

echo "s$i: ${d}s"

done

📊 Valores de referência (narration-template real)

~8–10s

hook curto

s2–s6

~12–18s

desenvolvimento

~8–12s

exemplo real

~5–8s

CTA rápido

✓ Workflow correto

✓ Gere todos os WAVs primeiro, depois meça
✓ Anote as durações no SCRIPT ponto M D
✓ Use as durações no build-index para definir timing
✓ LEAD=0.5 antes da fala + TAIL=0.9 após a fala

✗ Erros de timing

✗ Usar duração estimada — sempre meça o WAV real
✗ Cortar cena antes do áudio terminar
✗ Não deixar o LEAD antes da narração começar
✗ Esquecer o FADE=0.45 no final da cena

💡

Valores de timing padrão do pipeline

O build-index.mjs usa por padrão: LEAD=0.5 (silêncio antes da fala), TAIL=0.9 (silêncio após a fala) e FADE=0.45 (fade-out de saída). A duração total da cena = LEAD + duração_do_wav + TAIL.

Conceitos-chave

📏

ffprobe

mede WAV

⏩

LEAD=0.5

antes da fala

⏸️

TAIL=0.9

após a fala

🌅

FADE=0.45

fade-out final

🎚️ Vozes PT-BR disponíveis

O Kokoro tem três vozes PT-BR prontas para uso: pf_dora (feminina, padrão recomendado), pm_alex e pm_santa. Cada voz tem timbre distinto — escolha conforme o tom do vídeo.

🎙️

pf_dora

PT-BR · Feminina

Voz feminina clara e natural em português do Brasil. É a voz padrão do narration-template.sh e a recomendada para todos os vídeos do pipeline HyperFrames.

--voice pf_dora --speed 0.98

🎤

pm_alex

PT-BR · Masculina

Voz masculina grave, boa para conteúdo mais sério ou técnico. Alternativa para variar em séries longas ou quando o tom exige mais autoridade.

--voice pm_alex --speed 0.98

🔈

pm_santa

PT-BR · Alternativa

Terceira opção PT-BR com timbre diferenciado. Use para testar se o conteúdo específico soa mais natural nessa voz ou para A/B test de retenção.

--voice pm_santa --speed 0.98

✓ Boas práticas de voz

✓ Use pf_dora como padrão — é a mais testada
✓ Mantenha a mesma voz em todo o vídeo
✓ Teste a voz com a cena de maior complexidade primeiro
✓ Velocidade 0.95–1.00 para narração técnica

✗ Erros com vozes

✗ Misturar vozes dentro do mesmo vídeo
✗ Speed acima de 1.05 — soa robótico
✗ Speed abaixo de 0.85 — arrasta demais
✗ Tentar instalar espeak-ng — Kokoro não precisa

📊 Comparativo técnico das vozes

Voz	Gênero	Timbre	Melhor para
pf_dora	Feminina	Claro, natural	Cursos, tutoriais, padrão
pm_alex	Masculina	Grave, autoritativo	Tech sério, demos
pm_santa	Masculina	Diferenciado	A/B test, variedade

💡

Sem espeak-ng, sem chave, sem conta

Kokoro tem fonemizador PT-BR nativo — não precisa do espeak-ng que outros motores TTS open-source exigem. Nenhuma chave de API, nenhuma conta em plataforma. Instalar espeak-ng pode até conflitar com a fonética do Kokoro, então evite.

Conceitos-chave

🏆

pf_dora

padrão recomendado

3️⃣

3 vozes PT-BR

dora, alex, santa

🚫

Sem espeak-ng

fonética nativa

🔑

Sem chave

local e gratuito

📋 Resumo do Módulo 2.3

O que você aprendeu

✓ SCRIPT ponto M D com arco de 8–9 cenas: hook → princípio → mecânica → insight → aplicação → avançado → exemplo → fecho → CTA
✓ Narração de 1–3 frases por cena; ~100s de fala total ≈ 1:50 de vídeo
✓ Expansão de siglas: "SKILL.md" → "SKILL ponto M D"; ".claude/skills" → "ponto claude barra skills"; "inema.club" → "inema ponto club"
✓ Gerar WAV: npx hyperframes tts "assets/txt/s1.txt" --voice pf_dora --speed 0.98 --output assets/audio/s1.wav
✓ Medir duração: ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 assets/audio/s1.wav
✓ Vozes PT-BR: pf_dora (padrão), pm_alex, pm_santa — sem espeak-ng, sem chave, ~340 MB download único

Próximo módulo

2.4

🎞️ Composição de cenas

Monte as cenas no build-index.mjs usando as durações dos WAVs. Defina LEAD, TAIL, FADE e os timings de cada animação para gerar o index.html final pronto para render.

Ir para o módulo 2.4 →

← Voltar para Trilha 2 Próximo Módulo: 2.4 Composição →