Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,68 @@
+---
+license: mit
+library_name: onnx
+tags:
+  - audio-to-audio
+  - audio-source-separation
+  - onnx
+  - onnxruntime-web
+  - webgpu
+  - demucs
+---
+
+# htdemucs — ONNX graphs for onnxruntime-web (WebGPU)
+
+Hybrid Transformer Demucs, exported to ONNX and prepared for **in-browser**
+inference with [onnxruntime-web](https://onnxruntime.ai/) on the **WebGPU**
+backend. Used by [stemstudio.jp](https://www.stemstudio.jp) for local,
+upload-free stem separation.
+
+Derived from [facebookresearch/demucs](https://github.com/facebookresearch/demucs)
+(MIT). See `LICENSE` — the upstream notice travels with these files.
+
+## Files
+
+| File | Transfer (gzip) | Inflated | Stems |
+|---|---|---|---|
+| `htdemucs_ft.opt.fp16.istft.onnx.gzbin` | 141,591,461 | 172,746,888 | vocals / instrumental (fine-tuned) |
+| `htdemucs_4s.opt.fp16.istft.onnx.gzbin` | 141,601,329 | 172,746,888 | vocals / drums / bass / other |
+| `htdemucs_6s.opt.fp16.istft.onnx.gzbin` | 114,203,693 | 142,573,723 | + guitar / piano |
+
+## Two things that are easy to get wrong
+
+**1. The `.gzbin` extension is deliberate.** These are raw gzip streams stored
+as ordinary files, and the browser inflates them with
+`DecompressionStream('gzip')`. They are *not* named `.gz`, because some hosts
+and dev servers see that extension and add `content-encoding: gzip`, at which
+point the transport decompresses them and the application decompresses them
+again — which fails with `incorrect header check`. Detect gzip by the leading
+magic bytes (`1f 8b`), not by header or extension.
+
+The compression is in the file rather than in the transport because model hosts
+generally serve `.onnx` uncompressed regardless of `Accept-Encoding`.
+
+**2. Build order matters: optimize *before* fp16, not after.** Running the
+graph optimizer on an fp16 graph overflows folded constants to `inf` and every
+output becomes `NaN`. Worse, `nan > tolerance` is false, so a naive comparison
+reports "max diff 0.000e+00 / OK" on a completely broken model. The order used
+here is: fp32 export → graph optimization → fp16 weights → inverse STFT folded
+into the graph.
+
+## Why the optimized graph is WebGPU-only
+
+Measured on one 7.8 s segment, same model, same host:
+
+| | wasm heap | wasm infer | WebGPU session build |
+|---|---|---|---|
+| unoptimized | 1,223 MB | 16.8 s | 15.6 s |
+| optimized | **3,251 MB** | 18.1 s | **1.4 s** |
+
+On WebGPU, session build gets ~11× faster. On wasm, heap grows 2.7× and
+inference gets *slower*. "Ship the optimized one and everyone gets faster" is
+false — pick per execution provider.
+
+## Training data
+
+The upstream weights were trained on MUSDB18-HQ and additional sources. The
+MIT license covers the code and these derived graphs; the dataset carries its
+own terms, which are worth checking for your own use.