clipwise 0.2.1 → 0.3.0

package/README.ko.md

@@ -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,38 @@ speedRamp:
   actionSpeed: 0.8
 ```
 
+## 출력 압축
+
+`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

@@ -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"
@@ -283,21 +283,40 @@ speedRamp:
 
 ## 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 +346,7 @@ effects:
 output:
   format: mp4
   fps: 30
-  quality: 80
+  preset: social    # social | balanced | archive
 
 steps:
   - name: "Open app"