feat: enhance background generation

Author: LeadcodeDev

.claude/skills/rustmotion/SKILL.md

@@ -58,6 +58,7 @@ Read individual rule files for detailed explanations, GOOD/BAD examples, and con
 - [rules/text-background.md](rules/text-background.md) - text-background renders a colored rectangle behind text
 - [rules/3d-perspective.md](rules/3d-perspective.md) - 3D perspective transforms with rotate_x, rotate_y, perspective keyframes
 - [rules/timeline-sequencing.md](rules/timeline-sequencing.md) - Timeline steps for multi-phase animations within a single scene
+- [rules/gradient-quality.md](rules/gradient-quality.md) - Gradient quality: linear color space, 10-bit encoding, ProRes for dark gradients
 
 ---
 
@@ -306,8 +307,10 @@ Read individual rule files for detailed explanations, GOOD/BAD examples, and con
 | `height`     | u32    | required    | Video height in pixels. **Must be even for H.264.**     |
 | `fps`        | u32    | `30`        | Frames per second                                       |
 | `background` | string | `"#000000"` | Default background color (hex `#RRGGBB` or `#RRGGBBAA`) |
-| `codec`      | string | `null`      | `"h264"`, `"h265"`, `"vp9"`, `"prores"`                 |
-| `crf`        | u8     | `null`      | Constant Rate Factor (0-51, lower = better quality)     |
+| `codec`      | string | `null`      | `"h264"` (10-bit), `"h265"`, `"vp9"`, `"prores"`        |
+| `crf`        | u8     | `23`        | Constant Rate Factor (0-51, lower = better quality)     |
+
+> **Encoding note:** H.264 outputs 10-bit (`yuv420p10le`) by default when ffmpeg is available, which reduces color banding on dark gradients. For best quality on gradient-heavy videos, use `--codec prores` (lossless).
 
 #### `audio` (optional array)
 
@@ -1294,7 +1297,7 @@ Scenes support a virtual camera with animatable pan, zoom, and rotation.
 
 #### Animated Background
 
-Scenes can have animated gradient backgrounds. Use `concentric_circles` for a subtle, professional look (dark arc rings radiating from center). Use `gradient_shift` for color-shifting gradients.
+Scenes can have animated gradient backgrounds. Gradients are interpolated in **linear color space** with subdivided color stops for smooth dark transitions. Use `concentric_circles` for a subtle, professional look (dark arc rings radiating from center). Use `gradient_shift` for color-shifting gradients.
 
 ```json
 {

.claude/skills/rustmotion/rules/gradient-quality.md

@@ -0,0 +1,41 @@
+# Rule: Gradient Quality and Encoding
+
+Dark gradients are prone to color banding (visible steps instead of smooth transitions). Rustmotion mitigates this with:
+
+1. **Linear color space interpolation** for animated background gradients (smoother dark tones)
+2. **Subdivided color stops** (16 intermediate stops between each color pair)
+3. **10-bit H.264** encoding (`yuv420p10le`, `high10` profile) when ffmpeg is available
+4. **Dithering** enabled on all gradient paints
+
+## Encoding recommendations
+
+| Scenario | Recommendation |
+|---|---|
+| Dark gradient backgrounds | Use `--codec prores` for best quality |
+| General use | Default H.264 10-bit (requires ffmpeg) |
+| No ffmpeg available | Built-in openh264 (8-bit, may show banding on dark gradients) |
+
+**GOOD:** Use `gradient_type: "radial"` with at least 3 colors for smooth transitions:
+```json
+{
+  "animated-background": {
+    "colors": ["#0f172a", "#1e1b4b", "#0f172a"],
+    "speed": 20,
+    "gradient_type": "radial"
+  }
+}
+```
+
+**BAD:** Only 2 very similar dark colors (minimal contrast = worst banding):
+```json
+{
+  "animated-background": {
+    "colors": ["#0a0a0a", "#0b0b0b"],
+    "gradient_type": "radial"
+  }
+}
+```
+
+## ffmpeg auto-detection
+
+When ffmpeg is installed, rustmotion uses it automatically for all MP4 output (10-bit H.264). Without ffmpeg, it falls back to the built-in openh264 encoder (8-bit). No flag needed.

CLAUDE.md

@@ -6,3 +6,9 @@ See .claude/skills/ for detailed instructions on generating rustmotion scenarios
 ## Règle obligatoire
 
 Tout JSON de scénario généré doit être validé avec `rustmotion validate` avant d'être présenté à l'utilisateur.
+
+## Encodage
+
+- ffmpeg est auto-détecté et utilisé par défaut (10-bit H.264, meilleure qualité sur les gradients sombres)
+- Sans ffmpeg, le fallback openh264 intégré encode en 8-bit
+- Pour les vidéos avec des gradients sombres, recommander `--codec prores` pour une qualité maximale

README.md

@@ -12,7 +12,7 @@ A CLI tool that renders motion design videos from JSON scenarios. No browser, no
 cargo install rustmotion
 ```
 
-**Requirements:** Rust toolchain + C++ compiler (for openh264). Optional: `ffmpeg` CLI for H.265/VP9/ProRes/WebM/GIF output.
+**Requirements:** Rust toolchain + C++ compiler (for openh264). **Recommended:** `ffmpeg` CLI for 10-bit H.264 and H.265/VP9/ProRes/WebM/GIF output.
 
 ## Quick Start
 
@@ -1220,7 +1220,7 @@ Scenes support a virtual camera with animatable pan, zoom, and rotation.
 
 ### Animated Background
 
-Scenes can have animated gradient backgrounds.
+Scenes can have animated gradient backgrounds. Gradients are interpolated in linear color space with subdivided color stops for smooth dark transitions.
 
 ```json
 {
@@ -1572,7 +1572,8 @@ Renders multiple sub-frames and composites them for physically-correct motion bl
 
 | Format | Command | Requires |
 |---|---|---|
-| **MP4 (H.264)** | `rustmotion render in.json -o out.mp4` | Built-in |
+| **MP4 (H.264 10-bit)** | `rustmotion render in.json -o out.mp4` | ffmpeg (auto-detected) |
+| **MP4 (H.264 8-bit)** | `rustmotion render in.json -o out.mp4` | Built-in (fallback without ffmpeg) |
 | **MP4 (H.265)** | `rustmotion render in.json -o out.mp4 --codec h265` | ffmpeg |
 | **WebM (VP9)** | `rustmotion render in.json -o out.webm --codec vp9` | ffmpeg |
 | **MOV (ProRes)** | `rustmotion render in.json -o out.mov --codec prores` | ffmpeg |
@@ -1582,6 +1583,8 @@ Renders multiple sub-frames and composites them for physically-correct motion bl
 
 Transparency is supported with `--transparent` for PNG sequences, WebM (VP9), and ProRes 4444.
 
+> **Gradient quality:** When ffmpeg is available, H.264 uses 10-bit color depth (`yuv420p10le`, `high10` profile) which greatly reduces banding on dark gradients. For maximum quality, use `--codec prores`. The built-in openh264 encoder (fallback without ffmpeg) outputs 8-bit only.
+
 ---
 
 ## Full Example