# Video Material DB（视频素材语义数据库）

一个面向短视频研究与创作的本地优先知识库。它将视频、字幕和 AI 结构化分析统一保存到 PostgreSQL，并通过 Web 界面、REST API 与 MCP 工具提供自然语言检索。素材和分析数据默认保存在用户自己的运行环境中。

## 主要功能

- 从本地文件、文件夹或公开视频链接导入素材
- 采集抖音、TikTok、YouTube、B站等平台的博主视频列表
- 自动完成视频预处理、语音转写、关键帧提取与视觉分析
- 提取人物、场景、镜头、对白、剧情结构、笑点与改编建议
- 使用 pgvector 建立语义索引，按自然语言搜索视频、台词和剧情元素
- 通过 FastAPI Web 界面管理素材与后台任务
- 通过 MCP 接入 Codex 等 AI 工具
- 支持素材去重、异步处理、失败重试和批量导出

## 应用场景

- 短视频编剧查找剧情、台词、笑点、反转和镜头参考
- 内容团队建立可搜索的视频案例库与创意知识库
- 分析热门博主的内容结构、叙事节奏和视觉表达
- 从大量参考视频中寻找可复用的创作模式
- 为 AI 助手提供结构化、可追溯的视频研究资料

## 技术组成

- Python 3.11+
- FastAPI
- PostgreSQL + pgvector
- MCP Server
- ffmpeg / ffprobe
- 通义千问兼容接口（ASR、视觉分析与向量嵌入）

## 快速开始

完整安装步骤见 [INSTALL.md](INSTALL.md)。素材默认保存在项目下的 `./data` 本地目录。

```bash
python3 -m venv .venv
.venv/bin/pip install -e .
cp .env.example .env
```

启动数据库后，分别运行 Web 服务和后台分析任务：

```bash
.venv/bin/video-db-api
.venv/bin/video-db-worker
```

浏览器打开 <http://127.0.0.1:8000/>。

## MCP 接入

```bash
codex mcp add video-material-db -- <仓库绝对路径>/.venv/bin/video-db-mcp
```

可用工具包括 `add_video_url`、`add_local_video`、`search_videos`、`search_dialogue`、`search_jokes`、`search_story_structure` 和 `get_video_detail`。

## 数据与安全

公开仓库只包含通用程序源码。`.env`、API 密钥、视频文件、数据库内容、备份、本机路径及个人数据均不会进入版本控制。