feat: add CosyVoice3 MLX implementation

[walkoncross]

Summary

Adds a full MLX port of CosyVoice3 (mlx_audio/tts/models/cosyvoice3/), following the existing model contract used by other TTS models in this repo (e.g. chatterbox, spark).

• Pipeline: text → LLM (Qwen2 speech-token backbone) → speech tokens → flow (DiT-based CausalMaskedDiffWithDiT / CFM) → mel → HiFT vocoder (causal) → waveform.
• Generation modes: zero-shot voice cloning, cross-lingual synthesis, and instruction-based (instruct2) generation, matching the reference CosyVoice3 Python implementation's behavior.
• Speaker presets: spk2info system for caching/reusing zero-shot speaker prompts (--add_spk, --save_spkinfo, --load_spkinfo).
• Text frontend: ported text normalization pipeline (Chinese blank/bracket handling, English number spelling) and full CosyVoice3Tokenizer special-token registration for fine-grained control tokens.
• Weight conversion: sanitize/routing logic wired into convert.py so official CosyVoice3 checkpoints can be converted to MLX weights.
• Correctness fixes along the way (each validated against the PyTorch reference under /CosyVoice/cosyvoice): causal HiFT rewrite, DiT RoPE pairing/application order, CFM noise seeding to remove pitch bias, sample-rate handling for timbre cloning, prompt-feature/silence-token alignment with the reference, and a defensive post-hoc fix for a rare stochastic LLM-sampling tail-hiss artifact (acoustic-signature detection + fade, since the exact triggering token sequence could not be reliably reproduced after 100+ attempts — see README.md under this model's ## Status section for the full investigation).
• Docs: CLI usage examples (zero-shot, cross-lingual, instruct2, speaker presets) with bundled reference audio assets, and a ## Status section tracking known issues/investigations.

45 commits, squash-mergeable if preferred. See individual commit messages for a detailed history of the implementation and each fix.

Test plan

• pytest mlx_audio/tts/tests/test_cosyvoice3.py — 31 passed (2 pre-existing failures unrelated to this branch, confirmed via git stash against main: TestLLM::test_autoregressive_decode, TestModelIntegration::test_generate_end_to_end_with_mock_frontend, both AttributeError on an incomplete MockFrontEnd test double)
• End-to-end generate() validated against real CosyVoice3-0.5B checkpoint weights for zero-shot, cross-lingual, and instruct2 modes
• HiFT/flow determinism verified (fixed mel → bit-identical waveform across repeated calls)
• Tail-hiss fix verified: real reported bug file -28.1dB → -120dB after fade; synthetic clean-tail audio left bit-identical (no false positives)

[lucasnewman]

@walkoncross Thanks for the submission! This needs some cleanup, I left a few comments inline. Also, the examples should just live in the README.md, we don't want model-specific artifacts in there. If you can make those changes we can consider this.

[lucasnewman]

See comments above.

[walkoncross]

Hi @lucasnewman, thanks for the review! All the feedback has been addressed:

1. Implementation-specific / porting notes — removed from config.py and elsewhere; only comments that aid understanding remain.
2. sampling.py — nucleus_sampling / random_sampling are now thin wrappers around mlx_lm's make_sampler; ras_sampling stays separate because it needs repetition-aware masking.
3. generate.py — cross_lingual and friends are no longer part of the standard generate_audio signature; they're read from **kwargs and used internally.
4. .gitignore — reverted.
5. Examples — removed the model-specific examples/cosyvoice3/ artifacts (audio + prompt files). The examples now live in mlx_audio/tts/models/cosyvoice3/README.md and reuse the shared examples/voice_prompts/ samples, with a note for supplying your own reference clip for non-English voices.

I've also resolved the corresponding review threads. Could you take another look when you get a chance?

[github-actions]

⚠️ GitHub does not mark 3 commits in this PR as Verified.

Please sign every commit, then update the PR. You can review the commits on the commits tab and follow GitHub's commit-signing guide if needed.

[walkoncross]

Hi @lucasnewman — a quick follow-up on this. All four review threads from your earlier pass are now resolved, and the corresponding fixes are in:

1. Porting notes removed — implementation-specific comments taken out of config.py and elsewhere; only comments that aid understanding remain.
2. sampling.py — nucleus_sampling / random_sampling are now thin wrappers around mlx_lm's make_sampler; ras_sampling stays separate because it needs repetition-aware masking.
3. generate.py — cross_lingual and friends are no longer part of the standard generate_audio signature; they're read from extra kwargs and used internally.
4. .gitignore — reverted.
5. Examples — removed the model-specific examples/cosyvoice3/ artifacts; examples now live in mlx_audio/tts/models/cosyvoice3/README.md and reuse the shared examples/voice_prompts/ samples.

I also fixed the CI pre-commit failure flagged earlier: the branch hadn't been formatted against the pinned black/isort versions. I ran pre-commit locally and pushed the formatting fixes (latest head 8b2d686), so the code now passes black + isort.

One thing I can't do from my side: the Docs and Tests and Checks workflows on this fork PR are stuck in action_required — they need approval before they'll run on the latest head. Could you approve the runs and take another look when you get a chance? Thanks!

[github-actions]

⚠️ These MLX-Audio test jobs fail only on this PR while the current main baseline passes them:

• core

Review the failing CI output and run the corresponding command from .github/workflows/tests.yml locally. If a failure is unrelated, leave a note for the maintainers.