lanceriedel/demo-narrado

Demo narrado

Um agente, uma tarde, um .mov que um VP pode assistir no celular. A receita (comprovada em cinco clipes, 69–188 s cada):

1. Entreviste o usuário — cinco perguntas, no máximo (abaixo). Esboce a história a partir do contexto que você já possui; o usuário edita, não escreve.
2. Escreva uma especificação de cena (clips/<nome>.yaml): 4–8 cenas, ~25–45 palavras de narração cada (≈ 10–18 s falados). Cada cena tem uma revelação — o momento em que a coisa aparece — e o vídeo é cortado para que a revelação apareça cedo, não por último.
3. Renderize: scripts/render_clip.py clips/<nome>.yaml. Por cena: TTS → captura → ajuste de vídeo ao áudio → legenda → multiplexação; depois concatene.
4. Revise as imagens estáticas que o renderizador escreve (out/_<clipe>_<cena>.png) com a ferramenta read antes de declarar concluído. Renderize novamente cenas individuais com --only s2.
5. Publique (opcional): scripts/slack_post.py <id_do_canal> out/<clipe>.mov "<texto>".

Tudo é reexecutável e armazenado em cache (TTS por hash de texto, vídeo por cena), então iterar em uma frase custa segundos.

1. A entrevista (faça estas perguntas, depois esboce)

Faça todas as cinco em uma única mensagem; aceite respostas parciais e preencha o restante a partir do contexto, rotulando o que você assumiu.

1. Para quem é e quanto tempo eles têm? (engenheiro colega 3 min · executivo 90 s · rolagem no Slack 60 s) → define o número de cenas e o ritmo.
2. Qual é a única coisa em que eles devem acreditar depois de assistir? → torna-se a primeira frase da cena 1 e a última frase da última cena.
3. O que deve estar na tela? (uma interface de usuário, um terminal, um documento, um gráfico, um arquivo) → decide os tipos de captura. Peça URLs / comandos / caminhos.
4. Qual é o momento 'ao vivo'? Algo que acontece visivelmente (uma consulta retornando, uma compilação terminando, um número aparecendo). No mínimo um por clipe.
5. Voz e tom? Padrão: onyx, "calmo, claro, confiante, narração de demonstração técnica, ritmo médio, leve ênfase em números". Ofereça alloy/nova se quiserem algo mais leve.

Em seguida, proponha o storyboard como uma tabela (cena · o que está na tela · resumo da narração em 1 linha · revelação) e obtenha um sinal verde antes de renderizar. Renderizar um clipe de 5 cenas leva ~3–6 min; não renderize antes do sinal verde.

2. Especificação de cena

clip: 1-setup                 # nome da saída → out/1-setup.mov
tamanho: 1440x900              # opcional: moldura comum para todas as cenas (ajustar + preencher) — defina ao misturar cenas de tela e navegador
voz: onyx
instrucoes: "Narração calma, clara e confiante de demonstração técnica. Ritmo médio, pausas naturais nos pontos. Leve ênfase em números."
cenas:
  - id: s1                    # ids curtos e estáveis → chaves de cache
    legenda: "Tese · um gráfico, quatro evidências"     # terço inferior; mantenha ≤ 60 caracteres
    narracao: "…25–45 palavras…"                        # escreva números por extenso se o TTS os distorcer ("dezoito mil")
    # exatamente uma fonte de captura por cena:
    url: "http://127.0.0.1:4300/#mode=purchase"       # (a) navegador via Playwright — mais ações opcionais:
    acoes:                                             #     executadas após o carregamento, em ordem; `ready` marca a revelação
      - preencher: ["#prompt", "Acne Studios"]
      - pressionar: ["#prompt", "Enter"]
      - aguardar: ".layer-chip"                           #     seletor (timeout de 45 s) → define ready
      - clicar: "button:has-text('fit')"
      - selecionar: ["#graph-layout", "brand"]
      - rolar_ate: "#join"                            #     scrollIntoView (para documentos longos) → define ready
      - pairar: ".card"
    # video: "cache/cr_s3"                            # (b) diretório pré-gravado (page.mov + marks.json) ou um arquivo — veja record_screen.sh
    # imagem: "docs/figure.png"                        # (c) uma imagem estática (gráfico, slide) — sem Ken-Burns, mantida pela narração
    pausa: 2                                           # segundos extras após a última ação
    velocidade: 1                                      # pré-acelera a fonte (8 = rastreamento lento mostrado a 8×)
    escala: 2560                                       # largura de redução por cena (gravações de tela); fonte: 28 = tamanho da legenda em px para esta cena

Regras que tornaram os clipes bons:

• Revelação primeiro. O renderizador inicia cada cena ~2,5 s antes de ready, preenche o último quadro se a narração for mais longa, corta se for mais curta. Uma cena cuja revelação está no segundo 40 de uma gravação de 45 s se torna uma cena de 12 s que abre na revelação.
• Narração e tela concordam. Cada nome em maiúsculo e cada número na narração devem estar visíveis ou prestes a ficar visíveis. Corte frases que não estejam.
• Uma ideia por cena. Se uma frase começa com "também", é uma nova cena ou é cortada.
• Legendas são o esboço. Ler apenas as legendas deve contar a história toda.
• Nunca invente um número para a narração. Extraia-o de um arquivo de resultado ou de uma resposta ao vivo que você acabou de gerar; diga "aproximadamente" se arredondado.

3. Fontes de captura

• Navegador (url + acoes) — Playwright Chromium, 1440×900, headless, grava webm. Precisa de um projeto Node com @playwright/test e Chromium instalado; defina PW_REPO=/caminho/para/o/projeto (padrão: o próprio pw/ da skill — execute scripts/setup.sh uma vez para criá-lo).
• Tela / terminal (video) — scripts/record_screen.sh <cena> <segundos> [--rect x,y,l,a] -- <comando…>: inicia screencapture -V, executa seu comando, escreve marks.json com started (ms) quando o comando sinaliza a revelação imprimindo MARK. Ponto de atenção: screencapture -V só avança quando os pixels mudam; um painel de terminal estático congela a gravação. Mantenha algo em movimento (uma linha de relógio de 1 Hz) ou use show_file.sh que exibe um arquivo com um relógio. Reduza capturas largas com DEMO_SCALE=2560. Privacidade: grave um retângulo (--rect, em pontos; screencapture -R) para que apenas o painel desejado seja capturado — sem título de janela, barra de guias, barra lateral, dock, notificações ou janelas de fundo. Antes de publicar, leia cada imagem de revisão e pergunte: há algo na tela que identifique um empregador, um host, uma URL interna, outra pessoa? Neutralize o texto que você exibe (show_file.sh) — é a demonstração, não seus arquivos reais.
• Imagem estática (imagem) — um PNG/JPG mantido pela narração; use para gráficos, tabelas, um slide.
• Pré-gravado (video: arquivo.mov) — com ready: <segundos> na cena.

4. Renderize, revise, publique

export OPENAI_API_KEY=…                     # TTS (gpt-4o-mini-tts); ou TTS_URL=https://<proxy>/v1/audio/speech TTS_API_KEY=… para um proxy compatível
scripts/render_clip.py clips/1-setup.yaml            # clipe completo → out/1-setup.mov (+ out/_1-setup_<cena>.png imagens estáticas)
scripts/render_clip.py clips/1-setup.yaml --only s2  # renderizar novamente uma cena, reconcatenar
DEMO_FONT=26 scripts/render_clip.py …                # tamanho da legenda (22 para 1440 px, 26–30 para fontes de 2560 px)

Revise: read duas ou três das imagens out/_*.png. Se uma cena de navegador registrar wait failed: … Timeout, o aplicativo estava lento ou o seletor mudou: a cena ainda renderiza a partir de t=0 (sem corte de revelação) — corrija o seletor ou apenas execute novamente essa cena com --only <id> quando o aplicativo estiver ocioso (quadro de abertura de cada cena) — verifique se a legenda é legível, a revelação está na tela, nada confidencial está visível (tokens, linhas de nível de comprador, mensagens de outras pessoas). Assista os primeiros e últimos 5 s do .mov, se possível.

Publique no Slack com um texto de ≤ 3 linhas: o que mostra · duração · um número. scripts/slack_post.py C0123… out/1-setup.mov "…" usa as credenciais da sessão do navegador slack-mcp em ~/.config/slack-mcp/credentials.json; se ausente, entregue o arquivo e o texto ao usuário.

5. Convenções (mantenha o projeto organizado)

clips/ especificações · cache/ TTS + vídeo por cena (gitignorado) · out/ finais + imagens estáticas · blurbs/ texto do Slack. Nomeie clipes em ordem de reprodução (0-…, 1-…, 2a-…). Mantenha um storyboard.md com a tabela da entrevista; é o artefato que as pessoas pedem após o vídeo.

Dependências: ffmpeg/ffprobe, node ≥ 18, Playwright Chromium (para cenas de navegador), macOS screencapture (para cenas de tela), uma chave TTS. scripts/setup.sh verifica e instala o que puder.