reelforge 1.22.0 → 1.24.0

package/README.md

@@ -1,295 +1,295 @@
-# reelforge
-
-> Turn a topic or script into a finished vertical video — narration, visuals, and subtitles, assembled for you. Every capability is a command, with `--help` at every level.
-
-## Install
-
-```bash
-npm install -g reelforge
-```
-
-Or use directly without install:
-
-```bash
-npx reelforge <command>
-```
-
-After install, two binaries are on your `PATH` — `reelforge` and the short alias `rf`. Both behave identically; the docs use `rf` from here on.
-
-```bash
-rf --version            # same as `reelforge --version`
-```
-
-## Quick start
-
-The CLI ships pointing at the hosted service. Log in once, then call:
-
-```bash
-npm install -g reelforge
-rf login                                       # opens browser; headless? rf login <api_key>
-rf whoami                                      # balance + api_keys
-rf create "为什么我们还没找到外星文明？"          # auto-saves to ./<title>-<id>.mp4 in cwd
-```
-
-That's the whole story — no server to run.
-
-### Output behavior
-
-| invocation | result |
-|---|---|
-| `rf create "..."` | Saves to `./<sanitized-title>-<task_id_short>.mp4`, prints the path |
-| `rf create "..." -o ./videos/space.mp4` | Saves to that exact path (must include filename, not just a directory) |
-| `rf create "..." --no-download` | Skips local save, prints JSON result with `video_url` |
-| `rf create "..." \| jq .video_url` | When stdout is piped, download is skipped automatically |
-
-## Global options
-
-| flag | description |
-|---|---|
-| `-s, --server <url>` | Server URL (overrides `$REELFORGE_SERVER`; defaults to the hosted service) |
-| `-k, --api-key <key>` | API key (overrides `$REELFORGE_API_KEY` and `reelforge login` saved key) |
-| `--json` | Output raw JSON instead of pretty text — pipe-friendly |
-| `--quiet` | Suppress informational messages on stderr |
-| `-v, --version` | Show CLI version |
-| `-h, --help` | Show help (works on every sub-command) |
-
-## Command map
-
-Run `rf <command> --help` for full details on any of these.
-
-### Core capabilities
-
-| command | what it does |
-|---|---|
-| `llm chat -p <text>` | Send one prompt to the configured model |
-| `llm presets` | List built-in model presets |
-| `tts ... -t <text> -o out.mp3` | Text-to-speech (free local + cloud voice options) |
-| `tts voices [--locale zh]` | List supported voices |
-| `images generate -p <prompt>` | Image generation |
-
-### Content / audio / subtitle atomics
-
-| command | what it does |
-|---|---|
-| `content scene-plan -t <topic>` | Single LLM call: title + master script + per-scene image prompts (replaces the old narration / split / image-prompts / title trio) |
-| `content scene-plan --script <text-or-@file>` | Same, but the user supplies the script verbatim — LLM only segments and writes image prompts |
-| `audio transcribe -f <file>` / `--url <url>` | Speech-to-text with word + segment timestamps |
-| `subtitles split -t <text-or-@file>` | Deterministic tiered-punctuation subtitle line splitter (pure function, zero billing) |
-
-### Composition
-
-| command | what it does |
-|---|---|
-| `templates list [--size 1080x1920] [--type image]` | List HTML frame templates |
-| `templates preview <keyOrPath> [-o out.png]` | Render a preview from a preset key **or your own local .html file** |
-| `templates show <key> [-o file.html]` | Print or save the source HTML of any preset — copy it as a starting point for a custom template |
-| `frames render -t <keyOrPath> --title ... --text ...` | Render a single composed frame to PNG. `-t` accepts a preset key **or a local .html path** |
-| `compositions concat <v1> <v2> -o out.mp4` | FFmpeg concat (+ optional BGM) |
-| `compositions bgm -i video.mp4 --bgm bgm.mp3 -o out.mp4` | Add background music |
-| `compositions image-to-video -i img.png -a aud.mp3 -o out.mp4` | Build video from image + audio |
-| `compositions overlay -v video.mp4 --overlay overlay.png -o out.mp4` | Overlay PNG on video |
-
-### End-to-end pipelines
-
-All `pipelines *` commands submit an **async task** and (by default) poll until it finishes with a live progress indicator on stderr. Use `--no-wait` to return immediately with a `task_id`, then `rf tasks wait <id>` later.
-
-The standard pipeline turns a topic or script into a finished vertical video — narration, visuals, and subtitles are generated and assembled for you. One continuous narration track; visuals cut at scene boundaries; subtitles cut at line boundaries.
-
-| command | what it does |
-|---|---|
-| `pipelines standard -t <topic>` (or `--script <text>`) | Audio-first pipeline; `-d/--duration` and `-p/--pace` are the two main knobs |
-
-#### Composition knobs
-
-Three independent axes — mix and match as you like:
-
-| flag | values | default | what changes |
-|---|---|---|---|
-| `--motion` | `off` / `lite` / `max` | `lite` | per-scene zoompan + crossfade intensity |
-| `--layout` | `full` / `blur-bg` / `letterbox` | `full` | how the image sits in the canvas |
-| `--subtitle-style` | `plate` / `stroke` / `cinema` | `plate` | subtitle look |
-
-**Layout presets**:
-- `full` — image fills the whole 1080×1920 canvas. Generates a 1080×1920 image. High-impact; best for human portraits, landscapes, 9:16-native content.
-- `blur-bg` — image at 1080×1080 centered, top/bottom is a gaussian-blurred copy of the **same image** moving in sync with the foreground. Generates a 1080×1080 image (cheaper + no wasted pixels). Best for charts, screenshots, non-9:16 source content (小红书 / 抖音 style).
-- `letterbox` — image at 1080×1080 centered, top/bottom is a solid matte (CSS color). Generates a 1080×1080 image. Cinematic / calm. Customize the matte with `--layout-matte-color "#1a1a1a"` (default `black`).
-
-Examples:
-```bash
-rf create "财经日报" --layout blur-bg                              # 小红书 / 抖音
-rf create "纪录片片段" --layout letterbox --motion max             # 电影感
-rf create "..." --layout letterbox --layout-matte-color "#1a1a1a" # 柔和黑
-```
-
-### Resources
-
-| command | what it does |
-|---|---|
-| `bgm list / upload <file> / delete <name>` | Manage background music |
-| `files list / upload <file> / download <path> / delete <path>` | Manage user assets |
-
-### System
-
-| command | what it does |
-|---|---|
-| `config get` | Read server config (keys masked) |
-| `config set <key> <value>` | Update a dotted-path setting (e.g. `llm.api_key sk-xxx`) |
-| `config patch <file>` | Apply a JSON-merge patch |
-| `tasks list [--status running]` | List recent tasks |
-| `tasks get <id>` / `tasks wait <id>` / `tasks cancel <id>` | Task lifecycle |
-| `history list / get <id> / delete <id>` | Browse / delete completed runs |
-| `health` | Server health + capability check |
-
-### Heavy brand customization (custom overlay templates)
-
-`--motion` / `--layout` / `--subtitle-*` / `--brand-*` cover the common cases. For full visual identity ownership (custom path bar, accent decorations, light theme, footer block, etc.) pass a custom overlay HTML via `--frame-template <local.html | preset_key>`:
-
-```bash
-rf templates show 1080x1920/default.html -o ./my-brand.html
-# ...edit my-brand.html (change colors, add structure, etc.)...
-rf create "我的视频" --frame-template ./my-brand.html
-```
-
-**Contract for custom HTML**:
-
-- Canvas is **1080×1920** (pipeline-fixed; don't declare a different size in `<meta>`).
-- Background must be **transparent** — the scene image is composited by the renderer outside the HTML layer.
-- **`{{image}}` no longer exists.** Using `<img src="{{image}}">` is a hard error at submit time. The image is composited by the renderer.
-- The pipeline injects these placeholders for you:
-
-| Placeholder | What it is |
-|---|---|
-| `{{title}}` `{{text}}` | per-frame content |
-| `{{index}}` `{{total}}` | "scene N of M" — `{{total}}` is the LLM-decided scene count, don't hardcode |
-| `{{layout}}` | `"full"` / `"blur-bg"` / `"letterbox"` — react via `body[data-layout="..."]` CSS to put title/subtitle in the matte zones when layout ≠ full |
-| `{{subtitle_style}}` `{{subtitle_color}}` `{{subtitle_background}}` | subtitle preset + overrides |
-| `{{brand_position}}` `{{brand_handle}}` `{{brand_slogan}}` `{{brand_logo}}` `{{brand_color}}` | brand-chrome inputs (use or ignore as you like) |
-
-Inline HTML is hard-capped at 2 MB. The audio + motion + character-ref + scene-plan stages all keep working identically — only the overlay layer is yours.
-
-**Publishing to short-video platforms (Douyin / TikTok / WeChat Channels)** — the default composition renders to the full 1080×1920 canvas, but those apps overlay UI on top/bottom/right and cover-crop ~96-180px on each side on taller phones. ReelForge does NOT bake platform-specific padding into the renderer. Look up reference safe-zone numbers + recommended `--media-anchor-y` values per platform:
-
-```bash
-rf platform                  # overview table for all platforms
-rf platform 抖音              # detail + anchor variants (alias of douyin)
-rf platform tiktok
-rf platform wechat           # 视频号
-```
-
-## Examples
-
-```bash
-# 1. One-click out a video (45s default, AI writes the script)
-rf create "为什么我们还没找到外星文明？"
-
-# 2. Longer video with a slower visual rhythm
-rf create "深夜便利店的灯光" -d 90 -p slow
-
-# 3. Your own script — no narration-splitting on your side, the pipeline handles it
-rf create --script @./my-script.txt
-rf create --script "雨水缓缓滑落在玻璃窗上，像是无声的泪珠。"
-
-# 4. Preview-first workflow: scrub the storyboard in the browser
-#    before paying for the MP4 render. Finalize with `rf render` when satisfied.
-rf create "..." --preview-only          # opens browser studio
-rf render <task-id>                     # produce the MP4
-
-# 5. Push the image square up to grow the bottom matte (抖音 long-description
-#    case); subtitle position follows the image automatically.
-rf create "..." --layout blur-bg --media-anchor-y 0.40
-#  See `rf platform 抖音` for the safe range and per-scenario recommendations.
-
-# 6. Encoder budget — pick a quality preset or set an exact bitrate.
-rf create "..." --quality draft         # ~1 Mbps, ~3-4× smaller than default
-rf create "..." --video-bitrate 750k    # exact bitrate
-rf create "..." --crf 28                # fine-grained control
-
-# 7. Pick a built-in visual style preset
-rf create "美食教程" --style photorealistic
-
-# 5. Pipeline form with explicit output path
-rf pipelines standard \
-  --script @./script.txt \
-  --frame-template 1080x1920/image_default.html \
-  -p normal -o smoke.mp4
-
-# 6. Inspect existing tasks & redownload a finished video
-rf tasks list --limit 5
-rf history get <task-id> --download recovered.mp4
-
-# 7. Atomics for stand-alone use
-rf content scene-plan -t "雨天的玻璃窗" -d 45 --json | jq .scenes
-rf audio transcribe -f narration.mp3 --json | jq '.words[:5]'
-rf subtitles split -t @./narration.txt --min 10 --hard-max 24
-
-# 8. JSON pipe for automation
-rf llm presets --json | jq '.[].defaultModel'
-
-# 9. Use your own HTML template (no PR/release needed)
-#     Any --frame-template that points to a local .html file is read and sent
-#     inline. Declare size inside the file via
-#       <meta name="template:width"  content="1080">
-#       <meta name="template:height" content="1920">
-#     or pass --frame-template-size 1080x1920.
-rf templates show 1080x1920/image_default.html -o my-brand.html   # copy a preset
-# ...edit my-brand.html to suit your style...
-rf templates preview ./my-brand.html --title "Hello" -o preview.png
-rf frames render -t ./my-brand.html --values '{"author":"Alice"}' -o frame.png
-rf pipelines standard -t "宠物" --frame-template ./my-brand.html -o final.mp4
-```
-
-### Custom HTML templates
-
-Easiest way to start: grab a preset as a reference.
-
-```bash
-rf templates list                                                  # see all keys
-rf templates show 1080x1920/static_default.html                    # print to stdout
-rf templates show 1080x1920/image_default.html -o my-brand.html    # save and edit
-```
-
-`{{title}}`, `{{text}}`, `{{image}}`, `{{index}}`, `{{total}}` are reserved built-ins auto-injected by the pipeline; everything else uses the `{{name:type=default}}` DSL (`type` ∈ `text|number|color|bool`). Pass extras through `--values '{"author":"Alice"}'` (or `template_params` on the pipeline API).
-
-- `{{index}}` — current scene number, 1-based
-- `{{total}}` — scene count the LLM actually produced (use this for "scene N of M" badges; don't hardcode in `template_params`, the scene count is decided at runtime)
-
-#### Template type — does the pipeline generate an AI image per scene?
-
-When you ship an inline template through `rf create` / `rf pipelines standard`, ReelForge needs to know whether each scene should kick off image generation. Resolution priority (high → low):
-
-1. Explicit flag — `--frame-template-type image|static|asset` (or `frame_template_type` in the API body).
-2. Inside the HTML — `<meta name="template:type" content="image">` (or `static` / `asset`).
-3. **Default: `image`** — best practice for zero-config users. If your template doesn't reference scene imagery (pure-text card, etc.), declare `static` explicitly to skip image generation and its cost.
-
-The placeholder `{{image}}` no longer doubles as a type signal — declare type explicitly.
-
-Limits and safety:
-
-- Max 2 MB per inline HTML.
-- The render sandbox blocks `file://`, loopback / private / link-local IPs, CGNAT range, cloud-metadata, and `*.local` / `*.internal` hostnames. So your template can only reference public `https`/`http` resources or `data:` URIs.
-- If the CLI is talking to a hosted server, local-path `--image` won't reach the server; either upload to `rf files upload` first or use an HTTPS URL / data: URI.
-
-#### API field reference
-
-| endpoint | inline HTML field | size field | type field |
-|---|---|---|---|
-| `POST /api/v1/frames/render` | `template_html` | `size` | — (n/a, no image generation) |
-| `POST /api/v1/templates/preview` | `template_html` | `size` | — |
-| `POST /api/v1/pipelines/standard` | `frame_template_inline` | `frame_template_size` | `frame_template_type` |
-
-The pipeline endpoint uses the `frame_template_*` prefix because it already has a `frame_template` field (preset key). The single-frame endpoints use the shorter `template_html` because they don't.
-
-## Tip — getting unstuck
-
-Every level has `--help`:
-
-```bash
-rf --help                     # top-level overview
-rf pipelines --help           # list of pipelines
-rf pipelines standard --help  # full option reference
-rf tts edge --help            # one specific command
-```
-
-## License
-
-Apache-2.0
+# reelforge
+
+> Turn a topic or script into a finished vertical video — narration, visuals, and subtitles, assembled for you. Every capability is a command, with `--help` at every level.
+
+## Install
+
+```bash
+npm install -g reelforge
+```
+
+Or use directly without install:
+
+```bash
+npx reelforge <command>
+```
+
+After install, two binaries are on your `PATH` — `reelforge` and the short alias `rf`. Both behave identically; the docs use `rf` from here on.
+
+```bash
+rf --version            # same as `reelforge --version`
+```
+
+## Quick start
+
+The CLI ships pointing at the hosted service. Log in once, then call:
+
+```bash
+npm install -g reelforge
+rf login                                       # opens browser; headless? rf login <api_key>
+rf whoami                                      # balance + api_keys
+rf create "为什么我们还没找到外星文明？"          # auto-saves to ./<title>-<id>.mp4 in cwd
+```
+
+That's the whole story — no server to run.
+
+### Output behavior
+
+| invocation | result |
+|---|---|
+| `rf create "..."` | Saves to `./<sanitized-title>-<task_id_short>.mp4`, prints the path |
+| `rf create "..." -o ./videos/space.mp4` | Saves to that exact path (must include filename, not just a directory) |
+| `rf create "..." --no-download` | Skips local save, prints JSON result with `video_url` |
+| `rf create "..." \| jq .video_url` | When stdout is piped, download is skipped automatically |
+
+## Global options
+
+| flag | description |
+|---|---|
+| `-s, --server <url>` | Server URL (overrides `$REELFORGE_SERVER`; defaults to the hosted service) |
+| `-k, --api-key <key>` | API key (overrides `$REELFORGE_API_KEY` and `reelforge login` saved key) |
+| `--json` | Output raw JSON instead of pretty text — pipe-friendly |
+| `--quiet` | Suppress informational messages on stderr |
+| `-v, --version` | Show CLI version |
+| `-h, --help` | Show help (works on every sub-command) |
+
+## Command map
+
+Run `rf <command> --help` for full details on any of these.
+
+### Core capabilities
+
+| command | what it does |
+|---|---|
+| `llm chat -p <text>` | Send one prompt to the configured model |
+| `llm presets` | List built-in model presets |
+| `tts ... -t <text> -o out.mp3` | Text-to-speech (free local + cloud voice options) |
+| `tts voices [--locale zh]` | List supported voices |
+| `images generate -p <prompt>` | Image generation |
+
+### Content / audio / subtitle atomics
+
+| command | what it does |
+|---|---|
+| `content scene-plan -t <topic>` | Single LLM call: title + master script + per-scene image prompts (replaces the old narration / split / image-prompts / title trio) |
+| `content scene-plan --script <text-or-@file>` | Same, but the user supplies the script verbatim — LLM only segments and writes image prompts |
+| `audio transcribe -f <file>` / `--url <url>` | Speech-to-text with word + segment timestamps |
+| `subtitles split -t <text-or-@file>` | Deterministic tiered-punctuation subtitle line splitter (pure function, zero billing) |
+
+### Composition
+
+| command | what it does |
+|---|---|
+| `templates list [--size 1080x1920] [--type image]` | List HTML frame templates |
+| `templates preview <keyOrPath> [-o out.png]` | Render a preview from a preset key **or your own local .html file** |
+| `templates show <key> [-o file.html]` | Print or save the source HTML of any preset — copy it as a starting point for a custom template |
+| `frames render -t <keyOrPath> --title ... --text ...` | Render a single composed frame to PNG. `-t` accepts a preset key **or a local .html path** |
+| `compositions concat <v1> <v2> -o out.mp4` | FFmpeg concat (+ optional BGM) |
+| `compositions bgm -i video.mp4 --bgm bgm.mp3 -o out.mp4` | Add background music |
+| `compositions image-to-video -i img.png -a aud.mp3 -o out.mp4` | Build video from image + audio |
+| `compositions overlay -v video.mp4 --overlay overlay.png -o out.mp4` | Overlay PNG on video |
+
+### End-to-end pipelines
+
+All `pipelines *` commands submit an **async task** and (by default) poll until it finishes with a live progress indicator on stderr. Use `--no-wait` to return immediately with a `task_id`, then `rf tasks wait <id>` later.
+
+The standard pipeline turns a topic or script into a finished vertical video — narration, visuals, and subtitles are generated and assembled for you. One continuous narration track; visuals cut at scene boundaries; subtitles cut at line boundaries.
+
+| command | what it does |
+|---|---|
+| `pipelines standard -t <topic>` (or `--script <text>`) | Audio-first pipeline; `-d/--duration` and `-p/--pace` are the two main knobs |
+
+#### Composition knobs
+
+Three independent axes — mix and match as you like:
+
+| flag | values | default | what changes |
+|---|---|---|---|
+| `--motion` | `off` / `lite` / `max` | `lite` | per-scene zoompan + crossfade intensity |
+| `--layout` | `full` / `blur-bg` / `letterbox` | `full` | how the image sits in the canvas |
+| `--subtitle-style` | `plate` / `stroke` / `cinema` | `plate` | subtitle look |
+
+**Layout presets**:
+- `full` — image fills the whole 1080×1920 canvas. Generates a 1080×1920 image. High-impact; best for human portraits, landscapes, 9:16-native content.
+- `blur-bg` — image at 1080×1080 centered, top/bottom is a gaussian-blurred copy of the **same image** moving in sync with the foreground. Generates a 1080×1080 image (cheaper + no wasted pixels). Best for charts, screenshots, non-9:16 source content (小红书 / 抖音 style).
+- `letterbox` — image at 1080×1080 centered, top/bottom is a solid matte (CSS color). Generates a 1080×1080 image. Cinematic / calm. Customize the matte with `--layout-matte-color "#1a1a1a"` (default `black`).
+
+Examples:
+```bash
+rf create "财经日报" --layout blur-bg                              # 小红书 / 抖音
+rf create "纪录片片段" --layout letterbox --motion max             # 电影感
+rf create "..." --layout letterbox --layout-matte-color "#1a1a1a" # 柔和黑
+```
+
+### Resources
+
+| command | what it does |
+|---|---|
+| `bgm list / upload <file> / delete <name>` | Manage background music |
+| `files list / upload <file> / download <path> / delete <path>` | Manage user assets |
+
+### System
+
+| command | what it does |
+|---|---|
+| `config get` | Read server config (keys masked) |
+| `config set <key> <value>` | Update a dotted-path setting (e.g. `llm.api_key sk-xxx`) |
+| `config patch <file>` | Apply a JSON-merge patch |
+| `tasks list [--status running]` | List recent tasks |
+| `tasks get <id>` / `tasks wait <id>` / `tasks cancel <id>` | Task lifecycle |
+| `history list / get <id> / delete <id>` | Browse / delete completed runs |
+| `health` | Server health + capability check |
+
+### Heavy brand customization (custom overlay templates)
+
+`--motion` / `--layout` / `--subtitle-*` / `--brand-*` cover the common cases. For full visual identity ownership (custom path bar, accent decorations, light theme, footer block, etc.) pass a custom overlay HTML via `--frame-template <local.html | preset_key>`:
+
+```bash
+rf templates show 1080x1920/default.html -o ./my-brand.html
+# ...edit my-brand.html (change colors, add structure, etc.)...
+rf create "我的视频" --frame-template ./my-brand.html
+```
+
+**Contract for custom HTML**:
+
+- Canvas is **1080×1920** (pipeline-fixed; don't declare a different size in `<meta>`).
+- Background must be **transparent** — the scene image is composited by the renderer outside the HTML layer.
+- **`{{image}}` no longer exists.** Using `<img src="{{image}}">` is a hard error at submit time. The image is composited by the renderer.
+- The pipeline injects these placeholders for you:
+
+| Placeholder | What it is |
+|---|---|
+| `{{title}}` `{{text}}` | per-frame content |
+| `{{index}}` `{{total}}` | "scene N of M" — `{{total}}` is the LLM-decided scene count, don't hardcode |
+| `{{layout}}` | `"full"` / `"blur-bg"` / `"letterbox"` — react via `body[data-layout="..."]` CSS to put title/subtitle in the matte zones when layout ≠ full |
+| `{{subtitle_style}}` `{{subtitle_color}}` `{{subtitle_background}}` | subtitle preset + overrides |
+| `{{brand_position}}` `{{brand_handle}}` `{{brand_slogan}}` `{{brand_logo}}` `{{brand_color}}` | brand-chrome inputs (use or ignore as you like) |
+
+Inline HTML is hard-capped at 2 MB. The audio + motion + character-ref + scene-plan stages all keep working identically — only the overlay layer is yours.
+
+**Publishing to short-video platforms (Douyin / TikTok / WeChat Channels)** — the default composition renders to the full 1080×1920 canvas, but those apps overlay UI on top/bottom/right and cover-crop ~96-180px on each side on taller phones. ReelForge does NOT bake platform-specific padding into the renderer. Look up reference safe-zone numbers + recommended `--media-anchor-y` values per platform:
+
+```bash
+rf platform                  # overview table for all platforms
+rf platform 抖音              # detail + anchor variants (alias of douyin)
+rf platform tiktok
+rf platform wechat           # 视频号
+```
+
+## Examples
+
+```bash
+# 1. One-click out a video (45s default, AI writes the script)
+rf create "为什么我们还没找到外星文明？"
+
+# 2. Longer video with a slower visual rhythm
+rf create "深夜便利店的灯光" -d 90 -p slow
+
+# 3. Your own script — no narration-splitting on your side, the pipeline handles it
+rf create --script @./my-script.txt
+rf create --script "雨水缓缓滑落在玻璃窗上，像是无声的泪珠。"
+
+# 4. Preview-first workflow: scrub the storyboard in the browser
+#    before paying for the MP4 render. Finalize with `rf render` when satisfied.
+rf create "..." --preview-only          # opens browser studio
+rf render <task-id>                     # produce the MP4
+
+# 5. Push the image square up to grow the bottom matte (抖音 long-description
+#    case); subtitle position follows the image automatically.
+rf create "..." --layout blur-bg --media-anchor-y 0.40
+#  See `rf platform 抖音` for the safe range and per-scenario recommendations.
+
+# 6. Encoder budget — pick a quality preset or set an exact bitrate.
+rf create "..." --quality draft         # ~1 Mbps, ~3-4× smaller than default
+rf create "..." --video-bitrate 750k    # exact bitrate
+rf create "..." --crf 28                # fine-grained control
+
+# 7. Pick a built-in visual style preset
+rf create "美食教程" --style photorealistic
+
+# 5. Pipeline form with explicit output path
+rf pipelines standard \
+  --script @./script.txt \
+  --frame-template 1080x1920/image_default.html \
+  -p normal -o smoke.mp4
+
+# 6. Inspect existing tasks & redownload a finished video
+rf tasks list --limit 5
+rf history get <task-id> --download recovered.mp4
+
+# 7. Atomics for stand-alone use
+rf content scene-plan -t "雨天的玻璃窗" -d 45 --json | jq .scenes
+rf audio transcribe -f narration.mp3 --json | jq '.words[:5]'
+rf subtitles split -t @./narration.txt --min 10 --hard-max 24
+
+# 8. JSON pipe for automation
+rf llm presets --json | jq '.[].defaultModel'
+
+# 9. Use your own HTML template (no PR/release needed)
+#     Any --frame-template that points to a local .html file is read and sent
+#     inline. Declare size inside the file via
+#       <meta name="template:width"  content="1080">
+#       <meta name="template:height" content="1920">
+#     or pass --frame-template-size 1080x1920.
+rf templates show 1080x1920/image_default.html -o my-brand.html   # copy a preset
+# ...edit my-brand.html to suit your style...
+rf templates preview ./my-brand.html --title "Hello" -o preview.png
+rf frames render -t ./my-brand.html --values '{"author":"Alice"}' -o frame.png
+rf pipelines standard -t "宠物" --frame-template ./my-brand.html -o final.mp4
+```
+
+### Custom HTML templates
+
+Easiest way to start: grab a preset as a reference.
+
+```bash
+rf templates list                                                  # see all keys
+rf templates show 1080x1920/static_default.html                    # print to stdout
+rf templates show 1080x1920/image_default.html -o my-brand.html    # save and edit
+```
+
+`{{title}}`, `{{text}}`, `{{image}}`, `{{index}}`, `{{total}}` are reserved built-ins auto-injected by the pipeline; everything else uses the `{{name:type=default}}` DSL (`type` ∈ `text|number|color|bool`). Pass extras through `--values '{"author":"Alice"}'` (or `template_params` on the pipeline API).
+
+- `{{index}}` — current scene number, 1-based
+- `{{total}}` — scene count the LLM actually produced (use this for "scene N of M" badges; don't hardcode in `template_params`, the scene count is decided at runtime)
+
+#### Template type — does the pipeline generate an AI image per scene?
+
+When you ship an inline template through `rf create` / `rf pipelines standard`, ReelForge needs to know whether each scene should kick off image generation. Resolution priority (high → low):
+
+1. Explicit flag — `--frame-template-type image|static|asset` (or `frame_template_type` in the API body).
+2. Inside the HTML — `<meta name="template:type" content="image">` (or `static` / `asset`).
+3. **Default: `image`** — best practice for zero-config users. If your template doesn't reference scene imagery (pure-text card, etc.), declare `static` explicitly to skip image generation and its cost.
+
+The placeholder `{{image}}` no longer doubles as a type signal — declare type explicitly.
+
+Limits and safety:
+
+- Max 2 MB per inline HTML.
+- The render sandbox blocks `file://`, loopback / private / link-local IPs, CGNAT range, cloud-metadata, and `*.local` / `*.internal` hostnames. So your template can only reference public `https`/`http` resources or `data:` URIs.
+- If the CLI is talking to a hosted server, local-path `--image` won't reach the server; either upload to `rf files upload` first or use an HTTPS URL / data: URI.
+
+#### API field reference
+
+| endpoint | inline HTML field | size field | type field |
+|---|---|---|---|
+| `POST /api/v1/frames/render` | `template_html` | `size` | — (n/a, no image generation) |
+| `POST /api/v1/templates/preview` | `template_html` | `size` | — |
+| `POST /api/v1/pipelines/standard` | `frame_template_inline` | `frame_template_size` | `frame_template_type` |
+
+The pipeline endpoint uses the `frame_template_*` prefix because it already has a `frame_template` field (preset key). The single-frame endpoints use the shorter `template_html` because they don't.
+
+## Tip — getting unstuck
+
+Every level has `--help`:
+
+```bash
+rf --help                     # top-level overview
+rf pipelines --help           # list of pipelines
+rf pipelines standard --help  # full option reference
+rf tts edge --help            # one specific command
+```
+
+## License
+
+Apache-2.0

package/bin/reelforge.js

@@ -1,8 +1,8 @@
-#!/usr/bin/env node
-// Thin shim so `reelforge` (alias `rf`) is invokable globally. The actual
-// implementation is bundled to dist/ by `npm run build`.
-import("../dist/index.js").catch((err) => {
-  // eslint-disable-next-line no-console
-  console.error(err?.stack || err);
-  process.exit(1);
-});
+#!/usr/bin/env node
+// Thin shim so `reelforge` (alias `rf`) is invokable globally. The actual
+// implementation is bundled to dist/ by `npm run build`.
+import("../dist/index.js").catch((err) => {
+  // eslint-disable-next-line no-console
+  console.error(err?.stack || err);
+  process.exit(1);
+});

package/dist/commands/clip.js

@@ -0,0 +1,139 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { post } from "../client.js";
+import { waitForTask } from "../utils/task-waiter.js";
+import { downloadTo } from "../utils/download.js";
+import { formatUsd, humanDuration, info, isJson, print, success } from "../utils/output.js";
+async function loadSpec(raw) {
+    let text = raw;
+    if (raw.startsWith("@")) {
+        text = await fs.readFile(path.resolve(raw.slice(1)), "utf8");
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (e) {
+        throw new Error(`--spec is not valid JSON: ${e instanceof Error ? e.message : e}`);
+    }
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("--spec must be a JSON object (the component's render spec)");
+    }
+    return parsed;
+}
+export function registerClip(program) {
+    program
+        .command("clip")
+        .description("一个 scene 组件 → 独立竖屏 MP4 (可选配音; 给 `rf dub --append` 拼片尾用)")
+        .helpOption("-h, --help", "show help")
+        .requiredOption("--component <id>", "组件 kind id (如 kinetic-text / quote-card / index-board)")
+        .requiredOption("--spec <json>", "组件 spec,内联 JSON 或 @文件路径")
+        .option("--theme <id>", "主题皮肤 id (缺省 = 组件所属 profile;general 组件用 general)")
+        .option("--narration <text>", "配音文案 (传了才有声音;不传 = 无声片段)")
+        .option("--voice <id>", "配音音色 (index-tts-2 音色名, 默认 熊小二)", "熊小二")
+        .option("--tts-model <id>", "TTS 模型 (默认 vox/index-tts-2)", "vox/index-tts-2")
+        .option("--duration <sec>", "片段时长 (秒);缺省 = 组件自然时长(无声)或配音时长(有声)", (v) => parseFloat(v))
+        .option("--subtitles", "烧录字幕 (默认不烧;组件通常自带文字)")
+        .option("--subtitle-style <style>", "字幕样式: plate | stroke | cinema (默认 plate)", "plate")
+        .option("-o, --output <file>", "输出 MP4 路径 (默认: clip-<组件>.mp4, 放在当前目录)")
+        .option("--preview-only", "只生成 preview, 不渲染最终 MP4")
+        .option("--poll-ms <ms>", "轮询间隔", (v) => parseInt(v, 10), 1500)
+        .option("--timeout-ms <ms>", "最长等待时间", (v) => parseInt(v, 10))
+        .addHelpText("after", [
+        "",
+        "它是什么:",
+        "  把单个 scene 组件渲染成一段独立的 1080×1920 竖屏 MP4。通用命令 —— 任何",
+        "  想单独跑的组件都走这里;最常见用途是给 `rf dub --append` 做固定片尾(关注卡 /",
+        "  赞助板 / 口播尾板),生成一次反复拼,省去每条视频重复 TTS。",
+        "",
+        "配音 (可选):",
+        "  · 不传 --narration → 无声片段,时长 = 组件自然时长 (或 --duration)。",
+        "  · 传 --narration   → 熊小二配音 (可 --voice 换),时长 = max(配音, 组件自然时长),",
+        "                       即配音短也不会截断动画;--subtitles 可另烧字幕。",
+        "",
+        "组件 (--component) + spec (--spec):",
+        "  · --component 传组件的 kind id。常用通用组件: kinetic-text(一句大字) /",
+        "    quote-card(金句) / comparison-vs(对比) / stat-counter(数字) /",
+        "    bullet-list(要点) / timeline(时间线)。finance / mindset 垂直组件也可,",
+        "    会自动套对应主题皮肤 (也可 --theme 指定)。",
+        "  · --spec 是该组件的渲染字段 (JSON 对象),内联或 @文件。字段随组件而定,",
+        "    例: kinetic-text = {text, emphasis};quote-card = {quote, author, context}。",
+        "",
+        "认证: 需要 API key — `rf login <key>` / $REELFORGE_API_KEY / --api-key。",
+        "可用音色: `rf tts voices`。",
+        "",
+        "示例:",
+        "  # 无声金句卡 (用组件自然时长)",
+        '  rf clip --component quote-card --spec \'{"quote":"慢即是快","author":"老张"}\'',
+        "",
+        "  # 带配音的关注片尾,再拼到 dub 后面 (典型用法)",
+        '  rf clip --component kinetic-text --spec \'{"text":"关注 机械制造师","emphasis":"机械制造师"}\' \\',
+        '    --narration "关注机械制造师官方账号,每天一个离谱发明" -o outro.mp4',
+        "  rf dub gameplay.mp4 --append outro.mp4",
+        "",
+        "  # 指定时长 + 字幕",
+        '  rf clip --component kinetic-text --spec \'{"text":"上车!"}\' --narration "都给我上车" --subtitles --duration 4',
+        "",
+        "  # 财经组件 (spec 从文件读, 自动用 finance 皮肤)",
+        "  rf clip --component index-board --spec @board.json",
+    ].join("\n"))
+        .action(async (opts) => {
+        const spec = await loadSpec(opts.spec);
+        const subtitleStyle = (opts.subtitleStyle || "plate").toLowerCase();
+        if (!["plate", "stroke", "cinema"].includes(subtitleStyle)) {
+            throw new Error(`--subtitle-style must be plate | stroke | cinema (got ${opts.subtitleStyle})`);
+        }
+        if (opts.duration !== undefined && (!Number.isFinite(opts.duration) || opts.duration <= 0)) {
+            throw new Error(`--duration must be a positive number (got ${opts.duration})`);
+        }
+        const body = {
+            component: opts.component,
+            spec,
+            voice: opts.voice || "熊小二",
+            tts_model: opts.ttsModel || "vox/index-tts-2",
+            subtitles: opts.subtitles === true,
+            subtitle_style: subtitleStyle,
+        };
+        if (opts.theme)
+            body.theme = opts.theme;
+        if (opts.narration)
+            body.narration = opts.narration;
+        if (opts.duration !== undefined)
+            body.duration_sec = opts.duration;
+        if (opts.previewOnly)
+            body.preview_only = true;
+        info(`Rendering component "${opts.component}"${opts.narration ? " (voiced)" : " (silent)"}...`);
+        const submitted = await post("/api/v1/clip", body);
+        info(`Submitted task: ${submitted.task_id} — 渲染中, 请稍候...`);
+        const t = await waitForTask(submitted.task_id, { pollMs: opts.pollMs, timeoutMs: opts.timeoutMs });
+        if (t.status !== "completed") {
+            throw new Error(t.error || `Task ended with status ${t.status}`);
+        }
+        const result = t.result;
+        if (result?.render_pending) {
+            info(`MP4 render skipped (--preview-only). Run \`rf render ${t.id}\` to finalize.`);
+        }
+        else if (result?.video_url) {
+            const stdoutIsPipe = !process.stdout.isTTY;
+            const skipDownload = stdoutIsPipe && !opts.output;
+            let savedPath;
+            if (opts.output)
+                savedPath = path.resolve(opts.output);
+            else if (!skipDownload)
+                savedPath = path.resolve(`clip-${opts.component}.mp4`);
+            if (savedPath) {
+                await downloadTo(result.video_url, savedPath);
+                success(`Saved → ${savedPath}`);
+            }
+        }
+        if (result?.generation_ms != null) {
+            const playback = result.duration != null ? `, ${result.duration.toFixed(1)}s` : "";
+            const skin = result.theme ? `, theme ${result.theme}` : "";
+            info(`generated in ${humanDuration(result.generation_ms)}${playback}${skin}`);
+        }
+        if (result?.price_usd != null)
+            info(`charge: ${formatUsd(result.price_usd)}`);
+        if (isJson())
+            print({ task_id: t.id, status: t.status, ...result });
+    });
+}

package/dist/commands/compose.js

@@ -59,35 +59,35 @@ async function readAsDataUri(specPath, baseDir) {
     const buf = await fs.readFile(abs);
     return { dataUri: `data:${mime};base64,${buf.toString("base64")}`, bytes: buf.byteLength };
 }
-const EXAMPLE_SPEC_HINT = `{
-  "experimental": "compose.v2",
-  "audio": { "narration": "./narration.mp3" },
-  "scenes": [
-    { "start_sec": 0,  "end_sec": 5,  "image": "./s1.png",  "motion": "zoom-in"   },
-    { "start_sec": 5,  "end_sec": 11, "video": "./clip.mp4", "muted": true        }
-  ],
-  "subtitles": [
-    { "start_sec": 0, "end_sec": 5,  "text": "为什么咖啡因让人精神" },
-    { "start_sec": 5, "end_sec": 11, "text": "原来它跟睡眠物质是同一把钥匙" }
-  ],
-  "title": "咖啡因的真相"
+const EXAMPLE_SPEC_HINT = `{
+  "experimental": "compose.v2",
+  "audio": { "narration": "./narration.mp3" },
+  "scenes": [
+    { "start_sec": 0,  "end_sec": 5,  "image": "./s1.png",  "motion": "zoom-in"   },
+    { "start_sec": 5,  "end_sec": 11, "video": "./clip.mp4", "muted": true        }
+  ],
+  "subtitles": [
+    { "start_sec": 0, "end_sec": 5,  "text": "为什么咖啡因让人精神" },
+    { "start_sec": 5, "end_sec": 11, "text": "原来它跟睡眠物质是同一把钥匙" }
+  ],
+  "title": "咖啡因的真相"
 }`;
-const EXAMPLE_SPEC_V3_HINT = `{
-  "experimental": "compose.v3",
-  "audio": { "tts_voice": "熊小二" },
-  "scenes": [
-    {
-      "video": "./s1.mp4", "muted": true,
-      "narration": ["今天热得不行", "我跑厕所睡觉"],
-      "intro_title": "热到躲厕所"
-    },
-    {
-      "image": "./splash.jpg",
-      "narration": ["主人你找拖鞋去吧"]
-    }
-  ],
-  "subtitle_style": "stroke",
-  "title": "贼喵被抓现行"
+const EXAMPLE_SPEC_V3_HINT = `{
+  "experimental": "compose.v3",
+  "audio": { "tts_voice": "熊小二" },
+  "scenes": [
+    {
+      "video": "./s1.mp4", "muted": true,
+      "narration": ["今天热得不行", "我跑厕所睡觉"],
+      "intro_title": "热到躲厕所"
+    },
+    {
+      "image": "./splash.jpg",
+      "narration": ["主人你找拖鞋去吧"]
+    }
+  ],
+  "subtitle_style": "stroke",
+  "title": "贼喵被抓现行"
 }`;
 export function registerCompose(program) {
     program

package/dist/commands/dub.js

@@ -0,0 +1,201 @@
+import fs from "node:fs/promises";
+import fsSync from "node:fs";
+import path from "node:path";
+import { post } from "../client.js";
+import { waitForTask } from "../utils/task-waiter.js";
+import { downloadTo } from "../utils/download.js";
+import { formatUsd, humanDuration, info, isJson, print, success } from "../utils/output.js";
+const VIDEO_EXT_TO_MIME = {
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+    ".mkv": "video/x-matroska",
+    ".m4v": "video/mp4",
+};
+const MAX_BYTES = 55 * 1024 * 1024;
+function fmtSize(bytes) {
+    if (!bytes)
+        return "0";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+export function registerDub(program) {
+    program
+        .command("dub <video>")
+        .description("⚠️ EXPERIMENTAL · 一个原始视频 → 自动反推内容 + 写解说 + 熊小二配音 + 字幕,输出成片")
+        .helpOption("-h, --help", "show help")
+        .option("-o, --output <file>", "输出 MP4 路径 (默认: <视频名>-dub.mp4, 放在当前目录)")
+        .option("--voice <id>", "配音音色 id (index-tts-2 音色名, 默认 熊小二)", "熊小二")
+        .option("--tts-model <id>", "TTS 模型 (默认 vox/index-tts-2)", "vox/index-tts-2")
+        .option("--game-volume <n>", "原视频自带声音的音量 0..1 (默认 0.6; 设 0 = 完全静音原声, 只留配音)", (v) => parseFloat(v), 0.6)
+        .option("--no-subtitles", "不烧录字幕 (默认烧录)")
+        .option("--subtitle-style <style>", "字幕样式: plate | stroke | cinema (默认 plate)", "plate")
+        .option("--no-cover", "不加封面 (默认自动生成封面)")
+        .option("--cover-template <id>", "封面模板 (默认 paper-band; 见 `rf cover templates`)", "paper-band")
+        .option("--cover-title <text>", "封面标题 (默认自动生成 ≤10 字钩子)")
+        .option("--cover-subtitle <text>", "封面副标题 (默认无)")
+        .option("--cover-badge <text>", "封面角标 (默认无)")
+        .option("--append <file>", "在成片末尾拼接一段视频 (如 `rf clip` 出的关注片尾; 可多次传, 按顺序拼)", (val, acc) => {
+        acc.push(val);
+        return acc;
+    }, [])
+        .option("--theme <id>", "可选主题 id (影响字幕底板 / 配色风格)")
+        .option("--vision-model <id>", "反推用的视觉模型 (默认 qwen/qwen3-vl-flash)")
+        .option("--script-model <id>", "写解说脚本用的 LLM (默认服务端配置模型)")
+        .option("--preview-only", "只生成 preview, 不渲染最终 MP4 (更快更省, 用于试效果)")
+        .option("--poll-ms <ms>", "轮询间隔", (v) => parseInt(v, 10), 1500)
+        .option("--timeout-ms <ms>", "最长等待时间", (v) => parseInt(v, 10))
+        .addHelpText("after", [
+        "",
+        "它做了什么 (全部在服务端完成):",
+        "  1. 反推视频内容 — 详细、带时间段的分镜 + 屏幕文字",
+        "  2. 根据视频时长写一段贴合画面的解说脚本 (卡住时长, 画面演到哪讲到哪)",
+        "  3. 用熊小二音色合成配音 (可 --voice 指定其它音色)",
+        "  4. 把配音叠到原视频上, 原视频自带声音压到 60% 垫底 (可 --game-volume 调)",
+        "  5. 烧录字幕 (复用 compose 的字幕样式 + 切分逻辑; --no-subtitles 关闭)",
+        "  6. 自动生成封面 — 选画面最炸的一帧当底图 + LLM 钩子标题, 套 paper-band 模板",
+        "     (--no-cover 关; --cover-template / --cover-title 自定; 见 `rf cover templates`)",
+        "  7. (可选) 在末尾拼接片尾 — --append <clip.mp4>, 可多次, 按顺序拼",
+        "     (片尾用 `rf clip` 先生成, 比如固定的「关注」引导卡, 生成一次反复用)",
+        "",
+        "认证:",
+        "  需要 API key — `rf login <key>` 或 $REELFORGE_API_KEY 或 --api-key <key>。",
+        "  没有 key 服务端会拒绝 (401)。",
+        "",
+        "支持的输入扩展名: .mp4 .mov .webm .mkv .m4v (单文件 ≤ 55MB)",
+        "",
+        "可用音色: `rf tts voices` (熊小二 / 激情熊大 / 专业解说 等 149 个)",
+        "",
+        "示例:",
+        "  # 最简单: 一个视频进, 配音+字幕成片出 (默认熊小二, 原声 60%)",
+        "  rf dub ./clip.mp4",
+        "",
+        "  # 指定输出路径 + 换个音色 + 原声调小到 30%",
+        "  rf dub ./clip.mp4 -o ./out.mp4 --voice 激情熊大 --game-volume 0.3",
+        "",
+        "  # 不要字幕",
+        "  rf dub ./clip.mp4 --no-subtitles",
+        "",
+        "  # 批量 (PowerShell): 对一个目录里所有 mp4 串行处理",
+        "  Get-ChildItem *.mp4 | ForEach-Object { rf dub $_.FullName }",
+        "",
+        "  # 先看效果再决定 (preview, 不渲染 MP4)",
+        "  rf dub ./clip.mp4 --preview-only",
+        "",
+        "  # 配上固定片尾「关注卡」(先用 rf clip 生成一次, 之后反复拼)",
+        "  rf clip --component kinetic-text --spec '{\"text\":\"关注 机械制造师\"}' \\",
+        "    --narration \"关注机械制造师官方账号,每天一个离谱发明\" -o outro.mp4",
+        "  rf dub ./clip.mp4 --append outro.mp4",
+    ].join("\n"))
+        .action(async (videoArg, opts) => {
+        const abs = path.resolve(videoArg);
+        if (!fsSync.existsSync(abs))
+            throw new Error(`video not found: ${abs}`);
+        const ext = path.extname(abs).toLowerCase();
+        const mime = VIDEO_EXT_TO_MIME[ext];
+        if (!mime) {
+            throw new Error(`unsupported video extension "${ext}" (supported: ${Object.keys(VIDEO_EXT_TO_MIME).join(" / ")})`);
+        }
+        const gameVolume = opts.gameVolume ?? 0.6;
+        if (!Number.isFinite(gameVolume) || gameVolume < 0 || gameVolume > 1) {
+            throw new Error(`--game-volume must be between 0 and 1 (got ${opts.gameVolume})`);
+        }
+        const subtitleStyle = (opts.subtitleStyle || "plate").toLowerCase();
+        if (!["plate", "stroke", "cinema"].includes(subtitleStyle)) {
+            throw new Error(`--subtitle-style must be plate | stroke | cinema (got ${opts.subtitleStyle})`);
+        }
+        const buf = await fs.readFile(abs);
+        if (buf.byteLength > MAX_BYTES) {
+            throw new Error(`video is ${fmtSize(buf.byteLength)} — exceeds the ${fmtSize(MAX_BYTES)} upload cap. ` +
+                `Compress / trim it first (e.g. ffmpeg -crf 28).`);
+        }
+        info(`Uploading ${path.basename(abs)} (${fmtSize(buf.byteLength)})...`);
+        const body = {
+            video: `data:${mime};base64,${buf.toString("base64")}`,
+            voice: opts.voice || "熊小二",
+            tts_model: opts.ttsModel || "vox/index-tts-2",
+            game_audio_volume: gameVolume,
+            subtitles: opts.subtitles !== false,
+            subtitle_style: subtitleStyle,
+            cover: opts.cover !== false,
+        };
+        if (opts.coverTemplate)
+            body.cover_template = opts.coverTemplate;
+        if (opts.coverTitle)
+            body.cover_title = opts.coverTitle;
+        if (opts.coverSubtitle)
+            body.cover_subtitle = opts.coverSubtitle;
+        if (opts.coverBadge)
+            body.cover_badge = opts.coverBadge;
+        if (opts.theme)
+            body.theme = opts.theme;
+        const appendFiles = opts.append ?? [];
+        if (appendFiles.length) {
+            const appendUris = [];
+            for (const f of appendFiles) {
+                const aAbs = path.resolve(f);
+                if (!fsSync.existsSync(aAbs))
+                    throw new Error(`--append file not found: ${aAbs}`);
+                const aExt = path.extname(aAbs).toLowerCase();
+                const aMime = VIDEO_EXT_TO_MIME[aExt];
+                if (!aMime)
+                    throw new Error(`--append: unsupported extension "${aExt}" (${path.basename(aAbs)})`);
+                const aBuf = await fs.readFile(aAbs);
+                if (aBuf.byteLength > MAX_BYTES) {
+                    throw new Error(`--append clip ${path.basename(aAbs)} is ${fmtSize(aBuf.byteLength)} — exceeds ${fmtSize(MAX_BYTES)}.`);
+                }
+                info(`  + append ${path.basename(aAbs)} (${fmtSize(aBuf.byteLength)})`);
+                appendUris.push(`data:${aMime};base64,${aBuf.toString("base64")}`);
+            }
+            body.append = appendUris;
+        }
+        if (opts.visionModel)
+            body.vision_model = opts.visionModel;
+        if (opts.scriptModel)
+            body.script_model = opts.scriptModel;
+        if (opts.previewOnly)
+            body.preview_only = true;
+        const submitted = await post("/api/v1/dub", body);
+        info(`Submitted task: ${submitted.task_id} — 反推 + 写脚本 + TTS + 渲染, 请稍候...`);
+        const t = await waitForTask(submitted.task_id, { pollMs: opts.pollMs, timeoutMs: opts.timeoutMs });
+        if (t.status !== "completed") {
+            throw new Error(t.error || `Task ended with status ${t.status}`);
+        }
+        const result = t.result;
+        if (result?.script?.length) {
+            info(`配音脚本 (${result.voice || opts.voice}):`);
+            for (const line of result.script)
+                info(`   ${line}`);
+        }
+        if (result?.render_pending) {
+            info(`MP4 render skipped (--preview-only). Run \`rf render ${t.id}\` to finalize.`);
+        }
+        else if (result?.video_url) {
+            const stdoutIsPipe = !process.stdout.isTTY;
+            const skipDownload = stdoutIsPipe && !opts.output;
+            let savedPath;
+            if (opts.output) {
+                savedPath = path.resolve(opts.output);
+            }
+            else if (!skipDownload) {
+                const stem = path.parse(abs).name;
+                savedPath = path.resolve(`${stem}-dub.mp4`);
+            }
+            if (savedPath) {
+                await downloadTo(result.video_url, savedPath);
+                success(`Saved → ${savedPath}`);
+            }
+        }
+        if (result?.generation_ms != null) {
+            const playback = result.duration != null ? `, video ${result.duration.toFixed(1)}s` : "";
+            info(`generated in ${humanDuration(result.generation_ms)}${playback}`);
+        }
+        if (result?.price_usd != null)
+            info(`charge: ${formatUsd(result.price_usd)}`);
+        if (isJson())
+            print({ task_id: t.id, status: t.status, ...result });
+    });
+}

package/dist/index.js

@@ -34,6 +34,8 @@ import { registerExtract } from "./commands/extract.js";
 import { registerMedia } from "./commands/media.js";
 import { registerScript } from "./commands/script.js";
 import { registerCompose } from "./commands/compose.js";
+import { registerDub } from "./commands/dub.js";
+import { registerClip } from "./commands/clip.js";
 import { registerVlog } from "./commands/vlog.js";
 import { error as logError } from "./utils/output.js";
 import { ApiCallError } from "./client.js";
@@ -109,6 +111,7 @@ program.addHelpText("after", [
     "  rf fetch '<抖音分享链接>' -t                    下载抖音 MP4 + ASR 转写",
     "  rf cover -i scene.png -t '标题' -o cover.png   单图渲染封面",
     "  rf assets describe ./photo.jpg                  图片 / 视频 → 一句话描述",
+    "  rf dub ./clip.mp4                              一个视频 → 自动解说配音+字幕成片",
     "  rf history list                                 看之前生成的视频",
     "  rf tasks list --status running                  看进行中的任务",
     "",
@@ -146,6 +149,8 @@ registerExtract(program);
 registerMedia(program);
 registerScript(program);
 registerCompose(program);
+registerDub(program);
+registerClip(program);
 registerVlog(program);
 async function main() {
     if (process.argv.length <= 2) {

package/package.json

@@ -1,44 +1,44 @@
-{
-  "name": "reelforge",
-  "version": "1.22.0",
-  "description": "AI 视频生成 CLI。一句话主题或自己的脚本 → 自动出抖音/TikTok/视频号竖屏 MP4。安装即用：`reelforge` 或短别名 `rf`。",
-  "license": "Apache-2.0",
-  "type": "module",
-  "bin": {
-    "reelforge": "./bin/reelforge.js",
-    "rf": "./bin/reelforge.js"
-  },
-  "files": [
-    "bin",
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=22"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json && node scripts/copy-docs.mjs",
-    "dev": "tsc -p tsconfig.json --watch",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "clean": "rimraf dist",
-    "prepublishOnly": "npm run clean && npm run build"
-  },
-  "dependencies": {
-    "commander": "^12.1.0",
-    "kleur": "^4.1.5"
-  },
-  "devDependencies": {
-    "@types/node": "^20.14.0",
-    "rimraf": "^6.0.1",
-    "typescript": "^5.5.0"
-  },
-  "keywords": [
-    "reelforge",
-    "ai-video",
-    "douyin",
-    "tiktok",
-    "shorts",
-    "vertical-video",
-    "cli"
-  ]
-}
+{
+  "name": "reelforge",
+  "version": "1.24.0",
+  "description": "AI 视频生成 CLI。一句话主题或自己的脚本 → 自动出抖音/TikTok/视频号竖屏 MP4。安装即用：`reelforge` 或短别名 `rf`。",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "reelforge": "./bin/reelforge.js",
+    "rf": "./bin/reelforge.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-docs.mjs",
+    "dev": "tsc -p tsconfig.json --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rimraf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "commander": "^12.1.0",
+    "kleur": "^4.1.5"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "rimraf": "^6.0.1",
+    "typescript": "^5.5.0"
+  },
+  "keywords": [
+    "reelforge",
+    "ai-video",
+    "douyin",
+    "tiktok",
+    "shorts",
+    "vertical-video",
+    "cli"
+  ]
+}