Agent Voice Hub

Name: Agent Voice Hub
Rating: 3.5 (1 reviews)
Author: gancnmd

By gancnmd 👁 69 views ▲ 0 votes

Voice interaction plugin for AI agents (Hermes, OpenClaw) - TTS, STT, voice cloning, security scanning

GitHub

Install

pip install agent-voice-hub

Configuration Example

# 方式二：通过 YAML 配置注册
# ~/.hermes/skills/voice-hub.yaml
name: voice-hub
description: AI 语音处理技能
commands:
  speak:
    handler: agent_voice_hub.integrations.hermes:speak
    args:
      text: { type: string, required: true }
      voice: { type: string, default: "zh-CN-XiaoxiaoNeural" }
  listen:
    handler: agent_voice_hub.integrations.hermes:listen
    args:
      audio_path: { type: string, required: true }

README

<div align="center">

# 🎙️ Agent Voice Hub

[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![GitHub Stars](https://img.shields.io/github/stars/gancnmd/agent-voice-hub?style=social)](https://github.com/gancnmd/agent-voice-hub)

**中文：AI 智能体语音中枢 — 一站式 TTS / STT / 声音克隆 / 代码安全扫描平台**
**English: All-in-one TTS / STT / Voice Cloning / Code Security Scanner for AI Agents**

</div>

---

## ✨ 功能特性 (Features)

| 状态 | 模块 | 说明 |
|:---:|------|------|
| ✅ | **TTS 文本转语音** | Edge-TTS（免费，300+ 音色）+ Coqui XTTS（声音克隆） |
| ✅ | **STT 语音转文本** | faster-whisper，支持 99 种语言，自动检测语种 |
| ✅ | **声音克隆** | Coqui XTTS v2 零样本克隆，仅需 6-30 秒参考音频 |
| ✅ | **安全扫描器** | 46 种漏洞模式（命令注入、SQLi、XSS、硬编码密钥等） |
| ✅ | **智能体集成** | Hermes Skill / OpenClaw Plugin / 通用 REST API |
| ✅ | **CLI 工具** | speak / listen / scan / voices / clone 五大命令 |
| ✅ | **YAML 配置** | 灵活的 YAML 配置文件驱动 |

---

## 🏗️ 架构概览 (Architecture)

```
┌─────────────────────────────────────────────────────────────┐
│                    🎙️ Agent Voice Hub                       │
├──────────┬──────────┬──────────────┬────────────────────────┤
│  CLI 层  │ API 层   │  Agent 集成层 │     配置层 (YAML)      │
│ speak    │ REST API │  Hermes      │   config.yaml          │
│ listen   │ WebSocket│  OpenClaw    │                        │
│ scan     │          │  Generic     │                        │
│ voices   │          │              │                        │
│ clone    │          │              │                        │
├──────────┴──────────┴──────────────┴────────────────────────┤
│                     核心引擎 (Core Engine)                    │
├──────────────┬───────────────┬──────────────────────────────┤
│  TTS Engine  │  STT Engine   │   Security Scanner           │
│  ┌─────────┐ │ ┌───────────┐ │   ┌────────────────────┐    │
│  │Edge-TTS │ │ │  faster-  │ │   │ 46 vulnerability   │    │
│  │(免费)    │ │ │  whisper  │ │   │ patterns           │    │
│  ├─────────┤ │ │(99 languages│ │   │ Python/JS/Shell   │    │
│  │Coqui    │ │ └───────────┘ │   └────────────────────┘    │
│  │XTTS v2  │ │               │                              │
│  │(克隆)    │ │               │                              │
│  └─────────┘ │               │                              │
└──────────────┴───────────────┴──────────────────────────────┘
```

---

## 📦 安装 (Installation)

### 从 PyPI 安装

```bash
pip install agent-voice-hub
```

### 从源码安装

```bash
git clone https://github.com/gancnmd/agent-voice-hub.git
cd agent-voice-hub
pip install -e .
```

### 安装可选依赖

```bash
# 声音克隆功能（需要 GPU）
pip install agent-voice-hub[clone]

# 完整安装（所有功能）
pip install agent-voice-hub[all]
```

---

## 🚀 快速开始 (Quick Start)

### CLI 命令行

```bash
# 文本转语音 — 中文
agent-voice speak "你好世界" --voice zh-CN-XiaoxiaoNeural --output hello.mp3

# 文本转语音 — 英文
agent-voice speak "Hello World" --voice en-US-AriaNeural --output hello.mp3

# 语音转文本
agent-voice listen audio.mp3 --language zh --output transcript.txt

# 自动检测语种并转写
agent-voice listen audio.mp3 --auto-detect

# 查看可用音色
agent-voice voices --language zh-CN

# 代码安全扫描
agent-voice scan ./src --format json --output report.json

# 声音克隆
agent-voice clone --ref-audio speaker.wav --text "这是克隆的声音" --output cloned.mp3
```

### Python API

```python
from agent_voice_hub import TTS, STT, SecurityScanner

# ========== TTS 文本转语音 ==========
tts = TTS(engine="edge-tts")

# 中文语音合成
tts.speak(
    "欢迎使用 Agent Voice Hub",
    voice="zh-CN-XiaoxiaoNeural",
    output="welcome.mp3"
)

# 英文语音合成
tts.speak(
    "Welcome to Agent Voice Hub",
    voice="en-US-AriaNeural",
    output="welcome_en.mp3"
)

# 列出中文音色
voices = tts.list_voices(language="zh-CN")
for v in voices:
    print(f"{v['name']} — {v['gender']}")


# ========== STT 语音转文本 ==========
stt = STT(engine="faster-whisper")

# 自动检测语种
result = stt.transcribe("audio.mp3", auto_detect=True)
print(f"语种: {result.language}, 置信度: {result.confidence}")
print(f"文本: {result.text}")

# 指定语种
result = stt.transcribe("audio.mp3", language="zh")


# ========== 安全扫描 ==========
scanner = SecurityScanner()

# 扫描目录
report = scanner.scan("./src")
print(f"发现 {report.total_issues} 个安全问题")

for issue in report.issues:
    print(f"[{issue.severity}] {issue.file}:{issue.line} — {issue.description}")
```

---

## 🤖 智能体集成 (Agent Integrations)

### Hermes Skill

```python
# 在 Hermes 智能体中使用 voice-hub skill

# 方式一：直接调用
from agent_voice_hub.integrations import hermes_skill

@hermes_skill
def voice_assistant(text: str, action: str = "speak"):
    """语音助手技能 — 支持 TTS/STT/扫描"""
    if action == "speak":
        return tts.speak(text, voice="zh-CN-XiaoxiaoNeural")
    elif action == "listen":
        return stt.transcribe(text)
    elif action == "scan":
        return scanner.scan(text)
```

```yaml
# 方式二：通过 YAML 配置注册
# ~/.hermes/skills/voice-hub.yaml
name: voice-hub
description: AI 语音处理技能
commands:
  speak:
    handler: agent_voice_hub.integrations.hermes:speak
    args:
      text: { type: string, required: true }
      voice: { type: string, default: "zh-CN-XiaoxiaoNeural" }
  listen:
    handler: agent_voice_hub.integrations.hermes:listen
    args:
      audio_path: { type: string, required: true }
```

### OpenClaw Plugin

```python
# agent_voice_hub/integrations/openclaw_plugin.py
from agent_voice_hub.integrations import OpenClawPlugin

class VoiceHubPlugin(OpenClawPlugin):
    name = "voice-hub"
    version = "1.0.0"

    async def on_message(self, message):
        """自动语音回复"""
        if message.has_audio:
            text = self.stt.transcribe(message.audio)
            response = await self.agent.process(text)
            audio = self.tts.speak(response)
            return self.reply(audio)
```

### 通用 REST API

```bash
# 启动 API 服务
agent-voice serve --port 8080

# TTS 请求
curl -X POST http://localhost:8080/api/tts \
  -H "Content-Type: application/json" \
  -d '{"text": "你好世界", "voice": "zh-CN-XiaoxiaoNeural"}' \
  --output speech.mp3

# STT 请求
curl -X POST http://localhost:8080/api/stt \
  -F "[email protected]" \
  -F "language=zh"

# 安全扫描请求
curl -X POST http://localhost:8080/api/scan \
  -H "Content-Type: application/json" \
  -d '{"path": "./src", "format": "json"}'
```

---

## 🔒 安全扫描器 (Security Scanner)

内置 **46 种漏洞检测模式**，覆盖主流编程语言：

| 类别 | 检测项 | 语言 |
|------|--------|------|
| 🐍 命令注入 | `os.system()`, `subprocess.shell=True`, `eval()`, `exec()` | Python |
| 💉 SQL 注入 | 字符串拼接 SQL、未参数化查询 | Python/JS |
| 🌐 XSS | `innerHTML`, `document.write()`, 未转义输出 | JavaScript |
| 🔑 硬编码密钥 | API Key、密码、Token 字面量 | 全语言 |
| 📂 路径遍历 | `../` 拼接、未验证用户输入路径 | 全语言 |
| ⚠️ 反序列化 | `pickle.loads()`, `yaml.load()` 无 SafeLoader | Python |
| 🌍 SSRF | 未验证 URL、内网地址未过滤 | Python/JS |
| 🔓 弱加密 | MD5/SHA1 用于密码、ECB 模式 | 全语言 |

### 扫描示例

```bash
$ agent-voice scan ./my_project

🔒 安全扫描报告 — ./my_project
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  扫描文件: 47 个
  发现问题: 12 个

  🔴 严重 (Critical): 2
  🟠 高危 (High):     3
  🟡 中危 (Medium):   4
  🔵 低危 (Low):      3

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔴 CRITICAL — auth.py:23
   硬编码密码: password = "admin123"
   建议: 使用环境变量或密钥管理服务

🔴 CRITICAL — utils.py:45
   命令注入: os.system(f"convert {user_input}")
   建议: 使用 subprocess.run() 并传入列表参数

🟠 HIGH — db.py:67
   SQL 注入: cursor.execute(f"SELECT * FROM users WHERE id={uid}")
   建议: 使用参数化查询 cursor.execute("SELECT * FROM users WHERE id=?", (uid,))

🟡 MEDIUM — app.js:12
   XSS 风险: element.innerHTML = userInput
   建议: 使用 textContent 或 DOMPurify 净化

✅ 扫描完成。修复建议请参考报告详情。
```

---

## 🎤 声音克隆 (Voice Cloning)

基于 **Coqui XTTS v2** 的零样本声音克隆，仅需 6-30 秒参考音频即可生成高度相似的语音。

### 使用方法

```python
from agent_voice_hub import VoiceCloner

cloner = VoiceCloner(model="xtts_v2")

# 从参考音频克隆声音
cloner.clone(
    reference_audio="speaker_sample.wav",   # 6-30 秒参考音频
    text="这是用克隆声音说出的内容",           # 要合成的文本
    output="cloned_output.wav",              # 输出文件
    language="zh"                            # 语言
)
```

### CLI 使用

```bash
# 基本克隆
agent-voice clone \
  --ref-audio ./samples/speaker.wav \
  --text "你好，这是我克隆的声音" \
  --output cloned.wav

# 指定语言和温度参数
agent-voice clone \
  --ref-audio ./samples/speaker.wav \
  --text "Hello, this is my cloned voice" \
  --language en \
  --temperature 0.7 \
  --output cloned_en.wav
```

### 参考音频要求

| 参数 | 要求 |
|------|------|
| 时长 | 6-30 秒（推荐 10-15 秒） |
| 格式 | WAV / MP3 / FLAC / OGG |
| 采样率 | ≥ 16kHz |
| 质量 | 清晰无噪音，单人说话 |
| 环境 | 推荐 GPU（CUDA），CPU 亦可（较慢） |

---

## ⚙️ 配置 (Configuration)

配置文件默认路径：`~/.agent-voice-hub/config.yaml`

```yaml
# config.yaml
tts:
  engine: edge-tts          # edge-tts | xtts
  default_voice: zh-CN-XiaoxiaoNeural
  output_format: mp3        # mp3 | wav | ogg
  speed: 1.0                # 语速 (0.5 - 2.0)
  pitch: 0                  # 音调 (-50Hz - +50Hz)

stt:
  engine: faster-whisper
  model_size: large-v3      # tiny | base | small | medium | large-v3
  device: auto              # auto | cpu | cuda
  compute_type: float16     # float16 | int8 | float32
  auto_detect: true         # 自动检测语种

voice_clone:
  model: xtts_v2
  temperature: 0.65
  top_p: 0.85
  repetition_penalty: 5.0

security:
  severity_threshold: low   # low | medium | high | critical
  exclude_patterns:
    - "**/test/**"
    - "**/node_modules/**"
    - "**/.venv/**"
  languages:
    - python
    - javascript
    - shell

server:
  host: 0.0.0.0
  port: 8080
  cors_origins: ["*"]

logging:
  level: INFO               # DEBUG | INFO | WARNING | ERROR
  file: ~/.agent-voice-hub/logs/app.log
```

---

## 🎵 支持的音色 (Supported Voices)

Edge-TTS 提供 **300+ 音色**，以下为常用中文音色：

| 音色 ID | 语言 | 性别 | 说明 |
|---------|------|:---:|------|
| **zh-CN-XiaoxiaoNeural** | 中文（普通话） | 女 | ⭐ 默认推荐，自然流畅 |
| **zh-CN-YunxiNeural** | 中文（普通话） | 男 | 阳光少年音 |
| **zh-CN-YunjianNeural** | 中文（普通话） | 男 | 沉稳新闻播报 |
| **zh-CN-XiaoyiNeural** | 中文（普通话） | 女 | 甜美客服音 |
| **zh-CN-YunyangNeural** | 中文（普通话） | 男 | 专业主持音 |
| **zh-CN-XiaochenNeural** | 中文（普通话） | 女 | 温暖知性 |
| **zh-CN-XiaohanNeural** | 中文（普通话） | 女 | 端庄大气 |
| **z

... (truncated)

voice