✨ 功能特性

• 🎥 多平台支持：支持 YouTube、Bilibili、抖音、Apple Podcasts、SoundCloud 等 30+ 平台
• ⚡ 字幕优先架构：对有原生字幕的平台（如 YouTube）直接提取字幕文本，无需下载音频，速度大幅提升；无字幕时才回退到 Whisper 转录
• 🎬 原视频下载：转录的同时保留源视频。下载与转录并行进行，结果卡片内可直接预览播放，一键保存。走 Whisper 路径时音轨直接从这个视频里抽取，因此同一个视频只下载一次。只要文本时关掉「保留原视频」即可
• 📁 本地上传：支持拖放或选择文件 —— .txt（作为文稿直接进入后续管线）、.mp3、.mp4、.m4a、.wav、.webm、.mkv、.ogg、.flac。音视频经 FFmpeg 转码后由 Whisper 转录，优化、翻译、摘要流程与链接任务完全一致
• 🗣️ 智能转录：无字幕时使用 Faster-Whisper 进行高精度语音转文字
• 🤖 AI 文本优化：自动错别字修正、句子完整化和智能分段
• 🌍 多语言摘要：支持 11 种语言的智能摘要生成
• ⚙️ 条件式翻译：当所选摘要语言与转录语言不一致时，自动生成翻译
• 🔧 自定义 AI 模型：在页面中直接配置任意 OpenAI 兼容接口（OpenAI、OpenRouter、本地 LLM 等）—— 输入 API 地址和 Key，点击 Fetch 自动获取可用模型并选择
• 📡 实时进度：通过 SSE 推送实时状态，并用徽章标明本次走的是字幕模式还是 Whisper 模式
• 📱 移动适配：响应式布局，深色界面

📑 目录

• 快速开始
• 使用指南
• 在 Claude / Codex / 脚本中调用
• 接口说明
• 技术架构
• 配置选项
• 常见问题
• 支持的语言
• 性能提示
• 贡献指南

🚀 快速开始

环境要求

• Python 3.8+
• FFmpeg（链接音频提取、原视频合流、本地上传转码均需）
• 任意 OpenAI 兼容服务商的 API Key（OpenAI、OpenRouter 等）—— 可直接在页面 UI 中配置，无需服务器环境变量

安装方法

git clone https://github.com/wendy7756/AI-Video-Transcriber.git
cd AI-Video-Transcriber

chmod +x install.sh
./install.sh

git clone https://github.com/wendy7756/AI-Video-Transcriber.git
cd AI-Video-Transcriber

# 使用 Docker Compose（最简单）
cp .env.example .env
# 编辑 .env 设置服务端默认值（可选）
docker-compose up -d

# 或者直接使用 Docker
docker build -t ai-video-transcriber .
docker run -p 8000:8000 --env-file .env ai-video-transcriber

# 创建并启用虚拟环境（macOS 推荐，避免 PEP 668 系统限制）
python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

brew install ffmpeg                              # macOS
sudo apt update && sudo apt install ffmpeg       # Ubuntu/Debian
sudo yum install ffmpeg                          # CentOS/RHEL

# 如需服务端默认值可设置，否则直接在页面 AI Settings 面板中配置
export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"   # 任意兼容端点

启动服务

python3 start.py

服务启动后，打开浏览器访问 http://localhost:8000。

生产模式（推荐用于长视频） —— 禁用热重载，让 SSE 连接在 30–60+ 分钟的长任务中保持稳定：

python3 start.py --prod

source venv/bin/activate
export OPENAI_API_KEY=your_api_key_here                  # 可选：服务端默认值
# export OPENAI_BASE_URL=https://openrouter.ai/api/v1    # 可选：服务端默认值
python3 start.py --prod

📖 使用指南

1. 选择输入方式：链接或本地文件

• 视频/播客链接：在输入框粘贴 YouTube、Bilibili 等支持的平台链接
• 本地上传：将文件拖到虚线框内，或点击选择文件。点击同一个 Transcribe 按钮开始处理。上传与链接共用 POST /api/process-video（multipart 带 file 字段），便于反向代理只放行该路径时仍可使用上传

2. 选择处理选项

• 摘要语言 —— 摘要输出使用的语言
• 保留原视频 —— 默认开启。会下载源视频（≤720p），可在结果区预览和保存。只要文本时关掉它可以节省带宽和磁盘

3.（可选）配置 AI 模型 —— 点击 AI Settings 展开面板

• 填写 API Base URL（如 https://openrouter.ai/api/v1）和 API Key
• 点击 Fetch 自动拉取该服务商的可用模型列表，然后选择；留空则使用服务器默认模型
• 凭据保存在浏览器 localStorage 中，只会发往你自己指定的服务商

4. 开始处理 —— 点击 Transcribe。链接任务会显示当前模式徽章：

本地上传时：音视频先经 FFmpeg 转码再由 Whisper 转录；纯 .txt 文件不下载、不跑 Whisper，直接进入文本优化与摘要流程。

5. 查看结果

• 转录文本 和 智能摘要 标签页始终存在；当转录语言与所选摘要语言不一致时，会自动出现 翻译 标签页
• 每个标签页右侧都有独立的紫色下载图标，不切换标签也能直接下载对应文件
• Download original video 按钮位于标签栏右侧，下方是内嵌播放器，显示源文件及其大小

🤖 在 Claude / Codex / 脚本中调用

除了 Web 界面，项目还提供了无头入口，agent 和脚本可以在不启服务、不开浏览器的情况下 跑同一套管线。

命令行

venv/bin/python transcribe.py "https://www.youtube.com/watch?v=VIDEO_ID" --json
venv/bin/python transcribe.py talk.mp4 -l zh --no-video
venv/bin/python transcribe.py notes.txt --no-llm          # 无需 API Key

--json 会把机器可读结果打到 stdout，进度信息走 stderr。 退出码：0 成功，2 输入不合法，1 下载/转码失败。

Agent 的 AI 服务商配置

CLI/agent 场景推荐用环境变量配置 OpenAI 兼容服务商：

export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
export OPENAI_TRANSLATION_MODEL="gpt-4o"  # 可选

单次 CLI 调用也可以传 --api-key、--base-url 和 --model，但环境变量更安全， 因为 API key 不会直接留在 shell history 里。

Codex App plugin

仓库也内置了一个 skills-only Codex 插件：

.codex-plugin/plugin.json
skills/video-transcribe/SKILL.md

这个仓库根目录就是 plugin root。在 Codex App 中把这个目录作为本地插件导入或安装后， 新建任务并从 Plugins 中选择 AI Video Transcriber 即可。仓库带着插件文件不等于 已经自动安装；修改插件后需要刷新或重新安装插件，并新开任务让 Codex 重新加载 skill。 这个 skill 仍然包装上面的 CLI 管线，所以运行 Codex 的机器仍需准备好本仓库的 venv 和 ffmpeg。

Codex App 不会为这个 skills-only 插件自动生成项目专属的设置面板。想从 OpenRouter 切换到其他 OpenAI 兼容端点，需要更新 Codex 任务可见的环境变量，或让 Codex 在单次 运行 CLI 时传 --base-url / --model。

这个插件暂不把本地 stdio MCP 服务打包进去。如果希望 Codex 直接调用 transcribe_video MCP 工具，请按下面的方式单独注册 MCP server。

Claude Code skill

仓库内置 .claude/skills/video-transcribe/SKILL.md，在本目录下使用 Claude Code 时会 自动识别 —— 直接让它转录某个链接即可。想全局可用，把该目录复制到 ~/.claude/skills/。

MCP 服务（Claude Code、Claude Desktop、Codex）

项目内置的是可选的 stdio MCP server。它不会自动注册到各个客户端，需要每个客户端 配置一次。

pip install "mcp>=2.0"

# 在仓库根目录执行：
claude mcp add video-transcriber \
  -e OPENAI_API_KEY=your_api_key_here \
  -e OPENAI_BASE_URL=https://openrouter.ai/api/v1 \
  -- "$(pwd)/venv/bin/python" "$(pwd)/mcp_server.py"

codex mcp add \
  --env OPENAI_API_KEY=your_api_key_here \
  --env OPENAI_BASE_URL=https://openrouter.ai/api/v1 \
  video-transcriber -- "$(pwd)/venv/bin/python" "$(pwd)/mcp_server.py"

如果更喜欢手动编辑 Codex 配置，也可以写入 ~/.codex/config.toml：

[mcp_servers.video-transcriber]
command = "/abs/path/venv/bin/python"
args = ["/abs/path/mcp_server.py"]

[mcp_servers.video-transcriber.env]
OPENAI_API_KEY = "your_api_key_here"
OPENAI_BASE_URL = "https://openrouter.ai/api/v1"

Claude Desktop 则把同样的 command 和 args 加到 Claude Desktop 的 MCP 配置中：

{
  "mcpServers": {
    "video-transcriber": {
      "command": "/abs/path/venv/bin/python",
      "args": ["/abs/path/mcp_server.py"],
      "env": {
        "OPENAI_API_KEY": "your_api_key_here",
        "OPENAI_BASE_URL": "https://openrouter.ai/api/v1"
      }
    }
  }
}

后续如果要换服务商，就更新 MCP 客户端保存的环境变量，或移除后用新的 OPENAI_BASE_URL / 模型设置重新添加 MCP server；如果客户端会常驻 MCP 进程， 还需要重启或刷新客户端。

对外暴露一个工具 transcribe_video，返回转录、摘要、可选翻译、文件路径以及 no_speech 标记。可用 venv/bin/python mcp_server.py --selftest 验证服务端是否正常， 再用 claude mcp list 或 codex mcp list 检查客户端是否已经注册。

注意 no_speech：视频没有语音时，管线会完全跳过 LLM 并返回空文本。agent 应当 如实告知用户，而不是去猜内容 —— 把空文稿交给 LLM 会得到一段自信的虚构内容。

🔌 接口说明

所有接口与前端页面同源。

# 转录链接，同时跳过原视频下载
curl -X POST http://localhost:8000/api/process-video \
  -F "url=https://www.youtube.com/watch?v=VIDEO_ID" \
  -F "summary_language=zh" \
  -F "download_video=0"

🛠️ 技术架构

后端 —— FastAPI · yt-dlp（下载与字幕提取）· FFmpeg（音频提取、视频合流、上传文件转码为单声道 16 kHz）· Faster-Whisper（转录）· OpenAI 兼容接口（优化、翻译、摘要）

前端 —— 原生 HTML5/CSS3/ES6+ · Marked.js（Markdown 渲染）· Font Awesome（图标）· SSE 实时进度

处理流程

链接 ──┬─→ 探测字幕 ──有字幕──→ 解析 VTT/SRT ──────────────┐
       │                                                  │
       │   （若开启「保留原视频」，与下面并行）                 ├─→ 文本优化
       └─→ 下载原视频（≤720p）──→ 抽取音轨 ──→ Whisper ──────┘   → 翻译*
                                                              → 生成摘要
文件 ─→ FFmpeg 转码 ──→ Whisper ─────────────────────────────┘   → 展示结果
      （.txt 直接进入文本管线）                                  (* 语言不一致时)

项目结构

AI-Video-Transcriber/
├── backend/
│   ├── main.py             # FastAPI 应用、路由、任务编排
│   ├── pipeline.py         # Web/CLI/MCP 共用的纯函数（含无语音判定）
│   ├── video_processor.py  # yt-dlp：字幕、音频、原视频
│   ├── transcriber.py      # Faster-Whisper 转录
│   ├── summarizer.py       # 文稿优化 + 摘要
│   ├── translator.py       # 条件式翻译
│   └── llm_sanitize.py     # LLM 输出后处理（去除套话等）
├── static/
│   ├── index.html          # 页面结构与样式
│   └── app.js              # 前端逻辑、SSE、多语言
├── temp/                   # 生成的转录、摘要与媒体文件
├── Dockerfile
├── docker-compose.yml
├── .env.example
├── requirements.txt
├── install.sh
├── start.py                # 启动脚本（--prod 禁用热重载）
├── transcribe.py           # 无头命令行入口（agent、脚本、定时任务）
├── mcp_server.py           # MCP 服务，暴露 transcribe_video 工具
├── .codex-plugin/
│   └── plugin.json         # Codex App 插件清单
├── skills/
│   └── video-transcribe/   # 包装 CLI 的 Codex plugin skill
└── .claude/skills/
    └── video-transcribe/   # 包装 CLI 的 Claude Code skill

⚙️ 配置选项

环境变量

全部为可选项 —— 不配置也能运行，AI 凭据可直接在页面中填写。

Whisper 模型大小选项

所有尺寸均支持多语言，tiny–medium 另有英语专用版本。

🔧 常见问题

# 删除 7 天前生成的文件
find temp -type f -mtime +7 ! -name 'tasks.json' -delete

git clone https://github.com/wendy7756/AI-Video-Transcriber.git
cd AI-Video-Transcriber
cp .env.example .env      # 编辑以设置服务端默认值（可选）

docker-compose up -d      # 推荐

# 或手动构建运行
docker build -t ai-video-transcriber .
docker run -p 8000:8000 --env-file .env ai-video-transcriber

docker ps                                                    # 查看运行中的容器
docker logs ai-video-transcriber-ai-video-transcriber-1      # 查看日志
docker-compose down                                          # 停止服务
docker-compose build --no-cache                              # 修改后重新构建

# 减少内存占用
WHISPER_MODEL_SIZE=tiny

# 限制容器内存
docker run -m 1g -p 8000:8000 --env-file .env ai-video-transcriber

# 监控
docker stats ai-video-transcriber-ai-video-transcriber-1

curl -I https://www.youtube.com/     # 平台访问
curl -I https://openrouter.ai        # AI 服务商
docker pull hello-world              # Docker Hub

🎯 支持的语言

转录 —— 通过 Whisper 支持 100+ 种语言，自动检测语言。

摘要与翻译 —— 英语、中文（简体）、日语、韩语、西班牙语、法语、德语、意大利语、葡萄牙语、俄语、阿拉伯语。

界面 —— 中文与英文，可在右上角切换。

📈 性能提示

硬件要求

• 最低配置：4 GB 内存，双核 CPU
• 推荐配置：8 GB 内存，四核 CPU
• 理想配置：16 GB 内存，多核 CPU，SSD 存储

处理时间预估

以上数据基于关闭「保留原视频」。开启后，字幕模式任务的耗时主要取决于视频下载而非转录；由于下载与 AI 步骤重叠，实际增加的总时长通常明显小于下载本身所需的时间。

🤝 贡献指南

欢迎提交 Issue 和 Pull Request！

1. Fork 项目
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add some AmazingFeature'）
4. 推送到分支（git push origin feature/AmazingFeature）
5. 开启 Pull Request

致谢

• yt-dlp —— 强大的视频下载工具
• Faster-Whisper —— 高效的 Whisper 实现
• FastAPI —— 现代化的 Python Web 框架
• OpenAI —— 智能文本处理 API

📞 联系方式

如有问题或建议，请提交 Issue 或联系 Wendy。

🚀 体验完整功能 — sipsip.ai

本工具是 sipsip.ai 的开源部分。

完整产品提供更多功能：

• 📧 每日邮件简报 —— 关注你喜欢的创作者，每天早上收到 AI 整理的内容摘要
• ⚡ 随时转录和总结任意视频和播客
• 🌐 全功能支持多语言

免费开始使用 —— 无需绑定信用卡。

➡️ sipsip.ai

同一开发者的其他项目

• 要录视频的话，可以用这个 最好用的免费提词器：直接在浏览器使用或者下载app版本获得更好的使用体验。
• 想在 Pinterest 上获得增长的话，可以用 GetPinFast，帮产品拿到更多流量和转化。

⭐ 如果你觉得这个项目有帮助，请考虑给它一个 Star！