reelforge 0.5.2 → 0.5.4

package/README.md

@@ -94,8 +94,9 @@ Run `rf <command> --help` for full details on any of these.
 | command | what it does |
 |---|---|
 | `templates list [--size 1080x1920] [--type image]` | List HTML frame templates |
-| `templates preview <key> [-o out.png]` | Render a template preview |
-| `frames render -t <key> --title ... --text ...` | Render a single composed frame to PNG |
+| `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 |
@@ -153,8 +154,38 @@ rf config set llm.api_key rx-xxxxx          # RelayX key (or your own provider k
 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'
+
+# 6. Use your own HTML template (no PR/release needed)
+#    Any of -t / --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 --size 1080x1920 on the CLI.
+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}}` are reserved built-ins; 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).
+
+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.
+
 ## Tip — getting unstuck
 
 Every level has `--help`:

package/dist/commands/frames.js

@@ -1,3 +1,8 @@
+/**
+ * reelforge frames render
+ */
+import fs from "node:fs";
+import path from "node:path";
 import { post } from "../client.js";
 import { downloadTo } from "../utils/download.js";
 import { print, success } from "../utils/output.js";
@@ -8,15 +13,30 @@ export function registerFrames(program) {
         .helpOption("-h, --help", "show help");
     frames
         .command("render")
-        .description("Render one frame with custom values")
+        .description("Render one frame with custom values (preset key or your own local .html)")
         .helpOption("-h, --help", "show help")
-        .requiredOption("-t, --template <key>", "template key, e.g. 1080x1920/image_default.html")
+        .requiredOption("-t, --template <keyOrPath>", "template key (e.g. 1080x1920/image_default.html) OR path to a local .html file")
+        .option("--size <wxh>", "size for inline HTML when the file lacks <meta template:width|height>, e.g. 1080x1920")
         .option("--title <text>", "title placeholder", "")
         .option("--text <text>", "text placeholder", "")
         .option("--image <pathOrUrl>", "image placeholder")
         .option("--index <n>", "frame index (1-based)", parseInt, 1)
         .option("--values <json>", "JSON string with extra placeholder values, e.g. '{\"author\":\"Alice\"}'")
         .option("-o, --output <file>", "save the rendered PNG to this path")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  # preset",
+        "  rf frames render -t 1080x1920/image_default.html --title T --text X -o out.png",
+        "",
+        "  # custom local HTML (declare size via <meta template:width|height> or --size)",
+        "  rf frames render -t ./my-brand.html --size 1080x1920 \\",
+        "    --title 'Hello' --text 'world' --values '{\"author\":\"Alice\"}' -o out.png",
+        "",
+        "  Built-in placeholders: {{title}} {{text}} {{image}} {{index}}",
+        "  Custom params: {{name:type=default}} — type ∈ text|number|color|bool",
+        "  Limits: HTML ≤ 2 MB; sandbox blocks file://, intranet IPs, cloud-metadata.",
+    ].join("\n"))
         .action(async (opts) => {
         const extra = opts.values ? JSON.parse(opts.values) : {};
         const values = {
@@ -26,7 +46,8 @@ export function registerFrames(program) {
             index: opts.index,
             ...extra,
         };
-        const r = await post("/api/v1/frames/render", { template: opts.template, values });
+        const payload = buildTemplatePayload(opts.template, opts.size);
+        const r = await post("/api/v1/frames/render", { ...payload, values });
         if (opts.output) {
             await downloadTo(r.url, opts.output);
             success(`Saved → ${opts.output} (${r.width}x${r.height})`);
@@ -34,3 +55,31 @@ export function registerFrames(program) {
         print(r);
     });
 }
+/**
+ * Resolve `-t` into the right request fields:
+ *   - local file path → read HTML, send as `template_html`
+ *   - preset key (size/file.html) → send as `template`
+ */
+export function buildTemplatePayload(value, size) {
+    if (looksLikeLocalPath(value)) {
+        const abs = path.resolve(value);
+        if (!fs.existsSync(abs)) {
+            throw new Error(`Local template not found: ${abs}`);
+        }
+        const html = fs.readFileSync(abs, "utf-8");
+        return size ? { template_html: html, size } : { template_html: html };
+    }
+    return { template: value };
+}
+function looksLikeLocalPath(value) {
+    // Preset keys are always exactly "<size>/<file.html>" (one slash, no traversal).
+    // Anything that starts with ./, ../, /, ~ or contains a backslash is a path.
+    // Also: if it ends with .html AND the file exists on disk, treat as path.
+    if (/^[.~]|^\//.test(value))
+        return true;
+    if (value.includes("\\"))
+        return true;
+    if (value.endsWith(".html") && fs.existsSync(value))
+        return true;
+    return false;
+}

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,7 +48,8 @@ export function registerPipelines(program) {
         .option("--title <text>", "explicit video title (skip LLM title gen)")
         .option("-n, --n-scenes <n>", "number of scenes (mode=generate)", parseInt, 5)
         .option("--split-mode <mode>", "paragraph | line | sentence (mode=fixed)", "paragraph")
-        .option("--frame-template <key>", "template, e.g. 1080x1920/static_default.html", "1080x1920/static_default.html")
+        .option("--frame-template <keyOrPath>", "preset key (e.g. 1080x1920/static_default.html) OR path to a local .html file", "1080x1920/static_default.html")
+        .option("--frame-template-size <wxh>", "size for inline HTML when the file lacks <meta template:width|height>")
         .option("--image-model <id>", "RelayX image model (rx-image-z | rx-image-flux | rx-image-qwen) — only when template requires AI images")
         .option("--prompt-prefix <text>", "style prefix prepended to image prompts")
         .option("--tts-voice <id>", "Edge TTS voice", "zh-CN-YunjianNeural")
@@ -59,17 +62,22 @@ export function registerPipelines(program) {
         "  reelforge pipelines standard -t 'why we explore space' -n 5 -o space.mp4",
         "  reelforge pipelines standard -t @script.txt --mode fixed --split-mode paragraph --title 'My Show' -o out.mp4",
         "  reelforge pipelines standard -t '宠物' --frame-template 1080x1920/image_default.html --image-model rx-image-flux --prompt-prefix 'cinematic'",
+        "",
+        "  Custom HTML template (sent inline; no upload needed):",
+        "  reelforge pipelines standard -t '宠物' --frame-template ./my-brand.html -o final.mp4",
+        "  (declare size via <meta name=\"template:width|height\"> or pass --frame-template-size 1080x1920)",
     ].join("\n"))).action(async (opts) => {
         let text = opts.text;
         if (text.startsWith("@"))
             text = await fs.readFile(text.slice(1), "utf-8");
+        const tpl = resolveTemplateArg(opts.frameTemplate, opts.frameTemplateSize);
         await submitAndMaybeWait("/api/v1/pipelines/standard", {
             text,
             mode: opts.mode,
             title: opts.title,
             n_scenes: opts.nScenes,
             split_mode: opts.splitMode,
-            frame_template: opts.frameTemplate,
+            ...tpl,
             image_model: opts.imageModel,
             prompt_prefix: opts.promptPrefix,
             tts_voice: opts.ttsVoice,
@@ -79,3 +87,14 @@ export function registerPipelines(program) {
         }, { wait: opts.wait, output: opts.output, pollMs: opts.pollMs, timeoutMs: opts.timeoutMs });
     });
 }
+function resolveTemplateArg(value, size) {
+    if (/^[.~]|^\//.test(value) || value.includes("\\") || (value.endsWith(".html") && fsSync.existsSync(value))) {
+        const abs = path.resolve(value);
+        if (!fsSync.existsSync(abs)) {
+            throw new Error(`Local template not found: ${abs}`);
+        }
+        const html = fsSync.readFileSync(abs, "utf-8");
+        return size ? { frame_template_inline: html, frame_template_size: size } : { frame_template_inline: html };
+    }
+    return { frame_template: value };
+}

package/dist/commands/templates.js

@@ -1,6 +1,11 @@
+/**
+ * reelforge templates <list|preview|show>
+ */
+import fs from "node:fs/promises";
 import { get, post } from "../client.js";
 import { downloadTo } from "../utils/download.js";
-import { print, table, success } from "../utils/output.js";
+import { print, success, table } from "../utils/output.js";
+import { buildTemplatePayload } from "./frames.js";
 export function registerTemplates(program) {
     const tpl = program
         .command("templates")
@@ -28,16 +33,27 @@ export function registerTemplates(program) {
         })));
     });
     tpl
-        .command("preview <key>")
-        .description("Render a preview frame from a template (e.g. 1080x1920/static_default.html)")
+        .command("preview <keyOrPath>")
+        .description("Render a preview frame from a preset key (e.g. 1080x1920/static_default.html) or a local .html file path")
         .helpOption("-h, --help", "show help")
+        .option("--size <wxh>", "size for inline HTML when the file lacks <meta template:width|height>")
         .option("--title <text>", "title placeholder", "示例标题")
         .option("--text <text>", "text placeholder", "示例字幕，用于预览模板效果。")
         .option("--image <pathOrUrl>", "image placeholder")
         .option("-o, --output <file>", "save preview PNG to this path")
-        .action(async (key, opts) => {
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  rf templates preview 1080x1920/static_default.html -o p.png",
+        "  rf templates preview ./my-brand.html --size 1080x1920 -o p.png",
+        "",
+        "  Local .html: declare size via <meta name=\"template:width|height\"> or pass --size.",
+        "  HTML ≤ 2 MB; sandbox blocks file://, intranet IPs, cloud-metadata.",
+    ].join("\n"))
+        .action(async (keyOrPath, opts) => {
+        const payload = buildTemplatePayload(keyOrPath, opts.size);
         const r = await post("/api/v1/templates/preview", {
-            template: key,
+            ...payload,
             values: { title: opts.title, text: opts.text, image: opts.image || "", index: 1 },
         });
         if (opts.output) {
@@ -46,4 +62,32 @@ export function registerTemplates(program) {
         }
         print(r);
     });
+    tpl
+        .command("show <key>")
+        .description("Print or save the source HTML of a preset template — use as a starting point for your own")
+        .helpOption("-h, --help", "show help")
+        .option("-o, --output <file>", "save HTML to this path (otherwise print to stdout)")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  # see what the default static template looks like",
+        "  rf templates show 1080x1920/static_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",
+        "",
+        "  Get the list of keys via `rf templates list`.",
+    ].join("\n"))
+        .action(async (key, opts) => {
+        const r = await get(`/api/v1/templates/source?key=${encodeURIComponent(key)}`);
+        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)`);
+        }
+        else {
+            process.stdout.write(r.html);
+        }
+    });
 }

package/package.json

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