Communitygithub.com

josueh04/product-video-skills

누구보다 먼저 렌더링된 제품 비디오의 결함(워커 패턴 깜빡임, 검은 프레임, 음량 및 트루 피크, 클리핑, 클립 가장자리 클릭, 중첩 내레이션, 스크립트 대비 음성-텍스트, 금지 용어 및 레거시 이름, 카메라 줌, 전환 시 프레임 스트립 및 승인된 버전과의 일치 여부)을 검사하고 qa/REPORT.json을 작성합니다. HyperFrames 렌더링 이후, 또는 누군가 "렌더링 깨끗한가요", "QA 해주세요", "비디오 확인해주세요", "오디오 확인해주세요", "왜 깜빡이나요", "딸깍 소리가 나요", "v3와 v2를 비교해주세요", "승인된 부분이 변경되었나요"라고 묻거나, MP4를 보여주거나, 보내거나, 업로드하거나, 전달하기 전에, 심지어 요청에 QA가 명시되지 않은 경우에도 이 스킬을 사용하세요. 또한 리뷰어가 렌더에서 보고한 결함을 분류할 때도 사용하세요.

product-video-skills란 무엇인가요?

이 스킬은 제품 비디오 렌더링 후 자동화된 품질 검사(QA)를 수행합니다. HyperFrames 렌더링에서 발생할 수 있는 워커 패턴 깜빡임, 검은 프레임, 오디오 클리핑, 음량 이상, 내레이션 중첩, 스크립트와의 불일치, 금지 용어 사용, 카메라 줌 문제 등 다양한 결함을 탐지합니다. 검사 결과는 qa/REPORT.json과 qa/REPORT.md 파일로 출력되며, 접촉 시트와 프레임 스트립도 함께 생성하여 사람이 직접 확인할 수 있는 증거를 제공합니다. Cursor, Claude Code, Codex 등 AI 에이전트와 함께 사용하도록 설계되었으며, 렌더링 완료 직후 빠른 스캔, 전체 보고서 생성, 육안 검사 단계로 구성된 체계적인 게이트 프로세스를 따릅니다. 또한 전달(deliver.py) 전에 반드시 QA를 통과해야 하며, 각 버전의 파일명을 별도로 유지하고 이전 버전을 덮어쓰지 않습니다.

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

즐겨 사용하는 AI에게 물어보기

이 에이전트 스킬이 미리 로드된 새 채팅을 엽니다.

문서

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/를 포함합니다).

게이트, 순서대로

  1. 렌더링 전. 모션 린트(seek-safe-motion 스킬), hyperframes check, 그리고 모든 설정 비트의 스냅샷을 실행합니다. check만으로는 충분하지 않습니다: 한 번은 움직이는 요소가 네 개의 구간 중 세 개에서 보이지 않는 비디오를 통과시킨 적이 있습니다. 렌더링 전 단계는 references/checklist.md에 있습니다.
  2. 렌더링 직후, 빠른 스캔(몇 초): "$PY" "$S/scan_render.py" <mp4>. WORKER PATTERN 라인은 시크-세이프티 버그를 의미합니다: 중지하고 타임라인을 수정하고(seek-safe-motion 참조), 나머지를 실행하지 마세요.
  3. 전체 보고서: "$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 차이점을 포함하세요.
  4. 육안 검사. 보고서는 스크립트가 볼 수 없는 것으로 끝납니다. 모두 수행하세요:
    • 모든 접촉 시트를 살펴보세요. 샘플이 아닙니다.
    • 모든 모달 열림 및 닫힘, 스크롤, 카메라 이동, 챕터 변경, 이 버전에서 변경된 비트, 그리고 종료 화면에서 잠금 전환 주변에서 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.
  5. 분류 모든 실패와 경고는 references/triage.md를 사용하세요: 이 검사에서 발견된 실제 결함과 오탐지를 나열하고, 각각을 구별한 방법을 설명합니다. 원인을 소스(템플릿, 빌드, lines.tsv, 오디오)에서 수정하고, 재빌드, 재렌더링 후 2단계부터 게이트를 다시 실행하세요. 절대 index.html을 수동으로 편집하지 마세요: 빌드가 다시 생성합니다.
  6. 전달은 이 스킬의 호출 사항이 아닙니다. deliver.py는 사용자 또는 사용자가 시작한 스킬(/video-build, /video-review)이 전달을 요청할 때만 실행됩니다. 보고서가 통과하지 않았거나, 초안이거나, MP4와 바이트 단위로 일치하지 않으면 거부합니다.

검사 항목 측정 기준

검사실패 조건이 임계값을 사용하는 이유
size, fps크기가 video.size와 다를 때; fps는 경고만잘못된 크기는 깨진 렌더링; 다른 fps는 의도된 것일 수 있음(30 대 60)
worker_pattern4개 이상의 이상치 프레임이 모두 동일한 프레임 인덱스 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_lintseek-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에서 생성된 모든 실패(실제 또는 거짓)와 이를 구별하고 수정한 방법을 설명합니다. 검사가 실패하거나 경고하는 즉시 읽으세요.

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.

관련 스킬