reelforge 0.10.0 → 0.11.0

package/README.md

@@ -179,6 +179,8 @@ rf create "我的视频" --frame-template ./my-brand.html
 
 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

@@ -155,6 +155,8 @@ function optsToBody(opts) {
         out.topic = opts.topic;
     if (opts.script !== undefined)
         out.script = opts.script;
+    if (opts.title !== undefined)
+        out.title = opts.title;
     if (opts.duration !== undefined)
         out.duration = opts.duration;
     if (opts.pace !== undefined)
@@ -344,6 +346,7 @@ export function registerCreate(program) {
         // --- Content (exactly one of --topic / --script) ---
         .option("-t, --topic <text>", "video topic; AI writes the script (mode=generate). Prefix with @file to read from disk.")
         .option("--script <text>", "your own master script text; AI just plans scenes + visuals (mode=fixed). Prefix with @file to read from disk.")
+        .option("--title <text>", "hard-override video title; LLM will NOT auto-summarize. Useful for compliance-sensitive content (e.g. financial). Prefix with @file to read from disk. Pass --title '' (empty string) to explicitly suppress title rendering. Omit to keep LLM auto-title.")
         .option("-d, --duration <sec>", "target video duration in seconds (generate mode only; default 45). LLM aims for ~duration × 5 chars of narration.", (v) => parseInt(v, 10))
         .option("-p, --pace <pace>", "visual rhythm hint passed to the LLM: slow | normal | fast (default normal). LLM still decides the actual scene count from semantic structure.")
         // --- Visual ---
@@ -569,6 +572,11 @@ export function registerCreate(program) {
         if (typeof body.script === "string") {
             body.script = await resolveTextOrFile(body.script);
         }
+        // Title: resolve @file when present. Empty string is a legit value (=
+        // suppress rendering) and must pass through verbatim, never as @file.
+        if (typeof body.title === "string" && body.title.startsWith("@")) {
+            body.title = await resolveTextOrFile(body.title);
+        }
         // Resolve character ref: local file path → data: URI (RelayX accepts
         // both https:// and data: in image_urls). Done after layering so a
         // recipe can carry the ref by path too.

package/dist/commands/pipelines.js

@@ -45,6 +45,7 @@ export function registerPipelines(program) {
         .helpOption("-h, --help", "show help")
         .option("-t, --topic <text>", "video topic (mode=generate). Use @file to read from disk.")
         .option("--script <text>", "your own master script text (mode=fixed). Use @file to read from disk.")
+        .option("--title <text>", "hard-override video title; LLM will NOT auto-summarize. Useful for compliance-sensitive content. Use @file to read from disk. Pass --title '' (empty) to explicitly suppress title rendering. Omit to keep LLM auto-title.")
         .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")
@@ -108,10 +109,15 @@ export function registerPipelines(program) {
         }
         let topic = opts.topic;
         let script = opts.script;
+        let title = opts.title;
         if (topic?.startsWith("@"))
             topic = await fs.readFile(topic.slice(1), "utf-8");
         if (script?.startsWith("@"))
             script = await fs.readFile(script.slice(1), "utf-8");
+        // Title: resolve @file only when prefix present. Empty "" is a legit value
+        // (= suppress title) and must pass through verbatim.
+        if (title?.startsWith("@"))
+            title = await fs.readFile(title.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;
@@ -134,6 +140,7 @@ export function registerPipelines(program) {
         await submitAndMaybeWait("/api/v1/pipelines/standard", {
             topic,
             script,
+            title,
             duration: opts.duration,
             pace: opts.pace,
             motion: opts.motion,

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)")
@@ -86,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.10.0",
+  "version": "0.11.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",