reelforge 0.8.0 → 0.10.0

package/README.md

@@ -1,240 +1,289 @@
-# reelforge
-
-> CLI for [ReelForge Studio](https://github.com/puke3615/ReelForge) — every REST API exposed as a command, with `--help` available 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 instance (`https://reelforge.timor419.com`). 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 |
-
-### Self-hosting
-
-If you want to run your own ReelForge Studio (own RelayX key, your own pricing) clone the upstream repo, `pnpm dev`, then point the CLI at it:
-
-```bash
-rf --server http://localhost:8501 health
-# or persist:
-export REELFORGE_SERVER=http://localhost:8501
-# or via `rf login <key> --server http://localhost:8501`
-```
-
-## Global options
-
-| flag | description |
-|---|---|
-| `-s, --server <url>` | ReelForge server URL (overrides `$REELFORGE_SERVER`; default `https://reelforge.timor419.com`) |
-| `-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 LLM (RelayX gateway by default) |
-| `llm presets` | List built-in RelayX model presets |
-| `tts edge -t <text> -o out.mp3` | Local Edge TTS synthesis (free) |
-| `tts relayx -t <text> -o out.mp3` | RelayX TTS (vox/index-tts-2, 149 built-in voices) |
-| `tts voices [--locale zh]` | List supported Edge TTS voices |
-| `images generate -p <prompt> -m rx-image-flux` | Image generation via RelayX (rx-image-z / rx-image-flux / rx-image-qwen) |
-
-### 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>` | RelayX paraformer-v2 ASR 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 is **audio-first**: scene-plan → one-shot TTS → ASR alignment → per-scene image generation → per-subtitle-line frame rendering → ffmpeg mux. One continuous master audio track; image cuts at scene boundaries; subtitle cuts 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 |
-
-### 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 |
-
-## 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. 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. Configure & test LLM (self-hosted)
-rf config set llm.api_key rx-xxxxx          # RelayX key (or your own provider key)
-rf config set llm.base_url https://relayx.timor419.com/v1
-rf config set llm.model anthropic/claude-4-7-sonnet
-rf llm chat -p 'one-sentence summary of antifragile'
-
-# 10. 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 RelayX 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
+
+> CLI for [ReelForge Studio](https://github.com/puke3615/ReelForge) — every REST API exposed as a command, with `--help` available 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 instance (`https://reelforge.timor419.com`). 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 |
+
+### Self-hosting
+
+If you want to run your own ReelForge Studio (own RelayX key, your own pricing) clone the upstream repo, `pnpm dev`, then point the CLI at it:
+
+```bash
+rf --server http://localhost:8501 health
+# or persist:
+export REELFORGE_SERVER=http://localhost:8501
+# or via `rf login <key> --server http://localhost:8501`
+```
+
+## Global options
+
+| flag | description |
+|---|---|
+| `-s, --server <url>` | ReelForge server URL (overrides `$REELFORGE_SERVER`; default `https://reelforge.timor419.com`) |
+| `-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 LLM (RelayX gateway by default) |
+| `llm presets` | List built-in RelayX model presets |
+| `tts edge -t <text> -o out.mp3` | Local Edge TTS synthesis (free) |
+| `tts relayx -t <text> -o out.mp3` | RelayX TTS (vox/index-tts-2, 149 built-in voices) |
+| `tts voices [--locale zh]` | List supported Edge TTS voices |
+| `images generate -p <prompt> -m rx-image-flux` | Image generation via RelayX (rx-image-z / rx-image-flux / rx-image-qwen) |
+
+### 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>` | RelayX paraformer-v2 ASR 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 is **audio-first**: scene-plan → one-shot TTS → ASR alignment → per-scene image generation → per-subtitle-line frame rendering → ffmpeg mux. One continuous master audio track; image cuts at scene boundaries; subtitle cuts 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 AI image is composited by ffmpeg OUTSIDE the HTML layer.
+- **`{{image}}` no longer exists.** Using `<img src="{{image}}">` is a hard error at submit time. Image is composited by ffmpeg.
+- 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.
+
+## 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. 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. Configure & test LLM (self-hosted)
+rf config set llm.api_key rx-xxxxx          # RelayX key (or your own provider key)
+rf config set llm.base_url https://relayx.timor419.com/v1
+rf config set llm.model anthropic/claude-4-7-sonnet
+rf llm chat -p 'one-sentence summary of antifragile'
+
+# 10. 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 RelayX 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/dist/commands/create.js

@@ -45,6 +45,22 @@ async function resolveTextOrFile(input) {
  * Returns undefined when input is missing/blank so the caller can branch on
  * "user actually provided this knob".
  */
+/**
+ * Tell apart a preset template key (e.g. "1080x1920/default.html") from a
+ * local file path. Heuristic: anything that starts with ./ ~ /, contains a
+ * backslash, or whose .html extension corresponds to an existing file on
+ * disk is treated as a local path. Otherwise it's a key for the server's
+ * preset registry. Mirrors the 0.7.x detection so muscle memory carries over.
+ */
+function looksLikeLocalHtmlPath(value) {
+    if (/^[.~]|^\//.test(value))
+        return true;
+    if (value.includes("\\"))
+        return true;
+    if (value.endsWith(".html") && fsSync.existsSync(value))
+        return true;
+    return false;
+}
 async function resolveRefImage(input, flagName) {
     if (input === undefined)
         return undefined;
@@ -163,8 +179,48 @@ function optsToBody(opts) {
         out.video_fps = opts.videoFps;
     if (opts.motion !== undefined)
         out.motion = opts.motion;
+    if (opts.layout !== undefined)
+        out.layout = opts.layout;
+    if (opts.layoutMatteColor !== undefined)
+        out.layout_matte_color = opts.layoutMatteColor;
+    if (opts.frameTemplate !== undefined) {
+        // Local .html path? Read inline and send as frame_template_html. Otherwise
+        // treat as a preset key. Same heuristic as 0.7.x had for --frame-template.
+        if (looksLikeLocalHtmlPath(opts.frameTemplate)) {
+            const abs = path.resolve(opts.frameTemplate);
+            if (!fsSync.existsSync(abs)) {
+                throw new Error(`--frame-template: local file not found: ${abs}`);
+            }
+            out.frame_template_html = fsSync.readFileSync(abs, "utf-8");
+        }
+        else {
+            out.frame_template = opts.frameTemplate;
+        }
+    }
+    if (opts.frameTemplateHtml !== undefined)
+        out.frame_template_html = opts.frameTemplateHtml;
     if (opts.subtitleStyle !== undefined)
         out.subtitle_style = opts.subtitleStyle;
+    if (opts.subtitleColor !== undefined)
+        out.subtitle_color = opts.subtitleColor;
+    if (opts.subtitleBackground !== undefined)
+        out.subtitle_background = opts.subtitleBackground;
+    // Brand: collect flat --brand-* flags into a nested brand object only if
+    // at least one is set. The pipeline-side field-level merge with
+    // config.video.default_brand will fill in unset fields.
+    const brand = {};
+    if (opts.brandHandle !== undefined)
+        brand.handle = opts.brandHandle;
+    if (opts.brandSlogan !== undefined)
+        brand.slogan = opts.brandSlogan;
+    if (opts.brandLogo !== undefined)
+        brand.logo_url = opts.brandLogo;
+    if (opts.brandPosition !== undefined)
+        brand.position = opts.brandPosition;
+    if (opts.brandColor !== undefined)
+        brand.color = opts.brandColor;
+    if (Object.keys(brand).length > 0)
+        out.brand = brand;
     if (opts.subtitleMinChars !== undefined)
         out.subtitle_min_chars = opts.subtitleMinChars;
     if (opts.subtitleHardMax !== undefined)
@@ -296,7 +352,18 @@ export function registerCreate(program) {
         .option("--style <preset>", "image style preset — shortcut for --prompt-prefix; see 'Style presets' below")
         .option("--character-ref <urlOrPath>", "reference image of the main character — locks identity across scenes. URL, data: URI, or local png/jpg/webp path (auto-encoded). Auto-enables rx-image-qwen-edit.")
         .option("--motion <preset>", "per-scene image animation intensity. See 'Motion presets' below. Default: lite.")
+        .option("--layout <preset>", "image layout within canvas: full (default) | blur-bg | letterbox. See 'Layout presets' below.")
+        .option("--layout-matte-color <css>", "letterbox matte color (CSS string, e.g. 'black', '#1a1a1a', '#2d3748'). Ignored unless --layout letterbox. Default: black.")
+        .option("--frame-template <keyOrPath>", "custom overlay template — preset key (e.g. 1080x1920/default.html) OR path to a local .html (auto-sent inline). See 'Custom templates' below.")
         .option("--subtitle-style <preset>", "subtitle visual style. See 'Subtitle styles' below. Default: plate.")
+        .option("--subtitle-color <css>", "override subtitle text color, e.g. '#ffeb3b'. Omit for preset default.")
+        .option("--subtitle-background <css>", "override plate-preset background, e.g. 'rgba(20,30,80,0.75)'. Other presets ignore.")
+        // --- Brand chrome (corner @handle / slogan / logo) ---
+        .option("--brand-handle <text>", "creator handle shown in corner, e.g. '@大灰狼'")
+        .option("--brand-slogan <text>", "creator slogan/tagline shown under handle")
+        .option("--brand-logo <urlOrPath>", "logo/avatar URL or local file path (PNG/JPG/WebP)")
+        .option("--brand-position <pos>", "where to render brand chrome: top-left | top-right | bottom-left | bottom-right")
+        .option("--brand-color <css>", "brand text color, e.g. '#ffffff' (default)")
         // --- Audio (TTS) ---
         .option("--voice-id <id>", "RelayX TTS voice id (default 专业解说); see `rf tts voices`")
         .option("--tts-speed <n>", "speech speed 0.5..2 (default 1.0)", parseFloat)
@@ -330,7 +397,7 @@ export function registerCreate(program) {
         "  fast    split long semantic chunks into multiple shots for variety",
         "",
         "Defaults:",
-        "  duration=45s · pace=normal · motion=lite · subtitle-style=plate · tts-speed=1.0",
+        "  duration=45s · pace=normal · motion=lite · layout=full · subtitle-style=plate · tts-speed=1.0",
         "",
         "Motion presets (--motion <preset>) — per-scene image animation intensity:",
         "  off     no motion, hard cuts between scenes — PPT / slideshow mode",
@@ -339,10 +406,52 @@ export function registerCreate(program) {
         "  · sub-animations are Fisher-Yates shuffled per task_id, so every video",
         "    cycles a different order — no two videos feel identical.",
         "",
+        "Layout presets (--layout <preset>) — how the AI image sits in the 1080×1920 canvas:",
+        "  full        image fills the whole canvas (default; high-impact, attention-grabbing).",
+        "              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 — moves in sync with the foreground (小红书/抖音 style).",
+        "              best for charts, screenshots, infographics, non-9:16 source content.",
+        "  letterbox   image at 1080×1080 centered, top/bottom is a solid matte (cinematic).",
+        "              use --layout-matte-color to change (default 'black'; try '#1a1a1a' for less harsh).",
+        "  · The image generator is asked for the actual on-screen size (1080×1920 for full,",
+        "    1080×1080 for blur-bg/letterbox), so you don't pay for pixels that get cropped.",
+        "",
         "Subtitle styles (--subtitle-style <preset>):",
         "  plate    semi-transparent black plate + white text (CapCut default; safest readability)",
         "  stroke   bold white text with black stroke + shadow, no plate (抖音网红风)",
         "  cinema   bottom black gradient backdrop + lighter text (film / documentary look)",
+        "  · use --subtitle-color / --subtitle-background to override the preset's colors",
+        "    e.g. --subtitle-color '#ffeb3b' --subtitle-background 'rgba(20,30,80,0.75)'",
+        "",
+        "Brand chrome (--brand-* flags or config.video.default_brand):",
+        "  Adds a constant @handle / slogan / logo block in a frame corner.",
+        "  --brand-position bottom-right --brand-handle '@大灰狼' --brand-slogan '财经科普'",
+        "  --brand-logo accepts URL / data: URI / local png/jpg/webp path.",
+        "  All fields optional; missing handle/slogan/logo are individually hidden.",
+        "  Per-request flags merge over config defaults field by field.",
+        "",
+        "Custom templates (--frame-template) — heavy brand customization:",
+        "  Override the entire overlay HTML when --brand-* and --subtitle-color aren't",
+        "  enough (custom top bar / footer / decoration / theme color etc.).",
+        "  --frame-template ./my-overlay.html       # local .html, auto sent inline",
+        "  --frame-template 1080x1920/default.html  # preset key (the built-in default)",
+        "",
+        "  Contract for custom HTML:",
+        "    · Canvas is 1080×1920 (pipeline-fixed; don't declare a different size meta).",
+        "    · Background must be transparent — the AI image is composited by ffmpeg",
+        "      OUTSIDE the HTML layer. {{image}} placeholder no longer exists; using",
+        "      <img src=\"{{image}}\"> in your template is a hard error at submit time.",
+        "    · Inject points the pipeline writes for you:",
+        "        {{title}} {{text}}     per-frame content",
+        "        {{index}} {{total}}    \"scene N of M\"",
+        "        {{layout}}             \"full\" | \"blur-bg\" | \"letterbox\" — react via",
+        "                               body[data-layout=\"...\"] CSS to move title /",
+        "                               subtitle to the matte zones when layout != full.",
+        "        {{subtitle_style}} / {{subtitle_color}} / {{subtitle_background}}",
+        "        {{brand_*}}            handle / slogan / logo / position / color",
+        "    · Bootstrap from the built-in:  rf templates show 1080x1920/default.html -o my-overlay.html",
+        "    · Inline HTML hard-capped at 2 MB.",
         "",
         "Image style presets (--style <preset>) — quick shortcut for --prompt-prefix:",
         formatStylePresetsList(),
@@ -378,6 +487,16 @@ export function registerCreate(program) {
         '  rf create "..." --motion lite --subtitle-style cinema   # 文艺纪录片',
         '  rf create "..." --motion off                            # PPT 模式（旧行为）',
         "",
+        "  # Layout combos",
+        '  rf create "财经日报" --layout blur-bg                       # 小红书 / 抖音 风（图表内容首选）',
+        '  rf create "纪录片片段" --layout letterbox --motion max       # 电影感',
+        '  rf create "..." --layout letterbox --layout-matte-color "#1a1a1a"  # 柔和黑',
+        "",
+        "  # Custom overlay HTML (heavy brand customization)",
+        "  rf templates show 1080x1920/default.html -o ./brand.html       # copy as starting point",
+        "  # ...edit brand.html: change colors, add top path bar / footer, etc.",
+        '  rf create "..." --frame-template ./brand.html                  # apply your custom overlay',
+        "",
         "  # Recipe + replay last",
         "  rf create --recipe ./space.recipe.json",
         "  rf create --redo                       # replay last successful create",
@@ -409,9 +528,15 @@ export function registerCreate(program) {
         if (opts.motion && !["off", "lite", "max"].includes(opts.motion)) {
             throw new Error(`--motion must be one of off|lite|max (got: ${opts.motion})`);
         }
+        if (opts.layout && !["full", "blur-bg", "letterbox"].includes(opts.layout)) {
+            throw new Error(`--layout must be one of full|blur-bg|letterbox (got: ${opts.layout})`);
+        }
         if (opts.subtitleStyle && !["plate", "stroke", "cinema"].includes(opts.subtitleStyle)) {
             throw new Error(`--subtitle-style must be one of plate|stroke|cinema (got: ${opts.subtitleStyle})`);
         }
+        if (opts.brandPosition && !["top-left", "top-right", "bottom-left", "bottom-right"].includes(opts.brandPosition)) {
+            throw new Error(`--brand-position must be one of top-left|top-right|bottom-left|bottom-right (got: ${opts.brandPosition})`);
+        }
         // 1. Layer defaults: --redo → --recipe → CLI opts → positional topic
         let body = {};
         if (opts.redo) {
@@ -452,6 +577,14 @@ export function registerCreate(program) {
             body.character_ref = resolvedChar;
         else
             delete body.character_ref;
+        // Brand logo: same URL / data: / local-file rules as character ref.
+        if (body.brand?.logo_url) {
+            const resolvedLogo = await resolveRefImage(body.brand.logo_url, "--brand-logo");
+            if (resolvedLogo !== undefined)
+                body.brand.logo_url = resolvedLogo;
+            else
+                delete body.brand.logo_url;
+        }
         // Validate content mode
         const hasTopic = typeof body.topic === "string" && body.topic.trim().length > 0;
         const hasScript = typeof body.script === "string" && body.script.trim().length > 0;

package/dist/commands/pipelines.js

@@ -1,4 +1,6 @@
 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";
@@ -46,6 +48,9 @@ export function registerPipelines(program) {
         .option("-d, --duration <sec>", "target video duration in seconds (generate mode; default 45)", (v) => parseInt(v, 10))
         .option("-p, --pace <pace>", "visual rhythm hint: slow | normal | fast (default normal)")
         .option("--motion <preset>", "per-scene image animation: off | lite (default) | max")
+        .option("--layout <preset>", "image layout: full (default) | blur-bg | letterbox. See below.")
+        .option("--layout-matte-color <css>", "letterbox matte color (CSS). Ignored unless --layout letterbox. Default: black.")
+        .option("--frame-template <keyOrPath>", "custom overlay: preset key OR local .html (auto sent inline). Canvas 1080×1920, transparent bg, no {{image}}.")
         .option("--subtitle-style <preset>", "subtitle visual style: plate (default) | stroke | cinema")
         .option("--image-model <id>", "RelayX image model (rx-image-z | rx-image-flux | rx-image-qwen | rx-image-qwen-edit)")
         .option("--prompt-prefix <text>", "style prefix prepended to every image prompt")
@@ -65,10 +70,19 @@ export function registerPipelines(program) {
         "Motion (per-scene animation):    off | lite | max",
         "Subtitle style:                  plate | stroke | cinema",
         "",
+        "Layout — how the AI image sits in the 1080×1920 canvas:",
+        "  full        image fills the whole canvas (default; punchy, 9:16-native content).",
+        "  blur-bg     image at 1080×1080 centered + same image scaled/blurred as background",
+        "              (小红书 / 抖音 style; best for charts, screenshots, non-9:16 source).",
+        "  letterbox   image at 1080×1080 centered + solid matte top/bottom (cinematic).",
+        "              tweak with --layout-matte-color (default 'black').",
+        "  · Image is generated at the actual on-screen size, so you don't pay for cropped pixels.",
+        "",
         "Examples:",
         "  rf pipelines standard -t 'why we explore space' -d 60 -o space.mp4",
         "  rf pipelines standard --script @script.txt -p slow --motion max -o out.mp4",
-        "  rf pipelines standard -t '宠物' --motion lite --subtitle-style cinema -o final.mp4",
+        "  rf pipelines standard -t '财经日报' --layout blur-bg --subtitle-style plate -o out.mp4",
+        "  rf pipelines standard -t '纪录片' --layout letterbox --motion max -o film.mp4",
         "",
         "Tip: `rf create` is a more ergonomic wrapper around the same endpoint.",
     ].join("\n"))).action(async (opts) => {
@@ -86,6 +100,9 @@ export function registerPipelines(program) {
         if (opts.motion && !["off", "lite", "max"].includes(opts.motion)) {
             throw new Error(`--motion must be one of off|lite|max (got: ${opts.motion})`);
         }
+        if (opts.layout && !["full", "blur-bg", "letterbox"].includes(opts.layout)) {
+            throw new Error(`--layout must be one of full|blur-bg|letterbox (got: ${opts.layout})`);
+        }
         if (opts.subtitleStyle && !["plate", "stroke", "cinema"].includes(opts.subtitleStyle)) {
             throw new Error(`--subtitle-style must be one of plate|stroke|cinema (got: ${opts.subtitleStyle})`);
         }
@@ -95,12 +112,35 @@ export function registerPipelines(program) {
             topic = await fs.readFile(topic.slice(1), "utf-8");
         if (script?.startsWith("@"))
             script = await fs.readFile(script.slice(1), "utf-8");
+        // --frame-template can be a preset key OR a local .html — same heuristic
+        // as 0.7.x. Local path is read and sent as frame_template_html inline.
+        let frame_template;
+        let frame_template_html;
+        if (opts.frameTemplate) {
+            const v = opts.frameTemplate;
+            const isLocal = /^[.~]|^\//.test(v) || v.includes("\\") ||
+                (v.endsWith(".html") && fsSync.existsSync(v));
+            if (isLocal) {
+                const abs = path.resolve(v);
+                if (!fsSync.existsSync(abs)) {
+                    throw new Error(`--frame-template: local file not found: ${abs}`);
+                }
+                frame_template_html = await fs.readFile(abs, "utf-8");
+            }
+            else {
+                frame_template = v;
+            }
+        }
         await submitAndMaybeWait("/api/v1/pipelines/standard", {
             topic,
             script,
             duration: opts.duration,
             pace: opts.pace,
             motion: opts.motion,
+            layout: opts.layout,
+            layout_matte_color: opts.layoutMatteColor,
+            frame_template,
+            frame_template_html,
             subtitle_style: opts.subtitleStyle,
             image_model: opts.imageModel,
             prompt_prefix: opts.promptPrefix,

package/dist/commands/templates.js

@@ -70,14 +70,15 @@ export function registerTemplates(program) {
         .addHelpText("after", [
         "",
         "Examples:",
-        "  # see what the default static template looks like",
-        "  rf templates show 1080x1920/static_default.html",
+        "  # print the standard pipeline's default overlay HTML",
+        "  rf templates show 1080x1920/default.html",
         "",
-        "  # copy a preset and tweak it as your own brand template",
-        "  rf templates show 1080x1920/image_default.html -o my-brand.html",
-        "  # ...edit my-brand.html...",
-        "  rf frames render -t ./my-brand.html --title 'X' -o frame.png",
+        "  # copy as a starting point for a custom brand template",
+        "  rf templates show 1080x1920/default.html -o my-brand.html",
+        "  # ...edit my-brand.html (change colors, add path bar / footer, etc.)...",
+        "  rf create '...' --frame-template ./my-brand.html",
         "",
+        "  Contract for custom HTML: see `rf create --help` → 'Custom templates'.",
         "  Get the list of keys via `rf templates list`.",
     ].join("\n"))
         .action(async (key, opts) => {

package/package.json

@@ -1,51 +1,51 @@
-{
-  "name": "reelforge",
-  "version": "0.8.0",
-  "description": "CLI for ReelForge Studio — AI video engine. Installs as both `reelforge` and the short alias `rf`. Every REST API exposed as a command, with --help on every level.",
-  "license": "Apache-2.0",
-  "type": "module",
-  "bin": {
-    "reelforge": "./bin/reelforge.js",
-    "rf": "./bin/reelforge.js"
-  },
-  "files": [
-    "bin",
-    "dist",
-    "README.md"
-  ],
-  "engines": {
-    "node": ">=18.17"
-  },
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "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",
-    "relayx",
-    "tts",
-    "edge-tts",
-    "ffmpeg",
-    "playwright",
-    "cli"
-  ],
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/puke3615/ReelForge.git",
-    "directory": "cli"
-  },
-  "homepage": "https://github.com/puke3615/ReelForge"
-}
+{
+  "name": "reelforge",
+  "version": "0.10.0",
+  "description": "CLI for ReelForge Studio — AI video engine. Installs as both `reelforge` and the short alias `rf`. Every REST API exposed as a command, with --help on every level.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "bin": {
+    "reelforge": "./bin/reelforge.js",
+    "rf": "./bin/reelforge.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "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",
+    "relayx",
+    "tts",
+    "edge-tts",
+    "ffmpeg",
+    "playwright",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/puke3615/ReelForge.git",
+    "directory": "cli"
+  },
+  "homepage": "https://github.com/puke3615/ReelForge"
+}