Communitygithub.com

josueh04/product-video-skills

Verifique um vídeo de produto renderizado antes de qualquer outra pessoa vê-lo: flicker de padrão de worker, quadros pretos, loudness e pico verdadeiro, clipping, cliques nas bordas dos clipes, narração sobreposta, fala para texto contra o roteiro, termos proibidos e nomes legados, zoom de câmera, folhas de contato, tiras nas transições e paridade contra a versão aprovada; em seguida, escreva qa/REPORT.json, a única coisa que deliver.py aceita. Use-o após cada render do HyperFrames, sempre que alguém perguntar "o render está limpo", "faça QA disso", "verifique o vídeo", "verifique o áudio", "por que está piscando?", "tem um clique", "compare v3 com v2", "a parte aprovada mudou?", ou antes de mostrar, enviar, carregar ou entregar qualquer MP4, mesmo quando a solicitação não diz QA. Use-o também para fazer triagem de um defeito que um revisor relatou em um render.

O que é product-video-skills?

Esta skill automatiza a garantia de qualidade (QA) de vídeos de produtos renderizados, indo muito além de uma verificação superficial. Seu objetivo é garantir que um vídeo está 'limpo' e pronto para entrega, detectando problemas sutis como flicker (cintilação) em padrões de workers de renderização, quadros pretos indesejados, clipes de áudio com clipping, cliques impulsivos nas bordas, narrações sobrepostas e diferenças entre o que foi dito e o roteiro (ASR). Ela também verifica a presença de termos proibidos e nomes de produtos desatualizados, compara a paridade de quadros com uma versão aprovada e gera relatórios detalhados (REPORT.json, REPORT.md), folhas de contato e tiras de vídeo para inspeção visual. A skill é projetada para ser usada após cada renderização no HyperFrames e suporta uma trilha completa que vai desde a varredura rápida pós-renderização até a entrega final, garantindo que apenas vídeos que passaram em todas as verificações possam ser entregues. Sua utilidade principal é detectar defeitos que escapariam de uma revisão manual, como flashes de 0,3 segundos ou problemas de áudio em canais específicos, economizando tempo e evitando retrabalho.

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

Perguntar na sua IA favorita

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

Documentação

QA do Render

Um render não está pronto quando o renderizador termina. Ele está pronto quando as evidências dizem que está limpo: o relatório automático, cada folha de contato examinada, as tiras em cada transição examinadas e as bordas da narração ouvidas. Na produção de onde essas habilidades vêm, subagentes relataram renders como limpos que tinham um flash de UI de 0,3 s antes do travamento, um modal com clipping e um título que desaparecia a cada três quadros. Os scripts e as tiras encontraram todos os três.

Os scripts ficam ao lado deste arquivo. Resolva a bancada de trabalho uma vez:

PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"
S="$PVS_HOME/skills/render-qa/scripts"

Mantenha o interpretador e a pasta de scripts em variáveis separadas e coloque ambos entre aspas ("$PY" "$S/qa.py"): uma variável que contém um comando mais um caminho não é dividida pelo zsh e quebra no bash assim que um caminho tem espaço.

<video_dir> é products/<slug>/videos/<video>/ (contém BRIEF.md, audio/, video/).

A trilha, em ordem

  1. Antes de renderizar. Execute o lint de movimento (skill seek-safe-motion), hyperframes check e instantâneos de cada batida de configuração. Apenas check não é suficiente: uma vez ele aprovou um vídeo no qual elementos móveis ficaram invisíveis por três de seus quatro trechos. As etapas de pré-render estão em references/checklist.md.
  2. Logo após o render, a varredura rápida (alguns segundos): "$PY" "$S/scan_render.py" <mp4>. Uma linha WORKER PATTERN significa um bug de segurança de busca: pare e corrija a linha do tempo (veja seek-safe-motion), não execute o resto ainda.
  3. O relatório completo: "$PY" "$S/qa.py" <video_dir> <mp4>. Ele executa todas as verificações automáticas, escreve qa/REPORT.json e qa/REPORT.md, folhas de contato em qa/sheets/, tiras em qa/strips/ (cada execução de outlier e os últimos 5 s) e a transcrição em qa/asr.txt. Cerca de 15 s para um vídeo de 2 a 3 minutos a 60 fps em um Mac recente, incluindo fala para texto. Leia REPORT.md de cima a baixo, incluindo os avisos e cada diff de ASR.
  4. A passada a olho. O relatório termina com o que os scripts não podem ver. Faça tudo:
    • Olhe cada folha de contato, não uma amostra.
    • Faça tiras a 5 a 6 fps em torno de cada abertura e fechamento de modal, rolagem, movimento de câmera, mudança de capítulo, batida que mudou nesta versão e a passagem da tela final para o travamento: "$PY" "$S/strips.py" <mp4> <video_dir>/qa/strips modal:21.0:23.4:8 lockup:57:60. Uma folha de 1 fps amostra um quadro por segundo; um flash de 0,3 s cabe entre duas amostras.
    • Execute "$PY" "$S/edges.py" <mp4> <video_dir> e ouça cada borda que ele marcar.
    • Se esta versão edita uma aprovada, prove que o resto não mudou: "$PY" "$S/parity.py" <approved.mp4> <new.mp4> --skip 41.0:48.5. Como ler folhas, tiras e saída de paridade: references/reading-sheets-and-strips.md.
  5. Faça triagem de cada falha e aviso com references/triage.md: ele lista os defeitos reais que essas verificações encontraram e os falsos positivos, com como cada um foi diferenciado. Corrija a causa na origem (template, build, lines.tsv, áudio), reconstrua, re-renderize e execute a trilha novamente a partir da etapa 2. Nunca edite index.html manualmente: o build o regenera.
  6. A entrega não é da alçada desta skill. deliver.py é executado apenas quando o usuário, ou uma skill invocada pelo usuário que o usuário iniciou (/video-build, /video-review), pedir para entregar. Ele recusa a menos que o relatório tenha passado, não seja um rascunho e corresponda ao MP4 byte a byte.

O que as verificações medem

VerificaçãoFalha quandoPor que esse limite
size, fpstamanho difere de video.size; fps só avisaUm tamanho errado é um render quebrado; um fps diferente pode ser intencional (30 vs 60)
worker_patternuma sequência de 4 ou mais quadros outlier todos em um índice de quadro mod 3HyperFrames renderiza com 3 workers intercalados; um perdendo estado atinge cada terceiro quadro
outliersnunca (aviso)Rolagens em velocidade máxima, racks de desfoque e retornos de câmera produzem outliers isolados também; olhe cada tira
black_framesluma média abaixo de 3 fora do primeiro 1 s e dos últimos 2 sFades de e para preto são intencionais; preto no meio do vídeo é um bug
voice_overlapduas palavras faladas de clipes de voz se sobrepõem por mais de 20 msMedido nos timings das palavras, não nos limites dos clipes: caudas silenciosas sobrepostas é aceitável
loudnessloudness integrada mais de 1 LU de voice.mix_lufsFinais entregues medidos de -16,8 a -15,3 LUFS para um alvo de -16
true_peakacima de -1,0 dBFSMargem para os codecs com perda das plataformas de upload
clippingqualquer amostra a 0,995 ou mais em um canal realMedido por canal, não em um downmix, para que um lado estourado não seja escondido
clicks_outside_clipsum clique impulsivo fora de todo clipe de áudioDentro de um SFX é esperado; dentro da voz é quase sempre uma consoante
abrupt_edgesnunca (aviso)Um som terminando em 5 ms fora de um SFX é geralmente um clipe mal cortado; ouça
asrcorrespondência de palavras abaixo de 0,93, ou puladoFinais medidos de 0,953 a 0,988; roteiro comparado na ordem de reprodução, não na ordem do arquivo
banned_terms_*um termo proibido, frase nunca-diga ou nome legado ouvido, visível em index.html, ou em lines.tsvDe product.yaml; a UI ao vivo ainda pode mostrar um nome antigo, o vídeo não deve
camera_zoomnunca (aviso) acima de video.max_zoomTelas cheias em cerca de 2x foram rejeitadas duas vezes como "super ampliado"; uma tela ampliada tolera mais
motion_linto lint de seek-safe-motion relata um erroPega os bugs da linha do tempo antes que custem um render

--no-asr faz o relatório falhar de propósito: uma narração que se desviou do roteiro é exatamente o que um revisor ouve primeiro. A fala para texto usa whisper small.en para inglês e o modelo multilíngue small para qualquer outro lang (baixa uma vez se estiver faltando).

O contrato do relatório

qa/REPORT.json segue docs/contracts.md: mp4 (relativo à pasta do vídeo), sha256, created, draft, checks (name, passed, detail e level: warn para avisos), passed. Ele também carrega draft_reason, probe, artifacts e os diffs do ASR. draft é verdadeiro quando qualquer assinatura em BRIEF.md está vazia ou video/index.html carrega <meta name="pvs-draft" content="1"> (escrito por build.py --draft). Um rascunho pode passar em todas as verificações e ainda assim nunca ser entregue: cobertura não assinada é como um vídeo acaba perdendo o recurso com o qual o revisor se importava.

Entregando (apenas quando solicitado)

"$PY" "$S/deliver.py" <video_dir> <mp4> [--archive-previous] [--dry-run]

Ele copia para <product_dir>/deliveries/ como review.naming (padrão {product} {video} v{version}.mp4, versão de BRIEF.md) com um clone APFS quando possível, verifica a cópia byte a byte e escreve <mesmo nome>.BRIEF.md ao lado. Ele nunca sobrescreve: os mesmos bytes novamente é um no-op, bytes diferentes sob um nome já entregue incrementam a versão no nome do arquivo (então incrementa BRIEF.md para corresponder). --archive-previous move versões mais antigas do vídeo para deliveries/previous/ para que a pasta do revisor contenha apenas a mais recente. Após entregar, informe ao revisor em uma tabela: vídeo, versão, duração, o que mudou e no máximo três decisões em aberto, cada uma com um padrão recomendado. Qualquer cópia já enviada para algum lugar agora está obsoleta: diga isso.

Regras que vieram de incidentes

  • Reexecute a evidência você mesmo. Quando um subagente diz que um render está limpo, leia seu REPORT.md, abra as folhas e tiras, e verifique se o sha256 corresponde ao arquivo que você vai entregar. "Limpo" de um agente é uma afirmação, o relatório é a evidência.
  • Cada versão tem seu próprio nome de arquivo em renders/; nunca exclua uma mais antiga. Sobrescreva apenas uma versão que o revisor ainda não viu, dentro de um ciclo de correção.
  • Nunca mate processos que você não iniciou (Chrome, ffmpeg, node): outros agentes renderizam na mesma máquina.
  • Instantâneos sem a API de visão: passe --describe false para hyperframes snapshot, para que nenhum quadro de um produto não lançado saia da máquina.
  • Diffs de ASR apenas ortográficos são aceitáveis (uma palavra de marca ouvida como duas palavras, um tempo escrito por extenso). Leia cada diff antes de decidir; um diff de várias palavras é um corte ou uma linha corrompida.

Scripts

ScriptUso
qa.py <video_dir> <mp4> [--out DIR] [--no-asr] [--strip nome:t0:t1[:fps]]O relatório completo; sai com 1 quando não passa
scan_render.py <mp4> [--json]Varredura rápida de flicker, preto e loudness; sai com 1 em padrão de worker ou preto no meio do vídeo
qa_full.py <video_dir> <mp4> [--out DIR] [--no-asr]Apenas as medições, como REPORT.txt
sheets.py <mp4> <outdir> [--fps 1]Folhas de contato de 1 fps, 4x4
strips.py <mp4> <outdir> nome:t0:t1[:fps] ...Tiras rotuladas em torno de transições (padrão 6 fps)
edges.py <mp4> <video_dir ou index.html>Nível antes e depois de cada clipe de narração
parity.py <old> <new> [--end T] [--skip A:B] [--threshold 1.0] [--audio]Paridade de quadros; sai com 1 acima do limite
banned_terms.py [--product DIR] [--text T] [ARQUIVO ou DIR ...]Termos proibidos, frases nunca-diga e nomes legados; sai com 1 em acertos
deliver.py <video_dir> <mp4> [--archive-previous] [--dry-run]A trilha de entrega

banned_terms.find_banned(text, product) retorna [(termo, tipo)] para outras skills reutilizarem.

Referências

  • references/checklist.md: a trilha inteira como caixas para marcar, desde o build até a mensagem do revisor. Leia antes do primeiro render de um vídeo e antes de qualquer entrega.
  • references/reading-sheets-and-strips.md: o que procurar em folhas, tiras, recortes, paridade e as verificações numéricas (contagens de pixels brilhantes, caixas de diff). Leia ao fazer a etapa 4.
  • references/triage.md: cada falha que este QA produziu, real ou falsa, e como foi diferenciada e corrigida. Leia assim que qualquer verificação falhar ou avisar.

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

Write a product video's narration and turn it into voice clips with word timings, pronunciation fixes, sound effects and even loudness. The script becomes a table of moments and then audio/lines.tsv (one clip per sentence, with role and speed columns); tts.py voices it with ElevenLabs or the free macOS say voice, maps brand respellings back to the on-screen spelling, normalizes every clip and writes audio/timings.json for the composer; make_sfx.py builds typing tracks from real keystrokes and places recorded click and pop sounds. Use it whenever a video needs a script, narration, voice-over, lines.tsv, timings.json, TTS, a new take, a voice or casting choice, a pronunciation fix ("it says the name wrong"), a changed sentence, a tone note ("too hype", "sounds cut off"), audio levels, a click at the end of a clip, typing or click sounds, or when the build stage asks for the voice. Also use it for silent loops, which still need a moment table and SFX.

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