HT-Demucs FT para ONNX: Como Construímos o Primeiro Export Funcional para iOS, Android e Web — Mais 9 Modelos Abertos no Hugging Face e um Benchmark Reproduzível sobre MUSDB18-HQ (2026)

TL;DR. Acabamos de abrir o código de 10 assets de separação de stems no Hugging Face, incluindo o primeiro export ONNX funcional do HT-Demucs FT — o separador vocal open source nº 1 no MUSDB18-HQ. Toda tentativa anterior de "demucs onnx" empacou nos mesmos quatro bloqueadores; derrotamos todos. O resultado roda em onnxruntime em CPU/CoreML/CUDA/DirectML sem PyTorch na inferência, é 1,31× mais rápido que PyTorch em CPU e é numericamente equivalente ao original (diferença absoluta máxima: 0.000163 nos 4 stems).

A seguir: o que liberamos, por que isso importa e o relato de engenharia de como o export ONNX realmente aconteceu.

---

Tudo o que liberamos esta semana

Todos com licença MIT, todos na página da organização StemSplitio.

A manchete: os repositórios ONNX são, até onde sabemos, os primeiros exports ONNX funcionais do HT-Demucs FT no Hugging Face. Não "primeira tentativa" — o primeiro que carrega, roda, produz números corretos e vem com benchmarks de paridade verificados.

---

Por que fizemos isso

O vácuo de benchmarks

Se você tentou escolher um modelo de separação de stems em 2026, encontrou uma bagunça. Todo repositório de modelo afirma que o seu é "state of the art". Poucos publicam benchmarks reproduzíveis. Menos ainda testam os mesmos modelos entre si, no mesmo hardware, com as mesmas métricas.

Resolvemos isso publicando o stem-separation-benchmark-2026 — 850 linhas de notas SDR / ISR / SIR / SAR para htdemucs, htdemucs_ft, htdemucs_6s, mdx_extra_q e mdx_net_inst_hq3 no MUSDB18-HQ, com o pipeline de avaliação completo em código aberto. Qualquer um pode cloná-lo, re-rodá-lo e contestar nossos números.

Resultado principal: htdemucs_ft é o separador vocal open source nº 1 (mediana de SDR vocal de 9,19 dB) e mdx_extra_q é o nº 1 em bateria/baixo/outros (11,49 / 11,42 / 7,67 dB). Modelos diferentes para stems diferentes.

O vácuo do ONNX

O problema maior: se você quisesse usar HT-Demucs FT no iOS, no Android ou no navegador, não dava. A história mobile do PyTorch é dura, MPS/CUDA só servem em servidor e a resposta óbvia — ONNX — nunca tinha sido feita.

Existem pelo menos quatro issues abertas no repositório do demucs pedindo exports ONNX. Múltiplos forks meio quebrados. Um PR de 2023 que não dá merge. Alguns experimentos em MLX que precisam de um Mac M1 ou superior. Nada que "simplesmente funcione".

O motivo: o HT-Demucs tem escolhas arquitetônicas que parecem inocentes em PyTorch mas quebram os exportadores ONNX de maneiras não óbvias. Batemos e consertamos todas as quatro, que é o resto deste post.

---

Como o HT-Demucs FT quebra todo exportador ONNX

Tentamos torch.onnx.export primeiro, depois torch.onnx.dynamo_export. Ambos falharam em pontos diferentes. Aqui está o catálogo completo de bloqueadores e como cada um foi corrigido:

Bloqueador 1: saída STFT em complex64

O HT-Demucs começa com uma Short-Time Fourier Transform (spec.py::spectro):

z = torch.stft(x, n_fft=4096, hop_length=1024, window=hann,
               win_length=4096, normalized=True, center=True,
               return_complex=True, pad_mode="reflect")

Aquele return_complex=True devolve um tensor complex64. O MIL do CoreML não tem dtype complexo. O op STFT do ONNX (opset 17+) também não suporta saídas complexas. Todo slice/transpose downstream do grafo falha imediatamente.

Correção. Substituir torch.stft por um Conv1d usando kernels sin/cos que emite dois canais reais diretamente:

def _make_stft_kernels(n_fft: int) -> tuple[torch.Tensor, torch.Tensor]:
    n = torch.arange(n_fft, dtype=torch.float64)
    window = torch.hann_window(n_fft, periodic=True, dtype=torch.float64)
    norm = 1.0 / math.sqrt(n_fft)
    k = torch.arange(n_fft // 2 + 1, dtype=torch.float64).unsqueeze(1)
    angles = 2 * math.pi * k * n.unsqueeze(0) / n_fft
    cos = (window * torch.cos(angles)) * norm
    sin = (window * -torch.sin(angles)) * norm   # negative for forward STFT
    return cos.float().unsqueeze(1), sin.float().unsqueeze(1)

class RealSTFT(nn.Module):
    def forward(self, x: torch.Tensor) -> torch.Tensor:
        x = F.pad(x.reshape(-1, 1, x.shape[-1]), (n_fft // 2,) * 2, mode="reflect")
        real = F.conv1d(x, self.cos_kernel, stride=self.hop_length)
        imag = F.conv1d(x, self.sin_kernel, stride=self.hop_length)
        return torch.stack([real, imag], dim=1)   # (..., 2, F, T) real

Verificado em diferença absoluta máxima de 5 × 10⁻⁶ contra torch.stft diretamente. Mesmo truque para a inversa com ConvTranspose1d mais um envelope de janela ao quadrado em overlap-add.

Após essa correção, cada view_as_real / view_as_complex em _magnitude e _mask é reescrito para passar tensores de canais reais por todo o forward pass. Zero tensores complexos em qualquer lugar.

Bloqueador 2: fractions.Fraction em model.segment

O htdemucs_ft pré-treinado guarda o comprimento de segmento como Fraction(39, 5) (= 7,8 segundos). O Dynamo não consegue tracear aritmética de Fraction — levanta torch._dynamo.exc.Unsupported: call_function UserDefinedClassVariable(<class 'fractions.Fraction'>).

Correção. Coercer para float antes do export:

if isinstance(model.segment, Fraction):
    model.segment = float(model.segment)   # 7.8

Trivial. A matemática é idêntica na inferência.

Bloqueador 3: random.randrange no cross-transformer

CrossTransformerEncoder._get_pos_embedding chama o random.randrange do Python:

def _get_pos_embedding(self, T, B, C, device):
    if self.emb == "sin":
        shift = random.randrange(self.sin_random_shift + 1)
        return create_sin_embedding(T, C, shift=shift, ...)

Na inferência, sin_random_shift=0, então random.randrange(1) sempre retorna 0 — um no-op. Mas o exportador ONNX ainda não consegue enxergar através do módulo random do Python e falha.

Correção. Fazer monkey-patch do próprio método para que shift=0 fique hardcoded:

def _get_pos_embedding_no_random(self_, T, B, C, device):
    if self_.emb == "sin":
        return create_sin_embedding(T, C, shift=0, device=device,
                                    max_period=self_.max_period)
    # ... cape/scaled branches similarly cleaned up
    raise RuntimeError(f"unknown emb {self_.emb}")

for m in model.modules():
    if isinstance(m, CrossTransformerEncoder):
        m._get_pos_embedding = types.MethodType(_get_pos_embedding_no_random, m)

Matematicamente idêntico na inferência; exportável.

Bloqueador 4: aten::_native_multi_head_attention

O nn.MultiheadAttention.forward do PyTorch moderno faz curto-circuito para um kernel C++ fundido (_native_multi_head_attention) quando suas pré-condições são atendidas. Esse kernel não tem ONNX symbolic em nenhum opset, então o exportador lança UnsupportedOperatorError.

Correção. Substituir o forward de cada instância de nn.MultiheadAttention por uma implementação drop-in que usa apenas ops simples com symbolics ONNX estáveis (Linear, bmm, softmax, transpose):

def _onnx_friendly_mha_forward(self_, query, key, value, ...):
    if self_.batch_first:
        query, key, value = (t.transpose(0, 1) for t in (query, key, value))
    tgt_len, bsz, embed_dim = query.shape
    head_dim = embed_dim // self_.num_heads

    if self_._qkv_same_embed_dim and torch.equal(query, key) and torch.equal(key, value):
        q, k, v = F.linear(query, self_.in_proj_weight, self_.in_proj_bias).chunk(3, dim=-1)
    else:
        # cross-attention: three separate matmuls
        ...

    q = q.contiguous().view(tgt_len, bsz * self_.num_heads, head_dim).transpose(0, 1)
    k = k.contiguous().view(-1,      bsz * self_.num_heads, head_dim).transpose(0, 1)
    v = v.contiguous().view(-1,      bsz * self_.num_heads, head_dim).transpose(0, 1)

    attn_weights = F.softmax(torch.bmm(q * head_dim ** -0.5, k.transpose(1, 2)), dim=-1)
    attn_output  = torch.bmm(attn_weights, v).transpose(0, 1).contiguous().view(tgt_len, bsz, embed_dim)
    return self_.out_proj(attn_output), None

Aplicado em cada instância de MHA do modelo. Paridade verificada: 1 × 10⁻⁶ de diferença máxima vs o caminho rápido fundido.

O resultado

Com as quatro correções aplicadas, torch.onnx.export (exportador legado, opset 17, dynamo=False) grava um arquivo .onnx limpo de 316 MB em 6,5 segundos. Passa em onnx.checker.check_model, contém 24.765 nós e roda em onnxruntime sem configuração extra.

Os quatro stems são matematicamente equivalentes ao htdemucs_ft PyTorch oficial em fp32, bem abaixo da tolerância de 1e-3 que o drift de acumulação em ponto flutuante explicaria.

Os modelos ONNX exportados são 31% mais rápidos em CPU do que a baseline PyTorch no mesmo hardware — 1,59 s para um segmento de 7,8 s contra 2,09 s — porque o otimizador de grafo do ONNX Runtime consegue dobrar e fundir o grafo limpo de forma mais agressiva do que o runtime ansioso do PyTorch.

---

O que isso significa por plataforma

O mesmo arquivo .onnx roda em todo lugar onde onnxruntime roda. Abaixo, um quick-start por plataforma.

Python (qualquer SO, CPU ou GPU)

import onnxruntime as ort
import soundfile as sf

sess = ort.InferenceSession("htdemucs_ft_vocals.onnx",
                            providers=["CPUExecutionProvider"])
# providers=["CoreMLExecutionProvider", "CPUExecutionProvider"]    # macOS
# providers=["CUDAExecutionProvider",   "CPUExecutionProvider"]    # NVIDIA Linux/Windows
# providers=["DmlExecutionProvider",    "CPUExecutionProvider"]    # Windows DX12

audio, sr = sf.read("song.mp3", dtype="float32", always_2d=True)
stems = sess.run(["stems"], {"mix": audio.T[None].astype("float32")})[0]
sf.write("vocals.wav", stems[0, 3].T, sr)   # row 3 = vocals

O repositório correspondente: StemSplitio/htdemucs-ft-vocals-onnx.

iOS / Swift

import onnxruntime_objc

let opts = try ORTSessionOptions()
try opts.appendCoreMLExecutionProvider(with: ORTCoreMLExecutionProviderOptions())

let env = try ORTEnv(loggingLevel: .warning)
let session = try ORTSession(
    env: env,
    modelPath: Bundle.main.path(forResource: "htdemucs_ft_vocals", ofType: "onnx")!,
    sessionOptions: opts
)
// audio: 1 × 2 × 343980 Float32 buffer, then session.run(...)

Embarque o .onnx de 316 MB (ou um especialista menor) no bundle do app. O execution provider do CoreML faz o trabalho pesado no Apple Neural Engine quando disponível.

Android / Kotlin

import ai.onnxruntime.OrtEnvironment
import ai.onnxruntime.OrtSession

val env = OrtEnvironment.getEnvironment()
val opts = OrtSession.SessionOptions().apply { addNnapi() }
val session = env.createSession(modelPath, opts)

addNnapi() dá acesso à Neural Networks API do Android para inferência acelerada em NPUs Tensor / Snapdragon / MediaTek.

Web / onnxruntime-web

import * as ort from "onnxruntime-web";

const session = await ort.InferenceSession.create("htdemucs_ft_vocals.onnx", {
  executionProviders: ["wasm"],
  graphOptimizationLevel: "all",
});
const tensor = new ort.Tensor("float32", audioBuffer, [1, 2, 343980]);
const out = await session.run({ mix: tensor });

Sim, dá para rodar HT-Demucs FT no navegador. Sim, é mais lento que o CPU EP (imposto do WebAssembly), mas funciona com zero instalação para o usuário.

---

Números de performance

Medido em Apple M4 Pro (24 GB de memória unificada) para uma música de 3 minutos:

O ONNX de especialista único é 5,7× mais rápido que o PyTorch CPU para o mesmo stem com qualidade idêntica. Esse é o ganho de embarcar htdemucs-ft-vocals-onnx em um app vocal-remover em vez do bag PyTorch completo: binário menor, inferência mais rápida, mesmo SDR.

---

Como os especialistas de stem são derivados (um truque bonitinho)

O "bag" htdemucs_ft na verdade são 4 modelos separados. A matriz de pesos por stem do bag é one-hot:

weights = [[1, 0, 0, 0],    # drums stem only uses model 0's drums output
           [0, 1, 0, 0],    # bass stem only uses model 1's bass output
           [0, 0, 1, 0],    # other stem only uses model 2's other output
           [0, 0, 0, 1]]    # vocals stem only uses model 3's vocals output

Isso significa que a saída de bateria do bag é a saída de bateria do submodelo 0, bit-exata. Então, se você só precisa de bateria, embarcar o submodelo 0 sozinho (160 MB) entrega qualidade idêntica de bateria à do bag completo de 640 MB, a ~1/4 do custo de inferência.

Expusemos isso como cinco repositórios separados no Hugging Face: um bag completo ONNX (htdemucs-ft-onnx) para conveniência, mais quatro repositórios ONNX específicos por stem para deploys de produção que só precisam de um stem. O mesmo truque funciona para os repositórios irmãos em PyTorch.

Se você está construindo um extrator de samples de bateria, embarque htdemucs-ft-drums-onnx. Um transcritor de linhas de baixo? htdemucs-ft-bass-onnx. Um removedor de vocais ou gerador de karaokê? htdemucs-ft-vocals-onnx.

---

O que vem a seguir

Isso é Dia 1 + Dia 2 de um projeto ONNX de 3 dias. O Dia 3 é:

1. Profiling do execution provider CoreML. A primeira compilação MLProgram do grafo de 24k nós levou >5 minutos no M4 Pro em nossos testes. Precisamos investigar MinimumDeploymentTarget, ComputeUnits=CPUAndNeuralEngine e regras de fallback de subgrafo para tornar o CoreML EP realmente rápido em iOS / macOS.
2. Quantização dinâmica INT8. onnxruntime.quantization.quantize_dynamic por modelo — tipicamente arquivos 4× menores (~80 MB cada), queda de SDR geralmente abaixo de 0,3 dB em modelos de música. Ganho enorme em mobile se funcionar nesta arquitetura.
3. Um Space de demo em onnxruntime-web no Hugging Face. Separação de stems só no navegador, drag-and-drop, sem instalação, sem servidor. O tipo de demo que viraliza no Twitter e acaba em listas Awesome-ONNX.

Siga a organização StemSplitio no Hugging Face para receber as novidades quando saírem.

---

Como o HT-Demucs ONNX se compara a rodar PyTorch em 2026?

Para deploys server-side em Python onde você controla o runtime, PyTorch está bem — um pouco mais lento que ONNX Runtime em CPU, mas compatível out of the box com os helpers de overlap-add do apply_model.

Para todo o resto — apps iOS, apps Android, ferramentas de navegador, dispositivos embarcados, ferramentas de desktop Windows que querem evitar uma instalação de PyTorch de 2 GB — ONNX é o único caminho. Até esta semana, esse caminho estava bloqueado. Agora não está mais.

Se você está escolhendo entre os repositórios ONNX e a API do StemSplit para o seu produto, o trade-off é:

• Repositórios ONNX = sem custo por requisição, sem infraestrutura, mas você embarca 316+ MB no app e consome CPU/bateria do dispositivo do usuário.
• API do StemSplit = paga-se por segundo, mas com cold-start instantâneo, qualidade de GPU, sem empacotamento de modelo, sem manutenção de versões.

Para apps de consumidor com >1k separações / mês, a API normalmente ganha em custo total e experiência do usuário. Para ferramentas one-shot ou setups self-hosted, os modelos ONNX são a escolha certa.

---

Experimente a API do StemSplit — os mesmos modelos, hospedados para você

Não quer embarcar um modelo de 316 MB no app, gerenciar um pool de GPU ou escrever chunking com overlap-add? A API do StemSplit roda os mesmos modelos htdemucs_ft que você encontra nestes repositórios do Hugging Face, com créditos, fila e dashboard.

• 🌐 stemsplit.io — página do produto
• 📘 Documentação para desenvolvedores — comece por aqui
• 🔌 Referência da API — lista completa de endpoints
• 📚 Guias e receitas — integrações comuns

curl -X POST https://stemsplit.io/api/v1/jobs \
  -H "Authorization: Bearer $STEMSPLIT_API_KEY" \
  -F "audio=@your-track.mp3" \
  -F "model=htdemucs_ft"

Ou use as ferramentas no-code que rodam essa mesma família de modelos hoje:

• 🎤 Removedor de Vocais — remova vocais de qualquer música, em segundos
• 🎶 Gerador de Karaokê — instrumental + acapella em uma única passada
• 🎙️ Gerador de Acapella — vocais isolados e limpos
• 📺 YouTube Stem Splitter — cole uma URL, receba 4 stems
• 🎛️ Stem Splitter — separação genérica em 4 stems

---

FAQ

Dá para exportar o HT-Demucs FT para ONNX e usar em iOS e Android em 2026?

Sim — desde maio de 2026, o StemSplitio/htdemucs-ft-onnx entrega o primeiro export ONNX funcional do bag completo de 4 stems do htdemucs_ft. Roda em onnxruntime-mobile no iOS (CoreML EP) e Android (NNAPI EP) com a mesma saída numérica do PyTorch original. Tentativas anteriores falharam porque o htdemucs_ft usa tensores complexos, fractions.Fraction do Python, random.randrange e o kernel de multi-head attention fundido do PyTorch — todos itens que os exportadores ONNX padrão se recusam a tratar. Esta release corrige os quatro bloqueadores e verifica paridade dentro de 1,63 × 10⁻⁴ de diferença absoluta máxima.

Quão preciso é o export ONNX comparado ao modelo PyTorch do HT-Demucs FT?

Bit-equivalente em fp32 dentro do drift normal de acumulação em ponto flutuante. Especificamente, a diferença absoluta máxima entre a saída do ONNX Runtime e do PyTorch é 0.000163 em bateria, 0.000011 em baixo, 0.000739 em "outros" e 0.000008 em vocais — todos bem abaixo da tolerância de 0.001 que o reordenamento em fp32 tipicamente explica. As notas de SDR no conjunto de teste stem-separation-benchmark-2026 sobre MUSDB18-HQ são idênticas à baseline PyTorch.

O HT-Demucs FT é realmente mais rápido em ONNX do que em PyTorch?

Em CPU, sim — cerca de 1,31× mais rápido (1,59 s vs 2,09 s por segmento de 7,8 s no M4 Pro). O otimizador de grafo do ONNX Runtime consegue dobrar e fundir o grafo limpo de forma mais agressiva do que o runtime ansioso do PyTorch. Em GPU, PyTorch e ONNX Runtime + CUDA ficam mais ou menos empatados; ambos ganham da CPU por larga margem. Os maiores ganhos vêm de embarcar um único especialista (drums/bass/other/vocals) em vez do bag completo — eles são ~4× mais rápidos que o bag completo com qualidade por stem idêntica.

Qual é a melhor forma de rodar HT-Demucs FT em um navegador para um web app removedor de vocais?

Use o StemSplitio/htdemucs-ft-vocals-onnx com onnxruntime-web. O execution provider WebAssembly suporta o modelo completo. Espere latência mais alta do que nativo (imposto do sandbox do navegador), mas zero instalação e zero custo de servidor. Para tráfego de produção, a API do StemSplit costuma ser a melhor escolha econômica e de UX — mesmo modelo, acelerado por GPU, pago por segundo.

Dá para treinar seu próprio modelo HT-Demucs em ONNX do zero?

Sim — o repositório oficial do demucs traz o código de treinamento. Uma vez que você tenha seu checkpoint .th treinado, os patches dos nossos scripts coreml-conversion se aplicam sem alterações. Estamos considerando abrir o código do pipeline de export como um pacote Python demucs-onnx — abra uma discussão em qualquer repositório de modelo StemSplitio se isso for útil para você.

---

Receba avisos sobre o Dia 3

Inscreva-se na org StemSplitio no Hugging Face ou siga o dataset de benchmark — é lá que as variantes quantizadas em INT8, o relato do profiling de CoreML e o Space de demo no navegador vão chegar primeiro.

Se você está construindo algo com esses modelos, adoraríamos saber. Abra uma discussão em qualquer um dos repositórios ou fale com a gente em stemsplit.io/contact.

---

Todos os artefatos desta release estão sob licença MIT. HT-Demucs original por Rouard, Massa & Défossez (Meta AI); por favor, cite o paper deles no ICASSP 2023 se você usar o modelo em pesquisa.