Communitygithub.com

demo-narrator

Transforme uma demonstração de produto ou gravação de tela em um vídeo narrado com voz natural, efeitos sonoros de interface, música opcional e legendas — 100% local e gratuito.

O que é demo-narrator?

Esta skill é um pipeline completo para adicionar narração profissional, efeitos sonoros e legendas a vídeos de demonstração de produtos, gravações de tela ou walkthroughs. Ela extrai quadros do vídeo, analisa as cenas e gera um rascunho de roteiro baseado no conteúdo visual. Um ponto de aprovação obrigatório do roteiro impede a geração de áudio até que o usuário revise e aprove o texto da narração. A skill suporta síntese de voz local com Kokoro-82M TTS (com fallback para Piper), efeitos sonoros de UI (whooshes, pops, clicks, dings) e música de fundo gerada sinteticamente em vários estilos (positive, lofi, upbeat, ambient). Tudo funciona offline, sem chaves de API, usando apenas FFmpeg, Python e modelos de peso local. O resultado final é um vídeo H.264/AAC com legendas incorporadas e um arquivo .srt separado.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/GarvitSolanki/audio-generator/tree/main/skills/demo-narrator

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

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

  1. Se $PY nã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, execute bash "$SKILL/setup.sh" (leva alguns minutos; execute em segundo plano).
  2. 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.
  3. 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-duration para sobrescrever; use --interval 4 para vídeos longos).
  • Revise $WORK/sheets/*.jpg primeiro (cada um rotulado com timestamps). Abra quadros individuais $WORK/frames/*.jpg apenas 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,5 palavras (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ício ao 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.

  • whoosh em transições de página/tela (use scene_changes), whoosh_soft para painéis/modais deslizando, pop para elementos/toasts aparecendo, click para pressionamentos de botão importantes, ding para 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.

  1. Apresente o roteiro como uma tabela e pare:

    #TempoPalavras / orçamentoNarraçãoSFX
    10:00.4–0:04.611 / 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."

  2. Termine sua vez e espere. Silêncio, "parece bom?" ou aprovação de um rascunho anterior não é aprovação deste.

  3. Em edições: atualize script.json, reapresente as linhas alteradas, espere novamente.

  4. 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" --approve
    

    O carimbo é um resumo do texto da narração. generate_tts.py e render_video.py se 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 defina approved/approved_digest manualmente. Edições de tempo (início/fim) e sfx nã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 piper para 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 mover início/fim ou 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 ajuste atempo que 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 + overlay do FFmpeg, sem necessidade de libass), escreve $WORK/output_final.mp4 e subtitles.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 N para uma variação). Faça prévias de 30–40 s com --duration 40 e deixe o usuário escolher ouvindo antes de renderizar tudo, então renderize com --bgm "$WORK/bgm.wav". --bgm també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 escreve subtitles.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

  1. Verifique a saída da renderização: coluna drift ~0, nenhum aviso de quadro parado (ou explique-o).
  2. 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-scale ou avise o usuário.
  3. 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

SintomaCorreção
kokoro unavailable … trying fallbackExecute 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 pronunciadoSoletre foneticamente em text (ex. "Kubernetes" → "ku-ber-ne-tis"), obtenha aprovação, regenere aquele segmento com --only.
Voz parece apressadaReduza 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 VFRAdicione --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.

Habilidades Relacionadas