스크립터블 · 시네마틱 · 제로 컨피그

YAML 작성.
완성된 MP4 출력.

YAML 시나리오를 작성하면 시네마틱 데모 영상(MP4/GIF)을 자동으로 만들어주는 스크린 레코더. Playwright CDP 기반. 위 데모 영상은 YAML 파일 1개, 239줄로 만들었습니다.

npx clipwise demo
GitHub 보기 npm
기능

데모 영상에 필요한 모든 것

YAML 시나리오를 작성하고 녹화하면 — Clipwise가 모든 시네마틱 효과를 처리합니다.

📄
YAML 시나리오
간단한 YAML 파일로 데모를 기술하세요. 스텝, 액션, 타이밍, 이펙트를 코드 없이 정의할 수 있습니다.
🎬
시네마틱 이펙트
적응형 줌, 커서 트레일, 클릭 리플, 속도 램프, 배경 그라디언트, 페이드 전환 효과.
📱
디바이스 프레임
설정 한 줄로 브라우저, iPhone, iPad, Android 목업으로 감쌀 수 있습니다.
⚡
제로 컨피그 데모
npx clipwise demo 한 줄로 내장 대시보드를 즉시 녹화 — 설정 불필요.
🔧
CLI + 프로그래밍 API
CLI로 빠른 녹화, 또는 TypeScript API로 고급 워크플로에 통합할 수 있습니다.
🎯
Playwright 기반
Playwright CDP를 통한 픽셀 퍼펙트 프레임 캡처. 매번 일관된 결과를 보장합니다.
⚡
빠른 파이프라인
Sharp 배치 파이프라인 (합성 3배 빠름, 23ms/프레임). 스프링 물리 줌, 줌 영역 연속성, 로더 자동 감지, smartWait + smartSpeed API 대기 압축. HEVC 10-bit + AV1 코덱 지원.
빠른 시작

60초 안에 시작하기

Clipwise를 설치하고 데모를 실행하거나 직접 시나리오를 작성해보세요.

1
설치
dev 의존성으로 추가하거나 npx로 설치 없이 사용할 수 있습니다.
bash
npm install -D clipwise
2
내장 데모 실행
내장 대시보드를 시네마틱 이펙트와 함께 녹화합니다. 설정 불필요.
bash
npx clipwise demo
npx clipwise demo --device iphone      # iPhone 목업
npx clipwise demo --device android     # Android 목업
npx clipwise demo --url https://kwakseongjae.github.io/clipwise/demo/  # 내 사이트
3
직접 시나리오 작성
템플릿을 생성하고 URL을 내 사이트로 변경한 후 녹화하세요.
bash
npx clipwise init                             # clipwise.yaml 생성
# clipwise.yaml 편집 — URL을 내 사이트로 변경
npx clipwise record clipwise.yaml -f mp4      # 녹화!

프로그래밍 API

typescript
import { ClipwiseRecorder, CanvasRenderer, encodeMp4, loadScenario } from "clipwise";

const scenario = await loadScenario("my-scenario.yaml");
const recorder = new ClipwiseRecorder();
const session  = await recorder.record(scenario);

const renderer = new CanvasRenderer(scenario.effects, scenario.output, scenario.steps);
const frames   = await renderer.composeAll(session.frames);
const mp4      = await encodeMp4(frames, scenario.output);
Claude Code

AI 기반 워크플로

내장된 Claude Code 스킬을 설치하면 자연어로 시나리오를 생성할 수 있습니다. 설치 한 번, 슬래시 커맨드 한 번이면 끝.

1
스킬 설치
Clipwise 스킬을 .claude/skills/ 디렉토리에 복사합니다. 프로젝트당 한 번(또는 글로벌) 실행.
bash
npx clipwise install-skill
2
Claude Code에서 사용
Claude Code 세션에서 /clipwise를 입력하세요. 녹화할 내용을 자연어로 설명하면 됩니다.
Claude Code
/clipwise
> http://localhost:3000 대시보드 데모 녹화해줘
  — 로그인 클릭, 이메일/비밀번호 입력, 분석 페이지 이동
3
나머지는 Claude가 처리
Claude가 YAML 시나리오를 생성하고, npx clipwise validate로 검증한 후, MP4를 녹화합니다 — 전부 자동.

clipwise 업그레이드 후 npx clipwise install-skill을 다시 실행하면 최신 스킬로 업데이트됩니다.

이펙트

시네마틱 이펙트

모든 이펙트는 선택사항이며 합리적인 기본값이 있습니다. 원하는 스타일로 조합하세요.

줌
커서를 따라가며 클릭 대상에 자동으로 줌인합니다. 스마트 카메라: 스크롤 중 줌 자동 억제, 커서 위치 추적. 강도 프리셋(subtle → dramatic) 또는 숫자 스케일 설정.
followCursor intensity smart camera 
zoom:
  enabled: true
  intensity: light   # subtle|light|moderate|strong|dramatic
  duration: 800
커서
커스텀 커서 + 클릭 리플 + 트레일 + 하이라이트 + 속도 조절.
trail highlight clickEffect 
cursor:
  enabled: true
  speed: "normal"
  trail: true
  highlight: true
배경
그라디언트/단색 패딩 + 라운드 코너 + 드롭 섀도.
gradient shadow 
background:
  type: gradient
  value: "linear-gradient(135deg,
    #667eea 0%, #764ba2 100%)"
  padding: 48
  borderRadius: 14
디바이스 프레임
브라우저, iPhone, iPad, Android 목업으로 녹화를 감쌉니다.
browser iphone android 
deviceFrame:
  enabled: true
  type: browser   # or iphone/ipad/android
  darkMode: true
키스트로크 HUD
타이핑 내용을 화면 하단에 실시간으로 표시합니다. 멀티세션: 각 입력 필드가 별도 줄로 표시 (최대 3줄, 오래된 줄은 흐리게). 기본은 단축키만 — showTyping: true로 일반 타이핑도 표시.
bottom-center multi-session 
keystroke:
  enabled: true
  showTyping: true   # 기본: false
  position: bottom-center
  fontSize: 16
  fadeAfter: 1500
속도 램프
클릭 근처 슬로우모션, 유휴 구간 자동 빨리감기.
idleSpeed actionSpeed 
speedRamp:
  enabled: true
  idleSpeed: 3.0
  actionSpeed: 0.8
YAML 형식

시나리오 구조

시나리오는 4개 섹션으로 구성됩니다: 메타데이터, 이펙트, 출력, 스텝.

clipwise.yaml
name: "My Demo"
description: "선택 설명"

viewport:
  width: 1280    # 브라우저 너비 (기본: 1280)
  height: 800    # 브라우저 높이 (기본: 800)

effects:
  # 아래 "이펙트" 섹션 참조

output:
  format: mp4              # gif | mp4 | png-sequence
  width: 1280
  height: 800
  fps: 30                  # 1-60
  preset: balanced         # social | balanced | archive

steps:
  - name: "스텝 이름"
    actions:
      - action: navigate
        url: "https://example.com"
    captureDelay: 200       # 액션 후 대기(ms)
    holdDuration: 800       # 결과 화면 유지(ms)
    transition: none        # none | fade | slide-left | slide-up | blur
    effects:                # 스텝별 이펙트 오버라이드 (선택)
      zoom:
        enabled: false      # 이 스텝에서만 줌 비활성화

기본 액션

액션 파라미터 기본값 설명
navigateurl, waitUntil?networkidleURL로 이동
clickselector, delay?, timeout?요소 클릭
typeselector, text, delay?, timeout?delay: 50텍스트 입력 (한 글자씩)
hoverselector, timeout?요소에 마우스 올리기
scrolly?, x?, selector?, smooth?, timeout?smooth: true스크롤
waitduration대기 (ms)
screenshotname?, fullPage?fullPage: false캡처 마커

비동기 대기 액션

액션 파라미터 기본값 설명
waitForSelectorselector, state?, timeout?visible, 15s요소 상태 대기
waitForNavigationwaitUntil?, timeout?networkidle, 15s페이지 로드 대기
waitForURLurl, timeout?15sURL 매칭 대기
waitForFunctionexpression, polling?, timeout?raf, 30sJS 표현식이 truthy가 될 때까지 대기
waitForResponseurl, status?, timeout?30s네트워크 응답 대기 (URL 부분 문자열 매칭)
yaml — 비동기 대기 예시
# API 호출 후 요소 대기
- action: waitForSelector
  selector: ".result-panel"
  state: visible
  timeout: 20000

# AI 스트리밍 완료 대기
- action: waitForFunction
  expression: "document.querySelector('.ai-response')?.dataset.done === 'true'"
  timeout: 60000

# 특정 API 응답 대기
- action: waitForResponse
  url: "/api/chat/completions"
  status: 200
  timeout: 60000
AI-Ready

AI 도구를 위한 전체 스키마

전체 YAML 스키마 레퍼런스를 복사하세요. Claude Code, Cursor, ChatGPT 등 AI 도구에 붙여넣으면 즉시 시나리오를 생성할 수 있습니다.

전체 스키마 레퍼런스

이 블록에는 AI가 필요한 모든 정보가 담겨 있습니다: 13종 액션 타입, 파라미터, 기본값, 이펙트 설정, 출력 옵션, 사용 규칙.

yaml — Clipwise 전체 스키마 레퍼런스
# Clipwise YAML Schema Reference (v0.7.2)
# 스크립터블 시네마틱 스크린 레코더 — YAML 작성, MP4 출력
# 설치: npm install -D clipwise
# 녹화: npx clipwise record scenario.yaml -f mp4

# ─── 최상위 구조 ──────────────────────────────────────
name: "시나리오 이름"             # 필수
description: "설명"              # 선택
viewport:
  width: 1280                    # 기본: 1280
  height: 800                    # 기본: 800

# ─── 출력 ─────────────────────────────────────────────
output:
  format: mp4                    # mp4 | gif | png-sequence
  fps: 30                        # 1-60 (기본: 30)
  preset: balanced               # social | balanced | archive (기본: balanced)
  codec: auto                    # auto | h264 | hevc | av1 (기본: auto)
  width: 1280                    # 기본: 1280
  height: 800                    # 기본: 800

# ─── 인증 (선택) ─────────────────────────────────────
auth:
  storageState: ./auth.json      # Playwright storageState 파일 경로
  cookies:                       # 또는 인라인 쿠키
    - name: session_id
      value: abc123
      domain: .example.com
      path: /                    # 기본: /
      httpOnly: false            # 기본: false
      secure: false              # 기본: false
      sameSite: Lax              # Strict | Lax | None (기본: Lax)

# ─── 오디오 (MP4 전용) ───────────────────────────────
audio:
  file: "./narration.mp3"        # MP3, WAV 등
  volume: 1.0                    # 0.0 - 2.0 (기본: 1.0)
  fadeIn: 0                      # 초 (기본: 0)
  fadeOut: 0                     # 초 (기본: 0)

# ─── 스텝 ─────────────────────────────────────────────
steps:
  - name: "스텝 이름"            # 선택
    captureDelay: 200            # 액션 후 대기 ms (기본: 300)
    holdDuration: 800            # 결과 화면 유지 ms (기본: 1500)
    transition: none             # none | fade | slide-left | slide-up | blur
    effects:                     # 스텝별 오버라이드 (선택, 글로벌 상속)
      zoom:
        enabled: false           # 이 스텝에서만 줌 비활성화
    actions:
      # --- 기본 액션 (7종) ---
      - action: navigate
        url: "https://example.com"
        waitUntil: networkidle   # load | domcontentloaded | networkidle (기본)

      - action: click
        selector: "#btn"         # CSS 셀렉터 (유니코드/한국어 OK)
        delay: 0                 # 선택. 클릭 딜레이 (ms)
        timeout: 15000           # 선택. 요소 대기 타임아웃 (ms)

      - action: type
        selector: "#input"
        text: "hello"
        delay: 50                # 글자당 딜레이 ms (기본: 50)
        timeout: 15000           # 선택. 요소 대기 타임아웃 (ms)

      - action: hover
        selector: ".menu"
        timeout: 15000           # 선택

      - action: scroll
        y: 400                   # 수직 px (기본: 0)
        x: 0                     # 수평 px (기본: 0)
        selector: ".container"   # 선택. 대상 요소
        smooth: true             # 기본: true
        timeout: 15000           # 선택

      - action: wait
        duration: 1000           # ms

      - action: screenshot
        name: "결과"             # 선택
        fullPage: false          # 기본: false

      # --- 비동기 대기 액션 (5종 + smartWait) ---
      - action: waitForSelector
        selector: ".result"
        state: visible           # visible (기본) | attached | hidden
        timeout: 15000           # 기본: 15000
        captureWhileWaiting: false  # true = 대기 중 프레임 캡처 (기본: false)
        displaySpeed: 8          # 캡처된 대기 프레임 속도 배율 (1-32)

      - action: waitForNavigation
        waitUntil: networkidle   # load | domcontentloaded | networkidle (기본)
        timeout: 15000           # 기본: 15000
        captureWhileWaiting: false
        displaySpeed: 8

      - action: waitForURL
        url: "https://example.com/dashboard"
        timeout: 15000           # 기본: 15000
        captureWhileWaiting: false
        displaySpeed: 8

      - action: waitForFunction
        expression: "document.querySelector('.done') !== null"
        polling: raf             # raf (기본) 또는 밀리초 숫자 (예: 500)
        timeout: 30000           # 기본: 30000
        captureWhileWaiting: false
        displaySpeed: 8

      - action: waitForResponse
        url: "/api/chat"         # URL 부분 문자열 매칭
        status: 200              # 선택. HTTP 상태코드 필터 (100-599)
        timeout: 30000           # 기본: 30000
        captureWhileWaiting: false
        displaySpeed: 8

      # --- 스마트 대기 (녹화 + 자동 압축) ---
      - action: smartWait
        until: networkIdle       # networkIdle | selector | domStable
        selector: ".result"      # until=selector일 때 필수
        timeout: 30000           # 기본: 30000
        displaySpeed: 8          # 속도 배율 (1-32, 기본: 8)

# ─── 이펙트 ───────────────────────────────────────────
effects:
  zoom:
    enabled: true                # 기본: true
    intensity: light             # subtle(1.15x)|light(1.25x)|moderate(1.35x)|strong(1.5x)|dramatic(1.8x)
    # scale: 1.25               # 숫자 오버라이드 (1-5); intensity 설정 시 무시
    duration: 800                # ms (기본: 800)
    easing: ease-in-out          # ease-in-out | ease-in | ease-out | linear | spring
    autoZoom:
      followCursor: true         # 커서 위치를 따라 뷰포트 패닝
      transitionDuration: 300    # ms (기본: 300)
      padding: 200               # px (기본: 200)
    # 스마트 카메라: 스크롤 중 줌 자동 억제
  cursor:
    enabled: true                # 기본: true
    size: 20                     # px (기본: 20)
    color: "#000000"             # 기본: #000000
    speed: normal                # fast (~72ms) | normal (~144ms) | slow (~288ms)
    clickEffect: true            # 기본: true
    clickColor: "rgba(59,130,246,0.3)"
    trail: true                  # 기본: true
    trailLength: 6               # 기본: 6
    highlight: true              # 기본: true
    highlightRadius: 35          # 기본: 35
  background:
    type: gradient               # gradient | solid | image (기본: gradient)
    value: "linear-gradient(135deg, #667eea 0%, #764ba2 100%)"
    padding: 48                  # px (기본: 48)
    borderRadius: 14             # px (기본: 14)
    shadow: true                 # 기본: true
  deviceFrame:
    enabled: false               # 기본: false
    type: browser                # browser | iphone | ipad | android | none
    darkMode: false              # 기본: false
  keystroke:
    enabled: false               # 기본: false
    showTyping: false            # 타이핑 표시 (기본: false — 단축키만)
    position: bottom-center      # bottom-center | bottom-left | bottom-right
    fontSize: 16                 # 기본: 16
    fadeAfter: 1500              # ms (기본: 1500)
  speedRamp:
    enabled: false               # 기본: false
    idleSpeed: 2.0               # 기본: 2.0
    actionSpeed: 0.8             # 기본: 0.8
  smartSpeed:
    enabled: false               # 기본: false
    waitSpeed: 8                 # smartWait 프레임 속도 (1-32, 기본: 8)
    idleSpeed: 4                 # 유휴 프레임 속도 (1-16, 기본: 4)
    transitionDuration: 300      # 속도 전환 ease 시간 (ms)
    minSegmentDuration: 500      # 이보다 짧은 구간은 가속하지 않음 (ms)
  watermark:
    enabled: false               # 기본: false
    text: ""
    position: bottom-right       # top-left | top-right | bottom-left | bottom-right
    opacity: 0.5                 # 0-1 (기본: 0.5)

# ─── 규칙 ─────────────────────────────────────────────
# - 셀렉터: CSS 선택자 (#id, .class, [data-*], [aria-label="..."])
# - 유니코드/한국어 셀렉터 지원
# - 클릭/타이핑 전 요소가 화면에 보여야 함 — 필요하면 scroll 먼저
# - type 전에 click으로 input 포커스
# - 고정 wait보다 비동기 대기 액션 우선 사용 (더 안정적)
# - waitForFunction: AI 스트리밍, 동적 콘텐츠, DOM 변화 감지
# - waitForResponse: 트리거 액션 전에 자동으로 리스너 등록됨
# - 타이밍: captureDelay 50-100ms, holdDuration 500-800ms (빠른 데모)
# - 스텝별 이펙트: 글로벌 이펙트를 스텝 단위로 오버라이드 가능
# - 스마트 카메라: 스크롤 중 줌 억제; followCursor로 커서 추적
# - 트랜지션: fade/blur는 시네마틱 컷, slide-left/up은 순차 흐름에 적합
# - 오디오: MP4 포맷에서만 작동; 파일 경로가 유효해야 함
# - 인증: 로그인 필요 페이지는 storageState 사용 (playwright codegen으로 생성)
# - captureWhileWaiting: 비동기 대기 중 로딩 애니메이션 캡처 시 true 설정
# - 스프링 줌: easing: spring으로 Screen Studio 스타일 자연스러운 카메라 모션
# - 코덱: av1 = 최소 파일 크기 (느린 인코딩); hevc = 10비트 컬러; auto = h264
# - type 액션: React/Vue 호환을 위해 input/change 이벤트 자동 dispatch