🎬 视频转文字工具

English | 中文

基于 FunASR 实现的高性能本地视频语音识别转录工具，支持智能语音活动检测和GPU加速。

🚀 性能亮点

⚡ 超高速度: GPU加速下，转录速度比实时播放快100倍以上
🎯 实测效果: 33分钟1080p视频，完整转录16,663字符，用时仅数分钟
🧠 智能优化: 自动检测最佳设备（Apple MPS/NVIDIA CUDA/CPU）
📏 智能分段: 基于FunASR内置VAD智能分段，支持任意长度视频
🎬 精准时间轴: 基于FunASR毫秒级时间戳，字幕与视频完美同步

功能特性

🎥 支持多种视频格式：MP4, AVI, MKV, MOV, WMV, FLV, WEBM, M4V
🗣️ 高精度语音识别，基于FunASR先进模型
🌍 多语言支持：中文、英文、日语、韩语、西班牙语、法语、德语、意大利语、葡萄牙语、俄语
📝 多种输出格式：纯文本、SRT字幕、VTT字幕、JSON
⏱️ 精准时间戳: 使用FunASR实时时间戳，告别估算时间，实现毫秒级同步
🚀 本地处理，保护隐私
💻 智能GPU加速：自动检测并使用CUDA、Apple MPS或CPU
🤖 智能VAD分段: 使用FunASR内置语音活动检测，在静音处智能切分
⚡ 动态批处理：根据音频时长自动优化处理参数

📦 快速开始

1. 克隆项目

git clone https://github.com/AfeiFun/ASR.git
cd ASR

2. 安装依赖

# 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate  # Linux/macOS
# 或者 venv\Scripts\activate  # Windows

# 安装依赖
pip install -r requirements.txt

3. 立即开始使用

# 基础转录
python main.py your_video.mp4

# 生成SRT字幕
python main.py your_video.mp4 -f srt

# 长视频高速处理
python main.py long_video.mp4 --batch-size 16

重要说明:

Apple Silicon Mac: PyTorch会自动支持MPS加速，无需额外配置

NVIDIA GPU用户: 如需CUDA加速，请先安装CUDA工具包，然后安装对应版本的PyTorch

# CUDA 11.8示例
pip install torch torchaudio --index-url https://download.pytorch.org/whl/cu118

CPU用户: 默认安装即可正常使用

使用方法

🚀 快速开始（推荐）

# 激活虚拟环境
source asr/bin/activate

# 智能GPU加速转录（自动检测最佳设备）
python main.py your_video.mp4

# 长视频智能处理（任意长度，自动VAD分段）
python main.py long_video.mp4 --batch-size 16

# 生成SRT字幕
python main.py video.mp4 -f srt -l zh -o 字幕.srt

基础用法

# 基础转录，输出文本
python main.py input.mp4

# 指定输出文件
python main.py input.mp4 -o output.txt

# 输出SRT字幕格式
python main.py input.mp4 -f srt

# 指定语言（中文）
python main.py input.mp4 -f srt -l zh

# 输出带时间戳的JSON格式
python main.py input.mp4 -f json --timestamps

# 保留提取的音频文件
python main.py input.mp4 --keep-audio

# 显示详细处理信息
python main.py input.mp4 --verbose

高级选项

# 使用特定模型
python main.py input.mp4 --model paraformer-zh

# 使用GPU加速（自动检测最佳设备）
python main.py input.mp4 --device auto

# 手动指定设备
python main.py input.mp4 --device mps    # Apple GPU
python main.py input.mp4 --device cuda   # NVIDIA GPU
python main.py input.mp4 --device cpu    # CPU

# 长视频智能分段处理
python main.py input.mp4 --batch-size 16

# 组合多个选项
python main.py input.mp4 -f srt -l zh --timestamps --verbose -o 字幕.srt

命令行参数

参数	说明	默认值
`input`	输入视频文件路径	必需
`-o, --output`	输出文件路径	自动生成
`-f, --format`	输出格式 (text/srt/vtt/json)	text
`-l, --language`	语言代码	auto
`--model`	ASR模型名称	SenseVoiceSmall
`--vad-model`	VAD模型名称	fsmn-vad
`--device`	计算设备 (cpu/cuda/mps/auto)	auto
`--timestamps`	输出时间戳信息	False
`--keep-audio`	保留音频文件	False
`--verbose`	显示详细信息	False
`--max-length`	VAD片段合并长度(秒)	30
`--batch-size`	批处理大小	8

支持的语言

auto - 自动检测
zh - 中文
en - 英语
ja - 日语
ko - 韩语
es - 西班牙语
fr - 法语
de - 德语
it - 意大利语
pt - 葡萄牙语
ru - 俄语

输出格式说明

1. 纯文本 (text)

这是转录的文本内容...

2. SRT字幕 (srt)

1
00:00:00,000 --> 00:00:02,000
嗯。

2
00:00:02,000 --> 00:00:10,400
大家好，这是我们在AI领域里面的第一期内容。

3
00:00:10,400 --> 00:00:17,600
呃，它应该是一个系列视频里面的第一期。

🎯 时间轴精度: 基于FunASR毫秒级实时时间戳，确保字幕与视频完美同步

3. VTT字幕 (vtt)

WEBVTT

00:00:00.000 --> 00:00:05.000
这是第一段字幕

00:00:05.000 --> 00:00:10.000
这是第二段字幕

4. JSON格式 (json)

{
  "success": true,
  "text": "完整的转录文本...",
  "language": "zh",
  "duration": 120.5,
  "segments": [...]
}

项目结构

ASR/
├── main.py              # 主程序入口
├── asr_transcriber.py   # ASR转录器类
├── video_processor.py   # 视频处理工具
├── requirements.txt     # 依赖包列表
├── README.md           # 项目说明
└── asr/                # Python虚拟环境

系统要求

Python 3.8+
内存: 建议4GB以上（长视频建议8GB+）
硬盘: 建议2GB以上可用空间（用于模型缓存）
网络: 首次运行需要下载模型

GPU加速支持

Apple Silicon Mac 🍎:
- 自动检测: M1/M2/M3芯片自动启用MPS加速
- 性能提升: 转录速度提升100倍以上
- 推荐配置: --batch-size 16 获得最佳性能
NVIDIA GPU 🚀:
- 要求: 需要安装CUDA和对应的PyTorch版本
- 超高性能: 支持更大批处理，速度更快
Intel Mac/其他平台 💻:
- 兼容性: 自动回退到CPU处理
- 优化建议: 使用较小的分段长度 --max-length 300

性能优化指南

🚀 获得最佳性能

Apple Silicon Mac用户:

python main.py video.mp4 --device auto --batch-size 16

NVIDIA GPU用户:

python main.py video.mp4 --device cuda --batch-size 32

长视频处理（2小时以上）:

python main.py long_video.mp4 --batch-size 8 --verbose

控制字幕片段长度:

python main.py video.mp4 --max-length 15 -f srt  # 15秒片段

📊 性能基准测试

设备类型	视频长度	转录时间	加速比
M2 MacBook Air	33分钟	~3分钟	100x+
Intel Mac	33分钟	~30分钟	10x
NVIDIA RTX 4090	33分钟	~1分钟	300x+

常见问题

1. 模型下载缓慢

模型文件较大，首次运行需要下载。可以使用国内镜像源或手动下载模型。

2. GPU加速不生效

检查设备设置：--device auto（推荐）
Mac用户确认是否为Apple Silicon芯片
NVIDIA用户检查CUDA安装

3. 长视频处理慢

✅ 已优化: 现使用FunASR内置智能VAD分段，无需手动设置
调整批处理大小：--batch-size 16（GPU用户可用更大值）
关闭其他应用程序释放内存

4. 转录精度不理想

确保音频质量良好
选择合适的语言设置
尝试不同的模型

5. 处理速度仍然较慢

确保使用了GPU加速：检查日志中的设备信息
调整批处理大小：GPU用户可尝试更大的值
考虑升级硬件：更多内存或更强的GPU

6. 字幕时间轴不准确

✅ 已修复: 现已使用FunASR实时时间戳，彻底解决时间同步问题
对于之前版本生成的字幕，建议重新转录获得精准时间轴
如仍有问题，请检查音频质量和语言设置

实测案例

📺 测试视频信息

文件: BiliBili视频，33分钟1080p
内容: AI技术分享，中文语音
设备: Apple M2 MacBook Air

🎯 转录结果

处理时间: 约3分钟（使用MPS加速）
转录字数: 16,663个字符
准确率: 95%+（包含标点符号和语气词）
时间戳精度: 毫秒级同步，字幕与视频完美对齐
特色功能:
- 🎯 实时时间戳输出，告别估算时间
- 🤖 智能VAD分段，在静音处自动切分
- 🚀 动态批处理优化，根据音频时长自适应
- 🎭 自动情感标记（NEUTRAL、HAPPY、ANGRY等）
- 🌍 多语言片段识别（中文、英文、韩语等）
- ✂️ 完整语义保持，精准句子分割

📝 转录样例

大家好，这是我们在AI领域里面的第一期内容。呃，它应该是一个系列视频里面的第一期。
那在这期列的视频当中呢，我主要是想分享一下我个人是如何认知AI小宇宙的...

🤖 MCP服务器（推荐）

本项目现已支持 Model Context Protocol (MCP) 服务器模式，可以直接在 Claude Code 或 Claude Desktop 中使用，支持从视频URL自动下载并转录！

MCP功能特性

🌐 URL直接转录: 支持 YouTube、Bilibili 等500+平台视频URL
📁 本地文件转录: 处理本地视频/音频文件
🎯 多格式输出: text、srt、vtt、json 格式
🤖 智能分段: 自动VAD语音活动检测 (5秒智能分段)
🚀 GPU加速: 自动检测最佳设备 (MPS/CUDA/CPU)
⚡ 高性能处理: 批处理大小600，优化转录速度
💾 文件持久保存: 自动保存下载的视频、音频和转录文件
📂 本地路径返回: 提供所有生成文件的完整本地路径

方法一：Claude Code 配置 (推荐)

如果你使用 Claude Code，配置非常简单：

安装MCP依赖:

# 激活虚拟环境
source asr/bin/activate

# 安装MCP依赖
pip install -r requirements_mcp.txt

添加MCP服务器:

# 替换为你的实际路径
PYTHON_PATH="/path/to/ASR/asr/bin/python"
SERVER_PATH="/path/to/ASR/mcp_server.py"

# 全局用户级别配置 (推荐)
claude mcp add asr-transcriber $PYTHON_PATH $SERVER_PATH --scope user

# 或者项目级别配置
claude mcp add asr-transcriber $PYTHON_PATH $SERVER_PATH

检查连接状态:
```
claude mcp list
```
应该显示：asr-transcriber: ✓ Connected

开始使用:

在 Claude Code 中直接对话：

"请转写这个视频：https://www.youtube.com/watch?v=xxxxx"
"转写这个B站视频并生成SRT字幕：https://www.bilibili.com/video/BVxxxxx"
"分析这个本地视频文件：/path/to/video.mp4"

方法二：Claude Desktop 配置

安装MCP依赖 (同上)
找到Claude Desktop配置文件:
- macOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json

编辑配置文件，添加以下内容：

{
  "mcpServers": {
    "asr-transcriber": {
      "command": "/path/to/ASR/asr/bin/python",
      "args": ["/path/to/ASR/mcp_server.py"],
      "cwd": "/path/to/ASR",
      "env": {
        "PYTHONPATH": "/path/to/ASR",
        "VIRTUAL_ENV": "/path/to/ASR/asr"
      }
    }
  }
}

⚠️ 重要: 请将 /path/to/ASR 替换为你的实际项目路径

重启Claude Desktop

MCP可用工具

工具名称	功能	参数
`transcribe_from_url`	从URL下载并转录	url, output_format, language
`transcribe_local_file`	转录本地文件	file_path, output_format, language
`get_video_info`	获取视频信息	url
`list_supported_languages`	列出支持的语言	-
`list_supported_platforms`	列出支持的平台	-
`get_output_formats`	获取输出格式说明	-

支持的视频平台

🔴 YouTube
📺 Bilibili
🐦 Twitter/X
📱 TikTok
📷 Instagram
👥 Facebook
🎬 Vimeo
📹 Dailymotion
还有更多...（500+平台）

MCP使用示例

基础转录:

"转写这个视频：https://www.youtube.com/watch?v=dQw4w9WgXcQ"

生成字幕:

"请将这个视频转录成SRT字幕格式：https://www.bilibili.com/video/BV1xx411c7mD"

多语言支持:

"转录这个英文视频并指定语言为英文：https://www.youtube.com/watch?v=xxxxx"

本地文件处理:

"转录这个本地音频文件：/path/to/audio.wav"

故障排除

常见问题

MCP服务器连接失败:
- 检查Python路径是否正确
- 确保虚拟环境已激活并安装了所有依赖
- 使用 claude mcp list 检查状态
转录失败:
- 确保yt-dlp已安装：pip install yt-dlp
- 检查网络连接
- 验证视频URL是否有效
GPU加速不工作:
- 确认设备支持（Apple Silicon或NVIDIA GPU）
- 检查PyTorch安装：python -c "import torch; print(torch.backends.mps.is_available())"

技术支持

FunASR项目：https://github.com/modelscope/FunASR
yt-dlp项目：https://github.com/yt-dlp/yt-dlp
Model Context Protocol：https://modelcontextprotocol.io/
问题反馈：请在项目Issue中提交

许可证

本项目基于MIT许可证开源。

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.gitignore		.gitignore
README.md		README.md
README_EN.md		README_EN.md
asr_transcriber.py		asr_transcriber.py
claude_desktop_config.json		claude_desktop_config.json
main.py		main.py
mcp_server.py		mcp_server.py
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
requirements_mcp.txt		requirements_mcp.txt
video_downloader.py		video_downloader.py
video_processor.py		video_processor.py

Folders and files

Latest commit

History

Repository files navigation

🎬 视频转文字工具

🚀 性能亮点

功能特性

📦 快速开始

1. 克隆项目

2. 安装依赖

3. 立即开始使用

使用方法

🚀 快速开始（推荐）

基础用法

高级选项

命令行参数

支持的语言

输出格式说明

1. 纯文本 (text)

2. SRT字幕 (srt)

3. VTT字幕 (vtt)

4. JSON格式 (json)

项目结构

系统要求

GPU加速支持

性能优化指南

🚀 获得最佳性能

📊 性能基准测试

常见问题

1. 模型下载缓慢

2. GPU加速不生效

3. 长视频处理慢

4. 转录精度不理想

5. 处理速度仍然较慢

6. 字幕时间轴不准确

实测案例

📺 测试视频信息

🎯 转录结果

📝 转录样例

🤖 MCP服务器（推荐）

MCP功能特性

方法一：Claude Code 配置 (推荐)

方法二：Claude Desktop 配置

MCP可用工具

支持的视频平台

MCP使用示例

故障排除

常见问题

技术支持

许可证

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages