🎬 demo-video-skill

만들긴 했는데, 이걸 어떻게 보여주죠?

바이브코딩으로 만든 웹앱·도구, 데모 영상으로 제대로 뽐내세요.
녹화 앱도 영상 편집도 몰라도 됩니다. 코딩 에이전트에게 "데모 영상 만들어줘" 한마디면, 실제로 돌아가는 앱을 조작하는 시연 영상이 완성 mp4로 나옵니다.

_{한국어 · English}

이 스킬로 만든 샘플 데모

_{☝️ 이 클립도 스킬이 직접 만든 것입니다. 실제로 돌아가는 웹앱을 조작하면서 자막바·기능 라벨·가짜 커서·줌을 코드로 굽고, "AI 분석중" 대기 구간을 알아서 압축했습니다. · ▶ 고화질 MP4}

이런 분께 좋습니다

바이브코딩으로 웹앱이나 도구를 뚝딱 만들어 놓고, 정작 "이걸 남에게 어떻게 보여주지?" 에서 막히는 분들을 위해 만들었습니다.

성과를 공유하고 싶은 분 — 스크린샷 몇 장으로는 부족할 때, 실제로 돌아가는 화면을 짧은 영상 한 편으로 보여 줍니다.
업무 보고·내부 발표를 준비하는 분 — 자료 안에 "직접 동작하는 화면"을 넣어 설득력을 더합니다.
포트폴리오·동료 공유가 필요한 분 — 링크나 파일 하나로 깔끔한 시연 영상을 건넵니다.
녹화도 편집도 배운 적 없는 분 — 녹화 앱을 깔 필요도, 편집 타임라인을 만질 필요도 없습니다.

성과 공유, 업무 보고, 포트폴리오, 동료 공유, 내부 발표 — 만든 걸 보여줘야 하는 거의 모든 자리에 바로 씁니다. 만든 결과물이 아깝지 않게, 제대로 뽐내고 쉽게 알릴 수 있게 도와드립니다. 앱을 켜 두고, 에이전트에게 말만 하면 됩니다.

이렇게 씁니다 (초간단 3단계)

1. 앱을 켜 둡니다. 평소처럼 개발 서버를 띄워 두기만 하면 됩니다.
　예: npm run dev → http://localhost:3000

2. 에이전트에게 말합니다. 평범한 우리말로 요청하면 됩니다.
　예: "지식검색 기능 데모 영상 만들어줘."

3. 완성됩니다. 에이전트가 화면을 조작하며 녹화하고, 자막과 커서를 얹고, 지루한 대기 구간을 압축해서 완성된 .mp4를 내놓습니다.

중간에 에이전트는 정해진 순서를 따라갑니다. 대본 → 사용자 승인 → PoC 씬 1편 → 승인 → 전 씬 캡처 → 몽타주 검증 → 최종 합본. 사용자는 나온 결과를 보고 "2초쯤 자막이 겹쳐요" 같은 피드백만 주면 됩니다. 그러면 그 부분만 다시 렌더합니다.

처음부터 다시 찍을 필요가 없습니다. 마음에 안 드는 한 장면만 초 단위로 고칩니다.

결과물은 이렇게 생겼습니다

화면을 손으로 녹화한 것처럼 보이지만, 모든 프레임을 스크립트가 직접 합성합니다. 실제로 영상에 구워 넣는 요소는 아래와 같습니다.

구워진 프레임의 구조

하단 자막바 — 지금 무슨 기능을 보여 주는지 설명하는 자막이 화면 아래에 깔립니다.
기능 라벨 — "1. 지식검색"처럼 현재 시연 중인 기능 이름을 보여 줍니다.
부드러운 가짜 커서 — 마우스가 자연스럽게 움직이며 클릭 지점을 짚어 줍니다.
줌 인/아웃 — 중요한 부분을 확대해 시선을 모읍니다.
대기 구간 압축 — "AI 분석중" 같은 지루한 대기 시간은 자동으로 빠르게 지나갑니다. 28초 대기가 3초로 줄어듭니다.

이렇게 완성된 영상은 그대로 발표 자료에 넣거나, 사내 채널에 공유하거나, 포트폴리오에 붙이기 좋습니다.

_{여기부터는 동작 원리와 설치, 제작 순서, 주의할 점 등 조금 더 자세한 이야기입니다. 직접 스크립트를 돌려 보고 싶은 분을 위한 상세이니, 그냥 에이전트에게 맡길 생각이라면 편하게 건너뛰어도 좋습니다.}

왜 만들었나

제품 데모를 손으로 찍는 일은 지겹습니다. Cap이나 OBS로 화면을 녹화하고, 마우스를 어색하게 움직이고, LLM 스피너를 30초씩 멍하니 보다가, 편집기에서 자르고 붙입니다. 그러다 자막 하나 틀리면 처음부터 다시 찍어야 합니다.

이 스킬은 그 과정 전부를 코딩 에이전트가 코드로 처리하게 만듭니다. 그래서 몇 번이고 다시 돌릴 수 있고, 코드처럼 리뷰할 수 있습니다.

🎥 녹화 앱이 필요 없습니다. Playwright가 실제 앱을 1920×1080 헤드리스로 녹화합니다.
✍️ 오버레이를 코드로 굽습니다. 자막바, 기능 라벨, 가짜 커서, 줌을 DOM/CSS로 주입합니다. 버전 관리도 되고, 손보기도 쉽고, 다시 렌더하는 데 비용이 들지 않습니다.
⚡ 빈 구간을 알아서 압축합니다. LLM이나 로딩을 기다리는 시간을 어림잡지 않고 감지해서 ffmpeg로 6~9배속으로 압축합니다. 28초 대기가 3초로 줄어듭니다.
🔁 초 단위로 고칩니다. "2초쯤 글자가 겹친다" 싶으면 한 줄만 고치고 그 씬만 다시 렌더하면 됩니다. 타임라인을 이리저리 긁을 일이 없습니다.
🤖 에이전트를 가리지 않습니다. 공용 플레이북과 스크립트는 하나로 두고, 주요 코딩 에이전트마다 얇은 진입 파일만 얹었습니다.

실제 제품 기능시연(씬 0~9 + 약 6.5분 합본)에서 다듬어 검증한 파이프라인입니다. 원래 사용자가 릴리스용으로 승인한 것과 같은 방식입니다.

동작 원리

돌아가는 앱을 넣으면 완성된 .mp4가 나옵니다. 중간에 녹화기가 끼어들지 않습니다.

동작 원리

이 결과를 만드는 핵심 아이디어는 세 가지입니다.

오버레이는 <body>가 아니라 <html> 바로 아래에 둡니다. 줌은 body에 transform을 거는데, <html> 자식으로 붙은 자막과 커서는 줌의 영향을 받지 않아 또렷하게 유지됩니다.
가짜 SVG 커서에 CSS transition을 걸어 마우스 움직임을 연출합니다. 헤드리스에서는 실제 커서가 보이지 않고, 이 transition이 곧 Cap 같은 녹화기가 해 주는 커서 스무딩 역할을 대신합니다.
LLM이나 로딩 대기는 waitForFunction으로 감지하고, 걸린 시간을 waitMs에 기록합니다. 덕분에 ffmpeg가 정확히 그 구간만 압축하고 나머지는 건드리지 않습니다.

빈 구간 압축 트릭

직접 돌려 보고 싶다면 (빠른 시작)

에이전트에게 말로 시키는 게 기본이지만, 스크립트를 손수 돌려 보고 싶은 분을 위한 방법입니다.

사전 요건: Node.js 18+, PATH에 등록된 ffmpeg, 그리고 Chromium 계열 브라우저(Chrome/Chromium/Edge — 자동 탐지).

# 1. 스킬을 프로젝트에 넣은 뒤(아래 에이전트별 설치 참고):
mkdir -p /tmp/demoscratch && cd /tmp/demoscratch
npm i playwright-core
# Chrome은 macOS/Linux/Windows에서 자동 탐지됩니다. 필요하면 지정:
#   export CHROME_PATH="/path/to/chrome"
# 시스템 Chrome이 없으면 Playwright 내장 빌드로 대체:
#   npx playwright install chromium

# 2. 앱을 띄워 둡니다 (스킬은 사용자가 띄운 서버를 절대 죽이지 않습니다)
#    예: npm run dev  ->  http://localhost:3000

# 3. 에이전트에게 평범한 말로 요청:
#    "지식검색 기능 데모 영상 만들어줘."

그러면 에이전트가 정해진 순서를 따라갑니다. 대본 → 사용자 승인 → PoC 씬 1편 → 승인 → 전 씬 캡처 → 몽타주 검증 → 최종 합본. 사용자는 검토하고 초 단위로 피드백만 주면 됩니다.

씬 캡처를 직접 돌려 볼 수도 있습니다.

SCR=/tmp/demoscratch APP=http://localhost:3000 LABEL="1. 내 기능" node cap_scene.js
# -> {"waitMs":12300,"webm":"/tmp/demoscratch/clips_raw/....webm"}

source scripts/postprocess.sh
speedup clips_raw/scene.webm clips/1_feature.mp4 12.3 40.1 9   # 대기 구간 압축
montage clips/1_feature.mp4 check.png                          # 3×3 눈검증 (생략 금지)

에이전트별 설치

스킬은 공용 코어(scripts/, references/playbook.md) 하나에 에이전트별 얇은 진입 파일을 얹은 구조입니다. 폴더를 통째로 프로젝트에 넣거나 클론해 두면, 각 에이전트가 자기 파일을 알아서 읽어 갑니다.

하나의 스킬, 모든 코딩 에이전트

에이전트	읽는 진입 파일	위치
Claude Code	`SKILL.md`	`~/.claude/skills/demo-video/` (또는 프로젝트의 `.claude/skills/demo-video/`)
Cursor	`.cursor/rules/demo-video.mdc`	프로젝트 루트
Windsurf	`.windsurfrules`	프로젝트 루트
GitHub Copilot	`.github/copilot-instructions.md`	프로젝트 루트
Codex · Gemini CLI · Aider · Jules · Amp	`AGENTS.md`	프로젝트 루트
그 외 에이전트	룰 파일이 `references/playbook.md`를 가리키게	—

한 줄짜리 설치 스크립트가 알맞은 파일을 대신 복사해 줍니다.

# 리포 루트에서
./install.sh claude   /path/to/your/project     # 또는: cursor | windsurf | copilot | agents | all

진입 파일은 모두 같은 scripts/와 references/playbook.md를 가리킵니다. 그래서 진실의 출처가 하나로 유지되고, 에이전트끼리 내용이 어긋날 일이 없습니다.

제작 순서 — 워크플로 (순서 고정 — 단계마다 이유가 있습니다)

#	단계	이유
1	대본 먼저, 촬영은 승인 후	씬별로 `[진입 · 동작 · 입력 · 줌 · 배속구간 · 자막 · 라벨]` 표를 짜 두면 재촬영 루프에 빠지지 않습니다.
2	환경 확인	`curl`로 대상 서버가 살아 있는지 확인합니다. 사용자가 띄운 서버는 절대 죽이지 않습니다. `playwright-core`를 설치하고 `ffmpeg`가 있는지 확인합니다.
3	PoC 씬 1편 → 승인	열 개를 만들기 전에, 한 씬으로 톤(자막 스타일, 커서 속도, 줌 배율)을 먼저 맞춥니다.
4	씬 캡처	`cap_scene.template.js`를 복사하고 `SEQUENCE` 블록만 바꿉니다. 씬이 3개 이상이면 씬 번호를 인자로 받는 `gen.js` 하나로 처리합니다.
5	후처리 + 몽타주 검증	대기 구간에 배속을 걸고 mp4로 만든 뒤 3×3 몽타주로 눈검증합니다. 자막 겹침이나 줌 어긋남은 지표에 잡히지 않습니다.
6	합본 + 직접 재생	`-c copy`로 이어 붙이고, 프레임을 몇 군데 확인한 다음, 사용자가 직접 재생해서 최종 확정합니다. 그게 완료 조건입니다.

함정 전집, 오버레이 파라미터, 표준 씬 시퀀스, 대본 양식, 크로스플랫폼 노트 같은 상세 내용은 **references/playbook.md**에 있습니다.

주의할 점 — 함정 (절대 어기면 안 되는, 전부 실전에서 겪은 것들)

await ctx.close()를 browser.close()보다 먼저 호출합니다. 안 그러면 .webm이 flush되지 않아 빈 파일이 나옵니다.
goto에는 waitUntil:'networkidle'을 줍니다. 안 그러면 초기 로딩 화면부터 찍힙니다.
LLM 대기에 고정 sleep을 쓰지 않습니다. 응답 시간은 돌릴 때마다 다릅니다. waitForFunction으로 결과를 감지하고 waitMs를 기록합니다.
오버레이는 반드시 <html> 자식이어야 합니다. <body> 아래에 두면 줌에 같이 확대됩니다.
대기 구간 배속은 필수입니다. 배속 없이 LLM을 30초 기다리게 하면 그 사이 시청자가 떠납니다.
완성 판정은 세 단계로 확인합니다. 몽타주 눈검증, 프레임 스팟 확인, 사용자 직접 재생. 자동 지표는 어디까지나 보조입니다.

리포 구성

demo-video-skill/
├── SKILL.md                          # Claude Code 진입 (한/영 병기 트리거)
├── AGENTS.md                         # Codex / Gemini CLI / Aider / Jules 진입
├── .cursor/rules/demo-video.mdc      # Cursor 진입
├── .windsurfrules                    # Windsurf 진입
├── .github/copilot-instructions.md   # GitHub Copilot 진입
├── references/
│   └── playbook.md                   # 상세 — 단일 진실 원천
├── scripts/
│   ├── cap_scene.template.js         # 씬 캡처 골격 (크로스플랫폼 Chrome)
│   └── postprocess.sh                # ffmpeg 레시피: speedup · montage · concat · spotcheck
├── examples/ask-docs/                # 샘플 영상을 만든 실행 가능한 예제
│   ├── app.html · app.ko.html        #   자체 완결형 데모 앱 (영문 / 한글)
│   └── capture.js · capture.ko.js    #   특장점 시연 캡처 씬 (영문 / 한글)
├── assets/                           # 다이어그램 + 샘플 영상 (영문 *.svg·gif, 한글 *.ko.svg·*.ko.gif)
└── install.sh                        # 알맞은 진입 파일을 프로젝트에 복사

FAQ

내 화면을 녹화하나요? 아닙니다. Playwright가 헤드리스 브라우저를 조작하고 그 브라우저만 녹화합니다. 데스크톱이나 다른 창, 실제 커서는 화면에 나오지 않습니다.

내 dev 서버를 건드리나요? 아닙니다. curl로 살아 있는지만 확인하고, 사용자가 띄운 서버는 절대 죽이지 않도록 명시돼 있습니다.

Chrome이 없으면요? npx playwright install chromium을 실행하면 Playwright 내장 빌드를 씁니다. 특정 브라우저를 강제하려면 CHROME_PATH를 지정하면 됩니다.

Windows에서는요? 캡처 스크립트는 크로스플랫폼입니다. postprocess.sh는 WSL이나 Git Bash에서 돌리거나(ffmpeg 필터 문자열은 동일합니다) PowerShell로 포팅하면 됩니다.

자막에 한글이나 이모지가 필요합니다. 폰트가 제대로 렌더되도록 실제 Chrome을 씁니다(자동으로 우선 선택됩니다). 최소 구성 리눅스 컨테이너라면 fonts-noto-cjk를 설치합니다.

모션그래픽 티저를 만드는 도구인가요? 아닙니다. 이건 실제 화면을 조작하는 데모용입니다. 애니메이션이나 모션그래픽 인트로가 필요하면 다른 도구를 쓰면 됩니다.

크레딧 & 라이선스

실제 AI 제품 기능시연을 만드는 과정에서 다듬어 낸 스킬입니다. 기여는 언제든 환영합니다. 이슈나 PR을 열어 주세요.

MIT License로 배포합니다.

🎬 demo-video-skill

만들긴 했는데, 이걸 어떻게 보여주죠?

이런 분께 좋습니다

이렇게 씁니다 (초간단 3단계)

결과물은 이렇게 생겼습니다

왜 만들었나

동작 원리

직접 돌려 보고 싶다면 (빠른 시작)

에이전트별 설치

제작 순서 — 워크플로 (순서 고정 — 단계마다 이유가 있습니다)

주의할 점 — 함정 (절대 어기면 안 되는, 전부 실전에서 겪은 것들)

리포 구성

FAQ

크레딧 & 라이선스

Yorumlar (0)