kinocut

<p align="center"> <a href="https://kyanitelabs.tech"> <img src="assets/kinocut-hero.webp" alt="Kinocut - 为AI代理提供保障的视频编辑工具" width="100%"> </a> </p> <!-- mcp-name: io.github.KyaniteLabs/kinocut --> <h1 align="center">Kinocut</h1> <p align="center"> <strong>为AI代理提供保障的视频编辑MCP服务器。</strong><br> 为FFmpeg视频编辑、电影提示规划、媒体分析、字幕、音频、特效、Hyperframes视频创作、本地再利用包和预飞行验证提供结构化工具，帮助防止静默不良媒体输出。 </p> <p align="center"> <a href="https://pypi.org/project/kinocut/"><img src="https://img.shields.io/pypi/v/kinocut.svg" alt="PyPI"></a> <a href="https://git.kyanitelabs.tech/KyaniteLabs/kinocut/actions"><img src="https://img.shields.io/badge/Forgejo%20CI-actions-blue" alt="CI"></a> <img src="https://img.shields.io/badge/MCP-135%20tools-orange.svg" alt="135 MCP tools"> <img src="https://img.shields.io/badge/python-3.11%2B-blue.svg" alt="Python 3.11+"> <img src="https://img.shields.io/badge/license-Apache%202.0-blue.svg" alt="Apache 2.0"> </p> <p align="center"> <a href="#see-it-work">演示</a> &bull; <a href="#install">安装</a> &bull; <a href="#quick-start">快速开始</a> &bull; <a href="#what-agents-can-do">代理工作流</a> &bull; <a href="#tool-surface">工具</a> &bull; <a href="docs/TOOLS.md">工具参考</a> &bull; <a href="docs/RESCUE.md">视频救援</a> &bull; <a href="docs/AI_AGENT_DISCOVERY.md">AI发现</a> &bull; <a href="#agent-skill">代理技能</a> &bull; <a href="llms.txt">llms.txt</a> </p> --- ## See It Work 告诉代理你想要什么，用简单的语言： > "将这个采访剪辑到最强的45秒，加上烧录字幕，变成垂直的，并检查质量后再导出。" Kinocut将这个请求转换成键入的、受保护的工具调用 - 不需要猜测FFmpeg标志，不会静默地导出损坏的媒体： ```python from kinocut import Client video = Client() clip = video.trim("interview.mp4", start="00:02:15", duration="00:00:45") video.ai_transcribe(clip.output_path, output_srt="captions.srt") captioned = video.subtitles(clip.output_path, subtitle_file="captions.srt") short = video.resize(captioned.output_path, aspect_ratio="9:16") video.release_checkpoint(short.output_path) # thumbnail + quality gate before you publish ``` **人们使用它的三个原因** - **再利用** — 将一个录音变成字幕短视频、Reels和TikTok包，带有清单和审查工件。 - **播客和采访剪辑** — 找到最强段落，规范音频，添加章节，导出。 - **CI中的代理驱动媒体** — 从Claude Code、Cursor、Codex-style客户端或脚本重复、可审查地编辑。 ## Agent Workflow Engine 代理可以**计划、验证、渲染、恢复和证明**一个多步骤的本地视频作业，从一个JSON作业规范开始 - 通过MCP（`video_workflow_*`）、CLI（`workflow-*`）或Python客户端（`Client.workflow_*`）- 带有足够强的收据，让另一个代理或人类在渲染前后信任。 ```json { "schema_version": 1, "name": "captioned-vertical-short", "sources": { "hero": { "path": "input/hero.mp4" } }, "steps": [ { "id": "trim-hero", "op": "trim", "inputs": { "src": "@sources.hero" }, "params": { "start": 0, "duration": 6 }, "output": "@work/hero_trim.mp4" }, { "id": "vertical", "op": "resize", "inputs": { "src": "@work/hero_trim.mp4" }, "params": { "width": 1080, "height": 1920 }, "output": "@work/hero_vertical.mp4" }, { "id": "caption", "op": "add_text", "inputs": { "src": "@work/hero_vertical.mp4" }, "params": { "text": "Watch this", "position": "bottom-center" }, "output": "@outputs.master" } ], "outputs": { "master": { "path": "output/final.mp4" } } } ``` ```bash kino workflow-validate --spec job.json # cheap structural gate, no render kino workflow-plan --spec job.json --save-plan plan.json # dry-run op graph + hashes kino workflow-render --spec job.json --save-receipt receipt.json # execute + provenance receipt kino workflow-inspect --receipt receipt.json # read-only integrity re-check ``` 渲染收据记录每一步的输入/输出哈希、恢复光标和清理清单，所有路径都相对于工作空间： ```json { "receipt_kind": "workflow", "versions": { "mcp_video": "1.7.0", "ffmpeg": "8.1" }, "spec_hash": "sha256:be2f3a9b...", "steps": [ { "id": "trim-hero", "op": "trim", "status": "completed", "input_hashes": { "src": "sha256:3b976d49..." }, "output": "work/be2f3a9b-2effedb3/mcp_video_hero_trim.mp4", "output_hash": "sha256:00727499..." }, { "id": "caption", "op": "add_text", "status": "completed", "output": "output/final.mp4", "output_hash": "sha256:8633ad2a..." } ], "cleanup_manifest": { "cleaned": true, "policy": "clean-on-success" }, "resume_cursor": { "last_completed_step": "caption", "next_step": null }, "status": "completed", "render_determinism_scope": "spec/input/output hashes are deterministic; rendered bytes may vary across FFmpeg builds" } ``` `--all-variants` 发出一个声明的N个不同输出，而`--resume`继续一个失败的作业，保持其间产物（在更改规格时关闭失败保护）。完整的架构、`@ref`语法、变体、恢复和清理都在[docs/WORKFLOWS.md](docs/WORKFLOWS.md)中；一个可运行的规格在[examples/workflows/](examples/workflows/captioned-vertical-short/)中。 ## Dedicated Video Rescue 对于“修复这个剪辑”的请求，故事和时间线必须保持不变，请使用先审查的救援管道。计划并检查诊断，批准只有安全的修复ID，渲染，然后检查验证的包。源代码保持不变；主副本和通用共享副本始终经过验证；可选字幕保持在侧车。详见[docs/RESCUE.md](docs/RESCUE.md)，包括CLI、MCP、Python、取消、恢复和稳定错误。 ## Layered Compositing `composite-layers` / `video_composite_layers` 为需要多于两步叠加原语的代理添加了一个由规格驱动的有序层栈。它支持图像、视频和纯色层；法线alpha合成；每层不透明度；x / y放置；变换缩放；时间窗口；和遮罩/遮布alpha源 - 以及**全画布混合模式**（`multiply`，`screen`，`overlay`，`darken`，`lighten`）和**旋转**，并使用新的`pivot`参考点。 Dry-run计划和确定性的`layer_plan` v2收据捕获源、filtergraph和输出哈希。 ```bash kino composite-layers --spec layers.json --dry-run --save-layer-plan layer-plan.json kino composite-layers --spec layers.json -o out.mp4 --save-layer-plan layer-plan.json ``` ## Public Discovery **Kinocut** 是一个免费、开源的**Model Context Protocol (MCP) 服务器**、Python库和CLI，为AI代理提供真正的视频编辑界面。它封装了FFmpeg，PUSHING CREATION风格的规划、媒体分析、质量检查、字幕、音频生成、特效、Hyperframes渲染、本地再利用包和风险编辑参数的防护栏，位于结构化工具模式后面。 最佳搜索: - 视频编辑MCP服务器 - AI代理视频编辑 - FFmpeg MCP工具 - Claude Code视频编辑 - Cursor MCP视频工具 - Python视频编辑库 - 字幕自动化 - 短视频和短视频自动化 - 代理媒体管道 - 本地AI视频工作流 - Hyperframes视频创作 - YouTube短视频再利用 ## Why It Exists AI代理可以编写FFmpeg命令，但它们不应该猜测标志、解析脆弱的stderr或静默发布损坏的媒体。Kinocut为代理提供键入的操作、可检查的工具元数据、结构化结果、预飞行防护栏和质量检查点，以便视频工作流可以自动化和审查，而不会变成shell命令轮盘赌。 使用它时，您希望AI助手： - 修剪、合并、调整大小、裁剪、旋转、转码或导出视频； - 添加文本、字幕、水印、叠加层、滤镜、渐变、特效和过渡； - 提取音频、规范音频、合成音频、添加生成音频或创建波形图； - 检测场景、制作缩略图、生成故事板、比较质量并创建发布检查点； - 脚手架电影项目、读取STYLE_/NEG_块、解析故事板表格和扩展镜头提示； - 创建新的Hyperframes项目、检查渲染布局、捕获网站、生成本地语音、删除背景并使用FFmpeg工具进行后处理； - 将一个源视频再利用成垂直、水平和正方形本地交付包，并带有清单和审查工件； - 从Claude Code、Cursor、Codex-style客户端、脚本或CI驱动可重复的媒体工作流。 ## 安装 前提条件： [FFmpeg](https://ffmpeg.org/) 必须安装并在`PATH`上可用。 ```bash # macOS brew install ffmpeg # Ubuntu/Debian sudo apt install ffmpeg ``` 无需全局安装： ```bash uvx --from kinocut kino doctor ``` 或使用pip安装： ```bash pip install kinocut kino doctor ``` Hyperframes工具还需要Node.js 22+和可解析的Hyperframes CLI。安装/固定Hyperframes在活动Node包布局中，将`hyperframes`添加到`PATH`中，或设置`MCP_VIDEO_HYPERFRAMES_COMMAND`。 ### 我需要哪个额外功能？ 核心安装涵盖所有FFmpeg编辑工具。 可选功能作为额外功能提供 - 只需安装您使用的功能： | 您想要的 | 安装 | 大约额外大小 | | --- | --- | --- | | Speech-to-text 字幕（Whisper） | `pip install "kinocut[transcribe]"` | ~1 GB (torch) | | 图像分析（颜色、布局、对比度） | `pip install "kinocut[image]"` | ~50 MB | | 人声/乐器分离 | `pip install "kinocut[stems]"` | ~2 GB (torch + demucs) | | AI 提升 | `pip install "kinocut[upscale]"` | ~2 GB (Python ≤3.12) | | 程序音频/音乐工具 | `pip install "kinocut[audio]"` | ~30 MB (numpy) | | 所有AI功能 | `pip install "kinocut[ai]"` | 几个GB | 混合使用，例如 `pip install "kinocut[transcribe,image]"`。安装后运行`kino doctor` - 它报告哪些功能可用，缺少什么。 ### 从mcp-video升级 Kinocut在重命名窗口期间保留原始界面。 现有安装可以升级而不更改代码： ```bash pip install --upgrade mcp-video mcp-video doctor ``` `mcp-video==1.6.1` 是 `kinocut==1.7.0` 的元数据兼容安装程序。 `mcp_video`导入、`mcp-video`命令、`MCP_VIDEO_*`环境变量、`~/.mcp-video`数据目录、`mcp-video://`资源URI和现有收据密钥在至少Kinocut 1.8.x版本中保持支持。新集成应使用`kinocut`、`from kinocut import Client`和`kino`命令。 ## En español Kinocut是一个视频编辑MCP服务器，用于AI代理：135个结构化FFmpeg工具，用于剪辑、合并、字幕、混合音频、添加效果和再利用内容（短视频、Reels、TikTok），以及一个工作流引擎（`workflow`），它规划、验证、渲染、恢复和验证多步骤作业，并带有可验证的收据，以及检测风险参数的防护栏。 要求： [FFmpeg](https://ffmpeg.org/) 已安装并在`PATH`上可用。 ```bash # macOS brew install ffmpeg # Ubuntu/Debian sudo apt install ffmpeg # 安装和诊断 pip install kinocut kino doctor ``` 对于Claude Code： ```bash claude mcp add kinocut -- uvx --from kinocut kino ``` `kino doctor` 报告可用功能和缺少的内容。 完整文档为英文；主要错误消息为双语。 ## 快速开始 ### 先试试收据支持的证明 从此存储库的克隆中运行最小信心工作流： ```bash uv run --no-project --with kinocut python workflows/05-confidence-baseline/workflow.py uv run --no-project --with kinocut python workflows/benchmarks/run_confidence_benchmark.py``` 工作流生成一个微小的源剪辑，创建一个检查的垂直视频，运行质量/发布检查步骤，并写入`workflows/05-confidence-baseline/output/video_receipt.json`。 证明笔记存在于[`docs/proofs/`](docs/proofs/)中。 ### Claude Code ```bash claude mcp add kinocut -- uvx --from kinocut kino ``` ### Claude Desktop ```json { "mcpServers": { "kinocut": { "command": "uvx", "args": ["--from", "kinocut", "kino"] } } } ``` ### Cursor ```json { "mcpServers": { "kinocut": { "command": "uvx", "args": ["--from", "kinocut", "kino"] } } ``` 然后询问您的代理： > 将此采访剪辑成45秒的垂直剪辑，添加烧录字幕，规范音频，制作缩略图，并创建发布检查点后再导出。 ## 代理技能 Kinocut 在 [`skills/kinocut/SKILL.md`](skills/kinocut/SKILL.md) 中包含一个公共代理技能。 在兼容的代理主机中使用 `$kinocut` 时，您希望代理在MCP服务器、CLI和Python客户端之间进行选择，同时保留检查、编辑、验证和人工审查工作流。 ## Python 客户端 ```python from kinocut import Client editor = Client() clip = editor.trim("interview.mp4", start="00:02:15", duration="00:00:45") caption_file = "captions.srt" editor.ai_transcribe(clip.output_path, output_srt=caption_file) captioned = editor.subtitles(clip.output_path, subtitle_file=caption_file) vertical = editor.resize(captioned.output_path, aspect_ratio="9:16") checkpoint = editor.release_checkpoint(vertical.output_path) print(checkpoint["thumbnail"]) print(checkpoint["storyboard"]) ``` ## CLI ```bash kino info interview.mp4 kino trim interview.mp4 -s 00:02:15 -d 45 kino video-ai-transcribe clip.mp4 --output captions.srt kino subtitles clip.mp4 captions.srt kino resize clip.mp4 --aspect-ratio 9:16 kino video-quality-check clip.mp4 kino repurpose clip.mp4 --platforms youtube-shorts instagram-reel tiktok ``` ## What Agents Can Do | 工作流 | 示例提示 | | --- | --- | | 社交剪辑 | “将这个风景录音变成一个带有字幕的TikTok和YouTube Short。” | | 播客制作 | “找到最强段落，剪辑它，规范音频，添加章节，然后导出。” | | 产品演示 | “从截图、标题卡和语音创建短启动视频。” | | 电影规划 | “创建样式包和故事板，然后为生成渲染镜头提示。” | | 质量审查 | “比较这两个导出，制作缩略图，并标记视觉或音频问题。” | | 批量自动化 | “将此文件夹的剪辑转换为具有一致响度的网络友好MP4。” | | 代码创建视频 | “搭建一个Hyperframes合成，检查它，渲染它，然后添加字幕和水印。” | | 本地再利用 | “将此主剪辑变成垂直、水平和正方形本地交付包，带有缩略图和清单。” | ## MCP Tools kino 目前注册了 **135 个MCP工具**。下面的表格总结了文档化的核心类别；`search_tools`允许代理在不加载每个工具描述的情况下发现确切的操作。 | 类别 | 计数 | 亮点 | | --- | ---: | --- | | 核心视频编辑 | 32 | trim, merge, resize, crop, rotate, convert, overlays, subtitles, export, cleanup, templates, merge-compatibility guardrails | | 代理工作流引擎 | 4 | validate, plan, render, resume, inspect multi-step jobs with provenance receipts | | 专用救援 | 3 | diagnose, approve, render, verify, quarantine, and resume local content-preserving repairs | | 发布后规划 | 8 | semantic timelines/query, EDLs, visual transforms, restoration, composition, autopilot, explicit egress | | 电影创作 | 4 | project scaffold, style-pack parsing, storyboard parsing, shot prompt expansion | | AI辅助媒体 | 11 | transcription, scene detection, upscaling, stem separation, silence removal, color grading | | Hyperframes | 18 | init, preview, render, snapshots, inspect, catalog, website capture, local TTS, transcription, background removal, diagnostics, benchmark, post-process | | 再利用 | 2 | dry-run manifests, platform-ready variants, thumbnails, storyboards, release checkpoints | | 程序音频 | 7 | synthesize, compose, presets, effects, sequences, generated audio, spatial audio, mix-parameter guardrails | | 视觉效果 | 8 | vignette, glow, noise, scanlines, chromatic aberration, luma key, mask, shape mask, bounded filter parameters | | 过渡 | 3 | glitch, morph, pixelate | | 布局和运动 | 6 | grid, picture-in-picture, split-screen, animated text, counters, progress bars, auto-chapters, layout mismatch warnings | | 分析 | 8 | scene detection, thumbnail, preview, storyboard, quality compare, metadata, waveform, release checkpoint | | 图像分析 | 3 | extract colors, generate palettes, analyze product images | | 发现 | 1 | `search_tools` | ```python from kinocut import Client editor = Client() matches = editor.search_tools("subtitle") print(matches["tools"]) ``` 完整参考： [docs/TOOLS.md](docs/TOOLS.md) ## 安全工作流 对于自主代理，预期路径是检查、编辑、验证，然后请求人类审查发布工件： ```python from kinocut import Client client = Client() print(client.inspect("trim")) result = client.pipeline( [ {"op": "trim", "input": "source.mp4", "start": "00:01:00", "duration": "00:00:45"}, {"op": "add_text", "text": "Launch clip", "position": "top-center"}, {"op": "normalize_audio"}, {"op": "resize", "aspect_ratio": "9:16"}, {"op": "export", "quality": "high"}, {"op": "release_checkpoint"}, ], output_path="final-short.mp4", ) ``` 安全合约： - 媒体生成调用返回具有输出路径的结构化结果。 - 高风险编辑路径现在在 FFmpeg 执行前运行预飞行防护：过滤器边界、合并兼容性、音频混合音量/时间、叠加层/水印/色度不透明度和相似性、动画文本时间/溢出和网格/分屏不匹配警告。 - 分析和发现调用返回结构化的 JSON 报告。 - 通过 `search_tools()` 和 `Client.inspect()` 提供工具发现功能。 - 意外的关键字错误转换为可行的 `MCPVideoError` 指导。 - 未经 `video_quality_check`、`video_release_checkpoint` 和人工视觉/音频检查，不要发布代理生成的视频。 ## 文档 - [文档地图](docs/README.md) - [工具参考](docs/TOOLS.md) - [Python 客户端参考](docs/PYTHON_CLIENT.md) - [救援后规划](docs/POST_RESCUE_FEATURES.md) - [CLI 参考](docs/CLI_REFERENCE.md) - [AI 代理发现指南](docs/AI_AGENT_DISCOVERY.md) - [常见问题](docs/faq.md) - [llms.txt](llms.txt) ## 测试 开发验证位于 [docs/TESTING.md](docs/TESTING.md)。更改工具行为时，请保持公共表面、媒体工作流和安全检查的更新。 ## 开发 ```bash git clone https://git.kyanitelabs.tech/KyaniteLabs/kinocut.git cd kinocut python3 -m venv .venv source .venv/bin/activate pip install -e ".[dev]" pytest tests/ -v -m "not slow and not hyperframes" ``` ## 社区 - [贡献](CONTRIBUTING.md) - [行为准则](CODE_OF_CONDUCT.md) - [治理](GOVERNANCE.md) - [维护者](MAINTAINERS.md) - [安全](SECURITY.md) - [支持](SUPPORT.md) - [路线图](ROADMAP.md) - [变更日志](CHANGELOG.md) - [Forgejo 问题](https://git.kyanitelabs.tech/KyaniteLabs/kinocut/issues) ## 许可证 Apache 2.0。参见 [LICENSE](LICENSE)。 使用 [FFmpeg](https://ffmpeg.org/)、[Hyperframes](https://hyperframes.io/) 和 [Model Context Protocol](https://modelcontextprotocol.io/) 构建。 --- ## KyaniteLabs 的一部分 更多来自 [KyaniteLabs](https://kyanitelabs.tech)。相关项目： - **[Epoch](https://github.com/KyaniteLabs/Epoch)** — AI 代理的时间估计 MCP 服务器（PERT） - **[DialectOS](https://github.com/KyaniteLabs/DialectOS)** — 西班牙语方言本地化 MCP 服务器和 CLI - **[checkyourself](https://github.com/KyaniteLabs/checkyourself)** — AI 构建的代码的本地优先生产就绪检查 → 更多信息请访问 **[kyanitelabs.tech](https://kyanitelabs.tech)** --- 如果 Kinocut 对您有帮助，请 **[加星或关注它](https://git.kyanitelabs.tech/KyaniteLabs/kinocut)** — 它可以帮助其他代理构建者找到它。 由 **[Simon Gonzalez De Cruz](https://github.com/simongonzalezdc)** 构建 — 通过上面的公共个人资料链接提供前置部署/应用 AI 工程和合同工作。