stemdeckapp--stemdeck/README.md at main

wehub/stemdeckapp--stemdeck

Fork 0

Files

T

wehub-resource-sync 572aca14f1

CI / deps-audit (push) Waiting to run

Details

CI / trivy (push) Waiting to run

Details

CI / lint (push) Waiting to run

Details

CI / test (push) Waiting to run

Details

CI / js-syntax (push) Waiting to run

Details

CI / sast-bandit (push) Waiting to run

Details

Docker Publish / build-and-push (push) Waiting to run

Details

docs: make Chinese README the default

2026-07-13 10:58:55 +00:00

23 KiB

Raw Permalink Blame History

Note

本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
English · 原始项目 · 上游 README
原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

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

_加入社区

拖入 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 免费，且不接受任何资金、赞助或资助——既不来自用户，也不来自下方列出的任何人。我们分享这些创作者和艺术家，纯粹是为了向你介绍那些做着美好工作的优秀之人。去认识他们吧 ❤️

名称	他们在做什么	链接
Dlima Guitars	定制吉他与贝斯	@dlimaguitars
Lisbon Guitar Works	吉他制作	dlimaguitars.com
Joao Gaspar	制作人/电影配乐师，巡演/录音室乐手	@jay_glaspar
Kris Luthier	制琴师与乐器维修，里斯本	@krisluthier
Thomann	在线音乐商店	@thomann.music
Analog4Lyfe	模拟音乐设备	@analog4lyfe
Empress Effects	效果踏板	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. 都附有预构建安装包和 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 或系统依赖。

技术栈

StemDeck 基于 Python 3.12，通过 uv, 管理，后端采用 FastAPI 提供 REST 与 Server-Sent Events（服务器发送事件）。音轨分离使用 Demucs（htdemucs_6s），即 Meta AI 的开源 6 轨神经网络。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> 上通过 min/max 采样渲染绘制。

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

从源码构建

macOS 原生应用

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

# 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/<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 服务器（macOS / Linux / 已安装 Python 3.12+ 的 Windows）

前置条件

Python 3.12 或更高版本，PATH 中可访问 ffmpeg，以及 uv.。Demucs 模型约需 170 MB 磁盘空间，首次运行时会自动下载。

macOS / Linux（一键脚本）

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

打开 http://localhost:8000。

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

Windows（PowerShell）

安装前置依赖：

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

打开 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

手动安装（任意平台）

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

Docker

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

分离音轨会写入宿主机的 ./jobs/。Demucs 权重缓存在命名卷中，重建时不会重新下载。注意：macOS Docker 不支持 GPU 透传。

预构建镜像发布在 GHCR。标签：edge（滚动更新，每次合并到 main 时重建）、latest（最新稳定版发布）以及 X.Y.Z（固定到某一发布版本）。

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` 控制脚本

./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?

使用方法

在导入栏中，点击音轨芯片以选择要提取的音轨（默认全部 6 轨）。
粘贴 YouTube URL 或拖放 MP3/WAV 文件，然后点击 Process。
依次等待 Uploading... / Downloading... → Analyzing... → Separating... → Mixing tracks...。
完成后会显示工作室仪表盘。若你选择了子集，第一条轨道为 Original（完整歌曲减去你所选音轨）；其余为你的独立音轨。
混音：Play/Pause/Stop 控制主传输。按 M 静音某轨，按 S 独奏（可叠加；多个独奏同时可听）。Monitor 仅独奏该轨并清除其他独奏。音量推子随拖拽 1:1 移动；双击重置为 0 dB；Shift+wheel 用于粗调，普通滚轮用于微调。Reset、Mute 与 Solo 工具栏按钮会同时作用于所有音轨。
在标尺上拖拽以定义循环区域；点击 Loop 启用。使用 + / - / Fit 或 Ctrl/Cmd+wheel 缩放。
页脚的 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`	`<data>/cache`	Torch 模型缓存目录。
`STEMDECK_DOWNLOADS_DIR`	`<data>/downloads`	yt-dlp 下载临时目录。
`STEMDECK_MODELS_DIR`	`<data>/models`	Demucs 模型权重目录。
`STEMDECK_LOGS_DIR`	`<data>/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/<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)

任务状态保存在内存中。重启服务器后任务列表会重置，但文件仍保留在磁盘上。旧目录会自动清理（TTL 24 小时，可配置）。

免责声明

StemDeck 是一款本地音频 stem 分离工具，供个人学习、研究与实验使用。它不是下载服务，不会存储、缓存或再分发任何音频内容。所有处理均在用户本机运行，不会将音频传输到任何其他地方。

YouTube URL 支持通过 yt-dlp 提供，仅为便利。自动下载可能违反 YouTube 的服务条款。你（用户）须自行确保对所提交音频拥有处理权利，遵守所下载网站的各项服务条款，并尊重所处理材料的版权。

你还须遵守本项目所依赖底层工具的许可证（yt-dlp、Demucs、FFmpeg、PyTorch 及 pyproject.toml 中列出的其他工具）。

StemDeck 作者按“原样”提供本软件，不作任何形式的担保，且不对其使用方式承担任何责任。

社区

平台	链接
GitHub	stemdeckapp/stemdeck
Discord	discord.gg/2MVsWqaPRe
Reddit	r/StemDeckApp
Instagram	@stemdeck
X	@StemDeckApp
Website	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 了解计划中的内容。

23 KiB Raw Permalink Blame History Unescape Escape

我们推荐

功能

如实对比

下载

技术栈

从源码构建

macOS 原生应用

Web 服务器（macOS / Linux / 已安装 Python 3.12+ 的 Windows）

前置条件

macOS / Linux（一键脚本）

Windows（PowerShell）

手动安装（任意平台）

Docker

Unraid

run.sh 控制脚本

使用方法

配置

API

故障排除

磁盘布局

免责声明

社区

环境变量

贡献

Star History

23 KiB

Raw Permalink Blame History

`run.sh` 控制脚本