RiffCut 影创 · 使用文档
从安装到出片,一份文档讲清楚
RiffCut 影创是 macOS 上的本地剪辑智能体。你说一句话,AI 导演自己定方向、写分镜、找画面、配乐、出片,最后抽帧检查一遍才交给你。素材、工程、成片全部留在你自己的 Mac 上,不上传云端。
01认识 RiffCut
先把一件事说清楚:RiffCut 影创是一个装在你 Mac 上的本地剪辑智能体,不是一个把素材传到云端再返回的在线工具。
它是什么
RiffCut 影创(以下简称 RiffCut)把一位专业剪辑师 + 导演的工作方法,写进了 AI 内核。你用一句话说清要什么,AI 导演自己判断该不该追问、该走哪条流程,然后拆解任务、写分镜、找画面、配音、配乐、出片,最后抽帧检查一遍才交给你。
它本质是一个 Electron 桌面应用,内置 DSH(DeepSeek Harness)AI 导演内核。素材、工程、成片全部本地存储,不上传云端,可离线运行——离线时 AI 对话、生图、热点检索不可用,但本地剪辑、套模板、渲染照常。
十二个核心特性
本地与数据
- 数据写在
~/Library/Application Support/RiffCut影创,素材工程不强制上云 - 自有
timeline.json工程格式,四轨结构,本地 HyperFrames 渲染 - 成片、封面、工程 JSON 写回客户目录,首页读工程不读零散 mp4
- 单实例锁 + 毫秒级启动打点,可诊断
AI 与工具
- DSH 内核通过 stdio JSON-RPC 驱动,配 41 篇导演技能
- 界面和 AI 用同一张工具注册表,界面有的 AI 就能调
- 后台工位并行处理长任务,主对话保持秒回
- 插件市场约 6112 个插件、6 小时缓存,对外暴露 MCP 服务
成片能力
- ASS 字幕直出,11 档预设,关键词高亮 + 进场动画
- 音频四层混音,−14 LUFS 统一响度,本地 Ming 情感配音
- 50 种转场、10 种影调、8 档运镜、11 种音效现场合成
- 横转竖模糊底铺满、平台规格自动导出
交付与合规
- 内置 11 个平台规格,5 平台网页发布默认 dry-run
- 零依赖 CDP 复用你已登录的 Chrome,不碰你的密码
- ad-hoc 签名打包,用户数据不进安装包
- AGPL-3.0 + 商业双许可,产出物版权归你
技术栈
了解底层有助于判断能不能改、怎么改。当前 v0.1.0 的版本组合:
| 组件 | 版本 / 说明 |
|---|---|
| 桌面壳 | Electron ^45.3.4 |
| 运行时 | Node.js 26+(内核自带,无需你安装) |
| 渲染引擎 | hyperframes ^0.9.66(本地依赖,不走 npx) |
| AI 内核 | DSH 0.2.1-rc.3 |
| 音视频 | FFmpeg / ffprobe 6.0(已打包) |
| 协议 | MCP 2024-11-05 |
当前版本 v0.1.0,build 4,发布于 2026-11。
02安装与系统要求
RiffCut 只跑在 Apple Silicon Mac 上,安装包是一个 .zip(不是 dmg)。完整版被拆成两个分卷,下载后要合并。
系统要求
| 项目 | 要求 |
|---|---|
| 系统 | macOS 12.0 及以上 |
| 芯片 | Apple Silicon M1 / M2 / M3 / M4(Intel 未测试) |
| 内存 | 8 GB 起步,16 GB 及以上更顺 |
| 磁盘 | 完整版装完约 3.0 GB,轻量版约 1.2 GB |
| 依赖 | 无需另外安装 Node.js、Python、FFmpeg——全部内置 |
怎么看芯片:左上角苹果菜单 → 关于本机 → 芯片。写"Apple M1/M2/M3/M4"就是对的;写"Intel"则本机未经过测试。
选哪个版本
完整版(推荐)· 约 2.1 GB
- 两个分卷:
RiffCut-full.zip.part-aa(1,572,864,000 字节)+RiffCut-full.zip.part-ab(654,862,708 字节) - 解压安装后约 3.0 GB
- 已内置 Ming-TTS 情感配音 + SenseVoice 语音识别,装好即用
轻量版 · 约 427 MB
- 单个
RiffCut-lite.zip(448,105,135 字节) - 解压安装后约 1.2 GB
- 语音模型需自己另下(约 1.9 GB),适合磁盘紧张或只要先试试
下载后先校验
官方 SHA-256 对照表见安装包随附的 DOWNLOAD.md。在下载目录打开终端执行:
shasum -a 256 RiffCut-full.zip.part-aa
shasum -a 256 RiffCut-full.zip.part-ab完整版安装步骤
合并分卷
把两个分卷放在同一目录,终端执行:
cat RiffCut-full.zip.part-aa RiffCut-full.zip.part-ab > RiffCut-full.zip解压
双击 RiffCut-full.zip,或在终端 unzip RiffCut-full.zip。
拖进应用程序
把解压出来的 RiffCut影创.app 拖进「应用程序」文件夹。
去掉隔离属性并打开
应用是 ad-hoc 签名、未过公证,直接双击可能被拦。终端执行后再打开:
xattr -cr /Applications/RiffCut影创.app若仍提示无法验证开发者,可右键应用 → 打开 → 再点「打开」。
轻量版安装步骤
unzip RiffCut-lite.zip
mv RiffCut影创.app /Applications/
xattr -cr /Applications/RiffCut影创.app轻量版第一次要用语音功能,需补下模型,命令见下一节「首次使用与模型配置」。
升级
程序内已实现升级器(检查 → 下载 → 校验 SHA-256 → 先备份再替换 → 可回滚)。启动时默认不自动检查,需要时在设置里手动触发;配置文件 home/配置/更新.json 中 check_on_start 默认 false、require_sha256 默认 true,升级源 feed_url 只允许 https。
03首次使用与模型配置
装好就能用——RiffCut 预置了一个免注册的 auto 模型。等你用顺手了,再按需要接自己的 API Key。
第一次打开:直接对话
首次启动不用做任何配置。首页输入框直接说话,例如「帮我把这段素材剪成一个 30 秒的科技感短片」。预置的 auto(多模态) 会走作者公共网关(模型 id preset-auto),无需注册、无需填 Key。
选工作区
在设置里指定一个工作区目录。之后你的素材、工程、成片都围绕这个目录组织。
说清你要什么
一句话说明主题、时长、风格。AI 导演判断信息够不够,不够才会追问,不会一遍遍啰嗦地问。
等它出片
AI 自动拆任务、写分镜、找画面、配音配乐、渲染,最后抽帧自查一遍再交付。
数据写在 ~/Library/Application Support/RiffCut影创;打包版程序目录只读,换版本不会丢数据。开发态则用项目里的 home/ 目录。
接自己的模型(可选)
内置三家预置供应商,选一个就会自动填好地址和模型 ID,你只需粘 Key:
| 供应商 | 接口地址 | 模型 | 免费额度 |
|---|---|---|---|
| 白鹿 BailuCode | https://bailucode.com/openapi/v1 | bailu-2.8 | 每天 500 万 Tokens |
| Agnes 国内 | https://api.agnes-ai.cn/v1 | agnes-2.5-flash | 免费,10 rpm |
| Agnes 国际 | https://apihub.agnes-ai.com/v1 | agnes-2.5-flash | 免费,20 rpm |
两个易踩的坑:白鹿的 base_url 必须带 /openapi,否则返回的是网页 HTML 不是 API;Agnes 国际版的 Key 只在 apihub.agnes-ai.com 域名生效,填到国内端点会 401。
操作路径:模型管理 → 添加 / 配置 → 选供应商(自动填地址和模型 ID)→ 粘 API Key → 测试 → 回首页在下拉框选中。
Key 存在 macOS 钥匙串里(service riffcut.apikeys),不写进配置文件、不随工程备份外泄。命令行手动写入的格式:
security add-generic-password -U -s riffcut.apikeys -a <model-id> -w <key>轻量版补装语音模型
轻量版默认不含语音模型。要用配音 / 语音识别,先装 Hugging Face CLI,再下两个模型:
pip install -U "huggingface_hub[cli]"
hf download inclusionAI/Ming-3.0-tts-0.5B \
--local-dir "$HOME/Library/Application Support/RiffCut影创/系统/本地模型/语音/weights/ming-tts/"
hf download FunAudioLLM/SenseVoiceSmall model.int8.onnx tokens.txt \
--local-dir "$HOME/Library/Application Support/RiffCut影创/系统/本地模型/语音/weights/sense-voice/"数据都放在哪
- 客户素材:
客户/客户名/,工程在客户/客户名/工程/剪辑/,成片在客户/客户名/产出/ - 打包版根目录:
~/Library/Application Support/RiffCut影创 - 卸载应用不会自动删除这些数据——想清理需自己动手
04做出你的第一支片子
这一节带你从一句话走到一条能发的成片。你不需要懂剪辑术语——需要决策的地方 AI 会问,其余都按行业默认参数走。
三步交付流程
预览(preview)
AI 先出 720p 预览片。这一步快,用来确认分镜、节奏、字幕对不对。
停下,等你确认
预览出来后会停下来,把片子交给你看。你可以让它改文案、换素材、调节奏。在你点头之前不会出最终版。
成片(finalize)
确认后渲染 1080p 乃至更高规格的最终版,写回客户产出目录。
交片前它会做「三遍抽离测试」(分别只看画面 / 只听声音 / 只看字幕,各自能不能独立看懂)和「交片五问」自检,不通就重做。
它默认怎么剪
这些是内置的行业默认,你不开口它就按这个走;想改直接说:
- 画幅帧率:1920×1080,30 fps 拍摄 + 光流补帧到 60 fps 输出,一次编码(crf 16 / preset slow / lanczos)
- 静态图处理:默认 4.5 秒 ken burns 缓慢推拉
- 平均镜长:30 秒片约 2.2 秒/镜,60 秒片约 3.0 秒/镜,更长的片约 4.5 秒/镜
- 出片速度:一条 5 秒片约渲染 35 秒(M 系列芯片实测量级)
画面:进场、转场、调色、运镜
进场动画 · 7 档
fade / slideUp / slideDown / slideLeft / slideRight / zoomIn / zoomOut,另有 ken burns 整段缓推。
转场 · 约 50 种
叠化、淡入 0.3–0.6 秒;闪黑闪白 0.3–0.4 秒;推滑 0.3–0.5 秒;卡点快淡 0.2–0.3 秒;故障 0.3–0.4 秒。全片建议不超过 3 种,切换太多显乱。
调色 · 10 种影调
电影 / 胶片 / 人像 / 黑白 / 冷调 / 暖调 / 青橙 / 褪色 / 高反差 / 原色。强度 look_strength 取 0~1,全片只用一种,避免风格打架。
运镜 · 幅度可调
默认放大约 1.25 倍做推拉摇移,camera_amount 设 0.5 可收敛幅度。画中画缩放 0.3–0.4(超过 0.5 会挡脸),分屏各占 0.5 宽、位置在 0.25 / 0.75。
声音:四层混音
| 层 | 电平 | 说明 |
|---|---|---|
| 对白 / 人声 | 0 dB | 最前,永远清晰 |
| 音效 | −8 dB | 点缀,九类音效现场合成 |
| 配乐 | −21 dB | 垫底,人声出现时再压低 4 dB(ducking) |
| 环境底噪 | −29 dB | 营造空间感 |
全片统一到 −14 LUFS、真峰 −1 dBTP,AAC 编码再留 1.2 dB 余量,保证各平台响度一致不爆音。配音走本地 Ming 情感 TTS(含 1.66 GB GGUF 模型),失败时自动回落到 ZipVoice 或系统 say。
字幕 · 11 档预设
自动按语义切句(单句最多 16 字 / 2 行,静音 0.42 秒以上断句,单段不超 12 秒),可做关键词高亮 + 进场动画,贴顶/居中/卡片各档可选。字幕底衬半透明深色 + 轻微模糊,保证任何画面上都读得清。
开头 3 秒很关键
AI 会用「钩子评分」(0–10 分)给开头打分,低于 7 分会主动重做。加分项是悬念、数字、冲突、直击痛点,减分项是铺垫太长、logo 开场。想要什么样的开头,说一句就能定向。
05核心功能模块
想深入一点的话,这一节讲清楚 RiffCut 内部是怎么运转的——工程格式、渲染管线、字幕音频、发布和后台工位。
AI 内核
RiffCut 内置 DSH(DeepSeek Harness)内核,通过 stdio JSON-RPC 驱动:初始化握手、发消息(session.prompt)、续聊(session.resume)、等待(session.wait)、关停(session.shutdown)。会话全局单实例、目录隔离。你看到的「AI 导演」就是这套内核 + 导演技能的组合。
工程格式 timeline.json
每个片子对应一个 timeline.json,默认 1920×1080 / 30 fps / 10 秒,四条轨道:
| 轨道 | 内容 |
|---|---|
v1 | 视频 |
g1 | 图形 / 贴纸 / 画中画 |
t1 | 字幕 |
a1 | 音频 |
元素坐标 x/y 是相对画布中心的 0~1 比例,w/h 是占画布比例,at 是片段内进度 0~1。进场缓动 power3.out、出场 power2.in,8 档动画预设。字幕底衬 rgba(10,16,24,.58) + 2px 模糊,层序为视频 1 / 图形 2 / 文字 3。
渲染管线
时间线 → HTML 帧 → MP4,走本地打包的 HyperFrames(不是临时 npx 下载)。渲染超时上限 1 小时,偶发失败自动重试 2 次,失败日志留在 /tmp/hf_render_fail.log。预设缓存成功 5 分钟、失败 30 秒,避免反复试错。
字幕切句常量
自动字幕的规则是可调的:单句 ≤ 16 字、≤ 2 行;静音阈值 −32 dB、最短静音 0.42 秒、最短片段 0.55 秒、单段最长 12 秒、句间留 0.7 秒。11 档视觉预设覆盖钩子字、编辑字、贴顶、卡片等场景。
后台工位
长任务(渲染、调研、批量处理)可以丢给后台工位并行跑,主对话保持秒回。最多 24 个工位,每个工位都要写清任务简报(brief),等结果最多 30 分钟,单个工位工具动作上限 80 条。say 可续聊,stop 只是界面层止损,trim 只淘汰已结束工位。
工具与 MCP
界面能点的和 AI 能调的,来自同一张工具注册表。RiffCut 也对外暴露一个 MCP 服务(名 velora-video,协议 2024-11-05,stdio JSON-RPC 2.0),外部 AI 工具可用 mcp__velora-video__ 前缀调用它的能力。
06导演技能与经验库
这是 RiffCut 的"内功"——41 篇导演技能把专业剪辑师的判断写成 AI 可执行的步骤,另有 19 条经验库条目约束细节。你不用背,说人话它自己会调用。
41 篇导演技能分七类
创作流程 · 13 篇
从选题、脚本、分镜到素材组织,AI 导演按流程推进
出片技法 · 10 篇
运镜、转场、调色、节奏、卡点等专业剪辑手法
字幕配音 · 5 篇
切句、预设、关键词高亮、情感配音与音效
交付复核 · 4 篇
抽帧自检、响度检查、三遍抽离测试、交片五问
生图 · 4 篇
真人图七要素、角色卡、形状揭示、背景处理
流程纪律与发布 · 7 篇
安全检查、dry-run、平台规格与发布确认
常用的几个"暗号"
这些是高频技能,直接说关键词就能触发:
按词锚定
把画面精确对到台词里的某个词,精度到 0.01 秒;重复词用 trigger_nth 指定第几次出现。
照这条剪
参考一条已有片子,比照它的镜头长度、节奏、响度来剪新片。各维度比值控制在 0.7–1.3、响度差 1 LU 以内。
高光切片
从长素材里自动挑高光片段。灵敏度 sensitivity 默认 0.45,片段最短 max(1.2, min(6, 片长×5%)) 秒、最长 max(6, min(45, 片长×25%)) 秒。
默奇剪辑权量
判断一条片子"该不该切"时,情感 51% > 故事 23% > 节奏 10% > 视线 7% > 二维 5% > 三维 4%。
19 条经验库
经验库是踩坑清单,比如转写媒体、AI 出图、计划核对等,都被整理成可复用的判断规则。举几个直接影响成片质量的:
- 真人图七要素:别直视镜头、背景略乱、避免平光、构图别太工整、衣服别穿过身体、留一点压缩痕迹、保留人的不完美——这样才不像 AI 图。角色卡的
desc要写满 100 字以上。 - 形状揭示:动画时长不超过所在段的 2/3,底色别用纯黑,给
#101A2E这类深蓝更自然。 - 安全教育七类:涉及未成年人、医疗、金融等内容时触发额外审查分组。
想让 AI 按某条技能来
不用记名字。直接描述目标即可,比如「按爆款开头钩子的逻辑改一下前 3 秒」「用电影感调色,别超过两种转场」「字幕卡在鼓点上」。AI 会自己选对应技能并套用上面的参数。
07工具与模板
RiffCut 内置一批工具和模板库。工具是 AI 动手的"手",模板是能直接套用的成片骨架。
内置工具
官网口径是 87 个 AI 工具。源码里按用途分成 16 组(A–P),涵盖剪辑、素材、字幕、音频、图表、发布等。权限分四档,默认策略是能读一切、写入要确认:
- 只读:查文件、读配置、搜素材——随时可调
- 建议:给出改动方案,等你点头
- 可整理:整理工程内文件,范围限定在工作区
- 完全托管:需你明确授权的操作(如发布)
工具单次输出上限 9000 字符,写操作有一张禁写目录表(WRITE_DENY),并限制在三个允许根目录内,避免误改系统文件。
模板库
官网口径 448 个可安装模板。源码注册表共 456 条目(分成 block / component / example 三类),按用途分布:
套模板时只改模板里声明过的变量(data-composition-variables),文案改动控制在 ±20% 以内,别去动基线文件,否则容易渲染崩。
命令行方式
官网演示过这些命令风格(当前打包版没有独立 CLI 可执行文件,主要通过界面和 AI 对话调用):
riffcut tools list # 列出工具
riffcut tools capabilities # 查看能力
riffcut tools probe # 探测环境
python3 -m riffcut scan # 扫描素材
python3 -m riffcut render # 渲染工程真正的构建脚本是 构建.app.sh / 发版.sh / fetch-kernel.sh,供开发者打包和发版用,普通用户用不到。
08多平台发布
一条片子要发到多个平台,最烦的是每个平台尺寸、字数、话题数都不一样。RiffCut 内置了 11 个平台规格,自动适配。
先预览,绝不擅自发布
发布默认走 dry-run(只填不点):AI 会把标题、话题、封面都准备好,但不会真的点"发布"。只有当你明确说「发出去」,才会带 exec=1 真正提交。这一步是硬约束,防止手滑发错。
各平台规格
| 平台 | 标题 / 正文 | 话题 | 画幅 |
|---|---|---|---|
| 抖音 | 标题 30 字 | 3–5 个话题 | 9:16 竖屏 |
| 小红书 | 标题 20 全角字 | ≤10 个话题 | 竖屏为主 |
| 快手 | 正文 500 字 | — | — |
| 视频号 | 标题 22 字 | 需 7 天登录态 | — |
| B 站 | 标题 80 字 | — | 16:9 横屏 |
横转竖时用模糊背景铺满、主体居中(focus 0.5、模糊 26、暗化 −0.2、降饱和 0.82),避免上下黑边。更多平台(YouTube / Shorts / Reels / TikTok / Instagram / X / LinkedIn 等)各有分辨率、时长、体积上限,AI 会按规格自动导出。
微信公众号
走独立流程:wechat_status → save → publish。不加 exec 只建草稿,确认后才带 exec=1 群发。封面图 > 10 MB、正文图 > 1 MB 会被拒,标题 ≤ 64 字、正文 ≤ 20000 字节。排版提供 ink / plain / warm 三套主题。
它是怎么连上浏览器的
发布通过零依赖 CDP 复用你已经登录的 Chrome,不碰你的密码、不存 Cookie。端口默认 9333,可用环境变量 RiffCut_CDP_PORT 覆盖。
09CLI 与快捷键
熟练之后用快捷键操作会快很多。下面这些是界面里真实生效的键位。
常用快捷键
| 按键 | 作用 |
|---|---|
| Enter / Shift+Enter | 发送消息 / 换行(首页输入框) |
| Space | 播放 / 暂停(剪辑页、编辑器) |
| S | 在播放头处切分片段(剪辑页) |
| Cmd + D | 复制选中片段(剪辑页) |
| Delete / Backspace | 删除选中片段 |
| ← / → | 逐帧移动播放头 |
| Cmd + Z / Cmd + Shift + Z | 撤销 / 重做 |
| Home | 跳到时间线开头 |
| Cmd + 滚轮 | 缩放时间线 |
| Esc | 关闭弹窗 / 中断当前 AI 任务 |
知识库页面另有 Cmd + S 保存;大量弹窗都支持 Esc 关闭,且 Esc 在捕获阶段会中断正在跑的 AI 内核任务。
斜杠指令
在对话框里输入这些指令可以触发快捷操作:
| 指令 | 作用 |
|---|---|
! 命令 | 直接跑一条 ffmpeg 命令 |
ctrl + o | 展开分镜视图 |
/tighten | 压缩工程(精简冗余片段) |
/tools | 管理工具 |
/style:名称 | 给全片套用某个风格 |
/tree | 切换工程版本树 |
/fork | 从当前节点另开一版 |
多数指令更自然的用法是直接说人话,AI 会自己判断意图,不必死记命令。
10授权 · 隐私 · FAQ
最后是关于钱、版权和安全的几个问题,也是大家最关心的。
常见问答
RiffCut 免费吗?商用有限制吗?
软件采用 AGPL-3.0 开源协议 + 商业授权双许可。个人免费使用走 AGPL-3.0;如果你要闭源、去品牌、要 SLA 技术支持,需要商业授权。用 RiffCut 剪出来的成片版权归你自己,可自由商用。
我的素材会被上传到云端吗?
不会。素材、工程、成片全部本地存储。联网只在主动触发时发生——AI 对话、AI 生图、热点检索、素材下载、语音服务、检查更新。RiffCut 明确"四不做":不采集你的内容、不埋点、不拿你的数据训练、不出售数据。
能装机器的要求是什么?Intel Mac 行不行?
需要 macOS 12 及以上、Apple Silicon(M1–M4)芯片、8 GB 内存起步(16 GB 更顺)。Intel Mac 官方未做测试,README 里说可以运行,但下载页以 Apple Silicon 为准。看芯片的方法:苹果菜单 → 关于本机 → 芯片。
完整版和轻量版选哪个?
完整版(下载约 2.1 GB、装完约 3.0 GB)内置 Ming-TTS + SenseVoice 语音模型,开箱即用。轻量版(下载 427 MB、装完约 1.2 GB)需要自己补装约 1.9 GB 的语音模型,适合磁盘紧张或暂时不用配音的人。
会自动更新吗?
源码里已经实现完整的更新机制(检查 / 下载 / 安装 / 回滚四步,强制 https + SHA-256 校验 + 先备份后替换),不过默认配置里自动检查是关的。下载页 FAQ 说 v0.1.0 没有自动更新,与源码现状有出入——以源码为准,实际是否弹出更新取决于发布配置。
遇到问题、发现漏洞怎么反馈?
一般问题去 GitHub 仓库 提 Issue。安全漏洞请发邮件到 China@cyanweb.cn,不要公开提 Issue,便于先修复再披露。
你需要自己把关的事
工具再强,下面这些责任在使用者自己:
- 素材授权:用到的音乐、字体、图片、肖像、商标,确认你有权使用
- AI 输出复核:事实性、数字、台词成片前自己过一遍
- 平台规则:发布前确认目标平台当前的内容规范
- 声音克隆:只克隆本人,或取得被克隆者的书面授权
更多细节见 GitHub 上的完整 README。