Communitygithub.com

techgirlcrystal/product-video-skill

소프트웨어 제품의 실제 출력(데모 계정, 예시 보고서, 대시보드, 다이어그램)을 활용하여 전문적인 모션 그래픽 스타일의 제품 개요/설명/프로모션 비디오(MP4, 16:9 및 9:16)를 제작합니다. 화면 캡션, 애니메이션 커서, UI 사운드 효과 및 배경 음악을 포함하며 내레이션은 없습니다. 현대적인 SaaS 런치 비디오와 같은 스타일로, 다크 시네마틱 후크 장면, 라이트 스플릿 피처 장면, 애니메이션 카운터, 자체 그리기 다이어그램, 3D 브라우저 창 팬, URL이 포함된 엔드 카드 등으로 구성됩니다.

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

이 스킬은 소프트웨어 제품의 실제 출력 데이터를 기반으로 전문가 수준의 모션 그래픽 스타일 제품 비디오를 제작합니다. HTML 애니메이션을 프레임 단위로 렌더링하여 MP4 파일로 출력하며, 내레이션 없이 음악과 함께 시각적 스토리텔링에 집중합니다. 사용자가 제품 비디오, 데모, 기능 소개, 프로모션, 숏폼 콘텐츠(Reels/Shorts/TikTok)를 요청할 때 이 스킬을 사용하세요. Claude Code(CLI, 데스크톱 앱, 또는 웹 환경)에서 실행되며, Node.js, Playwright, Python, ffmpeg가 필요합니다. 실제 제품 데이터(숫자, 이름, 다이어그램)만을 사용하여 진정성을 확보하는 것이 핵심이며, 생성된 HTML 애니메이션을 Playwright가 프레임별로 캡처하여 ffmpeg로 인코딩합니다. 사운드 이펙트는 라이선스 문제 없이 처음부터 합성되며, 사용자가 제공한 음악 트랙을 비디오에 믹싱할 수 있습니다. 또한 기존 스토리보드를 렌더링하거나, 이미 제작된 비디오에 음악을 추가하거나, 가로/세로 등 다양한 비율로 리컷하는 기능도 지원합니다.

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

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

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

문서

제품 비디오

내레이션 없이 음악으로 구동되는 제품 개요 비디오를 제작합니다. HTML 애니메이션으로 빌드되고 프레임 단위로 렌더링되어 MP4로 출력됩니다. 화면의 모든 숫자, 이름, 다이어그램은 제품의 실제 출력에서 가져온 것입니다. 이것이 이 비디오의 신뢰성을 보장하며, 일반적인 스톡 모션 그래픽과 차별화되는 점입니다.

작동 방식: 대상 해상도의 단일 HTML 페이지가 window.seek(t)를 정의합니다. 이 함수는 시간 t의 프레임을 순수 함수로 그립니다(CSS 애니메이션이나 타이머 없음). Playwright가 seek(i/30)을 호출하여 각 프레임을 스크린샷으로 캡처하고, 프레임은 ffmpeg로 파이프되어 비디오로 인코딩됩니다. 프레임이 실제 시간에 의존하지 않으므로 출력은 모든 머신에서 동일하며, 단일 프레임을 미리 볼 수 있고, 변경 사항은 몇 분 내에 다시 렌더링됩니다.

번들 파일:

  • scripts/render.mjs: 컴포지션을 MP4로 렌더링 (--url --out [--w --h --fps --from --to])
  • scripts/preview.mjs: 선택한 시간의 정지 이미지, --sheet 옵션으로 연속 스트립 생성
  • scripts/cutdown.py: 기존 컴포지션에서 짧은 릴(예: 15초)을 잘라냅니다: 선택한 시간 범위를 렌더링하고 하드 컷으로 결합하며, 첫 번째 컷에 음악의 드롭을 맞춥니다
  • scripts/cues.mjs: 컴포지션에서 사운드 효과 큐 리스트를 파생합니다(씬 스우시, 카드/칩 팝, 카운터 틱, 커서 클릭, URL 차임, window.SFX_EXTRA 포함)
  • scripts/sfx.py: 처음부터 UI 사운드 키트를 합성하고(클릭, 팝, 스우시, 틱, 키, 차임, thud; 스톡 오디오나 라이선스 없음), 큐를 트랙으로 믹싱한 후 최종 음악 + 효과 믹스를 -16 LUFS로 출력합니다
  • scripts/music.py: 트랙의 에너지 맵을 analyze하고, 비디오 아래에 mux합니다(트림, 페이드, -16 LUFS)
  • scripts/doctor.mjs: 아래의 모든 요구 사항을 확인하고 누락된 사항에 대한 정확한 수정 방법을 출력합니다
  • scripts/_common.mjs: 사전 설치된 Chromium과 ffmpeg를 찾습니다(pip install imageio-ffmpeg 폴백 지원)
  • assets/template.html: 작동하는 씬 템플릿; 하나의 파일이 세로 미디어 쿼리를 통해 16:9 및 9:16을 모두 렌더링합니다
  • assets/fonts-manrope.css: 내장된 Manrope 글꼴(제품에 내장 글꼴이 없는 경우 폴백)
  • assets/examples/supersnapshot/: (Super Snapshot AI, GoHighLevel 도구) 완성된 80초 비디오의 전체 소스(16:9 + 세로), 모든 패턴이 프로덕션 수준으로 구현된 작업 예제
  • references/story-and-copy.md: 스토리 아크, 헤드라인 규칙, 정직성 규칙, 타이밍 규칙. 스토리보드 작성 전에 읽으십시오.
  • references/extraction.md: 안전한 데이터 소스를 찾고 제품에서 SVG, 그래프, 스크린샷을 추출하는 방법. 캡처 전에 읽으십시오.

요구 사항

이 스킬은 셸 명령을 실행하므로 Claude Code(CLI, 데스크톱 앱, 또는 Claude Code 웹)가 필요합니다. 코드 환경이 없는 일반 채팅은 스토리보드를 계획할 수 있지만 렌더링할 수는 없습니다. 머신 또는 컨테이너에서 필요한 사항:

필요이유설치 방법
Node.js 18+렌더링 스크립트 실행nodejs.org 또는 nvm install 22
playwright npm 패키지 (작업 디렉토리에서 import 가능)브라우저를 프레임 단위로 구동npm i -D playwright (많은 웹 저장소에 이미 있음)
Chromium프레임 렌더링npx playwright install chromium, 또는 사전 설치된 것 재사용 (CHROME=/path; /opt/pw-browsers 자동 감지)
Python 3.9+ with numpy사운드 효과 합성 및 믹싱pip install numpy
ffmpeg인코딩, 음악, 믹싱시스템 ffmpeg, 또는 pip install imageio-ffmpeg

네트워크 액세스는 설치 시에만 필요합니다. 렌더링은 완전히 오프라인으로 진행됩니다. 사용자가 자신의 음악 트랙을 제공합니다; 사운드 효과는 합성되므로 라이선스할 것이 없습니다.

워크플로우

0. 설정 확인

제품 저장소에서 node <skill>/scripts/doctor.mjs를 실행합니다. ✗ 표시가 있으면 시작하기 전에 출력된 수정 명령을 실행하거나(또는 이 환경에서 패키지를 설치할 수 없는 경우 사용자에게 요청) 진행하십시오. 30분 빌드 후 누락된 ffmpeg를 발견하면 세션 전체가 낭비됩니다.

1. 실제 자료 찾기

references/extraction.md를 읽습니다. 제품의 데모/예제 빌드(저장소 스크립트, fixture, 또는 공개 예제 URL)를 찾아 Playwright에서 열고 모든 탭을 클릭하며 각 창의 텍스트를 덤프합니다. 창을 스크린샷으로 캡처하고 살펴봅니다. 찾아야 할 것: 가장 인상적인 실제 숫자(후크), 구매자가 지불할 의향이 있는 기능, 움직임이 좋아 보이는 시각적 요소.

2. 스토리보드, 승인 받기

references/story-and-copy.md를 읽습니다. 테이블을 제안합니다: # · 시간 · 화면 내용 · 화면 캡션. 약 60–75초(소셜 컷의 경우 30–45초)로 유지합니다. 카메라에 약해 보이는 기능은 솔직히 말합니다. 사용자만이 답할 수 있는 몇 가지 사항만 질문하고 그 이상은 묻지 않습니다:

  • 언급하지 말아야 할 사항,
  • CTA(기본값: URL만),
  • 브랜드 룩(기본값: 제품 자체 토큰과 일치).

빌드하기 전에 사용자의 승인을 기다리십시오. 완성된 렌더링을 다시 컷하는 것은 테이블을 편집하는 것보다 훨씬 많은 비용이 듭니다.

3. 에셋 캡처

모든 것을 제품 저장소 외부의 스크래치 작업 디렉토리(세션의 스크래치패드가 있으면 그곳, 없으면 임시 디렉토리)에 넣습니다: <work>/index.html + <work>/assets/. extraction.md에 설명된 대로 다이어그램 SVG, 그래프 JSON 및 긴 보고서 스크린샷을 가져옵니다. 제품의 내장 글꼴 CSS를 assets/fonts.css로 복사합니다(또는 이 스킬의 assets/fonts-manrope.css).

4. 컴포지션 빌드

assets/template.html을 <work>/index.html로 복사합니다. 모든 [BRACKETED] 자리 표시자를 실제 콘텐츠로 바꾸고, 필요 없는 씬은 제거하고, 필요한 씬은 복제합니다. assets/examples/supersnapshot/index.html의 예제를 훑어보며 더 많은 패턴을 확인합니다(따뜻한 "문제" 카드, 콜아웃 상자가 있는 막대 카드, 점수 다이얼, 방사형 종속성 맵, 전체 계정 네트워크, 심각도 태그가 지정된 수정 행).

중요한 사항:

  • 타이밍은 두 곳에 존재합니다: SCENES 시작 시간과 각 요소의 data-in. 씬을 삽입하면 모든 이후 data-in과 seek()의 하드 코딩된 시간을 동일한 양만큼 이동해야 합니다(삽입 지점 이상의 data-in="…" 값에 대한 작은 정규식으로 처리).
  • 크로스페이드: 새 씬은 기존 씬 위로 페이드 인되며, 기존 씬은 그 아래에 단색으로 유지됩니다. 둘 다 동시에 페이드하면 밝은 씬이 탁한 회색으로 희미해집니다.
  • 리빌: SVG 부분은 읽기 순서(위에서 아래로, 또는 중앙에서 바깥쪽으로)로 나타납니다. 화살촉은 선이 완전히 그려진 후에만 나타납니다. 레이블 텍스트로 노드에 하이라이트를 연결합니다.
  • 콜아웃: 칩과 레이블은 가리키는 요소를 절대 가리지 않아야 합니다. 요소 옆의 빈 공간에 배치하고, 카메라가 팬되면 따라가도록 합니다.

5. 렌더링 전 미리보기

디렉토리를 서빙하고(cd <work> && python3 -m http.server 8765 &) 모든 씬의 핵심 순간에 정지 이미지를 렌더링합니다:

node <skill>/scripts/preview.mjs --url http://127.0.0.1:8765/index.html --dir <work>/prev --sheet 5 9 13 22 31 43 50 60

모든 프레임을 확인하십시오. 겹침, 어색한 줄 바꿈(<br>로 강제), 가리키는 요소보다 먼저 나타나는 요소, 빈 카드, 남아 있는 자리 표시자 텍스트가 없는지 확인합니다. 깨끗해질 때까지 수정하고 다시 미리보기합니다. 스크립트는 playwright가 필요합니다: node_modules에 playwright가 있는 디렉토리(보통 제품 저장소)에서 실행하십시오. 또한 사전 설치된 Chromium을 자체적으로 찾으므로 playwright install을 실행하지 마십시오.

6. 렌더링 및 확인

node <skill>/scripts/render.mjs --url http://127.0.0.1:8765/index.html --out <work>/video.mp4

1080p30에서 80초 기준 약 3-5분 소요. 완료 후 MP4 자체에서 씬 전환 시점의 프레임을 추출하여(ffmpeg -ss <t> -i video.mp4 -frames:v 1 x.jpg) 단일 정지 이미지로는 발견할 수 없는 전환 문제를 잡습니다.

7. 음악

사용자가 트랙을 보내면:

python3 <skill>/scripts/music.py analyze track.mp3             # 인트로, 드롭, 브레이크다운 찾기
python3 <skill>/scripts/music.py analyze track.mp3 --zoom 14 17 # 드롭을 비트에 정확히 맞추기
python3 <skill>/scripts/music.py mux video.mp4 track.mp3 out.mp4 [--offset s]

목표는 드롭이 브랜드 리빌에서 첫 번째 기능 씬으로의 컷에 맞춰지는 것입니다. --offset을 선택하거나 SCENES를 조정하여 이 위치를 맞춥니다. 음악의 조용한 구간이 어디에 있는지 사용자에게 알려줍니다. 주요 판매 씬이 브레이크다운에 있는 경우 씬 재배치를 제안합니다.

7b. 커서 및 사운드 효과

이 효과들은 비디오가 실제 제품을 사용하는 것처럼 느껴지게 하지만, 각 소리가 화면에서 이를 유발하는 요소가 있을 때만 효과적입니다.

커서: 템플릿의 CURSOR 목록은 2-4개의 클릭 순간을 정의합니다. 커서는 실제 요소로 부드럽게 이동하고(CSS 선택자 기준, 매 프레임 측정되므로 팬을 따라가고 두 방향 모두에서 작동), 누르고, 잔물결을 남깁니다. 각 클릭은 약 0.1-0.3초 후에 무언가를 발생시켜야 합니다: 막대가 채워지고, 단계가 강조되고, 지도가 펼쳐지고, 타이핑이 시작됩니다. 필요하면 반응의 data-in을 이동합니다. 미리보기에서 클릭할 대상이 이미 나타났는지 확인하십시오; 아직 그려지지 않은 노드를 클릭하면 깨져 보입니다. 대상에 적합한 선택자가 없으면 init()에서 id를 부여하십시오(예: mermaid 노드를 레이블 텍스트로 찾기).

사운드:

node <skill>/scripts/cues.mjs --url http://127.0.0.1:8765/index.html --out <work>/cues.json
python3 <skill>/scripts/sfx.py mix <work>/cues.json --duration <DURATION> --out <work>/sfx.wav
python3 <skill>/scripts/sfx.py final <work>/video.mp4 --sfx <work>/sfx.wav --music track.mp3 [--offset s] --out <work>/final.mp4

cues.mjs는 애니메이션 자체의 타이밍에서 사운드를 배치하므로, 언제든지 리타임해도 고정된 상태를 유지합니다. JS로 구동되는 카운터(data-count 대신), 타이핑, 후크 착지 등 스크립트가 볼 수 없는 것은 window.SFX_EXTRA에 넣습니다. 드물게 사용하십시오: 헤드라인 진입 시 소리 없음, 카운터 그룹당 하나의 틱 실행. 바쁜 기업 트랙에서 효과가 좋았던 게인: 클릭 약 -1 dB, 키 약 -6, 틱 약 -8, 팝 -11, 스우시 -10 ~ -14. 사운드가 묻히지 않는지 확인하려면 >2.5 kHz 대역에서 음악과 비교하십시오(둘 다 하이패스 필터링, 피크 비교); 전체 대역 피크는 음악의 베이스가 지배적이므로 오해의 소지가 있습니다. 효과가 묻혀 있다고 느껴지면 효과 게인을 올리기 전에 --music-gain(기본값 -6)을 낮추십시오. final은 하나의 정적 게인으로 음량을 설정합니다. 동적 loudnorm은 클릭을 평탄화하기 때문입니다. sfx.py kit <dir>은 모든 사운드를 WAV 파일로 작성하여 청취할 수 있게 합니다.

8. 세로 9:16

템플릿은 방향을 인식합니다: 동일한 페이지를 --w 1080 --h 1920으로 렌더링하면 세로 미디어 쿼리가 적용됩니다(헤드라인은 전체 너비 카드 위에 쌓이고, 주요 콘텐츠는 y≈250과 y≈1550 사이에 유지되어 소셜 앱의 오버레이를 피합니다). 세로에서만 발생해야 하는 줄 바꿈에는 <br class="br-v">를 사용하십시오. 템플릿(예제처럼)에서 빌드되지 않은 컴포지션의 경우 세로 위치로 vertical.html 복사본을 만드십시오. 세로 프레임도 미리보기하십시오. 텍스트 줄 바꿈이 다르게 발생할 수 있기 때문입니다.

9. 짧은 릴 (15초)

세로 비디오가 존재하면 그로부터 2-4개의 짧은 릴을 자릅니다. 각 릴은 하나의 앵글(하나의 고통, 하나의 기능 클러스터)을 가지므로 각각 별도의 광고나 게시물로 테스트할 수 있습니다. 아무것도 다시 빌드하지 마십시오: 세로 컴포지션에서 시간 범위를 선택하고 cutdown.py가 렌더링하고 결합하도록 합니다.

python3 <skill>/scripts/cutdown.py --url http://127.0.0.1:8765/vertical.html \
  --seg 3.2-6.2 --seg 6.5-9.0 --seg 15.4-20.9 --seg 75.6-79.6 \
  --out <work>/reel1.mp4 --music track.mp3 --drop 15.0 --sfx

--sfx는 각 세그먼트의 사운드 큐를 컴포지션에서 가져와 릴에 맞춰 재타이밍하고 음악과 믹싱합니다.

세그먼트 선택( references/story-and-copy.md의 "Short reels" 참조):

  • 구조: 후크(2.5–3초) → 1–2 기능 비트(각 4–5.5초) → 엔드 카드(4초). 총 15초.
  • 씬이 완전히 페이드 인된 후(씬 시작 + 약 0.5초) 또는 키 진입 시점에 각 세그먼트를 시작하고, 페이오프가 완료된 후(카운터 완료, 칩 팝, 하이라이트 켜짐)에 종료합니다. 컴포지션의 data-in/카운트 시간을 확인하십시오. 카운터가 중간에 잘리는 것이 전형적인 실수입니다.
  • 로고가 팝된 후 약 0.6초 후에 엔드 카드 세그먼트를 시작하여 URL이 3초 이상 화면에 표시되도록 합니다.
  • 각 세그먼트 길이를 비트(120 BPM에서 0.5초)의 배수로 유지하여 모든 컷이 비트에 맞도록 하고 --drop을 전달하여 드롭이 첫 번째 컷에 맞춰지도록 합니다.
  • 릴의 첫 번째 프레임은 이미 후크를 보여주어야 합니다. 느린 페이드 인을 위한 시간이 없습니다.

렌더링 후 완성된 MP4의 각 세그먼트 중간과 끝에서 프레임을 추출하여 확인합니다. 그런 다음 사용자에게 어떤 릴을 먼저 게시할지(문제를 여는 릴), 어떤 릴이 따뜻한 잠재 고객 전용인지(고통 없는 순수한 시각적 즐거움), 세부 사항은 이 속도에서 읽을 수 없으므로 후크도 게시물 캡션에 포함해야 한다고 알려줍니다.

10. 전달

MP4 파일을 사용자에게 파일로 전송합니다. 그런 다음 솔직한 비판을 제공합니다: 총 길이(80초는 깁니다; 30–45초가 Reels/Shorts에 적합), 가장 약한 씬, 하나의 구체적인 컷 또는 재배치. 다음 단계를 제안합니다: 세로 컷, 15초 릴, 음악, 트림. 요청하지 않는 한 비디오 파일이나 빌드 소스를 제품 저장소에 커밋하지 마십시오.

출하 체크리스트

  • 화면의 모든 숫자/이름이 제품의 실제 출력과 일치합니다.
  • 사용자가 제외하도록 요청한 사항이 어디에도 나타나지 않습니다.
  • 미리 본 모든 프레임에 [placeholder] 텍스트, 잘리거나 겹치는 요소가 없습니다.
  • 후크 숫자는 처음 5초 내에 표시됩니다; URL은 마지막에 최소 3초 이상 화면에 표시됩니다.
  • 정지 이미지뿐만 아니라 인코딩된 MP4에서도 전환이 확인되었습니다.
  • 음악(있는 경우)이 트리밍, 페이드 아웃, 정규화되었으며 드롭이 씬 컷에 맞춰집니다.
  • 모든 커서 클릭은 이미 표시된 요소에 착지하며 무언가를 발생시킵니다.
  • 클릭, 키, 틱이 음악 위에서 들립니다(>2.5 kHz 대역 확인), 최종 믹스는 -16 LUFS입니다.
  • 릴: 모든 세그먼트가 페이오프 후에 종료됩니다(미완성 카운터 없음), URL이 3초 이상 표시되고, 컷이 비트에 맞습니다.

관련 스킬