# 开箱即用安装说明

## 共同准备

推荐 macOS Apple Silicon、Python 3.12、`ffmpeg`。第一次执行模型下载会占用网络与磁盘。

```bash
brew install ffmpeg pipx
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -U pip
```

## A 低配：Edge

```bash
pipx install edge-tts
edge-tts --voice zh-CN-XiaoxiaoNeural --text "这里是我的播客。Hello, welcome." --write-media 女声.mp3
edge-tts --voice zh-CN-YunxiNeural --text "今天我们测试中英文混读。This is the male host." --write-media 男声.mp3
```

这条路线不需要 API Key，但依赖在线服务；可用性和商业边界以项目与服务最新条款为准。

## B 中配：LuxTTS

```bash
git clone https://github.com/ysharma3501/LuxTTS.git
cd LuxTTS
git checkout 28ae6a61151684fffc9d1a7aa15eafa02286fe0b
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt
```

把一段你有权使用的干净 WAV 作为 `reference.wav`。Mac 使用 `device="mps"`，没有 MPS 时回退 CPU。实际生产建议参考 10–14 秒，并把参数固定进 manifest。

```python
from zipvoice.luxvoice import LuxTTS
import soundfile as sf

tts = LuxTTS("YatharthS/LuxTTS", device="mps", threads=2)
prompt = tts.encode_prompt("reference.wav", duration=14.0, rms=0.01)
audio = tts.generate_speech(
    "这里是我的主播。Today we are testing a natural bilingual voice.",
    prompt,
    num_steps=4,
    guidance_scale=3.0,
    t_shift=0.9,
    speed=0.92,
    return_smooth=False,
)
sf.write("output.wav", audio.detach().cpu().squeeze().numpy(), 48000)
```

## C 高配：Qwen3-TTS

官方仓库与模型下载：

```bash
git clone https://github.com/QwenLM/Qwen3-TTS.git
pip install -U modelscope
modelscope download --model Qwen/Qwen3-TTS-12Hz-1.7B-Base --local_dir ./Qwen3-TTS-12Hz-1.7B-Base
```

Apple Silicon 可使用 MLX 社区转换模型；本经验包实测模型为 `mlx-community/Qwen3-TTS-12Hz-1.7B-Base-bf16`。参考文字必须与参考音频逐字一致，不要拿自动转写的大概文本凑数。

## 统一成品

```bash
ffmpeg -i input.wav -af loudnorm=I=-18:TP=-1.5:LRA=9 -ar 48000 -ac 1 -c:a libmp3lame -b:a 192k output.mp3
ffmpeg -v error -i output.mp3 -f null -
```

正式生产请增加两遍响度分析、逐段失败重生成、ASR 回读、声纹检查、哈希和日志。网页中的三条演示正是按这一套门禁生成，不是示意音频。