docs: add fp16-weights compact-storage variant section

README.md

@@ -214,6 +214,46 @@ Or use the no-code tools that ship the same model family:
 
 ---
 
+## Compact storage variant (fp16 weights)
+
+Alongside the 316 MB fp32 file, this repo now ships a **165 MB**
+compact-storage variant: `htdemucs_ft_vocals_fp16weights.onnx`.
+
+| Variant | File | Disk size | Runtime memory | Latency | Max abs diff vs fp32 |
+|---|---|---:|---:|---:|---:|
+| fp32 (baseline) | `htdemucs_ft_vocals.onnx` | 316 MB | 316 MB | 1.00× | 0 |
+| **fp16 weights** | `htdemucs_ft_vocals_fp16weights.onnx` | **165 MB** | 316 MB | ~1.00× | **6.0e-6** |
+
+**How it works.** Large fp32 weight tensors (Conv kernels, attention
+projection matrices, and the four STFT/iSTFT basis Constants — 134 MB
+combined) are stored on disk as fp16. A `Cast(fp16 → fp32)` op is inserted
+in front of each consumer. `onnxruntime` folds those Casts at session-init,
+so the in-memory representation and the compute graph remain pure fp32.
+
+**What that buys you.**
+- **1.91× smaller download / app bundle / Docker layer.**
+- Same numerical output as the fp32 file to within fp16 weight-quantization
+  noise (max diff 6.0e-6, ~3 decimal digits — below the perceptual
+  floor for audio).
+- Identical latency once the session is initialized.
+- Drop-in replacement: every code snippet on this page works unchanged.
+  Just point at `htdemucs_ft_vocals_fp16weights.onnx` instead.
+
+**When to use which.**
+- Use the **fp32** file when you want bit-exact reproduction of the
+  PyTorch reference, e.g. for research or for adding it to an evaluation
+  pipeline.
+- Use the **fp16-weights** file for every app bundle, container image,
+  CDN download, or mobile deployment. There is no runtime trade-off.
+
+> Looking for INT8 quantization or a true compute-fp16 build? We tried
+> both — htdemucs' transformer cross-attention overflows fp16
+> (`Pow(QK²)` past 65,504), and dynamic-INT8 either gave no speedup
+> (MatMul-only) or broke the model (with Conv). The honest answer is that
+> proper INT8 needs static quantization with MUSDB18 calibration data
+> plus model surgery on the STFT layer — a 2-3 day project that's still
+> on the Day 3 roadmap.
+
 ## Files in this repo
 
 | File | Size | Purpose |
@@ -222,6 +262,7 @@ Or use the no-code tools that ship the same model family:
 | `infer.py` | ~6 KB | Pure numpy + onnxruntime reference. No torch. |
 | `requirements.txt` | <1 KB | `onnxruntime`, `numpy`, `soundfile`. |
 | `README.md` | this file | |
+| `htdemucs_ft_vocals_fp16weights.onnx` | 165 MB | Compact-storage variant: same model as `htdemucs_ft_vocals.onnx`, fp16 weights on disk, fp32 compute at runtime. Drop-in replacement. |
 
 ---