---
name: web-demo-video
description: 화면 녹화 도구 없이 웹사이트/웹앱의 짧은 제품 데모·소개 영상(SNS용 1:1, 9:16, 16:9)을 만들 때 사용. 실제 사이트를 iframe에 띄워 진짜 마우스 이벤트로 조작하면서 프레임을 캡처하고 ffmpeg로 합성한다.
---

# 웹 데모 영상 만들기

밤밤의 웹 프로젝트(모자이크, 겟백앱, 카공메이트 등) 소개 영상을 만들 때 쓰는 절차.
목업 이미지를 이어붙이는 게 아니라 **실제 사이트를 실제로 조작한 화면**을 찍는 게 핵심이다.

## 먼저 물어볼 것

영상은 어디 쓰느냐로 비율·길이가 갈린다. **만들기 전에 반드시 확인한다.**

| 용도 | 비율 | 길이 |
|---|---|---|
| 스레드·릴스·쇼츠 | 9:16 (1080x1920) | 15~25초 |
| 블로그·유튜브 임베드·랜딩 | 16:9 (1920x1080) | 30~40초 |
| 인스타 피드·카톡 공유 | 1:1 (1080x1080) | ~20초 |

밤밤은 시각 산출물의 **형식**에 구체적인 기대가 있다. 레퍼런스가 있으면 먼저 달라고 한다.

## 절차

### 1. 로컬 서버로 대상 사이트를 띄운다

```bash
cd <프로젝트> && python3 -m http.server 8899
```

무대(stage) 페이지와 대상 사이트는 **반드시 같은 오리진**이어야 한다.
포트가 다르면 `iframe.contentDocument` 접근이 막혀서 조작이 불가능하다.
→ 무대 파일을 프로젝트 폴더 안에 임시로 두고, **작업이 끝나면 반드시 빼낸다**(안 그러면 다음 배포에 딸려 올라간다).

### 2. 무대 페이지를 만든다

`assets/stage-template.html`를 복사해서 고친다. 구조:

- `#stage` — 출력 비율 그대로의 고정 크기 div (1:1이면 540x540, dpr 2로 캡처하면 1080x1080)
- `#cap` / `#foot` — 큰 자막(상단) / 보조 문구(하단)
- `#win` — 맥 브라우저 창 목업(신호등 3개 + URL) 안에 `<iframe>`을 `transform: scale()`로 축소해 넣음
- `#cursor` — 가짜 마우스 커서 SVG. **이게 있어야 조작 영상처럼 보인다**
- `#ring` — 클릭·브러시 크기를 보여주는 하이라이트 원
- `#end` — 엔딩 카드(제품명 / 한줄 설명 / 셀링포인트 3개 / URL)
- `window.__tick(frameIndex)` — 프레임 번호 하나를 받아 그 시점의 화면 상태를 만드는 **결정론적** 함수

### 3. 타임라인을 결정론적으로 짠다

`__tick(frame)` 안에서 `t = frame / FPS`로 시간을 계산하고, 모든 상태를 t로부터 다시 계산한다.
실시간 `setTimeout`을 쓰면 캡처 속도와 어긋나서 망가진다.

- 1회성 동작(이미지 로드, 모드 전환)은 `once(key, fn)` 으로 중복 실행을 막는다
- 드래그는 `drag(t, 시작초, 끝초, ptFn)` — 시작 프레임에 `mousedown`, 매 프레임 `mousemove`, 끝나면 `mouseup`
- 이벤트는 iframe의 `W.MouseEvent`로 만들어 `clientX/clientY`(iframe 기준 좌표)로 dispatch한다.
  `mousedown`은 대상 요소에, `mousemove`/`mouseup`은 보통 `window`에 붙어 있으니 확인하고 각각 맞는 타깃에 쏜다
- 좌표는 하드코딩하지 말고 **요소의 `getBoundingClientRect()` 또는 그려넣은 목업의 rect 비율**로 계산한다. 창 크기를 바꿔도 안 깨진다
- iframe 안에서 영상에 불필요한 요소(헤더, SEO 본문, 푸터, 광고 배너, 상태줄)는 `iframe` load 시점에 `<style>` 주입으로 숨긴다

### 4. 프레임을 캡처한다

```js
for (let i = from; i <= to; i++) {
  await page.evaluate(f => __tick(f), i);
  const buf = await page.screenshot({ clip: { x:0, y:0, width:540, height:540 } });
  await fs.writeFile(`${DIR}/f${String(i).padStart(4,'0')}.png`, buf);
}
```

- **`clip`은 CSS 픽셀 단위다.** devicePixelRatio를 곱하면 안 된다. dpr 2면 540 클립이 1080px 이미지로 나온다
- 프레임 한 장에 약 0.09초. 400장이면 40초 → REPL 120초 제한 때문에 **100~150장씩 나눠 호출**한다
- 캡처 시작 전에 페이지를 새로 로드해 상태를 초기화하고, `__tick(0)` 후 이미지 로드가 끝날 시간을 준다

### 5. ffmpeg로 합성한다

`ffmpeg`는 PATH에 없다. `export PATH="$PATH:/opt/homebrew/bin"` 를 붙인다.

```bash
ffmpeg -y -framerate 20 -i frames/f%04d.png \
  -vf "scale=1080:1080:flags=lanczos,fps=30" \
  -c:v libx264 -profile:v high -pix_fmt yuv420p -crf 20 -movflags +faststart out.mp4
```

- `-pix_fmt yuv420p`는 SNS 호환 필수
- 채팅에 붙여 보여줄 미리보기 GIF는 palettegen/paletteuse 2패스로:
  `fps=10,scale=420:-1:flags=lanczos,palettegen=stats_mode=diff` → `paletteuse=dither=bayer:bayer_scale=3`
- 콘티 확인용 컨택트시트: `select='eq(n\,20)+...',scale=340:340,tile=3x3`

### 6. 뒷정리

- 무대 파일을 프로젝트 폴더 밖으로 옮긴다 (배포에 섞이면 안 됨)
- 로컬 서버 종료: `lsof -ti:8899 | xargs kill -9`
- 캡처 탭 닫기

## 주의

- 영상에 쓰는 예시 데이터(대화 내용, 이름, 계좌번호, 전화번호, 주소)는 **전부 지어낸 가짜**로 만들고, 보고할 때 가짜라고 명시한다. 밤밤의 실제 개인정보(전세금 등)나 제3자 정보는 절대 넣지 않는다
- 무음이 기본. 음악이 필요하면 밤밤에게 확인받는다
- 완성본은 세션 artifacts에 두되, 다시 뽑을 수 있도록 **무대 파일을 영구 경로에 보관**한다

---

## 부록 · 블로그 본문용 GIF (브라우저 목업 없이)

SNS 영상과 목적이 다르다. 블로그 독자는 **"이 도구가 뭘 하는지"**를 3초 안에 봐야 하므로,
맥 브라우저 창 목업·엔딩 카드 없이 **작업 대상만 크게** 보여주는 편이 낫다.
무대(stage) 페이지도 로컬 서버도 필요 없다. 배포된 사이트를 직접 조작하고 캔버스를 그대로 뜬다.

### 절차

1. 배포 사이트를 열고 예시 이미지를 붙여넣기 이벤트로 주입한다(파일 선택 UI를 거치지 않아도 된다).
   ```js
   await page.evaluate(async (b64) => {
     const blob = await (await fetch('data:image/png;base64,'+b64)).blob();
     const dt = new DataTransfer(); dt.items.add(new File([blob],'s.png',{type:'image/png'}));
     document.dispatchEvent(new ClipboardEvent('paste',{clipboardData:dt,bubbles:true}));
   }, b64);
   ```
2. 영상에 불필요한 요소는 캡처 전에 숨긴다 (`adInCanvas` 같은 광고 영역).
3. **좌표는 반드시 픽셀로 탐지한다. 눈대중 금지.** 이번에 눈대중으로 잡았다가 펜·채우기가 엉뚱한 데
   찍혀서 세 번 다시 찍었다. 캔버스 픽셀을 직접 훑어 대상 글자의 bbox를 구한다.
   ```js
   const bbox = (x0,x1,y0,y1) => { /* 어두운 픽셀(r,g,b<110)의 min/max */ };
   ```
   노란 말풍선 같은 색 블록은 해당 색 범위로 같은 방식으로 찾는다.
4. 프레임은 **캔버스를 새 캔버스에 다시 그려서** 만든다. `page.screenshot({clip})`은 스크롤/DPR 때문에
   좌표가 어긋나기 쉽다. 자막·커서·선택 박스·브러시 원도 이 합성 단계에서 그려 넣는다.
   - 상단에 라벨 띠(무슨 모드를 쓰는지)를 넣으면 GIF 하나로 기능 여러 개를 설명할 수 있다
   - 드래그 중에는 파란 점선 선택 박스를, 펜 모드에서는 브러시 크기 원을 그린다
5. 실제 마우스 이벤트로 조작하면서 매 스텝 프레임을 저장한다. 동작 전후로 **정지 프레임 6~8장**을
   넣어야 눈이 따라간다.
6. ffmpeg 2패스로 GIF 합성 (본문용은 폭 620~640px, 12fps, 70KB 안팎이면 충분).

### 효과 선택 주의

- **단색 영역에 블러를 걸면 화면상 아무 변화가 없다.** 평면 아바타를 블러 처리하는 컷을 넣었다가
  차이가 안 보여서 뺐다. 블러는 디테일이 있는 대상에만 쓴다.
- **펜은 모자이크보다 블러가 깔끔하다.** 펜+모자이크는 블록이 흩뿌려진 것처럼 지저분하게 나온다.
- 가리기 결과를 보여줄 땐 **가린 영역 위로 원본이 삐져나오지 않았는지** 마지막 프레임에서 확인한다.
  살짝 비치면 여백을 더 줘서 한 번 더 덮고 뒤쪽 정지 프레임만 다시 찍으면 된다.

### 어디에 쓰나

- 네이버 블로그: 사진 업로드와 동일하게 `사진` 버튼 → 파일 선택으로 올린다 (GIF도 그대로 애니메이션된다)
- 티스토리: `첨부 → 사진`. 업로드하면 `[##_Image|...|_##]` 문법이 본문에 들어가므로,
  그걸 읽어서 전체 HTML을 조립한 뒤 `setContent()` 하면 이미지 위치를 원하는 곳에 둘 수 있다
- 사이트 자체: `<figure>` + `loading="lazy"` + 캡션에 "예시 데이터는 전부 가짜"를 명시