reelforge 0.9.0 → 0.10.0

package/README.md

@@ -152,6 +152,33 @@ rf create "..." --layout letterbox --layout-matte-color "#1a1a1a" # 柔和黑
 | `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

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;
@@ -167,6 +183,22 @@ function optsToBody(opts) {
         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)
@@ -322,6 +354,7 @@ export function registerCreate(program) {
         .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.")
@@ -398,6 +431,28 @@ export function registerCreate(program) {
         "  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(),
         "  · Pass --prompt-prefix to override (raw string always wins).",
@@ -437,6 +492,11 @@ export function registerCreate(program) {
         '  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",

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";
@@ -48,6 +50,7 @@ export function registerPipelines(program) {
         .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")
@@ -109,6 +112,25 @@ 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,
@@ -117,6 +139,8 @@ export function registerPipelines(program) {
             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,6 +1,6 @@
 {
   "name": "reelforge",
-  "version": "0.9.0",
+  "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",