reelforge 0.5.4 → 0.6.0

package/README.md

@@ -79,15 +79,14 @@ Run `rf <command> --help` for full details on any of these.
 | `tts voices [--locale zh]` | List supported Edge TTS voices |
 | `images generate -p <prompt> -m rx-image-flux` | Image generation via RelayX (rx-image-z / rx-image-flux / rx-image-qwen) |
 
-### Content generation
+### Content / audio / subtitle atomics
 
 | command | what it does |
 |---|---|
-| `content narration -t <topic>` | Generate N narration sentences from a topic |
-| `content split -s <script>` | Split a fixed script into narrations |
-| `content image-prompts -i <file>` | English image prompts from narration list |
-| `content title -c <content>` | Generate a short video title |
-| `content asset-script --intent ... --assets <file>` | Asset-based scene script |
+| `content scene-plan -t <topic>` | Single LLM call: title + master script + per-scene image prompts (replaces the old narration / split / image-prompts / title trio) |
+| `content scene-plan --script <text-or-@file>` | Same, but the user supplies the script verbatim — LLM only segments and writes image prompts |
+| `audio transcribe -f <file>` / `--url <url>` | RelayX paraformer-v2 ASR with word + segment timestamps |
+| `subtitles split -t <text-or-@file>` | Deterministic tiered-punctuation subtitle line splitter (pure function, zero billing) |
 
 ### Composition
 
@@ -106,9 +105,11 @@ Run `rf <command> --help` for full details on any of these.
 
 All `pipelines *` commands submit an **async task** and (by default) poll until it finishes with a live progress indicator on stderr. Use `--no-wait` to return immediately with a `task_id`, then `rf tasks wait <id>` later.
 
+The standard pipeline is **audio-first**: scene-plan → one-shot TTS → ASR alignment → per-scene image generation → per-subtitle-line frame rendering → ffmpeg mux. One continuous master audio track; image cuts at scene boundaries; subtitle cuts at line boundaries.
+
 | command | what it does |
 |---|---|
-| `pipelines standard -t <topic\|script>` | Topic / script → narration → frames → final MP4 |
+| `pipelines standard -t <topic>` (or `--script <text>`) | Audio-first pipeline; `-d/--duration` and `-p/--pace` are the two main knobs |
 
 ### Resources
 
@@ -132,35 +133,49 @@ All `pipelines *` commands submit an **async task** and (by default) poll until
 ## Examples
 
 ```bash
-# 1. One-click out a video (auto-saves to ./<title>-<id>.mp4 in cwd)
+# 1. One-click out a video (45s default, AI writes the script)
 rf create "为什么我们还没找到外星文明？"
 
-# 2. Same, but with a fixed script and explicit output path
+# 2. Longer video with a slower visual rhythm
+rf create "深夜便利店的灯光" -d 90 -p slow
+
+# 3. Your own script — no narration-splitting on your side, the pipeline handles it
+rf create --script @./my-script.txt
+rf create --script "雨水缓缓滑落在玻璃窗上，像是无声的泪珠。"
+
+# 4. Pick a built-in visual style preset
+rf create "美食教程" --style photorealistic
+
+# 5. Pipeline form with explicit output path
 rf pipelines standard \
-  -t "Hello world. This is scene one.\n\nThis is scene two." \
-  --mode fixed --title "Smoke Test" \
-  --frame-template 1080x1920/static_default.html \
-  --tts-voice en-US-AriaNeural -o smoke.mp4
+  --script @./script.txt \
+  --frame-template 1080x1920/image_default.html \
+  -p normal -o smoke.mp4
 
-# 3. Inspect existing tasks & redownload a finished video
+# 6. Inspect existing tasks & redownload a finished video
 rf tasks list --limit 5
 rf history get <task-id> --download recovered.mp4
 
-# 4. JSON pipe for automation
+# 7. Atomics for stand-alone use
+rf content scene-plan -t "雨天的玻璃窗" -d 45 --json | jq .scenes
+rf audio transcribe -f narration.mp3 --json | jq '.words[:5]'
+rf subtitles split -t @./narration.txt --min 10 --hard-max 24
+
+# 8. JSON pipe for automation
 rf llm presets --json | jq '.[].defaultModel'
 
-# 5. Configure & test LLM (self-hosted)
+# 9. Configure & test LLM (self-hosted)
 rf config set llm.api_key rx-xxxxx          # RelayX key (or your own provider key)
 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.
+# 10. Use your own HTML template (no PR/release needed)
+#     Any --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 --frame-template-size 1080x1920.
 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
@@ -180,12 +195,32 @@ rf templates show 1080x1920/image_default.html -o my-brand.html    # save and ed
 
 `{{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).
 
+#### Template type — does the pipeline generate an AI image per scene?
+
+When you ship an inline template through `rf create` / `rf pipelines standard`, ReelForge needs to know whether each scene should kick off RelayX image generation. Resolution priority (high → low):
+
+1. Explicit flag — `--frame-template-type image|static|asset` (or `frame_template_type` in the API body).
+2. Inside the HTML — `<meta name="template:type" content="image">` (or `static` / `asset`).
+3. **Default: `image`** — best practice for zero-config users. If your template doesn't reference scene imagery (pure-text card, etc.), declare `static` explicitly to skip image generation and its cost.
+
+The placeholder `{{image}}` no longer doubles as a type signal — declare type explicitly.
+
 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.
 
+#### API field reference
+
+| endpoint | inline HTML field | size field | type field |
+|---|---|---|---|
+| `POST /api/v1/frames/render` | `template_html` | `size` | — (n/a, no image generation) |
+| `POST /api/v1/templates/preview` | `template_html` | `size` | — |
+| `POST /api/v1/pipelines/standard` | `frame_template_inline` | `frame_template_size` | `frame_template_type` |
+
+The pipeline endpoint uses the `frame_template_*` prefix because it already has a `frame_template` field (preset key). The single-frame endpoints use the shorter `template_html` because they don't.
+
 ## Tip — getting unstuck
 
 Every level has `--help`:

package/dist/commands/audio.js

@@ -0,0 +1,73 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { uploadMultipart, post } from "../client.js";
+import { print } from "../utils/output.js";
+export function registerAudio(program) {
+    const audio = program
+        .command("audio")
+        .description("Audio atomics — transcription / forced alignment")
+        .helpOption("-h, --help", "show help");
+    audio
+        .command("transcribe")
+        .description("Transcribe an audio file to text + word-level timestamps (RelayX paraformer-v2)")
+        .helpOption("-h, --help", "show help")
+        .option("-f, --file <path>", "local audio file (mp3/wav/m4a). Use this OR --url.")
+        .option("-u, --url <url>", "remote audio URL — server downloads and transcribes.")
+        .option("-l, --language <code>", "language hint (e.g. zh, en). Optional — paraformer-v2 auto-detects.")
+        .option("-m, --model <id>", "override ASR model id (default alibaba/paraformer-v2)")
+        .option("-o, --output <file>", "write the full JSON response to this file as well as stdout")
+        .addHelpText("after", [
+        "",
+        "Examples:",
+        "  rf audio transcribe -f ./narration.mp3",
+        "  rf audio transcribe --url https://example.com/clip.mp3 --language zh",
+        "  rf audio transcribe -f ./voice.wav --json | jq '.words[:5]'",
+    ].join("\n"))
+        .action(async (opts) => {
+        if (!opts.file && !opts.url) {
+            throw new Error("either --file or --url is required");
+        }
+        if (opts.file && opts.url) {
+            throw new Error("--file and --url are mutually exclusive");
+        }
+        let r;
+        if (opts.file) {
+            const buf = await fs.readFile(opts.file);
+            const filename = path.basename(opts.file);
+            const ext = path.extname(filename).toLowerCase();
+            const mime = ext === ".wav" ? "audio/wav" :
+                ext === ".m4a" ? "audio/mp4" :
+                    ext === ".flac" ? "audio/flac" :
+                        ext === ".ogg" ? "audio/ogg" :
+                            "audio/mpeg";
+            const fileBlob = new File([new Uint8Array(buf)], filename, { type: mime });
+            const fields = { file: fileBlob };
+            if (opts.language)
+                fields.language = opts.language;
+            if (opts.model)
+                fields.model = opts.model;
+            r = await uploadMultipart("/api/v1/audio/transcribe", fields);
+        }
+        else {
+            const body = { audio_url: opts.url };
+            if (opts.language)
+                body.language = opts.language;
+            if (opts.model)
+                body.model = opts.model;
+            r = await post("/api/v1/audio/transcribe", body);
+        }
+        if (opts.output) {
+            await fs.writeFile(opts.output, JSON.stringify(r, null, 2), "utf-8");
+        }
+        print({
+            model: r.model,
+            language: r.language,
+            duration: r.duration,
+            text: r.text,
+            n_segments: r.segments.length,
+            n_words: r.words.length,
+            segments: r.segments,
+            words: r.words,
+        });
+    });
+}

package/dist/commands/content.js

@@ -4,109 +4,63 @@ import { print } from "../utils/output.js";
 export function registerContent(program) {
     const content = program
         .command("content")
-        .description("LLM-based content generators (script, image prompts, titles, asset scripts)")
+        .description("Content atomics — scene planning (master script + image prompts in one call)")
         .helpOption("-h, --help", "show help");
     content
-        .command("narration")
-        .description("Generate N narration sentences from a topic")
+        .command("scene-plan")
+        .description("Generate a master script + per-scene image prompts (replaces narration/image-prompts/title)")
         .helpOption("-h, --help", "show help")
-        .requiredOption("-t, --topic <text>", "the video topic")
-        .option("-n, --n-scenes <n>", "number of scenes", parseInt, 5)
-        .option("--min-words <n>", "minimum words per narration", parseInt, 5)
-        .option("--max-words <n>", "maximum words per narration", parseInt, 20)
-        .addHelpText("after", "\nExample:\n  reelforge content narration -t 'why we explore space' -n 5")
-        .action(async (opts) => {
-        const r = await post("/api/v1/content/narration", {
-            topic: opts.topic,
-            n_scenes: opts.nScenes,
-            min_words: opts.minWords,
-            max_words: opts.maxWords,
-        });
-        print(r);
-    });
-    content
-        .command("split")
-        .description("Split a fixed script into narrations (no LLM cost)")
-        .helpOption("-h, --help", "show help")
-        .requiredOption("-s, --script <text>", "raw script text (use @file for a file)")
-        .option("-m, --mode <mode>", "paragraph | line | sentence", "paragraph")
-        .addHelpText("after", "\nExample:\n  reelforge content split -s @script.txt -m sentence")
-        .action(async (opts) => {
-        let script = opts.script;
-        if (script.startsWith("@"))
-            script = await fs.readFile(script.slice(1), "utf-8");
-        const r = await post("/api/v1/content/narration/split", { script, mode: opts.mode });
-        print(r);
-    });
-    content
-        .command("image-prompts")
-        .description("Generate English image-generation prompts from narrations")
-        .helpOption("-h, --help", "show help")
-        .requiredOption("-i, --narrations <file>", "file with one narration per line (or @file)")
-        .option("--prefix <text>", "style prefix prepended to each prompt")
-        .option("--min-words <n>", "minimum words per prompt", parseInt, 30)
-        .option("--max-words <n>", "maximum words per prompt", parseInt, 60)
-        .addHelpText("after", "\nExample:\n  reelforge content image-prompts -i narrations.txt --prefix 'cinematic'")
-        .action(async (opts) => {
-        let src = opts.narrations;
-        if (src.startsWith("@"))
-            src = src.slice(1);
-        const text = await fs.readFile(src, "utf-8");
-        const narrations = text.split(/\r?\n/).map((s) => s.trim()).filter(Boolean);
-        const r = await post("/api/v1/content/image-prompts", {
-            narrations,
-            prompt_prefix: opts.prefix,
-            min_words: opts.minWords,
-            max_words: opts.maxWords,
-        });
-        print(r);
-    });
-    content
-        .command("title")
-        .description("Generate a short video title from content")
-        .helpOption("-h, --help", "show help")
-        .requiredOption("-c, --content <text>", "content to title (use @file)")
-        .option("--max-length <n>", "maximum characters", parseInt, 15)
-        .action(async (opts) => {
-        let body = opts.content;
-        if (body.startsWith("@"))
-            body = await fs.readFile(body.slice(1), "utf-8");
-        const r = await post("/api/v1/content/title", {
-            content: body,
-            max_length: opts.maxLength,
-        });
-        print(r);
-    });
-    content
-        .command("asset-script")
-        .description("Generate a scene script that assigns user-uploaded assets to scenes")
-        .helpOption("-h, --help", "show help")
-        .requiredOption("--intent <text>", "video intent / purpose")
-        .option("--title <text>", "optional video title")
-        .option("--duration <s>", "target duration in seconds", parseInt, 30)
-        .requiredOption("--assets <file>", "file with one asset per line, format: `path | description`")
+        .option("-t, --topic <text>", "video topic; AI writes the script (generate mode). Use @file for disk input.")
+        .option("--script <text>", "your own master script text (fixed mode). Use @file for disk input.")
+        .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("-m, --model <id>", "override LLM model")
         .addHelpText("after", [
         "",
-        "Example assets.txt:",
-        "  data/uploads/cat.jpg | A fluffy cat",
-        "  data/uploads/dog.jpg | A happy dog wagging tail",
+        "Two modes (exactly one required):",
+        "  generate    -t / --topic <text>     LLM writes both script and image prompts",
+        "  fixed       --script @file or text  LLM only segments + writes image prompts; text unchanged verbatim",
+        "",
+        "Examples:",
+        "  rf content scene-plan -t '深夜便利店' -d 60 -p slow",
+        "  rf content scene-plan --script @./my-script.txt -p fast",
+        "  rf content scene-plan -t '雨天的玻璃窗' --json | jq .scenes",
     ].join("\n"))
         .action(async (opts) => {
-        const raw = await fs.readFile(opts.assets, "utf-8");
-        const assets = raw
-            .split(/\r?\n/)
-            .map((s) => s.trim())
-            .filter(Boolean)
-            .map((line) => {
-            const [p, d] = line.split("|").map((s) => s.trim());
-            return { path: p, description: d || "" };
-        });
-        const r = await post("/api/v1/content/asset-script", {
-            intent: opts.intent,
-            title: opts.title,
-            duration: opts.duration,
-            assets,
+        const hasTopic = typeof opts.topic === "string" && opts.topic.length > 0;
+        const hasScript = typeof opts.script === "string" && opts.script.length > 0;
+        if (!hasTopic && !hasScript) {
+            throw new Error("either --topic / -t or --script is required");
+        }
+        if (hasTopic && hasScript) {
+            throw new Error("--topic and --script are mutually exclusive");
+        }
+        if (opts.pace && !["slow", "normal", "fast"].includes(opts.pace)) {
+            throw new Error(`--pace must be one of slow|normal|fast (got: ${opts.pace})`);
+        }
+        let topic = opts.topic;
+        let script = opts.script;
+        if (topic?.startsWith("@"))
+            topic = (await fs.readFile(topic.slice(1), "utf-8")).trim();
+        if (script?.startsWith("@"))
+            script = (await fs.readFile(script.slice(1), "utf-8")).trim();
+        const body = {};
+        if (topic)
+            body.topic = topic;
+        if (script)
+            body.script = script;
+        if (opts.duration !== undefined)
+            body.duration = opts.duration;
+        if (opts.pace)
+            body.pace = opts.pace;
+        if (opts.model)
+            body.model = opts.model;
+        const r = await post("/api/v1/content/scene-plan", body);
+        print({
+            mode: r.mode,
+            title: r.title,
+            n_scenes: r.scenes.length,
+            scenes: r.scenes,
         });
-        print(r);
     });
 }

package/dist/commands/create.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import fsSync from "node:fs";
 import path from "node:path";
 import os from "node:os";
 import { post } from "../client.js";
@@ -7,30 +8,58 @@ import { downloadTo } from "../utils/download.js";
 import { info, print, success, warn } from "../utils/output.js";
 const LAST_CREATE_PATH = path.join(os.homedir(), ".reelforge", "last-create.json");
 // ── Cost estimation (mirrors server src/lib/billing.ts) ──────────
-const IMAGE_UNITS = 3; // matches ATOMIC_UNITS["images.generate"] in src/lib/billing.ts
-const TTS_RELAYX_UNITS = 1; // matches ATOMIC_UNITS["tts.relayx"]
+const PLAN_UNITS = 1;
+const TTS_UNITS = 1;
+const ASR_UNITS = 1;
+const IMAGE_UNITS = 3;
+const CHARS_PER_SEC_ZH = 5;
+const TARGET_SEC_PER_SCENE = 8;
 function estimateUnits(body) {
-    const mode = body.mode || "generate";
-    const titleExplicit = !!body.title;
-    const N = body.n_scenes ?? 5;
-    // Template type from filename prefix
-    const tplKey = body.frame_template || "1080x1920/static_default.html";
-    const tplBase = (tplKey.split("/").pop() || "").toLowerCase();
-    const tplType = tplBase.startsWith("static_")
-        ? "static"
-        : tplBase.startsWith("asset_")
-            ? "asset"
-            : "image";
-    const mediaPerFrame = tplType === "image" ? IMAGE_UNITS : 0;
-    const ttsMode = body.tts_inference_mode || "edge";
-    const ttsPerFrame = ttsMode === "relayx" ? TTS_RELAYX_UNITS : 0;
-    const narrations = mode === "generate" ? 1 : 0;
-    const title = titleExplicit ? 0 : 1;
-    const imagePrompts = tplType === "static" ? 0 : 1;
-    return narrations + title + imagePrompts + N * (ttsPerFrame + mediaPerFrame);
+    let tplType;
+    if (body.frame_template_inline) {
+        if (body.frame_template_type) {
+            tplType = body.frame_template_type;
+        }
+        else {
+            const m = body.frame_template_inline.match(/<meta[^>]+name=["']template:type["'][^>]+content=["']([a-z]+)["']/i);
+            const v = m?.[1].toLowerCase();
+            tplType = v === "static" || v === "asset" || v === "image" ? v : "image";
+        }
+    }
+    else {
+        const tplKey = body.frame_template || "1080x1920/image_default.html";
+        const tplBase = (tplKey.split("/").pop() || "").toLowerCase();
+        tplType = tplBase.startsWith("static_")
+            ? "static"
+            : tplBase.startsWith("asset_")
+                ? "asset"
+                : "image";
+    }
+    // Estimated scene count: from script length (fixed) or from duration (generate).
+    let estimatedScenes;
+    if (body.script) {
+        const estSec = body.script.length / CHARS_PER_SEC_ZH;
+        estimatedScenes = Math.max(2, Math.round(estSec / TARGET_SEC_PER_SCENE));
+    }
+    else {
+        const dur = body.duration ?? 45;
+        estimatedScenes = Math.max(2, Math.round(dur / TARGET_SEC_PER_SCENE));
+    }
+    const imageUnits = tplType === "image" ? estimatedScenes * IMAGE_UNITS : 0;
+    return PLAN_UNITS + TTS_UNITS + ASR_UNITS + imageUnits;
 }
 // ── Helpers ─────────────────────────────────────────────────────
-async function resolveText(input) {
+function looksLikeLocalHtmlPath(value) {
+    if (/^[.~]|^\//.test(value))
+        return true;
+    if (value.includes("\\"))
+        return true;
+    if (value.endsWith(".html") && fsSync.existsSync(value))
+        return true;
+    return false;
+}
+/** `@file` prefix → load file contents; raw text → return as-is. */
+async function resolveTextOrFile(input) {
     if (input.startsWith("@")) {
         const file = input.slice(1);
         return (await fs.readFile(file, "utf-8")).trim();
@@ -59,14 +88,6 @@ async function saveLastCreate(body) {
     await fs.writeFile(LAST_CREATE_PATH, JSON.stringify(body, null, 2) + "\n", "utf-8");
 }
 // ── Filename derivation ─────────────────────────────────────────
-//
-// Cascade (highest → lowest):
-//   1. result.title              — server's actual video title (LLM or explicit)
-//   2. body.title                — user-supplied --title (pre-task fallback)
-//   3. raw topic (mode=generate, length ≤ 60, no @-prefix)
-//   4. @file stem                — when text was loaded from @./script.txt
-//   5. "reelforge" literal
-// Always suffixed with "-<task_id[:8]>" to avoid collisions.
 const FILENAME_MAX_CHARS = 40;
 function sanitizeFilename(name) {
     const cleaned = name
@@ -86,14 +107,8 @@ function computeDefaultFilename(args) {
     if (args.resultTitle && args.resultTitle.trim()) {
         base = sanitizeFilename(args.resultTitle);
     }
-    else if (args.bodyTitle && args.bodyTitle.trim()) {
-        base = sanitizeFilename(args.bodyTitle);
-    }
-    else if (args.mode === "generate" &&
-        args.rawTextInput &&
-        !args.rawTextInput.startsWith("@") &&
-        Array.from(args.rawTextInput).length <= 60) {
-        base = sanitizeFilename(args.rawTextInput);
+    else if (args.topic && Array.from(args.topic).length <= 60) {
+        base = sanitizeFilename(args.topic);
     }
     else if (args.fileStemFromAt) {
         base = sanitizeFilename(args.fileStemFromAt);
@@ -118,57 +133,54 @@ async function validateOutputPath(out) {
 /** Camel-case CLI options → snake_case body, only including provided fields */
 function optsToBody(opts) {
     const out = {};
-    if (opts.text !== undefined)
-        out.text = opts.text;
-    if (opts.mode !== undefined)
-        out.mode = opts.mode;
-    if (opts.title !== undefined)
-        out.title = opts.title;
-    if (opts.nScenes !== undefined)
-        out.n_scenes = opts.nScenes;
-    if (opts.splitMode !== undefined)
-        out.split_mode = opts.splitMode;
-    if (opts.ttsInferenceMode !== undefined)
-        out.tts_inference_mode = opts.ttsInferenceMode;
-    if (opts.ttsVoice !== undefined)
-        out.tts_voice = opts.ttsVoice;
-    if (opts.voiceId !== undefined)
-        out.voice_id = opts.voiceId;
-    if (opts.ttsSpeed !== undefined)
-        out.tts_speed = opts.ttsSpeed;
+    if (opts.topic !== undefined)
+        out.topic = opts.topic;
+    if (opts.script !== undefined)
+        out.script = opts.script;
+    if (opts.duration !== undefined)
+        out.duration = opts.duration;
+    if (opts.pace !== undefined)
+        out.pace = opts.pace;
+    if (opts.llmModel !== undefined)
+        out.llm_model = opts.llmModel;
+    if (opts.ttsModel !== undefined)
+        out.tts_model = opts.ttsModel;
+    if (opts.asrModel !== undefined)
+        out.asr_model = opts.asrModel;
     if (opts.imageModel !== undefined)
         out.image_model = opts.imageModel;
-    if (opts.frameTemplate !== undefined)
-        out.frame_template = opts.frameTemplate;
     if (opts.promptPrefix !== undefined)
         out.prompt_prefix = opts.promptPrefix;
-    if (opts.bgm !== undefined)
-        out.bgm_path = opts.bgm;
-    if (opts.bgmVolume !== undefined)
-        out.bgm_volume = opts.bgmVolume;
-    if (opts.bgmMode !== undefined)
-        out.bgm_mode = opts.bgmMode;
-    if (opts.minNarrationWords !== undefined)
-        out.min_narration_words = opts.minNarrationWords;
-    if (opts.maxNarrationWords !== undefined)
-        out.max_narration_words = opts.maxNarrationWords;
-    if (opts.minImagePromptWords !== undefined)
-        out.min_image_prompt_words = opts.minImagePromptWords;
-    if (opts.maxImagePromptWords !== undefined)
-        out.max_image_prompt_words = opts.maxImagePromptWords;
+    if (opts.voiceId !== undefined)
+        out.voice_id = opts.voiceId;
+    if (opts.ttsSpeed !== undefined)
+        out.tts_speed = opts.ttsSpeed;
     if (opts.videoFps !== undefined)
         out.video_fps = opts.videoFps;
+    if (opts.frameTemplate !== undefined) {
+        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_inline = fsSync.readFileSync(abs, "utf-8");
+        }
+        else {
+            out.frame_template = opts.frameTemplate;
+        }
+    }
+    if (opts.frameTemplateSize !== undefined)
+        out.frame_template_size = opts.frameTemplateSize;
+    if (opts.frameTemplateType !== undefined)
+        out.frame_template_type = opts.frameTemplateType;
     if (opts.templateParams !== undefined)
         out.template_params = opts.templateParams;
+    if (opts.subtitleMinChars !== undefined)
+        out.subtitle_min_chars = opts.subtitleMinChars;
+    if (opts.subtitleHardMax !== undefined)
+        out.subtitle_hard_max = opts.subtitleHardMax;
     return out;
 }
-const DEFAULTS = {
-    mode: "generate",
-    n_scenes: 5,
-    frame_template: "1080x1920/image_default.html",
-    tts_voice: "zh-CN-YunjianNeural",
-    tts_speed: 1.2,
-};
 const STYLE_PRESETS = {
     matchstick: {
         prefix: "Minimalist black-and-white matchstick figure style illustration, clean lines, simple sketch style",
@@ -256,7 +268,6 @@ const STYLE_PRESETS = {
         scene: "奢华品牌 / 复古优雅",
     },
 };
-// CJK chars take 2 display columns in monospace terminals; pad accordingly.
 function displayWidth(s) {
     let w = 0;
     for (const c of s)
@@ -282,34 +293,32 @@ function formatStylePresetsList() {
 export function registerCreate(program) {
     program
         .command("create [topic]")
-        .description("One-click: topic → fully-generated MP4. 23 tunable params + recipe files.")
+        .description("One-click: topic (or your own script) → fully-generated MP4. Audio-first pipeline.")
         .helpOption("-h, --help", "show help")
-        // --- Content ---
-        .option("-t, --text <text>", "topic (mode=generate) or fixed script (mode=fixed). Prefix with @ to read from a file (e.g. @script.txt).")
-        .option("--mode <mode>", "generate | fixed (default: generate)")
-        .option("--title <text>", "explicit video title (default: LLM-generated from topic)")
-        .option("-n, --n-scenes <N>", "number of scenes", (v) => parseInt(v, 10))
-        .option("--split-mode <mode>", "paragraph | line | sentence (mode=fixed only)")
-        .option("--min-narration-words <N>", "narration min words per scene", (v) => parseInt(v, 10))
-        .option("--max-narration-words <N>", "narration max words per scene", (v) => parseInt(v, 10))
-        .option("--min-image-prompt-words <N>", "image prompt min words", (v) => parseInt(v, 10))
-        .option("--max-image-prompt-words <N>", "image prompt max words", (v) => parseInt(v, 10))
+        // --- 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("-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 ---
-        .option("--frame-template <key>", "HTML frame template, e.g. 1080x1920/image_default.html")
+        .option("--frame-template <keyOrPath>", "HTML frame template: preset key (e.g. 1080x1920/image_default.html) OR path to a local .html (auto-sent inline)")
+        .option("--frame-template-size <wxh>", "size for inline HTML when the file lacks <meta template:width|height>, e.g. 1080x1920")
+        .option("--frame-template-type <type>", "inline template type: image (default) | static | asset. Controls whether AI image generation runs per scene.")
         .option("--image-model <id>", "RelayX image model (rx-image-z | rx-image-flux | rx-image-qwen)")
         .option("--prompt-prefix <text>", "raw style prefix prepended to every image prompt (overrides --style)")
-        .option("--style <preset>", "image style preset — shortcut for --prompt-prefix; see 'Style presets' below for the full list")
+        .option("--style <preset>", "image style preset — shortcut for --prompt-prefix; see 'Style presets' below")
         // --- Audio (TTS) ---
-        .option("--tts-voice <id>", "TTS voice id; for edge use e.g. zh-CN-YunjianNeural / en-US-AriaNeural; for relayx use vox voice ids (default: 专业解说)")
-        .option("--tts-speed <n>", "speech speed 0.5..2", parseFloat)
-        .option("--tts-inference-mode <mode>", "edge (default, local Microsoft Edge TTS) | relayx (vox/index-tts-2 via RelayX)")
-        .option("--voice-id <id>", "alias of --tts-voice (legacy compat)")
-        // --- Audio (BGM) ---
-        .option("--bgm <path>", "background music file path (server-side relative to bgm/)")
-        .option("--bgm-volume <n>", "BGM volume 0..1", parseFloat)
-        .option("--bgm-mode <mode>", "loop | once")
+        .option("--voice-id <id>", "RelayX TTS voice id (default 专业解说); see `rf tts voices`")
+        .option("--tts-speed <n>", "speech speed 0.5..2 (default 1.0)", parseFloat)
+        // --- Service overrides ---
+        .option("--llm-model <id>", "override the LLM model used for scene-plan")
+        .option("--tts-model <id>", "override the TTS model (default vox/index-tts-2)")
+        .option("--asr-model <id>", "override the ASR model (default alibaba/paraformer-v2)")
+        // --- Subtitle splitter knobs (advanced) ---
+        .option("--subtitle-min-chars <N>", "subtitle line min chars (default 10)", (v) => parseInt(v, 10))
+        .option("--subtitle-hard-max <N>", "subtitle line absolute max chars (default 24)", (v) => parseInt(v, 10))
         // --- Output / extra ---
-        .option("--video-fps <n>", "output video fps", (v) => parseInt(v, 10))
+        .option("--video-fps <n>", "output video fps (default 30)", (v) => parseInt(v, 10))
         .option("--template-params <json>", "extra template placeholders as JSON string", (v) => {
         try {
             return JSON.parse(v);
@@ -323,104 +332,68 @@ export function registerCreate(program) {
         .option("--redo", "replay last successful create from ~/.reelforge/last-create.json")
         .option("--dry-run", "print the final request body + estimated units; do NOT submit")
         .option("--no-wait", "submit and return task_id immediately (do not poll)")
-        .option("-o, --output <file>", "save the final video to this exact path (must include filename, e.g. ./out/space.mp4). Default: auto-named file in current directory.")
-        .option("--no-download", "do not save the video locally — just print the JSON result with video_url")
+        .option("-o, --output <file>", "save the final video to this exact path (must include filename, e.g. ./out/space.mp4).")
+        .option("--no-download", "do not save the video locally — just print JSON with video_url")
         .option("--poll-ms <ms>", "poll interval while waiting", (v) => parseInt(v, 10), 1500)
         .option("--timeout-ms <ms>", "max wait time before aborting (default unlimited)", (v) => parseInt(v, 10))
         .addHelpText("after", [
         "",
-        "Defaults match the /create web page:",
-        "  mode=generate · n-scenes=5 · frame-template=1080x1920/image_default.html",
-        "  tts-voice=zh-CN-YunjianNeural · tts-speed=1.2",
+        "Two content modes (one is required):",
+        "  generate    AI writes the script.   --topic / -t <text>  + optional --duration -d",
+        "  fixed       You supply the script.  --script <text-or-@file>",
+        "",
+        "Pace (visual rhythm hint to the LLM):",
+        "  slow    fewer scenes, glued to semantic boundaries",
+        "  normal  balance semantic edges with visual variety (default)",
+        "  fast    split long semantic chunks into multiple shots for variety",
         "",
-        "Param groups:",
-        "  Content : --mode --title -n --split-mode --min/max-narration-words --min/max-image-prompt-words",
-        "  Visual  : --frame-template --image-model --style --prompt-prefix",
-        "  TTS     : --tts-voice --tts-speed --tts-inference-mode --voice-id",
-        "  BGM     : --bgm --bgm-volume --bgm-mode",
-        "  Output  : --video-fps --template-params -o --no-download --no-wait --poll-ms --timeout-ms",
-        "  Workflow: --recipe --redo --dry-run",
+        "Defaults:",
+        "  duration=45s · pace=normal · frame-template=1080x1920/image_default.html · tts-speed=1.0",
         "",
         "Style presets (--style <preset>) — quick shortcut for --prompt-prefix:",
         formatStylePresetsList(),
         "  · Pass --prompt-prefix to override (raw string always wins).",
-        "  · Omit both to use the server's configured default style.",
+        "  · Omit both to use the server's configured default style (if any).",
         "",
         "Output behavior:",
-        "  No flag     → saves to ./<title>-<task_id>.mp4 in current directory, prints the path",
-        "  -o <path>   → saves to that exact path (must include filename, not just a directory)",
+        "  No flag       → saves to ./<title>-<task_id>.mp4 in current directory, prints the path",
+        "  -o <path>     → saves to that exact path (must include filename)",
         "  --no-download → skips local save, just prints JSON result with video_url",
         "  (when stdout is piped, --no-download is implied automatically)",
         "",
-        "Explore available resources (separate commands):",
-        "  reelforge templates list                  # all HTML templates",
-        "  reelforge tts voices --locale zh          # Edge TTS voice ids",
-        "  reelforge bgm list                        # built-in BGM files",
-        "",
-        "Examples (`rf` is a short alias for `reelforge`):",
-        "  # Minimum — saves to ./<title>-<short_id>.mp4 in cwd",
+        "Examples (`rf` is the short alias):",
+        "  # Minimum — AI writes a 45s script",
         '  rf create "为什么我们还没找到外星文明？"',
         "",
-        "  # Pick the exact output path",
-        '  rf create "..." -o ./videos/space.mp4',
-        "",
-        "  # Long script from a file, fixed mode (no LLM scriptwriting)",
-        "  rf create @./script.txt --mode fixed --split-mode paragraph",
+        "  # 60-second video with slow visual pace",
+        '  rf create "..." -d 60 -p slow',
         "",
-        "  # Landscape (1920x1080)",
-        '  rf create "..." --frame-template 1920x1080/image_default.html',
+        "  # Your own script, you decide the wording",
+        "  rf create --script @./script.txt",
+        '  rf create --script "整段文案文本..."',
         "",
-        "  # Add BGM",
-        '  rf create "..." --bgm bgm/Echoes.mp3 --bgm-volume 0.3 --bgm-mode loop',
-        "",
-        "  # Change voice + speed",
-        '  rf create "..." --tts-voice zh-CN-XiaoxiaoNeural --tts-speed 1.0',
+        "  # Custom HTML template (auto-detected when --frame-template is a local path)",
+        "  rf create '...' --frame-template ./my-brand.html",
         "",
         "  # Pick a built-in style preset",
         '  rf create "..." --style cinematic',
-        '  rf create "美食教程" --style photorealistic',
-        "",
-        "  # Free-form style — write your own prefix from scratch",
-        '  rf create "..." --prompt-prefix "Studio Ghibli, pastel, dreamy"',
         "",
-        "  # Full recipe in one file",
+        "  # Recipe + replay last",
         "  rf create --recipe ./space.recipe.json",
-        "",
-        "  # Override a field on top of a recipe",
-        '  rf create --recipe ./space.recipe.json --text "新主题" -n 8',
-        "",
-        "  # Replay last successful create",
-        "  rf create --redo",
-        "",
-        "  # Replay last but tweak one knob",
-        "  rf create --redo --tts-speed 1.0",
+        "  rf create --redo                       # replay last successful create",
+        "  rf create --redo -p fast               # replay with one knob tweaked",
         "",
         "  # See exactly what would be sent (no submission)",
-        '  rf create "..." -n 7 --bgm bgm/Echoes.mp3 --dry-run',
+        '  rf create "..." -d 60 --dry-run',
         "",
-        "  # Pipe-friendly: skip local download, take video_url for downstream",
+        "  # Pipe-friendly",
         '  rf create "..." --no-download --json | jq -r .video_url',
-        "",
-        "Recipe file format (every field is optional; all keys match the REST API body):",
-        "  {",
-        '    "text": "为什么我们还没找到外星文明？",',
-        '    "n_scenes": 7,',
-        '    "frame_template": "1080x1920/image_default.html",',
-        '    "image_model": "rx-image-flux",',
-        '    "prompt_prefix": "Minimalist matchstick figure style",',
-        '    "tts_voice": "zh-CN-YunjianNeural",',
-        '    "tts_speed": 1.2,',
-        '    "bgm_path": "bgm/Echoes.mp3",',
-        '    "bgm_volume": 0.2',
-        "  }",
     ].join("\n"))
         .action(async (topicArg, opts) => {
-        // Validate -o early so we fail before submitting a paid task
         if (opts.output) {
             await validateOutputPath(opts.output);
         }
-        // Expand --style preset to --prompt-prefix unless an explicit
-        // --prompt-prefix is also given (the raw string always wins).
+        // Expand --style preset to --prompt-prefix unless --prompt-prefix is given.
         if (opts.style) {
             const preset = STYLE_PRESETS[opts.style];
             if (!preset) {
@@ -430,6 +403,9 @@ export function registerCreate(program) {
                 opts.promptPrefix = preset.prefix;
             }
         }
+        if (opts.pace && !["slow", "normal", "fast"].includes(opts.pace)) {
+            throw new Error(`--pace must be one of slow|normal|fast (got: ${opts.pace})`);
+        }
         // 1. Layer defaults: --redo → --recipe → CLI opts → positional topic
         let body = {};
         if (opts.redo) {
@@ -445,45 +421,49 @@ export function registerCreate(program) {
             body = { ...body, ...recipe };
             info(`Loaded recipe from ${opts.recipe}`);
         }
-        // CLI options layer
         const fromOpts = optsToBody(opts);
         body = { ...body, ...fromOpts };
-        // Capture the raw text input (with potential @-prefix) for filename derivation.
-        // After `resolveText` we lose the @path → file stem mapping.
-        const rawTextInput = topicArg ?? (typeof body.text === "string" ? body.text : undefined);
-        const fileStemFromAt = rawTextInput?.startsWith("@")
-            ? path.parse(rawTextInput.slice(1)).name
-            : undefined;
-        // Positional topic wins for `text` (with @file support)
+        // Positional arg always wins for `topic`.
+        // Resolve @file prefix on whichever of topic/script is set.
+        const rawTopicInput = topicArg ?? (typeof body.topic === "string" ? body.topic : undefined);
+        const fileStemFromAt = rawTopicInput?.startsWith("@") ? path.parse(rawTopicInput.slice(1)).name :
+            body.script?.startsWith("@") ? path.parse(body.script.slice(1)).name :
+                undefined;
         if (topicArg) {
-            body.text = await resolveText(topicArg);
+            body.topic = await resolveTextOrFile(topicArg);
+        }
+        else if (typeof body.topic === "string") {
+            body.topic = await resolveTextOrFile(body.topic);
+        }
+        if (typeof body.script === "string") {
+            body.script = await resolveTextOrFile(body.script);
+        }
+        // Validate content mode
+        const hasTopic = typeof body.topic === "string" && body.topic.trim().length > 0;
+        const hasScript = typeof body.script === "string" && body.script.trim().length > 0;
+        if (!hasTopic && !hasScript) {
+            throw new Error("either --topic (or positional arg) or --script is required.");
         }
-        else if (typeof body.text === "string") {
-            body.text = await resolveText(body.text);
+        if (hasTopic && hasScript) {
+            throw new Error("--topic and --script are mutually exclusive (pick one mode).");
         }
-        if (!body.text) {
-            throw new Error("text is required — pass it as the positional arg, or via --text / --recipe / --redo.");
+        // 3. Final body — drop empty / null fields
+        const finalBody = { ...body };
+        if (finalBody.frame_template_inline && finalBody.frame_template) {
+            delete finalBody.frame_template;
         }
-        // 2. Apply defaults for fields still unset
-        const finalBody = {
-            ...DEFAULTS,
-            ...body,
-            text: body.text,
-        };
-        // 3. Estimate cost
+        // 4. Estimate cost
         const estimate = estimateUnits(finalBody);
-        // 4. Dry-run: print & exit
         if (opts.dryRun) {
             info("--- DRY RUN ---");
             info("Final request body:");
             print(finalBody);
-            info(`Estimated cost: ${estimate} units`);
+            info(`Estimated cost: ≈ ${estimate} units`);
             info("(use without --dry-run to actually submit)");
             return;
         }
         info(`Submitting create task (≈ ${estimate} units)...`);
         const submitted = await post("/api/v1/pipelines/standard", finalBody);
-        // 5. Save as last (post-submit, before wait — so even cancelled tasks can be replayed)
         await saveLastCreate(finalBody).catch((e) => {
             warn(`Could not save last-create.json: ${e.message}`);
         });
@@ -500,11 +480,6 @@ export function registerCreate(program) {
             throw new Error(t.error || `Task ended with status ${t.status}`);
         }
         const result = t.result;
-        // Decide where (or whether) to save locally.
-        //   -o            → that exact path
-        //   --no-download → skip
-        //   stdout piped  → skip (clig.dev: don't dump binary-touching side effects into a script)
-        //   otherwise     → auto-named in cwd
         if (result?.video_url) {
             const stdoutIsPipe = !process.stdout.isTTY;
             const skipDownload = !!opts.noDownload || (stdoutIsPipe && !opts.output);
@@ -513,11 +488,10 @@ export function registerCreate(program) {
                 savedPath = opts.output;
             }
             else if (!skipDownload) {
+                const topicForFilename = hasTopic && finalBody.topic ? finalBody.topic : undefined;
                 savedPath = computeDefaultFilename({
                     resultTitle: result.title,
-                    bodyTitle: finalBody.title,
-                    mode: finalBody.mode,
-                    rawTextInput,
+                    topic: topicForFilename,
                     fileStemFromAt,
                     taskId: t.id,
                     ext: "mp4",

package/dist/commands/pipelines.js

@@ -36,54 +36,74 @@ export function registerPipelines(program) {
     const pl = program
         .command("pipelines")
         .alias("pipeline")
-        .description("End-to-end video pipelines (standard)")
+        .description("End-to-end video pipelines (standard, audio-first)")
         .helpOption("-h, --help", "show help");
     // ---------- standard ----------
     commonOptions(pl
         .command("standard")
-        .description("Topic / script → narration → frames → final MP4")
+        .description("Audio-first pipeline: topic|script → master TTS → ASR → scene/subtitle layers → final MP4")
         .helpOption("-h, --help", "show help")
-        .requiredOption("-t, --text <text>", "topic OR fixed script (use @file)")
-        .option("--mode <mode>", "generate | fixed", "generate")
-        .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 <keyOrPath>", "preset key (e.g. 1080x1920/static_default.html) OR path to a local .html file", "1080x1920/static_default.html")
+        .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("-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("--frame-template <keyOrPath>", "preset key (e.g. 1080x1920/image_default.html) OR path to a local .html file")
         .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")
-        .option("--tts-speed <n>", "speech speed (0.5..2)", parseFloat, 1.2)
-        .option("--bgm <path>", "BGM file path")
-        .option("--bgm-volume <n>", "BGM volume", parseFloat, 0.2)
+        .option("--frame-template-type <type>", "inline type: image (default) | static | asset")
+        .option("--image-model <id>", "RelayX image model (rx-image-z | rx-image-flux | rx-image-qwen)")
+        .option("--prompt-prefix <text>", "style prefix prepended to every image prompt")
+        .option("--voice-id <id>", "RelayX TTS voice id (default 专业解说); see `rf tts voices`")
+        .option("--tts-speed <n>", "speech speed (0.5..2; default 1.0)", parseFloat)
+        .option("--video-fps <n>", "output video fps (default 30)", (v) => parseInt(v, 10))
+        .option("--subtitle-min-chars <N>", "subtitle line min chars (default 10)", (v) => parseInt(v, 10))
+        .option("--subtitle-hard-max <N>", "subtitle line absolute max chars (default 24)", (v) => parseInt(v, 10))
         .addHelpText("after", [
         "",
-        "Examples:",
-        "  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'",
+        "Two content modes (exactly one required):",
+        "  generate    AI writes the script.   --topic / -t <text>  + optional --duration -d",
+        "  fixed       You supply the script.  --script <text-or-@file>",
+        "",
+        "Pace (LLM visual rhythm hint):  slow | normal | fast",
         "",
-        "  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)",
+        "Examples:",
+        "  rf pipelines standard -t 'why we explore space' -d 60 -o space.mp4",
+        "  rf pipelines standard --script @script.txt -p slow -o out.mp4",
+        "  rf pipelines standard -t '宠物' --frame-template ./my-brand.html -o final.mp4",
     ].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);
+        const hasTopic = typeof opts.topic === "string" && opts.topic.length > 0;
+        const hasScript = typeof opts.script === "string" && opts.script.length > 0;
+        if (!hasTopic && !hasScript) {
+            throw new Error("either --topic / -t or --script is required");
+        }
+        if (hasTopic && hasScript) {
+            throw new Error("--topic and --script are mutually exclusive");
+        }
+        if (opts.pace && !["slow", "normal", "fast"].includes(opts.pace)) {
+            throw new Error(`--pace must be one of slow|normal|fast (got: ${opts.pace})`);
+        }
+        let topic = opts.topic;
+        let script = opts.script;
+        if (topic?.startsWith("@"))
+            topic = await fs.readFile(topic.slice(1), "utf-8");
+        if (script?.startsWith("@"))
+            script = await fs.readFile(script.slice(1), "utf-8");
+        const tpl = opts.frameTemplate
+            ? 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,
+            topic,
+            script,
+            duration: opts.duration,
+            pace: opts.pace,
             ...tpl,
+            frame_template_type: opts.frameTemplateType,
             image_model: opts.imageModel,
             prompt_prefix: opts.promptPrefix,
-            tts_voice: opts.ttsVoice,
+            voice_id: opts.voiceId,
             tts_speed: opts.ttsSpeed,
-            bgm_path: opts.bgm,
-            bgm_volume: opts.bgmVolume,
+            video_fps: opts.videoFps,
+            subtitle_min_chars: opts.subtitleMinChars,
+            subtitle_hard_max: opts.subtitleHardMax,
         }, { wait: opts.wait, output: opts.output, pollMs: opts.pollMs, timeoutMs: opts.timeoutMs });
     });
 }

package/dist/commands/subtitles.js

@@ -0,0 +1,40 @@
+import fs from "node:fs/promises";
+import { post } from "../client.js";
+import { print } from "../utils/output.js";
+export function registerSubtitles(program) {
+    const sub = program
+        .command("subtitles")
+        .alias("subtitle")
+        .description("Subtitle atomics — deterministic line splitter (no LLM, no billing)")
+        .helpOption("-h, --help", "show help");
+    sub
+        .command("split")
+        .description("Split a chunk of text into subtitle-sized lines using tiered punctuation priority")
+        .helpOption("-h, --help", "show help")
+        .requiredOption("-t, --text <text>", "text to split. Use @file to read from disk.")
+        .option("--min <N>", "minimum line length in chars (default 10)", (v) => parseInt(v, 10))
+        .option("--hard-max <N>", "absolute maximum line length in chars (default 24)", (v) => parseInt(v, 10))
+        .addHelpText("after", [
+        "",
+        "Rule:",
+        "  Within [min, hard-max], pick the highest-tier punctuation; same tier → latest position.",
+        "  Tier 1 (。！？) > Tier 2 (；：) > Tier 3 (，、)",
+        "  No punctuation in window → force-cut at hard-max.",
+        "",
+        "Examples:",
+        "  rf subtitles split -t '雨水缓缓滑落在玻璃窗上，像是无声的泪珠。'",
+        "  rf subtitles split -t @./narration.txt --min 8 --hard-max 20",
+    ].join("\n"))
+        .action(async (opts) => {
+        let text = opts.text;
+        if (text.startsWith("@"))
+            text = (await fs.readFile(text.slice(1), "utf-8")).trim();
+        const body = { text };
+        if (opts.min !== undefined)
+            body.min_chars = opts.min;
+        if (opts.hardMax !== undefined)
+            body.hard_max = opts.hardMax;
+        const r = await post("/api/v1/subtitles/split", body);
+        print({ count: r.count, lines: r.lines });
+    });
+}

package/dist/index.js

@@ -19,6 +19,8 @@ import { registerModels } from "./commands/models.js";
 import { registerTts } from "./commands/tts.js";
 import { registerImages } from "./commands/images.js";
 import { registerContent } from "./commands/content.js";
+import { registerAudio } from "./commands/audio.js";
+import { registerSubtitles } from "./commands/subtitles.js";
 import { registerTemplates } from "./commands/templates.js";
 import { registerFrames } from "./commands/frames.js";
 import { registerCompositions } from "./commands/compositions.js";
@@ -70,7 +72,7 @@ program.addHelpText("afterAll", [
     "  rf llm chat --prompt 'explain antifragile in 3 sentences'",
     "  rf tts edge --text 'hello world' --voice en-US-AriaNeural -o out.mp3",
     "  rf images generate --prompt 'a cat' --model rx-image-flux -o cat.png",
-    "  rf pipelines standard --text 'why we explore space' --tts-voice zh-CN-YunjianNeural",
+    "  rf pipelines standard -t 'why we explore space' -d 60",
     "  rf tasks list --status running",
     "  rf config get",
 ].join("\n"));
@@ -81,6 +83,8 @@ registerModels(program);
 registerTts(program);
 registerImages(program);
 registerContent(program);
+registerAudio(program);
+registerSubtitles(program);
 registerTemplates(program);
 registerFrames(program);
 registerCompositions(program);

package/package.json

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