reelforge 1.21.0 → 1.23.0

package/dist/commands/dub.js

@@ -0,0 +1,154 @@
+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";
+import { formatUsd, humanDuration, info, isJson, print, success } from "../utils/output.js";
+const VIDEO_EXT_TO_MIME = {
+    ".mp4": "video/mp4",
+    ".mov": "video/quicktime",
+    ".webm": "video/webm",
+    ".mkv": "video/x-matroska",
+    ".m4v": "video/mp4",
+};
+const MAX_BYTES = 55 * 1024 * 1024;
+function fmtSize(bytes) {
+    if (!bytes)
+        return "0";
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / 1024 / 1024).toFixed(1)} MB`;
+}
+export function registerDub(program) {
+    program
+        .command("dub <video>")
+        .description("⚠️ EXPERIMENTAL · 一个原始视频 → 自动反推内容 + 写解说 + 熊小二配音 + 字幕,输出成片")
+        .helpOption("-h, --help", "show help")
+        .option("-o, --output <file>", "输出 MP4 路径 (默认: <视频名>-dub.mp4, 放在当前目录)")
+        .option("--voice <id>", "配音音色 id (index-tts-2 音色名, 默认 熊小二)", "熊小二")
+        .option("--tts-model <id>", "TTS 模型 (默认 vox/index-tts-2)", "vox/index-tts-2")
+        .option("--game-volume <n>", "原视频自带声音的音量 0..1 (默认 0.6; 设 0 = 完全静音原声, 只留配音)", (v) => parseFloat(v), 0.6)
+        .option("--no-subtitles", "不烧录字幕 (默认烧录)")
+        .option("--subtitle-style <style>", "字幕样式: plate | stroke | cinema (默认 plate)", "plate")
+        .option("--theme <id>", "可选主题 id (影响字幕底板 / 配色风格)")
+        .option("--vision-model <id>", "反推用的视觉模型 (默认 qwen/qwen3-vl-flash)")
+        .option("--script-model <id>", "写解说脚本用的 LLM (默认服务端配置模型)")
+        .option("--preview-only", "只生成 preview, 不渲染最终 MP4 (更快更省, 用于试效果)")
+        .option("--poll-ms <ms>", "轮询间隔", (v) => parseInt(v, 10), 1500)
+        .option("--timeout-ms <ms>", "最长等待时间", (v) => parseInt(v, 10))
+        .addHelpText("after", [
+        "",
+        "它做了什么 (全部在服务端完成):",
+        "  1. 反推视频内容 — 详细、带时间段的分镜 + 屏幕文字",
+        "  2. 根据视频时长写一段贴合画面的解说脚本 (卡住时长, 画面演到哪讲到哪)",
+        "  3. 用熊小二音色合成配音 (可 --voice 指定其它音色)",
+        "  4. 把配音叠到原视频上, 原视频自带声音压到 60% 垫底 (可 --game-volume 调)",
+        "  5. 烧录字幕 (复用 compose 的字幕样式 + 切分逻辑; --no-subtitles 关闭)",
+        "",
+        "认证:",
+        "  需要 API key — `rf login <key>` 或 $REELFORGE_API_KEY 或 --api-key <key>。",
+        "  没有 key 服务端会拒绝 (401)。",
+        "",
+        "支持的输入扩展名: .mp4 .mov .webm .mkv .m4v (单文件 ≤ 55MB)",
+        "",
+        "可用音色: `rf tts voices` (熊小二 / 激情熊大 / 专业解说 等 149 个)",
+        "",
+        "示例:",
+        "  # 最简单: 一个视频进, 配音+字幕成片出 (默认熊小二, 原声 60%)",
+        "  rf dub ./clip.mp4",
+        "",
+        "  # 指定输出路径 + 换个音色 + 原声调小到 30%",
+        "  rf dub ./clip.mp4 -o ./out.mp4 --voice 激情熊大 --game-volume 0.3",
+        "",
+        "  # 不要字幕",
+        "  rf dub ./clip.mp4 --no-subtitles",
+        "",
+        "  # 批量 (PowerShell): 对一个目录里所有 mp4 串行处理",
+        "  Get-ChildItem *.mp4 | ForEach-Object { rf dub $_.FullName }",
+        "",
+        "  # 先看效果再决定 (preview, 不渲染 MP4)",
+        "  rf dub ./clip.mp4 --preview-only",
+    ].join("\n"))
+        .action(async (videoArg, opts) => {
+        const abs = path.resolve(videoArg);
+        if (!fsSync.existsSync(abs))
+            throw new Error(`video not found: ${abs}`);
+        const ext = path.extname(abs).toLowerCase();
+        const mime = VIDEO_EXT_TO_MIME[ext];
+        if (!mime) {
+            throw new Error(`unsupported video extension "${ext}" (supported: ${Object.keys(VIDEO_EXT_TO_MIME).join(" / ")})`);
+        }
+        const gameVolume = opts.gameVolume ?? 0.6;
+        if (!Number.isFinite(gameVolume) || gameVolume < 0 || gameVolume > 1) {
+            throw new Error(`--game-volume must be between 0 and 1 (got ${opts.gameVolume})`);
+        }
+        const subtitleStyle = (opts.subtitleStyle || "plate").toLowerCase();
+        if (!["plate", "stroke", "cinema"].includes(subtitleStyle)) {
+            throw new Error(`--subtitle-style must be plate | stroke | cinema (got ${opts.subtitleStyle})`);
+        }
+        const buf = await fs.readFile(abs);
+        if (buf.byteLength > MAX_BYTES) {
+            throw new Error(`video is ${fmtSize(buf.byteLength)} — exceeds the ${fmtSize(MAX_BYTES)} upload cap. ` +
+                `Compress / trim it first (e.g. ffmpeg -crf 28).`);
+        }
+        info(`Uploading ${path.basename(abs)} (${fmtSize(buf.byteLength)})...`);
+        const body = {
+            video: `data:${mime};base64,${buf.toString("base64")}`,
+            voice: opts.voice || "熊小二",
+            tts_model: opts.ttsModel || "vox/index-tts-2",
+            game_audio_volume: gameVolume,
+            subtitles: opts.subtitles !== false,
+            subtitle_style: subtitleStyle,
+        };
+        if (opts.theme)
+            body.theme = opts.theme;
+        if (opts.visionModel)
+            body.vision_model = opts.visionModel;
+        if (opts.scriptModel)
+            body.script_model = opts.scriptModel;
+        if (opts.previewOnly)
+            body.preview_only = true;
+        const submitted = await post("/api/v1/dub", body);
+        info(`Submitted task: ${submitted.task_id} — 反推 + 写脚本 + TTS + 渲染, 请稍候...`);
+        const t = await waitForTask(submitted.task_id, { pollMs: opts.pollMs, timeoutMs: opts.timeoutMs });
+        if (t.status !== "completed") {
+            throw new Error(t.error || `Task ended with status ${t.status}`);
+        }
+        const result = t.result;
+        if (result?.script?.length) {
+            info(`配音脚本 (${result.voice || opts.voice}):`);
+            for (const line of result.script)
+                info(`   ${line}`);
+        }
+        if (result?.render_pending) {
+            info(`MP4 render skipped (--preview-only). Run \`rf render ${t.id}\` to finalize.`);
+        }
+        else if (result?.video_url) {
+            const stdoutIsPipe = !process.stdout.isTTY;
+            const skipDownload = stdoutIsPipe && !opts.output;
+            let savedPath;
+            if (opts.output) {
+                savedPath = path.resolve(opts.output);
+            }
+            else if (!skipDownload) {
+                const stem = path.parse(abs).name;
+                savedPath = path.resolve(`${stem}-dub.mp4`);
+            }
+            if (savedPath) {
+                await downloadTo(result.video_url, savedPath);
+                success(`Saved → ${savedPath}`);
+            }
+        }
+        if (result?.generation_ms != null) {
+            const playback = result.duration != null ? `, video ${result.duration.toFixed(1)}s` : "";
+            info(`generated in ${humanDuration(result.generation_ms)}${playback}`);
+        }
+        if (result?.price_usd != null)
+            info(`charge: ${formatUsd(result.price_usd)}`);
+        if (isJson())
+            print({ task_id: t.id, status: t.status, ...result });
+    });
+}

package/dist/commands/vlog.js

@@ -9,6 +9,11 @@ const VERTICALS = [
         label: "宠物第一视角搞笑 vlog",
         blurb: "用户拍的猫狗图 / 视频 + 一句话 → 宠物第一人称搞笑竖屏短视频",
     },
+    {
+        id: "general",
+        label: "通用素材→视频(兜底)",
+        blurb: "没有更专门赛道时的通用 SOP:做饭 / 旅行 / 日常 vlog / 开箱等临时场景都走这里",
+    },
 ];
 function loadPlaybook(id) {
     const candidates = [
@@ -38,9 +43,12 @@ function indexText() {
         lines.push(`  ${" ".repeat(8)} ${v.blurb}`);
     }
     lines.push("");
+    lines.push("挑选规则:有贴合的垂类就用垂类;没有 → 用 general 兜底。");
+    lines.push("");
     lines.push("用法:");
-    lines.push("  rf vlog pet            打印「宠物赛道」完整剧本(SOP)");
-    lines.push("  rf vlog pet | less     分页浏览");
+    lines.push("  rf vlog <id>           打印某赛道完整剧本(SOP),如 `rf vlog pet`");
+    lines.push("  rf vlog general        通用 SOP(临时 / 没专门赛道的场景)");
+    lines.push("  rf vlog <id> | less    分页浏览");
     return lines.join("\n");
 }
 export function registerVlog(program) {

package/dist/data/vlog/general.md

@@ -0,0 +1,129 @@
+# rf vlog · 通用素材→视频剧本（general）
+
+> 给**上层 agent**（你，正在帮用户做视频的 Claude Code / Cursor 等）读的工作指南。
+> 这是**兜底剧本**:用户拿一批自己的图/视频想做条短视频,但没有更专门的赛道时,走这里。
+> 有更贴合的垂类(如 `rf vlog pet`)就优先用垂类;没有 → 用本剧本。临时场景(做饭、
+> 旅行、日常 vlog、开箱…)都适用。
+>
+> **角色边界（先记死）**
+> - 引擎只给你两样**你做不到**的能力:`rf assets describe`(给视频「眼睛」,你看不到视频帧)、`rf compose`(渲染 + 配音 + 字幕对齐)。
+> - **写旁白 / 脚本是你的活,不是引擎的。** 本剧本只给你「怎么写」的最佳实践,绝不替你写一个字。
+> - 字段 / 参数的精确用法一律以 `rf compose -h`、`rf cover -h` 为准。
+
+---
+
+## Step 0 · 动手前先确认输入（别让用户从 0 摸索）
+
+| 输入 | 默认 | 要问吗 |
+|---|---|---|
+| 素材目录 | — | 必给(让用户指一个文件夹) |
+| **故事方向 / 想表达啥** | — | **灵魂问 1** |
+| **调性 + 旁白视角** | — | **灵魂问 1 的一部分**:恶搞/温馨/科普/沉浸?旁观叙述 / 第一人称 / 主人 vlog? |
+| **音色** | 不固定 | **灵魂问 2**:按调性挑 2-3 个候选给用户选(查法见下) |
+| 封面 | 自动取一张高光素材 | 用户想要精致封面时,把模板预览图发他挑 |
+| 字幕风格 | stroke(短视频爆款描边) | 默认,不问 |
+| BGM / 分辨率 | 默认 BGM / 1080×1920 | 默认,不问 |
+
+---
+
+## Step 1 · 看素材（必做,这是你「看到」素材的唯一方式）
+
+```bash
+rf assets describe ./素材目录/ -o assets.json
+```
+
+返回每个素材的客观描述(图片 ~30 字 / 视频 ~80 字含动作与氛围)+ 视频时长。
+**这是事实地基。后面写旁白,只能基于这里描述出来的真实动作。**
+
+> ⚠️ 视频 describe 有 body 体积上限(~10MB 就会 400)。源视频偏大时,先用 ffmpeg 压个低清短代理
+> (如 `-vf scale=480:-2,fps=12 -crf 30`,几百 KB)再 describe;代理只用来"看懂内容",不进成片。
+
+## Step 2 · 你来写旁白 + 给用户过故事板
+
+引擎不替你写。按《写作最佳实践》自己写,然后用**人话故事板**(不是 JSON)给用户确认。
+
+## Step 3 · 渲染
+
+```bash
+rf compose spec.json -o ./final.mp4
+```
+
+---
+
+## ★ 写作最佳实践
+
+### 🚫 反虚构铁律（最重要,违反 = 废片）
+**旁白只能解说画面里 `describe` 出来的真实动作。**
+- ✅ 可以编:情绪、内心戏、动机、夸张比喻。
+- ❌ 不准编:画面没发生的物理事件(画面"够不着"就不能写"够到了")。
+- 不确定画面里发生没发生 → 当作没发生,别写。
+
+### 句子写法
+- 写**完整句子、句末带标点**(。！？)。每句 10~30 字。
+- **别为字幕节奏手动拆短**——字幕切分是引擎的活(compose 内部按真实配音时间对齐)。
+- 每条旁白是一个独立句子,放进对应 scene 的 `narration` 数组里。
+
+---
+
+## ★ 素材 & 画幅最佳实践（决定"短视频观感"）
+
+短视频节奏踩过的坑,默认这么做:
+
+- **优先用视频片段,尽量少用静图。** 静图即便加了 Ken Burns,整体节奏也会显得拖沓,不合现代短视频快节奏。能用视频就别用图。
+- **竖拍照片用 full-bleed 铺满**(`fit:"cover"` + `focal` 保主体),别让它缩在中间——铺满才有跟视频齐平的沉浸感。
+- **横屏视频**:要么用 `layout:"blur-bg"`(不裁画面,但竖图会被装在中间显小);要么先用 ffmpeg 把横屏烤成自带模糊垫底的 9:16 片,再整片走 `layout:"full"`——想让图和视频**统一全屏**就用后者。
+- **照片朝向**:手机竖拍照片常带旋转标记,直接喂可能横躺。喂前先摆正、抽帧确认:`ffmpeg -noautorotate -i in.jpg -vf "transpose=1" up.jpg`。
+- 不设 `theme` → 引擎**不会压暗**你的素材(保持原始亮度);只有显式选 theme 才会按主题调色压暗。
+
+---
+
+## 音色怎么选
+
+按调性挑,不固定某一个。查全部音色:
+
+```bash
+rf tts voices --provider relayx --model vox/index-tts-2
+```
+
+按风格筛,例如 `... | grep 解说`。**别让用户从一长串里盲选**——你挑 2-3 个候选报给他,他点一个。
+选定后填进 spec 的 `audio.tts_voice`。
+
+## 封面怎么选
+
+compose 的 `cover.image` 只收**一张图**。两种做法:
+
+- **省事**:挑一张高光素材当封面 → `"cover": { "image": "高光帧.jpg" }`。
+- **套模板**:`rf cover templates`(每个模板带 preview_url)→ **把预览裸链接发给用户看图挑** → 渲染:
+  `rf cover -i 高光帧.jpg -t "标题" --template <模板id> -o cover.png` → 填 `"cover": { "image": "cover.png" }`。
+  (`--subtitle` / `--badge` / `--param` 见 `rf cover -h`。)
+
+---
+
+## compose.v3 spec 模板
+
+```json
+{
+  "experimental": "compose.v3",
+  "output": { "width": 1080, "height": 1920, "fps": 30, "layout": "full" },
+  "audio": { "tts_model": "vox/index-tts-2", "tts_voice": "<选定音色>", "bgm_volume": 0.12 },
+  "subtitle_style": "stroke",
+  "cover": { "image": "封面.jpg" },
+  "scenes": [
+    { "video": "clip1.mp4", "muted": true, "narration": ["句1。", "句2。"] },
+    { "image": "photo1.jpg", "fit": "cover", "focal": "center", "motion": "zoom-in", "narration": ["句1。"] }
+  ]
+}
+```
+
+- spec 里**没有任何秒数**;时间由引擎量真实配音派生。
+- 旁白尽量 ≤ 视频时长,省掉片头黑卡;真比视频长时引擎会自动前置标题卡。
+- `layout` 选择见上面《素材 & 画幅最佳实践》。
+
+---
+
+## 提交前自查
+- [ ] 跑过 `rf assets describe`?
+- [ ] 旁白每一句都对得上画面真实动作?(过一遍反虚构铁律)
+- [ ] 给用户看的是**人话故事板**,不是裸 JSON?
+- [ ] 照片朝向已摆正、竖图 full-bleed?横屏视频处理好画幅?
+- [ ] 没设 theme(素材保持原始亮度)?

package/dist/data/vlog/pet.md

@@ -138,6 +138,11 @@ rf cover -i 高光帧.jpg -t "橘子大战鱼缸" --template <模板id> -o cover
 - spec 里**没有任何秒数**；时间由引擎量真实配音派生。
 - 旁白尽量 ≤ 视频时长，省掉片头黑卡；真比视频长时引擎会自动前置一张标题卡。
 
+### 素材 & 画幅（短视频节奏）
+- **优先视频片段，尽量少用静图**：静图即便加 Ken Burns 也会拖慢节奏，不合短视频快感。
+- 竖拍照片用 `fit:"cover"` 铺满（别缩在中间显小）；横屏视频要么 `layout:"blur-bg"`，要么先烤成 9:16 再走 `layout:"full"` 统一全屏。
+- 完整的通用画幅 / 朝向 / 音色 / 封面最佳实践见 `rf vlog general`。
+
 ### ⚠️ 照片朝向
 手机竖拍照片常带旋转标记，直接喂可能是横躺的。喂前先摆正、抽帧确认方向：
 

package/dist/index.js

@@ -34,6 +34,7 @@ import { registerExtract } from "./commands/extract.js";
 import { registerMedia } from "./commands/media.js";
 import { registerScript } from "./commands/script.js";
 import { registerCompose } from "./commands/compose.js";
+import { registerDub } from "./commands/dub.js";
 import { registerVlog } from "./commands/vlog.js";
 import { error as logError } from "./utils/output.js";
 import { ApiCallError } from "./client.js";
@@ -109,12 +110,14 @@ program.addHelpText("after", [
     "  rf fetch '<抖音分享链接>' -t                    下载抖音 MP4 + ASR 转写",
     "  rf cover -i scene.png -t '标题' -o cover.png   单图渲染封面",
     "  rf assets describe ./photo.jpg                  图片 / 视频 → 一句话描述",
+    "  rf dub ./clip.mp4                              一个视频 → 自动解说配音+字幕成片",
     "  rf history list                                 看之前生成的视频",
     "  rf tasks list --status running                  看进行中的任务",
     "",
-    "做 vlog?(用户拍的素材 → 视频,如宠物号)先看赛道剧本:",
-    "  rf vlog                                         列出可用赛道(宠物等)",
-    "  rf vlog pet                                     打印「宠物第一视角搞笑」完整 SOP",
+    "做 vlog?(用户拍的素材 → 视频)先看赛道剧本:",
+    "  rf vlog                                         列出可用赛道",
+    "  rf vlog pet                                     宠物第一视角搞笑 SOP",
+    "  rf vlog general                                 通用 SOP(没专门赛道就用它兜底)",
     "  → 拿到 SOP 后照着走:rf assets describe(看素材) → 写旁白 → rf compose(渲染)",
 ].join("\n"));
 registerAuth(program);
@@ -145,6 +148,7 @@ registerExtract(program);
 registerMedia(program);
 registerScript(program);
 registerCompose(program);
+registerDub(program);
 registerVlog(program);
 async function main() {
     if (process.argv.length <= 2) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "reelforge",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "AI 视频生成 CLI。一句话主题或自己的脚本 → 自动出抖音/TikTok/视频号竖屏 MP4。安装即用：`reelforge` 或短别名 `rf`。",
   "license": "Apache-2.0",
   "type": "module",