QA de Render
Un render no está terminado cuando el renderizador sale. Está terminado cuando la evidencia dice que está limpio: el informe automático, cada hoja de contacto revisada, las tiras en cada transición revisadas y los bordes de la narración escuchados. En la producción de la que provienen estas habilidades, los subagentes reportaron renders como limpios que tenían un destello de UI de 0.3 s antes del bloqueo, un modal recortado y un título que desaparecía en cada tercer fotograma. Los scripts y las tiras encontraron los tres.
Los scripts viven junto a este archivo. Resuelve el espacio de trabajo una vez:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"
S="$PVS_HOME/skills/render-qa/scripts"
Mantén el intérprete y la carpeta de scripts en variables separadas y entrecomilla ambas ("$PY" "$S/qa.py"): una variable que contiene un comando más una ruta no se divide en zsh y se rompe en bash tan pronto como una ruta tiene un espacio.
<video_dir> es products/<slug>/videos/<video>/ (contiene BRIEF.md, audio/, video/).
La puerta, en orden
- Antes de renderizar. Ejecuta el lint de movimiento (habilidad
seek-safe-motion),hyperframes checky capturas de pantalla de cada pulso de configuración.checksolo no es suficiente: una vez aprobó un video en el que los elementos en movimiento eran invisibles durante tres de sus cuatro tramos. Los pasos previos al render están enreferences/checklist.md. - Justo después del render, el escaneo rápido (unos segundos):
"$PY" "$S/scan_render.py" <mp4>. Una líneaWORKER PATTERNsignifica un error de seguridad de búsqueda: detente y corrige la línea de tiempo (consultaseek-safe-motion), no ejecutes el resto todavía. - El informe completo:
"$PY" "$S/qa.py" <video_dir> <mp4>. Ejecuta todas las comprobaciones automáticas, escribeqa/REPORT.jsonyqa/REPORT.md, hojas de contacto enqa/sheets/, tiras enqa/strips/(cada ejecución atípica y los últimos 5 s), y la transcripción enqa/asr.txt. Aproximadamente 15 s para un video de 2 a 3 minutos a 60 fps en un Mac reciente, incluido el reconocimiento de voz. LeeREPORT.mdde principio a fin, incluyendo las advertencias y cada diff de ASR. - La revisión visual. El informe termina con lo que los scripts no pueden ver. Haz todo esto:
- Mira cada hoja de contacto, no una muestra.
- Crea tiras a 5 o 6 fps alrededor de cada apertura y cierre de modal, desplazamiento, movimiento de cámara, cambio de capítulo, pulso que cambió en esta versión, y la transición de pantalla final a bloqueo:
"$PY" "$S/strips.py" <mp4> <video_dir>/qa/strips modal:21.0:23.4:8 lockup:57:60. Una hoja a 1 fps muestra un fotograma por segundo; un destello de 0.3 s cabe entre dos muestras. - Ejecuta
"$PY" "$S/edges.py" <mp4> <video_dir>y escucha cada borde que marque. - Si esta versión edita una aprobada, demuestra que el resto no se movió:
"$PY" "$S/parity.py" <approved.mp4> <new.mp4> --skip 41.0:48.5. Cómo leer hojas, tiras y salida de paridad:references/reading-sheets-and-strips.md.
- Diagnostica cada fallo y advertencia con
references/triage.md: enumera los defectos reales que estas comprobaciones encontraron y los falsos positivos, con cómo se distinguieron. Corrige la causa en la fuente (plantilla, compilación, lines.tsv, audio), reconstruye, vuelve a renderizar y ejecuta la puerta de nuevo desde el paso 2. Nunca editesindex.htmla mano: la compilación lo regenera. - La entrega no es decisión de esta habilidad.
deliver.pyse ejecuta solo cuando el usuario, o una habilidad invocada por el usuario que el usuario inició (/video-build,/video-review), solicita entregar. Se niega a menos que el informe haya pasado, no sea un borrador y coincida byte por byte con el MP4.
Lo que miden las comprobaciones
| Comprobación | Fallo cuando | Por qué este umbral |
|---|---|---|
size, fps | el tamaño difiere de video.size; fps solo advierte | Un tamaño incorrecto es un render roto; un fps diferente puede ser intencional (30 vs 60) |
worker_pattern | una ejecución de 4 o más fotogramas atípicos, todos en un mismo índice de fotograma módulo 3 | HyperFrames renderiza con 3 workers entrelazados; uno que pierde estado afecta a cada tercer fotograma |
outliers | nunca (advertencia) | Los desplazamientos a máxima velocidad, los cambios de desenfoque y los retornos de cámara crean fotogramas atípicos aislados; mira cada tira |
black_frames | luminancia media menor de 3 fuera del primer 1 s y último 2 s | Los fundidos desde y hacia negro son intencionales; negro en medio del video es un error |
voice_overlap | dos clips de voz tienen palabras habladas que se superponen por más de 20 ms | Medido en tiempos de palabra, no en límites de clip: las colas silenciosas superpuestas están bien |
loudness | sonoridad integrada a más de 1 LU de voice.mix_lufs | Los finales entregados midieron entre -16.8 y -15.3 LUFS para un objetivo de -16 |
true_peak | por encima de -1.0 dBFS | Margen de seguridad para los codificadores con pérdida de las plataformas de subida |
clipping | cualquier muestra a 0.995 o más en un canal real | Medido por canal, no en una mezcla descendente, para que un lado recortado no quede oculto |
clicks_outside_clips | un clic impulsivo fuera de cualquier clip de audio | Dentro de un SFX es esperado; dentro de la voz es casi siempre una consonante |
abrupt_edges | nunca (advertencia) | Un sonido que termina en 5 ms fuera de un SFX suele ser un clip mal recortado; escucha |
asr | coincidencia de palabras por debajo de 0.93, o saltada | Los finales midieron entre 0.953 y 0.988; el guion se compara en orden de reproducción, no en orden de archivo |
banned_terms_* | un término prohibido, frase jamás dicha o nombre heredado escuchado, visible en index.html o en lines.tsv | Desde product.yaml; la UI en vivo puede mostrar aún un nombre antiguo, el video no debe |
camera_zoom | nunca (advertencia) por encima de video.max_zoom | Las capturas de pantalla a aproximadamente 2x fueron rechazadas dos veces como "super ampliado"; un lienzo alejado tolera más |
motion_lint | el lint de movimiento seguro de búsqueda reporta un error | Detecta los errores de línea de tiempo antes de que cuesten un render |
--no-asr hace que el informe falle a propósito: una narración que se desvió del guion es exactamente lo que un revisor escucha primero. El reconocimiento de voz usa whisper small.en para inglés y el modelo multilingüe small para cualquier otro lang (se descarga una vez si no existe).
El contrato del informe
qa/REPORT.json sigue docs/contracts.md: mp4 (relativo a la carpeta de video), sha256, created, draft, checks (name, passed, detail y level: warn para advertencias), passed. También incluye draft_reason, probe, artifacts y los diffs de ASR. draft es verdadero cuando cualquiera de las firmas en BRIEF.md está vacía o video/index.html contiene <meta name="pvs-draft" content="1"> (escrito por build.py --draft). Un borrador puede pasar todas las comprobaciones y nunca ser entregado: la cobertura sin firmar es cómo un video termina sin la característica que importaba al revisor.
Entregar (solo cuando se solicite)
"$PY" "$S/deliver.py" <video_dir> <mp4> [--archive-previous] [--dry-run]
Copia a <product_dir>/deliveries/ como review.naming (por defecto {product} {video} v{version}.mp4, versión desde BRIEF.md) con un clon APFS cuando sea posible, verifica la copia byte por byte y escribe <mismo nombre>.BRIEF.md junto a él. Nunca sobrescribe: los mismos bytes de nuevo no hacen nada, bytes diferentes con un nombre ya entregado incrementan la versión en el nombre del archivo (luego actualiza BRIEF.md para que coincida). --archive-previous mueve versiones anteriores del video a deliveries/previous/ para que la carpeta del revisor contenga solo la última. Después de entregar, informa al revisor en una tabla: video, versión, duración, qué cambió y como máximo tres decisiones abiertas, cada una con un valor predeterminado recomendado. Cualquier copia ya subida a algún lugar ahora está desactualizada: dilo.
Reglas que provienen de incidentes
- Vuelve a ejecutar la evidencia tú mismo. Cuando un subagente dice que un render está limpio, lee su
REPORT.md, abre las hojas y las tiras, y verifica que el sha256 coincida con el archivo que entregarás. "Limpio" de un agente es una afirmación, el informe es evidencia. - Cada versión recibe su propio nombre de archivo en
renders/; nunca elimines una anterior. Sobrescribe solo una versión que el revisor aún no ha visto, dentro de un ciclo de corrección. - Nunca mates procesos que no iniciaste (Chrome, ffmpeg, node): otros agentes renderizan en la misma máquina.
- Capturas de pantalla sin la API de visión: pasa
--describe falseahyperframes snapshot, para que ningún fotograma de un producto no lanzado salga de la máquina. - Los diffs de ASR solo ortográficos están bien (una palabra de marca escuchada como dos palabras, una hora escrita en palabras). Lee cada diff antes de decidir; un diff de varias palabras es un corte o una línea distorsionada.
Scripts
| Script | Uso |
|---|---|
qa.py <video_dir> <mp4> [--out DIR] [--no-asr] [--strip name:t0:t1[:fps]] | El informe completo; sale con 1 si no pasa |
scan_render.py <mp4> [--json] | Escaneo rápido de parpadeo, negro y sonoridad; sale con 1 en patrón de worker o negro en medio del video |
qa_full.py <video_dir> <mp4> [--out DIR] [--no-asr] | Solo las mediciones, como REPORT.txt |
sheets.py <mp4> <outdir> [--fps 1] | Hojas de contacto a 1 fps, 4x4 |
strips.py <mp4> <outdir> name:t0:t1[:fps] ... | Tiras etiquetadas alrededor de transiciones (6 fps por defecto) |
edges.py <mp4> <video_dir or index.html> | Nivel antes y después de cada clip de narración |
parity.py <old> <new> [--end T] [--skip A:B] [--threshold 1.0] [--audio] | Paridad de fotogramas; sale con 1 por encima del umbral |
banned_terms.py [--product DIR] [--text T] [FILE or DIR ...] | Términos prohibidos, frases jamás dichas y nombres heredados; sale con 1 en coincidencias |
deliver.py <video_dir> <mp4> [--archive-previous] [--dry-run] | La puerta de entrega |
banned_terms.find_banned(text, product) devuelve [(term, kind)] para que otras habilidades lo reutilicen.
Referencias
references/checklist.md: toda la puerta como casillas para marcar, desde la compilación hasta el mensaje al revisor. Léelo antes del primer render de un video y antes de cualquier entrega.references/reading-sheets-and-strips.md: qué buscar en hojas, tiras, recortes, paridad y las comprobaciones numéricas (recuentos de píxeles brillantes, cuadros de diferencias). Léelo al hacer el paso 4.references/triage.md: cada fallo que este QA produjo, real o falso, y cómo se distinguió y corrigió. Léelo tan pronto como una comprobación falle o advierta.