product-video
실제 영상 + 이벤트 로그 → 선언적 계획(YAML) → pvk render → 콘택트 시트 → 최종 결과물.
스크립트가 타이밍, 줌, 오버레이 및 오디오를 처리하고, 사용자는 스토리보드를 작성하고 계획을 수립하며 프레임을 검토합니다.
PVK=~/.claude/skills/product-video/bin/pvk # 또는 `pip install -e ~/.claude/skills/product-video` 후 `pvk`
사용 시기
| 사용자 요구사항 | 제작할 것 | 먼저 읽을 문서 |
|---|---|---|
| 사용자가 기능이나 앱 전체를 배우도록 함 (비디오 hướng dẫn, 튜토리얼, 온보딩) | 튜토리얼: 각 챕터 1-3분, 이후 pvk join | references/storyboard.md |
| 제품이나 릴리스에 대한 주목도 확보 (비디오 quảng cáo, 프로모션, 런칭, 티저) | 프로모션: 30-45초 16:9 비트에 맞춘 컷 | references/storyboard.md |
| 짧은 웹 앱 데모 또는 버그 재현 클립 | web-video 스킬만 사용 | - |
엄격한 규칙
- 실제 앱, 샘플 데이터. 실제 제품을 현실적인 가상 샘플 데이터로 촬영합니다. 목업은 사용하지 않으며, 실제 고객 데이터, 비밀, 프로덕션 계정은 절대 사용하지 않습니다 (
references/privacy.md). - 먼저 스토리보드, 그 다음 승인. 스토리보드를 평문으로 작성하고 촬영 전에 승인을 받습니다.
- 프로젝트 디자인. 프로젝트에서
theme init을 실행하고, 결과를 디자인 가이드와 비교하여 확인합니다. - 음악과 효과음은 필수. 모든 비디오에는 배경 음악과 UI 사운드가 포함되며, -16 LUFS로 마스터링합니다.
- 드래프트, 확인, 그 다음 최종.
--draft --check로 렌더링하고, 모든 콘택트 시트를 열어 확인하고 수정한 후에만--final을 실행합니다. - 소유자의 승인 없이 어떤 것도 기기 밖으로 나가지 않습니다 (업로드, 게시물, 이슈 첨부 파일).
- 보안, 키체인, 로그인 대화상자는 절대 직접 처리하지 않습니다. 사용자에게 넘깁니다.
0단계. 설정 (기기당 한 번)
$PVK doctor # ffmpeg, Python 3.11+, 패키지, Chromium, 폰트, 선택 도구 확인
python3 -m pip install -r ~/.claude/skills/product-video/requirements.txt && python3 -m playwright install chromium
$PVK fonts # Inter, Playfair Display, JetBrains Mono (OFL) 다운로드 → ~/.cache/product-video
$PVK sfx gen && $PVK music beds
$PVK selftest # 번들 데모로 짧은 챕터와 프로모션 렌더링 (~1분)
누락된 도구: 설치 명령어를 출력하고 물어보십시오. 조용히 설치하지 마십시오.
1단계. 프로젝트에서 테마 생성
cd <video-folder> # 예: <project>/video (출력물은 git에 포함하지 않음)
$PVK theme init --repo <project> --out theme.json
$PVK fonts --theme theme.json
$PVK overlay chapter title="Preview" --theme theme.json --out preview.png # 확인
디자인 가이드가 추가 정보를 제공하는 경우(references/theme.md), theme.json에서 색상, 폰트, brand, logo를 수동으로 수정합니다.
2단계. 스토리보드
튜토리얼: 사용자가 배워야 할 각 작업당 하나의 챕터; 각 챕터 = 챕터 카드, 3-8개의 번호가 매겨진 캡션이 있는 영상, 요약 카드. 프로모션: 5-8개의 하이라이트, 각각 짧은 헤드라인 카드 + 2-4초 영상 순간, 엔드 카드. 표(시간, 화면, 캡션, 사운드)로 작성하고 승인을 받습니다. 자세한 내용: references/storyboard.md.
3단계. 캡처
| 제품 | 방법 |
|---|---|
| 네이티브 macOS 앱 | scene.py 작성 (examples/scene_native.py 참조), $PVK capture native scene.py --app "App" --out takes/s1 --rehearse, 그 다음 --rehearse 없이 실행 |
| 웹 앱 | web-video로 녹화 (record.py --slug x), $PVK capture import video-out/x/v1 --name w1 |
| 기타 모든 것 | raw.mp4와 events.json (references/plan-format.md 참조)을 takes/<name>/에 저장 |
| 아직 앱이 없거나 시험 중인 경우 | $PVK demo --out takes/demo |
각 촬영 전: 샘플 데이터 로드, 알림 끄기 (방해 금지 모드), 이전 토스트 닫기, 창 크기 고정.
각 촬영 후: $PVK check popups takes/s1 및 $PVK check grab takes/s1 grab.png 1 5 9로 확인.
macOS 함정 (Mission Control 키, Cmd vs Ctrl, 실제 포인터, HUD): references/pitfalls.md.
4단계. 계획
examples/tutorial.yaml 또는 examples/promo.yaml을 촬영본 옆에 복사하고 편집합니다. 영상 클립의 시간은 해당 촬영본의 events.json에 있는 소스 초이며, 상자(박스)는 소스 픽셀입니다. 전체 형식: references/plan-format.md.
$PVK render ch01.yaml --only-plan # 빠름: out/plan/ch01.md에 모든 클립, 캡션, 줌, 사운드, 경고 목록
모든 경고를 수정합니다 (짧은 캡션, 겹침, 줌 범위를 넘는 콜아웃, 두 자리 단계 번호).
5단계. 드래프트 및 확인
$PVK render ch01.yaml --draft --check # 720p; out/drafts/ch01.mp4 + out/check/ch01/contact-*.png
$PVK render ch01.yaml --frames 3.2,7.5 # 출력 시간의 스틸 이미지, 자세히 보기
$PVK promo promo.yaml --draft --check # 프로모션: 동일 엔진, 비트 그리드에 맞춰 컷
모든 콘택트 시트를 엽니다 (PNG 읽기). 확인: 캡션이 읽기 쉽고 액션을 가리지 않는지, 줌 위치가 올바른지, OS 팝업이나 남은 토스트가 없는지, 커서가 클릭 위치에 있는지, 카드 철자가 올바른지, 음량이 약 -16 LUFS인지. 최대 3번까지 수정 후 사용자에게 드래프트와 시트를 보여줍니다.
6단계. 최종 및 전체 컷
$PVK render ch01.yaml --final # 1080p, out/final/ch01.mp4
$PVK join out/final/tutorial.mp4 out/final/ch0*.mp4
$PVK check out/final/tutorial.mp4
보고: 파일 경로, 길이, 음량, 확인할 수 없었던 사항 (믹스를 들을 수 없으므로 그 사실을 명시).
음악과 사운드
music: bed:soft-piano | bed:ambient | bed:promo는 합성된 배경 음악입니다 (자체 제작, 무료). 라이선스 트랙의 경우: $PVK music fetch (획득 위치), $PVK music add track.mp3 --title ... --author ... --source URL --license ... (-20 LUFS로 정규화하고 music/LICENSES.md에 기록). 타사 트랙을 절대 커밋하지 마십시오. SFX 맵, 덕킹, 음량: references/audio.md.
참고 자료
references/storyboard.md: 튜토리얼 vs 프로모션, 챕터 구조, 캡션 작성, 비트 컷references/plan-format.md: 모든 계획 키, events.json 형식, 타임라인 계산references/theme.md: theme.json,theme init, 폰트 (OFL), 로고references/audio.md: 배경 음악, 라이선스 음악, SFX 맵, 음량 목표references/capture.md: 네이티브 macOS 캡처, web-video 가져오기, 촬영본 레이아웃references/pitfalls.md: 실제 프로젝트에서 발생한 모든 문제와 해결책references/privacy.md: 데이터 및 공유 규칙