使用说明

MCP转录本

概述

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

两个转录引擎

MCP Transcript支持两种转录引擎：

耳语（当地） -免费，完全在您的机器上使用OpenAI的Whisper模型运行
谷歌云语音转文本（云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之前，请确保您拥有以下内容：

必需

Python 3.10或更高版本
- 下载自 python.org
- 标准CPython发行版（来自python.org）
- 验证安装： python --version 或 python3 --version
FFmpeg
- 音频格式转换所需
- 视窗：从下载 ffmpeg.org 并添加到PATH
- macOS: brew install ffmpeg
- Linux: sudo apt install ffmpeg （Debian/Ubuntu）或 sudo dnf install ffmpeg （Fedora）
- 验证安装： ffmpeg -version
拥抱脸代币 （用于演讲者日记）
- 在以下网址创建免费帐户 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提供自动安装脚本，创建隔离的虚拟环境并安装所有依赖项。

视窗

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

install.bat

脚本将：

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

Linux/macOS

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

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：要转录的音频文件的路径

选项：

选项	简短	描述	默认
`--output`	`-o`	输出标记文件路径	`input_file.md`
`--engine`	`-e`	转录引擎： `whisper` （本地）或 `google` （云API）	`whisper`
`--model`	`-m`	Whisper型号尺寸： `tiny`, `base`, `small`, `medium`, `large-v2`, `large-v3`	`base`
`--google-api-key`		Google Cloud API密钥（用于Google引擎）	来自 `GOOGLE_API_KEY` env
`--language`	`-l`	音频语言（例如。， `en`, `es`, `fr`)	自动检测
`--no-diarize`		禁用扬声器日记	已启用
`--min-speakers`		预期的最小扬声器数量	自动
`--max-speakers`		预期的最大扬声器数量	自动
`--no-timestamps`		从输出中排除时间戳	包括
`--device`		计算设备： `auto`, `cpu`, `cuda` （仅耳语）	`auto`
`--hf-token`		拥抱日记的脸令牌	来自 `HF_TOKEN` env
`--verbose`	`-V`	带有调试信息的详细输出	关闭

示例：

# 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 ...：要转录的音频文件的路径

选项：

选项	简短	描述	默认
`--output-dir`	`-d`	所有成绩单的输出目录	与输入文件相同
`--engine`	`-e`	转录引擎： `whisper` 或 `google`	`whisper`
`--model`	`-m`	Whisper型号尺寸	`base`
`--no-diarize`		禁用扬声器日记	已启用

示例：

# 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

发动机选择指南

发动机	类型	速度	成本	最适合
`whisper`	本地	取决于硬件	免费	隐私、离线使用、长文件
`google`	云API	快速	每次使用付费	快速结果，短文件

选择发动机：

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

选型指南（Whisper发动机）

型号	尺寸	速度	精度	用例
`tiny`	约75 MB	最快	基本	快速草稿、测试
`base`	~150 MB	快速	良好	通用，默认
`small`	约500 MB	中等	较好	专业成绩单
`medium`	约1.5 GB	较慢	优秀	需要高精度
`large-v2`	约3 GB	慢速	最佳	最高质量
`large-v3`	约3 GB	慢速	最佳	最新，质量最好

推荐：从以下内容开始 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.

输出结构

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

配置

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

环境变量

变量	描述	示例
`MCP_TRANSCRIPT_ENGINE`	默认转录引擎	`whisper`, `google`
`GOOGLE_API_KEY`	Google Cloud API密钥（用于Google引擎）	`AIzaSy...`
`HF_TOKEN`	HuggingFace访问令牌（日记化所需）	`hf_xxxxxxxxxxxxx`
`MCP_TRANSCRIPT_MODEL`	默认Whisper型号尺寸	`base`, `small`, `medium`
`MCP_TRANSCRIPT_DEVICE`	默认计算设备	`auto`, `cpu`, `cuda`
`HUGGINGFACE_TOKEN`	的替代名称 `HF_TOKEN`	`hf_xxxxxxxxxxxxx`

设置环境变量

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支持所有常见的音频格式：

格式	扩展名	注释
MP3	`.mp3`	最常见的，良好的压缩
WAV	`.wav`	未压缩，质量最好
M4A	`.m4a`	苹果格式，压缩效果好
FLAC	`.flac`	无损压缩
OGG	`.ogg`	开放格式，压缩良好
WEB	`.webm`	Web音频格式

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

发展

设置开发环境

克隆存储库：

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

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

# Windows:
install.bat

# Linux/macOS:
./install.sh

激活虚拟环境：

# Windows:
.venv\Scripts\activate

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

安装开发依赖项：

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许可证是一种许可证，允许您：

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

条件是：

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

贡献

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

报告问题

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

检查问题是否已存在于问题章节
如果没有，请使用以下命令创建新问题：
- 问题的清晰描述
- 复制步骤（针对bug）
- 预期行为与实际行为
- 您的环境（操作系统、Python版本、音频格式）
- 错误消息或日志

提交变化

复刻仓库
创建要素分支： git checkout -b feature/your-feature-name
通过清晰、描述性的提交进行更改
添加新功能的测试
确保所有测试通过： pytest
格式代码： black src/mcp_transcript tests/
检查绒毛： ruff check src/mcp_transcript tests/
通过以下方式提交拉取请求：
- 变更说明
- 为什么需要改变
- 它是如何被测试的

开发指南

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

行为准则

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

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

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