Communitygithub.com

josueh04/product-video-skills

Escreve a narração de um vídeo de produto e a transforma em clipes de voz com timings de palavras, correções de pronúncia, efeitos sonoros e até loudness. O roteiro vira uma tabela de momentos e depois audio/lines.tsv (um clipe por frase, com colunas de papel e velocidade); tts.py faz a locução com ElevenLabs ou a voz gratuita do macOS say, mapeia as respellings da marca de volta para a grafia na tela, normaliza cada clipe e escreve audio/timings.json para o compositor; make_sfx.py constrói faixas de digitação a partir de teclas reais e coloca sons de clique e pop gravados.

O que é product-video-skills?

Esta skill é especializada na criação de narrações profissionais para vídeos de produto, integrando roteiro, locução TTS e efeitos sonoros. Ela converte um roteiro em uma tabela de momentos e depois em clipes de áudio individuais (lines.tsv), cada um com uma frase, papel (narrador, agente, cliente) e velocidade. A geração de voz suporta ElevenLabs ou a voz nativa do macOS (say), com correção de pronúncia para marcas, normalização de loudness (utilizando ffmpeg loudnorm) e criação de timings precisos (timings.json) que sincronizam cada palavra com a animação. A skill também gera efeitos sonoros realistas, como digitação a partir de teclas reais e cliques/pops gravados. É ideal para pipelines de vídeo que exigem mudanças iterativas no roteiro, substituição de locução ou ajustes de tom, garantindo que alterações em uma frase regenerem apenas o clipe afetado e reajustem o restante automaticamente. Suporta múltiplas versões (cópia de lines.tsv e timings.json para rollback), verificação ortográfica (check_script.py) e validação de pronúncia (pronounce_check.py).

Funciona com✓Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/josueh04/product-video-skills/tree/HEAD/skills/script-and-voice

Perguntar na sua IA favorita

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

Documentação

Roteiro e voz

A voz é o relógio do vídeo. Cada batida da animação está ancorada a uma palavra da narração (T[clip] + w(clip, "word") no build.py), então o roteiro e seus clipes vêm antes da animação, e alterar uma frase regenera um clipe e reajusta o tempo de tudo que vem depois. Na produção de onde estas skills vêm, trocar o motor TTS inteiro reajustou um vídeo finalizado sem edições manuais por causa desse design. Animar primeiro e encaixar a voz depois significa esticar áudio ou arrastar batidas manualmente a cada alteração.

Escreva apenas sob <video_dir>/audio/ (mais a seção de roteiro do BRIEF.md). Toda frase deve ser respaldada no TRUTH.md e respeitar o CLAIMS.md; se uma frase que você precisa não tem fonte, peça para ser verificada ou corte-a.

Roteiros, chamados conforme docs/contracts.md:

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
S="$PVS_HOME/skills/script-and-voice/scripts"
"$PVS_HOME/bin/pvs-py" "$S/check_script.py" <video_dir>                 # lint no lines.tsv
"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir> [--only N3,N4] [--provider say] [--force] [--restore]
"$PVS_HOME/bin/pvs-py" "$S/pronounce_check.py" <video_dir> [--only N3]  # o ASR ouviu as palavras da marca?
"$PVS_HOME/bin/pvs-py" "$S/make_sfx.py" <video_dir> [--list]            # sfx.tsv, ou lista a biblioteca

1. O roteiro é uma tabela de momentos

Uma gravação do produto é uma referência, não uma linha do tempo: tempos de carregamento reais e mudanças de tela não pertencem ao vídeo. Escreva o roteiro como momentos, cada um com o que acontece na tela, a frase (ou silêncio) e quanto tempo dura. Um momento dura o que for maior entre sua ação e sua frase. Comprima esperas reais: quarenta segundos de carregamento viram cerca de dois segundos de um estado de pensamento.

Adicione a tabela ao BRIEF.md sob ## Script, na ordem dos capítulos:

MomentoNa telaLinhaTexto (ou silêncio)Segura
AberturaNome do produto sobre o app desfocadoN1Este é o Acme Tasks, a lista de tarefas que planeja seu dia.0.8 s depois
EsperaO plano está sendo construído(silêncio)2.0 s

Depois escolha o template para o formato do vídeo e siga sua estrutura: leia references/script-templates.md (pitch, tour, página de docs, tutorial, loop silencioso).

Como escrever as linhas, e por quê:

  • Explique os recursos importantes; não os liste. Diga o que um recurso faz para o espectador enquanto a IU o faz. Na produção de onde estas skills vêm, 9 de 26 versões aconteceram porque um vídeo nomeou um recurso sem explicá-lo. COVERAGE.md diz quais recursos devem ser explicados na tela: toda linha marcada como "must explain" precisa de pelo menos uma linha que o explique.
  • Explique cada passo para alguém que nunca viu o produto. Quem é o personagem, o que ele pede, o que cada passo faz. Uma abertura rápida e não explicada foi rejeitada na revisão.
  • Uma ideia por frase e uma frase por clipe. Uma frase alterada custa então um clipe.
  • Nomeie o que o cursor toca no momento em que toca. As batidas ancoram nessas palavras, então o substantivo na tela e a palavra no clipe devem ser os mesmos.
  • Use o rótulo real da IU, mesmo quando o revisor usa outra palavra para ele. O vídeo então corresponde ao que o espectador verá no produto.
  • Escreva números e horários por extenso ("dez da manhã", "trinta minutos depois"). Motores TTS leem dígitos de forma inconsistente e a comparação de fala para texto compara palavras, não dígitos.
  • Deixe ar ao redor de esperas. Cerca de três segundos antes de um telefone tocar, "cerca de um minuto" em vez de um número preciso que ninguém pode verificar.
  • Termine com uma frase completa, lida um pouco mais devagar. Um fragmento de slogan como última linha soou cortado na revisão; uma frase completa com o posicionamento do CLAIMS.md não.
  • Mantenha a pessoa consistente dentro de um vídeo: primeira pessoa como o usuário fictício ("Primeiro, conecto minha agenda.") ou terceira pessoa sobre ele. Use apenas o elenco fictício de product.yaml, com o mesmo nome em todos os vídeos.
  • O posicionamento vem do CLAIMS.md, não dos documentos fonte: um documento fonte pode conter uma frase que a equipe baniu, e a regra vence.

2. lines.tsv

audio/lines.tsv, separado por tabulação, cabeçalho id role speed text, um clipe por linha em ordem de reprodução, linhas com # são comentários. Formato completo e como o build.py lê o resultado: references/audio-formats.md.

  • id: N1, N2, N7b para narração; outras letras para personagens (A1 para um agente, C1 para um cliente). Inserir uma linha entre N7 e N8 como N7b mantém todos os outros ids, e todas as âncoras que os usam, estáveis.
  • role: uma chave de voice.roles em product.yaml (narrator, agent, customer, ou uma variante de leitura como narrator_close, veja seção 3). O papel, não o id, escolhe a voz.
  • speed: 1.0 por padrão, 0.7 a 1.2. Use 0.9 a 0.96 para as linhas de abertura e fechamento.
  • text: exatamente como aparece na tela e nas legendas, com a grafia canônica dos nomes de produtos. Nunca escreva uma respelling aqui; a pronúncia vive em product.yaml.

Antes de alterar linhas de uma versão entregue, copie lines.tsv para lines-v<N>.tsv e timings.json para timings-v<N>.json, para que a versão anterior possa ser reconstruída.

Execute check_script.py após cada edição. Ele falha em ids duplicados, papéis desconhecidos, velocidades fora do intervalo, clipes com mais de 40 palavras, termos banidos, frases never_say, nomes legados e respellings no roteiro, e avisa sobre clipes longos, dígitos e travessões. Corrija todos os erros antes de vocalizar: uma frase banida que chega ao TTS custa uma tomada, e uma que chega a um render custa uma versão.

3. Elenco

Leia references/casting-and-pronunciation.md antes de propor vozes. Em resumo:

  • Ofereça vozes realistas primeiro. A voz padrão do próprio produto e os modelos mais baratos foram julgados "muito falsos" na revisão; o modelo mais natural disponível vale a pena para personagens.
  • Faça audições no contexto: duas linhas consecutivas reais por papel, três a seis candidatos por papel.
  • Proponha cada escolha para veto como uma pergunta fechada com um padrão recomendado ("Narrador: voz B, calorosa e sem pressa. Manter?"). Listas abertas de opções ficaram sem resposta por dias.
  • Decida o tratamento por papel: treatment: phone para alguém em uma chamada, treatment: room para uma reunião gravada, nada para o narrador.
  • Uma leitura por linha (mais estável, mais lenta, menos estilo) é uma variante de papel que aponta para a mesma voz com outras configurações, então a escolha está na configuração e sobrevive a uma reexecução.

voice.provider: say (ou --provider say) usa a voz gratuita do macOS e whisper para timings de palavras. Use para rascunhos, testes e trabalho de timing antes de existir uma chave; entregue com a voz real.

4. Gere os clipes

"$PVS_HOME/bin/pvs-py" "$S/tts.py" <video_dir>

Para cada linha, ele respella as palavras da marca apenas para o TTS, mantém a tomada intacta em audio/raw/ (a tomada anterior vai para audio/raw/prev/), corta silêncio, reamostra para 48 kHz mono, aplica o tratamento do papel, normaliza para voice.clip_lufs (ffmpeg loudnorm, duas passadas; picos abaixo de -1.5 dBTP), desvanece ambas as bordas e mescla a entrada do clipe em audio/timings.json.

Por que cada etapa de processamento existe:

  • Tomadas brutas são sempre arquivadas e sempre a fonte. Um cliente anterior normalizou a partir de um arquivo bruto desatualizado após um rerender completo; aqui um clipe é sempre reconstruído a partir da tomada que o produziu.
  • A cauda é cortada no máximo 0,6 s após a última palavra, com um fade. Uma tomada TTS pode terminar com um clique ou o início de outra frase; um desses cliques foi enviado como um "corte estranho" no áudio.
  • Todos os clipes no mesmo volume. Uma voz de personagem saiu 6 dB mais alta que a do narrador antes da normalização.
  • Linhas inalteradas são puladas (hash do texto, voz e configurações em audio/raw/cache.json), então uma execução completa após editar uma linha chama o provedor uma vez. Se apenas clip_lufs ou o processamento mudaram, os clipes são reconstruídos a partir das tomadas arquivadas gratuitamente. --force pede uma nova tomada de qualquer forma.

A chave é lida pelo script do ambiente ou PVS_HOME/.env e nunca é impressa. Nunca leia .env você mesmo e nunca peça a chave no chat: se estiver faltando, diga ao usuário para adicionar a linha ao .env ele mesmo, ou mude para say.

Execute pronounce_check.py após qualquer nova tomada. Ele transcreve cada clipe sem acionar o ASR, sinaliza palavras da marca e do elenco que não foram reconhecidas, nomes legados que foram ouvidos e vogais que se desviaram (seção 5). Uma sinalização significa ouvir, não regenerar: ASRs ouvem mal palavras de marca que foram ditas corretamente.

5. Pronúncia

O roteiro e a tela mantêm a grafia real. product.pronounce muda apenas o que é enviado ao TTS, e tts.py mapeia os timings de volta, então timings.json contém a palavra na tela em w e a respelling em say ({"w": "Acme", "say": "AK-mee", ...}). Âncoras no build.py usam a palavra na tela.

product:
  pronounce:
    Acme: AK-mee                                    # respelling simples
    Acme Tasks: {say: AK-mee Tasks, vowel: ae, confusable: ey}   # com verificação de primeira vogal

Quando um revisor diz que o nome soa errado, tente três ou quatro respellings em uma linha, meça-as com a verificação de vogal, mantenha a que passar, depois verifique todas as outras linhas que têm a palavra: provedores variam por tomada. Detalhes e a tabela de vogais: references/casting-and-pronunciation.md.

6. Tomadas

  • No máximo duas tomadas por linha, a menos que o usuário diga o contrário; as cotas do provedor geralmente são compartilhadas em uma equipe. Diga quantos caracteres uma execução completa custará antes de executá-la.
  • Regere apenas a linha que precisa: tts.py <video_dir> --only N7 --force.
  • Se a nova tomada for pior, --only N7 --restore a troca de volta com seus timings.
  • Para uma nota de tom ("muito hype", "soa como meia frase"), faça duas ou três variantes como variantes de papel ou mudanças de velocidade, e deixe o revisor compará-las no contexto com a linha anterior.
  • Alterando uma linha, em ordem: copie os arquivos de versão, edite a linha, check_script.py, tts.py --only <id>, pronounce_check.py --only <id>, então o compositor reconstrói; tudo depois desse clipe se move sozinho.

7. Efeitos sonoros

Use apenas sons gravados, da biblioteca que acompanha o HyperFrames (make_sfx.py --list). Digitação sintetizada soou "como um canudo, não um teclado" e um whoosh sintetizado como "ruído branco" na revisão, então whooshes e risers são recusados pelo script, e nada vai abaixo da narração como música a menos que o briefing peça. A produção de onde estas skills vêm foi enviada sem trilha musical e sem ducking, e ninguém sentiu falta.

  • Digitação: typing_track(text, start, cps) constrói uma faixa a partir de teclas individuais extraídas de uma gravação real, com um toque mais forte nos espaços e um ritmo com semente, então é determinística e o mesmo texto sempre soa igual. Faça durar exatamente o tempo da batida que mostra o texto (dur=), e deixe as palavras digitadas coincidirem com as faladas.
  • Cliques e pops: library_sfx("click", start) no quadro em que o cursor pressiona.
  • audio/sfx/CREDITS.md lista cada arquivo da biblioteca usado e carrega a licença da biblioteca.
  • Níveis sugeridos: narração 1.0, personagens 1.0, cliques 0.35 (0.22 em um arrasto solto), digitação 0.45, pops 0.12 a 0.3. Dois clipes na mesma faixa de áudio nunca devem se sobrepor: inicie um clipe pelo menos 0,02 s após o término do anterior, ou mova-o para outra faixa.

build.py importa as funções; make_sfx.py <video_dir> com um audio/sfx.tsv pré-constrói os mesmos arquivos a partir da linha de comando (formato no docstring do script).

8. Entrega ao compositor

Entregue, sob <video_dir>/audio/: lines.tsv, clips/<id>.wav, timings.json, e sfx/ com CREDITS.md. Diga ao compositor a que palavras cada batida deve ancorar (o substantivo que o cursor toca, a palavra em que a digitação chega) e as esperas da tabela de momentos. Nunca edite timings.json manualmente: ele é regenerado a partir dos clipes, e uma edição manual é perdida na próxima execução.

Relate ao usuário: as linhas vocalizadas, a duração de cada clipe, quaisquer sinalizações de pronúncia e o que você ouviu, as vozes usadas (com o padrão recomendado para o que ainda estiver em aberto) e os caracteres do provedor gastos.

Individual skills in this repo

This repo contains 14 individual skills — each has its own dedicated page.

josueh04/product-video-skills

Extract, once per product, everything every video of it reuses and write it to kit/ and product.yaml (design tokens, font subsets as woff2, icon subsets as SVG from the product's own icon packages, logos in light, dark and app-tile variants from the repo, a fictional cast proposed once for veto and then frozen, the canonical-names map, pronunciations, banned terms and the read-only tool list). Use it when a product is set up or its kit is missing or incomplete, when a video needs an icon, font or logo that is not in kit/ yet, when someone asks for demo names, fake customers, phone numbers or emails, when a brand word is mispronounced or an old product name shows up, and when checking that demo data is fictional.

josueh04/product-video-skills

Interview the user about a product, then create products/<slug>/ with its own git history, a filled product.yaml and linked skills, fetch its sources and build its kit. Run only when the user types /product-new.

josueh04/product-video-skills

Back every sentence of a video's narration (audio/lines.tsv) and every screen it shows with a citation into the pinned source code (role/path:line@sha) or a docs URL, mark what is visible in the UI versus backend-only, flag restricted or unreleased features, and cut or rewrite anything unbacked; writes the video's TRUTH.md and checks it with truth_check.py. Use it whenever a script or narration is drafted or edited, before voice is generated, before a build, when someone asks "can we say this?", "is this true?", "does the product really do X?", when a reviewer asks for a feature or a claim the product may not support, and when a source document (pitch deck, PRD, marketing page) makes claims the video wants to repeat.

josueh04/product-video-skills

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

josueh04/product-video-skills

The animation rules that keep HyperFrames' parallel render workers from dropping, flashing or flickering elements, plus a static lint (lint_motion.py) that finds the violations in a video's template before it costs a render. Use it whenever you write or edit GSAP tweens, timelines, cursors, camera moves, typing, scrolls or pop-ups in a HyperFrames composition or a video's src/template.tpl, whenever a render shows flicker, stutter, an element that vanishes on some frames, a title that flashes, or a "WORKER PATTERN" line from scan_render.py or qa.py, and whenever the preview looks right but the MP4 does not. Also use it to review someone else's timeline code before rendering.

josueh04/product-video-skills

Pin a product's source code (read-only exports in sources/ plus sources.lock), confirm that the pinned commit is what runs in production, and map every screen of a video brief to its route, components, i18n strings and state, written to the video's SOURCES.md. Use it whenever a video needs to know where a screen lives in the code, when sources/ is missing or stale, before ui-spec-from-code or product-truth start on a video, after the product's frontend changed ("what changed", "which videos are affected", "refresh the sources", "is this checkout current", "which commit is in prod"), and when there is no code and you need an inventory of the no-code references (recordings, recovered captures, docs) a screen can be rebuilt from.

josueh04/product-video-skills

Compose a narrated product demo in HyperFrames: the stage (the product UI rebuilt at its real viewport and scaled to 1080p, camera, rack focus with veil, chapter titles, cursor and clicks, typing, streaming text, pop-ups, toasts, scrolls, end screen and lockup) and the build.py that anchors every beat to a word of the narration. Use it whenever you write or edit a video's video/build.py, src/template.tpl or src/app.css, place a beat on a word, add a chapter, a click, a pop-up or a push-in, frame a screen, build the end screen or lockup, snapshot setup beats, or render a draft or delivery MP4 of a product video in this workbench. Also use it when someone says "the cursor is off", "too zoomed in", "too fast", "it feels chaotic", "the title flashes", "sync the UI to the voice", or asks for a walkthrough, demo or pitch video of a UI.

josueh04/product-video-skills

Gather pixel references for UI that the code cannot show, or to check a rebuild against the real thing, using frames and timed OCR text from screen recordings, captures recovered from past Claude Code session transcripts, a local instance of the app built like production, and web research for third-party apps, plus side-by-side parity images and contact sheets. Use it whenever someone hands over a screen recording (.mov or .mp4) of the product, when a screen has no usable source code (a stale checkout, another company's UI such as a sign-in page, calendar or CRM, runtime output from a backend not in the repos), when asked "what does it really look like", "match the recording", "how long does that animation take in the app", "compare our render to the real app", or when screenshots from an earlier session might already exist. Never uses the reviewer's personal browser.

josueh04/product-video-skills

Turn a product's real frontend code into 1:1 rebuild specs for a video, one read-only subagent per screen, each returning static HTML, CSS with every variable resolved to its literal value and cited (role/path:line@sha), every state, transitions with exact durations and easings, icons from the code's own icon sets, and the exact i18n strings; plus resolve_tokens.py to write the product's design tokens to kit/tokens.css. Use it whenever a screen of the product has to appear in a video, when writing or fixing video/src/app.css or the template markup, when someone asks for exact sizes, colors, fonts, paddings, animations or icons of a screen, when a rebuilt screen "looks off" next to the real app, and when the design tokens or theme of a product need extracting. Framework adapters cover Angular with PrimeNG (proven), React, Vue, Tailwind and plain HTML (unproven).

josueh04/product-video-skills

Say where this session stands in the Product Video Skills workbench (setup state, which product and video the current folder belongs to, the stage of every video) and the exact next command to type. Also answers "how do I..." questions about the workbench from its docs.

josueh04/product-video-skills

Coordinate the build of one or more signed videos of the current product with subagents (source recon, product truth, UI specs, voice, one builder per video), re-run QA itself, then deliver. A light coordinator that never builds itself. Run only when the user types /video-build.

josueh04/product-video-skills

Start a new video of the current product - create videos/<video>/, write BRIEF.md, the feature coverage matrix (COVERAGE.md) and the claims sheet (CLAIMS.md), propose chapters, then stop for the reviewer's sign-off. Never builds. Run only when the user types /video-new.

josueh04/product-video-skills

Turn a batch of reviewer feedback on the product's videos into one table per video, fix every video that got notes in parallel (one subagent each) while keeping approved parts, re-run QA and parity, bump versions and deliver. Run only when the user types /video-review.

josueh04/product-video-skills

Check this machine and install the pinned video toolchain of the Product Video Skills workbench (HyperFrames CLI, its rendering Chrome and its agent skills from the same release, the Python environment, the speech model for QA), then run the self-check. Safe to run again. `/video-setup check` only reports.

Habilidades Relacionadas