qwen3-tts-mlx

Qwen3-TTS MLX

MLX を使用して、Apple Silicon（M1/M2/M3/M4）上で Qwen3-TTS をローカル実行します。11 言語、9 種類の内蔵ボイス、ボイスクローン、テキストの説明からのボイスデザインに対応しています。

使用する場面

• Mac 上で完全にオフラインで音声を生成する
• ナレーション、オーディオブック、ポッドキャスト、動画のナレーションを作成する
• スタイルや感情を調整できる多言語 TTS を作成する
• 短い音声サンプルから任意の声をクローンする
• テキストの説明からカスタムボイスをデザインする

クイックスタート

インストール

pip install mlx-audio
brew install ffmpeg

基本的な使い方

python scripts/run_tts.py custom-voice \
  --text "Hello, welcome to local text to speech." \
  --voice Ryan \
  --output output.wav

スタイルを調整する

python scripts/run_tts.py custom-voice \
  --text "Breaking news: local AI model achieves human-level speech." \
  --voice Uncle_Fu \
  --instruct "news anchor tone, calm and authoritative" \
  --output news.wav

モデルの種類

種類	モデル	サイズ	メモリ	用途
CustomVoice	mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit	約1GB	約4GB	内蔵ボイス＋スタイル調整（推奨）
VoiceDesign	mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-5bit	約2GB	約5GB	テキストの説明からボイスを作成
Base	mlx-community/Qwen3-TTS-12Hz-0.6B-Base-4bit	約1GB	約4GB	参照音声からボイスをクローン

対応言語

言語	コード	備考
自動検出	auto	デフォルト。テキストから検出します
中国語	Chinese	標準中国語
英語	English
日本語	Japanese
韓国語	Korean
フランス語	French
ドイツ語	German
スペイン語	Spanish
ポルトガル語	Portuguese
イタリア語	Italian
ロシア語	Russian

内蔵ボイス

ボイス	言語	特徴
Vivian	中国語	女性、明るく若々しい
Serena	中国語	女性、穏やかで柔らかい
Uncle_Fu	中国語	男性、威厳があり、ニュースキャスター風
Dylan	中国語	男性、北京方言
Eric	中国語	男性、四川方言
Ryan	英語	男性、エネルギッシュ
Aiden	英語	男性、明瞭でニュートラル
Ono_Anna	日本語	女性
Sohee	韓国語	女性

ボイス選択ガイド：

場面	おすすめのボイス
中国語のニュース／ナレーション	Uncle_Fu
中国語のカジュアル／活気のあるコンテンツ	Eric
中国語の女性、プロフェッショナルな雰囲気	Vivian
中国語の女性、ストーリーテリング	Serena
英語のエネルギッシュなコンテンツ	Ryan
英語のニュートラル／教育的なコンテンツ	Aiden
日本語のコンテンツ	Ono_Anna
韓国語のコンテンツ	Sohee

モード

1) CustomVoice

内蔵ボイスを使用します。--instruct で感情やスタイルを調整することもできます。

python scripts/run_tts.py custom-voice \
  --text "This is amazing news!" \
  --voice Vivian \
  --instruct "excited and happy" \
  --output excited.wav

スタイル指示の例：

• "calm and warm" - 柔らかく親しみやすい話し方
• "news anchor, authoritative" - プロフェッショナルな放送スタイル
• "excited and energetic" - エネルギッシュで熱意のある話し方
• "sad and melancholic" - 感情的で沈んだトーン
• "whispering, intimate" - 静かで、マイクに近い話し方

2) VoiceDesign

自然言語で説明して、まったく新しいボイスを作成します。

python scripts/run_tts.py voice-design \
  --text "Welcome to our podcast." \
  --instruct "warm, mature male narrator with low pitch and gentle tone" \
  --output podcast_intro.wav

ボイスの説明例：

• "young cheerful female with high pitch"
• "elderly wise male with deep resonant voice"
• "professional female news anchor, clear articulation"
• "friendly young male, casual and relaxed"

3) VoiceClone

参照音声サンプルから任意の声をクローンします（5～10 秒を推奨）。

python scripts/run_tts.py voice-clone \
  --text "This is my cloned voice speaking new content." \
  --ref_audio reference.wav \
  --ref_text "The exact transcript of the reference audio" \
  --output cloned.wav

ボイスクローンのヒント：

• 背景ノイズのないクリアな音声を使用する
• 5～10 秒の音声が最適です
• 参照音声の正確な書き起こしを用意する
• 参照音声と出力の言語を一致させる

CLI パラメーター

パラメーター	必須	デフォルト	説明
--text	はい	-	合成するテキスト
--voice	いいえ	Vivian	組み込み音声（CustomVoice のみ）
--lang_code	いいえ	auto	言語コード
--instruct	いいえ	-	スタイル制御または音声の説明
--speed	いいえ	1.0	音声速度の倍率
--temperature	いいえ	0.7	サンプリング温度（値が高いほど変化が大きくなります）
--model	いいえ	(モードごと)	デフォルトモデルを上書きします
--output	いいえ	-	出力ファイルのパス
--out-dir	いいえ	./outputs	--output が設定されていない場合の出力ディレクトリ
--ref_audio	VoiceClone	-	参照音声ファイル
--ref_text	VoiceClone	-	参照音声の書き起こし

Python API

generate_audio を使用する（推奨）

from mlx_audio.tts.generate import generate_audio

# CustomVoice with style control
generate_audio(
    text="Hello from Qwen3-TTS!",
    model="mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit",
    voice="Ryan",
    lang_code="english",
    instruct="friendly and warm",
    output_path=".",
    file_prefix="hello",
    audio_format="wav",
    join_audio=True,
    verbose=True,
)

Model を直接使用する

from mlx_audio.tts.utils import load
import soundfile as sf
import numpy as np

# Load model
model = load("mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-4bit")

# Generate audio (returns a generator)
audio_chunks = []
for chunk in model.generate_custom_voice(
    text="Hello from Qwen3-TTS.",
    speaker="Ryan",
    language="english",
    instruct="clear, steady delivery"
):
    if hasattr(chunk, 'audio') and chunk.audio is not None:
        audio_chunks.append(chunk.audio)

# Combine and save
audio = np.concatenate(audio_chunks)
sf.write("output.wav", audio, 24000)

VoiceDesign

from mlx_audio.tts.generate import generate_audio

generate_audio(
    text="Welcome to the show.",
    model="mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-5bit",
    instruct="warm, friendly female narrator with medium pitch",
    lang_code="english",
    output_path=".",
    file_prefix="voice_design",
    join_audio=True,
)

VoiceClone

from mlx_audio.tts.generate import generate_audio

generate_audio(
    text="New content in the cloned voice.",
    model="mlx-community/Qwen3-TTS-12Hz-0.6B-Base-4bit",
    ref_audio="reference.wav",
    ref_text="Transcript of the reference audio",
    output_path=".",
    file_prefix="cloned",
    join_audio=True,
)

バッチ処理

複数の行を処理するには、scripts/batch_dubbing.py を使用します。

python scripts/batch_dubbing.py \
  --input dubbing.json \
  --out-dir outputs

JSON 形式については、references/dubbing_format.md を参照してください。

パフォーマンス

指標	値
サンプルレート	24,000 Hz
リアルタイム係数	約 0.7x（リアルタイムより高速）
ピークメモリ	約 4～6 GB
初回実行	モデルをダウンロードします（約 1～2GB）

トラブルシューティング

問題	解決策
生成が遅い	4-bit CustomVoice モデルを使用します
不自然な間	句読点を追加し、文を短くします
言語が誤って検出される	--lang_code を明示的に指定します
音声クローンの品質	よりクリアな参照音声と、正確な書き起こしを使用します
トークナイザーの警告	無害なので、無視できます
メモリ不足	他のアプリを終了し、4-bit モデルを使用します