# video-summarizer

> Turn videos / audio / meeting recordings into structured transcripts & summaries — multi-backend ASR with auto-fallback, zero hard dependencies, and MCP support.

[![Python](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org)
[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
[![MCP Ready](https://img.shields.io/badge/MCP-ready-orange.svg)](src/video_summarizer/mcp_server.py)

对 [tmeet-skill](https://skillhub.cn)（腾讯会议专属）的二创与泛化：去掉对单一会议平台的强依赖，
做成**任意视频/音频都能用的总结工具**。同一个核心代码，既能当命令行工具跑，也能当 **MCP 服务器**
被 Claude / Cursor / WorkBuddy 等任意 AI 客户端直接调用。

---

## ✨ 特性

- **多后端 ASR，自动降级**：本地 Whisper → 阿里云百炼 → OpenAI，按可用性自动选；挂了无缝下一个。
- **零硬依赖**：没装 ffmpeg / whisper 也不崩，给出清晰安装指引。
- **外部转写直读**：已有 `.txt / .srt / .vtt`（含腾讯会议导出的转写）直接读，零依赖跑通。
- **结构化输出**：`transcript.txt`（纯文本）、`transcript.json`（带元数据）、`transcript.srt`（字幕）。
- **双形态**：命令行工具 + MCP 服务器，一份代码两种接入方式。
- **开闭原则**：新增 ASR 后端只需实现一个函数并注册，主流程一行不动。

## 🔧 支持的转写后端

| 后端 | 参数值 | 是否联网 | 成本 | 依赖 | 数据出境 |
|---|---|---|---|---|---|
| 本地 Whisper | `local` | 否（首下模型需网） | 免费 | `faster-whisper` + ffmpeg | 否（离线） |
| 阿里云百炼 | `aliyun` | 是 | 低 | `dashscope` + `DASHSCOPE_API_KEY` | 是（国内合规更稳） |
| OpenAI API | `openai` | 是 | 按量 | `openai` + `OPENAI_API_KEY` | 是 |
| 外部转写文件 | `--transcript` | 否 | 免费 | 无 | 否 |

`auto`（默认）顺序：`local → aliyun → openai`；都不行则提示用 `--transcript`。

## 📦 安装

```bash
git clone https://github.com/yangmiao3/video-summarizer.git
cd video-summarizer
pip install -r requirements.txt
```

> 核心逻辑零硬依赖；上面会一并装 `mcp` / `dashscope` / `openai` / `faster-whisper` 以便用满所有后端。
> 只想用"外部转写直读"的话，不装任何东西也能跑。

## 🚀 快速开始

```bash
# 1) 已有转写文件（如腾讯会议导出）→ 零依赖直读
python -m video_summarizer.pipeline 会议.mp4 --transcript 转写.txt

# 2) 直接丢视频/音频，自动选后端转写（需配好至少一个 ASR 后端 + ffmpeg）
python -m video_summarizer.pipeline 会议录制.mp4 --backend auto --language zh

# 3) 指定后端
python -m video_summarizer.pipeline lecture.m4a --backend aliyun --language zh
```

输出在源文件旁的 `<stem>_transcript/` 目录：`transcript.txt` / `transcript.json` / `transcript.srt`。
拿到转写后，交给任意 LLM（或你的总结 Skill）按模板生成**概览 / 章节 / 核心要点 / 行动项**即可。

## 🔌 作为 MCP 服务器使用（跨客户端复用）

```bash
pip install mcp
python -m video_summarizer.mcp_server
```

客户端配置（以 WorkBuddy 为例，编辑 `~/.workbuddy/mcp.json`）：

```json
{
  "mcpServers": {
    "video-summarizer": {
      "command": "python",
      "args": ["-m", "video_summarizer.mcp_server"]
    }
  }
}
```

配置后，AI 客户端就能直接调用 `transcribe_audio` / `summarize_video` / `list_backends` 三个工具。

## 📁 项目结构

```
video-summarizer/
├── README.md
├── LICENSE
├── requirements.txt
├── .gitignore
├── SKILL.md                      # 兼顾 WorkBuddy 技能用法
├── src/video_summarizer/
│   ├── __init__.py
│   ├── asr.py                    # 多后端转写（核心，开闭原则）
│   ├── pipeline.py               # 抽音频 + 转写 + 落盘（CLI 入口）
│   └── mcp_server.py            # MCP 封装（FastMCP）
├── assets/summary_template.md   # 总结模板
└── examples/sample_transcript.txt
```

## 🧩 扩展：加一个新后端（开闭原则演示）

只需在 `asr.py` 实现一个函数并注册，不用改任何主流程：

```python
def _try_my_backend(audio: Path, language: str) -> Transcript | None:
    key = os.environ.get("MY_KEY")
    if not key:
        return None
    # ... 调用你的 ASR ...
    return Transcript(text=..., segments=..., backend="my-backend")

BACKENDS["my"] = _try_my_backend   # 一行注册，transcribe() 自动支持 --backend my
```

## 📄 许可证

[MIT](LICENSE) —— 可自由用于学习与商业项目。