MCP transcript

MCP转录本

概述

MCP Transcript是一个功能强大的命令行工具，可以将音频文件转换为格式良好的Markdown文档，并自动识别说话者。它基于最先进的语音识别模型，提供精确的转录和说话者日记（语音区分），非常适合会议笔记、访谈、播客和任何多人音频内容。

两个转录引擎

MCP Transcript支持两种转录引擎：

1. 耳语（当地） -免费，完全在您的机器上使用OpenAI的Whisper模型运行
2. 谷歌云语音转文本（云API） -使用Google的API进行基于云的快速转录

这两个引擎都通过pyannote.audio输出干净、可读的Markdown文件，其中包含时间戳和说话者标签，用于说话者检测。

特性

• 双引擎支持：在本地Whisper或Google Cloud Speech-to-Text API之间进行选择
• 高精度转录：由OpenAI的Whisper模型提供支持，具有多种尺寸选项（从小到大-v3）
• 云转录：快速谷歌云语音到文本API支持，以实现快速结果
• 演讲者日记：自动识别和标记音频中的不同扬声器
• 多种音频格式：支持MP3、WAV、M4A、FLAC、OGG和WEBM
• Markdown输出：生成具有元数据标头的干净、结构良好的Markdown
• 批处理：一次处理多个音频文件
• GPU加速：自动CUDA检测，处理速度更快（Whisper引擎）
• 可配置的时间戳：在输出中包含或排除时间戳
• 语言支持：自动检测或手动语言规范
• 交叉平台的：适用于Windows、macOS和Linux
• 隔离环境：在自己的虚拟环境中运行以避免冲突

先决条件

在安装MCP Transcript之前，请确保您拥有以下内容：

必需

1. Python 3.10或更高版本

- 下载自 python.org - 标准CPython发行版（来自python.org） - 验证安装： python --version 或 python3 --version

1. FFmpeg

- 音频格式转换所需 - 视窗：从下载 ffmpeg.org 并添加到PATH - macOS: brew install ffmpeg - Linux: sudo apt install ffmpeg （Debian/Ubuntu）或 sudo dnf install ffmpeg （Fedora） - 验证安装： ffmpeg -version

1. 拥抱脸代币 （用于演讲者日记）

- 在以下网址创建免费帐户 huggingface.co - 在以下位置生成访问令牌 huggingface.co/settings/tokens - 接受pyannote模型的条款： - 发音/扬声器发音-3.1 - pyannote/分割-3.0

可选的

• 支持CUDA的GPU：使用Whisper引擎进行更快的处理（需要CUDA工具包）
• Google Cloud API密钥：使用谷歌语音转文本引擎

- 从获取API密钥 谷歌云控制台 - 启用云演讲到文本API

• Internet连接：用于初始模型下载（Whisper）或API调用（Google）

快速开始

# 1. Clone or download the repository
git clone https://github.com/mcp-transcript/mcp-transcript.git
cd mcp-transcript

# 2. Run the installation script
# Windows:
install.bat

# Linux/macOS:
chmod +x install.sh
./install.sh

# 3. Set your HuggingFace token (required for diarization)
# Windows:
set HF_TOKEN=your_token_here

# Linux/macOS:
export HF_TOKEN=your_token_here

# 4. Transcribe your first audio file
# Windows:
mcp-transcript.bat recording.mp3 -o transcript.md

# Linux/macOS:
./mcp-transcript recording.mp3 -o transcript.md

安装

自动化安装

MCP Transcript提供自动安装脚本，创建隔离的虚拟环境并安装所有依赖项。

视窗

1. 打开命令提示符或PowerShell
2. 导航到项目目录
3. 运行安装脚本：

install.bat

脚本将：

• 检查Python版本兼容性
• 验证FFmpeg可用性
• 在中创建虚拟环境 .venv
• 安装所有Python依赖项
• 创建启动器脚本 mcp-transcript.bat
• 下载所需的ML模型

Linux/macOS

1. 打开终端
2. 导航到项目目录
3. 使脚本可执行并运行：

chmod +x install.sh
./install.sh

脚本将：

• 检查Python 3.10+的可用性
• 验证FFmpeg安装
• 在中创建虚拟环境 .venv
• 安装所有Python依赖项
• 创建启动器脚本 mcp-transcript
• 下载所需的ML模型

验证

安装后，验证一切正常：

# Windows:
mcp-transcript.bat --version

# Linux/macOS:
./mcp-transcript --version

您应该看到显示的版本号。

卸载

要完全删除MCP转录：

# Windows:
uninstall.bat

# Linux/macOS:
./uninstall.sh

这将删除虚拟环境和启动器脚本。

用法

基础转录

使用默认设置转录单个音频文件：

# Windows:
mcp-transcript.bat input.mp3 -o output.md

# Linux/macOS:
./mcp-transcript input.mp3 -o output.md

命令参考

transcribe -转录单个音频文件

mcp-transcript transcribe INPUT_FILE [OPTIONS]

论据：

• INPUT_FILE：要转录的音频文件的路径

选项：

示例：

# Basic transcription (uses default engine from .env or whisper)
mcp-transcript transcribe meeting.mp3

# Use Google Cloud Speech-to-Text API
mcp-transcript transcribe meeting.mp3 --engine google

# Use local Whisper with a larger model for better accuracy
mcp-transcript transcribe interview.wav --engine whisper -m large-v2 -o interview.md

# Specify language and speaker count
mcp-transcript transcribe podcast.m4a -l en --min-speakers 2 --max-speakers 3

# CPU-only processing without timestamps (Whisper)
mcp-transcript transcribe lecture.flac --device cpu --no-timestamps

# Disable diarization for single-speaker content
mcp-transcript transcribe monologue.mp3 --no-diarize

# Verbose mode for debugging
mcp-transcript transcribe audio.ogg -V

batch -一次处理多个文件

mcp-transcript batch FILE1 FILE2 FILE3 ... [OPTIONS]

论据：

• FILE1 FILE2 ...：要转录的音频文件的路径

选项：

示例：

# Process all MP3 files in current directory
mcp-transcript batch *.mp3

# Save all outputs to a specific directory
mcp-transcript batch meeting1.mp3 meeting2.mp3 -d transcripts/

# Use a larger model for batch processing
mcp-transcript batch *.wav -m medium

info -系统信息和诊断

mcp-transcript info

显示器：

• Python 版本
• FFmpeg可用性和版本
• CUDA/GPU状态
• HuggingFace令牌状态
• Google API关键状态
• 默认转录引擎

输出示例：

Python: 3.11.5
FFmpeg: Available
  ffmpeg version 6.0
CUDA: Available
  Devices: 1
  GPU: NVIDIA GeForce RTX 3080
HuggingFace Token: Set
Google API Key: Set
Default Engine: whisper

发动机选择指南

选择发动机：

• 耳语：最适用于对隐私敏感的内容、脱机环境或处理多个文件时（无API成本）
• 谷歌：最适合快速转录，当你没有强大的GPU时，或者偶尔使用

选型指南（Whisper发动机）

推荐：从以下内容开始 base 为了测试，请使用 small 或 medium 用于生产工作。

输出格式

MCP Transcript生成干净、结构良好的Markdown文件，格式如下：

示例输出

---
title: Transcript - meeting_recording
date: 2025-11-26
source: meeting_recording.mp3
duration: 00:15:32
speakers: 3
---

# Transcript: meeting_recording

**Duration:** 00:15:32
**Speakers:** Speaker 1, Speaker 2, Speaker 3
**Generated:** 2025-11-26 14:30:45

---

## Transcript

**[00:00:00] Speaker 1:**
Good morning everyone. Thank you for joining today's meeting. Let's start by reviewing last week's action items.

**[00:00:15] Speaker 2:**
Sure. I completed the analysis we discussed. The results are quite promising, showing a 20% improvement in efficiency.

**[00:00:35] Speaker 1:**
That's excellent news. Could you share more details about the methodology?

**[00:00:45] Speaker 2:**
Absolutely. We focused on three key areas: process optimization, automation, and resource allocation.

**[00:01:10] Speaker 3:**
I have some questions about the implementation timeline. How long do you estimate this will take?

**[00:01:20] Speaker 2:**
Based on our current resources, I'd estimate about six weeks for full deployment.

输出结构

1. YAML前体：元数据，包括标题、日期、源文件、持续时间和发言人数量
2. 标题段：供快速参考的摘要信息
3. 成绩单科：带有说话者标签的带时间戳的对话
4. 自动格式化：适当的间距、有规律的时间戳、清晰的说话者过渡

配置

MCP转录可以使用环境变量进行配置：

环境变量

设置环境变量

Windows（命令提示符）：

set HF_TOKEN=your_token_here
set MCP_TRANSCRIPT_MODEL=medium

Windows（PowerShell）：

$env:HF_TOKEN="your_token_here"
$env:MCP_TRANSCRIPT_MODEL="medium"

Linux/macOS：

export HF_TOKEN=your_token_here
export MCP_TRANSCRIPT_MODEL=medium

永久配置：

创建一个 .env 项目目录中的文件（复制自 .env.example):

# Transcription engine: whisper (local) or google (cloud API)
MCP_TRANSCRIPT_ENGINE=whisper

# Google Cloud API key (required for google engine)
GOOGLE_API_KEY=your_google_api_key_here

# HuggingFace token (required for speaker diarization)
HF_TOKEN=your_huggingface_token_here

# Whisper settings
MCP_TRANSCRIPT_MODEL=base
MCP_TRANSCRIPT_DEVICE=auto

重要提示： 这 .env 文件在 .gitignore 并且不会致力于版本控制。切勿公开共享您的API密钥。

支持的音频格式

MCP Transcript通过FFmpeg支持所有常见的音频格式：

所有格式都会自动转换为WAV进行处理，而不会造成质量损失。

发展

设置开发环境

1. 克隆存储库：

git clone https://github.com/mcp-transcript/mcp-transcript.git
cd mcp-transcript

1. 运行安装脚本（创建虚拟环境）：

# Windows:
install.bat

# Linux/macOS:
./install.sh

1. 激活虚拟环境：

# Windows:
.venv\Scripts\activate

# Linux/macOS:
source .venv/bin/activate

1. 安装开发依赖项：

pip install -e ".[dev]"

开发工具

该项目使用以下开发工具：

• pytest：测试框架
• 新冠肺炎：代码覆盖率报告
• 黑色：代码格式
• 颈毛：快速脱绒
• 米皮：静态类型检查

运行测试

# Run all tests
pytest

# Run with coverage report
pytest --cov=mcp_transcript --cov-report=html

# Run specific test file
pytest tests/test_transcriber.py

# Verbose output
pytest -v

代码质量

# Format code with black
black src/mcp_transcript tests/

# Lint with ruff
ruff check src/mcp_transcript tests/

# Type check with mypy
mypy src/mcp_transcript

项目结构

mcp_transcript/
├── src/mcp_transcript/       # Main package
│   ├── __init__.py          # Package initialization
│   ├── __main__.py          # Entry point
│   ├── cli.py               # Command-line interface
│   ├── transcriber.py       # Whisper integration
│   ├── google_transcriber.py # Google Speech-to-Text integration
│   ├── diarizer.py          # Speaker diarization
│   ├── audio.py             # Audio processing
│   ├── markdown.py          # Output generation
│   ├── config.py            # Configuration
│   └── utils.py             # Utilities
├── tests/                   # Test suite
│   ├── test_cli.py
│   ├── test_transcriber.py
│   ├── test_diarizer.py
│   └── test_data/          # Sample audio files
├── install.bat             # Windows installer
├── install.sh              # Linux/macOS installer
├── pyproject.toml          # Project configuration
└── README.md               # This file

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

MIT许可证是一种许可证，允许您：

• 将软件用于商业目的
• 修改软件
• 分发软件
• 私下使用软件

条件是：

• 必须包括许可和版权声明
• 软件按“原样”提供，不提供保修

贡献

欢迎投稿！以下是您可以提供帮助的方式：

报告问题

如果您遇到错误或有功能请求：

1. 检查问题是否已存在于 问题 章节
2. 如果没有，请使用以下命令创建新问题：

- 问题的清晰描述 - 复制步骤（针对bug） - 预期行为与实际行为 - 您的环境（操作系统、Python版本、音频格式） - 错误消息或日志

提交变化

1. 复刻仓库
2. 创建要素分支： git checkout -b feature/your-feature-name
3. 通过清晰、描述性的提交进行更改
4. 添加新功能的测试
5. 确保所有测试通过： pytest
6. 格式代码： black src/mcp_transcript tests/
7. 检查绒毛： ruff check src/mcp_transcript tests/
8. 通过以下方式提交拉取请求：

- 变更说明 - 为什么需要改变 - 它是如何被测试的

开发指南

• 遵循PEP 8风格指南（由黑色和褶边强制执行）
• 为所有公共函数和类编写文档字符串
• 为函数参数和返回值添加类型提示
• 保持测试覆盖率在80%以上
• 更新面向用户的更改文档
• 保持提交原子性和良好的描述

行为准则

• 尊重他人，包容他人
• 欢迎新来者并帮助他们做出贡献
• 注重建设性反馈
• 尊重不同的观点和经验

______________________________________________________________________

问题？ 打开问题或检查 文档.

需要帮助？ 请参阅 故障排除指南 或奔跑 mcp-transcript info 检查您的系统设置。