# Qwen3-TTS Rust [中文](README.md) | [English](docs/README_EN.md) | [日本語](docs/README_JA.md) | [Korean](docs/README_KO.md) | [Français](docs/README_FR.md) | [Español](docs/README_ES.md) | [Italiano](docs/README_IT.md) | [Deutsch](docs/README_DE.md) | [Русский](docs/README_RU.md) | [Português](docs/README_PT.md) 本项目是 Qwen3-TTS 的极致性能实现,核心突破在于 **“指令驱动 (Instruction-Driven)”** 与 **“零样本自定义音色 (Custom Speakers)”** 的深度集成。通过 Rust 的内存安全特性与 llama.cpp/ONNX 的高效推理,为您提供工业级的文本转语音解决方案。 ## 🚀 核心特性 ### 1. 极致性能与流式响应 - **并发流式解码**:采用 4 帧 (64 codes) 粒度的并发解码策略,首字延迟低至 300ms,实现“边想边说”的流畅体验。 - **硬件加速**:默认启用 **Vulkan** (Windows/Linux) 和 **Metal** (macOS) 加速,显著提升推理速度。 - **自动运行时管理**:零配置环境,自动下载并配置 `llama.cpp` (b7885) 和 `onnxruntime`,开箱即用。 ### 2. 灵活的说话人管理 - **自动扫描与缓存**:启动时自动加载 `speakers/` 目录下的音色文件。 - **多种选择方式**:支持通过 CLI 参数 `--speaker ` 或 `--voice-file ` 灵活选择说话人。 - **智能回退**:若指定说话人不存在,自动回退至默认音色 (vivian),确保系统稳定性。 ### 3. 精准的指令控制 - **指令驱动**:支持在文本中嵌入 `[高兴]`、`[悲伤]` 等情感指令,实时调整演绎风格。 - **EOS 对齐**:完美对齐 Qwen3 的停止逻辑,支持多种 EOS token 检测,杜绝生成末尾的静音或乱码。 ## 📊 性能基准 (Benchmarks) | Backend | Model (GGUF) | RTF (Real-Time Factor) | Avg Time (ms) | Avg Audio (s) | Status | | :--- | :--- | :--- | :--- | :--- | :--- | | **CUDA** | Q5_K_M | **0.553** | 1162.6 | 2.19 | OK | | **Vulkan** | Q5_K_M | 0.598 | 1285.4 | 2.19 | OK | | **CUDA** | Q8_0 | 0.640 | 1523.4 | 2.44 | OK | | **Vulkan** | Q8_0 | 0.638 | 1502.0 | 2.44 | OK | | **CPU** | Q5_K_M | 1.677 | 2823.4 | 1.96 | OK | | **CPU** | Q8_0 | 1.866 | 4160.1 | 2.51 | OK | - **测试环境**: Intel Core i9-13980HX, NVIDIA RTX 2080 Ti. 显存占用约 0.7-1.5GB. - **数据来源**: Windows 平台 10 轮生成平均值。 - **最佳性能**: RTF 0.553 (CUDA + Q5KM),即生成 1 秒音频仅需 0.553 秒。 ## 🛠️ 快速上手 ### 1. 基础生成 使用默认说话人生成语音: ```powershell cargo run --bin qwen3_tts -- --text "你好,欢迎使用 Qwen3-TTS Rust!" ``` ### 2. 指定说话人 使用预设或自定义说话人: ```powershell # 使用名称 (需在 speakers/ 目录下存在对应的 .json 文件) cargo run --bin qwen3_tts -- --text "今天天气不错。" --speaker dylan # 使用指定文件路径 cargo run --bin qwen3_tts -- --text "我是自定义音色。" --voice-file "path/to/my_voice.json" ``` ### 3. 克隆新音色 只需 3-10 秒的参考音频即可克隆音色: ```powershell cargo run --bin qwen3_tts -- ` --ref-audio "ref.wav" ` --ref-text "参考音频对应的文本内容" ` --save-voice "speakers/my_voice.json" ` --text "新音色已保存,现在可以直接使用了!" ``` ### 4. 风格/情感控制 (Instruction) 通过 `--instruction` 参数实时改变说话语气: ```powershell # 悲伤语气 cargo run --bin qwen3_tts -- --text "对不起,我不是故意的..." --instruction "悲伤啜泣,非常难过" # 开心语气 cargo run --bin qwen3_tts -- --text "太棒了!我们成功了!" --instruction "开心激动,语速稍快" ``` ### 5. 高级配置 ```powershell cargo run --bin qwen3_tts -- ` --text "长文本生成测试。" ` --max-steps 1024 ` # 调整最大生成长度 --output "output.wav" # 指定输出文件名 ``` ### 6. 采样参数调整 通过采样参数控制生成的随机性和多样性: ```powershell # 调整温度 (更高 = 更随机,0.0 = 贪婪) cargo run --bin qwen3_tts -- --text "测试文本" --temperature 0.8 # 使用固定种子复现结果 cargo run --bin qwen3_tts -- --text "测试文本" --seed 12345 # 完整参数示例 cargo run --bin qwen3_tts -- ` --text "测试采样参数。" ` --temperature 0.7 ` # 温度 (默认 0.7) --top-k 40 ` # Top-K 采样 (默认 40) --top-p 0.9 ` # Top-P 核采样 (默认 0.9) --seed 42 # 随机种子 (可选) ``` ## 📦 作为 Rust 库使用 在 `Cargo.toml` 中添加依赖: ```toml [dependencies] # 本地引用 qwen3-tts = { path = "." } # 或从 Git 引用 # qwen3-tts = { git = "https://github.com/cgisky1980/Qwen3-TTS-Rust" } ``` ### 基础用法 ```rust use qwen3_tts::{TtsEngine, VoiceFile, SamplerConfig}; #[tokio::main] async fn main() -> Result<(), Box> { // 1. 初始化引擎 let mut engine = TtsEngine::new("models", "none").await?; // 2. 配置采样参数 (可选) let sampler_config = SamplerConfig::new(0.7, 40, 0.9, None); engine.set_sampler_config(sampler_config); // 3. 加载音色 let voice = VoiceFile::load("speakers/sohee.json")?; // 4. 生成语音 let audio = engine.generate_with_voice( "你好,欢迎使用 Qwen3-TTS!", &voice, None, // instruction )?; // 5. 保存音频 audio.save_wav("output.wav")?; Ok(()) } ``` ### 从参考音频创建音色 ```rust use qwen3_tts::TtsEngine; #[tokio::main] async fn main() -> Result<(), Box> { let mut engine = TtsEngine::new("models", "none").await?; // 从参考音频提取音色 let voice = engine.create_voice_file( "reference.wav", "参考音频对应的文本".to_string(), )?; // 保存音色文件 voice.save("speakers/my_voice.json")?; // 使用新音色生成 let audio = engine.generate_with_voice("测试新音色", &voice, None)?; audio.save_wav("output.wav")?; Ok(()) } ``` ## �� 目录结构 系统首次运行会自动构建如下结构: ```text . ├── models/ # 模型文件 (GGUF, ONNX, Tokenizer) ├── runtime/ # 自动下载的依赖库 (dll, so, dylib) └── speakers/ # 用户自定义音色 ``` ## 📜 许可证与致谢 - 基于 **MIT / Apache 2.0** 许可证。 - 感谢 [Qwen3-TTS](https://github.com/QwenLM/Qwen3-TTS) 官方仓库提供的模型与技术基座。 - 感谢 [Qwen3-TTS-GGUF](https://github.com/HaujetZhao/Qwen3-TTS-GGUF) 提供的推理流程启发。