> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/stemdeckapp/stemdeck) · [上游 README](https://github.com/stemdeckapp/stemdeck/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
StemDeck **免费、本地音轨分离。无需账号。无需上传。无需订阅。**
CI GitHub Stars Total Downloads Latest Release License

加入社区

GitHub Discord Reddit Instagram X Website

拖入 MP3、WAV 或 FLAC 文件，或粘贴 YouTube URL，StemDeck 可将音频拆分为最多六个音轨（vocals 人声、drums 鼓、bass 贝斯、guitar 吉他、piano 钢琴、other 其他）。在 DAW 风格的多轨混音器中回放：静音、独奏、平衡电平、缩放波形、循环某段区域，并导出单个音轨或自定义混音。一切都在你自己的机器上本地运行。 > **这是什么？** StemDeck 是一款音轨分离工具，而不是下载器。它的主要工作是处理你已拥有的音频：将 MP3、WAV 或 FLAC 拖到导入栏即可开始。YouTube 支持是为你有权处理的内容提供的便利功能。StemDeck 不会存储、缓存或再分发任何下载内容。一切都在本地完成，没有任何数据离开你的机器。 > StemDeck 是 Moises、LALAL.AI 等云端音轨分离服务的免费开源替代方案：无需账号、无配额限制、无需上传、无需订阅。如果你想为个人学习获取音轨，并倾向于保持本地、免费，StemDeck 能满足你的需求。如果你需要更精致的体验、移动应用或更深入的音乐人工具，商业产品会更合适。 ![StemDeck screenshot](imgs/screenshot/stemdeck.png) ## 我们推荐 StemDeck 免费，且**不接受任何资金、赞助或资助**——既不来自用户，也不来自下方列出的任何人。我们分享这些创作者和艺术家，纯粹是为了向你介绍那些做着美好工作的优秀之人。去认识他们吧 ❤️ | 名称 | 他们在做什么 | 链接 | |---|---|---| | Dlima Guitars | 定制吉他与贝斯 | [@dlimaguitars](https://www.instagram.com/dlimaguitars) | | Lisbon Guitar Works | 吉他制作 | [dlimaguitars.com](https://dlimaguitars.com) | | Joao Gaspar | 制作人/电影配乐师，巡演/录音室乐手 | [@jay_glaspar](https://www.instagram.com/jay_glaspar) | | Kris Luthier | 制琴师与乐器维修，里斯本 | [@krisluthier](https://www.instagram.com/krisluthier) | | Thomann | 在线音乐商店 | [@thomann.music](https://www.instagram.com/thomann.music) | | Analog4Lyfe | 模拟音乐设备 | [@analog4lyfe](https://www.instagram.com/analog4lyfe) | | Empress Effects | 效果踏板 | [empresseffects.com](https://empresseffects.com) | --- ## 功能 通过 Demucs `htdemucs_6s` 实现**六轨分离**，自动检测最佳 Torch 设备（NVIDIA 上使用 CUDA，Apple Silicon 上使用 MPS，CPU 作为后备）。 **YouTube 与本地文件导入。** 粘贴 YouTube URL，或将 MP3、WAV 直接拖到导入栏。 **DAW 风格波形编辑器**，所有音轨均采用 min/max 采样渲染、共享归一化、放大/缩小/适应（Fit）、在标尺上拖拽循环、金色播放头叠加，以及音轨对齐的轨道。 **音轨子集提取。** 点击音轨标签选择要保留的音轨。从「全部选中」状态点击会切换为「仅此项」；后续点击可添加或移除。 **「原始」伴奏轨。** 选择子集时，第 7 条轨道包含补集（完整歌曲减去所选音轨），非常适合 A/B 参考对比，且无需重复加载。 **可下载的选定混音。** 一个 `mix.wav`，仅包含你选定的音轨，通过 ffmpeg amix 求和混音。 **逐轨混音器**，每条音轨配有音量推子、静音、独奏和「监听」（仅独奏）功能。预览混音器与音轨侧栏之间的状态同步。 **实时 VU 表**，每条音轨独立显示。通过后增益 RMS（Web Audio 分析器）实现，带峰值保持与缓慢回落。 **歌曲分析**，包括 BPM（librosa 节拍追踪器）、调性、音阶与置信度（Albrecht-Shanahan profiles）、集成 LUFS（BS.1770）以及 dBFS 采样峰值。 **可取消的任务。** 可在处理流程中途取消；运行器会立即终止活动子进程、删除部分任务目录，并返回就绪状态。 **曲库面板**，支持基于文件夹的曲目组织、拖放、搜索与回收站。 --- ## 如实对比 StemDeck 并非要与商业音轨分离产品竞争。它很好地覆盖了核心使用场景，仅此而已。本表旨在帮助你做出知情选择，而不是事后才发现差距。 | | StemDeck | Moises / LALAL.AI / 类似产品 | |---|---|---| | **价格** | 永久免费 | 免费增值；常规使用需积分或订阅 | | **托管方式** | 完全在你的机器上运行 | 云端；音频必须上传到其服务器 | | **账号 / 登录** | 无 | 必需 | | **是否需要互联网** | 仅用于 YouTube 下载和首次模型获取（约 170 MB，之后缓存） | 始终需要；无法离线使用 | | **隐私** | 音频永不离开你的机器 | 音频被上传至第三方服务器处理 | | **数据保留** | 由你控制；随时可删除 | 受其隐私政策与保留期限约束 | | **音轨模型** | Demucs `htdemucs_6s`（开源，Meta AI） | 专有模型，定期更新，通常质量更高 | | **音轨数量** | 6（vocals 人声、drums 鼓、bass 贝斯、guitar 吉他、piano 钢琴、other 其他） | 视服务与套餐而定，最多 10 轨 | | **输入格式** | YouTube URL、MP3、WAV | MP3、WAV、FLAC、M4A 等，视服务而定 | | **处理速度** | 取决于你的硬件；有 GPU 时快，仅 CPU 时慢 | 无论你的硬件如何都很快（在其服务器上运行） | | **批量处理** | 一次一个任务 | 有，付费套餐支持 | | **移动应用** | 无 | iOS 与 Android | | **额外功能** | 无（无移调、和弦检测、歌词、节拍器、BPM 敲击） | 有，因产品而异 | | **精致度** | 实用、爱好者级 UI | 精致、生产级应用 | | **源代码** | 开源，可 fork，可自托管 | 闭源 | 如果你需要速度、质量、移动端访问或额外的音乐人工具，商业产品物有所值。如果你只是想为个人学习获取音轨、希望保持音频私密，或只是想要一款无附加条件的本地运行工具，StemDeck 已足够。 --- ## 下载 每个 [GitHub Release](https://github.com/stemdeckapp/stemdeck/releases). 都附有预构建安装包和 zip 压缩包。 **macOS** | DMG | GPU | 芯片 | |---|---|---| | `StemDeck-macOS-arm64.dmg` | Apple Silicon (MPS) | M1 及更新机型 | | `StemDeck-macOS-x64.dmg` | 仅 CPU | Intel | 打开 DMG，将 StemDeck 拖入 Applications（应用程序）文件夹并启动。首次启动时，设置界面会下载 Python 运行时（约 500 MB）、FFmpeg 以及 Demucs 模型（约 170 MB）。之后再次启动会跳过设置，几秒内即可进入。无需安装 Python 或任何系统依赖。 macOS 首次打开时可能会弹出 Gatekeeper 提示——右键点击应用并选择“打开”即可绕过。 **Windows** | Zip | GPU | 大约大小 | |---|---|---| | `StemDeck-Windows-x64.zip` | 仅 CPU | ~700 MB | | `StemDeck-Windows-x64.NVIDIA.zip` | NVIDIA CUDA | ~1.6 GB | 将 zip 解压到任意位置，运行 `StemDeck.exe`。首次启动时，应用会校验内置的 Python 运行时，并下载 FFmpeg 与 Demucs 模型（约 170 MB）。之后再次启动会跳过此步骤，几秒内即可进入。所有内容自包含；无需 Python 或系统依赖。 --- ## 技术栈
Platform Powered by Demucs CI: GitHub Actions

StemDeck 基于 **[Python 3.12](https://python.org)**，通过 **[uv](https://github.com/astral-sh/uv)**, 管理，后端采用 **[FastAPI](https://fastapi.tiangolo.com)** 提供 REST 与 Server-Sent Events（服务器发送事件）。音轨分离使用 **[Demucs](https://github.com/facebookresearch/demucs)**（`htdemucs_6s`），即 Meta AI 的开源 6 轨神经网络。YouTube 音频通过 **[yt-dlp](https://github.com/yt-dlp/yt-dlp)**; 获取；转码与混音使用 **[FFmpeg](https://ffmpeg.org)**.；BPM 检测与调性分析基于 **[librosa](https://librosa.org)**;；响度测量使用 **[pyloudnorm](https://github.com/csteinmetz1/pyloudnorm)**（ITU-R BS.1770）。macOS 与 Windows 桌面外壳采用 **[Tauri v2](https://tauri.app)**（macOS 为 Rust/WKWebView，Windows 为 Rust/WebView2）。前端为原生 JS 配合 Web Audio API，无框架、无构建步骤；波形在 `` 上通过 min/max 采样渲染绘制。 *感谢所有开源库的创作者与维护者，正是他们让 StemDeck 成为可能。* --- ## 从源码构建 ### macOS 原生应用 需要 Rust、Node.js 和 Python 3.12。会构建一个自包含的 `.app`，首次启动时会自行下载运行时。 ```sh # 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 ``` `.app` 输出到 `desktop/src-tauri/target//release/bundle/macos/StemDeck.app`。DMG 输出到 `.build/macos-dist/StemDeck-macOS-.dmg`。 若要在不安装 DMG 的情况下直接运行全新构建： ```sh open desktop/src-tauri/target/aarch64-apple-darwin/release/bundle/macos/StemDeck.app ``` 若 macOS 因 Gatekeeper 提示阻止应用运行，请执行： ```sh xattr -dr com.apple.quarantine desktop/src-tauri/target/aarch64-apple-darwin/release/bundle/macos/StemDeck.app ``` > **注意：** 开发过程中若要测试干净的首次启动，可先清除先前的应用数据：`rm -rf ~/Library/Application\ Support/StemDeck`。请勿在正式安装环境中执行此操作。 --- ### Web 服务器（macOS / Linux / 已安装 Python 3.12+ 的 Windows） #### 前置条件 Python 3.12 或更高版本，PATH 中可访问 `ffmpeg`，以及 [uv](https://github.com/astral-sh/uv).。Demucs 模型约需 170 MB 磁盘空间，首次运行时会自动下载。 #### macOS / Linux（一键脚本） ```sh git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck ./run.sh setup # installs ffmpeg + uv, runs uv sync ./run.sh start ``` 打开 。 `setup` 在 macOS 上使用 Homebrew，在 Debian/Ubuntu 上使用 `apt-get`。对于其他 Linux 发行版，请手动安装 `ffmpeg` 与 [uv](https://github.com/astral-sh/uv)，然后依次运行 `uv sync` 和 `./run.sh start`。 #### Windows（PowerShell） 安装前置依赖： - [uv](https://docs.astral.sh/uv/getting-started/installation/) — `winget install astral-sh.uv` - [ffmpeg](https://ffmpeg.org/download.html) — `winget install Gyan.FFmpeg`（或通过 Chocolatey：`choco install ffmpeg`） ```powershell 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 ``` 打开 。 > `run.sh` 仅适用于 macOS/Linux。在 Windows 上请使用上述 PowerShell 命令，或在 WSL 中运行。 **NVIDIA GPU（CUDA）：** 启动前先安装支持 CUDA 的 torch 构建： ```powershell 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 ``` --- #### 手动安装（任意平台） ```sh git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck uv sync uv run uvicorn app.main:app --reload ``` #### Docker ```sh docker compose -f build/docker-compose.yml up --build ``` 分离音轨会写入宿主机的 `./jobs/`。Demucs 权重缓存在命名卷中，重建时不会重新下载。注意：macOS Docker 不支持 GPU 透传。 预构建镜像发布在 GHCR。标签：`edge`（滚动更新，每次合并到 main 时重建）、`latest`（最新稳定版发布）以及 `X.Y.Z`（固定到某一发布版本）。 ```sh 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 ``` 在已安装 NVIDIA 驱动与 NVIDIA Container Toolkit 的 Linux 宿主机上，添加 `--runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all`，StemDeck 会自动检测 CUDA。镜像已内置支持 CUDA 的 torch，无需单独安装 CUDA。 #### Unraid StemDeck 可在 Unraid Community Applications 中获取：打开 **Apps**，搜索 "StemDeck" 并安装。将两个卷映射到持久化 appdata 路径： - `/app/jobs` -> `/mnt/user/appdata/stemdeck/jobs`（曲库 + 音轨） - `/cache` -> `/mnt/user/appdata/stemdeck/cache`（模型权重） 曲库默认持久化（`STEMDECK_PERSIST_LIBRARY=1`），因此曲目不会被自动删除。若要 GPU 加速，请安装 **Nvidia Driver** 插件，然后将容器的 Extra Parameters 设置为 `--runtime=nvidia`（模板中已包含 `NVIDIA_VISIBLE_DEVICES` 与 `NVIDIA_DRIVER_CAPABILITIES` 变量）。仅 CPU 模式无需额外配置。 #### `run.sh` 控制脚本 ```sh ./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. 在导入栏中，点击音轨芯片以选择要提取的音轨（默认全部 6 轨）。 2. 粘贴 YouTube URL **或** 拖放 MP3/WAV 文件，然后点击 **Process**。 3. 依次等待 `Uploading...` / `Downloading...` → `Analyzing...` → `Separating...` → `Mixing tracks...`。 4. 完成后会显示工作室仪表盘。若你选择了子集，第一条轨道为 **Original**（完整歌曲减去你所选音轨）；其余为你的独立音轨。 5. 混音：**Play/Pause/Stop** 控制主传输。按 **M** 静音某轨，按 **S** 独奏（可叠加；多个独奏同时可听）。**Monitor** 仅独奏该轨并清除其他独奏。音量推子随拖拽 1:1 移动；双击重置为 0 dB；`Shift+wheel` 用于粗调，普通滚轮用于微调。**Reset**、**Mute** 与 **Solo** 工具栏按钮会同时作用于所有音轨。 6. 在标尺上拖拽以定义循环区域；点击 `Loop` 启用。使用 `+` / `-` / `Fit` 或 `Ctrl/Cmd+wheel` 缩放。 7. 页脚的 **Download Mix** 可下载所选音轨混合后的 WAV 文件。 **键盘快捷键：** `Space` 播放/暂停 · `[` 后退 5 秒 · `]` 前进 5 秒 · `L` 循环 · `I` 循环入点 · `O` 循环出点 --- ## 配置 | 变量 | 默认值 | 说明 | |---|---|---| | `STEMDECK_DEMUCS_DEVICE` | auto | 强制指定 Torch 设备：`cuda`、`mps` 或 `cpu`。 | | `STEMDECK_DEMUCS_MODEL` | `htdemucs_6s` | Demucs 模型名称。 | | `STEMDECK_JOBS_DIR` | `./jobs` | 任务目录的存放位置。 | | `STEMDECK_DATA_DIR` | (none) | 便携模式根目录；其下所有子目录均置于该目录内。 | | `STEMDECK_CACHE_DIR` | `/cache` | Torch 模型缓存目录。 | | `STEMDECK_DOWNLOADS_DIR` | `/downloads` | yt-dlp 下载临时目录。 | | `STEMDECK_MODELS_DIR` | `/models` | Demucs 模型权重目录。 | | `STEMDECK_LOGS_DIR` | `/logs` | 日志文件输出目录。 | | `STEMDECK_FFMPEG_DIR` | (none) | 包含捆绑 ffmpeg 二进制文件的目录。 | | `STEMDECK_FFMPEG` | `ffmpeg` | ffmpeg 可执行文件路径。 | | `STEMDECK_FFPROBE` | `ffprobe` | ffprobe 可执行文件路径。 | | `STEMDECK_MAX_DURATION_SEC` | `1200` | 拒绝超过此时长（秒）的音频。 | | `STEMDECK_JOB_TTL_SECONDS` | `86400` | 任务目录在磁盘上的保留时长。 | | `STEMDECK_MAX_PENDING_JOBS` | `3` | 排队任务数上限，超出后返回 503。 | | `STEMDECK_TIMEOUT_FFMPEG` | `300` | ffmpeg 子进程超时（秒）。 | | `STEMDECK_TIMEOUT_ANALYZE` | `120` | 音频分析超时（秒）。 | | `STEMDECK_TIMEOUT_DEMUCS_STALL` | `1800` | 若在此秒数内无输出则终止 Demucs。 | `run.sh` 还会读取：`HOST`（默认 `127.0.0.1`）、`PORT`（默认 `8765`）、`RELOAD=1`（开发时启用 uvicorn 自动重载）、`FOREGROUND=1`（前台运行而非后台运行）。 --- ## API | 方法 | 路径 | 说明 | |---|---|---| | GET | `/api/health` | 服务器健康状态与版本信息 | | POST | `/api/jobs` | JSON `{url, stems?}` 或 multipart `file + stems` → `{job_id}` | | GET | `/api/jobs` | 列出已完成（库中）任务 | | GET | `/api/jobs/{id}` | 任务状态快照 | | GET | `/api/jobs/{id}/events` | 任务状态的 SSE 流 | | POST | `/api/jobs/{id}/cancel` | 终止活动子进程并取消任务 | | PATCH | `/api/jobs/{id}/sections` | 保存任务的波形区段标记 | | GET | `/api/jobs/{id}/stems/{name}.wav` | 流式传输单个 stem 的 WAV 文件 | | GET | `/api/jobs/{id}/stems/{name}.mp3` | 转码并以 MP3 流式传输 stem | | GET | `/api/jobs/{id}/video.mp4` | 将当前混音与源视频（MP4 上传或 YouTube）封装为 MP4 | | DELETE | `/api/jobs/{id}` | 从磁盘删除任务目录（仅限已结束任务） | --- ## 故障排除 **`ffmpeg: command not found`：** 安装 ffmpeg 并使用 `./run.sh restart` 重启。 **`WARNING: [youtube] No supported JavaScript runtime`：** 安装 deno（macOS 上为 `brew install deno`）并重启。未安装时下载仍可用，但可能选择次优格式。 **首次分离非常慢：** Demucs 首次运行时会下载 `htdemucs_6s` 权重（约 170 MB）；之后会缓存。 **Demucs 仅在 CPU 上运行：** 检查启动日志中的 `device=mps` 或 `device=cuda`。若看到 `cpu`，你的 torch 安装可能仅为 CPU 版。 **任务进行中页面被刷新：** 任务会在服务端继续运行。等待其完成后再重新提交。 **`./run.sh: Permission denied`：** 运行 `chmod +x run.sh`。 --- ## 磁盘布局 ``` jobs// └── 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) ``` 任务状态保存在内存中。重启服务器后任务列表会重置，但文件仍保留在磁盘上。旧目录会自动清理（TTL 24 小时，可配置）。 --- ## 免责声明 StemDeck 是一款本地音频 stem 分离工具，供个人学习、研究与实验使用。它不是下载服务，不会存储、缓存或再分发任何音频内容。所有处理均在用户本机运行，不会将音频传输到任何其他地方。 YouTube URL 支持通过 [yt-dlp](https://github.com/yt-dlp/yt-dlp) 提供，仅为便利。自动下载可能违反 YouTube 的服务条款。你（用户）须自行确保对所提交音频拥有处理权利，遵守所下载网站的各项服务条款，并尊重所处理材料的版权。 你还须遵守本项目所依赖底层工具的许可证（yt-dlp、Demucs、FFmpeg、PyTorch 及 `pyproject.toml` 中列出的其他工具）。 StemDeck 作者按“原样”提供本软件，不作任何形式的担保，且不对其使用方式承担任何责任。 --- ## 社区 | 平台 | 链接 | |---|---| | GitHub | [stemdeckapp/stemdeck](https://github.com/stemdeckapp/stemdeck) | | Discord | [discord.gg/2MVsWqaPRe](https://discord.gg/2MVsWqaPRe) | | Reddit | [r/StemDeckApp](https://www.reddit.com/r/StemDeckApp/) | | Instagram | [@stemdeck](https://www.instagram.com/stemdeck) | | X | [@StemDeckApp](https://x.com/StemDeckApp) | | Website | [stemdeck.app](https://stemdeck.app) *(coming soon)* | --- ## 环境变量 以下变量用于开发与测试。正式版构建仅识别标注为“release”的变量。 | 变量 | 平台 | 范围 | 说明 | |---|---|---|---| | `STEMDECK_DATA_DIR` | all | release | 覆盖用户数据目录（默认：平台标准位置） | | `STEMDECK_ROOT` | all | release | 覆盖应用根目录（默认：由可执行文件路径推导） | | `STEMDECK_PYTHON` | all | **debug builds only** | 覆盖 Python 可执行文件路径 | | `STEMDECK_FFMPEG_URL` | Windows, macOS | release | 覆盖 FFmpeg 下载 URL | | `STEMDECK_FFPROBE_URL` | macOS | release | 覆盖 ffprobe 下载 URL | --- ## 贡献 欢迎提交 Issue、功能建议与 Pull Request。可查看开放的 Issue 了解计划中的内容。 --- ## Star History Star History Chart