StemDeck 本地音频分轨工具详细部署教程

StemDeck 是一款免费、开源的本地音频分轨工具，专为音乐人、制作人和爱好者设计。它能将歌曲分离为独立的音轨（如人声、鼓、贝斯、吉他、钢琴等），所有处理都在您自己的电脑上完成，无需上传、无需账户、无需订阅。本教程将指导您通过多种方式部署和使用 StemDeck。

📋 目录

  1. StemDeck 是什么
  2. 核心功能
  3. 安装前准备
  4. 下载与安装
  5. 从源码构建
  6. Docker 部署
  7. 首次使用与配置
  8. 使用指南
  9. 更新与卸载
  10. 常见问题排查

StemDeck 是什么

StemDeck 是一个基于 Demucs（Meta AI 开源的分轨模型）的桌面和 Web 应用，它将复杂的音频处理封装在简洁的界面后，让用户能轻松地将歌曲分离为多个独立音轨。

核心价值：

  • 完全本地处理：音频文件不上传任何服务器，保护隐私。
  • 免费且开源：无任何隐藏费用，代码公开可审计。
  • 易于使用：拖拽文件或粘贴 YouTube 链接即可开始，界面直观。
  • 多平台支持：提供 macOS、Windows 原生应用，以及可通过 Docker 部署的 Web 服务。

核心功能

  • 6 轨分离：使用 Demucs htdemucs_6s 模型，分离为 vocals（人声）、drums（鼓）、bass（贝斯）、guitar（吉他）、piano（钢琴）、other（其他）。
  • 多种输入格式：支持 MP3、WAV、FLAC、OGG/Opus、MP4、M4A 文件，以及 YouTube URL。
  • DAW 风格混音器：可在界面中单独调节各音轨音量、静音、独奏，并实时查看 VU 表。
  • 波形编辑器：提供波形显示、缩放、循环播放功能。
  • 歌曲分析：自动检测 BPM（节拍）、调性、响度（LUFS）。
  • 导出：可导出分离后的单个音轨或自定义混音文件（WAV 格式）。
  • 任务管理：支持取消正在进行的分离任务。

安装前准备

最终用户（使用预构建安装包）

  • macOS：需要 macOS 10.15+（Catalina）或更新版本。
  • Windows：需要 Windows 10 或更新版本（64位）。
  • 网络：首次启动时需要下载 Python 运行时和 AI 模型（约 670MB），之后可离线使用。

开发者（从源码构建）

  • Python 3.12 或更新版本。
  • uv：推荐的 Python 包管理器。
  • FFmpeg：需在系统 PATH 中。
  • Git：用于克隆仓库。
  • Rust 和 Node.js（仅用于构建 macOS/Windows 原生应用）。

下载与安装

1. 获取安装包

从项目的 GitHub Releases 页面 下载对应您操作系统的安装包。

平台 文件名 说明
macOS (Apple Silicon) StemDeck-macOS-arm64.dmg 支持 MPS (Metal) 加速
macOS (Intel) StemDeck-macOS-x64.dmg CPU 运行
Windows (通用) StemDeck-Windows-x64.zip CPU 运行，约 700 MB
Windows (NVIDIA GPU) StemDeck-Windows-x64.NVIDIA.zip 支持 CUDA 加速，约 1.6 GB

2. 安装与首次启动

macOS：

  1. 双击打开 .dmg 文件。
  2. 将 StemDeck.app 拖入 Applications 文件夹。
  3. 首次启动时，系统可能会提示“无法验证开发者”。右键点击应用，选择“打开”，然后在弹出的对话框中确认即可。
  4. 应用会自动下载所需的 Python 运行时和 AI 模型，请耐心等待。

Windows：

  1. 解压下载的 .zip 文件到您选择的文件夹。
  2. 双击 StemDeck.exe 运行。
  3. 应用会在 StemDeck.exe 同级的 data/ 文件夹中下载依赖和模型。

从源码构建

如果您想运行 Web 版本的 StemDeck 或进行开发，可以按以下步骤操作。

1. 克隆仓库

1
2
git clone https://github.com/stemdeckapp/stemdeck.git
cd stemdeck

2. 安装依赖

macOS / Linux：

1
./run.sh setup

此脚本会自动安装 ffmpeg（通过 Homebrew/apt）和 uv，并同步 Python 依赖。

Windows (PowerShell)：

1
2
3
4
5
6
# 先安装 uv 和 ffmpeg (使用 winget)
winget install astral-sh.uv
winget install Gyan.FFmpeg

# 同步 Python 依赖
uv sync

3. 启动 Web 服务

macOS / Linux：

1
./run.sh start

然后在浏览器中打开 http://localhost:8000。

Windows (PowerShell)：

1
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000 --timeout-graceful-shutdown 5

启用 NVIDIA GPU 加速 (CUDA)：

1
2
3
4
5
# 安装 CUDA 版 PyTorch（示例为 CUDA 12.4）
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
export STEMDECK_DEMUCS_DEVICE="cuda"   # Linux/macOS
# 或 $env:STEMDECK_DEMUCS_DEVICE = "cuda" (Windows PowerShell)
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000

Docker 部署

StemDeck 提供了 Docker 镜像，适合服务器或 Unraid 等 NAS 环境部署。

1. 使用 Docker Compose

1
docker compose -f build/docker-compose.yml up --build
  • 分离后的文件位于主机的 ./jobs/ 目录。
  • Demucs 模型缓存在 Docker 卷中。

2. 直接运行官方镜像

1
2
3
4
5
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
  • edge 标签为滚动更新版，latest 为最新稳定版，也可使用具体版本号（如 X.Y.Z）。
  • 如需 NVIDIA GPU 加速，需添加 --runtime=nvidia 参数并确保已安装 NVIDIA Container Toolkit。

首次使用与配置

  1. 启动应用：通过桌面图标或启动脚本打开。
  2. 设置工作目录 (可选)：在设置界面可以更改 Stem 文件的默认保存位置。
  3. 开始分离：
    • 将音频文件（MP3, WAV, FLAC等）拖拽到应用的导入区域，或点击“选择文件”。
    • 或者，在输入框中粘贴一个 YouTube 视频链接。
  4. 选择要提取的音轨：默认会提取全部 6 轨。您也可以点击“音轨选择”标签，只勾选需要的部分（如仅人声和吉他）。
  5. 点击“处理”：应用会依次进行下载（如果是 YouTube）、分析和分离。首次运行因需要下载模型，时间会稍长。处理进度会实时显示。

使用指南

混音器界面

处理完成后，您会进入一个类似数字音频工作站（DAW）的混音界面。

  • 播放控制：使用底部的播放/暂停、停止按钮。
  • 音轨控制：每个音轨都有音量推子、静音（M）、独奏（S）和监听按钮。
  • 波形视图：您可以拖拽鼠标选择波形区域进行循环播放，或使用缩放按钮查看细节。
  • 导出：点击“下载混音”按钮，可以导出您当前选择的音轨组合成一个 WAV 文件。也可以单独下载每个分离的音轨。

键盘快捷键

  • Space：播放/暂停
  • [ / ]：快退/快进 5 秒
  • L：切换循环
  • I / O：设置循环起点/终点

更新与卸载

更新

  • 桌面应用：需要手动下载并安装最新版本的安装包。应用内暂不支持自动更新。
  • Web/源码版本：
    1. 进入项目目录：cd stemdeck
    2. 拉取最新代码：git pull
    3. 重新同步依赖：./run.sh setup（macOS/Linux）或 uv sync（Windows）。
    4. 重启服务：./run.sh restart。

卸载

  • macOS：将 StemDeck.app 拖入废纸篓即可。应用数据和配置通常位于 ~/Library/Application Support/StemDeck/。
  • Windows：删除整个解压后的文件夹。应用数据和配置位于该文件夹下的 data/ 目录中。

常见问题排查

问题：首次启动提示下载失败或模型下载慢。

  • 解决：模型文件较大（约 170MB），请确保网络稳定。如果一直失败，可以尝试从 Hugging Face 或其他镜像手动下载 htdemucs_6s 模型，并将其放置在缓存目录中（具体路径可参考应用日志）。

问题：分离速度非常慢或提示 CPU 运行。

  • 解决：
    • 检查启动日志，确认 device 是否为 cuda（NVIDIA GPU）或 mps（Apple Silicon）。
    • 如果您有 NVIDIA 显卡，请确保安装了 CUDA 版的 PyTorch（源码部署时需手动安装，桌面应用已内置）。
    • 大型文件处理本身较耗时，请耐心等待。

问题：ffmpeg 相关的错误。

  • 解决：请确保 ffmpeg 已正确安装并已添加到系统 PATH 环境变量中。桌面版应用已内置 ffmpeg，一般不会出现此问题。

通过以上步骤，您应该能成功部署并开始使用 StemDeck。它是一款功能强大且注重隐私的本地分轨工具，适合音乐学习、混音练习和创意音频制作。如需获取更多帮助或参与讨论，可以加入其 Discord 社区或 Reddit 论坛。