reelforge 0.9.0 → 0.10.1

package/README.md

@@ -152,6 +152,35 @@ 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.
+
+**Publishing to short-video platforms (Douyin / TikTok / WeChat Channels)** — the default template 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 default template. For reference safe-zone numbers + a copy-pasteable CSS diff: `rf templates safezone [douyin|tiktok|wechat]`.
+
 ## 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

@@ -1,16 +1,26 @@
 /**
- * reelforge templates <list|preview|show>
+ * reelforge templates <list|preview|show|safezone>
  */
 import fs from "node:fs/promises";
+import kleur from "kleur";
 import { get, post } from "../client.js";
 import { downloadTo } from "../utils/download.js";
-import { print, success, table } from "../utils/output.js";
+import { isJson, print, success, table } from "../utils/output.js";
 import { buildTemplatePayload } from "./frames.js";
 export function registerTemplates(program) {
     const tpl = program
         .command("templates")
-        .description("Browse and preview HTML frame templates")
-        .helpOption("-h, --help", "show help");
+        .description("Browse templates, preview, view source, and look up platform safe zones")
+        .helpOption("-h, --help", "show help")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  rf templates list --size 1080x1920",
+        "  rf templates show 1080x1920/default.html -o my.html",
+        "  rf templates safezone                 # all platforms overview",
+        "  rf templates safezone douyin          # CSS diff for 抖音",
+        "  rf templates preview ./my.html -o p.png",
+    ].join("\n"));
     tpl
         .command("list")
         .description("List all HTML templates (static / image / video / asset, grouped by size)")
@@ -70,14 +80,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) => {
@@ -85,9 +96,149 @@ export function registerTemplates(program) {
         if (opts.output) {
             await fs.writeFile(opts.output, r.html, "utf-8");
             success(`Saved → ${opts.output} (${r.size}, ${r.type}, ${r.params.length} custom params)`);
+            if (/default\.html$/.test(key) && !isJson()) {
+                process.stderr.write(kleur.dim("  ↳ for short-video platform safe zones (抖音/TikTok/视频号), see ") +
+                    kleur.cyan("rf templates safezone") +
+                    "\n");
+            }
         }
         else {
             process.stdout.write(r.html);
         }
     });
+    tpl
+        .command("safezone [platform]")
+        .description("Reference safe-zone padding for short-video platforms (抖音 / TikTok / 视频号)")
+        .helpOption("-h, --help", "show help")
+        .addHelpText("after", [
+        "",
+        "Why this exists:",
+        "  Default 1080×1920 templates render to the full canvas. When a short-video",
+        "  app plays a 9:16 video on a taller phone (19.5:9 iPhone, 20:9/21:9 Android)",
+        "  it cover-crops ~96-180px each side, AND overlays its own UI on top, bottom,",
+        "  and the right action-button column. Important content near those edges gets",
+        "  cut or covered.",
+        "",
+        "  ReelForge does NOT bake platform-specific padding into the default template",
+        "  (UI changes; device crop varies). Use this command to look up reference",
+        "  numbers, then dial them into your own copy of default.html.",
+        "",
+        "Workflow:",
+        "  rf templates show 1080x1920/default.html -o my-douyin.html",
+        "  rf templates safezone douyin       # copy the CSS diff",
+        "  # paste the diff into my-douyin.html",
+        "  rf create '...' --frame-template ./my-douyin.html",
+        "",
+        "Examples:",
+        "  rf templates safezone              # overview table for all platforms",
+        "  rf templates safezone douyin       # detailed CSS diff for 抖音",
+        "  rf templates safezone tiktok",
+        "  rf templates safezone wechat       # 视频号",
+        "  rf templates safezone --json       # machine-readable",
+    ].join("\n"))
+        .action((platform) => {
+        if (isJson()) {
+            if (platform) {
+                const zone = PLATFORM_SAFEZONES[platform.toLowerCase()];
+                if (!zone) {
+                    print({ ok: false, error: `unknown platform: ${platform}`, known: Object.keys(PLATFORM_SAFEZONES) });
+                    process.exit(1);
+                }
+                print({ ok: true, platform: platform.toLowerCase(), ...zone });
+            }
+            else {
+                print({ ok: true, platforms: PLATFORM_SAFEZONES });
+            }
+            return;
+        }
+        if (platform) {
+            const key = platform.toLowerCase();
+            const zone = PLATFORM_SAFEZONES[key];
+            if (!zone) {
+                process.stderr.write(kleur.red(`✗ unknown platform: ${platform}\n`) +
+                    `  known: ${Object.keys(PLATFORM_SAFEZONES).join(", ")}\n`);
+                process.exit(1);
+            }
+            printPlatformDetail(key, zone);
+        }
+        else {
+            printPlatformOverview();
+        }
+    });
+}
+const PLATFORM_SAFEZONES = {
+    douyin: {
+        label: "Douyin (抖音)",
+        top: 250,
+        bottom: 400,
+        left: 150,
+        right: 250,
+        centerMax: 820,
+        reason: "Cover-crop on tall phones cuts ~96-180px per side; status bar ~250px; bottom caption+progress+buttons ~400px; right action-button column ~150px from the visible edge.",
+    },
+    tiktok: {
+        label: "TikTok",
+        top: 220,
+        bottom: 380,
+        left: 150,
+        right: 240,
+        centerMax: 820,
+        reason: "Same cover-crop behavior as Douyin; slightly smaller top tab area and bottom caption.",
+    },
+    wechat: {
+        label: "WeChat Channels (视频号)",
+        top: 200,
+        bottom: 350,
+        left: 120,
+        right: 120,
+        centerMax: 880,
+        reason: "Cover-crop similar; right-side action buttons are less obtrusive than 抖音/TikTok, so right padding can be smaller.",
+    },
+};
+function printPlatformOverview() {
+    process.stdout.write(kleur.bold("Reference safe-zone padding for 1080×1920 vertical video.\n") +
+        kleur.dim("Numbers cover ~90% of mainstream phones — verify on your own target devices.\n\n"));
+    table(Object.entries(PLATFORM_SAFEZONES).map(([key, z]) => ({
+        platform: key,
+        name: z.label,
+        top: z.top,
+        bottom: z.bottom,
+        left: z.left,
+        right: z.right,
+        "center-max": z.centerMax,
+    })));
+    process.stdout.write("\n" +
+        kleur.dim("CSS diff for a specific platform: ") +
+        kleur.cyan("rf templates safezone <platform>") +
+        "\n" +
+        kleur.dim("Start from default.html:           ") +
+        kleur.cyan("rf templates show 1080x1920/default.html -o my.html") +
+        "\n");
+}
+function printPlatformDetail(key, z) {
+    process.stdout.write(kleur.bold(`${z.label} — safe-zone padding for 1080×1920 vertical video.\n\n`) +
+        kleur.dim("Why: ") +
+        z.reason +
+        "\n\n" +
+        kleur.bold("Apply this CSS to your custom template (copy of default.html):\n\n") +
+        kleur.cyan(buildCssDiff(z)) +
+        "\n" +
+        kleur.dim("Note: layout=blur-bg / letterbox push title/subtitle into matte zones\n" +
+            `(y=0..420 / 1500..1920) that overlap ${z.label}'s UI heavily. For ${key}\n` +
+            "investment, layout=full + the padding above is the safest combo.\n"));
+}
+function buildCssDiff(z) {
+    return [
+        `    .title {`,
+        `      top: ${z.top}px;`,
+        `      max-width: ${z.centerMax}px;`,
+        `    }`,
+        `    .subtitle {`,
+        `      bottom: ${z.bottom}px;`,
+        `      max-width: ${z.centerMax}px;`,
+        `    }`,
+        `    body[data-brand-position$="left"]  .brand-corner { left:  ${z.left}px; }`,
+        `    body[data-brand-position$="right"] .brand-corner { right: ${z.right}px; }`,
+        "",
+    ].join("\n");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelforge",
-  "version": "0.9.0",
+  "version": "0.10.1",
   "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",