Add MDX-Net LiteRT fp16 models, deterministic export script, and standalone inference guide

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+example.mp3 filter=lfs diff=lfs merge=lfs -text

LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Gyoom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+The model weights are derived from the Ultimate Vocal Remover (UVR) MDX-Net
+models by Anjok07 (UVR-MDXNET 9482) and Kimberley Jensen (UVR-MDX-NET Voc FT),
+distributed under the MIT License via https://github.com/TRvlvr/model_repo and
+mirrored at https://huggingface.co/Politrees/UVR_resources. This repository
+redistributes format-converted (ONNX -> LiteRT fp16) copies under the same
+MIT terms.

README.md

@@ -1,3 +1,256 @@
 ---
 license: mit
+pipeline_tag: audio-to-audio
+base_model:
+  - Politrees/UVR_resources
+base_model_relation: quantized
+tags:
+  - audio
+  - audio-to-audio
+  - music-source-separation
+  - stem-separation
+  - vocal-separation
+  - mdx-net
+  - uvr
+  - tflite
+  - litert
+  - on-device
+  - android
 ---
+
+# UVR MDX-Net → LiteRT (on-device vocal separation)
+
+Two **UVR MDX-Net** vocal separators, converted to **LiteRT** (`.tflite`) as **fp16** and made to
+delegate *whole* to a mobile **GPU** — the models that power on-device vocal/instrumental separation in
+the MusicStemSeparation Android app. This repo ships the models plus everything needed to *run* and
+*reproduce* them:
+
+- **`separate.py`** — a self-contained, runnable Python reference (numpy STFT + LiteRT). WAV in →
+  `vocals` + `instrumental` WAV out.
+- **`export/export_mdx_litert.py`** — the single, deterministic ONNX→LiteRT-fp16 export script (it
+  reproduces the shipped `.tflite` **byte-for-byte**).
+- A documented **Android (Kotlin) integration** recipe below — the real CPU→GPU accelerator ladder.
+
+> **Not int8.** `base_model_relation: quantized` is HF's closest label; these are **fp16** precision +
+> format (ONNX→LiteRT) conversions of the original UVR MDX-Net weights, not integer-quantized models.
+
+## Models
+
+| Model | Params | `dim_f` | `n_fft` | `hop` | Size | Notes |
+|---|---|---|---|---|---|---|
+| **`UVR_MDXNET_9482.fp16acc.tflite`** | 7.4 M | 2048 | 4096 | 1024 | ~28 MB | general, fast (default) |
+| **`UVR-MDX-NET-Voc_FT.fp16acc.tflite`** | 16.7 M | 3072 | 6144 | 1024 | ~64 MB | vocal fine-tune, higher quality |
+
+Both run a native **256-frame** segment (`dim_t = 256`, ≈ 5.9 s @ 44.1 kHz). The model predicts the
+**vocal** spectrogram; the **instrumental is the free residual** `mix − vocals`.
+
+## Quickstart
+
+```bash
+pip install -r requirements.txt          # numpy + ai-edge-litert (WAV IO is stdlib)
+
+# input must be WAV — convert first if needed:
+ffmpeg -i example.mp3 example.wav
+
+python separate.py example.wav                    # 9482 (default)  → example_vocals.wav + example_instrumental.wav
+python separate.py example.wav --model voc_ft     # higher-quality model
+python separate.py example.wav --model voc_ft --denoise --out-dir out/
+```
+
+`separate.py` runs the model on the **CPU** (via `ai-edge-litert`/XNNPACK) — a correct, portable
+reference. The fp16 speedup and the GPU/NPU path are Android-only (see below).
+
+## Model I/O contract (the one thing to get right)
+
+```
+input = OUTPUT = float32 tensor  [1, 4, dim_f, 256]   (NCHW)
+```
+The 4 channels are **complex-as-channels**, plane order **`[L_re, L_im, R_re, R_im]`**
+(real plane = `2·c`, imag plane = `2·c + 1`), flat row-major index `((plane·dim_f) + bin)·256 + frame`.
+
+- The STFT keeps bins `[0, dim_f)` of the `n_fft/2 + 1` one-sided bins — i.e. **the Nyquist bin is
+  dropped** (`dim_f = n_fft/2`); on the inverse it is zero-padded back.
+- Voc FT carries **no embedded STFT metadata** — derive `n_fft = dim_f · 2`.
+- A wrong packing (swapped re/im planes, a kept Nyquist bin, a stray `1/√n`) produces
+  *plausible-but-wrong* audio, not an error. If a stem sounds off, look here first.
+
+## How it works — STFT *outside* the graph
+
+The `.tflite` is the **learned core only** — a convolutional U-Net that maps a spectrogram to the vocal
+spectrogram. The STFT, chunking, overlap-add and inverse STFT are ordinary CPU code (numpy in
+`separate.py`, Kotlin in the app). Per chunk:
+
+```
+STFT (host CPU) → inference (LiteRT: CPU / GPU / NPU) → iSTFT (host CPU) → weighted overlap-add
+```
+
+This is a faithful reimplementation of UVR's `mdx.py` demix: periodic Hann window, `center=True` reflect
+padding, **unnormalized** (`torch.stft(normalized=False)`), a fixed **10%** crossfade between chunks
+(set to 0 for the classic hard-tiled concat), and the free instrumental residual. Because the accelerator
+only ever sees the learned core, the model delegates cleanly and every stage is independently timed.
+
+## Android on-device inference (XNNPACK ↔ GPU)
+
+The app picks the accelerator **by availability**, not by assumption. LiteRT exposes two APIs, and each
+rung uses the right one:
+
+- **XNNPACK (fp16) / built-in CPU** → the classic `org.tensorflow.lite.Interpreter`.
+- **GPU** (and NPU) → the newer `com.google.ai.edge.litert.CompiledModel` + `Accelerator.GPU`.
+
+`CompiledModel` is **all-or-nothing** — one unsupported op fails the *whole* compile (that is exactly why
+the export un-fuses `TRANSPOSE_CONV`, see below). And whether the GPU delegate accepts a model can't be
+known without trying (*coverage-gated, not accelerator-exists*). So: **build each rung, run a warm-up
+inference, and keep the first that survives**, falling back `GPU → XNNPACK → CPU`.
+
+**Gradle**
+```kotlin
+dependencies {
+    implementation("com.google.ai.edge.litert:litert:2.1.6")   // GPU accelerator .so ships inside this AAR
+}
+android {
+    androidResources { noCompress += "tflite" }                // let LiteRT memory-map the model
+    // ABIs: arm64-v8a (+ x86_64 for the emulator)
+}
+```
+
+**Snippet A — XNNPACK / CPU via `Interpreter`** (fp16 engages automatically on ARMv8.2-FP16 cores)
+```kotlin
+import org.tensorflow.lite.Interpreter
+import java.io.RandomAccessFile
+import java.nio.channels.FileChannel
+
+val mapped = RandomAccessFile(tflitePath, "r").use { raf ->
+    raf.channel.map(FileChannel.MapMode.READ_ONLY, 0, raf.length())   // mmap the .tflite
+}
+val interpreter = Interpreter(mapped, Interpreter.Options().apply {
+    setNumThreads(bigCoreCount)   // e.g. the device's performance-core count
+    setUseXNNPACK(true)           // fp16 kicks in via the model's reduced_precision_support flag
+})
+// per chunk: input/output are direct float ByteBuffers of 1*4*dim_f*256 floats
+interpreter.run(inputBuffer, outputBuffer)
+```
+
+**Snippet B — GPU via `CompiledModel`** (fp16 is the GPU's native, ~2× precision; MDX is fp16-safe)
+```kotlin
+import com.google.ai.edge.litert.Accelerator
+import com.google.ai.edge.litert.CompiledModel
+import com.google.ai.edge.litert.Environment
+
+val env = Environment.create()
+val model = CompiledModel.create(
+    tflitePath,
+    CompiledModel.Options(Accelerator.GPU).apply {
+        gpuOptions = CompiledModel.GpuOptions(precision = CompiledModel.GpuOptions.Precision.FP16)
+    },
+    env,
+)
+val inputs = model.createInputBuffers()
+val outputs = model.createOutputBuffers()
+// per chunk:
+inputs[0].writeFloat(chunkFloats)   // 1*4*dim_f*256, [L_re, L_im, R_re, R_im]
+model.run(inputs, outputs)
+val vocals = outputs[0].readFloat()
+// NPU: swap Accelerator.NPU + QualcommOptions(HtpPerformanceMode.SUSTAINED_HIGH_PERFORMANCE);
+// needs a vendor runtime (hardware-gated — see "NPU" below).
+```
+
+**Snippet C — the fallback ladder** (build + warm-up-run each rung; keep the first that survives)
+```kotlin
+fun createEngine(tflitePath: String): Engine {
+    for (backend in listOf(Backend.GPU, Backend.XNNPACK, Backend.CPU)) {
+        runCatching {
+            val engine = build(backend, tflitePath)   // Snippet A or B
+            engine.warmUp()                            // one inference on a zeroed input
+            engine
+        }.onSuccess { return it }
+         .onFailure { Log.w(TAG, "backend $backend failed; falling back", it) }
+    }
+    error("no backend available")   // the built-in CPU floor is always last and always works
+}
+```
+
+The full production version (fallback-reason reporting, the NPU rung, warm-up gating, the `MdxEngine`
+seam) lives in the app's `tools/mdxlitert/pipeline/MdxLiteRtEngine.kt`.
+
+## Why LiteRT — the acceleration story
+
+**MDX-Net delegates whole.** It is a clean single-domain conv U-Net — no attention, no LSTM, no
+whole-tensor norm — which is exactly the op set XNNPACK, the GPU (ML Drift / OpenCL) and (on capable
+SoCs) the NPU map end-to-end. With the STFT pulled out of the graph, the accelerator sees only convs,
+transposed-convs and the TDF fully-connected blocks, so the whole graph delegates in one partition.
+
+**fp16 is the ~2× lever and it's safe here.** fp16 (not int8) is the quality-safe speedup, but only for a
+model with no whole-tensor reduction to overflow the fp16 ceiling (65504). MDX has only per-channel
+BatchNorm, which folds into the conv — nothing overflows:
+
+| Model | peak activation | fp16 ceiling | headroom |
+|---|---|---|---|
+| 9482 | 559 | 65504 | **117×** |
+| Voc FT | 1384 | 65504 | **47×** |
+
+fp16 is requested via the `.tflite` metadata flag `reduced_precision_support = "fp16accfp16"` (the fast
+accumulate value — measured quality-safe for MDX), which lets XNNPACK run the delegated ops in fp16 on
+ARMv8.2-FP16 cores.
+
+### The GPU fix — un-fuse `TRANSPOSE_CONV`'s ReLU
+
+The converter fuses each decoder `ConvTranspose + BN + ReLU` into one `TRANSPOSE_CONV` op with a *fused
+ReLU* — and a fused activation is precisely what tags the op **v4**. LiteRT 2.1.6's OpenCL delegate caps
+`TRANSPOSE_CONV` at **v3**, whose semantics have *no* fused activation. Because `CompiledModel` is
+all-or-nothing, that lone v4 op fails the whole GPU compile.
+
+The export **un-fuses** it: each `TRANSPOSE_CONV(+fused ReLU)` becomes a legitimately-v3 bias-only
+`TRANSPOSE_CONV` followed by a standalone `RELU` op (which the GPU supports). The whole graph then
+delegates in one partition **and computes the right function**. (Simply force-lowering the v4 tag to v3
+instead — the earlier attempt — made the GPU accept the graph but silently drop the ReLU on all five
+decoder upsamplers, producing an audible broadband buzz.) CPU numerics are unchanged.
+
+## Reproducing the export
+
+The two `.tflite` were produced by `export/export_mdx_litert.py`, and the export is **deterministic** —
+re-running it from the source ONNX yields the shipped files **byte-for-byte** (verified via SHA-256).
+
+```bash
+# heavy converter env (Python 3.11):
+pip install torch==2.9.1 --index-url https://download.pytorch.org/whl/cpu
+pip install -r export/requirements.txt
+
+python export/export_mdx_litert.py UVR_MDXNET_9482.onnx     UVR_MDXNET_9482.fp16acc.tflite
+python export/export_mdx_litert.py UVR-MDX-NET-Voc_FT.onnx  UVR-MDX-NET-Voc_FT.fp16acc.tflite
+```
+
+Six gated steps: `onnx2torch → SNR-gate (>100 dB vs ONNX Runtime) → litert_torch export (NCHW, static
+dim_t=256) → +fp16 metadata → un-fuse TRANSPOSE_CONV ReLU → verify (CPU SNR, output shape, no op above
+the GPU v3 cap)`. Source ONNX: the UVR MDX-Net releases from
+[TRvlvr/model_repo](https://github.com/TRvlvr/model_repo), also on the Hub at
+[Politrees/UVR_resources](https://huggingface.co/Politrees/UVR_resources).
+
+> `onnx2tf` does **not** work here — its per-op NCHW→NHWC guessing breaks the TDF MatMuls. The
+> PyTorch → StableHLO → TFLite route (`litert_torch`) does no layout guessing and keeps NCHW I/O, so the
+> app's complex-as-channels packing feeds the model directly.
+
+## Fidelity & performance
+
+- **Fidelity:** the fp16 `.tflite` is gated at **> 100 dB** CPU SNR vs the ONNX reference; measured
+  **≈ 109 dB (9482)** and **≈ 112 dB (Voc FT)** after the un-fuse step. Validated by ear on-device.
+- **Performance (one measured device — Xiaomi Redmi Note 10 Pro, Snapdragon 732G / Adreno 618, Android
+  13):** XNNPACK-fp16 runs the graph at **RTF ≈ 1.0** (roughly real-time) as the universal CPU floor;
+  the GPU path (whole-graph `LITERT_CL` partition) runs **clean and faster than XNNPACK** after the
+  un-fuse fix. Numbers vary by SoC; treat these as one data point, not a benchmark.
+- **NPU:** the rung is wired (`CompiledModel` + `Accelerator.NPU`, QNN / NeuroPilot) but is
+  hardware-gated — LiteRT admits only SM8550+ Snapdragons and listed MediaTek Dimensity SoCs — and is
+  currently deferred/untested.
+
+## Attribution & license
+
+Released under the **MIT License**, matching the upstream UVR MDX-Net models.
+
+- **UVR MDX-Net** and the **9482** model — the [Ultimate Vocal Remover](https://github.com/Anjok07/ultimatevocalremovergui)
+  project by **Anjok07** and contributors.
+- **UVR-MDX-NET Voc FT** — vocal fine-tune by **Kimberley Jensen**.
+- Source ONNX via [TRvlvr/model_repo](https://github.com/TRvlvr/model_repo) (Hub mirror:
+  [Politrees/UVR_resources](https://huggingface.co/Politrees/UVR_resources)).
+
+**This repo's contribution:** the ONNX → LiteRT **fp16** conversion, the whole-graph GPU fix (un-fusing
+`TRANSPOSE_CONV`'s ReLU), the runnable `separate.py` reference, and the Android integration recipe. The
+weights are the original UVR models, format-converted.

UVR-MDX-NET-Voc_FT.fp16acc.tflite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5ef47e3b3bafa14357532c0a3f6c5f18444d94b6efe3fd62b3d13f80051f1e58
+size 66848828

UVR_MDXNET_9482.fp16acc.tflite

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:2a07e11db13a11ca4900a54b4a316ef67931e993a6a3d19444bccbbeb9b445ee
+size 29802684

example.mp3

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:1b3783ea92eafc1741e6730bc0dc22b047c56dfcb0defc8af085ec9b5e937f56
+size 2402037

export/export_mdx_litert.py

@@ -0,0 +1,258 @@
+#!/usr/bin/env python3
+"""One-shot: a UVR MDX-Net .onnx -> the GPU-ready fp16 LiteRT .tflite the app ships.
+
+Pipeline (each step gated so a bad export fails loudly, not silently):
+  1. onnx2torch(onnx) -> nn.Module
+  2. SNR-gate the torch module vs ONNX Runtime (must be > --min-snr, default 100 dB)
+  3. litert_torch export -> .tflite  (keeps NCHW I/O; static dim_t=256)
+  4. add `reduced_precision_support = fp16accfp16` metadata (the XNNPACK-fp16 signal; measured
+     quality-safe for MDX: peak activation << the 65504 fp16 ceiling, no whole-tensor reduction)
+  5. un-fuse the RELU from every TRANSPOSE_CONV (fused activation is exactly what tags the op v4 —
+     "TransposeConvOp has fused activation function from version 4", op_version.cc — and LiteRT's GPU
+     accelerator caps TRANSPOSE_CONV at v3, whose semantics have NO fused activation. Force-lowering
+     the tag instead (the old approach) made the GPU accept the graph but its kernel then SILENTLY
+     DROPPED the ReLU on all 5 decoder upsamplers — the "GPU buzz". A standalone RELU op after a
+     legitimately-v3 bias-only TRANSPOSE_CONV delegates whole-graph AND computes the right function.
+     See UVR_MDX_LITERT.md §5.)
+  6. verify: CPU-inference SNR vs ONNX, output shape, and no op left above the GPU version cap.
+
+`onnx2tf` is NOT usable here (it guesses NCHW->NHWC per op and breaks the 22 TDF MatMuls + a
+ConvTranspose dummy-inference); the PyTorch -> StableHLO -> TFLite route below does no layout guessing.
+
+Env (pinned): onnx2torch 1.5.15, litert_torch 0.8.0 (ai_edge_torch 0.7.2), torch 2.9.1+cpu,
+ai-edge-litert 2.1.2, onnxruntime, onnx, tensorflow, flatbuffers, Python 3.11.
+
+Usage:
+    python export_mdx_litert.py UVR_MDXNET_9482.onnx     UVR_MDXNET_9482.fp16acc.tflite
+    python export_mdx_litert.py UVR-MDX-NET-Voc_FT.onnx  UVR-MDX-NET-Voc_FT.fp16acc.tflite
+"""
+import argparse
+import os
+import sys
+import types
+import warnings
+
+warnings.filterwarnings("ignore")
+os.environ.setdefault("GRPC_VERBOSITY", "NONE")
+
+# onnx2torch eagerly imports torchvision; MDX uses no vision ops, so stub it out when the real package
+# is missing or ABI-broken in the conversion env.
+try:
+    import torchvision  # noqa: F401
+except Exception:
+    _tv = types.ModuleType("torchvision")
+    _tv.__version__ = "0.0.0"
+    _ops = types.ModuleType("torchvision.ops")
+
+    def _stub(*a, **k):
+        raise NotImplementedError("torchvision op unavailable (stub)")
+
+    for _n in ("nms", "batched_nms", "roi_align", "RoIAlign", "DeformConv2d", "deform_conv2d"):
+        setattr(_ops, _n, _stub)
+    _tv.ops = _ops
+    sys.modules["torchvision"] = _tv
+    sys.modules["torchvision.ops"] = _ops
+
+import flatbuffers
+import numpy as np
+import onnx
+import onnx2torch
+import onnxruntime as ort
+import torch
+import litert_torch
+from ai_edge_litert.interpreter import Interpreter
+from tensorflow.lite.python import schema_py_generated as schema
+
+DIM_T = 256                 # native trained segment (~5.92 s @ hop 1024); static in the shipped tflite
+FP16_FLAG = b"fp16accfp16"  # reduced_precision_support: fast fp16 accumulate, quality-safe for MDX
+GPU_TRANSPOSE_CONV_CAP = 3
+
+
+def onnx_dim_f(onnx_path):
+    """MDX input is [batch, 4, dim_f, dim_t]; return dim_f (2048 for 9482, 3072 for Voc FT)."""
+    dims = onnx.load(onnx_path).graph.input[0].type.tensor_type.shape.dim
+    return int(dims[2].dim_value)
+
+
+def sample(dim_f):
+    return np.random.randn(1, 4, dim_f, DIM_T).astype(np.float32)
+
+
+def snr(ref, got):
+    den = np.sqrt((ref ** 2).mean())
+    num = np.sqrt(((ref - got) ** 2).mean())
+    return 20.0 * np.log10(den / (num + 1e-12))
+
+
+def module_snr(mod, onnx_path, dim_f, trials=2):
+    sess = ort.InferenceSession(onnx_path, providers=["CPUExecutionProvider"])
+    iname = sess.get_inputs()[0].name
+    worst = 1e9
+    for _ in range(trials):
+        x = sample(dim_f)
+        ref = sess.run(None, {iname: x})[0]
+        with torch.no_grad():
+            got = mod(torch.from_numpy(x)).numpy()
+        worst = min(worst, snr(ref, got))
+    return float(worst)
+
+
+def add_fp16_metadata(path):
+    model = schema.ModelT.InitFromObj(schema.Model.GetRootAsModel(open(path, "rb").read(), 0))
+    for md in (model.metadata or []):
+        name = md.name.decode() if isinstance(md.name, (bytes, bytearray)) else md.name
+        if name == "reduced_precision_support":
+            return
+    if model.metadata is None:
+        model.metadata = []
+    buf = schema.BufferT()
+    buf.data = list(FP16_FLAG)
+    model.buffers.append(buf)
+    md = schema.MetadataT()
+    md.name = "reduced_precision_support"
+    md.buffer = len(model.buffers) - 1
+    model.metadata.append(md)
+    builder = flatbuffers.Builder(1024)
+    builder.Finish(model.Pack(builder), b"TFL3")
+    open(path, "wb").write(bytes(builder.Output()))
+
+
+def unfuse_transpose_conv_relu(path):
+    """Split `TRANSPOSE_CONV(+fused RELU)` into `TRANSPOSE_CONV (v3, bias-only) -> RELU`.
+
+    The GPU accelerator's TRANSPOSE_CONV kernel implements v3 semantics (no fused activation) and
+    silently drops a fused ReLU, so the activation must live in its own (GPU-supported) RELU op.
+    CPU numerics are unchanged. Same surgery as the standalone unfuse_tconv_relu.py.
+    """
+    model = schema.ModelT.InitFromObj(schema.Model.GetRootAsModel(open(path, "rb").read(), 0))
+    tconv_opcodes = {
+        i for i, oc in enumerate(model.operatorCodes)
+        if max(oc.builtinCode, oc.deprecatedBuiltinCode) == schema.BuiltinOperator.TRANSPOSE_CONV
+    }
+    relu_opcode = next(
+        (i for i, oc in enumerate(model.operatorCodes)
+         if max(oc.builtinCode, oc.deprecatedBuiltinCode) == schema.BuiltinOperator.RELU), None)
+    if relu_opcode is None:
+        oc = schema.OperatorCodeT()
+        oc.builtinCode = schema.BuiltinOperator.RELU
+        oc.deprecatedBuiltinCode = schema.BuiltinOperator.RELU
+        oc.version = 1
+        model.operatorCodes.append(oc)
+        relu_opcode = len(model.operatorCodes) - 1
+
+    unfused = 0
+    for sg in model.subgraphs:
+        new_ops = []
+        for op in sg.operators:
+            new_ops.append(op)
+            opts = op.builtinOptions
+            if (op.opcodeIndex not in tconv_opcodes or opts is None
+                    or getattr(opts, "fusedActivationFunction", 0) == 0):
+                continue
+            assert opts.fusedActivationFunction == schema.ActivationFunctionType.RELU
+            old_out = op.outputs[0]
+            old_t = sg.tensors[old_out]
+
+            pre = schema.TensorT()
+            pre.shape = list(old_t.shape) if old_t.shape is not None else None
+            pre.type = old_t.type
+            base = old_t.name.decode() if isinstance(old_t.name, (bytes, bytearray)) else old_t.name
+            pre.name = (base + "_prerelu").encode()
+            buf = schema.BufferT()
+            model.buffers.append(buf)
+            pre.buffer = len(model.buffers) - 1
+            sg.tensors.append(pre)
+            pre_idx = len(sg.tensors) - 1
+
+            opts.fusedActivationFunction = schema.ActivationFunctionType.NONE
+            outs = list(op.outputs)  # the packed array is read-only; swap in a mutable list
+            outs[0] = pre_idx
+            op.outputs = outs
+
+            relu = schema.OperatorT()
+            relu.opcodeIndex = relu_opcode
+            relu.inputs = [pre_idx]
+            relu.outputs = [old_out]
+            new_ops.append(relu)
+            unfused += 1
+        sg.operators = new_ops
+
+    # With the activation un-fused, bias-only TRANSPOSE_CONV is legitimately v3 — no forged tag.
+    for oc in model.operatorCodes:
+        code = max(oc.builtinCode, oc.deprecatedBuiltinCode)
+        if code == schema.BuiltinOperator.TRANSPOSE_CONV and oc.version > GPU_TRANSPOSE_CONV_CAP:
+            oc.version = GPU_TRANSPOSE_CONV_CAP
+    builder = flatbuffers.Builder(1024)
+    builder.Finish(model.Pack(builder), b"TFL3")
+    open(path, "wb").write(bytes(builder.Output()))
+    return unfused
+
+
+def tflite_cpu_snr(path, onnx_path, dim_f, trials=2):
+    sess = ort.InferenceSession(onnx_path, providers=["CPUExecutionProvider"])
+    iname = sess.get_inputs()[0].name
+    it = Interpreter(model_path=path)
+    it.allocate_tensors()
+    inp = it.get_input_details()[0]
+    outp = it.get_output_details()[0]
+    worst, oshape = 1e9, None
+    for _ in range(trials):
+        x = sample(dim_f)
+        ref = sess.run(None, {iname: x})[0]
+        it.set_tensor(inp["index"], x)
+        it.invoke()
+        got = it.get_tensor(outp["index"])
+        oshape = got.shape
+        worst = min(worst, snr(ref, got))
+    return float(worst), oshape
+
+
+def over_cap_ops(path):
+    model = schema.Model.GetRootAsModel(open(path, "rb").read(), 0)
+    bad = []
+    for i in range(model.OperatorCodesLength()):
+        oc = model.OperatorCodes(i)
+        code = max(oc.BuiltinCode(), oc.DeprecatedBuiltinCode())
+        if code == schema.BuiltinOperator.TRANSPOSE_CONV and oc.Version() > GPU_TRANSPOSE_CONV_CAP:
+            bad.append(("TRANSPOSE_CONV", oc.Version()))
+    return bad
+
+
+def main():
+    ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
+    ap.add_argument("onnx", help="source UVR MDX-Net .onnx")
+    ap.add_argument("out", help="output .fp16acc.tflite")
+    ap.add_argument("--min-snr", type=float, default=100.0)
+    args = ap.parse_args()
+
+    dim_f = onnx_dim_f(args.onnx)
+    print(f"[1/6] onnx2torch: {args.onnx}  (dim_f={dim_f}, dim_t={DIM_T})", flush=True)
+    mod = onnx2torch.convert(args.onnx).eval()
+
+    msnr = module_snr(mod, args.onnx, dim_f)
+    print(f"[2/6] torch-module SNR vs ONNX Runtime = {msnr:.1f} dB", flush=True)
+    if msnr < args.min_snr:
+        raise SystemExit(f"FAIL: onnx2torch fidelity {msnr:.1f} dB < {args.min_snr} dB (do not ship)")
+
+    print(f"[3/6] litert_torch export -> {args.out}", flush=True)
+    litert_torch.convert(mod, (torch.from_numpy(sample(dim_f)),)).export(args.out)
+
+    print("[4/6] add fp16 metadata (reduced_precision_support=fp16accfp16)", flush=True)
+    add_fp16_metadata(args.out)
+
+    n = unfuse_transpose_conv_relu(args.out)
+    print(f"[5/6] un-fused {n} TRANSPOSE_CONV ReLU(s) -> standalone RELU ops (GPU kernel drops fused "
+          f"activations; op now legitimately v{GPU_TRANSPOSE_CONV_CAP})", flush=True)
+
+    tsnr, oshape = tflite_cpu_snr(args.out, args.onnx, dim_f)
+    bad = over_cap_ops(args.out)
+    size_mb = os.path.getsize(args.out) / 1e6
+    ok = tsnr >= args.min_snr and oshape == (1, 4, dim_f, DIM_T) and not bad
+    print(f"[6/6] verify: tflite CPU SNR vs ONNX = {tsnr:.1f} dB | out = {oshape} | "
+          f"over-cap ops = {bad or 'none'} | size = {size_mb:.1f} MB", flush=True)
+    print("      " + ("PASS — GPU-ready fp16 tflite" if ok else "FAIL — do not ship"), flush=True)
+    raise SystemExit(0 if ok else 1)
+
+
+if __name__ == "__main__":
+    main()

export/requirements.txt

@@ -0,0 +1,15 @@
+# Toolchain to reproduce the ONNX -> LiteRT fp16 export (export_mdx_litert.py). Python 3.11.
+# Install torch from the CPU wheel index first:
+#   pip install torch==2.9.1 --index-url https://download.pytorch.org/whl/cpu
+#   pip install -r requirements.txt
+# Only onnx2torch and litert-torch are hard-pinned (the conversion route is sensitive to their
+# versions); the rest float. This is the heavy converter env — to only RUN a shipped .tflite you just
+# need `numpy` + `ai-edge-litert` (see ../requirements.txt).
+onnx2torch==1.5.15
+litert-torch==0.8.0
+ai-edge-litert
+tensorflow
+onnx
+onnxruntime
+flatbuffers
+numpy

requirements.txt

@@ -0,0 +1,4 @@
+# Runtime deps for separate.py (the standalone inference guide).
+# WAV IO uses the Python stdlib `wave` module, so there are no audio libraries to install.
+numpy>=1.24
+ai-edge-litert>=1.1

separate.py

@@ -0,0 +1,327 @@
+#!/usr/bin/env python3
+"""Standalone vocal / instrumental separation with UVR MDX-Net on LiteRT.
+
+This is a self-contained, runnable reference for the "STFT outside the graph" design used by the
+MusicStemSeparation Android app. The `.tflite` graph is the **learned core only** — a convolutional
+U-Net that maps a spectrogram to the vocal spectrogram. The STFT, chunking, overlap-add and inverse
+STFT are ordinary CPU code here (numpy), exactly as they are ordinary Kotlin code in the app. Per chunk:
+
+        STFT (numpy) -> inference (LiteRT) -> iSTFT (numpy) -> weighted overlap-add
+
+Everything below mirrors the app's DSP line-for-line so the output matches; the Kotlin sources are cited
+inline (`CacDsp.kt`, `MdxSeparationPipeline.kt`, `MdxLiteRtEngine.kt`, `MdxTypes.kt`, audio/*). The whole
+pipeline is a faithful reimplementation of UVR's `mdx.py` demix (with a 10% crossfade instead of hard
+tiling — set OVERLAP = 0 to get the classic hard concat).
+
+THE MODEL I/O CONTRACT (the one thing to get right):
+    input  = OUTPUT = float32 tensor  [1, 4, dim_f, 256]  (NCHW)
+    the 4 channels are complex-as-channels, plane order  [L_re, L_im, R_re, R_im]
+    flat row-major index = ((plane * dim_f) + bin) * 256 + frame
+    9482 : dim_f 2048, n_fft 4096      Voc FT : dim_f 3072, n_fft 6144      both hop 1024
+A wrong packing (swapped re/im planes, kept Nyquist bin, a stray 1/sqrt(n)) yields plausible-but-wrong
+audio, not an error — so this is where to look first if a stem sounds off.
+
+NOTE ON PRECISION / SPEED: this runs the model on the CPU via ai-edge-litert (XNNPACK). The `.tflite`
+carries `reduced_precision_support=fp16accfp16`, which only engages fp16 kernels on ARMv8.2-FP16 cores;
+on a desktop it runs fp32 (correct, just not the ~2x mobile speed). The real CPU->GPU->NPU accelerator
+ladder is Android-only — see the README's "Android on-device inference" section and the app's
+`MdxLiteRtEngine.kt`.
+
+Usage:
+    python separate.py song.wav                      # 9482 model, writes song_vocals.wav + song_instrumental.wav
+    python separate.py song.wav --model voc_ft       # higher-quality (larger) model
+    python separate.py song.wav --out-dir out/ --denoise
+Input must be a WAV (convert other formats first, e.g. `ffmpeg -i in.mp3 in.wav`). Feed 44.1 kHz for
+exact UVR parity; other rates are linearly resampled (matching the app, not librosa/soxr).
+"""
+import argparse
+import os
+import sys
+import wave
+
+import numpy as np
+from ai_edge_litert.interpreter import Interpreter
+
+# ── Fixed constants (MdxTypes.kt) ────────────────────────────────────────────────────────────────
+SAMPLE_RATE = 44100      # MDX_SAMPLE_RATE — MDX-Net operates at 44.1 kHz
+DIM_T = 256              # native trained segment (~5.92 s @ hop 1024); static in the shipped .tflite
+HOP = 1024               # STFT hop, both models
+OVERLAP = 0.10           # MDX_OVERLAP — fixed 10% chunk crossfade (0 -> classic hard-tiled concat)
+
+# The .tflite assets live beside this script. Each entry carries its STFT framing (MdxModel enum).
+HERE = os.path.dirname(os.path.abspath(__file__))
+MODELS = {
+    "9482":   dict(tflite="UVR_MDXNET_9482.fp16acc.tflite",     n_fft=4096, dim_f=2048, compensation=1.0),
+    "voc_ft": dict(tflite="UVR-MDX-NET-Voc_FT.fp16acc.tflite",  n_fft=6144, dim_f=3072, compensation=1.0),
+}
+
+
+# ══════════════════════════════════════════════════════════════════════════════════════════════════
+#  Host DSP — a numpy port of CacDsp.kt (CacStft / CacIstft / reflect pad / crossfade window).
+#  Mirrors UVR's STFT/ISTFT: periodic Hann, center=True reflect pad, normalized=False (no 1/sqrt(n)),
+#  Nyquist bin dropped (dim_f = n_fft/2).
+# ══════════════════════════════════════════════════════════════════════════════════════════════════
+
+def hann_periodic(n):
+    """torch.hann_window(n, periodic=True) = 0.5*(1 - cos(2*pi*k/n)), k=0..n-1 (divisor n)."""
+    k = np.arange(n, dtype=np.float64)
+    return (0.5 * (1.0 - np.cos(2.0 * np.pi * k / n))).astype(np.float32)
+
+
+class Stft:
+    """Forward STFT: stereo chunk (chunk_size samples/channel) -> CaC tensor [1, 4, dim_f, 256].
+
+    Port of CacStft.transform. For each channel: reflect-pad by n_fft/2 (center=True), slide a
+    hop-spaced periodic-Hann window over DIM_T frames, rfft each frame, keep bins [0, dim_f) (dropping
+    the Nyquist bin since dim_f = n_fft/2), and store real/imag into planes [L_re, L_im, R_re, R_im].
+    """
+
+    def __init__(self, n_fft, dim_f):
+        self.n = n_fft
+        self.dim_f = dim_f
+        self.pad = n_fft // 2                       # centerPad
+        self.chunk_size = HOP * (DIM_T - 1)
+        self.hann = hann_periodic(n_fft)
+
+    def _channel_spec(self, samples):
+        # reflectPad(x, left=pad, right=pad): mirror without repeating the edge == np.pad(mode="reflect").
+        padded = np.pad(samples, (self.pad, self.pad), mode="reflect")
+        # DIM_T frames starting at f*hop, each n_fft long (padded length = chunk_size + n_fft).
+        frames = np.lib.stride_tricks.sliding_window_view(padded, self.n)[::HOP]
+        assert frames.shape[0] == DIM_T, (frames.shape, DIM_T)
+        frames = frames * self.hann                 # analysis window
+        spec = np.fft.rfft(frames, axis=1)          # [DIM_T, n/2+1], unnormalized (normalized=False)
+        spec = spec[:, : self.dim_f]                # crop to dim_f -> drops the Nyquist bin
+        # -> [dim_f, DIM_T] planes; rfft already gives DC imag == 0.
+        return spec.real.T.astype(np.float32), spec.imag.T.astype(np.float32)
+
+    def __call__(self, left, right):
+        l_re, l_im = self._channel_spec(left)
+        r_re, r_im = self._channel_spec(right)
+        out = np.empty((1, 4, self.dim_f, DIM_T), dtype=np.float32)
+        out[0, 0], out[0, 1], out[0, 2], out[0, 3] = l_re, l_im, r_re, r_im   # [L_re, L_im, R_re, R_im]
+        return out
+
+
+class Istft:
+    """Inverse STFT: CaC tensor [1, 4, dim_f, 256] -> stereo chunk (chunk_size samples/channel).
+
+    Port of CacIstft.inverse. Rebuilds each frame's one-sided spectrum (Nyquist bin zero-padded back),
+    irfft (includes 1/n), applies the synthesis Hann window, overlap-adds, divides by the running
+    window-sum-of-squares envelope (+1e-8), and trims the n_fft/2 center pad each side.
+    """
+
+    def __init__(self, n_fft, dim_f):
+        self.n = n_fft
+        self.dim_f = dim_f
+        self.pad = n_fft // 2
+        self.chunk_size = HOP * (DIM_T - 1)
+        self.hann = hann_periodic(n_fft)
+        self.ola_len = (DIM_T - 1) * HOP + n_fft
+        self.hann_sq = (self.hann * self.hann).astype(np.float32)
+
+    def _channel_wave(self, re, im):
+        # Full one-sided spectrum [DIM_T, n/2+1]; bins >= dim_f (i.e. the Nyquist bin) stay zero.
+        full = np.zeros((DIM_T, self.n // 2 + 1), dtype=np.complex128)
+        full[:, : self.dim_f] = re.T + 1j * im.T
+        frames = np.fft.irfft(full, n=self.n, axis=1).astype(np.float32)   # [DIM_T, n], includes 1/n
+        frames = frames * self.hann                                        # synthesis window
+        ola = np.zeros(self.ola_len, dtype=np.float32)
+        env = np.zeros(self.ola_len, dtype=np.float32)
+        for t in range(DIM_T):
+            s = t * HOP
+            ola[s : s + self.n] += frames[t]
+            env[s : s + self.n] += self.hann_sq
+        seg = slice(self.pad, self.pad + self.chunk_size)
+        return ola[seg] / (env[seg] + 1e-8)
+
+    def __call__(self, spec):
+        left = self._channel_wave(spec[0, 0], spec[0, 1])
+        right = self._channel_wave(spec[0, 2], spec[0, 3])
+        return left, right
+
+
+def build_crossfade_window(gen_size, overlap_len):
+    """Trapezoid: ramp up over first overlap_len, flat 1, ramp down over last overlap_len. Strictly
+    positive so the envelope divide is well-defined at the un-overlapped first/last edges. Port of
+    CacDsp.buildCrossfadeWindow (overlap_len == 0 -> all ones = hard tile)."""
+    if overlap_len <= 0:
+        return np.ones(gen_size, dtype=np.float32)
+    denom = float(overlap_len + 1)
+    k = np.arange(gen_size, dtype=np.float32)
+    up = (k + 1.0) / denom
+    down = (gen_size - k) / denom
+    return np.minimum(1.0, np.minimum(up, down)).astype(np.float32)
+
+
+# ══════════════════════════════════════════════════════════════════════════════════════════════════
+#  Inference seam — a numpy port of the MdxEngine seam (MdxLiteRtEngine.kt). One run() method:
+#  CaC spectrogram in -> vocal CaC spectrogram out. This is the whole "how to call the model" story.
+# ══════════════════════════════════════════════════════════════════════════════════════════════════
+
+class MdxLiteRtEngine:
+    """LiteRT inference stage. On the CPU this is the classic Interpreter path (== InterpreterRunner in
+    the app; the GPU/NPU rungs use the CompiledModel API and are Android-only)."""
+
+    def __init__(self, tflite_path):
+        self.it = Interpreter(model_path=tflite_path)   # LiteRT memory-maps the .tflite
+        self.it.allocate_tensors()
+        self._in = self.it.get_input_details()[0]
+        self._out = self.it.get_output_details()[0]
+
+    def _infer(self, x):
+        self.it.set_tensor(self._in["index"], np.ascontiguousarray(x, dtype=np.float32))
+        self.it.invoke()
+        return self.it.get_tensor(self._out["index"]).copy()   # copy: the tensor is reused across calls
+
+    def run(self, spec, denoise=False):
+        out = self._infer(spec)
+        if denoise:
+            # UVR shift trick: spec_pred = 0.5*model(spec) - 0.5*model(-spec). 2x inference cost.
+            out = 0.5 * out - 0.5 * self._infer(-spec)
+        return out
+
+
+# ══════════════════════════════════════════════════════════════════════════════════════════════════
+#  Pipeline — a numpy port of MdxSeparationPipeline.separate: chunk, STFT -> infer -> iSTFT, weighted
+#  overlap-add, envelope normalize, volume compensation, and the free instrumental residual.
+# ══════════════════════════════════════════════════════════════════════════════════════════════════
+
+def separate(engine, cfg, left, right, denoise=False):
+    n_fft, dim_f, comp = cfg["n_fft"], cfg["dim_f"], cfg["compensation"]
+    trim = n_fft // 2                              # STFT center trim / per-side overlap
+    chunk_size = HOP * (DIM_T - 1)
+    gen_size = chunk_size - 2 * trim               # useful samples a chunk contributes
+    n_sample = min(len(left), len(right))
+    if n_sample <= 0:
+        raise ValueError("empty audio")
+
+    # Overlap geometry (MdxSeparationPipeline.kt).
+    stride = int(round(gen_size * (1.0 - OVERLAP)))
+    stride = max(1, min(gen_size, stride))
+    overlap_len = gen_size - stride
+    window = build_crossfade_window(gen_size, overlap_len)
+    n_chunks = 1 if n_sample <= gen_size else (n_sample - gen_size + stride - 1) // stride + 1
+    out_len = (n_chunks - 1) * stride + gen_size
+
+    # mixture = [trim zeros | audio | right-pad zeros | trim zeros] so every window is in-bounds.
+    mix_len = trim + out_len + trim
+    mix_l = np.zeros(mix_len, dtype=np.float32); mix_l[trim : trim + n_sample] = left[:n_sample]
+    mix_r = np.zeros(mix_len, dtype=np.float32); mix_r[trim : trim + n_sample] = right[:n_sample]
+
+    acc_l = np.zeros(out_len, dtype=np.float32)
+    acc_r = np.zeros(out_len, dtype=np.float32)
+    env = np.zeros(out_len, dtype=np.float32)
+
+    stft = Stft(n_fft, dim_f)
+    istft = Istft(n_fft, dim_f)
+    for i in range(n_chunks):
+        s = i * stride
+        spec = stft(mix_l[s : s + chunk_size], mix_r[s : s + chunk_size])   # STFT
+        voc = engine.run(spec, denoise)                                     # inference
+        w_l, w_r = istft(voc)                                               # iSTFT -> chunk_size samples
+        # Window the central gen_size samples (drop trim each side) and overlap-add.
+        acc_l[s : s + gen_size] += window * w_l[trim : trim + gen_size]
+        acc_r[s : s + gen_size] += window * w_r[trim : trim + gen_size]
+        env[s : s + gen_size] += window
+        print(f"  chunk {i + 1}/{n_chunks}", end="\r", flush=True)
+    print()
+
+    # Normalize by the crossfade envelope, crop to length, apply volume compensation.
+    voc_l = (acc_l[:n_sample] / (env[:n_sample] + 1e-8) * comp).astype(np.float32)
+    voc_r = (acc_r[:n_sample] / (env[:n_sample] + 1e-8) * comp).astype(np.float32)
+    # Instrumental is the free residual: original mix - vocals.
+    ins_l = (left[:n_sample] - voc_l).astype(np.float32)
+    ins_r = (right[:n_sample] - voc_r).astype(np.float32)
+    return voc_l, voc_r, ins_l, ins_r
+
+
+# ══════════════════════════════════════════════════════════════════════════════════════════════════
+#  Audio IO — stdlib `wave`, matching audio/AudioDecoder, AudioResampler, WavWriter (16-bit, /32768 in,
+#  x32767 out). No external audio deps; WAV in / WAV out.
+# ══════════════════════════════════════════════════════════════════════════════════════════════════
+
+def read_wav_stereo_44100(path):
+    with wave.open(path, "rb") as w:
+        ch, width, sr, nframes = w.getnchannels(), w.getsampwidth(), w.getframerate(), w.getnframes()
+        raw = w.readframes(nframes)
+    if width == 2:
+        data = np.frombuffer(raw, dtype="<i2").astype(np.float32) / 32768.0
+    elif width == 1:                                  # WAV 8-bit is unsigned
+        data = (np.frombuffer(raw, dtype=np.uint8).astype(np.float32) - 128.0) / 128.0
+    elif width == 4:                                  # assume 32-bit signed PCM
+        data = np.frombuffer(raw, dtype="<i4").astype(np.float32) / 2147483648.0
+    else:
+        raise ValueError(f"unsupported WAV sample width {width} bytes (use 16-bit PCM WAV)")
+    data = data.reshape(-1, ch)
+    if ch == 1:
+        left = right = data[:, 0]                     # mono -> duplicate (AudioDecoder)
+    else:
+        left, right = data[:, 0], data[:, 1]          # keep first two channels
+    if sr != SAMPLE_RATE:                             # resample only if needed (AudioResampler.resampleLinear)
+        left = resample_linear(left, sr, SAMPLE_RATE)
+        right = resample_linear(right, sr, SAMPLE_RATE)
+    return np.ascontiguousarray(left), np.ascontiguousarray(right)
+
+
+def resample_linear(src, src_sr, dst_sr):
+    """Naive linear-interpolation resampler — a port of AudioResampler.resampleLinear (NOT librosa/soxr,
+    so it matches the app, not UVR's reference; feed 44.1 kHz for exact parity)."""
+    if src_sr == dst_sr or src.size < 2:
+        return src.astype(np.float32)
+    dst_len = max(1, int(src.size * dst_sr // src_sr))
+    pos = np.arange(dst_len, dtype=np.float64) * (src_sr / dst_sr)
+    i0 = np.floor(pos).astype(np.int64)
+    frac = (pos - i0).astype(np.float32)
+    i0 = np.clip(i0, 0, src.size - 1)
+    i1 = np.clip(i0 + 1, 0, src.size - 1)
+    return (src[i0] + (src[i1] - src[i0]) * frac).astype(np.float32)
+
+
+def write_wav_stereo_16(path, left, right, sr=SAMPLE_RATE):
+    n = min(len(left), len(right))
+    l = np.clip(left[:n], -1.0, 1.0); r = np.clip(right[:n], -1.0, 1.0)
+    inter = np.empty(n * 2, dtype="<i2")
+    inter[0::2] = (l * 32767.0).astype(np.int16)      # x32767 truncate, matching WavWriter.toPcm16
+    inter[1::2] = (r * 32767.0).astype(np.int16)
+    os.makedirs(os.path.dirname(os.path.abspath(path)), exist_ok=True)
+    with wave.open(path, "wb") as w:
+        w.setnchannels(2); w.setsampwidth(2); w.setframerate(sr)
+        w.writeframes(inter.tobytes())
+
+
+# ══════════════════════════════════════════════════════════════════════════════════════════════════
+
+def main():
+    ap = argparse.ArgumentParser(description="UVR MDX-Net vocal separation on LiteRT (STFT outside the graph).")
+    ap.add_argument("input", help="input WAV (any sample rate; 44.1 kHz for exact parity)")
+    ap.add_argument("--model", choices=list(MODELS), default="9482", help="which MDX-Net model (default: 9482)")
+    ap.add_argument("--out-dir", default=".", help="directory for the output stems (default: .)")
+    ap.add_argument("--denoise", action="store_true", help="UVR shift trick (2x inference, slightly cleaner)")
+    args = ap.parse_args()
+
+    cfg = MODELS[args.model]
+    tflite = os.path.join(HERE, cfg["tflite"])
+    if not os.path.exists(tflite):
+        sys.exit(f"model not found: {tflite}\nDownload it from the repo (it is tracked with Git LFS).")
+
+    print(f"model      : {args.model}  ({cfg['tflite']}, dim_f={cfg['dim_f']}, n_fft={cfg['n_fft']})")
+    print(f"loading    : {args.input}")
+    left, right = read_wav_stereo_44100(args.input)
+    print(f"samples    : {len(left)} per channel ({len(left)/SAMPLE_RATE:.1f} s @ {SAMPLE_RATE} Hz)")
+
+    engine = MdxLiteRtEngine(tflite)
+    print("separating :")
+    voc_l, voc_r, ins_l, ins_r = separate(engine, cfg, left, right, denoise=args.denoise)
+
+    stem = os.path.splitext(os.path.basename(args.input))[0]
+    voc_path = os.path.join(args.out_dir, f"{stem}_vocals.wav")
+    ins_path = os.path.join(args.out_dir, f"{stem}_instrumental.wav")
+    write_wav_stereo_16(voc_path, voc_l, voc_r)
+    write_wav_stereo_16(ins_path, ins_l, ins_r)
+    print(f"wrote      : {voc_path}")
+    print(f"           : {ins_path}")
+
+
+if __name__ == "__main__":
+    main()