mcpField
M
media-transcriber

media-transcriber

github.com/43college创意与媒体2846 次安装7 周前更新
代码仓库

关于 media-transcriber

media-transcriber 是一款使用 OpenAI Whisper 将音视频转为带时间戳逐字稿的工具，适合需要整理录音或视频内容的人。它支持说话人识别和 Claude 标点恢复，并在首次运行时自动准备环境和模型。

主要功能

  1. 01转录多种音视频格式
  2. 02生成带时间戳的逐字稿
  3. 03支持说话人识别
  4. 04使用 Claude 恢复标点
  5. 05提供快速与质量模式
  6. 06首次运行自动安装依赖和模型

适用场景

  1. 01整理会议或访谈录音
  2. 02为视频生成带时间戳文本
  3. 03区分多人对话中的说话人
  4. 04快速预览音视频内容

MCP 相关

该项目描述的是本地命令行转录 skill，未说明 MCP 接口或 MCP 服务能力。

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/43college/43-agent-skills --skill media-transcriber

安装后在 Claude Code 中输入/media-transcriber确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

.gitignore
.gitkeep
config.json.template
README.md
SETUP.md
scripts/
transcribe.py

详细介绍

来自项目 README

media-transcriber — 音视频逐字稿转录

作者：43 COLLEGE 凯寓 (KAIYU) 出品 版本：v1.0

使用 OpenAI Whisper 将视频/音频文件转为带时间戳的逐字稿。支持说话人识别和 Claude 标点恢复。

第一次运行时会自动创建虚拟环境、安装依赖并下载 Whisper 模型（turbo 约 1.5GB），全程自动，无需手动配置。

重要：首次转录前必须提前告知用户——模型下载 + 依赖安装可能需要 5-15 分钟（取决于网速），期间终端可能长时间没有新输出，这不是卡死。务必在执行转录命令前向用户说明这一点，避免用户中途强制中断导致环境损坏。

如果运行报错缺少 ffmpeg 或需要配置说话人识别，读 SETUP.md 完成首次配置。

跨平台兼容

项目macOS / LinuxWindows
Pythonpython3python
路径分隔符/\
脚本路径${CLAUDE_SKILL_DIR}/scripts/transcribe.py${CLAUDE_SKILL_DIR}\scripts\transcribe.py

关于 ${CLAUDE_SKILL_DIR}：这是文档占位符，代表本 skill 的安装目录（通常是 ~/.claude/skills/media-transcriber/）。Claude 在 bash 里执行命令时会自动替换成实际路径，用户不要直接复制这串到终端——直接复制粘贴会因变量未定义而失败。要么把命令交给 AI 执行，要么自行替换成具体目录。

调用方式

质量模式（默认推荐）

带说话人识别 + Claude 标点恢复，适合正式内容沉淀。速度约为实时的 1/2（turbo 模型，CPU）。

# 预检环境和权限（推荐首次运行）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py --check

# 质量模式：说话人识别 + 标点恢复
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate

# 指定说话人数量（不指定则自动检测）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate --speakers 2

# 整个文件夹批量转录（质量模式）
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "/path/to/folder" --language zh --diarize --punctuate

# 强制覆盖已有逐字稿
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh --diarize --punctuate --overwrite

Python 内联调用：

import sys; sys.path.insert(0, f"{CLAUDE_SKILL_DIR}/scripts")
from transcribe import transcribe_file

transcribe_file("video.mp4", language="zh", diarize=True, punctuate=True)
快速模式

无说话人识别、无标点恢复，速度快 3-5 倍，适合快速预览内容。

# 快速模式：仅转录，无说话人，无标点
python3 ${CLAUDE_SKILL_DIR}/scripts/transcribe.py "video.mp4" --language zh

# Windows 快速模式
python ${CLAUDE_SKILL_DIR}\scripts\transcribe.py "C:\path\to\video.mp4" --language zh

环境信息

  • 虚拟环境: 首次运行自动创建在 skill 目录的 venv/
  • 模型存储: models/（本地化，不依赖系统缓存）
  • 自动安装: openai-whisper, numpy<2.4, numba, anthropic
  • 按需安装: pyannote-audio（仅 --diarize 时安装）
  • GPU: 无 CUDA 时自动回退 CPU

模型选择

模型大小CPU 速度中文质量场景
turbo1.5GB~2x 实时优秀默认推荐
medium1.4GB~3x 实时良好turbo 备选
small461MB~1x 实时一般追求速度
base139MB~0.3x 实时较差快速预览

"Nx 实时" = 1 分钟音频需 N 分钟处理（CPU）

输出格式

每个文件生成 <原文件名>_逐字稿.txt：

无说话人识别（默认）：

# 文件名

[00:00 - 00:05] 文本内容
[00:05 - 00:12] 文本内容

---

# 完整文本

完整的文本内容。

有说话人识别（--diarize）：

# 文件名

**[说话人A]**
[00:00 - 00:05] 文本内容

**[说话人B]**
[00:05 - 00:12] 文本内容

---

# 完整文本

[说话人A] 第一段话内容。
[说话人B] 第二段话内容。

支持格式：.mp4 .mkv .avi .mov .wmv .flv .webm .mp3 .wav .flac .aac .ogg .m4a .wma

关键设计

  • 自动 bootstrap: 首次运行自动创建 venv 并安装依赖，之后直接用 python3 调用即可，无需 activate
  • 防幻觉: condition_on_previous_text=False 阻止错误传播 + ffprobe 时长过滤超时段落
  • 标点引导: 指定 --language zh 时自动注入 initial_prompt 引导标点输出
  • Claude 标点恢复: --punctuate 调用 Claude Haiku 对全文做整体标点恢复
  • 说话人匹配: 按时间重叠量将 Whisper 片段匹配到 pyannote 说话人段落
  • 按需安装: pyannote-audio 体积大，仅在使用 --diarize 时自动安装
  • 模型本地化: Whisper 模型存放在 models/ 目录，通过 download_root 加载

已知限制

  1. NumPy 版本: numba 需要 numpy<2.4，已在自动安装时固定版本
  2. 长视频内存: 超 2 小时视频 turbo 模型约需 4-6GB RAM
  3. 背景音乐: 末尾纯音乐段可能残留少量误识别
  4. 说话人识别精度: 多人同时说话时准确率下降
  5. 标点恢复速度: Claude API 调用约 3-10 秒延迟

评论

支持 Markdown