Render QA
렌더링이 완료된 것은 렌더러가 종료되었을 때가 아닙니다. 증거가 깨끗하다고 말할 때 완료된 것입니다: 자동 보고서, 모든 접촉 시트 확인, 모든 전환 지점의 스트립 확인, 내레이션 가장자리 청취. 이 스킬이 비롯된 프로덕션에서 하위 에이전트들은 렌더링이 깨끗하다고 보고했지만, 실제로는 잠금 전 0.3초 UI 플래시, 클리핑된 모달, 매 세 번째 프레임마다 사라지는 제목이 있었습니다. 스크립트와 스트립이 이 세 가지를 모두 발견했습니다.
스크립트는 이 파일과 같은 위치에 있습니다. 워크벤치를 한 번 해석하세요:
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
PY="$PVS_HOME/bin/pvs-py"
S="$PVS_HOME/skills/render-qa/scripts"
인터프리터와 스크립트 폴더를 별도의 변수에 저장하고 둘 다 인용 부호로 감싸세요("$PY" "$S/qa.py"): 명령어와 경로를 하나의 변수에 담으면 zsh에서 분할되지 않고 bash에서 경로에 공백이 있을 경우 문제가 발생합니다.
<video_dir>은 products/<slug>/videos/<video>/입니다 (BRIEF.md, audio/, video/를 포함합니다).
게이트, 순서대로
- 렌더링 전. 모션 린트(
seek-safe-motion스킬),hyperframes check, 그리고 모든 설정 비트의 스냅샷을 실행합니다.check만으로는 충분하지 않습니다: 한 번은 움직이는 요소가 네 개의 구간 중 세 개에서 보이지 않는 비디오를 통과시킨 적이 있습니다. 렌더링 전 단계는references/checklist.md에 있습니다. - 렌더링 직후, 빠른 스캔(몇 초):
"$PY" "$S/scan_render.py" <mp4>.WORKER PATTERN라인은 시크-세이프티 버그를 의미합니다: 중지하고 타임라인을 수정하고(seek-safe-motion참조), 나머지를 실행하지 마세요. - 전체 보고서:
"$PY" "$S/qa.py" <video_dir> <mp4>. 모든 자동 검사를 실행하고,qa/REPORT.json및qa/REPORT.md를 작성하며, 접촉 시트는qa/sheets/에, 스트립은qa/strips/에(각 이상치 실행 및 마지막 5초), 그리고 대본은qa/asr.txt에 작성합니다. 최신 Mac에서 2~3분 60fps 비디오의 경우 약 15초가 소요되며, 음성-텍스트 변환 시간이 포함됩니다.REPORT.md를 처음부터 끝까지 읽고, 경고와 모든 ASR 차이점을 포함하세요. - 육안 검사. 보고서는 스크립트가 볼 수 없는 것으로 끝납니다. 모두 수행하세요:
- 모든 접촉 시트를 살펴보세요. 샘플이 아닙니다.
- 모든 모달 열림 및 닫힘, 스크롤, 카메라 이동, 챕터 변경, 이 버전에서 변경된 비트, 그리고 종료 화면에서 잠금 전환 주변에서 5~6fps로 스트립을 만드세요:
"$PY" "$S/strips.py" <mp4> <video_dir>/qa/strips modal:21.0:23.4:8 lockup:57:60. 1fps 시트는 초당 한 프레임을 샘플링합니다. 0.3초 플래시는 두 샘플 사이에 들어갑니다. "$PY" "$S/edges.py" <mp4> <video_dir>를 실행하고 표시된 모든 가장자리를 청취하세요.- 이 버전이 승인된 버전을 편집한 경우, 나머지 부분이 변경되지 않았음을 증명하세요:
"$PY" "$S/parity.py" <approved.mp4> <new.mp4> --skip 41.0:48.5. 시트, 스트립 및 패리티 출력을 읽는 방법:references/reading-sheets-and-strips.md.
- 분류 모든 실패와 경고는
references/triage.md를 사용하세요: 이 검사에서 발견된 실제 결함과 오탐지를 나열하고, 각각을 구별한 방법을 설명합니다. 원인을 소스(템플릿, 빌드, lines.tsv, 오디오)에서 수정하고, 재빌드, 재렌더링 후 2단계부터 게이트를 다시 실행하세요. 절대index.html을 수동으로 편집하지 마세요: 빌드가 다시 생성합니다. - 전달은 이 스킬의 호출 사항이 아닙니다.
deliver.py는 사용자 또는 사용자가 시작한 스킬(/video-build,/video-review)이 전달을 요청할 때만 실행됩니다. 보고서가 통과하지 않았거나, 초안이거나, MP4와 바이트 단위로 일치하지 않으면 거부합니다.
검사 항목 측정 기준
| 검사 | 실패 조건 | 이 임계값을 사용하는 이유 |
|---|---|---|
size, fps | 크기가 video.size와 다를 때; fps는 경고만 | 잘못된 크기는 깨진 렌더링; 다른 fps는 의도된 것일 수 있음(30 대 60) |
worker_pattern | 4개 이상의 이상치 프레임이 모두 동일한 프레임 인덱스 mod 3에 있을 때 | HyperFrames는 3개의 인터리브된 워커로 렌더링; 하나가 상태를 잃으면 매 세 번째 프레임에 영향 |
outliers | 절대 실패하지 않음(경고) | 최대 속도 스크롤, 블러 랙, 카메라 복귀로 인해 고립된 이상치가 발생할 수 있음; 각 스트립을 확인 |
black_frames | 처음 1초와 마지막 2초를 제외한 평균 휘도가 3 미만 | 검은색으로 페이드 인/아웃은 의도된 것; 비디오 중간의 검은색은 버그 |
voice_overlap | 두 음성 클립의 말한 단어가 20ms 이상 중첩 | 클립 경계가 아닌 단어 타이밍으로 측정: 침묵하는 꼬리가 중첩되는 것은 괜찮음 |
loudness | 통합 음량이 voice.mix_lufs에서 1 LU 이상 차이 | 전달된 최종본은 -16 목표에 대해 -16.8 ~ -15.3 LUFS로 측정됨 |
true_peak | -1.0 dBFS 초과 | 업로드 플랫폼의 손실 인코더를 위한 헤드룸 |
clipping | 실제 채널에서 0.995 이상의 샘플 | 다운믹스가 아닌 채널별로 측정하므로 한쪽 클리핑이 숨겨지지 않음 |
clicks_outside_clips | 모든 오디오 클립 외부에서 충동적인 클릭 | SFX 내부는 예상됨; 음성 내부는 거의 항상 자음 |
abrupt_edges | 절대 실패하지 않음(경고) | SFX 외부에서 5ms 이내에 끝나는 소리는 일반적으로 잘못 트리밍된 클립; 청취 필요 |
asr | 단어 일치도가 0.93 미만 또는 건너뜀 | 최종본은 0.953 ~ 0.988로 측정됨; 파일 순서가 아닌 재생 순서로 스크립트 비교 |
banned_terms_* | 금지 용어, 절대 사용하지 말아야 할 구문 또는 레거시 이름이 들리거나, index.html에 보이거나, lines.tsv에 있을 때 | product.yaml에서 가져옴; 라이브 UI에는 여전히 이전 이름이 표시될 수 있지만 비디오에는 없어야 함 |
camera_zoom | 절대 실패하지 않음(경고) video.max_zoom 초과 시 | 약 2배의 전체 페이지 화면이 "매우 확대됨"으로 두 번 거부됨; 축소된 캔버스는 더 많은 것을 허용함 |
motion_lint | seek-safe-motion 린트가 오류를 보고할 때 | 렌더링 비용이 발생하기 전에 타임라인 버그를 잡음 |
--no-asr는 보고서를 의도적으로 실패하게 만듭니다: 스크립트에서 벗어난 내레이션은 리뷰어가 가장 먼저 듣는 것입니다. 음성-텍스트 변환은 영어의 경우 whisper small.en을 사용하고, 다른 lang의 경우 다국어 small 모델을 사용합니다(없으면 한 번 다운로드).
보고서 계약
qa/REPORT.json은 docs/contracts.md를 따릅니다: mp4(비디오 폴더 기준 상대 경로), sha256, created, draft, checks (name, passed, detail, 경고의 경우 level: warn), passed. 또한 draft_reason, probe, artifacts 및 ASR 차이점을 포함합니다. draft는 BRIEF.md의 두 서명 중 하나가 비어 있거나 video/index.html에 <meta name="pvs-draft" content="1">이 포함된 경우 참입니다(build.py --draft에 의해 작성됨). 초안은 모든 검사를 통과할 수 있지만 절대 전달되지 않습니다: 서명되지 않은 범위는 비디오가 리뷰어가 신경 쓰는 기능을 놓치는 방식입니다.
전달 (요청 시에만)
"$PY" "$S/deliver.py" <video_dir> <mp4> [--archive-previous] [--dry-run]
<product_dir>/deliveries/에 review.naming(기본값 {product} {video} v{version}.mp4, 버전은 BRIEF.md에서 가져옴)으로 복사하고, 가능하면 APFS 클론을 사용하며, 복사본을 바이트 단위로 확인하고, 같은 이름의 .BRIEF.md 파일을 함께 작성합니다. 절대 덮어쓰지 않습니다: 동일한 바이트는 아무 작업도 하지 않으며, 전달된 이름 아래 다른 바이트는 파일 이름의 버전을 증가시킵니다(그런 다음 BRIEF.md도 일치하도록 증가). --archive-previous는 이전 버전의 비디오를 deliveries/previous/로 이동하여 리뷰어의 폴더에 최신 버전만 남깁니다. 전달 후, 리뷰어에게 하나의 테이블로 알리세요: 비디오, 버전, 길이, 변경 사항, 그리고 최대 3개의 미결정 사항(각각 권장 기본값 포함). 이미 다른 곳에 업로드된 모든 복사본은 이제 만료되었습니다: 그렇게 말하세요.
사고로부터 비롯된 규칙
- 증거를 직접 다시 실행하세요. 하위 에이전트가 렌더링이 깨끗하다고 말할 때, 해당
REPORT.md를 읽고, 시트와 스트립을 열고, sha256이 전달할 파일과 일치하는지 확인하세요. 에이전트의 "깨끗함"은 주장일 뿐, 보고서가 증거입니다. - 모든 버전은 고유한 파일 이름을
renders/에 가집니다. 이전 버전을 절대 삭제하지 마세요. 수정 주기 내에서 리뷰어가 아직 보지 못한 버전만 덮어쓰세요. - 직접 시작하지 않은 프로세스는 종료하지 마세요 (Chrome, ffmpeg, node): 다른 에이전트가 동일한 머신에서 렌더링합니다.
- 비전 API 없이 스냅샷:
hyperframes snapshot에--describe false를 전달하여 미출시 제품의 프레임이 머신을 벗어나지 않도록 하세요. - 철자만 다른 ASR 차이점은 괜찮습니다 (브랜드 단어가 두 단어로 들리거나, 시간이 문자로 쓰인 경우). 결정하기 전에 각 차이점을 읽으세요. 여러 단어의 차이점은 컷 또는 깨진 라인입니다.
스크립트
| 스크립트 | 용도 |
|---|---|
qa.py <video_dir> <mp4> [--out DIR] [--no-asr] [--strip name:t0:t1[:fps]] | 전체 보고서; 통과하지 못하면 exit 1 |
scan_render.py <mp4> [--json] | 빠른 깜빡임, 검은색 및 음량 스캔; 워커 패턴 또는 비디오 중간 검은색 시 exit 1 |
qa_full.py <video_dir> <mp4> [--out DIR] [--no-asr] | 측정값만 REPORT.txt로 출력 |
sheets.py <mp4> <outdir> [--fps 1] | 1fps 접촉 시트, 4x4 |
strips.py <mp4> <outdir> name:t0:t1[:fps] ... | 전환 주변의 레이블이 지정된 스트립(기본 6fps) |
edges.py <mp4> <video_dir or index.html> | 각 내레이션 클립 전후 레벨 |
parity.py <old> <new> [--end T] [--skip A:B] [--threshold 1.0] [--audio] | 프레임 패리티; 임계값 초과 시 exit 1 |
banned_terms.py [--product DIR] [--text T] [FILE or DIR ...] | 금지 용어, 절대 사용하지 말아야 할 구문 및 레거시 이름; 적중 시 exit 1 |
deliver.py <video_dir> <mp4> [--archive-previous] [--dry-run] | 전달 게이트 |
banned_terms.find_banned(text, product)는 다른 스킬이 재사용할 수 있도록 [(term, kind)]를 반환합니다.
참고 자료
references/checklist.md: 빌드부터 리뷰어 메시지까지 전체 게이트를 체크박스로 제공합니다. 비디오의 첫 번째 렌더링 전과 모든 전달 전에 읽으세요.references/reading-sheets-and-strips.md: 시트, 스트립, 크롭, 패리티 및 숫자 검사(밝은 픽셀 수, 차이 상자)에서 무엇을 찾아야 하는지 설명합니다. 4단계를 수행할 때 읽으세요.references/triage.md: 이 QA에서 생성된 모든 실패(실제 또는 거짓)와 이를 구별하고 수정한 방법을 설명합니다. 검사가 실패하거나 경고하는 즉시 읽으세요.