clipwise 0.2.1 → 0.4.0

package/README.ko.md

@@ -5,7 +5,7 @@
 YAML 시나리오를 작성하면 시네마틱 데모 영상(MP4/GIF)을 자동으로 만들어주는 스크린 레코더. Playwright CDP 기반.
 
 <p align="center">
-  <img src="https://github.com/kwakseongjae/clipwise/releases/download/v0.1.0/demo.gif" width="100%" alt="Clipwise Demo" />
+  <video src="https://kwakseongjae.github.io/clipwise/demo.mp4" autoplay loop muted playsinline width="100%"></video>
 </p>
 
 > *`npx clipwise demo` 한 줄로 생성된 영상입니다.*
@@ -100,7 +100,7 @@ output:
   width: 1280
   height: 800
   fps: 30                  # 1-60
-  quality: 80              # 1-100 (MP4: CRF에 매핑)
+  preset: social           # social | balanced | archive
 
 steps:
   - name: "스텝 이름"
@@ -272,6 +272,52 @@ speedRamp:
   actionSpeed: 0.8
 ```
 
+## 성능
+
+**Apple M1 Max (10코어)** 기준 — Pulse Dashboard 데모, 44초 @ 30fps, 1280×800:
+
+| 단계 | v0.3.0 | v0.4.0 | 변화 |
+|------|--------|--------|------|
+| 녹화 | 30.8 s | 31.1 s | — |
+| 합성 + 인코딩 | 97.2 s | 60.6 s | **−38%** |
+| **전체** | **127.9 s** | **91.7 s** | **−28%** |
+| ms / 프레임 | 69 ms | 67 ms | −3% |
+| 캡처 프레임 수 | 1,303 | 902 | −31% (중복 제거) |
+
+v0.4.0 주요 최적화: 동시 스트리밍 파이프라인, 정적 프레임 중복 제거(~33% 건너뜀), 워커별 StaticLayers 캐시, raw RGBA 버퍼 파이프라인.
+
+## 출력 압축
+
+`preset` 필드로 화질과 파일 크기를 조절합니다:
+
+```yaml
+output:
+  format: mp4
+  fps: 30
+  preset: social      # social | balanced | archive
+```
+
+| 프리셋 | libx264 CRF | HEVC VideoToolbox q:v | 용도 |
+|--------|-------------|----------------------|------|
+| `social` | 22 | 60 | Twitter, LinkedIn 등 소셜 공유 (~2-4 MB / 30초) |
+| `balanced` | 18 | 70 | 범용, 포트폴리오 (~4-6 MB / 30초) |
+| `archive` | 13 | 80 | 고화질 보관, 소스 마스터 (무제한) |
+
+**권장**: 대부분의 데모에는 `preset: balanced`.
+
+> **레거시**: `quality: 1-100`은 계속 작동하며 가장 가까운 프리셋으로 매핑됩니다 (`>= 75` → social, `>= 45` → balanced, `< 45` → archive). 명확성을 위해 `preset` 사용을 권장합니다.
+
+### macOS — 하드웨어 가속
+
+**Apple Silicon 및 Intel Mac**에서 Clipwise는 자동으로 `hevc_videotoolbox` (HEVC/H.265) 하드웨어 인코더를 사용합니다. 별도 설정 없이 소프트웨어 인코딩 대비 **~5–10× 빠른 인코딩** 속도를 제공합니다.
+
+```
+macOS (HEVC VideoToolbox)  →  44초짜리 1280×800 데모 기준 약 3분
+Linux / Windows            →  동일 품질 기준 약 8–12분 (libx264)
+```
+
+VideoToolbox는 런타임에 자동 감지되며, 사용 불가 시 `libx264`로 자동 폴백합니다.
+
 ## AI로 시나리오 작성
 
 [PROMPTS.md](./PROMPTS.md)에 바로 사용할 수 있는 AI 프롬프트 템플릿이 있습니다. ChatGPT나 Claude에 복붙하고 내 사이트 URL만 넣으면 YAML 시나리오를 생성해줍니다.

package/README.md

@@ -5,7 +5,7 @@
 Scriptable cinematic screen recorder for product demos — YAML in, polished MP4 out. Powered by Playwright CDP.
 
 <p align="center">
-  <img src="https://github.com/kwakseongjae/clipwise/releases/download/v0.1.0/demo.gif" width="100%" alt="Clipwise Demo" />
+  <video src="https://kwakseongjae.github.io/clipwise/demo.mp4" autoplay loop muted playsinline width="100%"></video>
 </p>
 
 > *Generated with `npx clipwise demo` — zero config, one command.*
@@ -100,7 +100,7 @@ output:
   width: 1280
   height: 800
   fps: 30                  # 1-60
-  quality: 80              # 1-100 (MP4: maps to CRF)
+  preset: social           # social | balanced | archive
 
 steps:
   - name: "Step name"
@@ -281,23 +281,56 @@ speedRamp:
   actionSpeed: 0.8      # Slow factor near clicks
 ```
 
+## Performance
+
+Measured on **Apple M1 Max (10 cores)** — Pulse Dashboard demo, 44s @ 30fps, 1280×800:
+
+| Stage | v0.3.0 | v0.4.0 | Change |
+|-------|--------|--------|--------|
+| Recording | 30.8 s | 31.1 s | — |
+| Compose + Encode | 97.2 s | 60.6 s | **−38%** |
+| **Total** | **127.9 s** | **91.7 s** | **−28%** |
+| ms / frame | 69 ms | 67 ms | −3% |
+| Frames captured | 1,303 | 902 | −31% (dedup) |
+
+Key optimisations in v0.4.0: concurrent streaming pipeline, static frame deduplication (~33% skipped), per-worker StaticLayers cache, and raw RGBA buffer pipeline.
+
 ## Output Compression
 
-MP4 output uses `libx264` with `slow` preset and `animation` tuning for best quality-per-byte. The `quality` field maps to CRF:
+Use the `preset` field to control quality and file size:
 
-| quality | CRF | Use case |
-|---------|-----|----------|
-| 90-100 | 0-5 | Lossless / archival |
-| 70-85 | 8-15 | High quality demos |
-| 50-70 | 15-26 | Web sharing |
-| 30-50 | 26-36 | Small file size |
+```yaml
+output:
+  format: mp4
+  fps: 30
+  preset: social      # social | balanced | archive
+```
+
+| Preset | libx264 CRF | HEVC VideoToolbox q:v | Target use case |
+|--------|-------------|----------------------|-----------------|
+| `social` | 22 | 60 | Twitter, LinkedIn, Loom-style sharing (~2-4 MB / 30s) |
+| `balanced` | 18 | 70 | General purpose, portfolio sites (~4-6 MB / 30s) |
+| `archive` | 13 | 80 | High-fidelity storage, source masters (uncapped) |
+
+**Recommended**: `preset: balanced` for most demos.
+
+> **Legacy**: `quality: 1-100` still works and maps to the nearest preset (`>= 75` → social, `>= 45` → balanced, `< 45` → archive). Prefer `preset` for clarity.
+
+### macOS — Hardware Acceleration
+
+On **Apple Silicon and Intel Mac**, Clipwise automatically uses `hevc_videotoolbox` (HEVC/H.265) for hardware-accelerated encoding. This delivers **~5–10× faster encoding** than software `libx264` with no setup required.
+
+```
+macOS (HEVC VideoToolbox)  →  ~3 min wall time for a 44s, 1280×800 demo
+Linux / Windows            →  ~8–12 min wall time (libx264, same quality)
+```
 
-**Recommended**: `quality: 80` for most demos (CRF ~10, good visual quality, ~3-7 MB for 30s).
+VideoToolbox is detected at runtime — no config needed. If VideoToolbox is unavailable, it falls back to `libx264` automatically.
 
 For further compression after export:
 
 ```bash
-# Re-encode with tighter CRF
+# Re-encode with tighter settings
 ffmpeg -i input.mp4 -c:v libx264 -crf 26 -preset slow -movflags +faststart output.mp4
 
 # Convert to WebM (smaller, web-native)
@@ -327,7 +360,7 @@ effects:
 output:
   format: mp4
   fps: 30
-  quality: 80
+  preset: social    # social | balanced | archive
 
 steps:
   - name: "Open app"