@t3lnet/sceneforge 1.0.14 → 1.0.16

package/dist/templates/base/cli-reference.md

@@ -103,8 +103,11 @@ sceneforge split --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name (folder in output) |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
 
-**Video Quality:** Encodes with H.264 (libx264), CRF 18, medium preset for high-quality output.
+**Video Quality:** Configurable via `--quality` preset or `--crf`/`--codec` flags. Default: medium preset (CRF 18, libx264).
 
 ### voiceover
 Generate voiceover audio from scripts.
@@ -137,8 +140,11 @@ sceneforge add-audio --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
 
-**Video Quality:** Re-encodes with H.264 (libx264), CRF 18, medium preset. Audio encoded as AAC at 192kbps.
+**Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Audio: AAC 192kbps.
 
 ### concat
 Concatenate step clips into final video.
@@ -152,8 +158,15 @@ sceneforge concat --demo <name> [options]
 |------|-------------|
 | `--demo` | Demo name |
 | `--output`, `-o` | Output directory |
+| `--quality` | Quality preset: low, medium, high (default: medium) |
+| `--crf` | Override CRF value (0-51, lower = better) |
+| `--codec` | Video codec: libx264, libx265 (default: libx264) |
+| `--intro` | Intro video to prepend |
+| `--outro` | Outro video to append |
+| `--music` | Background music file |
+| `--music-volume` | Music volume 0-1 (default: 0.15) |
 
-**Video Quality:** Final encode with H.264 (libx264), CRF 18, medium preset. Includes `+faststart` for web streaming optimization. Audio encoded as AAC at 192kbps.
+**Video Quality:** Configurable via `--quality` preset. Default: medium (CRF 18, libx264). Includes `+faststart` for web streaming. Audio: AAC 192kbps.
 
 ### doctor
 Run environment diagnostics.
@@ -249,24 +262,55 @@ sceneforge record -d demo.yaml -b http://localhost:3000 --headed --slowmo 500
 
 ## Video Quality
 
-SceneForge uses high-quality FFmpeg encoding settings optimized for multi-pass video processing:
+SceneForge provides configurable video quality settings via CLI flags on `split`, `add-audio`, and `concat` commands.
 
-| Setting | Value | Purpose |
-|---------|-------|---------|
-| Codec | `libx264` | H.264 for broad compatibility |
-| Preset | `medium` | Balanced quality/speed tradeoff |
-| CRF | `18` | High quality (visually lossless) |
-| Audio | `aac @ 192k` | High-quality audio |
-| Flags | `+faststart` | Web streaming optimization |
+### Quality Presets
+
+| Preset | CRF | Encoding | Use Case |
+|--------|-----|----------|----------|
+| `low` | 28 | fast | Quick drafts, smaller files |
+| `medium` | 18 | medium | Default - balanced quality and size |
+| `high` | 10 | slow | Final delivery, best quality |
+
+### Supported Codecs
+
+| Codec | Name | Description |
+|-------|------|-------------|
+| `libx264` | H.264 | Excellent compatibility (default) |
+| `libx265` | H.265/HEVC | ~50% smaller files, slower encoding |
+
+### CLI Flags
+
+```bash
+--quality <preset>    # low, medium, high (default: medium)
+--crf <value>         # Override CRF (0-51, lower = better)
+--codec <codec>       # libx264 or libx265 (default: libx264)
+```
+
+### Examples
+
+```bash
+# High quality for final output
+sceneforge concat --demo my-demo --quality high
+
+# Smaller files with H.265 codec
+sceneforge concat --demo my-demo --codec libx265
+
+# Custom CRF for fine control
+sceneforge split --demo my-demo --crf 15
+```
+
+### Why Quality Matters
 
-**Why these settings:**
 - Videos go through multiple processing stages (split → add-audio → concat)
 - Each re-encoding can degrade quality (generation loss)
-- CRF 18 preserves quality across all stages
-- Medium preset provides good compression without sacrificing quality
+- Higher quality settings (lower CRF) preserve fidelity across stages
+- The `high` preset (CRF 10) produces near-lossless quality
+
+### CRF Reference
 
-**CRF Reference:**
 - 0 = Lossless (huge files)
-- 18 = Visually lossless (SceneForge default)
+- 10 = Near-lossless (high preset)
+- 18 = Visually lossless (medium preset, default)
 - 23 = FFmpeg default
-- 28+ = Lower quality, smaller files
+- 28 = Lower quality (low preset)

package/dist/templates/stages/stage4-rebalancing.md

@@ -218,24 +218,26 @@ Aim for variance within ±500ms per step:
 - [ ] No unexpected pauses
 
 ### Video Quality Check
-SceneForge uses high-quality encoding settings to preserve video fidelity:
+SceneForge provides configurable quality settings to preserve video fidelity:
 - [ ] Video appears sharp (no compression artifacts)
 - [ ] Colors are accurate (no banding)
 - [ ] Text is readable (no blur from compression)
 - [ ] No visible quality degradation between steps
 
-**Encoding Settings Used:**
-| Setting | Value | Purpose |
-|---------|-------|---------|
-| Codec | `libx264` | H.264 for compatibility |
-| CRF | `18` | High quality (visually lossless) |
-| Preset | `medium` | Balanced quality/speed |
-| Audio | `aac @ 192k` | High-quality audio |
+**Quality Presets:**
+| Preset | CRF | Encoding | Use Case |
+|--------|-----|----------|----------|
+| `low` | 28 | fast | Quick drafts |
+| `medium` | 18 | medium | Default - balanced |
+| `high` | 10 | slow | Final delivery |
+
+**CLI Flags:** `--quality`, `--crf`, `--codec` (available on split, add-audio, concat)
 
 **If you notice quality issues:**
-1. Ensure source recording is high quality (check `output/videos/<demo>.webm`)
-2. Re-run the pipeline to regenerate all clips
-3. Check available disk space (low space can affect encoding)
+1. Re-run with `--quality high` for better fidelity
+2. Ensure source recording is high quality (check `output/videos/<demo>.webm`)
+3. Try `--codec libx265` for better compression at same quality
+4. Check available disk space (low space can affect encoding)
 
 ## Final Checklist
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@t3lnet/sceneforge",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "description": "SceneForge runner and generation utilities for YAML-driven demos",
   "license": "MIT",
   "author": "T3LNET",