AI导哈

语音转文本工具

STT（语音转文本）工具支持通过麦克风录音或音频文件转录将用户语音输入转换为文本，实现AI与用户之间的双向语音通信。

  • by AuraFriday
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 AuraFriday/stt_mcp

使用说明

STT工具-语音转文本MCP工具

概述

STT（语音转文本）工具使AI代理能够通过麦克风录音或音频文件转录接收用户的语音输入。它是TTS工具的伴侣，实现了人工智能和用户之间的完全双向语音通信。

特性

  • 🎤 麦克风录音 -通过自动语音检测记录用户语音
  • 📁 文件转录 -转录现有的音频文件（mp3、wav、m4a、ogg、flac、webm）
  • 🔊 语音活动检测 -使用WebRTC VAD进行智能语音开始/结束检测
  • ☁️ 云转录 -OpenAI Whisper API实现最佳精度
  • 💻 本地转录 -离线/私人使用更快的耳语（如果CUDA不可用，则自动回退到CPU）
  • ⏱️ 灵活的超时 -配置整体、初始静音和语音后静音超时
  • 🔄 无限期等待 -永远等待用户响应（当用户不在时）
  • 🐛 调试功能 -将录音和成绩单保存到文件
  • 📦 自动安装 -首次使用时会自动安装依赖项

安装

无需手动安装！ 首次使用时会自动安装依赖关系：

依赖关系 安装时间 包
音响设备 第一 listen 或 list_input_devices 呼叫 sounddevice
numpy 第一个 listen 或 list_input_devices 呼叫 numpy
webrtcvad 第一 listen 或 list_input_devices 呼叫 webrtcvad-wheels
openai 首次云转录 openai
更快的耳语 第一 use_local_model: true 呼叫 faster-whisper

对于手动安装：

# Core dependencies
pip install sounddevice numpy webrtcvad-wheels

# Cloud transcription (OpenAI Whisper API)
pip install openai

# Local transcription (faster-whisper)
pip install faster-whisper

快速开始

基本语音输入

{
  "input": {
    "operation": "listen",
    "timeout_seconds": 60,
    "silence_timeout_seconds": 2.0,
    "tool_unlock_token": "<token>"
  }
}

无限期等待用户

非常适合用户可能不在的时候：

{
  "input": {
    "operation": "listen",
    "timeout_seconds": 0,
    "initial_silence_timeout_seconds": 0,
    "tool_unlock_token": "<token>"
  }
}

使用本地模型（不需要API密钥）

{
  "input": {
    "operation": "listen",
    "use_local_model": true,
    "local_model_size": "small",
    "tool_unlock_token": "<token>"
  }
}

转录文件

{
  "input": {
    "operation": "transcribe_file",
    "audio_file_path": "C:/recordings/meeting.mp3",
    "language": "en",
    "tool_unlock_token": "<token>"
  }
}

运营

操作 说明
readme 获取文档并解锁令牌
listen 从麦克风录制，直到演讲结束，然后转录
transcribe_file 转录现有音频文件
list_input_devices 列出带有ID的可用麦克风
stop_listening 停止活动录制会话
get_status 检查当前是否正在录制/处理

参数

记录参数

参数 类型 默认值 说明
timeout_seconds int 60 最大录制时间（0=不确定）
silence_timeout_seconds float 2.0 演讲后结束录制的静音持续时间
initial_silence_timeout_seconds int 30 第一个语音的最大等待时间（0=不确定）
min_speech_duration_seconds float 0.5 静音结束录制前的最小语音
input_device string null 麦克风设备ID或名称子字符串
vad_aggressiveness int 2 VAD敏感性0-3（较高=更具攻击性）

转录参数

参数 类型 默认值 说明
language string null 语言提示（ISO-639-1代码，如'en'、'es'、'fr'）
use_local_model bool false 使用本地更快的耳语而不是OpenAI
local_model_size string “base” 型号：微型、底座、小型、中型、大v3、涡轮增压
openai_api_key string null neneneba API密钥（如果不使用env/config）

调试参数

参数 类型 说明
save_audio_to_file string 将录制的音频保存为WAV的路径
save_transcript_to_file string 将成绩单另存为文本的路径

响应格式

成功转录

{
  "status": "success",
  "transcript": "Hello, this is what the user said.",
  "duration_seconds": 3.5,
  "language_detected": "en",
  "engine_used": "openai_whisper",
  "audio_saved_to": "C:/temp/recording.wav",
  "transcript_saved_to": "C:/temp/recording.txt"
}

超时（无发言）

{
  "status": "timeout",
  "message": "No speech detected within timeout period",
  "waited_seconds": 30
}

录制已停止

{
  "status": "stopped",
  "message": "Recording was stopped by user request"
}

获取状态响应

{
  "status": "recording",
  "is_recording": true,
  "session_id": "rec_1234567890",
  "elapsed_seconds": 5.2,
  "speech_detected": true
}

用例

1.交互式语音命令

{
  "input": {
    "operation": "listen",
    "timeout_seconds": 10,
    "silence_timeout_seconds": 1.5,
    "initial_silence_timeout_seconds": 5,
    "tool_unlock_token": "<token>"
  }
}

2.用户离开-等待返回

{
  "input": {
    "operation": "listen",
    "timeout_seconds": 0,
    "initial_silence_timeout_seconds": 0,
    "use_local_model": true,
    "tool_unlock_token": "<token>"
  }
}

代理可以通过TTS、弹出窗口或其他方式显示通知，表示它正在等待输入。

3.直接提供API密钥

{
  "input": {
    "operation": "listen",
    "openai_api_key": "sk-...",
    "timeout_seconds": 30,
    "tool_unlock_token": "<token>"
  }
}

4.调试录制问题

{
  "input": {
    "operation": "listen",
    "save_audio_to_file": "C:/temp/debug.wav",
    "save_transcript_to_file": "C:/temp/debug.txt",
    "tool_unlock_token": "<token>"
  }
}

转录引擎

OpenAI Whisper API（默认）

  • 准确度：同类最佳
  • 成本：约0.006美元/分钟
  • 语言：97+种语言
  • API关键来源 （按优先顺序）：
    1. openai_api_key 参数（直接在调用中）
    2. OPENAI_API_KEY 环境变量
    3. 配置文件(settings[0].api_keys.OPENAI_API_KEY)

本地更快的耳语

  • 隐私：没有数据离开您的机器
  • 成本：免费
  • 图形处理器：如果可用，自动使用CUDA，回退到CPU
  • 模型：微小（最快）→ base → 小→ 中等→ large-v3/turbo（最精确）
型号 参数 速度 精度
微小 39M 最快 适合快速命令
基础 74M 速度快 平衡性好
小 244M 中等 精度更好
中等 769M 较慢 精度高
large-v3 1550M 最慢 最佳精度
涡轮增压 809M 快速 优化的大型型号

语音活动检测

该工具使用WebRTC VAD进行智能语音检测：

  1. 等待：听取任何演讲以开始录制
  2. 录制：在检测到语音时捕获音频
  3. 静音检测：结束录制后 silence_timeout_seconds 沉默
Aggressiveness 0: Least aggressive (catches more speech, more false positives)
Aggressiveness 1: Moderate
Aggressiveness 2: Default (good balance)
Aggressiveness 3: Most aggressive (may miss soft speech)

平台支持

平台 状态 注释
Windows ✅ 完整 初级开发平台
macOS ✅ 支持 需要麦克风权限
Linux ✅ 支持 与PulseAudio/ALSA兼容

CUDA/GPU支持

本地转录引擎（更快的耳语）自动：

  1. 检查CUDA是否可用
  2. CUDA实际工作的测试
  3. 如果CUDA失败（例如，驱动程序不匹配），则回退到CPU

无需手动配置-它只是工作！

最佳结果提示

  1. 使用好的麦克风 -USB耳机或专用麦克风效果最佳
  2. 尽量减少背景噪音 -VAD有帮助，但安静的环境更好
  3. 说清楚 -语速正常，说话不要太快
  4. 设置适当的超时 -命令越短，听写越长
  5. 使用语言提示 -当您知道预期的语言时，可以提高准确性
  6. 使用“小”模型 -本地转录速度和准确性的最佳平衡

相关工具

  • TTS（chrome_browser） -用于与用户对话的文本转语音
  • 用户 -UI弹出窗口和通知
  • 系统 -系统级操作，包括音频设备管理

许可证

专有-©2025克里斯托弗·内森·德雷克。保留所有权利。

相关 MCP