reelforge 0.5.1 → 0.5.3

package/README.md

@@ -94,8 +94,8 @@ 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** |
+| `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 +153,28 @@ 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 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
+
+`{{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,7 @@
 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 +29,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) {

package/dist/commands/tts.js

@@ -67,14 +67,45 @@ export function registerTts(program) {
     });
     tts
         .command("voices")
-        .description("List supported Edge-TTS voices (id, label, locale, gender)")
+        .description("List TTS voices: Edge (built-in 25) or RelayX (live, per-model)")
         .helpOption("-h, --help", "show help")
-        .option("--locale <prefix>", "filter by locale prefix, e.g. zh, en-US")
+        .option("--provider <p>", "edge (default) | relayx", "edge")
+        .option("--model <id>", "RelayX TTS model id (required when --provider=relayx), e.g. vox/index-tts-2")
+        .option("--locale <prefix>", "Edge only: filter by locale prefix, e.g. zh, en-US")
+        .option("--refresh", "RelayX only: bypass the 5-minute server-side cache")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  reelforge tts voices                                              # Edge 25 built-in",
+        "  reelforge tts voices --locale zh                                  # Edge filtered",
+        "  reelforge tts voices --provider relayx --model vox/index-tts-2    # 149 vox voices",
+        "  reelforge tts voices --provider relayx --model minimax/speech-2.6-hd",
+    ].join("\n"))
         .action(async (opts) => {
-        const r = await get("/api/v1/tts/voices");
-        let voices = r.voices;
-        if (opts.locale)
-            voices = voices.filter((v) => v.locale.startsWith(opts.locale));
-        table(voices);
+        const provider = opts.provider || "edge";
+        if (provider === "edge") {
+            const r = await get("/api/v1/tts/voices?provider=edge");
+            let voices = r.voices;
+            if (opts.locale)
+                voices = voices.filter((v) => v.locale.startsWith(opts.locale));
+            table(voices);
+            return;
+        }
+        if (provider === "relayx") {
+            if (!opts.model)
+                throw new Error("--model is required when --provider=relayx (e.g. vox/index-tts-2)");
+            const qs = new URLSearchParams({ provider: "relayx", model: opts.model });
+            if (opts.refresh)
+                qs.set("refresh", "1");
+            const r = await get(`/api/v1/tts/voices?${qs.toString()}`);
+            table(r.voices.map((v) => ({
+                id: v.id,
+                label: v.label,
+                featured: v.featured ? "★" : "",
+                demo_url: v.demo_url ?? "",
+            })));
+            return;
+        }
+        throw new Error(`Unknown --provider: ${provider} (expected "edge" or "relayx")`);
     });
 }

package/package.json

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