内容
# 剪辑目录
将您的**视频作品集**变成一个**可搜索的剪辑目录**，然后从中剪辑出**自然语言超级剪辑**，支持任意宽高比。剪辑目录从**本地文件夹**（或 Frame.io 项目）中导入已完成的作品，对场景进行拆分，生成每个镜头的剪辑，并使用视觉语言模型（描述、物体、动作、情绪、镜头类型、质量评分、商业类别、屏幕文本标记）对每个剪辑进行标记，可选地**使用 Whisper 转录对话/语音**，并将所有内容编目到 SQLite + FTS5 中。您可以用自然语言搜索它，并通过一个命令组装一个剪辑。整个流程都可以通过命令行界面、局域网 HTTP API 或 MCP 服务器进行操作。
## 快速入门
```bash
git clone <repo-url> 剪辑目录 && cd 剪辑目录
ffmpeg -version # ffmpeg 必须在 PATH 中（并且 Python >= 3.11）
pip install -e ".[mcp,transcribe]" # 核心 + MCP 服务器 + Whisper；添加 ，frameio 以获取 Frame.io 内容
cp .env.example .env # 添加您的 OpenRouter API 密钥（这是您需要的全部）
剪辑目录 ingest-local /path/to/your/portfolio # 场景检测 + 分割成剪辑
剪辑目录 analyze # 使用 VLM 标记每个剪辑
剪辑目录 transcribe # 使对话/语音可搜索（可选）
剪辑目录 supercut "史诗般的空中无人机" --aspect 9:16 --duration 15
```
将主文件组织为 `Brand/Project/file.mp4` — 子文件夹名称成为每个视频的上下文提示，可以提高 VLM 分析的准确性。重新运行导入操作是幂等的。
### 或使用 Docker
```bash
cp .env.example .env # 添加您的 OpenRouter API 密钥
mkdir -p 媒体 && cp your-videos/* 媒体/
docker compose up -d serve # 网页图形用户界面在 http://localhost:8787/
docker compose run --rm serve ingest-local /媒体
docker compose run --rm serve analyze
docker compose run --rm serve transcribe
```
容器使用 CPU x264 编码。对于 NVIDIA GPU 编码，请本地运行（编码器自动检测 NVENC）或使用 NVIDIA 容器工具包构建基于 CUDA ffmpeg 的容器。
## 架构
```
本地文件夹 ─┬─► 目录视频 (Frame.io 替代方案: 下载交付成果)
Frame.io ─────┘
└► PySceneDetect ──► 分割成每个镜头的剪辑 + 缩略图
└► VLM 分析 ──► 描述、物体、动作、情绪、镜头类型、
质量评分（0-10）、商业类别、has_text + 图形注释
└► Whisper 转录（可选） ──► 可搜索的对话/语音 per 剪辑
└► SQLite + FTS5 目录（全文可搜索）
└► 自然语言查询 ──► 选择最佳剪辑 ──► ffmpeg ──► 剪辑
```
每个剪辑都带有**视觉验证的 `has_text` 标志**（是否有添加的文本/图形叠加层？），因此剪辑可以排除屏幕上的文本 — 在 16:9 上布局的叠加层在裁剪到 4:5/9:16 时看起来很糟糕。剪辑默认使用 `clean_cuts`，扫描每个剪辑并从其最长的内部一致运行中剪辑，以躲避 PySceneDetect 错过的隐藏剪辑和边界杂乱。
## 命令
| 命令 | 功能 |
| --- | --- |
| `剪辑目录 ingest-local <文件夹>` | 目录本地文件夹下的每个视频，场景检测，分割成剪辑。不需要账户。 |
| `剪辑目录 ingest-url <网址...>` | 从 YouTube/Vimeo/任意 yt-dlp 站点下载视频，然后进行场景检测和分割。需要 `pip install -e ".[url]"`。 **仅导入您有权使用的内容** — 参见下面的注释。 |
| `剪辑目录 ingest` | 相同，但来源是 Frame.io 项目（下载已完成的交付成果）。 |
| `剪辑目录 analyze-both` | 使用两个 VLM 并行标记未分析的剪辑，从一个共享队列 (`VISION_MODEL` + `VISION_MODEL_2`)。 |
| `剪辑目录 transcribe` | Whisper 语音转文本 per 剪辑，使对话/语音可搜索（`pip install -e ".[transcribe]"`）。 |
| `剪辑目录 search "查询"` | 用自然语言对目录进行全文搜索（默认使用 LLM 查询扩展）。 |
| `剪辑目录 supercut "查询" --aspect 4:5` | 从最佳剪辑中构建快速剪辑。支持的宽高比：`4:5`、`9:16`、`16:9`、`1:1`。 |
| `剪辑目录 scene "简介"` | **场景设计器**：解析纯英文简介，应用电影语法规则集（镜头尺寸弧线、跳切避免、节奏曲线），从目录中为每个槽选定镜头，输出镜头列表 + 渲染剪辑。模板：覆盖、揭示、蒙太奇、动作、对话。 |
| `剪辑目录 serve` | 局域网 HTTP API + 网页图形用户界面，用于浏览、搜索和剪辑剪辑（绑定 `0.0.0.0:8787`）。 |
| `剪辑目录 serve-mcp` | MCP 服务器，允许局域网代理搜索 + 剪辑剪辑作为工具调用（绑定 `0.0.0.0:8765`）。 |
| `剪辑目录 status` | 显示流程进度（视频 / 剪辑 / 已分析计数）。 |
其他命令：`analyze`（单模型备用）、`compile`（目标时长剪辑）、`context`（每个视频的品牌/产品提示，使 VLM 更准确）。运行 `剪辑目录 --help` 获取所有选项。
> **网址导入 & 权利。** `ingest-url` 是一个基于 [yt-dlp](https://github.com/yt-dlp/yt-dlp) 的源中立下载器。您有责任只导入您有权使用的素材 — 您自己的上传内容、Creative Commons / 公共领域作品或授权的镜头素材。下载第三方内容可能会违反主机服务条款和版权；该工具不会对此进行监管。设置 `YTDLP_FORMAT` 以覆盖下载格式（默认：≤1080p MP4）。
## 适用于代理
该软件包旨在由代理而非人类驱动。
- **技能**: [`skills/frameio-clip-reels/SKILL.md`](skills/frameio-clip-reels/SKILL.md) — 完整的运行指南（导入 → 分析 → 精选 → 剪辑），包括实际生成优质剪辑的剪辑精选模式。从这里开始。
- **HTTP API** (`剪辑目录 serve`，`:8787`)：自描述 OpenAPI，位于 `/docs`。使用 `POST /api/cut` 剪辑，使用 `GET /api/search?q=...` 搜索，加上 `/api/outputs` 和 `/api/status`。网页图形用户界面位于 `/`。
- **MCP** (`剪辑目录 serve-mcp`，`:8765`)：添加 `http://<主机>:8765/mcp` 作为 HTTP MCP 服务器。工具：`search_clips`、`cut_reel`、`list_outputs`、`pipeline_status`。剪辑网址指向 HTTP 服务器，因此请同时运行 `serve`。
## 配置
所有设置都从项目本地的 `.env` 读取 — 复制 [`.env.example`](.env.example) 并填写。 对于本地文件夹导入，唯一需要的参数是视觉模型密钥 (`OPENROUTER_API_KEY`；`VISION_MODEL` / `VISION_MODEL_2` 以选择模型)。Frame.io V4 OAuth 设置 (`FRAMEIO_*`) 仅在 `剪辑目录 ingest` 时需要。 可选：`WHISPER_MODEL` / `WHISPER_LANGUAGE`（转录）、`CLIP_CATALOG_DATA_DIR`、`VIDEO_ENCODER`。
## 跨平台
支持 Windows、macOS 和 Linux。ffmpeg 编码器**自动检测**最佳可用加速器 (`h264_nvenc` → `h264_videotoolbox` → `h264_qsv` → `libx264`)；在 `.env` 中设置 `VIDEO_ENCODER` 以强制指定一个。`data/`（目录 + 媒体）和 `.env`（您的凭证）都被 gitignore — 没有本地或机密内容被提交。
