--- title: "Qwen3-TTS | Micdrop" description: "Local text to speech with Qwen3-TTS, ten languages and style instructions from one checkpoint." url: "https://micdrop.dev/docs/ai-integration/provided-integrations/qwen-tts" --- * [Getting Started](/docs/getting-started) * [Client (Browser)](/docs/client) * [Installation](/docs/client/installation) * [React Hooks](/docs/client/react-hooks) * [Start/Stop Call](/docs/client/start-stop-call) * [Pause/Resume Call](/docs/client/pause-resume-call) * [Mute/Unmute Call](/docs/client/mute-unmute-call) * [Call State](/docs/client/call-state) * [Display Conversation Messages](/docs/client/display-conversation-messages) * [Handling Tool Calls](/docs/client/handling-tool-calls) * [Device Management](/docs/client/devices-management) * [Voice Activity Detection (VAD)](/docs/client/vad) * [Turn Detection](/docs/client/turn-detection) * [Reducing Latency](/docs/client/latency) * [Error Handling](/docs/client/error-handling) * Utility Classes * [Mic](/docs/client/utility-classes/mic) * [MicdropClient](/docs/client/utility-classes/micdrop-client) * [MicRecorder](/docs/client/utility-classes/mic-recorder) * [Speaker](/docs/client/utility-classes/speaker) * [Client (React Native)](/docs/react-native) * [Installation](/docs/react-native/installation) * [Hooks and Call State](/docs/react-native/hooks) * [Audio Output and Devices](/docs/react-native/audio-output) * [Voice Activity Detection (VAD)](/docs/react-native/vad) * [Turn Detection](/docs/react-native/turn-detection) * [Using Another Audio Library](/docs/react-native/custom-audio) * [Server (Node.js)](/docs/server) * [Installation](/docs/server/installation) * [With Fastify](/docs/server/with-fastify) * [With NestJS](/docs/server/with-nestjs) * [Auth and Parameters](/docs/server/auth-and-parameters) * [First Message](/docs/server/first-message) * [Dictation and Text-Only Calls](/docs/server/dictation) * [Partial Messages](/docs/server/partial-messages) * [Save Messages](/docs/server/save-messages) * [Resume a Conversation](/docs/server/resume-conversation) * [Recording Audio](/docs/server/recording-audio) * [Error Handling](/docs/server/error-handling) * [Tools](/docs/server/tools) * [Extract Value from Answer](/docs/server/extract) * [Auto End Call](/docs/server/auto-end-call) * [Semantic Turn Detection](/docs/server/semantic-turn-detection) * [Noise Filtering](/docs/server/noise-filtering) * [Micdrop Protocol](/docs/server/protocol) * [AI Integrations](/docs/ai-integration) * Provided Integrations * [AI SDK](/docs/ai-integration/provided-integrations/ai-sdk) * [Cartesia](/docs/ai-integration/provided-integrations/cartesia) * [ElevenLabs](/docs/ai-integration/provided-integrations/elevenlabs) * [Gladia](/docs/ai-integration/provided-integrations/gladia) * [Gradium](/docs/ai-integration/provided-integrations/gradium) * [Kokoro](/docs/ai-integration/provided-integrations/kokoro) * [Mistral](/docs/ai-integration/provided-integrations/mistral) * [OpenAI](/docs/ai-integration/provided-integrations/openai) * [Piper](/docs/ai-integration/provided-integrations/piper) * [Pocket TTS](/docs/ai-integration/provided-integrations/pocket-tts) * [Qwen3-TTS](/docs/ai-integration/provided-integrations/qwen-tts) * [Whisper](/docs/ai-integration/provided-integrations/whisper) * Custom Integrations * [Agent (LLM)](/docs/ai-integration/custom-integrations/custom-agent) * [Speech-to-Text (STT)](/docs/ai-integration/custom-integrations/custom-stt) * [Text-to-Speech (TTS)](/docs/ai-integration/custom-integrations/custom-tts) * Fallback Strategies * [FallbackAgent](/docs/ai-integration/fallback-strategies/agent-fallback) * [FallbackSTT](/docs/ai-integration/fallback-strategies/stt-fallback) * [FallbackTTS](/docs/ai-integration/fallback-strategies/tts-fallback) * [Local Models](/docs/ai-integration/local-models) * [Local LLM](/docs/ai-integration/local-models/agent) * [Local STT](/docs/ai-integration/local-models/speech-to-text) * [Local TTS](/docs/ai-integration/local-models/text-to-speech) * [Latency and Memory](/docs/ai-integration/local-models/performance) * [Explorations](/docs/ai-integration/local-models/explorations) * [MiniCPM5-2B](/docs/ai-integration/local-models/explorations/minicpm) * [Mistral 7B](/docs/ai-integration/local-models/explorations/mistral-7b) * [Voxtral Mini 3B](/docs/ai-integration/local-models/explorations/voxtral-stt) * [Voxtral TTS 4B](/docs/ai-integration/local-models/explorations/voxtral-tts) * [AuK and AuK-Flash](/docs/ai-integration/local-models/explorations/auk) * [IA Vocale Souveraine đŸ‡«đŸ‡·đŸ‡ȘđŸ‡ș](/docs/ai-integration/sovereign-voice-ai) * [Migration](/docs/migration) * [Upgrade to v3](/docs/migration/v3) [Micdrop](/) â€ș [Documentation](/docs/getting-started) â€ș [AI Integrations](/docs/ai-integration) â€ș Provided Integrations # Qwen3-TTS Local text to speech for [@micdrop/server](/docs/server), generated by an [mlx-audio](https://github.com/Blaizzy/mlx-audio) server holding the [Qwen3-TTS](https://github.com/QwenLM/Qwen3-TTS) weights. Qwen3-TTS is an open source text to speech model from Alibaba. It is the only local voice in Micdrop that speaks ten languages with one checkpoint: Chinese, English, French, German, Italian, Japanese, Korean, Portuguese, Russian and Spanish. It accepts an instruction such as `"Very happy"` or `"speak slowly"` that changes how a sentence is read, can design a voice from a description, and can clone a voice from three seconds of reference audio. It also needs more computation than the other local voices, because it generates audio with a language model. It needs a GPU and a server running next to your app. On a machine without a GPU, use [Piper](/docs/ai-integration/provided-integrations/piper) or [Kokoro](/docs/ai-integration/provided-integrations/kokoro). ## Installation Install the package: Terminal window ``` npm install @micdrop/qwen-tts ``` Start an mlx-audio server, on Python 3.10 or above: Terminal window ``` uv run --with "mlx-audio[server]" python -m mlx_audio.server --port 8000 ``` `pip install "mlx-audio[server]"` in a virtual environment does the same. The server downloads the checkpoint on its first request, 2.6 GB for the default one, and holds it in memory afterwards. mlx-audio uses the Apple Silicon GPU through MLX, so it only runs on a Mac. On another machine, any server that implements the route described in [Another server](#another-server) can replace it. ## Usage with MicdropServer ``` import { MicdropServer } from '@micdrop/server'import { Qwen3TTS } from '@micdrop/qwen-tts' const tts = new Qwen3TTS({ url: 'http://localhost:8000', voice: 'Ryan', language: 'en-US',}) // Use with MicdropServernew MicdropServer(socket, { tts, // ... other options}) ``` ## Usage without MicdropServer ``` import { Qwen3TTS } from '@micdrop/qwen-tts'import { Readable } from 'stream' const tts = new Qwen3TTS({ voice: 'Ryan' }) // Audio is raw PCM, 16 bits, 16 kHz, monotts.on('Audio', (chunk) => console.log('Audio:', chunk.length, 'bytes'))tts.on('Failed', (texts) => console.error('Failed:', texts)) tts.speak(Readable.from(['Hello! ', 'What can I do for you?'])) ``` ## Events Event Payload Description `Audio` `Buffer` A chunk of audio, PCM 16 bits, 16 kHz, mono, ready to be played. `Failed` `string[]` The server answered with an error, with the text that stayed unspoken. See the [TTS interface](/docs/ai-integration/custom-integrations/custom-tts) for the full contract. ## Options Option Type Default Description `url` `string` `http://localhost:8000` Address of the mlx-audio server `model` `string` `mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-6bit` Checkpoint the server loads `voice` `string` `Ryan` Preset speaker of the CustomVoice checkpoints `language` `string` Guessed from the text A code (`fr`), a locale (`fr-FR`) or the name the checkpoint uses (`french`) `instruct` `string` Optional How the sentence is read, or the voice to invent on VoiceDesign `refAudio` `string` Optional Path, on the server, to a few seconds of speech to clone `refText` `string` Optional What the reference audio says `streamingInterval` `number` `0.5` Audio generated before a chunk is sent, in seconds `temperature` `number` `0.9` Sampling temperature `topK` `number` `50` Sampling window, in number of candidates `topP` `number` `1` Sampling window, in cumulated probability `repetitionPenalty` `number` `1.05` Penalty on repeated audio tokens `maxTokens` `number` `500` Ceiling on the audio tokens of one sentence, 12.5 per second `warmup` `boolean` `true` Loads the checkpoint on the server at startup ## Voices The CustomVoice checkpoints include nine speakers, so changing the voice costs nothing at runtime. Each speaker was recorded in one language and can read all ten. The language of the call is set by `language`, not by the speaker. Speaker Recorded in `Ryan`, `Aiden` English `Vivian`, `Serena`, `Uncle_Fu` Chinese `Dylan`, `Eric` Chinese, Beijing and Sichuan dialects `Ono_Anna` Japanese `Sohee` Korean `language` accepts a locale such as `fr-FR`, a code such as `fr`, or the checkpoint name `french`. `resolveLanguage()` returns the value sent to the model. For a language outside the ten, it returns `auto`, and the model detects the language from the text. `QWEN_SPEAKERS` exports this list with the recording language of each voice. The demo uses it to fill its voice select. A voice recorded in Chinese reads French as accurately as an English one. In a test of nine French sentences across four speakers, Whisper transcribed eight word for word, and one had `"quatorze"` mispronounced. Expect an occasional mispronounced word with any speaker. ## Reading with an intention `instruct` describes how to read each sentence: ``` new Qwen3TTS({ voice: 'Serena', instruct: 'Warm and reassuring, speak slowly' }) ``` The instruction applies to every sentence of the call, so it describes the overall style of the assistant, not one answer. It changes how the speaker talks, not which speaker it is. ## Checkpoints `model` can be any Qwen3-TTS export the server can load. The server keeps each checkpoint it has loaded in memory. Checkpoint Downloads What it does `mlx-community/Qwen3-TTS-12Hz-1.7B-CustomVoice-6bit` 2.6 GB The default: nine speakers, style instructions `mlx-community/Qwen3-TTS-12Hz-0.6B-CustomVoice-6bit` 1.8 GB 100 ms faster, less accurate reading `mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-6bit` 2.6 GB Designs a voice from the description in `instruct` `mlx-community/Qwen3-TTS-12Hz-1.7B-Base-6bit` 2.6 GB Clones the voice of `refAudio` The 0.6B checkpoint is smaller and returns its first audio about 100 ms sooner. But it starts each sentence with half a second of silence, against a tenth of a second for the 1.7B, and it more often produces audio much longer than the sentence. The 8 bit export of the 1.7B is slower than real time on a MacBook Pro M2, so prefer the 6 bit one. ## Inventing a voice A VoiceDesign checkpoint has no preset speakers. It generates the voice from the description in `instruct`. ``` new Qwen3TTS({ model: 'mlx-community/Qwen3-TTS-12Hz-1.7B-VoiceDesign-6bit', instruct: 'A calm British man in his fifties, low pitch, unhurried', language: 'en-US',}) ``` ## Cloning a voice A Base checkpoint has no preset speakers either. It reads a sentence in the voice of a recording, given the recording and its transcript. The mlx-audio server opens the file, so the path must exist on the machine that runs the server. ``` new Qwen3TTS({ model: 'mlx-community/Qwen3-TTS-12Hz-1.7B-Base-6bit', refAudio: '/srv/voices/marie.wav', refText: 'Bonjour, je suis Marie et je vous accompagne aujourd’hui.', language: 'fr-FR',}) ``` Clone a voice only with the consent of the person it belongs to. ## How the audio arrives The server decodes audio tokens as they are generated, so a sentence starts playing before it is fully generated. `streamingInterval` sets the length of each chunk, half a second by default. A smaller value gives an earlier first word, but adds a decoder pass per chunk. Sentences are generated one after the other, so they stay in order and the GPU handles one sentence at a time. When the user interrupts, the package closes the connection and the server stops generating. ## Another server The package sends `POST /v1/audio/speech` with the OpenAI fields (`model`, `input`, `voice`) plus the Qwen ones (`instruct`, `lang_code`, `ref_audio`, `ref_text`), sets `stream`, and reads raw PCM at 24 kHz with `response_format: "pcm"`. Any server that implements this route can replace mlx-audio. ## Documentation Read the [guide on running Micdrop with local models](/docs/ai-integration/local-models) to combine Qwen3-TTS with a local LLM and local speech to text, and the [local TTS page](/docs/ai-integration/local-models/text-to-speech) to compare it with the other three. ## License Qwen3-TTS is released under the Apache 2.0 license, including the weights, so it can be used commercially. Cloning a person’s voice still requires their consent. [Previous← Pocket TTS](/docs/ai-integration/provided-integrations/pocket-tts)[NextWhisper →](/docs/ai-integration/provided-integrations/whisper) On this page * [Installation](#installation) * [Usage with MicdropServer](#usage-with-micdropserver) * [Usage without MicdropServer](#usage-without-micdropserver) * [Events](#events) * [Options](#options) * [Voices](#voices) * [Reading with an intention](#reading-with-an-intention) * [Checkpoints](#checkpoints) * [Inventing a voice](#inventing-a-voice) * [Cloning a voice](#cloning-a-voice) * [How the audio arrives](#how-the-audio-arrives) * [Another server](#another-server) * [Documentation](#documentation) * [License](#license)