Awesome-omni-skill qwen3-tts

Qwen3-TTS 文本转语音技能，支持多语言语音合成、语音克隆和语音设计。当用户需要生成语音、转换文本为语音、或使用 TTS 功能时使用此技能。

install

source · Clone the upstream repo

git clone https://github.com/diegosouzapw/awesome-omni-skill

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/diegosouzapw/awesome-omni-skill "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data-ai/qwen3-tts" ~/.claude/skills/diegosouzapw-awesome-omni-skill-qwen3-tts && rm -rf "$T"

manifest: skills/data-ai/qwen3-tts/SKILL.md

source content

Qwen3-TTS 文本转语音

基于 MLX 框架的本地 TTS（文本转语音）解决方案，专为 Apple Silicon M 系列芯片优化。

快速开始

# 安装（仅需一次）
uv tool install --force mlx-audio --prerelease=allow

# 基础使用
~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "你好，欢迎体验 Qwen3-TTS！" \
  --voice "serena" \
  --play

使用已克隆的音色

当用户已经保存了克隆语音配置时（在

~/.qwen3_tts_voices/

目录下），可以直接使用保存的语音生成音频：

检查是否有保存的克隆语音

# 列出所有保存的语音
ls -1 ~/.qwen3_tts_voices/

使用保存的克隆语音（推荐方式）

# 使用 voice-clone.sh 脚本（最简单）
~/.claude/skills/qwen3-tts/templates/voice-clone.sh use my_voice "你好，这是测试。" --play

直接使用命令

# 读取配置文件获取参数
CONFIG_FILE="$HOME/.qwen3_tts_voices/my_voice/config.json"

# 如果配置文件存在，直接使用
if [ -f "$CONFIG_FILE" ]; then
  ~/.local/bin/mlx_audio.tts.generate \
    --model "mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16" \
    --text "你好，这是测试。" \
    --ref_audio "$HOME/.qwen3_tts_voices/my_voice/reference.wav" \
    --ref_text "你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。" \
    --lang_code "zh" \
    --play
fi

技能调用流程

当用户要求"使用我的音色"或类似请求时：

检查保存的语音：
```
ls ~/.qwen3_tts_voices/
```

读取配置：

cat ~/.qwen3_tts_voices/my_voice/config.json

生成语音：使用
```
--ref_audio
```
和
```
--ref_text
```
参数

示例对话：

用户：用我的声音说"你好，世界"
AI：让我使用你保存的克隆语音来生成...
    [执行 voice-clone.sh use my_voice "你好，世界" --play]

可用模型

模型	大小	特点	用途
`Qwen3-TTS-12Hz-0.6B-Base-bf16`	0.6B	基础模型	语音克隆（推荐）
`Qwen3-TTS-12Hz-0.6B-CustomVoice-bf16`	0.6B	9 个预设语音	使用预设语音生成
`Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16`	1.7B	9 个预设语音	更高质量的预设语音
`Qwen3-TTS-12Hz-1.7B-VoiceDesign-bf16`	1.7B	语音设计	创建自定义语音描述

CustomVoice 模型可用语音

中文语音

```
serena
```
- 温柔女声（推荐中文）
```
vivian
```
- 知性女声
```
ryan
```
- 成熟男声

英文语音

```
aiden
```
- 青年男声
```
ono_anna
```
- 日式女声
```
sohee
```
- 韩式女声
```
eric
```
- 欧美男声
```
dylan
```
- 青少年男声
```
uncle_fu
```
- 特色男声

基础用法

生成并播放语音

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "你好，这是一段测试语音。" \
  --voice "serena" \
  --play

保存语音文件

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "你好，这是保存的音频。" \
  --voice "vivian" \
  --file_prefix my_audio \
  --audio_format wav

高级用法

调整语速

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "这是加快语速的示例。" \
  --voice "serena" \
  --speed 1.5

使用温度控制语音多样性

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "同样的文本，不同的语气。" \
  --voice "serena" \
  --temperature 0.8

批量生成长文本

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "第一段。第二段。第三段。" \
  --voice "serena" \
  --split_pattern "。" \
  --join_audio

详细输出信息

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "显示详细生成信息。" \
  --voice "serena" \
  --verbose

语音克隆

重要：语音克隆必须使用 Base 模型

语音克隆应该使用 Base 模型，而不是 CustomVoice 模型！

Base 模型支持从参考音频克隆任意声音，而 CustomVoice 模型只支持预设语音。

基础克隆（正确方式）

# 使用 Base 模型进行语音克隆
~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16 \
  --text "这是克隆的语音。" \
  --ref_audio /path/to/reference.wav \
  --ref_text "参考音频的文本内容"

注意：

使用
```
Base
```
模型，不是
```
CustomVoice
```
不需要
```
--voice
```
参数（让模型完全从参考音频克隆）
只需要
```
--ref_audio
```
和
```
--ref_text
```

参考音频要求

格式: WAV, MP3, FLAC, M4A 等常见格式
时长: 建议 3-10 秒
内容: 清晰的语音，无背景噪音
文本:
```
--ref_text
```
必须与参考音频的内容完全匹配

引导用户录音流程

由于命令行录音需要用户确认，推荐使用以下步骤引导用户录音：

# 步骤 1: 引导用户使用 macOS 录音应用
echo "请按以下步骤录音："
echo "1. 打开「语音备忘录」应用"
echo "2. 点击红色录音按钮"
echo "3. 清晰朗读以下文本："
echo '   "你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。"'
echo "4. 点击停止按钮"
echo "5. 将录音共享到桌面，命名为 'voice_reference.m4a'"
echo ""
echo "完成后告诉我，继续下一步..."

# 步骤 2: 查找桌面上的录音文件
# 用户录音完成后，查找最新的 m4a 文件
LATEST_AUDIO=$(ls -t ~/Desktop/*.m4a 2>/dev/null | head -1)

# 步骤 3: 转换音频格式（如果需要）
if [ -f "$LATEST_AUDIO" ]; then
  ffmpeg -i "$LATEST_AUDIO" -ar 24000 -ac 1 -acodec pcm_s16le ~/reference.wav -y
  echo "音频已转换: ~/reference.wav"
fi

# 步骤 4: 使用 Base 模型进行语音克隆
~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16 \
  --text "你好，这是测试语音克隆效果。" \
  --ref_audio ~/reference.wav \
  --ref_text "你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。" \
  --play

保存和复用克隆语音

使用

templates/voice-clone.sh

脚本可以保存克隆语音配置：

# 首次克隆并保存配置
./templates/voice-clone.sh save my_voice \
  --ref_audio ~/reference.wav \
  --ref_text "你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。"

# 之后直接使用保存的语音
./templates/voice-clone.sh use my_voice "这是要生成的新文本" --play

语音配置保存在

~/.qwen3_tts_voices/

目录，包含：

```
config.json
```
- 语音配置（参考音频路径、文本等）
参考音频文件的副本

完整工作流程示例：

# 1. 引导用户录音（使用语音备忘录）
# 见上面的"引导用户录音流程"

# 2. 保存为克隆语音
./templates/voice-clone.sh save my_custom_voice \
  --ref_audio ~/reference.wav \
  --ref_text "你好，这是我的声音"

# 3. 使用克隆语音生成任意文本
./templates/voice-clone.sh use my_custom_voice "今天天气真好" --play

# 4. 查看所有保存的语音
./templates/voice-clone.sh list

批量克隆管理

# 列出所有保存的克隆语音
./templates/voice-clone.sh list

# 删除某个克隆语音
./templates/voice-clone.sh delete my_voice

# 更新克隆语音的参考音频
./templates/voice-clone.sh update my_voice --ref_audio ~/new_reference.wav

参数说明

参数	说明	默认值
`--model`	模型路径或 HuggingFace ID	`mlx-community/Kokoro-82M-bf16`
`--text`	要转换的文本	从 stdin 读取
`--voice`	语音名称（仅 CustomVoice 模型需要）	模型默认
`--speed`	播放速度	1.0
`--temperature`	采样温度 (0.1-1.5)	0.7
`--top_p`	Top-p 采样	0.9
`--top_k`	Top-k 采样	50
`--max_tokens`	最大生成 token 数	1200
`--file_prefix`	输出文件前缀	`audio`
`--audio_format`	音频格式 (wav/flac/mp3)	`wav`
`--play`	播放生成的音频	false
`--join_audio`	合并多个音频段	false
`--split_pattern`	分段模式	`\n`
`--verbose`	显示详细信息	false
`--ref_audio`	参考音频路径（语音克隆必需）	null
`--ref_text`	参考音频文本（语音克隆必需）	null
`--lang_code`	语言代码（如 zh, en）	自动检测

输出格式

控制台输出

Text: 你好，欢迎体验 Qwen3-TTS！
Voice: None  # Base 模型显示 None
Speed: 1.0x
Language: zh
==========
Duration:              00:00:08.123
Samples/sec:           24000.0
Prompt:                245 tokens, 30.12 tokens-per-sec
Audio:                 194952 samples, 24000.0 samples-per-sec
Real-time factor:      0.42x
Processing time:       19.32s
Peak memory usage:     2.15GB
✅ Audio successfully generated and saving as: audio_000.wav

文件输出

默认输出为 WAV 格式
采样率：24000 Hz

文件命名：

{file_prefix}_{索引:03d}.{audio_format}

使用 uvx（无需安装）

uvx mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16 \
  --text "使用 uvx 运行" \
  --ref_audio reference.wav \
  --ref_text "参考文本"

常见问题

1. 语音克隆不像我的声音

确保使用 Base 模型，不是 CustomVoice 模型
确保
```
--ref_text
```
与参考音频内容完全匹配
参考音频应清晰、无背景噪音
尝试使用更长的参考音频（5-10 秒）

2. 音频无法播放

确保已安装音频驱动：

# macOS 自带 afplay
afplay audio_000.wav

# 或使用 ffplay（需要安装 ffmpeg）
brew install ffmpeg
ffplay audio_000.wav

3. 内存不足

使用较小的模型（0.6B）
减少
```
--max_tokens
```
值
关闭其他应用释放内存

4. 中文发音不准

使用
```
--lang_code zh
```
参数
调整
```
--temperature
```
参数
使用
```
--speed
```
调整语速

5. 生成速度慢

正常现象，实时因子约为 0.3-0.5x
即生成 10 秒音频需要 20-30 秒

实用脚本

Ready-to-use 模板脚本

templates/

目录提供了多个开箱即用的脚本：

脚本	描述
`simple-tts.sh`	简单语音生成，适合快速测试
`batch-tts.sh`	批量生成多种语音的相同文本
`file-to-tts.sh`	从文本文件读取并生成语音
`voice-clone.sh`	语音克隆管理（保存、使用、列表、删除）
`record-reference.sh`	录制参考音频用于语音克隆

使用示例：

# 快速生成语音
./templates/simple-tts.sh "你好，世界" "serena"

# 录制参考音频
./templates/record-reference.sh my_voice.wav 5

# 保存并使用克隆语音
./templates/voice-clone.sh save my_voice \
  --ref_audio my_voice.wav \
  --ref_text "你好，世界"

./templates/voice-clone.sh use my_voice "新的文本内容" --play

批量生成多个语音

#!/bin/bash
TEXT="你好，这是测试文本。"

for voice in serena vivian ryan; do
  ~/.local/bin/mlx_audio.tts.generate \
    --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
    --text "$TEXT" \
    --voice "$voice" \
    --file_prefix "output_${voice}" \
    --audio_format wav
done

从文件读取文本

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --voice "serena" \
  --play \
  < input.txt

流式生成（边生成边播放）

~/.local/bin/mlx_audio.tts.generate \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-bf16 \
  --text "这是一段很长的文本..." \
  --voice "serena" \
  --stream \
  --streaming_interval 2.0

Python API 用法

from mlx_audio.tts.utils import load_model
import sounddevice as sd
import numpy as np

# 加载模型
model = load_model("mlx-community/Qwen3-TTS-12Hz-0.6B-Base-bf16")

# 语音克隆
text = "你好，这是测试语音克隆效果。"
results = list(model.generate(
    text=text,
    ref_audio="reference.wav",
    ref_text="你好，这是我的声音克隆测试。今天天气真不错，我很高兴能体验这个功能。",
    verbose=True
))

# 播放音频
audio = results[0].audio
sample_rate = results[0].sample_rate
sd.play(np.array(audio), sample_rate)
sd.wait()

技术规格

框架: MLX (Apple Silicon 优化)
采样率: 24000 Hz
音频编码: SNAC (SoundStream)
基础模型: Qwen3 (12Hz)
支持语言: 中文、英文、日文、韩文等多语言
硬件要求: Apple Silicon (M1/M2/M3/M4)
Python 要求: 3.10+