qwen-tts

# Qwen3-TTS MLX ガイド

Mac M2+（MLX）でQwen3-TTS VoiceDesignモードを効率的に実行するためのベストプラクティス。

## 最重要ポイント

**警告**: デフォルト `max_tokens=4096` は **327秒の音声** を生成してしまう！

**推奨設定**:
```python
max_tokens=150  # 約12秒の音声
```

## RTF（Real-Time Factor）早見表

| 意味 | RTF値 | ステータス |
|------|------|----------|
| リアルタイムより速い | < 1 | 配信可能 |
| 等速 | = 1 | ギリギリ可能 |
| リアルタイムより遅い | > 1 | 事前生成向け |

**計算式**: `RTF = 生成時間 ÷ 音声の長さ`

### 環境別パフォーマンス

| 環境 | 設定 | RTF | リアルタイム |
|------|-----|-----|------------|
| **Mac M2 MLX** | max_tokens=150 | **0.955** | ほぼ可能 |
| Mac M2 MLX | max_tokens=4096 | 7.0 | 不可 |
| RTX 3090 | バッチ3 | 0.63 | 可能 |
| RTX 3090 | バッチ1 | 1.9 | 不可 |

## クイックスタート

### インストール

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install mlx-audio soundfile
```

### 最小コード（安定版）

```python
from mlx_audio.tts import load

model = load('mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-4bit')

result = next(model.generate_voice_design(
    text="こんにちは、私はクエンTTSです。",
    instruct="明るく元気な若い女性の声",
    language="Japanese",
    max_tokens=150,           # 重要: 約12秒
    temperature=0.65,         # 安定性向上
    repetition_penalty=1.15,  # 繰り返し防止
    top_k=35,
    top_p=0.92,
))

# result.audio: 音声データ (numpy array)
# result.sample_rate: 24000Hz
```

### 音声ファイル保存

```python
import soundfile as sf
sf.write("output.wav", result.audio, result.sample_rate)
```

## max_tokens と音声長

**計算式**: `音声長（秒）≈ max_tokens / 12.5`

| max_tokens | 想定音声長 | 用途 |
|------------|----------|------|
| 50 | ~4秒 | 短い挨拶 |
| 100 | ~8秒 | ショートフレーズ |
| **150** | **~12秒** | **標準（推奨）** |
| 200 | ~16秒 | 長めの説明 |
| 500 | ~40秒 | ナレーション |
| 2000 | ~160秒 | 長文読み上げ |
| 4096 | ~327秒 | 使用非推奨 |

### 動的max_tokens計算（セリフ長に応じた最適化）

固定値ではなく、セリフ長に応じてmax_tokensを動的に計算することで、途切れ防止と速度のバランスを取る：

```python
def calculate_optimal_max_tokens(text_length: int) -> int:
    """
    セリフ長に応じた最適なmax_tokensを計算

    計算式:
    - 1文字あたり約0.35秒と見積もり（日本語の平均的な読み上げ速度）
    - 最低3秒は確保
    - 12.5トークン/秒 + 20%の余裕
    """
    estimated_duration = max(text_length * 0.35, 3.0)
    max_tokens = i