Video Transcriber

Video Transcriber MCP 🚀

基于 whisper.cpp（Rust）的高性能视频转录 MCP 服务

一个使用 whisper.cpp 转录 1000 多个平台视频的 Model Context Protocol（MCP）服务。使用 Rust 构建，实现卓越的性能和效率。

📦 安装

Homebrew（macOS/Linux）- 推荐

最简单的安装方式，包含所有依赖项：

brew install nhatvu148/tap/video-transcriber-mcp

此命令会自动安装二进制文件及所需依赖项（cmake、yt-dlp、ffmpeg）。

Cargo 安装

如果已安装 Rust：

cargo install video-transcriber-mcp

注意： 你需要手动安装依赖项：yt-dlp、ffmpeg、cmake

预构建二进制文件

从 GitHub Releases 下载：

# macOS (Intel)
curl -L https://github.com/nhatvu148/video-transcriber-mcp-rs/releases/latest/download/video-transcriber-mcp-x86_64-apple-darwin.tar.gz | tar xz
sudo mv video-transcriber-mcp /usr/local/bin/

# macOS (Apple Silicon)
curl -L https://github.com/nhatvu148/video-transcriber-mcp-rs/releases/latest/download/video-transcriber-mcp-aarch64-apple-darwin.tar.gz | tar xz
sudo mv video-transcriber-mcp /usr/local/bin/

# Linux (x86_64) — no ARM64 Linux build, see issue #13; use `cargo install`
curl -L https://github.com/nhatvu148/video-transcriber-mcp-rs/releases/latest/download/video-transcriber-mcp-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv video-transcriber-mcp /usr/local/bin/

# Windows: Download .zip from releases page

注意： 你需要手动安装依赖项：yt-dlp、ffmpeg

Claude Code 插件

一步安装 MCP 服务和 /transcribe 技能：

/plugin marketplace add nhatvu148/video-transcriber-mcp-rs
/plugin install video-transcriber@nhatvu148-tools

此插件会为你注册 MCP 服务，但不会安装二进制文件——请先运行上方的任一安装命令，确保 video-transcriber-mcp 位于 PATH 中。

🎯 为什么选择 Rust？

此版本使用 whisper.cpp（带 Rust 绑定的 C++ 实现），而非 Python 版 OpenAI Whisper：

优势	whisper.cpp（Rust）	OpenAI Whisper（Python）
性能	原生 C++ 速度	Python 解释器开销
内存	占用更低	内存使用量更高
启动	即时（<100ms）	较慢（模型加载约需 2-3s）
依赖项	独立二进制文件	需要 Python 和相关包
可移植性	单个二进制文件	需要 Python 环境

实际性能取决于硬件、视频时长和所选模型。

✨ 功能

• 🚀 使用 whisper.cpp（带 Rust 绑定的 C++）实现高性能转录
• 🎥 从 1000 多个平台下载视频（YouTube、Vimeo、TikTok、Twitter 等）
• 📂 转录本地视频文件（mp4、avi、mov、mkv 等）
• 🎤 100% 离线转录（优先保护隐私）
• 🎛️ 5 种模型大小（tiny、base、small、medium、large）
• 🌐 支持 90 多种语言
• 📝 支持多种输出格式（TXT、JSON、Markdown）
• 🔌 与 Claude Code 集成 MCP
• 🌐 双传输模式——stdio（本地）和 Streamable HTTP（远程）
• ⚡ 原生二进制文件——无需 Python 或 Node.js
• 💾 相较于 Python 实现，内存占用更低

⚡ 快速开始（使用 Taskfile）

最快的开始方式：

# 1. Install Task (if not already installed)
brew install go-task/tap/go-task

# 2. Complete setup (build + download model)
task setup

# 3. Run a quick test
task test:quick

# Done! 🎉

可用命令：

task setup           # Complete project setup
task test:quick      # Test with short video
task benchmark       # Run performance benchmark
task deps:check      # Check dependencies
task download:base   # Download base model
task help            # Show all commands

查看 Taskfile.yml 了解所有可用任务。

---

🌐 传输模式

服务支持两种传输模式：

Stdio 传输（默认）

用于配合 Claude Code 本地 CLI 的标准输入/输出传输。这是默认模式。

video-transcriber-mcp
# or explicitly:
video-transcriber-mcp --transport stdio

Streamable HTTP 传输

用于远程访问的 HTTP 传输。支持通过网络访问 MCP 服务。

# Start HTTP server on default port (8080)
video-transcriber-mcp --transport http

# Custom host and port
video-transcriber-mcp --transport http --host 0.0.0.0 --port 3000

远程 MCP 客户端配置：

使用 HTTP 传输时，请使用此 URL 配置 MCP 客户端：

{
  "mcpServers": {
    "video-transcriber-mcp": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

HTTP 传输的优势：

• 客户端无需本地安装
• 集中部署服务
• 自动更新（服务端）
• 更适合团队环境
• 兼容无服务器平台

CLI 选项

video-transcriber-mcp --help

Options:
  -t, --transport <TRANSPORT>  Transport mode [default: stdio] [possible values: stdio, http]
      --host <HOST>            Host address for HTTP transport [default: 127.0.0.1]
  -p, --port <PORT>            Port for HTTP transport [default: 8080]
  -h, --help                   Print help
  -V, --version                Print version

---

📦 从源代码手动构建

先决条件

1. Rust（Rust 2024 版需要 1.85+）

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. yt-dlp（用于下载视频）

# macOS
brew install yt-dlp

# Linux
pip install yt-dlp

# Windows
winget install yt-dlp.yt-dlp

3. FFmpeg（用于音频处理）

# macOS
brew install ffmpeg

# Linux
sudo apt install ffmpeg  # Debian/Ubuntu
sudo dnf install ffmpeg  # Fedora

# Windows
choco install ffmpeg

4. clang/libclang（whisper-rs-sys 使用 bindgen 构建 whisper.cpp，构建时需要 libclang）

# macOS: bundled with Xcode Command Line Tools

# Linux
sudo apt install libclang-dev  # Debian/Ubuntu
sudo dnf install clang-devel   # Fedora

# Windows: install LLVM (https://releases.llvm.org) and set LIBCLANG_PATH

从源代码构建

# Clone the repository
git clone https://github.com/nhatvu148/video-transcriber-mcp-rs.git
cd video-transcriber-mcp-rs

# Build the project
cargo build --release

# The binary will be at: target/release/video-transcriber-mcp-rs

下载 Whisper 模型

# Download base model (recommended for testing)
bash scripts/download-models.sh base

# Or download all models
bash scripts/download-models.sh all

模型存储在 ~/.cache/video-transcriber-mcp/models/

🚀 快速开始

MCP 服务（用于 Claude Code）

添加到 ~/.claude/settings.json：

选项 1：通过 GitHub Release 或 cargo install 安装：

{
  "mcpServers": {
    "video-transcriber-mcp": {
      "command": "video-transcriber-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

选项 2：从源代码构建：

{
  "mcpServers": {
    "video-transcriber-mcp": {
      "command": "/absolute/path/to/video-transcriber-mcp-rs/target/release/video-transcriber-mcp",
      "args": [],
      "env": {
        "RUST_LOG": "info"
      }
    }
  }
}

然后在 Claude Code 中使用：

基本转录（默认使用 base 模型）：

Please transcribe this YouTube video: https://www.youtube.com/watch?v=VIDEO_ID

使用指定模型进行转录：

Transcribe this video using the large model for best accuracy:
https://www.youtube.com/watch?v=VIDEO_ID

转录本地视频文件：

Transcribe this local video file: /Users/myname/Videos/meeting.mp4

使用指定语言进行转录：

Transcribe this Spanish video: https://www.youtube.com/watch?v=VIDEO_ID
(language: es, model: medium)

📊 性能

预期性能特征

基于社区提供的 whisper.cpp 与 OpenAI Whisper 基准测试：

转录速度（近似值，因硬件而异）：

• whisper.cpp 通常比 Python Whisper 快 2-6 倍
• 启动更快（无 Python 解释器开销）
• 内存占用更低（无 Python 运行时）

影响实际性能的因素：

• CPU：核心越多，处理越快
• 模型大小：Tiny 速度最快，Large 速度最慢，但准确度最高
• 视频时长：视频越长，耗时按比例增加
• 音频复杂度：清晰语音比嘈杂音频转录得更快

想要帮忙吗？

我们正在收集真实的基准测试数据！如果你运行了两个版本，请分享结果：

• 硬件规格（CPU、RAM）
• 测试的视频时长
• 使用的模型
• 每个版本所用的时间

请提交包含基准测试结果的问题，帮助改进本节内容！

🎛️ 模型对比

模型	速度	准确度	内存	使用场景
tiny	⚡⚡⚡⚡⚡	⭐⭐	~400 MB	快速草稿、测试
base	⚡⚡⚡⚡	⭐⭐⭐	~600 MB	常规用途（默认）
small	⚡⚡⚡	⭐⭐⭐⭐	~1.2 GB	更高准确度
medium	⚡⚡	⭐⭐⭐⭐⭐	~2.5 GB	高准确度
large	⚡	⭐⭐⭐⭐⭐⭐	~4.8 GB	准确度最高，速度最慢

🌍 支持的平台

得益于 yt-dlp，此工具支持 1000 多个视频平台，包括：

• 社交媒体：YouTube、TikTok、Twitter/X、Facebook、Instagram、Reddit
• 视频托管：Vimeo、Dailymotion、Twitch
• 教育平台：Coursera、Udemy、Khan Academy、edX
• 新闻媒体：BBC、CNN、NBC、PBS
• 以及 1000 多个平台！

📝 输出格式

对于每个视频，都会在 ~/Downloads/video-transcripts/ 中生成三个文件：

video-id-title.txt   # Plain text transcript
video-id-title.json  # JSON with metadata and timestamps
video-id-title.md    # Markdown with video info

输出示例

# How to Build Fast Software

**Video:** https://www.youtube.com/watch?v=example
**Platform:** YouTube
**Channel:** Tech Channel
**Duration:** 600s

---

## Transcript

The key to building fast software is understanding...

---

*Transcribed using whisper.cpp (Rust) - Model: base*

🔧 配置

环境变量

所有环境变量均为可选项。即使不设置任何变量，转录器也能正常工作；这些变量可启用身份验证、远程推理、AI 摘要和付费 HTTP API。

💡 转录文本的输出目录不是环境变量——请将 output_dir 传递给 transcribe_video 工具（默认为 ~/Downloads/video-transcripts）。输出文件的命名格式为 <video_id>-<title>.{txt,json,md}。

远程 MCP 访问（--transport http）

HTTP 传输仅响应 Host 标头位于允许列表中的请求。为防止 [DNS 重绑定][dns-rebinding]，默认仅允许本地回环地址（localhost、127.0.0.1、::1），因此已部署的实例会拒绝自身的公共主机名并返回 403，直到你将其添加到列表中：

# Comma-separated. Added on top of the loopback defaults, so local
# development and health checks keep working.
export MCP_ALLOWED_HOSTS=mcp.example.com,mcp.example.com:8080

# On Fly:
fly secrets set MCP_ALLOWED_HOSTS=your-app.fly.dev

本地使用时请勿设置此项——服务启动时会记录接受的主机，因此远程客户端遇到 403 时很容易诊断。

⚠️ 此设置控制的是可访问性，而非授权。任何能够访问该 URL 的人都可以调用这些工具，包括 transcribe_video；配置了远程 Whisper / OpenRouter 时，该工具会产生实际费用。请在公开部署前配置身份验证代理。

下载（yt-dlp cookies）

仅在下载有年龄限制或仅限会员观看的视频，或遇到 YouTube 的“登录以确认你不是机器人”验证时才需要。

# Option 1 (preferred on headless / Linux): a Netscape-format cookies file.
# Export it however you like — e.g. a QR-login flow — then point at it.
export YT_DLP_COOKIES=/path/to/cookies.txt

# Option 2: read cookies straight from a logged-in local browser.
# One of: chrome, brave, edge, firefox, safari, chromium, opera, vivaldi.
# Ignored when YT_DLP_COOKIES is set.
export YT_DLP_COOKIES_FROM_BROWSER=chrome

远程 Whisper（卸载转录任务）

# POST audio to a remote HTTP worker (e.g. a serverless GPU) instead of
# running whisper-rs locally. Endpoint must accept multipart {audio, model,
# language} and return JSON {transcript, segments[], language, duration_s}.
export REMOTE_WHISPER_URL=https://your-worker.example.com/transcribe

🧪 开发

构建

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Run tests
cargo test

# Run with logging
RUST_LOG=debug cargo run -- --url "https://youtube.com/watch?v=example"

项目结构

src/
├── main.rs           # CLI + transport selection (stdio / streamable HTTP)
├── lib.rs            # public API for embedders
├── mcp/              # MCP server: tool definitions and handlers
├── transcriber/      # the pipeline: yt-dlp → ffmpeg → whisper.cpp
├── embeddings.rs     # passage embeddings, used by `search_transcripts`
└── utils/            # paths

此 crate 仅包含转录流水线及其 MCP 接口。基于它构建的产品——REST API、账户、额度、付款、AI 摘要和图表——位于单独的私有 crate 中，并将此 crate 作为库依赖，因此，运行 cargo install video-transcriber-mcp 安装的是转录服务，而不是别人的 SaaS 后端。

🤝 贡献

欢迎贡献！请：

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 视情况添加测试
5. 提交拉取请求

🙏 致谢

• whisper.cpp - Whisper 的快速 C++ 实现
• whisper-rs - whisper.cpp 的 Rust 绑定
• yt-dlp - 支持 1000 多个平台的视频下载器
• OpenAI Whisper - 原始语音识别模型
• Model Context Protocol SDK - 用于 MCP 的 Rust SDK

🆚 与 TypeScript 版本的比较

我用 TypeScript 构建了原版 video-transcriber-mcp。以下是我用 Rust 重写它的原因：

方面	TypeScript 版本	Rust 版本
转录速度	10 分钟视频需 5 分钟	50 秒（快 6 倍）
内存使用量	~2 GB	~800 MB（减少 2.5 倍）
启动时间	~2 秒	<100 毫秒（快 20 倍）
二进制文件大小	不适用（Node.js 运行时）	约 8 MB，独立运行
依赖项	Node.js、Python、whisper	仅需 yt-dlp、ffmpeg
CPU 使用率	高（Python 开销）	更低（原生代码）

Rust 版本已可用于生产环境，效率也显著更高！

🔗 链接

• GitHub 仓库
• TypeScript 版本
• Model Context Protocol
• whisper.cpp

许可证

您可以选择以下任一许可证：

• MIT 许可证（LICENSE-MIT）
• Apache 许可证 2.0 版（LICENSE-APACHE）

由您选择。

贡献

除非您明确另行声明，否则您有意提交以纳入本作品的任何贡献（如 Apache-2.0 许可证所定义）均按上述方式采用双重许可，且不附加任何条款或条件。

---

用 Rust 构建 ❤️，实现极致性能

_{MCP 注册表所有权令牌 — crates.io 会移除 HTML 注释，因此此行必须保持可见：}

mcp-name: io.github.nhatvu148/video-transcriber-mcp