# 语音理解与语音回复

`语音识别` `语音合成` `声音克隆` `Agent技能` `通义千问`

# qwen-voice（Agent 技能）

目标：为 Agent 对话添加**语音理解 + 语音回复**能力。

亮点：
- ASR：语音 → 文字（可选粗粒度时间戳，基于分块实现）
- TTS：文字 → 语音（默认音色：Cherry）
- 声音克隆：一段样本音频 → 你的自定义音色 → 语音回复

完美支持 **Clawdbot**（以及其他支持 Agent Skills 的宿主）。

## 安装（Agent 技能）

```bash
npx skills add ada20204/qwen-voice
```

## 环境要求

系统依赖：
- ffmpeg

Python 依赖：
- Python 3.10+
- 推荐使用：`uv`（或任意 venv + pip）

## 环境变量

必填：
- `DASHSCOPE_API_KEY`

### 代码读取环境变量的方式

脚本同时支持以下**两种**方式：
1) **用户级**（推荐）：`~/.config/qwen-voice/.env`
2) **项目级**（开发/测试用）：`./.qwen-voice/.env`

优先级：用户级优先，其次项目级。

> 注意：系统环境变量会被忽略，只读取 `.env` 文件。

### 配置方式（推荐）

将模板目录复制到用户配置目录：

```bash
cp -r .qwen-voice ~/.config/qwen-voice
cp ~/.config/qwen-voice/.env.example ~/.config/qwen-voice/.env
# 编辑 ~/.config/qwen-voice/.env
```

### 配置方式（项目本地，可选）

```bash
cp .qwen-voice/.env.example .qwen-voice/.env
# 编辑 .qwen-voice/.env
```

## 快速命令

ASR（不带时间戳）：
```bash
python3 scripts/qwen_asr.py --in /path/to/audio.ogg
```

ASR（带粗粒度时间戳）：
```bash
python3 scripts/qwen_asr.py --in /path/to/audio.ogg --timestamps --chunk-sec 3
```

TTS（预设音色）：
```bash
python3 scripts/qwen_tts.py --text '你好，我是 Pi。' --voice Cherry --out /tmp/out.ogg
```

声音克隆（创建一次声音档案，重复使用）：
```bash
python3 scripts/qwen_voice_clone.py --in ./sample.ogg --name george --out ./george.voice.json
python3 scripts/qwen_tts.py --text '你好，我是 George。' --voice-profile ./george.voice.json --out /tmp/out.ogg
```

## 注意事项

- 时间戳基于**分块**，而非词级对齐。
- 音频输入在 ASR 前会被转换为**单声道 16k WAV** 格式。
- `.ogg` 输出使用 Opus 编码（兼容 Telegram 语音消息）。

## 仓库结构

- `SKILL.md` + `scripts/` 是 Agent 技能的入口（遵循约定的发现机制）
- `.qwen-voice/` 环境变量模板目录（复制到 `~/.config/qwen-voice/` 使用）