AI News
商业产业 Hacker News AI 2026-08-29T01:24 正文 ok 2765 words

🔶 StemDeck：免费、开源、完全本地运行的 AI 音轨分离工具

英文标题：🔶 StemDeck, a free, open-source and local AI stem separator

StemDeck 是一款免费开源的本地 AI 音轨分离工具，可将本地音频或符合处理权利要求的 YouTube 内容拆分为最多 6 条音轨，包括人声、鼓、贝斯、吉他、钢琴及其他声部。它基于 Meta AI 开源的 Demucs `htdemucs_6s` 模型，可在 NVIDIA CUDA、Apple Silicon MPS 或 CPU 上运行，且音频无需上传、无需账号或订阅。软件提供类似 DAW 的多轨混音、波形编辑、单轨导出、BPM/调性/响度分析及本地曲库管理功能。与 Moises、LALAL.AI 等云端产品相比，StemDeck 的重点是隐私、本地运行和可自托管，但在模型质量、移动端、批处理及专业功能完整度上存在取舍。
打开原文相关 2 · 机会 2
media1.5 KB media2.2 KB media754 B media560 B media566 B media575 B media1.7 KB media2.4 KB media2.3 KB media3.4 KB media1.0 KB media16.1 KB media1.3 MB media62.7 KB media62.7 KB media620 B media573 B media2.9 KB media76.8 KB

中文

StemDeck

免费、本地音轨分离。无需账号。无需上传。无需订阅。

将 MP3、WAV、FLAC、OGG/Opus、MP4 或 M4A 文件拖入，或粘贴 YouTube URL，StemDeck 即可将音频拆分为最多六条音轨（人声、鼓、贝斯、吉他、钢琴、其他）。你可以在类似 DAW 的多轨混音器中回放这些音轨：静音、独奏、平衡音量、缩放波形、循环某个区域，并导出单独音轨或自定义混音。所有操作均在你自己的设备上本地完成。

这是什么？ StemDeck 是一款音轨分离工具，并非下载工具。它的主要用途是处理你已拥有的音频：将 MP3、WAV、FLAC、OGG 或 M4A 拖到导入栏即可开始。YouTube 支持只是为了方便处理你有权处理的内容。StemDeck 不会存储、缓存或重新分发任何下载内容。所有操作都在本地进行，任何内容都不会离开你的设备。

StemDeck 是 Moises、LALAL.AI 等云端音轨分离服务的免费开源替代方案：无需账号、无配额、无需上传、无需订阅。如果你希望为个人学习获取音轨，并倾向于本地、免费地处理内容，StemDeck 可以满足需求。如果你需要更精致的体验、移动端应用或更深入的音乐人工具，商业产品会更适合。

StemDeck 截图

Star History 图表

StemDeck 是免费的，且不接受下列任何个人或机构的金钱、赞助或资助。作者分享这些创作者、艺术家和社群，纯粹是希望将你介绍给从事美好创作的优秀人士。欢迎去认识他们 ❤️

名称 他们的工作 链接
Analog4Lyfe 全模拟音乐设备，不走数字捷径 @analog4lyfe
r/bass 作者喜爱的 Reddit 贝斯社群 r/Bass
Beltr 将你已拥有的歌曲在本机变成出色的卡拉 OK，无订阅、无云端，只有你和麦克风 beltr.app
Dlima Guitars 一次打造一把的定制吉他与贝斯 @dlimaguitars
Empress Effects 面向不愿妥协音色追求者的精品效果器踏板 empresseffects.com
Joao Gaspar 制作人及电影配乐师，也从事巡演与录音室乐手工作 @jay_glaspar
Kris Luthier 在里斯本手工维修和修复乐器，一次细致修复一件 @krisluthier
Lisbon Guitar Works 在里斯本手工制作的吉他 dlimaguitars.com
More Notes Less Talk 充满个性的乐器和设备，以磁带原始录制。没有炒作，不设门槛。 @morenoteslesstalk
Seratone 将任何电视变成录音室级别的卡拉 OK 舞台 seratone.audio
slashCAM 德语摄影与视频技术内容：实测、行业新闻，以及大多数评测忽略的后期制作细节 @slashcam.de
Thomann 欧洲最大的音乐设备零售商之一，几乎涵盖音乐人所需的一切 @thomann.music

6 音轨分离：通过 Demucs htdemucs_6s 实现，并自动检测最佳 Torch 设备（NVIDIA 使用 CUDA，Apple Silicon 使用 MPS，CPU 作为回退方案）。

YouTube 与本地文件导入。 粘贴 YouTube URL，或将 MP3、WAV、FLAC、OGG/Opus、MP4 或 M4A 直接拖到导入栏。

DAW 风格波形编辑器：支持跨全部音轨的最小值/最大值采样渲染、共享归一化、放大/缩小/适配视图、在标尺上拖动设置循环区、金色播放头叠层，以及按音轨对齐的通道。

音轨子集提取。 点击音轨标签以选择要保留的音轨。从“全部已选中”状态点击某一音轨，会直接切换为“仅保留这一条”；后续点击可添加或移除音轨。

“Original”伴奏轨。 选择一个子集后，第 7 条通道会包含其补集（完整歌曲减去所选音轨），适合在不发生叠加的情况下进行 A/B 参考。

可下载的所选混音。 可获得仅包含已选音轨、通过 ffmpeg amix 混合生成的单个 mix.wav 文件。

逐轨混音器：每条音轨均提供音量推子、静音、独奏和“监听”（仅独奏）功能。预览混音器和音轨侧边栏之间会同步状态。

实时 VU 表。 每条音轨都提供后增益 RMS 电平显示，使用 Web Audio analyser 实现峰值保持与缓慢衰减。

歌曲分析：包括 BPM（librosa 节拍跟踪器）、调性、音阶与置信度（Albrecht-Shanahan profiles）、综合 LUFS（BS.1770），以及以 dBFS 表示的采样峰值。

可取消任务。 可在处理管线中途取消任务；运行器会立即终止活跃子进程、删除未完成的任务目录，并恢复至就绪状态。

曲库面板：支持基于文件夹的曲目整理、拖放、搜索和移至废纸篓。

StemDeck 并不试图与商业音轨分离产品竞争。它较好地覆盖了核心使用场景，并止步于此。下表旨在帮助你在使用前了解差异，而不是事后才发现功能缺口。

| StemDeck | Moises / LALAL.AI / 同类产品
---|---|---
价格 | 永久免费 | 免费增值；经常使用需购买点数或订阅
托管方式 | 完全在你的设备上运行 | 云端；音频必须上传到其服务器
账号 / 登录 | 无需 | 必需
是否需要网络 | 仅用于下载 YouTube 内容和首次获取模型（约 170 MB，之后会缓存） | 始终需要；不支持离线使用
隐私 | 音频绝不会离开你的设备 | 音频会上传至第三方服务器并被处理
数据保留 | 由你控制；可随时删除 | 受其隐私政策和数据保留期限约束
音轨模型 | Demucs htdemucs_6s（开源，Meta AI） | 专有模型，持续更新，整体质量通常更高
音轨数量 | 6 条（人声、鼓、贝斯、吉他、钢琴、其他） | 最多 10 条，取决于服务和套餐
输入格式 | YouTube URL、MP3、WAV、FLAC、OGG/Opus、MP4、M4A | MP3、WAV、FLAC、M4A 等，取决于服务
处理速度 | 取决于你的硬件；GPU 较快，仅 CPU 时较慢 | 不受你的硬件影响，速度较快（在其服务器上运行）
批处理 | 每次一个任务 | 支持，限付费套餐
移动应用 | 无 | iOS 和 Android
额外功能 | 无（无变调、和弦检测、歌词、节拍器轨、BPM 点按） | 有，因产品而异
完成度 | 功能可用、业余级 UI | 精致的生产级应用
源代码 | 开源，可 Fork、可自行托管 | 闭源

如果你需要速度、质量、移动端访问或额外的音乐人工具，商业产品值得付费。如果你只是想为个人学习获取音轨、希望音频保持私密，或只需要一个没有附加条件的本地运行工具，StemDeck 已经足够。

每个 GitHub Release 均附有预构建安装包和压缩包。

macOS

DMG GPU 芯片
StemDeck-macOS-arm64.dmg Apple Silicon（MPS） M1 及后续机型
StemDeck-macOS-x64.dmg 仅 CPU Intel

打开 DMG，将 StemDeck 拖到“应用程序”文件夹后启动。首次启动时，设置界面会下载 Python 运行时（约 500 MB）、FFmpeg 和 Demucs 模型（约 170 MB）。后续启动会跳过设置，并在数秒内打开。无需安装 Python 或其他系统依赖。

macOS 首次打开时可能显示 Gatekeeper 提示——右键点击应用，选择“打开”即可绕过。

Windows

压缩包 GPU 约占空间
StemDeck-Windows-x64.zip 仅 CPU 约 700 MB
StemDeck-Windows-x64.NVIDIA.zip NVIDIA CUDA 约 1.6 GB

将压缩包解压至任意位置，运行 StemDeck.exe。FFmpeg、Demucs 模型、配置和日志均位于 StemDeck.exe 旁边的 data/ 文件夹中，而非 AppData；将整个解压目录移动或复制到任何位置后，软件仍可正常工作。首次启动时，应用会验证内置的 Python 运行时，并将 FFmpeg 和 Demucs 模型（约 170 MB）下载至该目录。后续启动会跳过这一步，并在数秒内打开。一切均为自包含，无需 Python 或其他系统依赖。你的任务/曲库数据保留在常规位置（默认是 ~/Documents/StemDeck），并可随时在“设置 → StemData location”中迁移。

StemDeck 基于由 uv 管理的 Python 3.12 构建，后端使用 FastAPI 提供 REST 和 Server-Sent Events 服务。音轨分离使用 Demucs（htdemucs_6s），即 Meta AI 的开源 6 音轨神经网络。可选的按需主唱/伴唱人声分离通过 audio-separator 运行 UVR-MDX-NET Karaoke 2 模型；该模型作为 Anjok07 的 Ultimate Vocal Remover 项目的一部分训练。YouTube 音频通过 yt-dlp 获取；转码和混音使用 FFmpeg。BPM 检测与调性分析基于 librosa；响度测量使用 pyloudnorm（ITU-R BS.1770）。macOS 和 Windows 桌面壳采用 Tauri v2（macOS 上为 Rust/WKWebView，Windows 上为 Rust/WebView2）。前端采用原生 JS 与 Web Audio API，不使用框架，也没有构建步骤；波形通过 <canvas> 使用最小值/最大值采样渲染。

感谢所有让 StemDeck 成为可能的开源库创作者与维护者。

需要 Rust、Node.js 和 Python 3.12。构建出的自包含 .app 会在首次启动时下载自己的运行时。

# 仅首次需要——添加交叉编译目标
rustup target add aarch64-apple-darwin   # Apple Silicon
rustup target add x86_64-apple-darwin    # Intel

# 构建 Apple Silicon 版本
ARCH=arm64 scripts/macos/make-runtime-pack.sh
ARCH=arm64 scripts/macos/make-app.sh
ARCH=arm64 scripts/macos/make-dmg.sh

# 构建 Intel 版本（需要 Rosetta 2 和 x86_64 Python）
ARCH=x64 scripts/macos/make-runtime-pack.sh
ARCH=x64 scripts/macos/make-app.sh
ARCH=x64 scripts/macos/make-dmg.sh

.app 会生成在 desktop/src-tauri/target/<target>/release/bundle/macos/StemDeck.app，DMG 会生成在 .build/macos-dist/StemDeck-macOS-<arch>.dmg。

如需不经由 DMG 直接运行刚构建的版本：

open desktop/src-tauri/target/aarch64-apple-darwin/release/bundle/macos/StemDeck.app

如果 macOS 以 Gatekeeper 提示阻止应用，请运行：

xattr -dr com.apple.quarantine desktop/src-tauri/target/aarch64-apple-darwin/release/bundle/macos/StemDeck.app

注意： 在开发期间，如需测试干净的首次启动状态，可先清除之前的应用数据：rm -rf ~/Library/Application\ Support/StemDeck。请不要在实际安装环境中这样做。

Web Server（macOS / Linux / Windows，Python 3.12+）

需要 Python 3.12 或更新版本、已加入 PATH 的 ffmpeg 以及 uv。Demucs 模型需要约 170 MB 可用磁盘空间，并会在首次运行时自动下载。

git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck
./run.sh setup     # 安装 ffmpeg + uv，并运行 uv sync
./run.sh start

打开 http://localhost:8000。

setup 在 macOS 上使用 Homebrew，在 Debian/Ubuntu 上使用 apt-get。对于其他 Linux 发行版，请手动安装 ffmpeg 和 uv，然后运行 uv sync，接着执行 ./run.sh start。

安装前置依赖：

  • uv — winget install astral-sh.uv

  • ffmpeg — winget install Gyan.FFmpeg（或 Chocolatey：choco install ffmpeg）

    git clone https://github.com/stemdeckapp/stemdeck stemdeck; cd stemdeck uv sync uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --timeout-graceful-shutdown 5

打开 http://localhost:8000。

run.sh 仅适用于 macOS/Linux。Windows 请使用上述 PowerShell 命令，或在 WSL 中运行。

NVIDIA GPU（CUDA）： 启动前安装启用 CUDA 的 torch 构建版本：

uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
$env:STEMDECK_DEMUCS_DEVICE = "cuda"
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --timeout-graceful-shutdown 5

git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck
uv sync
uv run uvicorn app.main:app --reload --timeout-graceful-shutdown 5

--timeout-graceful-shutdown 用于限制停止 uvicorn 时等待开放连接的时长。当浏览器标签页打开应用时，StemDeck 会为导入队列保持一个长期存在的 SSE 流；如果没有该参数，按下 Ctrl-C 时程序会等待该流关闭，而不会直接退出。

English / 原文

StemDeck

Free, local stem separation. No account. No upload. No subscription.

JOIN THE COMMUNITY

Drop in an MP3, WAV, FLAC, OGG/Opus, MP4, or M4A file, or paste a YouTube URL, and StemDeck splits the audio into up to six stems (vocals, drums, bass, guitar, piano, other). Play them back in a DAW-style multitrack mixer: mute, solo, balance levels, zoom the waveform, loop a region, and export individual stems or a custom mix. Everything runs locally on your own machine.

What is this? StemDeck is a stem separation tool, not a downloader. Its main job is processing audio you already own: drag an MP3, WAV, FLAC, OGG, or M4A onto the import bar and go. YouTube support is a convenience for content you have the right to process. StemDeck does not store, cache, or redistribute any downloaded content. Everything happens locally and nothing leaves your machine.

StemDeck is a free, open alternative to cloud stem-splitters like Moises and LALAL.AI: no account, no quota, no uploads, no subscription. If you want stems for personal study and prefer to keep things local and free, StemDeck has you covered. If you need the polish, a mobile app, or deeper musician tooling, the commercial products are a better fit.

StemDeck screenshot

Star History Chart

StemDeck is free and does not accept any money, sponsorship, or funding from anyone listed below. I share these makers and artists and communities purely for the joy of pointing you toward wonderful people doing beautiful work. Go meet them ❤️

Name What they do Link
Analog4Lyfe All-analog music gear, no digital shortcuts @analog4lyfe
r/bass My beloved bass community on reddit r/Bass
Beltr Turns the songs you already own into karaoke gold, right on your own machine, no subscription, no cloud, just you and the mic beltr.app
Dlima Guitars Custom guitars and basses, built one at a time @dlimaguitars
Empress Effects Boutique effects pedals for tone chasers who don't settle empresseffects.com
Joao Gaspar Producer and film scorer, also plays as a touring/session musician @jay_glaspar
Kris Luthier Hand-repairs and restores instruments in Lisbon, one careful fix at a time @krisluthier
Lisbon Guitar Works Guitars built by hand in Lisbon dlimaguitars.com
More Notes Less Talk Instruments and gear with personality, recorded raw to tape. No hype, no gatekeeping. @morenoteslesstalk
Seratone Turns any TV into a studio-grade karaoke stage seratone.audio
slashCAM German-language camera and video tech: hands-on tests, industry news, and the post-production details most reviews skip @slashcam.de
Thomann One of Europe's largest music gear retailers, practically everything a musician could need @thomann.music

6-stem separation via Demucs htdemucs_6s, with auto-detection of the best Torch device (CUDA on NVIDIA, MPS on Apple Silicon, CPU fallback).

YouTube and local file import. Paste a YouTube URL or drop an MP3, WAV, FLAC, OGG/Opus, MP4, or M4A directly onto the import bar.

DAW-style waveform editor with min/max sample rendering across all stems, shared normalization, zoom in/out/Fit, loop drag on the ruler, gold playhead overlay, and stem-aligned lanes.

Stem subset extraction. Click stem chips to choose which stems to keep. Clicking from "all selected" snaps to "only this one"; subsequent clicks add or remove.

"Original" backing track. When you pick a subset, a 7th lane contains the complement (full song minus selected stems), perfect for A/B reference without doubling.

Downloadable selected mix. A single mix.wav of just your selected stems, summed via ffmpeg amix.

Per-stem mixer with volume fader, mute, solo, and "monitor" (solo-only) per stem. State syncs between the preview mixer and the stems sidebar.

Live VU meters per stem. Post-gain RMS via Web Audio analysers with peak hold and slow falloff.

Song analysis including BPM (librosa beat tracker), key, scale, and confidence (Albrecht-Shanahan profiles), integrated LUFS (BS.1770), and sample peak in dBFS.

Cancellable jobs. Cancel mid-pipeline and the runner terminates the active subprocess immediately, deletes the partial job dir, and returns to ready.

Library panel with folder-based track organisation, drag-and-drop, search, and trash.

StemDeck is not trying to compete with commercial stem-separation products. It covers the core use case well and stops there. This table exists so you can make an informed choice rather than discover the gaps after the fact.

| StemDeck | Moises / LALAL.AI / similar
---|---|---
Price | Free, forever | Freemium; credits or subscription required for regular use
Hosting | Runs entirely on your machine | Cloud; audio must be uploaded to their servers
Account / login | None | Required
Internet required | Only for YouTube download and first model fetch (~170 MB, cached after) | Always; no offline use
Privacy | Audio never leaves your machine | Audio is uploaded and processed on third-party servers
Data retention | You control it; delete anytime | Governed by their privacy policy and retention period
Stem model | Demucs htdemucs_6s (open source, Meta AI) | Proprietary models, regularly updated, generally higher quality
Stem count | 6 (vocals, drums, bass, guitar, piano, other) | Up to 10 depending on service and plan
Input formats | YouTube URL, MP3, WAV, FLAC, OGG/Opus, MP4, M4A | MP3, WAV, FLAC, M4A, and more depending on service
Processing speed | Depends on your hardware; fast with a GPU, slow on CPU only | Fast regardless of your hardware (runs on their servers)
Batch processing | One job at a time | Yes, on paid plans
Mobile app | No | iOS and Android
Extra features | No (no pitch shift, chord detection, lyrics, click track, BPM tap) | Yes, varies by product
Polish | Functional, hobby-grade UI | Polished, production-grade apps
Source code | Open source, forkable, self-hostable | Closed source

If you need speed, quality, mobile access, or the extra musician tooling, the commercial products are worth the money. If you want stems for personal study, prefer to keep audio private, or just want something that runs locally with no strings attached, StemDeck is enough.

Pre-built installers and zips are attached to each GitHub Release.

macOS

DMG GPU Chip
StemDeck-macOS-arm64.dmg Apple Silicon (MPS) M1 and later
StemDeck-macOS-x64.dmg CPU only Intel

Open the DMG, drag StemDeck to Applications, and launch it. On first launch the setup screen downloads the Python runtime (~500 MB), FFmpeg, and the Demucs model (~170 MB). Subsequent launches skip setup and start in seconds. No Python or system dependencies required.

macOS may show a Gatekeeper prompt on first open — right-click the app and choose Open to bypass it.

Windows

Zip GPU Approx. size
StemDeck-Windows-x64.zip CPU only ~700 MB
StemDeck-Windows-x64.NVIDIA.zip NVIDIA CUDA ~1.6 GB

Extract the zip anywhere, run StemDeck.exe. FFmpeg, the Demucs model, config, and logs live in a data/ folder next to StemDeck.exe, not in AppData; move or copy the whole extracted folder anywhere and it keeps working. On first launch the app verifies the bundled Python runtime and downloads FFmpeg and the Demucs model (~170 MB) into that folder. Subsequent launches skip this and start in seconds. Everything is self-contained; no Python or system dependencies required. Your job/library data stays in its usual location (~/Documents/StemDeck by default) and is relocatable anytime from Settings → StemData location.

StemDeck is built on Python 3.12 managed via uv , with a FastAPI backend serving REST and Server-Sent Events. Stem separation uses Demucs (htdemucs_6s), Meta AI's open-source 6-stem neural network. The optional on-demand lead/backing vocal split runs the UVR-MDX-NET Karaoke 2 model via audio-separator , trained as part of the Ultimate Vocal Remover project by Anjok07. YouTube audio is fetched via yt-dlp ; transcoding and mixing use FFmpeg. BPM detection and key analysis run on librosa ; loudness measurement uses pyloudnorm (ITU-R BS.1770). The macOS and Windows desktop shells are Tauri v2 (Rust/WKWebView on macOS, Rust/WebView2 on Windows). The frontend is vanilla JS with the Web Audio API, no framework and no build step; waveforms are rendered on <canvas> using min/max sample rendering.

Thanks to the creators and maintainers of all the open-source libraries that make StemDeck possible.

Requires Rust, Node.js, and Python 3.12. Builds a self-contained .app that downloads its own runtime on first launch.

# First time only — add the cross-compilation targets
rustup target add aarch64-apple-darwin   # Apple Silicon
rustup target add x86_64-apple-darwin    # Intel

# Build Apple Silicon
ARCH=arm64 scripts/macos/make-runtime-pack.sh
ARCH=arm64 scripts/macos/make-app.sh
ARCH=arm64 scripts/macos/make-dmg.sh

# Build Intel (requires Rosetta 2 and an x86_64 Python)
ARCH=x64 scripts/macos/make-runtime-pack.sh
ARCH=x64 scripts/macos/make-app.sh
ARCH=x64 scripts/macos/make-dmg.sh

The .app lands at desktop/src-tauri/target/<target>/release/bundle/macos/StemDeck.app. The DMG lands at .build/macos-dist/StemDeck-macOS-<arch>.dmg.

To run a fresh build directly without the DMG:

open desktop/src-tauri/target/aarch64-apple-darwin/release/bundle/macos/StemDeck.app

If macOS blocks the app with a Gatekeeper prompt, run:

xattr -dr com.apple.quarantine desktop/src-tauri/target/aarch64-apple-darwin/release/bundle/macos/StemDeck.app

Note: To test a clean first-launch during development, you can wipe previous app data first: rm -rf ~/Library/Application\ Support/StemDeck. Don't do this on a real install.

Web Server (macOS / Linux / Windows with Python 3.12+)

Python 3.12 or newer, ffmpeg on your PATH, and uv. Around 170 MB of free disk for the Demucs model, which downloads automatically on first run.

git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck
./run.sh setup     # installs ffmpeg + uv, runs uv sync
./run.sh start

Open http://localhost:8000.

setup uses Homebrew on macOS and apt-get on Debian/Ubuntu. For other Linux distros, install ffmpeg and uv manually, then run uv sync followed by ./run.sh start.

Install prerequisites:

  • uv — winget install astral-sh.uv

  • ffmpeg — winget install Gyan.FFmpeg (or Chocolatey: choco install ffmpeg)

    git clone https://github.com/stemdeckapp/stemdeck stemdeck; cd stemdeck uv sync uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --timeout-graceful-shutdown 5

Open http://localhost:8000.

run.sh is macOS/Linux only. On Windows use the PowerShell commands above, or run inside WSL.

NVIDIA GPU (CUDA): install the CUDA-enabled torch build before starting:

uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
$env:STEMDECK_DEMUCS_DEVICE = "cuda"
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --timeout-graceful-shutdown 5

git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck
uv sync
uv run uvicorn app.main:app --reload --timeout-graceful-shutdown 5

--timeout-graceful-shutdown bounds how long uvicorn waits for open connections when you stop it. StemDeck keeps a long-lived SSE stream open for the import queue while a browser tab is on the app, so without it Ctrl-C waits for that stream instead of exiting.

docker compose -f build/docker-compose.yml up --build

Stems land in ./jobs/ on the host. Demucs weights are cached in a named volume so they don't re-download on rebuild. Note: no GPU passthrough on macOS Docker.

A prebuilt image is published to GHCR. Tags: edge (rolling, rebuilt on every merge to main), latest (newest stable release), and X.Y.Z (pinned to a release).

docker run -d --name stemdeck -p 8000:8000 \
  -v /path/to/jobs:/app/jobs \
  -v /path/to/cache:/cache \
  -e STEMDECK_PERSIST_LIBRARY=1 \
  ghcr.io/stemdeckapp/stemdeck:edge

On a Linux host with an NVIDIA GPU (driver + NVIDIA Container Toolkit installed), add --runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all and StemDeck auto-detects CUDA. The image already bundles CUDA-enabled torch, so no separate CUDA install is needed.

StemDeck is available in Unraid Community Applications: open Apps , search "StemDeck", and install. Map the two volumes to persistent appdata paths:

  • /app/jobs -> /mnt/user/appdata/stemdeck/jobs (library + stems)
  • /cache -> /mnt/user/appdata/stemdeck/cache (model weights)

The library is persistent by default (STEMDECK_PERSIST_LIBRARY=1), so tracks are never auto-deleted. For GPU acceleration, install the Nvidia Driver plugin, then set the container's Extra Parameters to --runtime=nvidia (the NVIDIA_VISIBLE_DEVICES and NVIDIA_DRIVER_CAPABILITIES variables are already in the template). CPU-only works with no extra configuration.

./run.sh setup      # one-shot: install ffmpeg + uv, then uv sync
./run.sh start      # boots uvicorn in the background
./run.sh stop       # graceful shutdown
./run.sh restart    # stop + start
./run.sh status     # is it running?
  1. On the import bar, click stem chips to choose which stems to extract (defaults to all 6).
  2. Paste a YouTube URL or drop an audio file (MP3, WAV, FLAC, OGG, MP4, M4A), then click Process.
  3. Wait through Uploading... / Downloading... → Analyzing... → Separating... → Mixing tracks....
  4. When done, the studio dashboard appears. If you picked a subset, the first lane is Original (full song minus your selection); the rest are your isolated stems.
  5. Mix: Play/Pause/Stop controls the master transport. M mutes a stem, S solos it (additive; multiple solos stay audible), Monitor solos only that stem and clears others. The volume fader moves 1:1 with drag; double-click resets to 0 dB; Shift+wheel gives coarse adjustment and plain wheel gives fine. The Reset , Mute , and Solo toolbar buttons act on all stems at once.
  6. Drag on the ruler to define a loop region; click Loop to enable. Use + / - / Fit or Ctrl/Cmd+wheel to zoom.
  7. Download Mix in the footer gives you a WAV of your selected stems summed together.

Keyboard shortcuts: Space play/pause · [ seek -5s · ] seek +5s · L loop · I loop in · O loop out

Variable Default Purpose
STEMDECK_DEMUCS_DEVICE auto Force Torch device: cuda, mps, or cpu.
STEMDECK_DEMUCS_MODEL htdemucs_6s Demucs model name.
STEMDECK_JOBS_DIR ./jobs Where job directories land.
STEMDECK_DATA_DIR (none) Portable mode root; sets all sub-dirs below to live inside it.
STEMDECK_CACHE_DIR <data>/cache Torch model cache directory.
STEMDECK_DOWNLOADS_DIR <data>/downloads yt-dlp download scratch space.
STEMDECK_MODELS_DIR <data>/models Demucs model weights directory.
STEMDECK_LOGS_DIR <data>/logs Log file output directory.
STEMDECK_FFMPEG_DIR (none) Directory containing a bundled ffmpeg binary.
STEMDECK_FFMPEG ffmpeg Path to the ffmpeg executable.
STEMDECK_FFPROBE ffprobe Path to the ffprobe executable.
STEMDECK_MAX_DURATION_SEC 1200 Reject audio longer than this (seconds).
STEMDECK_JOB_TTL_SECONDS 86400 How long to keep job dirs on disk.
STEMDECK_MAX_PENDING_JOBS 3 Max queued jobs before returning 503.
STEMDECK_TIMEOUT_FFMPEG 300 ffmpeg subprocess timeout (seconds).
STEMDECK_TIMEOUT_ANALYZE 120 Audio analysis timeout (seconds).
STEMDECK_TIMEOUT_DEMUCS_STALL 1800 Kill Demucs if no output for this many seconds.

run.sh also reads: HOST (default 127.0.0.1), PORT (default 8765), RELOAD=1 (enable uvicorn auto-reload for development), FOREGROUND=1 (run in foreground instead of backgrounding).

Method Path Purpose
GET /api/health Server health and version info
POST /api/jobs JSON {url, stems?} or multipart file + stems → {job_id}
GET /api/jobs List completed (library) jobs
GET /api/jobs/{id} Job state snapshot
GET /api/jobs/{id}/events SSE stream of job state
POST /api/jobs/{id}/cancel Terminate active subprocess and cancel job
PATCH /api/jobs/{id}/sections Save waveform section markers for a job
GET /api/jobs/{id}/stems/{name}.wav Stream a single stem WAV file
GET /api/jobs/{id}/stems/{name}.mp3 Transcode and stream a stem as MP3
GET /api/jobs/{id}/video.mp4 Mux the current mix with the source video (MP4 upload or YouTube) into an MP4
DELETE /api/jobs/{id} Remove job dir from disk (terminal jobs only)

ffmpeg: command not found: install ffmpeg and restart with ./run.sh restart.

WARNING: [youtube] No supported JavaScript runtime: install deno (brew install deno on macOS) and restart. Downloads still work without it but may pick suboptimal formats.

First separation is very slow: Demucs downloads htdemucs_6s weights (~170 MB) on first run; cached afterwards.

Demucs runs on CPU only: check the startup log for device=mps or device=cuda. If you see cpu, your torch install may be CPU-only.

Page reloaded mid-job: the job keeps running server-side. Wait for it to finish, then resubmit.

./run.sh: Permission denied: run chmod +x run.sh.

jobs/<job_id>/
└── stems/
    ├── vocals.wav      # the 6 Demucs stems (always present)
    ├── drums.wav
    ├── bass.wav
    ├── guitar.wav
    ├── piano.wav
    ├── other.wav
    ├── original.wav    # sum of un-selected stems (subset only)
    └── mix.wav         # ffmpeg amix of selected stems (subset only)

Job state is in-memory. Restart the server and the job list resets, but files persist on disk. Old dirs are swept automatically (TTL 24 h, configurable).

StemDeck is a local audio stem separation tool intended for personal study, research, and experimentation. It is not a downloading service. It does not store, cache, or redistribute any audio content. All processing runs on the user's own machine and no audio is transmitted anywhere.

YouTube URL support is provided via yt-dlp as a convenience. Automated downloading may violate YouTube's Terms of Service. You, the user, are solely responsible for ensuring you have the right to process any audio you submit, complying with the terms of service of any site you download from, and respecting the copyright of the material you work with.

You are also responsible for following the licenses of the underlying tools this project depends on (yt-dlp, Demucs, FFmpeg, PyTorch, and others listed in pyproject.toml).

The author(s) of StemDeck provide this software "as is", without warranty of any kind, and accept no responsibility or liability for how it is used.

Community

These are for development and testing. Release builds only recognize the variables marked "release".

Variable Platform Scope Description
STEMDECK_DATA_DIR all release Override the user data directory (default: platform-standard location)
STEMDECK_ROOT all release Override the app root directory (default: derived from executable path)
STEMDECK_PYTHON all debug builds only Override the Python executable path
STEMDECK_FFMPEG_URL Windows, macOS release Override the FFmpeg download URL
STEMDECK_FFPROBE_URL macOS release Override the ffprobe download URL

Issues, feature suggestions, and pull requests are welcome. See open issues for what's planned.