# Mlx Tts

> Use when needing to generate speech audio from text files on Apple Silicon Mac using Qwen3-TTS (MLX framework, fast, prompt-based voice design)

- **Type:** Skill
- **Install:** `agentstack add skill-renky1025-agent-skills-mlx-tts`
- **Verified:** Pending review
- **Seller:** [renky1025](https://agentstack.voostack.com/s/renky1025)
- **Installs:** 0
- **Category:** [Content & Media](https://agentstack.voostack.com/c/content-and-media)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [renky1025](https://github.com/renky1025)
- **Source:** https://github.com/renky1025/agent-skills/tree/main/mlx-tts

## Install

```sh
agentstack add skill-renky1025-agent-skills-mlx-tts
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# MLX TTS (Qwen3-TTS)

High-quality local text-to-speech synthesis for Apple Silicon Macs using Qwen3-TTS via MLX framework. Optimized for Apple Neural Engine, runs entirely on-device.

## Overview

Qwen3-TTS is a 1.7B parameter TTS model optimized for Apple Silicon (M1/M2/M3/M4) using the MLX framework. Features:
- **Fast inference**: Leverages Apple Neural Engine
- **Prompt-based voice design**: Describe the voice you want, no reference audio needed
- **ASR support**: Speech-to-text included
- **Low memory**: 8-bit quantized, runs on 16GB Mac
- **Local only**: No cloud, no API keys, fully private

## When to Use

- Have an Apple Silicon Mac (M1/M2/M3/M4)
- Need high-quality TTS locally
- Want to design voices with text prompts (e.g., "a warm female voice, slightly soft")
- Need ASR (speech-to-text) capability
- Want fast inference with Apple Neural Engine

## When NOT to Use

- Non-Mac system (Intel Mac or Windows/Linux) → Use other TTS solutions
- Need voice cloning from reference audio → Use other tools
- Less than 16GB RAM → May work but slower

## Environment Setup

### One-Command Install

```bash
brew install ffmpeg uv && uv tool install --force "mlx-audio" --prerelease=allow
```

### Verify Installation

```bash
uv tool list | grep mlx
# Should show: mlx-audio v0.4.2
```

### Model Download

Models auto-download on first run (~2GB total) to `~/.cache/huggingface/hub/`:
- `mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit`
- `mlx-community/Qwen3-ASR-0.6B-bf16`

**For China users (accelerated download):**

Option 1 - HuggingFace mirror:
```bash
export HF_ENDPOINT=https://hf-mirror.com
```

Option 2 - ModelScope (faster):
```bash
pip install modelscope

# Download TTS model
modelscope download \
  --model mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit \
  --local_dir ~/.cache/huggingface/hub/Qwen3-TTS

# Download ASR model
modelscope download \
  --model mlx-community/Qwen3-ASR-0.6B-bf16 \
  --local_dir ~/.cache/huggingface/hub/Qwen3-ASR
```

## Usage

### Basic TTS

```bash
mlx_audio.tts.generate \
  --text "你好，这是本地 TTS 测试" \
  --output-path ./output.wav
```

### With Voice Design (Prompt-Based)

```bash
mlx_audio.tts.generate \
  --text "我是明日香" \
  --instruct "a confident teenage girl, flirtatious, seductive edge" \
  --output-path ./asuka.wav
```

### Voice Prompt Examples

| Style | Prompt |
|-------|--------|
| 自信少女 | `"a confident teenage girl, German-Japanese, EVA pilot"` |
| 温柔女声 | `"a warm, gentle female voice, slightly soft"` |
| 磁性男声 | `"a deep, masculine voice with authority"` |
| 儿童声音 | `"a cheerful little child, about 5 years old"` |
| 新闻播报 | `"a professional news anchor, clear and authoritative"` |
| 温柔妈妈 | `"a caring mother, warm and soothing"` |
| 神秘低语 | `"a mysterious whisper, soft and intimate, close to microphone"` |
| 激动演讲 | `"an energetic public speaker, passionate and enthusiastic"` |
| 悲伤叙述 | `"a melancholic storyteller, slow and reflective"` |

### Advanced Voice Design Tips

**Delivery Instructions** (Qwen3-TTS supports these):
- `"speak slowly and clearly"`
- `"whisper gently"`
- `"speak with excitement"`
- `"calm and soothing tone"`
- `"fast-paced, energetic delivery"`

**Combine multiple descriptors**:
```bash
--instruct "a warm female voice, slightly soft, speak slowly with gentle pauses"
```

### Long Text TTS (Auto-Chunking)

For texts longer than ~500 characters, use auto-chunking to avoid memory issues:

**Option 1: Manual script**
```bash
# Split text into sentences and generate separately
python3  texts.txt  ~/voice_templates.txt 500 chars |
| Pronunciation issues | Use phonetic spelling or hyphens: "AI" → "A I", "COVID" → "Co-vid" |

### Performance Tips

1. **First run is slow**: Model downloads ~2GB on first use
2. **Keep sentences together**: Don't split mid-sentence
3. **Simple prompts work better**: Avoid overly complex instructions
4. **Use --verbose**: See detailed output for debugging

### Debug Mode

```bash
# Verbose output
mlx_audio.tts.generate --verbose --text "Hello" --output test.wav

# Check model cache
ls -la ~/.cache/huggingface/hub/ | grep mlx

# Check disk space
df -h ~/.cache/huggingface/

# Test with minimal text
mlx_audio.tts.generate --text "Test" --output /tmp/test.wav
```

## References

- [MLX-Audio GitHub](https://github.com/Blaizzy/mlx-audio)
- [Qwen3-TTS Model](https://huggingface.co/mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-8bit)
- [Qwen3-ASR Model](https://huggingface.co/mlx-community/Qwen3-ASR-0.6B-bf16)
- [ModelScope](https://www.modelscope.cn/)
- [HuggingFace Mirror](https://hf-mirror.com/)

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [renky1025](https://github.com/renky1025)
- **Source:** [renky1025/agent-skills](https://github.com/renky1025/agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** yes
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-renky1025-agent-skills-mlx-tts
- Seller: https://agentstack.voostack.com/s/renky1025
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.