Oh My Cassette

Oh My Cassette

在 Claude Code、Codex、OpenCode 或 Hermes 中，与 Cassette Agent 对话即可剪辑视频。
_{一个发布在 PyPI 上的小型 MCP 桥接工具。剪辑工具来自 Cassette MCP 服务，因此无需更新插件，也能保持最新。}

中文

---

一次 Claude Code 会话，输入内容如实呈现。 导入五段 4K 旅行视频（共 10½ 分钟素材）和一首歌，将四句剪辑要求和一行修改意见原样发送给 Cassette Agent，最终在 cassette-exports/ 中生成一段 30 秒的 1080p MP4。等待过程已快进：实际导入耗时 4½ 分钟，初剪耗时 9½ 分钟，修改耗时 3½ 分钟，导出耗时 1 分钟。

用这五段视频剪辑一支 30 秒的土耳其预告片，配乐使用 Pamgaea.mp3，并跟随节拍。以卡帕多奇亚黎明时分亮起的热气球开场，从古代遗迹一路拍到海边，在每个地点首次出现时标注名称，最后以雾气笼罩的湖泊和标题 TURKEY 收尾。

遗迹部分拖沓了。只保留以弗所最好的两个镜头，并把骆驼放在热气球之后。

_{观看生成的预告片（MP4，30 秒，含声音）。视频素材和音乐来源见下文。}

30 秒内完成安装

你需要 uv（首次启动时会自动获取 Python 和软件包）以及用于导入视频的 ffmpeg。

# Claude Code
claude plugin marketplace add Cassette-Editor/oh-my-cassette
claude plugin install oh-my-cassette@cassette-editor

# Codex
codex plugin marketplace add https://github.com/Cassette-Editor/oh-my-cassette.git
codex plugin add oh-my-cassette@cassette-editor

# Hermes
hermes mcp add cassette --command uvx --args oh-my-cassette==0.6.0

OpenCode 和其他 MCP 主机：请参阅下文的安装。运行 uvx oh-my-cassette==0.6.0 login，并在浏览器中通过邮箱验证码完成登录。如果 Agent 无法刷新工具列表，请重启它，然后输入：

创建一个新的 Cassette 项目并导入 ./footage 中的片段，然后剪辑一支 30 秒的旅行视频，并在开头加上标题。

从 0.4 升级

0.5 是一次重写。0.4 插件自带编辑运行时、音乐搜索和 Hermes 网关；0.5 则是连接到 Cassette MCP 服务的轻量桥接层，Agent 看到的工具由该服务提供。

• 重新登录，运行 uvx oh-my-cassette==0.6.0 login。0.4 的密码和令牌不再使用。
• 工具已更新。 项目、编辑轮次、问题、计划、撤销、媒体、分析和导出功能都来自服务，并带有各自的说明；0.4 的工具名称（cassette_run_job、cassette_ingest_media、cassette_match_bgm，……）已不再提供。请重新安装插件，或将主机配置指向 uvx oh-my-cassette==0.6.0。
• 项目保存在你的 Cassette 账户中，与你在网页或 Cassette for Mac 中打开的项目相同；每个回答附带的编辑器链接都会打开你正在处理的项目。0.4 的会话不会迁移。
• Hermes 现在只是一个普通的 MCP 主机；请移除 0.4 网关插件。

项目与保留期限

桥接层创建的项目是云端项目；闲置三天后，Cassette 会连同媒体一起删除。每次使用都会重置期限，每个回答都会说明到期时间（retention_expires_at）。导出的文件已保存在你的计算机上的 cassette-exports/ 中，并会一直保留。在 Cassette for Mac 中创建的项目会一直保留；只要 Mac 上的应用处于在线状态，桥接层就能打开、编辑和导出该项目，但其媒体会在应用中导入。

概览

Oh My Cassette 将你的编码 Agent 连接到 Cassette 编辑 Agent。它是一个本地 stdio MCP 服务，会将请求转发给 Cassette MCP 服务（CASSETTE_MCP_URL），后者再调用 Cassette 后端：

Claude Code / Codex / OpenCode / Hermes  ──stdio──▶  oh-my-cassette  ──HTTP──▶  Cassette MCP service  ──▶  Cassette backend

• 工具由服务提供。 服务列出的内容（项目、编辑轮次、问题、撤销、导出）就是 Agent 看到的内容，并附有服务自己的说明和工作流指引。Cassette 更新时，工具也会随之更新；插件无需发布新版本。
• 桥接层只处理需要访问你计算机的操作。 调用中指定的本地文件会先经过处理并上传（仅限工作区中的媒体类型文件）：视频会通过 ffmpeg 转码为服务声明的版本；服务无法直接接收的音频或图像也会进行转换。每个文件在准备下一个文件的同时上传，最多同时传输四个文件；如果文件上传中断，再次导入时会从之前的导入进度继续。 导出的文件会下载到 cassette-exports/。每次调用都会附带工作区标识，以便服务按目录记住项目。
• 耗时操作不会导致主机超时。 每次调用都会等待有限时长；本地准备耗时较长时，会返回 preparing 并在后台继续处理，下一次相同调用会接着处理。
• 部署更新后仍可正常运行。 连接断开或服务拒绝请求时，它会自动重新连接，并重新发送包含请求名称的调用；它会恢复中断的下载，报告带有 retryable 标记的 bridge.* 错误（如果服务提供了重试时间，还会附上 retry_after_seconds）；当服务无法访问或拒绝令牌时，则只会列出一个 cassette_bridge_status 工具，说明原因。

插件与服务之间的规则定义在 src/oh_my_cassette/contract.py 中；运行 oh-my-cassette check 可验证服务是否符合这些规则。

要求

• 一个已获邀请的 Cassette 账户，以及一个实现 contract v1 的 Cassette MCP 服务。使用 uvx oh-my-cassette==0.6.0 check --url <endpoint> 检查。在服务无法访问或拒绝令牌期间，只会列出 cassette_bridge_status。
• uv 0.5 或更高版本。uvx oh-my-cassette==0.6.0 会自行解析 Python 3.11 或更高版本。
• 导入视频需要 ffmpeg（包含 ffprobe）：brew install ffmpeg、sudo apt install ffmpeg 或 winget install ffmpeg。视频会先在你的计算机上转码，然后再上传。带有 zscale 的构建版本还可以正确地对 HDR 素材进行色调映射。

工具接受哪些格式，以及文件在上传前如何准备，由服务声明（最多包括视频、音频和图像类型）。

配置

使用项目所属的 Cassette 账户，通过 oh-my-cassette login 登录一次：浏览器会要求你输入通过电子邮件收到的验证码并征求你的同意。登录后即可访问该账户下的所有项目，无论项目是在网页上创建，还是在 Cassette for Mac 中创建。媒体位于 Mac 上的项目会在那台 Mac 的应用中打开；读取其中的图片或声音以及导出项目都需要那台 Mac 在线，媒体也会在那里导入。登录、状态查询和退出登录都使用操作系统密钥环；无需复制令牌。以下环境变量均为可选覆盖项。

变量	默认值	含义
CASSETTE_MCP_URL	已保存的连接；否则为 https://mcp.trycassette.online/mcp	显式覆盖 MCP 端点。
CASSETTE_AUTH_TOKEN	未设置	高级持有者令牌覆盖项。通常应使用 login；同样适用账户、范围和资源检查。切勿将其放入共享配置。
CASSETTE_WORKSPACE	主机启动服务时所在的目录	相对路径的解析位置、本地文件的来源，以及服务可以为项目记住的目录。如果主机在整个磁盘或你的主目录中启动服务，在设置此变量或 CASSETTE_ALLOWED_ROOTS 之前，服务无法读取任何文件。
CASSETTE_ALLOWED_ROOTS	未设置	本地文件来源的额外目录（以 : 分隔；Windows 上使用 ;）。
CASSETTE_DOWNLOAD_DIR	<workspace>/cassette-exports	导出文件的保存位置。默认位置必须位于工作区内：如果 cassette-exports 符号链接指向其他位置，操作会被拒绝。
CASSETTE_MAX_UPLOAD_MB / CASSETTE_MAX_DOWNLOAD_MB	4096 / 16384	每个文件的大小限制。
CASSETTE_UPLOAD_ANY_TYPE	关闭	工具接受非媒体文件时，允许上传此类文件。
CASSETTE_LOCAL_WAIT_SEC	240	一次调用等待本地准备和上传的时长上限；超时后会返回 preparing。
CASSETTE_FFMPEG / CASSETTE_FFPROBE	来自 PATH	用于准备本地媒体的 ffmpeg 和 ffprobe 程序。
CASSETTE_TEMP_DIR	系统临时目录	每次上传创建独立的私有目录（oh-my-cassette-job-*）来存放准备好的文件，直到文件上传完毕。
CASSETTE_CONNECT_TIMEOUT_SEC	10	连接时等待服务的时长。
CASSETTE_MCP_HOST	未设置	主机未标识自身时，发送给服务的主机名。
OH_MY_CASSETTE_LOG	WARNING	stderr 上的日志级别。

安装

Claude Code

插件（推荐）：顶部的两条命令。插件使用 oh-my-cassette login 保存的连接，并以 10 分钟的工具超时时间启动 uvx oh-my-cassette==0.6.0。

不使用插件的项目级配置：将 .mcp.json 复制到你的项目中，或运行：

claude mcp add --transport stdio cassette -- uvx oh-my-cassette==0.6.0

技能文件位于 skills/cassette-video-edit/SKILL.md，并随插件一起提供。

Codex

插件：使用顶部的两个命令（.codex-plugin/plugin.json 在其中内联声明了服务，设置 tool_timeout_sec: 600，并从你的 shell 传递 CASSETTE_* 变量）。也可以直接添加服务：

codex mcp add cassette -- uvx oh-my-cassette==0.6.0

OpenCode

添加到 opencode.json（项目配置文件或 ~/.config/opencode/opencode.json）：

{
  "mcp": {
    "cassette": {
      "type": "local",
      "command": ["uvx", "oh-my-cassette==0.6.0"],
      "timeout": 600000
    }
  }
}

然后复制技能，让 OpenCode 加载它：

mkdir -p ~/.config/opencode/skills/cassette-video-edit
curl -fsSL https://raw.githubusercontent.com/Cassette-Editor/oh-my-cassette/v0.6.0/skills/cassette-video-edit/SKILL.md \
  -o ~/.config/opencode/skills/cassette-video-edit/SKILL.md

OpenCode 不支持 MCP elicitation，但这没问题：编辑 Agent 的问题会作为普通工具结果返回，服务的工具会说明如何回答这些问题。

Hermes

hermes mcp add cassette --command uvx --args oh-my-cassette==0.6.0

mkdir -p ~/.hermes/skills/cassette-video-edit
curl -fsSL https://raw.githubusercontent.com/Cassette-Editor/oh-my-cassette/v0.6.0/skills/cassette-video-edit/SKILL.md \
  -o ~/.hermes/skills/cassette-video-edit/SKILL.md

在 ~/.hermes/config.yaml 中设置 mcp_servers.cassette.timeout: 600，以适应调用的有限等待时间。Hermes 在这里是一个纯 MCP 主机：0.4 网关／插件层已经移除。

其他 MCP 主机

命令为 uvx，参数为 ["oh-my-cassette==0.6.0"]，使用 stdio 传输，工具超时设为 10 分钟，并设置上述环境变量。没有 uv？pipx run oh-my-cassette==0.6.0 也可以。

一次操作的流程

you:    Import intro.mp4 and beach.mov, then make a 20-second cut with the title "Kota Kinabalu".
agent:  (calls the service's import tool with ["intro.mp4", "beach.mov"])
        bridge: transcodes both videos, uploads them, passes the service media references
        (calls the service's editing tool with your sentence, verbatim; progress streams while it runs)
        "Done. Added a 20 s cut from both clips with the title at the start (v0→v3). Open it: <editor link>"
you:    Export it.
agent:  (calls the service's export tool)
        bridge: downloads the MP4 to cassette-exports/kota-kinabalu.mp4

服务会提供编辑器链接：在浏览器中打开，即可实时查看运行情况并手动接管。

检查服务

uvx oh-my-cassette==0.6.0 check --url http://127.0.0.1:8790/mcp --upload \
  --arguments '{"project_id": "<a test project>"}'

每项检查都会输出一行（传输和令牌、契约声明、说明、工具架构、本地文件和 prepare 声明；使用 --upload 时还会执行真实的上传往返测试；--arguments 用于指定文件工具的其他参数），任何一项失败都会以状态码 1 退出。--json 会输出机器可读的结果，供服务的 CI 使用。服务必须支持 MCP 2026-07-28；如果只响应握手阶段的 initialize，就会无法通过传输检查，桥接器也会拒绝该服务，并返回 bridge.protocol_unsupported。

更新

在主机配置中更新版本固定值（oh-my-cassette==<new version>），或重新安装插件；uvx 会在下次启动时获取新 wheel。发行说明见：CHANGELOG.md。

开发

git clone https://github.com/Cassette-Editor/oh-my-cassette && cd oh-my-cassette
uv sync --group dev
uv run pytest -q                                   # reference service on loopback, no network; needs ffmpeg
uv run oh-my-cassette                              # the bridge itself (stdio)
uv run oh-my-cassette check --url <endpoint>       # conformance check

tests/reference_remote.py 是契约的可执行参考服务；RELEASING.md 介绍了 PyPI 发布流程。

致谢

演示视频由 yasin ilcebay 拍摄，采用 CC BY 3.0 许可，来自 Wikimedia Commons： Aizanoi Temple of Zeus、 Cappadocia、 Datça、 Ephesus 和 Gölcük Lake。预告片对视频进行了剪辑和重新编排，并添加了地点名称、标题和音乐。

音乐为 Kevin MacLeod（incompetech.com）创作的《Pamgaea》
采用 Creative Commons：署名 4.0 许可
https://creativecommons.org/licenses/by/4.0/
预告片使用了其中一段节选。

许可证

代码采用 MIT 许可证。Oh My Cassette 是客户端；Cassette 服务有自己的条款。

演示录屏（assets/demo-claude-code.gif）、预告片画面（assets/turkey-teaser.jpg）以及随发行版本附带的预告片视频包含上述致谢作品。它们不受 MIT 许可证约束，仍遵循各自的许可（视频素材采用 CC BY 3.0，音乐采用 CC BY 4.0）。

_{MCP 注册表：mcp-name: io.github.Cassette-Editor/oh-my-cassette}