Speechpulse

🎙️ SpeechPulse

语音情感理解 MCP 服务器

SpeechPulse 通过分析语音音频，利用韵律特征（音高、能量、节奏）来检测情感、评估紧迫性并识别讽刺。Lite 层级完全基于 Python 标准库构建，实现零机器学习依赖。

✨ 主要特性

• 🎭 情感检测：基于变异系数（CV）阈值识别 7 种情感（高兴、兴奋、愤怒、悲伤、疲惫、焦虑、中性）
• ⏱️ 紧迫性评估：基于说话模式进行 4 级紧迫性检测（低、中、高、紧急）
• 🙃 讽刺检测：通过对比文本情感与音频情感来识别讽刺
• 🚫 零机器学习依赖：Lite 层级仅使用 Python 标准库（无需 numpy/scipy/librosa）
• 🔌 MCP 兼容：通过 Model Context Protocol 暴露工具，可与 Claude Desktop 及其他 MCP 客户端集成

📦 安装指南

从 PyPI 安装（发布后可用）

pip install speechpulse

从源码安装

git clone https://github.com/sophieMiao/speechpulse.git
cd speechpulse
pip install -e ".[dev]"

🚀 快速开始

作为 MCP 服务器使用

将其添加到你的 MCP 客户端配置中（例如 Claude Desktop）：

{
  "mcpServers": {
    "speechpulse": {
      "command": "python",
      "args": ["-m", "speechpulse"],
      "env": {
        "SPEECHPULSE_TIER": "lite"
      }
    }
  }
}

作为 Python 库使用

from speechpulse.analyzer import SpeechAnalyzer

# Initialize analyzer
analyzer = SpeechAnalyzer()

# Analyze emotion
result = analyzer.analyze("path/to/audio.wav")
print(f"Primary emotion: {result['emotion']['primary']}")

# Assess urgency
urgency = analyzer.assess_urgency("path/to/audio.wav")
print(f"Urgency level: {urgency.level}")

# Detect sarcasm (requires text in Lite tier)
sarcasm = analyzer.detect_sarcasm(
    "path/to/audio.wav",
    text="这真是太棒了"
)
print(f"Is sarcastic: {sarcasm.is_sarcastic}")

# Full analysis
full = analyzer.full_analysis("path/to/audio.wav", text="我受够了！")
print(full['summary'])
print(full['interpretation'])

命令行用法

# Start MCP server with stdio transport (default)
python -m speechpulse

# Start with SSE transport
python -m speechpulse --transport sse --port 8080

# Enable verbose logging
python -m speechpulse -v

🔧 MCP 工具

analyze_audio

分析音频的情感和基础特征。

参数：

• audio_path（string，必填）：WAV 音频文件的路径
• text（string，可选）：用于上下文的转写文本

返回： 情感检测结果、说话人状态以及原始音频特征

assess_urgency

基于音频韵律评估紧迫程度。

参数：

• audio_path（string，必填）：音频文件的路径
• text（string，可选）：用于基于关键词的紧迫性检测的文本

返回： 紧迫性评分、级别以及判断依据

detect_sarcasm

通过对比文本情感与音频情感来检测讽刺。

参数：

• audio_path（string，必填）：音频文件的路径
• text（string，可选）：转写文本（推荐提供）

返回： 讽刺检测结果，包含置信度与指示项

full_analysis

执行完整分析（情感 + 紧迫性 + 讽刺）。

参数：

• audio_path（string，必填）：音频文件的路径
• text（string，可选）：转写文本

返回： 包含摘要与解读的完整分析结果

health_check

检查服务器健康状态与能力。

返回： 状态、版本、层级以及可用能力

🏗️ 项目架构

speechpulse/
├── types.py           # Core data types (AudioFeatures, EmotionResult, etc.)
├── config.py          # Configuration management
├── utils.py           # Audio loading and processing utilities
├── audio_features.py  # Feature extraction (pitch, energy, etc.)
├── emotion.py         # CV-based emotion rule engine
├── urgency.py         # Urgency assessment logic
├── sarcasm.py         # Sarcasm detection
├── analyzer.py        # Main analysis pipeline
├── server.py          # MCP server implementation
├── asr.py             # ASR stub (Standard/Pro tier)
└── ml_emotion.py      # ML emotion stub (Pro tier)

🔬 技术细节

音频处理

• 纯 Python：仅使用 wave、struct、math 和 array 模块
• 格式支持：8/16/24/32 位 PCM 的 WAV 文件
• 重采样：线性插值至 16kHz
• 分帧：32ms 帧长，50% 重叠，Hamming 窗

特征提取

• 音高（Pitch）：基于自相关的 F0 检测（50-500 Hz 范围）
• 能量（Energy）：逐帧 RMS 能量
• 过零率（Zero Crossing Rate）：浊音/清音判别
• 静音比（Silence Ratio）：停顿模式分析

情感识别

使用变异系数（CV = 标准差/均值）来规避性别偏差，同时保持区分能力：

# Example: Happy emotion rule (using coefficient of variation)
"happy": {
    "conditions": [
        ("pitch_cv", ">", 0.15),       # High pitch variation (lively)
        ("energy_mean", ">", 0.3),      # Moderate-high energy
        ("energy_cv", ">", 0.2),        # Energy fluctuation
    ],
    "weight": 0.8,
}

紧迫性评估

基于 5 个因素：

• 语速（快/中/慢）
• 音量（高/中/低）
• 音高变化（高/中/低）
• 停顿模式（少/正常/多）
• 关键词检测（当提供文本时）

🎚️ 服务层级

Lite 层级（当前）

• ✅ 基于规则的情感识别
• ✅ 韵律紧迫性评估
• ✅ 基于关键词的讽刺检测
• ✅ 纯 Python（无机器学习依赖）
• ❌ 无 ASR 功能（需手动提供文本）
• ❌ 仅支持 WAV 格式

Standard 层级（规划中）

• 基于 faster-whisper 的 ASR
• 更多音频格式支持（MP3、FLAC 等）
• 说话人分离（Speaker Diarization）

Pro 层级（规划中）

• Qwen2-Audio 集成
• 上下文感知的情感分析
• 更细腻的情感检测
• 实时流式处理

🛠️ 开发指南

环境搭建

# Clone repository
git clone https://github.com/sophieMiao/speechpulse.git
cd speechpulse

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

运行测试

# Run all tests
python -m pytest tests/

# Run specific test file
python tests/test_all.py

# Run integration tests
python tests/test_integration.py

演示

# Run demo script
python examples/demo.py

⚙️ 配置

环境变量：

⚠️ 局限性

1. Lite 层级进行讽刺检测时需提供文本：通过 text 参数提供转写文本
2. 仅支持 WAV 格式：其他格式需在分析前转换为 WAV
3. 基于规则的情感识别：更细腻的机器学习情感检测将在 Pro 层级提供
4. 针对中文/英文优化：完整的多语言支持将在 Pro 层级提供

🤝 贡献指南

1. Fork 本仓库
2. 创建功能分支（git checkout -b feature/amazing-feature）
3. 提交更改（git commit -m 'Add amazing feature'）
4. 推送分支（git push origin feature/amazing-feature）
5. 发起 Pull Request

📄 许可证

本项目基于 MIT 许可证授权 —— 详情请参阅 LICENSE 文件。

🙏 致谢

• 基于 MCP SDK 构建
• 灵感来源于语音情感识别中的韵律分析研究
• CV 方法基于性别公平的情感识别研究

💬 支持

• GitHub Issues：https://github.com/sophieMiao/speechpulse/issues

Made with ❤️ for voice emotion understanding