Demo Narrator
Pipeline: quadros → entender → rascunho do roteiro → PORTÃO DE APROVAÇÃO DO USUÁRIO → SFX + TTS → renderizar → verificar.
Saída: output_final.mp4 (H.264/AAC, −16 LUFS, legendas embutidas) + subtitles.srt.
SKILL="<caminho absoluto do diretório que contém este SKILL.md>" # ex. ~/.claude/skills/demo-narrator ou ./.claude/skills/demo-narrator
PY="$SKILL/.venv/bin/python"
Resolva SKILL uma vez no início (depende de onde a skill foi instalada) e use caminhos absolutos daí em diante.
0. Pré-voo
- Se
$PYnão existir, informe ao usuário que a instalação baixa ffmpeg + espeak-ng (Homebrew/apt), um venv Python 3.12, PyTorch e ~400 MB de pesos de modelo gratuitos; se a resposta for sim, executebash "$SKILL/setup.sh"(leva alguns minutos; execute em segundo plano). - Escolha um diretório de trabalho ao lado do vídeo:
WORK="<dir do vídeo>/demo-narrator-work/<nome base do vídeo>". Nunca escreva dentro do diretório da skill. - Pergunte (em uma mensagem, apenas o que for desconhecido): nome do produto + o que ele faz, público, tom (padrão: amigável, confiante, conciso), preferência de voz (padrão
af_heart) e tudo que deve ser dito (CTA, URL). Não bloqueie se o usuário já disse "apenas faça" — infira a partir dos quadros.
1. Extrair quadros + verificar duração
"$PY" "$SKILL/scripts/extract_frames.py" "<video>" --out "$WORK"
- Imprime duração/resolução, amostra 1 quadro / 2 s, detecta mudanças de cena, constrói folhas de contato 3×3.
- Recusa vídeos com menos de 3 s ou mais de 15 min (
--force/--max-durationpara sobrescrever; use--interval 4para vídeos longos). - Revise
$WORK/sheets/*.jpgprimeiro (cada um rotulado com timestamps). Abra quadros individuais$WORK/frames/*.jpgapenas onde precisar de detalhes (texto pequeno de UI, momento exato de um clique). $WORK/frames.json→duration,scene_changes(melhores lugares para whooshes), lista de quadros.
Construa uma lista de batidas: o que está na tela em cada momento, quais ações acontecem (clique, digitação, mudança de página, estado de sucesso) e o que o espectador deve absorver.
2. Rascunhar $WORK/script.json
{
"video": "/abs/path/to/demo.mp4",
"voice": "af_heart",
"speed": 1.0,
"approved": false,
"segments": [
{"id": 1, "start": 0.4, "end": 4.6, "text": "Conheça o Relay, a forma mais rápida de transformar chamadas de clientes em tickets."},
{"id": 2, "start": 5.0, "end": 10.8, "text": "Solte uma gravação, e o Relay extrai cada bug, solicitação e acompanhamento para você."}
],
"sfx": [
{"name": "whoosh", "at": 4.8},
{"name": "pop", "at": 7.2, "gain_db": -12},
{"name": "ding", "at": 10.4}
]
}
Regras de tempo
- Orçamento de palavras por segmento ≈
(fim − início) × 2,5palavras (Kokoro ≈ 150 ppm na velocidade 1.0). Fique abaixo disso. - Deixe ≥ 0,3 s entre segmentos; comece a primeira linha em ~0,3–0,8 s; deixe o vídeo respirar após momentos grandes.
- Ancore o
inícioao momento em que a coisa sendo descrita aparece, não antes. A narração pode liderar uma ação em ~0,3 s. - Os segmentos não devem exceder o vídeo; o segmento final deve terminar ≥ 1 s antes do fim do vídeo.
Escrevendo para o ouvido
- Conversacional, segunda pessoa ("você"), contrações, verbos ativos. Uma ideia por segmento.
- Descreva o benefício do que está acontecendo, não os pixels. Nunca "Aqui vemos…" / "Como você pode ver…".
- Escreva as coisas como devem ser faladas: "duas-vezes mais rápido", "A-P-I" apenas se deve ser soletrado, "ponto com". Evite símbolos, emojis, URLs com barras e parênteses.
- Frases curtas. Termine com um CTA claro se o usuário forneceu um.
SFX (whoosh, whoosh_soft, pop, click, ding) — at é o tempo absoluto do vídeo.
whooshem transições de página/tela (usescene_changes),whoosh_softpara painéis/modais deslizando,poppara elementos/toasts aparecendo,clickpara pressionamentos de botão importantes,dingpara sucesso/conclusão.- Moderação: ~1 cue a cada 4–6 s no máximo. Não empilhe cues com menos de 0,3 s de diferença. Nível padrão −9 dB abaixo da voz; defina
gain_db(ex. −14) para sons sutis.
Vozes (Kokoro): af_heart (feminino US caloroso, padrão), af_bella, am_michael / am_fenrir (masculino US), bf_emma (feminino UK), bm_george (masculino UK). Outras vozes são baixadas uma vez no primeiro uso.
3. ⛔ PORTÃO DE APROVAÇÃO DO ROTEIRO — obrigatório
Não gere nenhum áudio até que o usuário aprove explicitamente o roteiro.
-
Apresente o roteiro como uma tabela e pare:
# Tempo Palavras / orçamento Narração SFX 1 0:00.4–0:04.6 11 / 10 ⚠ Conheça o Relay, … — Sinalize segmentos acima do orçamento com ⚠. Mencione a voz + duração total da narração. Termine com: "Aprove este roteiro, ou me diga o que mudar."
-
Termine sua vez e espere. Silêncio, "parece bom?" ou aprovação de um rascunho anterior não é aprovação deste.
-
Em edições: atualize
script.json, reapresente as linhas alteradas, espere novamente. -
Somente após um "sim" explícito ("aprovar", "sim", "vai", "manda") para o texto atual, carimbe-o:
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json" --approveO carimbo é um resumo do texto da narração.
generate_tts.pyerender_video.pyse recusam a executar em um roteiro não carimbado ou se algum texto mudou após o carimbo — você deve voltar por este portão. Nunca definaapproved/approved_digestmanualmente. Edições de tempo (início/fim) esfxnão precisam de re-aprovação.
4. Gerar SFX + narração
"$PY" "$SKILL/scripts/generate_sfx.py" --out "$WORK/sfx"
"$PY" "$SKILL/scripts/generate_tts.py" "$WORK/script.json"
- TTS escreve
$WORK/audio/seg_###.wav+tts.json. Motor: Kokoro, com fallback automático para Piper (--engine piperpara forçar). - Cada clipe é ajustado ao seu slot (até o início do próximo segmento); excedentes são re-sintetizados mais rápido até
--max-speed 1.25. - Se a tabela ainda mostrar
OVER, prefira moverinício/fimou segmentos posteriores (sem re-aprovação). Se o texto precisar ser mais curto, isso é uma mudança de texto → de volta ao portão. - Refazer segmentos individuais:
--only 3 5. Variação diferente de SFX:--seed 7.
5. Renderizar
"$PY" "$SKILL/scripts/render_video.py" "$WORK/script.json"
- Coloca os clipes em seus
início, nunca sobrepondo; pequenos excedentes recebem um ajusteatempoque preserva o tom (≤ 1,12×), o restante desloca clipes posteriores (impresso como drift). Mantém o último quadro se a narração ultrapassar o vídeo. - Mixa voz + SFX, normaliza o volume para −16 LUFS, queima legendas (cartões renderizados com Pillow +
overlaydo FFmpeg, sem necessidade de libass), escreve$WORK/output_final.mp4esubtitles.srt. - Música de fundo opcional (original, sintetizada localmente, sem licenciamento):
"$PY" "$SKILL/scripts/generate_bgm.py" --duration <segundos do vídeo> --out "$WORK/bgm.wav"(estilos:positive(padrão) = violão dedilhado semicolcheia com cordas soltas vibrantes, acorde quente a cada batida, bumbo four-on-the-floor, rimas/claps sincopados, baixo fora do beat, lead suave dedilhado, 111 BPM, break no meio da faixa, modelado em uma demo B2B de referência;demo-bright/demo-dorian= groove de demo SaaS modelado em faixas de demo de produto: 110 BPM, acordes quentes pulsando em colcheias e bombeando com um bumbo suave, claps no 2 e 4, chimbal em colcheias, baixo nas fundamentais, uma linha superior sustentada, uma melodia leve dedilhada, introdução → groove → break de 8 compassos no meio → groove → final limpo;uke,marimba,pluck,kalimba= bases brilhantes para demo de software, um motivo dedilhado ou de martelo sobre uma batida simples de bumbo suave + estalo/clap + shaker e um pouco de baixo, 100–112 BPM, tonalidade maior;lofi(padrão) = batida swingada relaxada com bateria;keys= piano elétrico;upbeat= four-on-the-floor + arpejo;ambient= apenas pad.--bpm,--key(estilos brilhantes),--mood(outros),--seed Npara uma variação). Faça prévias de 30–40 s com--duration 40e deixe o usuário escolher ouvindo antes de renderizar tudo, então renderize com--bgm "$WORK/bgm.wav".--bgmtambém aceita uma faixa fornecida pelo usuário (mp3/m4a/wav): é nivelada automaticamente para a mesma referência, repetida com um crossfade de 2,5 s se mais curta que o vídeo e com fade out no final. Pergunte ao usuário se ele tem os direitos da faixa fornecida. A música faz duck automático sob a voz; ajuste com--bgm-db(padrão −2,5) e--duck-db(padrão −5). - Flags úteis:
--out <caminho>,--orig-volume 0.15(manter áudio original baixo),--sfx-gain-db -12,--no-subs(ainda escrevesubtitles.srt; use quando o vídeo já tiver legendas na tela próximas à parte inferior),--font <ttf>,--font-scale 0.05,--crf 20.
6. Verificar antes de relatar
- Verifique a saída da renderização: coluna drift ~0, nenhum aviso de quadro parado (ou explique-o).
- Verifique legendas:
ffmpeg -ss <t> -i "$WORK/output_final.mp4" -frames:v 1 "$WORK/check_<t>.jpg"em 2–3 pontos médios dos segmentos, depois veja as imagens — legendas legíveis, não cobrindo UI importante. Se cobrirem algo importante, considere--font-scaleou avise o usuário. - Relate: caminho de saída, duração, motor/voz usados, segmentos que foram acelerados ou deslocados e como ajustar (editar
script.json→ re-executar etapas 4–5; edições de texto passam pelo portão novamente).
Solução de problemas
| Sintoma | Correção |
|---|---|
kokoro unavailable … trying fallback | Execute setup.sh novamente; verifique se o Python é 3.10–3.12 em .venv. A saída do Piper é boa, mas menos natural. |
| Palavra/nome mal pronunciado | Soletre foneticamente em text (ex. "Kubernetes" → "ku-ber-ne-tis"), obtenha aprovação, regenere aquele segmento com --only. |
| Voz parece apressada | Reduza speed para 0,95, aumente as janelas dos segmentos ou corte palavras. |
| Legendas muito pequenas/grandes | --font-scale 0.035–0.06. |
| Cores erradas / trepidação VFR | Adicione --fps 30. |
| Vídeo tem música que você quer manter | --orig-volume 0.12–0.2. |
Tudo funciona offline após o download único do modelo. Licenças: Kokoro-82M Apache-2.0, Piper GPL-3.0 (piper-tts ≥1.3), vozes conforme model card, FFmpeg LGPL/GPL.