返回首页RiffCut 影创 · 使用文档v0.1.0

RiffCut 影创 · 使用文档

从安装到出片,一份文档讲清楚

RiffCut 影创是 macOS 上的本地剪辑智能体。你说一句话,AI 导演自己定方向、写分镜、找画面、配乐、出片,最后抽帧检查一遍才交给你。素材、工程、成片全部留在你自己的 Mac 上,不上传云端。

v0.1.0 · build 4macOS 12.0+ · Apple Silicon全程本机运行更新于 2026-11

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

完整版安装步骤

1

合并分卷

把两个分卷放在同一目录,终端执行:

cat RiffCut-full.zip.part-aa RiffCut-full.zip.part-ab > RiffCut-full.zip
2

解压

双击 RiffCut-full.zip,或在终端 unzip RiffCut-full.zip。

3

拖进应用程序

把解压出来的 RiffCut影创.app 拖进「应用程序」文件夹。

4

去掉隔离属性并打开

应用是 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。

1

选工作区

在设置里指定一个工作区目录。之后你的素材、工程、成片都围绕这个目录组织。

2

说清你要什么

一句话说明主题、时长、风格。AI 导演判断信息够不够,不够才会追问,不会一遍遍啰嗦地问。

3

等它出片

AI 自动拆任务、写分镜、找画面、配音配乐、渲染,最后抽帧自查一遍再交付。

数据写在 ~/Library/Application Support/RiffCut影创;打包版程序目录只读,换版本不会丢数据。开发态则用项目里的 home/ 目录。

接自己的模型(可选)

内置三家预置供应商,选一个就会自动填好地址和模型 ID,你只需粘 Key:

供应商接口地址模型免费额度
白鹿 BailuCodehttps://bailucode.com/openapi/v1bailu-2.8每天 500 万 Tokens
Agnes 国内https://api.agnes-ai.cn/v1agnes-2.5-flash免费,10 rpm
Agnes 国际https://apihub.agnes-ai.com/v1agnes-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 会问,其余都按行业默认参数走。

三步交付流程

1

预览(preview)

AI 先出 720p 预览片。这一步快,用来确认分镜、节奏、字幕对不对。

2

停下,等你确认

预览出来后会停下来,把片子交给你看。你可以让它改文案、换素材、调节奏。在你点头之前不会出最终版。

3

成片(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 篇导演技能分七类

01

创作流程 · 13 篇

从选题、脚本、分镜到素材组织,AI 导演按流程推进

02

出片技法 · 10 篇

运镜、转场、调色、节奏、卡点等专业剪辑手法

03

字幕配音 · 5 篇

切句、预设、关键词高亮、情感配音与音效

04

交付复核 · 4 篇

抽帧自检、响度检查、三遍抽离测试、交片五问

05

生图 · 4 篇

真人图七要素、角色卡、形状揭示、背景处理

06

流程纪律与发布 · 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 三类),按用途分布:

背景纹理 80动效零件 66产品展示 65转场 62图表数据 60文字动画 26片头片尾 24下三分之一 19字幕 18社媒包装 15其他 13

套模板时只改模板里声明过的变量(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。