wecut 是做什么的？
wecut 将 JSON 项目渲染为 MP4（或 GIF），使用本机安装的 FFmpeg。你描述编辑意图，WeCut 完成视频工作。它绝不调用网络服务。
如果 wecut 不在 PATH 中，请用 npx -y wecut（Node 16+）替代下面的所有命令。如果 WeCut 以 MCP 服务器方式连接，则相同的步骤对应工具 wecut_doctor、wecut_probe、wecut_validate、wecut_preview（返回帧图像）、wecut_render、wecut_list、wecut_schema、wecut_example、wecut_analyze（返回帧拼接图）、wecut_recipe_list、wecut_recipe_show、wecut_recipe_apply 和 wecut_recipe_from_project；通过 project（对象）或 projectFile（路径）传入项目。
工作流程
- 检查本机环境（只需一次）：
wecut doctor。如果报告 FFmpeg 缺失，请遵循其hint（例如sudo apt-get install -y ffmpeg）。 - 将媒体文件放入工作目录。 项目中的所有路径都相对于你运行
wecut的文件夹（或--root DIR）。拒绝 URL：请先下载文件。 - 查看媒体信息：
wecut probe media/talk.mp4 media/music.mp3会输出时长、大小、帧率以及是否有音频。使用这些数值设置from/to。 - 编写
project.json（格式如下）。wecut example podcast-clip会打印完整示例；wecut schema打印 JSON Schema；wecut list显示所有样式、字体、转场和滤镜名称。 - 验证：
wecut validate project.json。错误会返回 JSON 指针（例如/clips/0/to）和hint。修复后重复验证。 - 渲染前预览：
wecut preview project.json --at 0.5,3,10会将小尺寸 JPG 帧写入out/preview/。打开它们检查构图、文字大小和字幕位置。 - 渲染：
wecut render project.json。使用--preset draft进行快速的 540p 检查，默认final用于交付。
每条命令输出一个 JSON 对象。退出码：0 成功，2 无效输入，3 缺失依赖，4 渲染失败，5 超出限制。你可以通过 wecut render - 通过管道传入项目。
项目格式
{
"wecut": "1",
"output": { "file": "out/clip-01.mp4", "ratio": "9:16", "res": 1080, "fps": 30 },
"clips": [
{ "src": "media/talk.mp4", "from": 754.2, "to": 781.0, "focus": { "x": 0.42, "y": 0.5 } },
{ "src": "media/talk.mp4", "from": 795.5, "to": 812.0, "zoom": 1.15 }
],
"texts": [
{ "text": "How I made my first $10k", "start": 0, "end": 3, "style": "hook", "y": 0.2, "in": { "type": "pop" } }
],
"captions": { "words": "media/talk.words.json", "src": "media/talk.mp4", "style": "karaoke" },
"audio": [ { "src": "media/music.mp3", "volume": 25, "loop": true, "duck": true, "fadeOut": 1.5 } ]
}
重要规则：
- 两套时间系统。 片段的
from/to是源文件的秒数。其他所有内容（texts、overlays、audio.at、filters、effects）是最终视频的秒数。wecut validate会打印最终duration。 - 转场重叠。 片段上的
transition会与下一个片段融合，并使视频缩短其duration长度。 - 构图。 默认
fit为cover（填充并裁剪）。通过focus（0..1；x 0.3 保留左侧）和zoom控制裁剪位置。使用"fit": "contain"配合"background": "blur"可显示完整画面。 - 位置 是画布的比例，0.5 表示中心。字体
size以 1080p 下的像素为单位。 - 图片 使用
duration（默认 3），可以添加motion：in、out、left、right、up、down。 - 文本中不支持 Emoji。 请将其放入 PNG 并通过
overlays添加。
字幕
为 WeCut 提供带时间戳的转录文本，它会生成字幕：
words：.json、.srt或.vtt文件路径，或者内联数组[{"word": "hi", "start": 0.1, "end": 0.4}]。OpenAI/Groq 的verbose_json和 whisper.cpp 的 JSON 格式可直接读取。src：设置为转录文本对应的视频。这样转录文本保留源文件的原始时间，WeCut 会将该文件每个剪裁片段中的每个单词映射到输出时间线上（包括变速影响）。如果不设置src，时间必须已经是输出时间。style：classic、yellow、box-black、box-white、bold、comic、shadow（一次显示一个短语）、karaoke、karaoke-green（说出的单词高亮）、pop（一次一个放大的单词）。
如果需要转录文本：当 FFmpeg 包含 Whisper 滤镜时，wecut doctor 会报告 local_transcription: true。否则，请使用你已有的任何语音转文字服务，并保存其单词时间戳为 JSON。
模板：复制成功结构
Recipe（模板） 是编辑结构而不包含具体内容：包含各个部分（例如 5 秒的 hook + 标题卡片 + 正片）、文字槽位、字幕和音乐样式、效果。将其应用于新片段、新单词和新音乐即可生成项目。
- 分析一个成功的视频：
wecut analyze media/viral.mp4返回镜头和节奏、前 3 秒的剪辑点、闪光、节奏、停顿、静音平台结尾（可忽略），以及sheet：每个镜头一帧的拼接图。查看拼接图以了解标题卡片、文字样式、构图和字幕样式。 - 选择或编写一个模板：
wecut recipe list（内置模板：news-headline、news-headline-blur、quote-hook、vlog-phrases、podcast-punch、photo-slideshow，以及工作目录中的recipes/*.json）。wecut recipe show <名称>列出其角色和文字槽位。要编写新模板，请遵循wecut recipe schema。 - 应用模板：
{
"recipe": "news-headline",
"clips": [
{ "src": "media/broll.mp4", "role": "hook" },
{ "src": "media/talk.mp4", "from": 120, "to": 165 }
],
"texts": { "label": { "text": "页面名称" }, "headline": { "text": "一句话总结", "emphasis": ["claim"] } },
"transcript": "media/talk.words.json",
"write": "projects/clip-01.json"
}
wecut recipe apply --input request.json（或 --input - 从 stdin 读取 JSON）会检查所有内容并保存项目；之后执行 preview 和 render。没有指定角色的片段会自动填充 body 部分；某个部分缺少片段时，会借用下一个片段开头的素材。
- 保存自己的模板：
wecut recipe from-project projects/clip-01.json --name my-style --write recipes/my-style.json会保留部分结构、转场、文字槽位、字幕样式、效果和默认音乐轨道。
音乐：模板可以自带音乐轨道（music.src），默认使用，类似 CapCut 模板中的歌曲。传入 "music": "media/song.mp3"（或视频，取其音频）可替换，传入 "none" 则无音乐。从他人视频中取用的歌曲可能在平台上传后被静音；在应用内发布时添加流行音频可避免此问题。
复制的是结构，而非内容：其他创作者的素材、确切措辞和音乐归他们所有。
从长视频制作多个片段
- 使用
wecut probe探测源文件并获取带时间戳的转录文本。 - 阅读转录文本，挑选精彩时刻（由你决定；WeCut 不评判内容）。
- 为每个片段编写一个项目，每个项目的
captions.src指向同一个源文件，这样一份转录文本可服务于所有片段。 - 对其中一个执行
wecut preview，调整focus，然后逐个执行wecut render。
故障排除
E_RANGE：to超出文件末尾。使用wecut probe获取实际时长。E_PATH：路径不在工作目录内或者是 URL。E_MEDIA：文件不是可读的视频、图片或音频文件，或者类型与该字段不匹配（例如音乐放在了clips中，视频放在了overlays中）。E_DEPENDENCY：FFmpeg 缺失、版本低于 6 或未编译 libass。运行wecut doctor。- 渲染太慢：使用
--preset draft、更低的output.res或减少每个项目的片段数量。结果中的render_seconds和realtime_factor显示本机的渲染速度。 - 查看 FFmpeg 将要运行的确切命令：
wecut render project.json --dry-run。