inthepond/ff-toolkit

ff-toolkit

将 FFmpeg 操作作为可供 LLM 调用的工具。

别再手写 FFmpeg 子进程调用和 JSON 工具 schema 了。
ff-toolkit 为你提供 5 个生产就绪的媒体操作、双格式 LLM schema（OpenAI + Anthropic），以及一个 MCP 服务器——全部只需一次 pip install。

真实世界用例

“我的 agent 流水线需要处理上传的视频” —— 给你的 agent 提供 openai_tools() 或 anthropic_tools()，让它自行决定如何剪辑、转码或提取音频。dispatch() 函数负责执行。

“我需要批量提取 16kHz WAV 用于 ASR” —— 一行代码：extract_audio("video.mp4", "out.wav", codec="pcm_s16le", sample_rate=16000, channels=1)

“我想在 Claude Desktop / Cursor 中使用 FFmpeg 工具” —— 添加 MCP 服务器配置（3 行 JSON），Claude 就能直接编辑你的视频。

“我想在 DeepSeek Harness 中使用 FFmpeg 工具” —— dsh plugin add dsh-ffkit 会从 integrations/deepseek-harness 安装原生插件。

“我厌倦了写同样的 FFmpeg 命令” —— 使用 CLI：ffkit clip input.mp4 output.mp4 --start 00:01:00 --duration 30

60 秒快速开始

安装（需要 FFmpeg 在 PATH 中）
pip install ff-toolkit

验证是否可用——无需 API 密钥
ffkit probe some_video.mp4

或者用生成的测试视频运行完整演示
python -m ff_kit.examples.local

Python API

from ff_kit import clip, extract_audio, merge, transcode

裁剪第 60-90 秒
clip("raw.mp4", "highlight.mp4", start="00:01:00", duration="30")

为 Whisper/Paraformer 提取 16kHz 单声道音频
extract_audio("raw.mp4", "speech.wav", codec="pcm_s16le", sample_rate=16000, channels=1)

拼接片头 + 正片 + 片尾
merge(["intro.mp4", "main.mp4", "outro.mp4"], "final.mp4")

压缩为 720p WebM 用于网页分发
transcode("raw.mp4", "web.webm", video_codec="libvpx-vp9", resolution="1280x720", crf=30)

CLI

ffkit clip raw.mp4 highlight.mp4 --start 00:01:00 --duration 30
ffkit extract-audio raw.mp4 speech.wav --codec pcm_s16le --sample-rate 16000 --channels 1
ffkit merge intro.mp4 main.mp4 outro.mp4 -o final.mp4
ffkit transcode raw.mp4 web.webm --video-codec libvpx-vp9 --resolution 1280x720 --crf 30
ffkit probe video.mp4

配合 OpenAI 使用（3 行代码即可集成）

from ff_kit.schemas.openai import openai_tools
from ff_kit.dispatch import dispatch

1. 将工具传给模型
response = client.chat.completions.create(
model="gpt-4o",
messages=messages,
tools=openai_tools(),       # ← 就这样
)

2. 执行模型调用的任何内容
tc = response.choices[0].message.tool_calls[0]
result = dispatch(tc.function.name, json.loads(tc.function.arguments))

配合 Anthropic 使用（3 行代码即可集成）

from ff_kit.schemas.anthropic import anthropic_toolspython
from ff_kit.dispatch import dispatch

response = client.messages.create(
model="claude-sonnet-4-20250514",
max_tokens=1024,
tools=anthropic_tools(),    # ← 就这样
messages=messages,
)

for block in response.content:
if block.type == "tool_use":
result = dispatch(block.name, block.input)

作为 MCP 服务器（Claude Desktop / Cursor）

添加到你的配置中（claude_desktop_config.json 或 Cursor 设置）：
json
{
"mcpServers": {
"ff-toolkit": {
"command": "ffkit-mcp",
"args": []
}
}
}

就这样。Claude 现在可以剪辑、合并、提取音频、添加字幕，并对你的文件进行转码。

作为 DeepSeek Harness 插件

DeepSeek Harness（dsh）是 DeepSeek 基于插件的智能体运行时。ff-toolkit 附带了一个原生 dsh 插件——即 integrations/deepseek-harness 中的 dsh-ffkit npm 包：
sh
pip install ff-toolkit                      # Python 端（本包）
dsh plugin --profile  add dsh-ffkit   # harness 端

该插件将所有五个操作注册为带结构化规范输出的类型化 harness 工具（可在 dsh Code Mode 中使用）以及 UI 卡片。在底层，每次调用都会运行 python -m ff_kit.bridge，这是一个基于 stdin/stdout 的一次性 JSON 入口点，任何宿主运行时都可以复用。有关配置，请参阅插件 README。

操作

| 工具 | 功能 | 示例 |
|------|-------------|---------|
| ffkit_clip | 按开始时间 + 结束时间/时长裁剪片段 | 从原始素材中剪辑精彩集锦 |
| ffkit_merge | 拼接多个文件 | 将片头 + 内容 + 片尾连接起来 |
| ffkit_extract_audio | 提取音频，可选重新编码 | 获取 16kHz WAV 用于语音识别 |
| ffkit_add_subtitles | 烧录或嵌入字幕（.srt/.ass/.vtt） | 将翻译后的 SRT 硬字幕嵌入视频 |
| ffkit_transcode | 转换格式、编解码器、分辨率、比特率 | 将 4K MP4 压缩为 720p WebM 用于网页 |

工作原理

你的智能体                    ff-toolkit                         FFmpeg
│                           │                              │
├─ openai_tools() ──────────┤                              │
│  或 anthropic_tools()     │                              │
│                           │                              │
├─ LLM 返回工具调用 ────────►│                              │
│                           │                              │
├─ dispatch(name, args) ───►├─ 验证并构建命令 ────────────►│
│                           │                              │
│◄── FFmpegResult ─────────┤◄── 子进程结果 ───────────────┤
│                           │                              │

项目结构

ff-toolkit/
├── src/ff_kit/
│   ├── __init__.py          # 公共 API：clip、merge、extract_audio、...
│   ├── cli.py               # CLI 入口点（ffkit 命令）
│   ├── executor.py          # FFmpeg 子进程运行器 + 探测
│   ├── dispatch.py          # 工具名称 → 函数路由器
│   ├── bridge.py            # 用于宿主运行时的一次性 JSON 桥接（stdin/stdout）
│   ├── core/                # 每个操作一个模块
│   │   ├── clip.py
│   │   ├── merge.py
│   │   ├── extract_audio.py
│   │   ├── add_subtitles.py
│   │   └── transcode.py
│   ├── schemas/             # LLM 工具定义
│   │   ├── openai.py        # OpenAI 函数调用格式
│   │   └── anthropic.py     # Anthropic 工具使用格式
│   └── mcp/                 # MCP 服务器（stdio JSON-RPC）
│       └── server.py
├── examples/
│   ├── local_example.py     # ← 先运行这个！无需 API 密钥
│   ├── openai_example.py
│   ├── anthropic_example.py
│   └── agent_loop_example.py
├── tests/                   # 49 个测试，全部模拟（无需 FFmpeg）
└── integrations/
└── deepseek-harness/    # dsh-ffkit npm 包（DeepSeek Harness 插件）

开发
bash
git clone https://github.com/inthepond/ff-toolkit.git
cd ff-toolkit
pip install -e ".[dev]"
pytest -v                    # 49 个测试，运行时间 <1 秒

常见问题

问：我需要安装 FFmpeg 吗？
是的，对于实际的媒体操作需要。测试完全模拟，不需要 FFmpeg。请从 ffmpeg.org/download 安装，或使用 brew install ffmpeg / apt install ffmpeg。

问：我可以添加自定义操作吗？
可以——在 core/ 中添加一个函数，在 dispatch.py 的 _REGISTRY 中注册它，并在 schemas/openai.py 和 schemas/anthropic.py 中添加 schema 条目。可以参考任何现有操作作为模板。

问：为什么不直接使用 LangChain / CrewAI 工具？
那些框架很棒，但它们是重量级依赖。ff-toolkit 是零依赖的（除 Python 标准库外），并且可与任何 LLM 提供商配合使用。如果你愿意，可以在 LangChain 中使用它，也可以独立使用。

问：流式传输 / 进度回调呢？
v0.1 中不支持。FFmpeg 进度解析计划在 v0.2 中实现。

许可证

MIT