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
- Antes de renderizar. Execute o lint de movimento (skill
seek-safe-motion),hyperframes checke instantâneos de cada batida de configuração. Apenaschecknã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 emreferences/checklist.md. - Logo após o render, a varredura rápida (alguns segundos):
"$PY" "$S/scan_render.py" <mp4>. Uma linhaWORKER PATTERNsignifica um bug de segurança de busca: pare e corrija a linha do tempo (vejaseek-safe-motion), não execute o resto ainda. - O relatório completo:
"$PY" "$S/qa.py" <video_dir> <mp4>. Ele executa todas as verificações automáticas, escreveqa/REPORT.jsoneqa/REPORT.md, folhas de contato emqa/sheets/, tiras emqa/strips/(cada execução de outlier e os últimos 5 s) e a transcrição emqa/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. LeiaREPORT.mdde cima a baixo, incluindo os avisos e cada diff de ASR. - 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.
- 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 editeindex.htmlmanualmente: o build o regenera. - 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ção | Falha quando | Por que esse limite |
|---|---|---|
size, fps | tamanho difere de video.size; fps só avisa | Um tamanho errado é um render quebrado; um fps diferente pode ser intencional (30 vs 60) |
worker_pattern | uma sequência de 4 ou mais quadros outlier todos em um índice de quadro mod 3 | HyperFrames renderiza com 3 workers intercalados; um perdendo estado atinge cada terceiro quadro |
outliers | nunca (aviso) | Rolagens em velocidade máxima, racks de desfoque e retornos de câmera produzem outliers isolados também; olhe cada tira |
black_frames | luma média abaixo de 3 fora do primeiro 1 s e dos últimos 2 s | Fades de e para preto são intencionais; preto no meio do vídeo é um bug |
voice_overlap | duas palavras faladas de clipes de voz se sobrepõem por mais de 20 ms | Medido nos timings das palavras, não nos limites dos clipes: caudas silenciosas sobrepostas é aceitável |
loudness | loudness integrada mais de 1 LU de voice.mix_lufs | Finais entregues medidos de -16,8 a -15,3 LUFS para um alvo de -16 |
true_peak | acima de -1,0 dBFS | Margem para os codecs com perda das plataformas de upload |
clipping | qualquer amostra a 0,995 ou mais em um canal real | Medido por canal, não em um downmix, para que um lado estourado não seja escondido |
clicks_outside_clips | um clique impulsivo fora de todo clipe de áudio | Dentro de um SFX é esperado; dentro da voz é quase sempre uma consoante |
abrupt_edges | nunca (aviso) | Um som terminando em 5 ms fora de um SFX é geralmente um clipe mal cortado; ouça |
asr | correspondência de palavras abaixo de 0,93, ou pulado | Finais 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.tsv | De product.yaml; a UI ao vivo ainda pode mostrar um nome antigo, o vídeo não deve |
camera_zoom | nunca (aviso) acima de video.max_zoom | Telas cheias em cerca de 2x foram rejeitadas duas vezes como "super ampliado"; uma tela ampliada tolera mais |
motion_lint | o lint de seek-safe-motion relata um erro | Pega 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 falseparahyperframes 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
| Script | Uso |
|---|---|
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.