Upload folder using huggingface_hub

Browse files

Files changed (4) hide show

README.md +17 -50
qwen3-tts-12hz-1.7b-base/README.md +132 -0
qwen3-tts-12hz-1.7b-customvoice/README.md +132 -0
qwen3-tts-12hz-1.7b-voicedesign/README.md +132 -0

README.md CHANGED Viewed

@@ -19,7 +19,7 @@ tags:
 **Image and music models converted for native MLX inference on Apple silicon**
-![MLX](https://img.shields.io/badge/MLX-0.32-1f6feb) ![platform](https://img.shields.io/badge/platform-Apple%20silicon-black) ![precision](https://img.shields.io/badge/precision-bf16%20and%204--bit-6f42c1) [![licence](https://img.shields.io/badge/licence-Apache--2.0%20and%20MIT-brightgreen)](https://huggingface.co/kruatech/studio-mlx/blob/main/LICENSES.md)
 </div>
@@ -34,60 +34,31 @@ Pick one line. The image models need the shared encoder, the music model does no
 ```bash
 pip install "huggingface_hub[hf_xet]"
-# Z-Image-Turbo - 6.14 GiB
-hf download kruatech/studio-mlx --local-dir bundles \
-  --include "shared/qwen3-4b-text-encoder-q4/*" "z-image-turbo-q4/*"
-# FLUX.2 [klein] 4B - 4.79 GiB
-hf download kruatech/studio-mlx --local-dir bundles \
-  --include "shared/qwen3-4b-text-encoder-q4/*" "flux2-klein-4b-q4/*"
-# ACE-Step 1.5 Turbo - 9.38 GiB
-hf download kruatech/studio-mlx --local-dir bundles --include "ace-step-1.5-turbo/*"
 ```
 The `-q4` folders sit at the top level rather than inside the bf16 ones, so an include pattern fetches one precision without dragging in the other.
 ## What is inside
-| folder                                                               | what it does                                           | precision | size      | licence    |
-|----------------------------------------------------------------------|--------------------------------------------------------|-----------|-----------|------------|
-| [`shared/qwen3-4b-text-encoder`](shared/qwen3-4b-text-encoder)       | Shared text encoder for both image models              | `bf16`    | 7.51 GiB  | Apache-2.0 |
-| [`shared/qwen3-4b-text-encoder-q4`](shared/qwen3-4b-text-encoder-q4) | Shared text encoder for both image models              | `4-bit`   | 2.59 GiB  | Apache-2.0 |
-| [`z-image-turbo`](z-image-turbo)                                     | Text to image, 6B, 8 steps                             | `bf16`    | 11.62 GiB | Apache-2.0 |
-| [`z-image-turbo-q4`](z-image-turbo-q4)                               | Text to image, 6B, 8 steps                             | `4-bit`   | 3.55 GiB  | Apache-2.0 |
-| [`flux2-klein-4b`](flux2-klein-4b)                                   | Text to image and multi-reference editing, 4B, 4 steps | `bf16`    | 7.39 GiB  | Apache-2.0 |
-| [`flux2-klein-4b-q4`](flux2-klein-4b-q4)                             | Text to image and multi-reference editing, 4B, 4 steps | `4-bit`   | 2.20 GiB  | Apache-2.0 |
-| [`ace-step-1.5-turbo`](ace-step-1.5-turbo)                           | Text to music, 48 kHz stereo                           | `bf16`    | 9.38 GiB  | MIT        |
 ## bf16 or 4-bit
 **Use the 4-bit folders.** Quantization is MLX affine: 4 bits per weight with a bf16 scale and bias for every group of 64, about 4.5 bits per weight and 28-30% of the bf16 size. Normalizations, modulations and the encoder's embedding table stay in bf16, and matrix multiplication still runs in bf16 - the gain is memory and load time, not integer arithmetic.
-| component           | bf16      | 4-bit    | ratio |
-|---------------------|-----------|----------|-------|
-| Z-Image DiT         | 11.46 GiB | 3.40 GiB | 30%   |
-| klein DiT           | 7.22 GiB  | 2.03 GiB | 28%   |
-| shared text encoder | 7.51 GiB  | 2.58 GiB | 34%   |
-The encoder ratio is higher on purpose: its 151936 x 2560 embedding table stays in bf16, because quantizing it moved the encoder output by 3e-01 in testing.
-What that buys, on one klein run at 1024 px with 4 steps:
-| phase                 | bf16  | 4-bit |
-|-----------------------|-------|-------|
-| read the text encoder | 40 s  | 22 s  |
-| read the transformer  | 58 s  | 19 s  |
-| 4 diffusion steps     | 35 s  | 32 s  |
-| total                 | 170 s | 73 s  |
-The steps themselves barely change: multiplication still happens in bf16, the kernel unpacks each group of 64 weights on the fly. The saving is disk reading, which is why it depends on your storage - these figures come from an external volume at about 0.2 GiB/s.
 Output quality was indistinguishable: the same prompt and seed gave two clean images that differ the way two seeds differ. The bf16 folders exist as the accuracy reference a port can be checked against.
-`ace-step-1.5-turbo` has no 4-bit variant. It is published as converted upstream, and its own card reports that its DiT has to run in float32 - bf16 already fails accuracy at `rel_max 1.45e-01`, so quantizing further is not on the table.
 ## Bundle layout
 ```
@@ -184,15 +155,11 @@ Stages run one at a time and release their weights, so peak memory is set by the
 Derivatives of three upstream models under two licences. Each folder carries the licence of its upstream model.
-| folder                            | upstream                                                                                      | licence                                                   |
-|-----------------------------------|-----------------------------------------------------------------------------------------------|-----------------------------------------------------------|
-| `shared/qwen3-4b-text-encoder`    | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
-| `shared/qwen3-4b-text-encoder-q4` | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
-| `z-image-turbo`                   | [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)                   | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
-| `z-image-turbo-q4`                | [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)                   | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
-| `flux2-klein-4b`                  | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
-| `flux2-klein-4b-q4`               | [black-forest-labs/FLUX.2-klein-4B](https://huggingface.co/black-forest-labs/FLUX.2-klein-4B) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
-| `ace-step-1.5-turbo`              | [ACE-Step/Ace-Step1.5](https://huggingface.co/ACE-Step/Ace-Step1.5)                           | [MIT](https://opensource.org/license/mit)                 |
 The shared text encoder is redistributed from inside the two image repositories, both Apache-2.0. Conversion tooling and these cards: MIT.

 **Image and music models converted for native MLX inference on Apple silicon**
+![MLX](https://img.shields.io/badge/MLX-0.32-1f6feb) ![platform](https://img.shields.io/badge/platform-Apple%20silicon-black) ![precision](https://img.shields.io/badge/precision-bf16%20and%204--bit-6f42c1) [![licence](https://img.shields.io/badge/licence-Apache--2.0%20and%20MIT-brightgreen)](LICENSES.md)
 </div>
 ```bash
 pip install "huggingface_hub[hf_xet]"
 ```
 The `-q4` folders sit at the top level rather than inside the bf16 ones, so an include pattern fetches one precision without dragging in the other.
 ## What is inside
+| folder                                                               | what it does                             | precision | size     | licence    |
+|----------------------------------------------------------------------|------------------------------------------|-----------|----------|------------|
+| [`qwen3-tts-12hz-1.7b-base`](qwen3-tts-12hz-1.7b-base)               | Voice cloning from a reference recording | `bf16`    | 4.23 GiB | Apache-2.0 |
+| [`qwen3-tts-12hz-1.7b-customvoice`](qwen3-tts-12hz-1.7b-customvoice) | Nine preset voices, ten languages        | `bf16`    | 4.21 GiB | Apache-2.0 |
+| [`qwen3-tts-12hz-1.7b-voicedesign`](qwen3-tts-12hz-1.7b-voicedesign) | Describe a voice in words and get it     | `bf16`    | 4.21 GiB | Apache-2.0 |
 ## bf16 or 4-bit
 **Use the 4-bit folders.** Quantization is MLX affine: 4 bits per weight with a bf16 scale and bias for every group of 64, about 4.5 bits per weight and 28-30% of the bf16 size. Normalizations, modulations and the encoder's embedding table stay in bf16, and matrix multiplication still runs in bf16 - the gain is memory and load time, not integer arithmetic.
+|                                   | bf16      | 4-bit    |
+|-----------------------------------|-----------|----------|
+| Z-Image DiT                       | 11.46 GiB | 3.40 GiB |
+| klein DiT                         | 7.22 GiB  | 2.03 GiB |
+| shared encoder                    | 7.51 GiB  | 2.58 GiB |
+| klein 512 px, 4 steps, wall clock | 170 s     | 73 s     |
 Output quality was indistinguishable: the same prompt and seed gave two clean images that differ the way two seeds differ. The bf16 folders exist as the accuracy reference a port can be checked against.
 ## Bundle layout
 ```
 Derivatives of three upstream models under two licences. Each folder carries the licence of its upstream model.
+| folder                            | upstream                                                                                            | licence                                                   |
+|-----------------------------------|-----------------------------------------------------------------------------------------------------|-----------------------------------------------------------|
+| `qwen3-tts-12hz-1.7b-base`        | [Qwen/Qwen3-TTS-12Hz-1.7B-Base](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-Base)               | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
+| `qwen3-tts-12hz-1.7b-customvoice` | [Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
+| `qwen3-tts-12hz-1.7b-voicedesign` | [Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign) | [Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0) |
 The shared text encoder is redistributed from inside the two image repositories, both Apache-2.0. Conversion tooling and these cards: MIT.

qwen3-tts-12hz-1.7b-base/README.md ADDED Viewed

	@@ -0,0 +1,132 @@

+---
+license: apache-2.0
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+base_model:
+- Qwen/Qwen3-TTS-12Hz-1.7B-Base
+---
+<div align="center">
+# Qwen3-TTS 12 Hz 1.7B Base for MLX, bf16
+**Voice cloning from a reference recording**
+![precision](https://img.shields.io/badge/precision-bf16-6f42c1) ![size](https://img.shields.io/badge/size-4.23%20GiB-1f6feb) [![licence](https://img.shields.io/badge/licence-Apache--2.0-brightgreen)](https://www.apache.org/licenses/LICENSE-2.0) [![part of](https://img.shields.io/badge/part%20of-studio--mlx-black)](https://huggingface.co/kruatech/studio-mlx)
+</div>
+Text to speech at 24 kHz. A talker generates 16 codec codes per frame at 12 Hz - the first sampled directly, the remaining 15 filled in by a code predictor - and a codec turns those codes into a waveform.
+Converted from [Qwen/Qwen3-TTS-12Hz-1.7B-Base](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-Base) for native MLX inference on Apple silicon.
+## Download
+Self-contained. It does not use the shared Qwen3-4B encoder that the image models share; its own text stack and codec are inside this folder.
+```bash
+pip install "huggingface_hub[hf_xet]"
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "qwen3-tts-12hz-1.7b-base/*"
+```
+## Files
+| component        | class                            | precision | tensors | size     |
+|------------------|----------------------------------|-----------|---------|----------|
+| model            | Qwen3TTSForConditionalGeneration | keep      | 480     | 3.59 GiB |
+| speech_tokenizer | Qwen3TTSTokenizerV2Model         | keep      | 496     | 651 MiB  |
+Folder total: **4.23 GiB**. `manifest.json` carries SHA-256, byte sizes and tensor counts for every file.
+## How this model works in MLX
+- Adds an ECAPA-TDNN speaker encoder (38 convolutions) on top of the talker, which the other two variants do not have. Clone a voice by supplying a reference recording and its transcript.
+- `model` holds the talker and the code predictor; `speech_tokenizer` holds the codec, whose 52 Conv1d and 6 ConvTranspose1d weights are permuted to MLX layout.
+- No 4-bit variant yet: quantization needs an MLX implementation of these modules, which does not exist at the time of writing.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licence
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), the licence of the upstream model. Conversion tooling and this card: MIT. The upstream card states usage restrictions that redistribution does not repeal.

qwen3-tts-12hz-1.7b-customvoice/README.md ADDED Viewed

	@@ -0,0 +1,132 @@

+---
+license: apache-2.0
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+base_model:
+- Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice
+---
+<div align="center">
+# Qwen3-TTS 12 Hz 1.7B Customvoice for MLX, bf16
+**Nine preset voices, ten languages**
+![precision](https://img.shields.io/badge/precision-bf16-6f42c1) ![size](https://img.shields.io/badge/size-4.21%20GiB-1f6feb) [![licence](https://img.shields.io/badge/licence-Apache--2.0-brightgreen)](https://www.apache.org/licenses/LICENSE-2.0) [![part of](https://img.shields.io/badge/part%20of-studio--mlx-black)](https://huggingface.co/kruatech/studio-mlx)
+</div>
+Text to speech at 24 kHz. A talker generates 16 codec codes per frame at 12 Hz - the first sampled directly, the remaining 15 filled in by a code predictor - and a codec turns those codes into a waveform.
+Converted from [Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-CustomVoice) for native MLX inference on Apple silicon.
+## Download
+Self-contained. It does not use the shared Qwen3-4B encoder that the image models share; its own text stack and codec are inside this folder.
+```bash
+pip install "huggingface_hub[hf_xet]"
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "qwen3-tts-12hz-1.7b-customvoice/*"
+```
+## Files
+| component        | class                            | precision | tensors | size     |
+|------------------|----------------------------------|-----------|---------|----------|
+| model            | Qwen3TTSForConditionalGeneration | keep      | 404     | 3.57 GiB |
+| speech_tokenizer | Qwen3TTSTokenizerV2Model         | keep      | 496     | 651 MiB  |
+Folder total: **4.21 GiB**. `manifest.json` carries SHA-256, byte sizes and tensor counts for every file.
+## How this model works in MLX
+- Pick a speaker by name and optionally steer delivery with an instruction in plain language. The speaker and language tables live in `config/model.json`.
+- `model` holds the talker and the code predictor; `speech_tokenizer` holds the codec, whose 52 Conv1d and 6 ConvTranspose1d weights are permuted to MLX layout.
+- No 4-bit variant yet: quantization needs an MLX implementation of these modules, which does not exist at the time of writing.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licence
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), the licence of the upstream model. Conversion tooling and this card: MIT. The upstream card states usage restrictions that redistribution does not repeal.

qwen3-tts-12hz-1.7b-voicedesign/README.md ADDED Viewed

	@@ -0,0 +1,132 @@

+---
+license: apache-2.0
+library_name: mlx
+tags:
+- mlx
+- mlx-swift
+- apple-silicon
+base_model:
+- Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign
+---
+<div align="center">
+# Qwen3-TTS 12 Hz 1.7B Voicedesign for MLX, bf16
+**Describe a voice in words and get it**
+![precision](https://img.shields.io/badge/precision-bf16-6f42c1) ![size](https://img.shields.io/badge/size-4.21%20GiB-1f6feb) [![licence](https://img.shields.io/badge/licence-Apache--2.0-brightgreen)](https://www.apache.org/licenses/LICENSE-2.0) [![part of](https://img.shields.io/badge/part%20of-studio--mlx-black)](https://huggingface.co/kruatech/studio-mlx)
+</div>
+Text to speech at 24 kHz. A talker generates 16 codec codes per frame at 12 Hz - the first sampled directly, the remaining 15 filled in by a code predictor - and a codec turns those codes into a waveform.
+Converted from [Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign](https://huggingface.co/Qwen/Qwen3-TTS-12Hz-1.7B-VoiceDesign) for native MLX inference on Apple silicon.
+## Download
+Self-contained. It does not use the shared Qwen3-4B encoder that the image models share; its own text stack and codec are inside this folder.
+```bash
+pip install "huggingface_hub[hf_xet]"
+hf download kruatech/studio-mlx --local-dir bundles \
+  --include "qwen3-tts-12hz-1.7b-voicedesign/*"
+```
+## Files
+| component        | class                            | precision | tensors | size     |
+|------------------|----------------------------------|-----------|---------|----------|
+| model            | Qwen3TTSForConditionalGeneration | keep      | 404     | 3.57 GiB |
+| speech_tokenizer | Qwen3TTSTokenizerV2Model         | keep      | 496     | 651 MiB  |
+Folder total: **4.21 GiB**. `manifest.json` carries SHA-256, byte sizes and tensor counts for every file.
+## How this model works in MLX
+- No preset speakers: the voice itself is described in natural language.
+- `model` holds the talker and the code predictor; `speech_tokenizer` holds the codec, whose 52 Conv1d and 6 ConvTranspose1d weights are permuted to MLX layout.
+- No 4-bit variant yet: quantization needs an MLX implementation of these modules, which does not exist at the time of writing.
+<details>
+<summary><b>Tensor layout</b></summary>
+MLX convolutions expect channels last, PyTorch expects channels first, so convolution weights are permuted during conversion. Everything else keeps its upstream shape.
+| kind                        | PyTorch             | MLX                 |
+|-----------------------------|---------------------|---------------------|
+| `Conv2d.weight`             | `(out, in, kH, kW)` | `(out, kH, kW, in)` |
+| `Linear`, norms, embeddings | `(out, in)`         | unchanged           |
+No `weight_norm` and no 3-D convolutions appear in these models, so no folding was needed. Parameter names match the upstream checkpoints, so weights load without remapping.
+</details>
+<details>
+<summary><b>Verification numbers</b></summary>
+Every module was compared against the upstream reference on fixed inputs in float32. The metric is `rel_max = max|a-b| / max|a|`.
+| module                                          | rel_max   | reference                       |
+|-------------------------------------------------|-----------|---------------------------------|
+| Qwen3 encoder, hidden_states[-2]                | 2.7e-07   | transformers                    |
+| Qwen3 encoder, layers 9/18/27 with padding mask | 6.0e-07   | transformers                    |
+| Z-Image DiT                                     | 4.2e-06   | diffusers                       |
+| Flux2 DiT                                       | 3.7e-07   | diffusers                       |
+| VAE decoder                                     | 1.3e-05   | diffusers                       |
+| VAE encoder                                     | 5.3e-06   | diffusers                       |
+| VAE tiled decode                                | 5.1e-06   | diffusers tiled_decode          |
+| sigma schedule, static shift                    | 3.2e-08   | FlowMatchEulerDiscreteScheduler |
+| sigma schedule, exponential dynamic shift       | 7.7e-08   | FlowMatchEulerDiscreteScheduler |
+| position ids, latent packing, patchify          | bit-exact | pipeline helpers                |
+A Swift MLX implementation was then checked against the Python one:
+| module                       | rel_max         | note                                           |
+|------------------------------|-----------------|------------------------------------------------|
+| tokenization, both pipelines | bit-exact       | same ids                                       |
+| Qwen3 encoder, bf16          | 2.2e-04         | Z-Image branch                                 |
+| Qwen3 encoder, bf16          | 4.6e-03         | klein branch, 512 tokens with mask             |
+| Qwen3 encoder, 4-bit         | 3.0e-04         | proves the quantized layout is rebuilt exactly |
+| Z-Image DiT, float32         | 3.7e-07         | 8 layers                                       |
+| Flux2 DiT, float32           | 1.0e-06         | 2 double + 2 single blocks                     |
+| VAE decode / tiled / encode  | 1e-05 or better | both VAE classes                               |
+| VAE BatchNorm statistics     | 0               | exact                                          |
+The bf16 figures for a full-depth DiT are larger - 2e-02 for both models - and that is rounding order, not a defect: at float32 the same code agrees to 1e-06, and the deviation grows with depth from a bf16-level 1e-04 per block. Comparing two bf16 implementations below 1e-02 is not meaningful for a 30-block network.
+</details>
+<details>
+<summary><b>Performance on an M1 Max</b></summary>
+Mac Studio, Apple M1 Max, 10-core CPU, 24-core GPU, 32 GB, macOS 26.5. Release build, 4-bit weights, batch 1, warm page cache.
+| run                                  | per step | VAE decode |
+|--------------------------------------|----------|------------|
+| Z-Image, 512 px, 4 steps             | 2.6 s    | 1.5 s      |
+| klein, 512 px, 4 steps               | 2.3 s    | 0.9 s      |
+| klein, 1024 px, 4 steps              | 8.0 s    | 0.2 s      |
+| klein, 512 px + one 512 px reference | 4.1 s    | 0.9 s      |
+Reading the weights dominates a cold run and depends entirely on the storage: on an external volume delivering about 0.2 GiB/s, the 4-bit encoder took 22-32 s and a 4-bit DiT 18-35 s, against 60-107 s for the same weights in bf16. On internal storage expect these to be several times shorter. Compute is unaffected: the numbers above are steady state.
+Stages run one at a time and release their weights, so peak memory is set by the largest single component rather than their sum. The 4-bit DiT is 2.03 GiB for klein and 3.40 GiB for Z-Image; activations at 1024 px add to that, and no separate peak measurement was made.
+</details>
+<details>
+<summary><b>Limitations</b></summary>
+- Seeds are not compatible with the upstream pipelines, which use `torch.Generator`. The same prompt gives comparable images, never the same file.
+- Both models are distilled: CFG is not applied, and step counts are low by design (8 for Z-Image, 4 for klein).
+- Z-Image's Omni mode is not covered: it needs a SigLIP encoder that is not part of this bundle.
+- Tiled VAE decode is available for high resolutions and gives a result that differs slightly from a single pass, exactly as it does in diffusers.
+- Batches larger than one are not implemented.
+</details>
+## Licence
+[Apache-2.0](https://www.apache.org/licenses/LICENSE-2.0), the licence of the upstream model. Conversion tooling and this card: MIT. The upstream card states usage restrictions that redistribution does not repeal.