IndexTTS2 on a Mac: Setup, Emotion Control, License

Direct answer: IndexTTS2 is bilibili's open-weight zero-shot text-to-speech model, and it does not run in Murmur. To use it on a Mac you clone the official repository, install its Python environment with uv, download the weights, and start the local Gradio web UI, then troubleshoot Apple's MPS backend yourself, because the README documents CUDA and never lists macOS as a supported path.

That last sentence is the part most tutorials skip. IndexTTS2 is genuinely interesting for two reasons: it separates timbre from emotion, and the paper describes precise duration control for an autoregressive model, which is unusual. But those features are research and demo features first. This guide separates what the README and paper actually claim from what a Mac user can expect on the first afternoon.

What IndexTTS2 is, per the official repository

The repository describes IndexTTS as an industrial-level controllable zero-shot TTS system that clones a voice from a single reference audio clip. Only clone a voice you own or have written permission to use. The IndexTTS-2.5 model card says the model does not verify that the speaker in a reference clip consented and that obtaining consent is the user's responsibility, and the project's disclaimer forbids synthesizing the voice of any unauthorized individual, political figure or public figure. The private voice cloning guide covers the practical side. IndexTTS2 is the September 2025 release, and its paper is arXiv 2506.21619. The model is a cascade of three parts: an autoregressive text-to-semantic transformer, a non-autoregressive semantic-to-mel module trained with flow matching, and a BigVGANv2 vocoder. The paper says the system was trained on 55,000 hours of data, including 30,000 Chinese and 25,000 English hours, on eight NVIDIA A100 80GB GPUs.

The README now leads with a newer release, IndexTTS-2.5, dated August 2026. Its Hugging Face card lists Chinese, English, Japanese, Spanish, and Arabic, a GPT backbone of roughly 0.8B parameters, 22.05 kHz output, and a requirement of Python 3.10 to 3.11 plus an NVIDIA GPU with roughly 6 GB of VRAM for inference. That card is for 2.5, not for the 2.0 weights, so do not assume the same environment applies to both. If you only need the 2.0 paper and code, the older weights are still published under IndexTeam/IndexTTS-2.

Emotion control: what the parameters actually do

The paper's main claim is a disentanglement between speaker identity and emotional expression. In practice the repository exposes that as a few inputs on the infer call, and the README documents each one.

• A separate emotional reference clip, passed as emo_audio_prompt, while spk_audio_prompt supplies the timbre.
• An intensity dial, emo_alpha, valid from 0.0 to 1.0 with a default of 1.0. Lower values blend the emotional reference in more gently.
• An eight-value emotion vector in the fixed order happy, angry, sad, afraid, disgusted, melancholic, surprised, calm. You can use this instead of an emotional clip.
• Text-driven emotion with use_emo_text, or a separate description string with emo_text, so the spoken script and the emotion prompt can differ.
• A use_random switch. The README warns that random sampling reduces voice cloning fidelity, so it is not a free quality upgrade.

There is one trap worth flagging. On IndexTTS-2.5, use_emo_text=True requires the model to be constructed with use_qwen_emo=True; otherwise inference raises a RuntimeError. The 2.5 model card states the same thing in its limitations section. If you copy a 2.0 example into a 2.5 environment and it fails at the emotion step, this is usually why.

The paper explains where the emotion signal comes from. A Conformer-based emotion perceiver extracts it from the style prompt, and a gradient reversal layer pushes the representation away from speaker identity during training. For text descriptions, the team distilled emotion distributions from Deepseek-r1 into a Qwen-3-1.7b student with LoRA. That is a sensible design, and it is also why text-driven emotion deserves the most auditioning: you are trusting a small classifier to interpret a sentence.

Duration control: read the release note carefully

The paper's headline contribution is a duration scheme for autoregressive TTS. It describes two modes. In the first, you specify the number of semantic tokens to generate, which fixes the length of the output. In the second, the model generates freely and follows the prosody of the prompt. The paper reports token number error rates below 0.02 percent at original duration on its SeedTTS test sets, which is a strong claim for an autoregressive model.

Then read the repository news entry for the 2025 release: the duration control feature is described as not yet enabled in that release. That sentence matters more than any benchmark table if your plan is frame-accurate dubbing. IndexTTS-2.5 adds duration_factor, a speed control valid from 0.5 to 2.0, where values above 1.0 slow the speech and values below 1.0 speed it up. Speed scaling is useful, but it is not the same thing as specifying an exact token count. Check the current release notes before you promise a client a fixed-length read.

Installing IndexTTS2 on a Mac, following the README

These steps come from the repository README. It is written for a CUDA machine, so treat the Mac-specific parts as unsupported territory rather than instructions.

1. Install git, then clone the repository: git clone https://github.com/index-tts/index-tts.git && cd index-tts. Example audio is fetched on demand the first time the WebUI starts, so Git LFS is no longer required.
2. Install uv, which the README calls required for a reliable installation: pip install -U uv.
3. Create the environment with uv sync --all-extras. This creates a .venv directory and installs the pinned Python version and dependencies. On a Mac, --all-extras also pulls DeepSpeed and a CUDA-only accel extra (flash-attn and NVIDIA runtime packages), which the README's extras tip does not discuss for macOS. I have not tested it on a Mac. Dropping the flag and adding --extra webui is the leaner path.
4. Download weights with uv tool install "huggingface-hub" and then hf download IndexTeam/IndexTTS-2 --local-dir=checkpoints_2, or use the ModelScope equivalent. IndexTTS-2.5 uses checkpoints instead.
5. Run uv run webui.py for the current default release, or uv run webui.py --version 2 --model_dir ./checkpoints_2 for 2.0, then open http://127.0.0.1:7860.
6. Optionally run uv run tools/gpu_check.py to see what the project detects. On Apple Silicon it should report whether Apple MPS is available, and it will not find a CUDA device.

Two environment details are easy to miss. The README says not to activate a virtual environment manually before running uv commands, because that can create dependency conflicts; uv activates the project environment itself. It also notes that auxiliary models, including w2v-bert-2.0, the MaskGCT semantic codec, CAMPPlus, and BigVGAN, are not in the repository and are downloaded into a cache on first run. Budget disk space for those separately from the main checkpoint.

Should you run it yourself?

The license is not MIT, and it is worth reading twice

The repository LICENSE is the bilibili Model Use License Agreement, not an OSI license. It grants a worldwide, non-exclusive, non-transferable, royalty-free limited license to use the model and derivative works, subject to conditions that matter to companies.

• If your products had more than 100 million monthly active users in the previous month, or your annual revenue exceeded RMB 1 billion in the previous year, you must request a separate license in writing.
• You may not use the model or a derivative to improve another AI model, except for IndexTTS2 itself, its derivatives, or non-commercial models.
• High-risk deployments are called out explicitly, including medical diagnosis, autonomous driving, military use, critical infrastructure, and large-scale biometric surveillance.
• If you distribute a derivative, you must keep the copyright notices and the agreement, and state that the original rights holder does not endorse the derivative.
• The agreement is governed by the laws of the People's Republic of China, with disputes going to the Shanghai Arbitration Commission. The Chinese text prevails if the versions differ.

The code and the weights are covered by that same agreement, and the auxiliary models are separate downloads with their own terms. If you plan to sell output, read the commercial license checklist for local TTS models before you build a product around any of it.

What can go wrong on a Mac

These are not hypothetical. They are issues in the official repository, some still open, and they are the reason macOS is a weekend project rather than a supported platform.

• MPS channel limit. Issue 193 reports NotImplementedError: Output channels > 65536 not supported at the MPS device on an M3 Max. It was filed in June 2025 against the original IndexTTS release, before IndexTTS-2 existed, so it shows the same MPS operator limit rather than an IndexTTS2 result. PyTorch's own error text suggests PYTORCH_ENABLE_MPS_FALLBACK=1, though the reporter's script already set it and still failed, and running with --device cpu works but is very slow. Commenters disagree about whether newer PyTorch builds fix it: one M4 user reported success with torch 2.7.0, an M1 Max user reported the same error.
• Memory pressure. Issue 414 describes RAM climbing from a normal 10 to 20 GB to 249 GB on a 256 GB M3 Ultra, followed by swap and a system crash. A commenter's fix was setting PYTORCH_MPS_LOW_WATERMARK_RATIO and PYTORCH_MPS_HIGH_WATERMARK_RATIO before launching. Another user in the same thread estimated 20 to 30 GB of memory for a 10 second clone.
• Audio export failures. Issue 465 reports a torchaudio save error on macOS Tahoe, with the reporter saying it was solved by moving to PyTorch in the stable channel.
• Disk space. In issue 414, one user described the drive filling to within 1 or 2 GB after setup and a couple of generations. Check free space before downloading checkpoints and caches.
• DeepSpeed. The README warns that DeepSpeed may be difficult to install on Windows and tells those users to drop --all-extras. There is no equivalent macOS guidance, so expect to manage it yourself.

None of this means the model is bad. It means the supported path is CUDA, and Apple's Metal backend is being exercised by users rather than maintained by the project. If you want a lower-risk Mac workflow, the no-Python local TTS options for Mac avoid this stack entirely, and the 16 GB Mac model guide covers what actually fits in unified memory.

Lookalike sites and domains

The README has an explicit caution box. It says the only official channel maintained by the core team is https://github.com/index-tts/index-tts, and that any other websites or services are not official, with no guarantee of security, accuracy, or timeliness. Domains such as indextts.org and indextts.online are independent third-party sites whose own pages say they are not affiliated with the project, and the README says GitHub is the only official channel. indextts.online is a hosted, paid generator, so signing in or downloading there is not the official model. Weights and installers should come from the GitHub repository or the linked Hugging Face and ModelScope organizations, not from a third-party download page.

If you want the same job without a terminal

IndexTTS2's appeal is expressive cloning with direct control over emotion. If your actual job is a finished narration, a course module, or a batch of videos, the model choice matters less than the workflow around it: reviewing takes, fixing one bad line, keeping speakers consistent, and exporting a file. That is the gap a studio app fills, and it is also the tradeoff described in the local voice studio versus DIY comparison.

Murmur is a local-first macOS voice studio for Apple Silicon and Intel Macs running macOS 15 or later. It does not run IndexTTS, and this article is not a workaround for that. It ships Kokoro bundled, and its catalog also includes Chatterbox Turbo, Chatterbox Multilingual, Qwen3-TTS Base, Voice Design, SparkTTS, Fish Audio S2 Pro, Breeze TTS 2, and OmniVoice. Kokoro runs on any supported Mac; the other models need at least 16 GB of unified memory, according to the app's model policy. Everything runs on the machine, with no per-character billing.

When Murmur is the wrong choice

Be clear about the boundaries. The app is not a Windows, iPhone, Android, or browser product. It does not do live or real-time streaming speech, it does not do speech to text, and it has no shared cloud workspace. It also cannot reproduce IndexTTS2's specific emotion vector API, and it does not promise frame-accurate duration. If those are your requirements, run IndexTTS2 from the official repository or use a tool built for that job. Murmur is the better fit when you want a repeatable Mac workflow and are willing to choose from the models it actually ships.

Frequently asked questions