HT-Demucs FT から ONNX へ：iOS・Android・Web 向け初の動作確認エクスポートの構築方法 — Hugging Face で 9 つのオープンモデルと再現可能な MUSDB18-HQ ベンチマーク公開（2026年）

TL;DR. Hugging Face で 10 個のステム分離アセットをオープンソース化しました。その中には、MUSDB18-HQ で第 1 位のオープンソース・ボーカル分離器である HT-Demucs FT の初の動作確認 ONNX エクスポートも含まれます。これまで「demucs onnx」へのあらゆる試みは同じ 4 つの障壁で停止していましたが、私たちはそのすべてを突破しました。結果として、推論時に PyTorch を必要とせず、onnxruntime 上で CPU/CoreML/CUDA/DirectML で動作し、CPU で PyTorch より 1.31 倍高速、かつ元のモデルと数値的に等価（4 ステム全体で最大絶対誤差 0.000163）です。

以下では、リリース内容、その意義、そして ONNX エクスポートを実際にどう実現したかというエンジニアリングの記録を紹介します。

---

今週リリースしたすべてのアセット

すべて MIT ライセンス、すべて StemSplitio org ページで公開しています。

ヘッドライン： ONNX リポジトリは、私たちが知る限り Hugging Face 上で初めて動作する HT-Demucs FT の ONNX エクスポートです。「初の試み」ではなく、ロードでき、動作し、正しい数値を出力し、パリティ検証済みのベンチマークが付属する、初めて出荷可能なものです。

---

なぜこれをやったのか

ベンチマークの空白

2026 年にステム分離モデルを選ぼうとすると、状況は混沌としています。どのモデルリポジトリも自分のモデルを「state of the art」と主張します。再現可能なベンチマークを公開しているところはほとんどなく、同じハードウェア・同じ指標で同じモデルを横並びにテストしているものはさらに稀です。

私たちは stem-separation-benchmark-2026 を公開してこれを解決しました — MUSDB18-HQ 上で htdemucs、htdemucs_ft、htdemucs_6s、mdx_extra_q、mdx_net_inst_hq3 の SDR / ISR / SIR / SAR スコアを 850 行収録し、評価パイプライン全体をオープンソース化しました。誰でもクローンして再実行し、数値を検証できます。

主な発見：htdemucs_ft がオープンソースのボーカル分離器で 1 位（ボーカル SDR 中央値 9.19 dB）、mdx_extra_q がドラム/ベース/その他で 1 位（11.49 / 11.42 / 7.67 dB）。ステムごとに最適なモデルが異なるという結論です。

ONNX の空白

より大きな問題は、HT-Demucs FT を iOS、Android、ブラウザで使いたくても、これまで不可能だったことです。PyTorch のモバイル対応は荒削りで、MPS/CUDA はサーバー側でしか動作せず、本来の答えである ONNX への移植は誰も完遂していませんでした。

demucs リポジトリには ONNX エクスポートを求める Open な GitHub Issue が少なくとも 4 件あります。半分壊れたフォークが複数、マージされない 2023 年の PR、M1 以降の Mac を必要とする MLX 実験がいくつか。「ただ動く」ものはありませんでした。

その理由は、HT-Demucs には PyTorch では innocent に見えても ONNX エクスポータを非自明な形で壊すアーキテクチャ上の選択が含まれているからです。私たちは 4 つすべてに遭遇し、修正しました — これがこの記事の本題です。

---

HT-Demucs FT があらゆる ONNX エクスポータを壊す理由

最初に torch.onnx.export、次に torch.onnx.dynamo_export を試しました。両方とも別の場所で失敗しました。以下が障壁の全カタログと、それぞれの修正方法です。

障壁 1：complex64 の STFT 出力

HT-Demucs は 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")

その return_complex=True は complex64 テンソルを返します。CoreML の MIL には複素数 dtype がありません。ONNX の STFT 演算（opset 17 以降）も複素出力をサポートしていません。グラフ内の下流のスライス/転置オペレータがすべて即座に失敗します。

修正。 torch.stft を、sin/cos カーネルを使う Conv1d に置き換え、実数 2 チャンネルを直接出力します。

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

torch.stft と直接比較して最大絶対誤差 5 × 10⁻⁶まで検証済みです。逆変換も同じトリック（ConvTranspose1d + オーバーラップアドの window-squared エンベロープ）で対応できます。

この修正後、_magnitude と _mask のすべての view_as_real / view_as_complex を、実数チャンネルテンソルが順伝播全体を流れるように書き換えます。複素テンソルはどこにも残りません。

障壁 2：model.segment の fractions.Fraction

事前学習済みの htdemucs_ft はセグメント長を Fraction(39, 5)（= 7.8 秒）として保持しています。Dynamo は Fraction の演算をトレースできず、torch._dynamo.exc.Unsupported: call_function UserDefinedClassVariable(<class 'fractions.Fraction'>) を発生させます。

修正。 エクスポート前に float に変換します。

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

簡単です。推論時の数学的結果は同一です。

障壁 3：cross-transformer の random.randrange

CrossTransformerEncoder._get_pos_embedding は Python の random.randrange を呼び出します。

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, ...)

推論時には sin_random_shift=0 のため、random.randrange(1) は常に 0 を返し、no-op になります。しかし ONNX エクスポータは Python の random モジュールを見通せず、失敗します。

修正。 メソッド自体をモンキーパッチして shift=0 をハードコードします。

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)

推論時には数学的に同一で、エクスポート可能になります。

障壁 4：aten::_native_multi_head_attention

最新の PyTorch の nn.MultiheadAttention.forward は、前提条件が満たされると融合された C++ カーネル（_native_multi_head_attention）にショートサーキットします。このカーネルはどの opset でも ONNX シンボリックを持たないため、エクスポータは UnsupportedOperatorError を投げます。

修正。 各 nn.MultiheadAttention インスタンスの forward を、安定した ONNX シンボリックを持つプレーンな演算（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

モデル内のすべての MHA インスタンスにパッチを当てます。融合された高速パスとのパリティ検証済み：最大絶対誤差 1 × 10⁻⁶。

結果

4 つのパッチをすべて適用すると、torch.onnx.export（レガシーエクスポータ、opset 17、dynamo=False）はクリーンな 316 MB の .onnx ファイルを 6.5 秒で書き出します。onnx.checker.check_model を通過し、24,765 個のノードを含み、onnxruntime でそのまま動作します。

4 ステムすべてが fp32 で公式の PyTorch htdemucs_ft と数学的に等価で、浮動小数点の累積ドリフトで説明できる 1e-3 の許容範囲を十分下回っています。

エクスポートされた ONNX モデルは同じハードウェア上で PyTorch ベースラインより CPU で 31% 高速です — 7.8 秒のセグメントに対して 1.59 秒 vs 2.09 秒 — ONNX Runtime のグラフ最適化器がクリーンアップされたグラフを PyTorch の eager runtime よりも積極的に折りたたみ・融合できるためです。

---

プラットフォーム別の意味

同じ .onnx ファイルが onnxruntime の動くすべての環境で動作します。プラットフォーム別のクイックスタートは以下のとおりです。

Python（任意の OS、CPU または 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

対応するリポジトリ：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(...)

316 MB の .onnx（あるいはより小さい特化版）をアプリバンドルに同梱します。CoreML 実行プロバイダは可能な場合に Apple Neural Engine で重い処理を実行します。

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() により、Tensor / Snapdragon / MediaTek の NPU で高速化された推論のための Android Neural Networks API が利用できます。

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 });

はい、HT-Demucs FT はブラウザでも動きます。はい、CPU EP よりは遅い（WebAssembly のオーバーヘッド）ですが、ユーザーはインストール不要で利用できます。

---

パフォーマンス値

Apple M4 Pro（24 GB ユニファイドメモリ）で 3 分の楽曲を計測した結果：

単一ステム特化版の ONNX は同一品質で同じステムに対して PyTorch CPU より 5.7 倍高速です。ボーカル除去アプリにフルの PyTorch バッグではなく htdemucs-ft-vocals-onnx を載せる利点：バイナリが小さく、推論が速く、SDR は同等。

---

ステム特化モデルの導出方法（小技）

htdemucs_ft の「バッグ」は実際には 4 つの別個のモデルです。バッグのステムごとの重み行列はワンホットです。

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

つまりバッグの drums 出力はサブモデル 0 の drums 出力そのもので、ビット単位で同一です。したがってドラムだけ必要なら、サブモデル 0 のみ（160 MB）を出荷すれば、フル 640 MB のバッグと同等のドラム品質を約 1/4 の推論コストで得られます。

これを 5 つの別の Hugging Face リポジトリとして公開しました：利便性のためのフルバッグ ONNX（htdemucs-ft-onnx）と、1 ステムしか必要としない本番デプロイ向けの 4 つのステム特化 ONNX リポジトリ。PyTorch 版でも同じトリックが使えます。

ドラムサンプル抽出を構築するなら htdemucs-ft-drums-onnx を。ベースライン採譜なら htdemucs-ft-bass-onnx。ボーカルリムーバーやカラオケメーカーなら htdemucs-ft-vocals-onnx です。

---

次のステップ

これは 3 日間の ONNX プロジェクトのうちの 1 日目 + 2 日目です。3 日目は以下を予定しています：

1. CoreML 実行プロバイダのプロファイリング。 24k ノードのグラフの初回 MLProgram コンパイルは、M4 Pro 上のテストで 5 分以上かかりました。CoreML EP を iOS / macOS で真に高速にするため、MinimumDeploymentTarget、ComputeUnits=CPUAndNeuralEngine、サブグラフのフォールバックルールを調査する必要があります。
2. INT8 動的量子化。 モデルごとの onnxruntime.quantization.quantize_dynamic — 通常はファイルが 4 倍小さくなり（各 ~80 MB）、音楽モデルでの SDR 低下は通常 0.3 dB 未満。このアーキテクチャで動けば大きなモバイル向けの勝利。
3. Hugging Face 上の onnxruntime-web デモ Space。 ブラウザのみでのステム分離、ドラッグ＆ドロップ、インストール不要、サーバー不要。Twitter で共有され、Awesome-ONNX 系のリストに載るタイプのデモ。

これらの公開状況については StemSplitio Hugging Face org をフォローしてください。

---

HT-Demucs ONNX は 2026 年の PyTorch 運用と比べてどうか？

ランタイムを自身で制御するサーバーサイド Python のデプロイでは、PyTorch で問題ありません — CPU では ONNX Runtime よりわずかに遅いものの、apply_model のオーバーラップアド補助機能とそのまま互換性があります。

それ以外すべて — iOS アプリ、Android アプリ、ブラウザツール、組み込み機器、2 GB の PyTorch インストールを避けたい Windows デスクトップツール — では ONNX が唯一の道です。今週まで、その道は塞がれていました。今はもう違います。

製品で ONNX リポジトリと StemSplit API のどちらを選ぶか迷うなら、トレードオフは以下のとおりです：

• ONNX リポジトリ = リクエスト単位の費用なし、インフラ不要、ただしアプリに 316+ MB を同梱し、ユーザー端末の CPU/バッテリーを消費。
• StemSplit API = 秒単位課金、ただし即時のコールドスタート、GPU グレードの品質、モデルの同梱不要、バージョン管理不要。

月 1,000 件以上の分離を行うコンシューマアプリでは、総コストとユーザー体験で API のほうが優れることが多いです。単発のツールやセルフホスト構成では ONNX モデルが正解です。

---

StemSplit API を試す — 同じモデル、ホスティングはお任せ

アプリに 316 MB のモデルを同梱したくない、GPU プールを管理したくない、オーバーラップアドのチャンキングを書きたくない？ StemSplit API は、Hugging Face リポジトリにあるのと同じ htdemucs_ft モデルを、クレジット、キューイング、ダッシュボード付きで提供します。

• 🌐 stemsplit.io — プロダクトホーム
• 📘 開発者ドキュメント — まずはここから
• 🔌 API リファレンス — エンドポイント一覧
• 📚 ガイド & レシピ — よくある統合例

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

または、同じモデルファミリーを使うノーコードツールをすぐに利用できます：

• 🎤 ボーカルリムーバー — どんな曲からも数秒でボーカルを除去
• 🎶 カラオケメーカー — インストとアカペラを一括取得
• 🎙️ アカペラメーカー — クリーンな分離ボーカル
• 📺 YouTube ステムスプリッター — URL を貼って 4 ステムを取得
• 🎛️ ステムスプリッター — 汎用の 4 ステム分離

---

FAQ

2026年に iOS や Android で使うために HT-Demucs FT を ONNX にエクスポートできますか？

はい — 2026 年 5 月時点で、StemSplitio/htdemucs-ft-onnx が htdemucs_ft フル 4 ステムバッグの初の動作確認 ONNX エクスポートを提供しています。iOS（CoreML EP）と Android（NNAPI EP）の onnxruntime-mobile で、PyTorch オリジナルと同じ数値出力で動作します。これまでの試みが失敗したのは、htdemucs_ft が複素テンソル、Python の fractions.Fraction、random.randrange、そして PyTorch の融合マルチヘッドアテンションカーネルを使用しており、これらすべてを標準の ONNX エクスポータが処理できなかったからです。本リリースは 4 つの障壁すべてにパッチを当て、最大絶対誤差 1.63 × 10⁻⁴ までのパリティを検証しています。

ONNX エクスポートは PyTorch 版の HT-Demucs FT モデルと比べてどれくらい正確ですか？

fp32 で通常の浮動小数点累積ドリフト範囲内のビット等価です。具体的には、ONNX Runtime 出力と PyTorch 出力の最大絶対誤差は drums で 0.000163、bass で 0.000011、other で 0.000739、vocals で 0.000008 — いずれも fp32 の演算順序入れ替えで通常説明される 0.001 の許容範囲を十分下回っています。stem-separation-benchmark-2026 の MUSDB18-HQ テストセットでの SDR スコアは PyTorch ベースラインと同一です。

HT-Demucs FT は ONNX のほうが PyTorch より本当に高速ですか？

CPU では、はい — 約 1.31 倍高速（M4 Pro 上で 7.8 秒セグメントあたり 1.59 秒 vs 2.09 秒）。ONNX Runtime のグラフ最適化器は、PyTorch の eager runtime よりも積極的にクリーンアップ済みグラフを折りたたみ・融合できます。GPU では PyTorch と ONNX Runtime + CUDA はほぼ同等で、どちらも CPU より大きく勝ります。さらに大きな勝利は、フルバッグではなく単一の特化版（drums/bass/other/vocals）を出荷することから来ます — これらはステムごとの品質が同等のままフルバッグより約 4 倍高速です。

ボーカル除去 Web アプリでブラウザ上で HT-Demucs FT を実行する最良の方法は？

StemSplitio/htdemucs-ft-vocals-onnx を onnxruntime-web で使うのがベストです。WebAssembly 実行プロバイダはモデル全体をサポートします。ネイティブよりレイテンシが高くなることは想定してください（ブラウザサンドボックスのオーバーヘッド）が、インストール不要、サーバー費用ゼロです。本番トラフィックでは StemSplit API のほうが経済性と UX の両面で通常は良い選択 — 同じモデル、GPU で高速化、秒単位課金です。

自分で ONNX HT-Demucs モデルをゼロから学習できますか？

はい — 公式の demucs リポジトリが学習コードを提供しています。学習済みの .th チェックポイントを用意できれば、coreml-conversion スクリプトのパッチがそのまま適用できます。エクスポートパイプラインを demucs-onnx Python パッケージとしてオープンソース化することも検討中です — もし役に立ちそうなら StemSplitio モデルリポジトリのいずれかでディスカッションを立ててください。

---

3 日目の通知を受け取る

Hugging Face の StemSplitio org を購読するか、ベンチマークデータセットをウォッチしてください — INT8 量子化版、CoreML プロファイリングの記事、ブラウザデモ Space は、まずそこに公開されます。

これらのモデルで何か作っているなら、ぜひお聞かせください。いずれかのリポジトリでディスカッションを開くか、stemsplit.io/contact からご連絡ください。

---

本リリースのすべての成果物は MIT ライセンスです。元の HT-Demucs は Rouard, Massa & Défossez（Meta AI）による作品です。研究でモデルを使用する場合は ICASSP 2023 の論文を引用してください。