kazuph/qwen-tts

Qwen3-TTS MLX ガイド

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

最重要ポイント

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

推奨設定:

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 | 不可 |

クイックスタート

インストール

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

最小コード（安定版）

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

音声ファイル保存

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を動的に計算することで、途切れ防止と速度のバランスを取る：

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 = int(estimated_duration * 12.5 * 1.2)  # 20%余裕
    return max(max_tokens, 50)  # 最低50トークン

実測結果（Mac M4 Pro）

| パターン | 文字数 | max_tokens | 音声長 | 途切れ | |----------|--------|------------|--------|--------| | 短め | 9文字 | 50 | 1.44秒 | なし | | 中くらい | 38文字 | 199 | 9.20秒 | なし | | 長め | 84文字 | 435 | 18.56秒 | なし |

使用例

text = "ずんだもんが、今日は特別なお知らせをお届けするのだ！"
optimal_max_tokens = calculate_optimal_max_tokens(len(text))

result = next(model.generate_voice_design(
    text=text,
    instruct="元気で明るく可愛らしい若い女の子の声",
    language="Japanese",
    max_tokens=optimal_max_tokens,  # 動的計算
    temperature=0.65,
    repetition_penalty=1.15,
    top_k=35,
    top_p=0.92,
))

パラメータリファレンス

詳細は PARAMETERS.md を参照。

| パラメータ | デフォルト | 推奨 | 効果 | |-----------|-----------|------|------| | max_tokens | 4096 | 150 | 音声長制御 | | temperature | 0.9 | 0.65 | 安定性向上 | | repetition_penalty | 1.05 | 1.15 | 繰り返し防止 | | top_k | 50 | 35 | 選択肢制限 | | top_p | 1.0 | 0.92 | 確率カットオフ |

声質プリセット例

VoiceDesignモードは instruct パラメータでテキスト指定：

# 女性声
"落ち着いた女性の声"
"明るく元気な若い女性の声"
"優しく穏やかな女性の声"
"知的でクールな女性の声"

# 男性声
"落ち着いた男性の声"
"明るく元気な若い男性の声"
"低く渋い男性の声"
"穏やかで優しい男性の声"

注意: instruct で「早口」「ゆっくり」を指定しても話速は変わらない。再生速度で調整。

Web UI

ブラウザでパラメータ調整できるWeb UIの構築方法は WEB-UI.md を参照。

主な機能

• スライダーでリアルタイムパラメータ調整
• 声質プリセット（8種類）
• キューベース処理（複数リクエスト対応）
• 再生速度調整（0.5x〜2x）
• 履歴保存・永続化

Remotion連携

動画制作ワークフローは REMOTION.md を参照。

実測時間（Mac M2）

| フェーズ | 時間 | |---------|------| | モデルロード | 3.65秒 | | 音声生成 (3ファイル) | 22.31秒 | | 動画レンダリング (3動画) | ~30秒 | | 合計 | 約70秒 |

トラブルシューティング

音声が長すぎる

→ max_tokens を下げる（150推奨）

繰り返しが発生する

→ repetition_penalty を1.15以上に

声質が安定しない

→ temperature を0.65以下に

話速を変えたい

→ instruct では変わらない。再生時に audio.playbackRate で調整

関連ドキュメント

• PARAMETERS.md - パラメータ詳細リファレンス
• WEB-UI.md - FastAPI + HTML Web UI構築
• REMOTION.md - Remotion動画制作連携
• EXAMPLES.md - コード例集

外部リソース

• Qwen3-TTS 公式
• mlx-audio
• MLX Community Model