Communitygithub.com

josueh04/product-video-skills

HyperFrames를 사용하여 내레이션이 포함된 제품 데모를 구성합니다: 스테이지(실제 뷰포트로 재구성되어 1080p로 스케일링된 제품 UI, 카메라, 베일을 사용한 랙 포커스, 챕터 제목, 커서 및 클릭, 타이핑, 스트리밍 텍스트, 팝업, 토스트, 스크롤, 엔드 화면 및 록업)와 모든 비트를 내레이션 단어에 고정하는 build.py입니다. 비디오의 video/build.py, src/template.tpl 또는 src/app.css를 작성하거나 편집할 때, 단어에 비트를 배치할 때, 챕터, 클릭, 팝업 또는 푸시인을 추가할 때, 화면을 구성할 때, 엔드 화면 또는 록업을 구축할 때, 스냅샷 설정 비트를 찍을 때, 또는 이 워크벤치에서 제품 비디오의 드래프트나 최종 MP4를 렌더링할 때 사용하세요. 또한 누군가 "커서가 이상해", "너무 확대됐어", "너무 빨라", "혼란스러워", "제목이 깜빡여", "UI를 음성에 맞춰줘"라고 말하거나 UI의 워크스루, 데모 또는 피치 비디오를 요청할 때도 사용하세요.

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

이 기술은 HyperFrames를 사용하여 전문적인 내레이션 기반 제품 데모 비디오를 구성하는 방법을 정의합니다. `video/build.py`(비트 테이블), `video/src/template.tpl`(재구성된 UI 및 GSAP 타임라인), `video/src/app.css`(제품 UI CSS)의 세 가지 핵심 파일을 중심으로 작동하며, 모든 UI 이벤트(클릭, 타이핑, 팝업 등)를 내레이션의 특정 단어에 고정시켜 완벽한 동기화를 보장합니다. 주요 특징으로는 실제 제품 뷰포트를 1080p로 스케일링하는 스테이지 모델, 챕터 기반의 페이싱(각 챕터는 초점이 흐려진 상태에서 시작하여 한 가지 아이디어에 집중), 모든 비트를 단어 타이밍에 연결하는 타임라인 시스템, 그리고 실제 제작 경험에서 비롯된 구체적인 규칙(예: 메뉴를 닫고 모달 열기, 클릭 전 호버 효과 등)이 포함됩니다. 이 기술은 Claude Code, Cursor 및 기타 AI 에이전트와 함께 사용하도록 설계되었으며, 드래프트 및 최종 렌더링, 스냅샷 QA, 자동화된 린트 및 검사 워크플로우를 제공합니다. 또한 '서명 게이트' 메커니즘을 통해 비디오 제작 전에 검토자와의 합의를 강제합니다.

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

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

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

문서

UI 데모 구성기

여기서 제품 비디오는 비디오당 작성하는 세 개의 파일과 모든 비디오가 공유하는 키트로 구성된 하나의 HyperFrames 컴포지션입니다:

파일설명편집자
video/build.py비트 테이블 T: 모든 시간이 단어 타이밍에서 파생됨사용자
video/src/template.tpl재구성된 UI, 화면 레이어 및 GSAP 타임라인사용자
video/src/app.css제품 UI CSS, specs/의 리터럴 값사용자
kit/stage.css, kit/titles.css, kit/stage.js스테이지 레이어 및 seek-safe 헬퍼이 기술
products/<slug>/kit/tokens.css, fonts/, icons/, ui/제품의 토큰, 폰트, 아이콘 및 공유 UI 조각product-kit
video/index.htmlbuild.py에 의해 생성됨. 수동으로 편집하지 마세요없음

scripts/buildlib.py는 모든 빌드의 일반적인 부분(타이밍, 서명 게이트, 오디오 태그, 인라인, 플레이스홀더, 아이콘, 카메라 클램프)을 처리하여 build.py가 간결한 비트 목록을 유지하도록 합니다.

스테이지 모델

#root > #stage > #camera > #blurWrap > #app      제품, 앱 픽셀 단위
               > #veil, .pvs-ttl, #endS, #lock, #fade      화면 공간, 1920x1080
  • UI는 실제 뷰포트에서 재구성되어 한 번 스케일링됩니다. #app은 product.yaml app_canvas.logical CSS 픽셀(예: 1440x810)이며, 하나의 변환으로 1920x1080으로 스케일링됩니다. 프로덕션 CSS는 리터럴 픽셀을 유지하므로 사양 값이 변경 없이 붙여넣어지고 모든 측정값이 코드와 1:1로 비교됩니다. 앱의 중단점 위에 있는 데스크톱 너비를 16:9로 선택하세요. 화면 녹화가 있는 경우 해당 논리적 크기를 사용하세요. 16:9가 아닌 캔버스는 레터박스 처리됩니다(buildlib이 경고함).
  • 위치는 측정되며, 입력되지 않습니다. S.box(sel)은 폰트 로드 후 #app까지의 오프셋을 합산합니다. CSS가 변경되어도 커서는 여전히 버튼 위에 위치합니다.
  • 커서와 클릭 리플은 #app의 마지막 자식 요소이므로 제품과 함께 스케일 및 블러 처리됩니다. 팝업(.pvs-modal) 및 토스트(.pvs-toast-slot)도 #app 내에 있습니다.
  • #camera만 움직이고 #blurWrap만 블러 처리됩니다. #app 또는 #stage를 트윈(tween)하지 마세요.

프레이밍: 기본값 1x 전체 페이지

기본적으로 모든 제품 비트를 1x, 전체 페이지로 설정하고, 팝업은 자연스러운 크기로 앱이 표시하는 방식대로 중앙에 배치합니다. 푸시인은 부드럽게(video.max_zoom까지, 기본값 1.35), 전체 섹션을 프레임 내에 유지하고 프레임 가장자리가 레이블을 통과하지 않도록 합니다. 챕터당 하나의 프레이밍: 제품이 초점에서 벗어난 상태에서 챕터 제목 뒤에서 이동하거나, 하나의 느린 시그니처 동작으로 수행합니다.

이유: 이 기술이 비롯된 프로덕션에서 설정 비디오가 줌으로 인해 두 번 거부되었습니다. 1.67x 펀치인은 레이블을 반으로 잘랐고("무슨 일이 일어나고 있는지 알 수 없음"), 나중에 컬럼당 약 2x의 프레이밍은 아무것도 잘리지 않았음에도 비좁게 느껴졌습니다. 검토자가 모범으로 제시한 비디오는 항상 1x로 실행되었습니다. 멀리 떨어진 캔버스(50%로 표시) 또는 좁은 채팅 컬럼은 더 많은 것을 허용합니다: 해당 제품에 대해 product.yaml에서 max_zoom을 높이고, 비트별로는 높이지 마세요. b.cam() 및 S.cam()은 max_zoom 이상에서 클램프하고 경고합니다. 세부 사항 및 숫자: references/framing-and-pacing.md.

페이싱: 챕터는 일시 정지

  • UI 중간이 아닌 컨텍스트에서 열기: 로고, 제품 이름 및 제품에 대한 한 줄 설명, 초점이 흐려진 제품 위에.
  • 각 챕터는 초점이 흐려진(블러 + 베일) 제품 위에 투톤 제목으로 열리고, 최소 약 1.4초 동안 유지되며, 첫 번째 동작을 명명하는 단어 직전에 초점이 돌아옵니다. 화면 변경은 제목 뒤에서 발생하므로 하드 컷이 없습니다.
  • 챕터당 하나의 아이디어, 한 번에 하나의 변경, 0.61초 간격, 각 챕터 끝에 약 0.8초의 유지. 제품의 실제 대기 시간은 12초로 압축됩니다.
  • 엔드 화면은 범위(제품이 수행하는 다른 작업, 실제 UI 조각 사용)를 보여준 후 록업을 보여줍니다.

이유: 0.5초마다 미세 동작이 있는 밀집된 원테이크 컷은 제작자에게는 세련미로 읽히고 검토자에게는 노이즈로 읽혔습니다("너무 빠르고, 한 번에 너무 많고, 압도적임") 결과를 확대 및 축소하여 따라가기 불가능하게 만들었습니다. 차분한 챕터 버전이 승인되었습니다.

모든 비트는 단어에 고정됩니다

b = buildlib.Build(__file__)
T, w, end = b.T, b.w, b.end
T["N2"] = T["ch1"] + 0.3                                  # 클립 ID 배치는 해당 클립을 배치합니다
T["rack1"] = T["N2"] + w("N2", "after") - 0.25            # "after" 직전에 초점이 돌아옴
T["send1"] = max(T["type1"] + T["type1Dur"] + 0.4, end("N3") + 0.15)
  • w(clip, prefix, nth=1)은 클립을 기준으로 prefix로 시작하는 첫 번째 단어의 시작입니다. 단어가 없으면 예외를 발생시킵니다(자동 대체 없음: 조용히 기본 시간에 비트를 배치하는 대체는 모션이 음성에서 눈에 띄지 않게 멀어지게 하는 방법입니다).
  • UI 이벤트는 이를 명명하는 단어보다 0.05~0.45초 먼저 발생합니다. max()는 내레이션 순서와 "UI가 완료됨"을 모두 유지합니다. end(k)는 T[k]에 클립 지속 시간을 더한 값입니다(또는 b.dur(k, d)).
  • 타이핑 속도는 초당 문자 수(약 17~21)이거나 비트에 맞게 고정됩니다.
  • 클릭, 타이핑 및 팝업은 동일한 T에서 사운드를 가져오므로(b.click(t), b.typing(text, t, dur), b.pop(t)), 리타이밍된 비트는 사운드도 이동시킵니다.
  • 음성의 한 줄을 재생성하면 전체 비디오의 타이밍이 다시 계산됩니다. 그것이 요점입니다.

이유: 타이밍에는 하나의 진실 공급원이 있습니다. 라인이 재생성되면 여기에 고정된 모든 것이 함께 이동합니다. 수동으로 입력한 초는 첫 번째 재촬영에서 쓸모없게 됩니다.

워크플로우

  1. BRIEF.md(챕터, 프레이밍), COVERAGE.md(각 챕터가 화면에서 설명해야 하는 것), specs/*.md 및 TRUTH.md를 읽습니다. UI를 발명하지 마세요: SOURCES.md 또는 specs/에 출처가 없는 화면이나 동작은 제외합니다.
  2. 사양에서 src/template.tpl 및 src/app.css의 화면을 재구성하고, product.yaml cast의 가상 데이터를 사용합니다. 다른 비디오에서 복사하는 대신 kit/ui/의 제품 조각을 {{UI:name}}으로 재사용합니다 (references/ui-component-library.md).
  3. build.py에 비트를 작성하고 키트 헬퍼를 사용하여 템플릿에 타임라인을 작성합니다 (references/stage-kit.md API 참조, references/beat-recipes.md 각 비트 참조, references/end-screen-and-lockup.md). 모든 트윈에 대해 seek-safe-motion 기술을 따릅니다.
  4. 드래프트를 빌드하고 인쇄되는 비트 테이블을 읽습니다:
    PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
    "$PVS_HOME/bin/pvs-py" <video_dir>/video/build.py --draft
    
    음성이 생성되기 전에 --draft --fake-timings는 lines.tsv에서 단어 타이밍을 생성하여 화면을 배치할 수 있도록 합니다.
  5. <video_dir>/video/에서 린트 및 검사:
    "$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/seek-safe-motion/scripts/lint_motion.py" .
    npx --yes [email protected] check
    
    오류 0개 및 런타임 경고 0개를 예상합니다. 하나의 린트 경고는 모놀리식 스테이지에 대해 예상됩니다: composition_file_too_large(키트가 인라인됨). 그런 다음 빌드가 인쇄하는 두 번째 check를 실행합니다. check --at <설정 비트 시간>: 기본 샘플은 종종 초점이 흐려진 순간에만 위치하며, 키트가 대비 검사에서 제품 텍스트를 숨깁니다(의도적으로 흐려짐). 따라서 contrast ... checked 0은 시청자가 읽는 것을 감사하지 않았습니다. check만으로는 충분하지 않습니다: 이동하는 항목이 경로의 대부분에서 보이지 않는 비디오를 통과시켰습니다. 프레임을 확인하세요.
  6. 모든 설정 비트를 스냅샷으로 찍고 각 이미지를 직접 확인하세요. build.py에서 b.snap(t, label)로 표시합니다. 빌드는 정확한 명령을 인쇄합니다:
    npx --yes [email protected] snapshot . --at 3.2,4.7,9.98 --no-end --describe false -o snapshots/setup
    
    --no-end는 해당 시간만 캡처합니다. --describe false는 프레임이 외부 비전 API로 전송되는 것을 방지합니다. 프레이밍(가장자리에서 잘린 것 없음), 대상 위의 커서, 자연 크기로 중앙에 배치된 팝업, 온전한 제목을 확인하세요. --zoom "#toast" --zoom-scale 2는 하나의 요소를 자릅니다. 의심스러운 트윈을 테스트하려면 --at <start>,<later>가 --at <later>와 일치해야 합니다.
  7. 렌더링합니다. 검토용 드래프트, BRIEF.md가 서명되면 최종본(build.py가 이 줄을 인쇄합니다):
    npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality draft
    npx --yes [email protected] render . -o renders/<video>-v<k>.mp4 --fps 30 --quality delivery
    
    그런 다음 MP4에서 render-qa를 실행합니다. 모든 버전의 MP4를 보관합니다.

서명 게이트

build.py는 coverage_signed_by 및 claims_signed_by가 BRIEF.md에 설정될 때까지 빌드를 거부합니다(종료 코드 2). --draft는 어쨌든 빌드하고 <meta name="pvs-draft" content="1">을 index.html에 스탬프합니다. QA는 보고서를 드래프트로 표시하고 최종본은 거부합니다. 검토자를 대신하여 서명하지 말고, 메타를 제거하지 마세요: 드래프트는 보기 위한 것이며, 제공하기 위한 것이 아닙니다.

이유: 이 기술이 비롯된 프로덕션에서 26개 버전 중 9개는 비디오가 검토자가 관심을 가진 기능을 설명하지 않았고, 아무도 빌드하기 전에 해당 기능을 기록하지 않았기 때문에 발생했습니다. 게이트는 합의가 먼저 오도록 합니다.

사고로 인한 규칙

  • 프로덕션 결함은 수정하고, 외관은 유지하세요. 레이아웃, 토큰 및 동작은 1:1로 유지하지만, 라이브 앱의 가시적인 결함(누락된 패딩, 넘치거나 잘린 텍스트, 회색 기본 컨트롤, 클릭 후 남은 포커스 링)을 수정하세요. 모든 수정 사항을 BRIEF.md 노트에 나열하세요.
  • 제품이 구성 가능할 때 구성 가능한 것을 표시하세요: 구매자가 물어볼 만한 설정은 내레이션뿐만 아니라 화면에 표시되어야 합니다.
  • 메뉴 위에 모달을 열기 한 프레임 전에 메뉴를 닫으세요. 열린 드롭다운 아래 새 대화상자는 한 렌더링에서 고스트 텍스트를 남겼습니다.
  • 엔드 화면 콘텐츠만 록업으로 페이드하고, 록업이 나타날 때까지 배경을 유지하세요. 둘 다 페이드하면 그 사이에 날카로운 UI 프레임이 나타났습니다(S.lockup이 이렇게 함).
  • 클릭 전에 호버(hov 클래스 약 0.12초 전), 첫 번째 랙 후 커서가 들어오고 엔드 화면 전에 커서가 나갑니다.
  • UI, 데이터 또는 내레이션에 공급업체 또는 금지된 이름이 없습니다(product.yaml banned_terms, names). 실제 화면에 하나가 표시되면 해당 조각을 프레임 밖으로 유지하고, 절대 비어 있는 상태로 두지 마세요.
  • 진행 상황을 일찍 보여주기 위해 렌더링하지 마세요. 스냅샷으로 반복하고, 설정 비트가 올바르게 보일 때 렌더링하세요.

파일

경로언제 읽을 것인가
references/stage-kit.md헬퍼의 시그니처, 플레이스홀더, CSS 변수 또는 buildlib API가 필요할 때
references/beat-recipes.md특정 비트(오프닝, 챕터, 클릭, 타이핑, 스트리밍, 팝업, 드롭다운, 토스트, 스크롤, 푸시인)를 구축할 때
references/framing-and-pacing.md프레이밍 또는 리듬을 선택하거나, 검토자가 "확대됨", "빠름", "혼란스러움"이라고 말할 때
references/end-screen-and-lockup.md엔딩을 구축할 때
references/ui-component-library.mdUI 조각이 둘 이상의 비디오에 나타나거나, 다른 비디오에서 마크업을 복사하려고 할 때
scripts/buildlib.pyAPI 참조에서 다루지 않는 동작이 필요할 때
kit/stage.js타임라인 헬퍼에 대해 동일함
PVS_HOME/_template/video/video/모든 새 비디오가 시작하는 예제 build.py, template.tpl 및 app.css

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

Check a rendered product video before anyone else sees it: worker-pattern flicker, black frames, loudness and true peak, clipping, clicks at clip edges, overlapping narration, speech to text against the script, banned terms and legacy names, camera zoom, contact sheets, frame strips at transitions and parity against the approved version; then write qa/REPORT.json, the only thing deliver.py accepts. Use it after every HyperFrames render, whenever someone asks "is the render clean", "QA this", "check the video", "check the audio", "why does it flicker", "there is a click", "compare v3 with v2", "did the approved part change", or before showing, sending, uploading or delivering any MP4, even when the request does not say QA. Also use it to triage a defect a reviewer reported in a render.

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

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.

관련 스킬