wehub/stemdeckapp--stemdeck
1
0
Fork 0
Code Issues Pull Requests Actions Deployments Models Agent Notes Packages Projects Releases Wiki Activity

docs: make Chinese README the default
CI / deps-audit (push) Has been cancelled
Details
CI / lint (push) Has been cancelled
Details
CI / test (push) Has been cancelled
Details
CI / js-syntax (push) Has been cancelled
Details
CI / sast-bandit (push) Has been cancelled
Details
CI / trivy (push) Has been cancelled
Details
Docker Publish / build-and-push (push) Has been cancelled
Details

Browse Source
This commit is contained in:
wehub-resource-sync
2026-07-13 10:58:55 +00:00
parent a2a4befd18
commit 572aca14f1
1 changed files with 160 additions and 154 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+160 -154
View File
@@ -1,8 +1,14 @@
<!-- WEHUB_ZH_README -->
> [!NOTE]
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
> [English](./README.en.md) · [原始项目](https://github.com/stemdeckapp/stemdeck) · [上游 README](https://github.com/stemdeckapp/stemdeck/blob/HEAD/README.md)
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
<div align="center">
<img src="imgs/stemdeck-svg-assets/stemdeck-logo-stacked.svg" alt="StemDeck" width="515" />
**Free, local stem separation. No account. No upload. No subscription.**
**免费、本地音轨分离。无需账号。无需上传。无需订阅。**
<div align="center">
<a href="https://github.com/stemdeckapp/stemdeck/actions/workflows/ci.yml"><img src="https://github.com/stemdeckapp/stemdeck/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
@@ -14,7 +20,7 @@
<br>
<p align="center"><sub>JOIN THE COMMUNITY</sub></p>
<p align="center"><sub>加入社区</sub></p>
<div align="center">
<a href="https://github.com/stemdeckapp/stemdeck"><img src="https://img.shields.io/badge/GitHub-stemdeckapp-181717?style=flat-square&logo=github&logoColor=white" alt="GitHub"></a>
<a href="https://discord.gg/2MVsWqaPRe"><img src="https://img.shields.io/badge/Discord-Join-5865F2?style=flat-square&logo=discord&logoColor=white" alt="Discord"></a>
@@ -28,110 +34,110 @@
<br>
Drop in an MP3, WAV, or FLAC 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.
拖入 MP3、WAV 或 FLAC 文件，或粘贴 YouTube URL，StemDeck 可将音频拆分为最多六个音轨（vocals 人声、drums 鼓、bass 贝斯、guitar 吉他、piano 钢琴、other 其他）。在 DAW 风格的多轨混音器中回放：静音、独奏、平衡电平、缩放波形、循环某段区域，并导出单个音轨或自定义混音。一切都在你自己的机器上本地运行。
> **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, or FLAC 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 是一款音轨分离工具，而不是下载器。它的主要工作是处理你已拥有的音频：将 MP3、WAV 或 FLAC 拖到导入栏即可开始。YouTube 支持是为你有权处理的内容提供的便利功能。StemDeck 不会存储、缓存或再分发任何下载内容。一切都在本地完成，没有任何数据离开你的机器。
> 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 是 Moises、LALAL.AI 等云端音轨分离服务的免费开源替代方案：无需账号、无配额限制、无需上传、无需订阅。如果你想为个人学习获取音轨，并倾向于保持本地、免费，StemDeck 能满足你的需求。如果你需要更精致的体验、移动应用或更深入的音乐人工具，商业产品会更合适。
![StemDeck screenshot](imgs/screenshot/stemdeck.png)
## We Recommend
## 我们推荐
StemDeck is free and **does not accept any money, sponsorship, or funding** - not from users, not from anyone listed below. We share these makers and artists purely for the joy of pointing you toward wonderful people doing beautiful work. Go meet them ❤️
StemDeck 免费，且**不接受任何资金、赞助或资助**——既不来自用户，也不来自下方列出的任何人。我们分享这些创作者和艺术家，纯粹是为了向你介绍那些做着美好工作的优秀之人。去认识他们吧 ❤️
| Name | What they do | Link |
| 名称 | 他们在做什么 | 链接 |
|---|---|---|
| Dlima Guitars | Custom guitars and basses | [@dlimaguitars](https://www.instagram.com/dlimaguitars) |
| Lisbon Guitar Works | Guitar building | [dlimaguitars.com](https://dlimaguitars.com) |
| Joao Gaspar | Producer/Film Scorer, Touring/Session Musician | [@jay_glaspar](https://www.instagram.com/jay_glaspar) |
| Kris Luthier | Luthier and Musical Instrument Repair, Lisboa | [@krisluthier](https://www.instagram.com/krisluthier) |
| Thomann | Online Music Store | [@thomann.music](https://www.instagram.com/thomann.music) |
| Analog4Lyfe | Analog music gear | [@analog4lyfe](https://www.instagram.com/analog4lyfe) |
| Empress Effects | Effects pedals | [empresseffects.com](https://empresseffects.com) |
| 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) |
---
## Features
## 功能
**6-stem separation** via Demucs `htdemucs_6s`, with auto-detection of the best Torch device (CUDA on NVIDIA, MPS on Apple Silicon, CPU fallback).
通过 Demucs `htdemucs_6s` 实现**六轨分离**，自动检测最佳 Torch 设备（NVIDIA 上使用 CUDA，Apple Silicon 上使用 MPS，CPU 作为后备）。
**YouTube and local file import.** Paste a YouTube URL or drop an MP3 or WAV directly onto the import bar.
**YouTube 与本地文件导入。** 粘贴 YouTube URL，或将 MP3、WAV 直接拖到导入栏。
**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.
**DAW 风格波形编辑器**，所有音轨均采用 min/max 采样渲染、共享归一化、放大/缩小/适应（Fit）、在标尺上拖拽循环、金色播放头叠加，以及音轨对齐的轨道。
**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.
**「原始」伴奏轨。** 选择子集时，第 7 条轨道包含补集（完整歌曲减去所选音轨），非常适合 A/B 参考对比，且无需重复加载。
**Downloadable selected mix.** A single `mix.wav` of just your selected stems, summed via ffmpeg amix.
**可下载的选定混音。** 一个 `mix.wav`，仅包含你选定的音轨，通过 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.
**实时 VU 表**，每条音轨独立显示。通过后增益 RMS（Web Audio 分析器）实现，带峰值保持与缓慢回落。
**Song analysis** including BPM (librosa beat tracker), key, scale, and confidence (Albrecht-Shanahan profiles), integrated LUFS (BS.1770), and sample peak in dBFS.
**歌曲分析**，包括 BPM（librosa 节拍追踪器）、调性、音阶与置信度（Albrecht-Shanahan profiles）、集成 LUFS（BS.1770）以及 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.
**曲库面板**，支持基于文件夹的曲目组织、拖放、搜索与回收站。
---
## Honest Comparison
## 如实对比
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 并非要与商业音轨分离产品竞争。它很好地覆盖了核心使用场景，仅此而已。本表旨在帮助你做出知情选择，而不是事后才发现差距。
| | StemDeck | Moises / LALAL.AI / similar |
| | StemDeck | Moises / LALAL.AI / 类似产品 |
|---|---|---|
| **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 | 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 |
| **价格** | 永久免费 | 免费增值；常规使用需积分或订阅 |
| **托管方式** | 完全在你的机器上运行 | 云端；音频必须上传到其服务器 |
| **账号 / 登录** | 无 | 必需 |
| **是否需要互联网** | 仅用于 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，可自托管 | 闭源 |
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.
如果你需要速度、质量、移动端访问或额外的音乐人工具，商业产品物有所值。如果你只是想为个人学习获取音轨、希望保持音频私密，或只是想要一款无附加条件的本地运行工具，StemDeck 已足够。
---
## Download
## 下载
Pre-built installers and zips are attached to each [GitHub Release](https://github.com/stemdeckapp/stemdeck/releases).
每个 [GitHub Release](https://github.com/stemdeckapp/stemdeck/releases). 都附有预构建安装包和 zip 压缩包。
**macOS**
| DMG | GPU | Chip |
| DMG | GPU | 芯片 |
|---|---|---|
| `StemDeck-macOS-arm64.dmg` | Apple Silicon (MPS) | M1 and later |
| `StemDeck-macOS-x64.dmg` | CPU only | Intel |
| `StemDeck-macOS-arm64.dmg` | Apple Silicon (MPS) | M1 及更新机型 |
| `StemDeck-macOS-x64.dmg` | 仅 CPU | 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.
打开 DMG，将 StemDeck 拖入 Applications（应用程序）文件夹并启动。首次启动时，设置界面会下载 Python 运行时（约 500 MB）、FFmpeg 以及 Demucs 模型（约 170 MB）。之后再次启动会跳过设置，几秒内即可进入。无需安装 Python 或任何系统依赖。
macOS may show a Gatekeeper prompt on first open — right-click the app and choose Open to bypass it.
macOS 首次打开时可能会弹出 Gatekeeper 提示——右键点击应用并选择“打开”即可绕过。
**Windows**
| Zip | GPU | Approx. size |
| Zip | GPU | 大约大小 |
|---|---|---|
| `StemDeck-Windows-x64.zip` | CPU only | ~700 MB |
| `StemDeck-Windows-x64.zip` | 仅 CPU | ~700 MB |
| `StemDeck-Windows-x64.NVIDIA.zip` | NVIDIA CUDA | ~1.6 GB |
Extract the zip anywhere, run `StemDeck.exe`. On first launch the app verifies the bundled Python runtime and downloads FFmpeg and the Demucs model (~170 MB). Subsequent launches skip this and start in seconds. Everything is self-contained; no Python or system dependencies required.
将 zip 解压到任意位置，运行 `StemDeck.exe`。首次启动时，应用会校验内置的 Python 运行时，并下载 FFmpeg 与 Demucs 模型（约 170 MB）。之后再次启动会跳过此步骤，几秒内即可进入。所有内容自包含；无需 Python 或系统依赖。
---
## Technologies
## 技术栈
<div align="center">
<img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-0078D6?style=flat-square&logo=windows" alt="Platform">
@@ -141,17 +147,17 @@ Extract the zip anywhere, run `StemDeck.exe`. On first launch the app verifies t
<br>
StemDeck is built on **[Python 3.12](https://python.org)** managed via **[uv](https://github.com/astral-sh/uv)**, with a **[FastAPI](https://fastapi.tiangolo.com)** backend serving REST and Server-Sent Events. Stem separation uses **[Demucs](https://github.com/facebookresearch/demucs)** (`htdemucs_6s`), Meta AI's open-source 6-stem neural network. YouTube audio is fetched via **[yt-dlp](https://github.com/yt-dlp/yt-dlp)**; transcoding and mixing use **[FFmpeg](https://ffmpeg.org)**. BPM detection and key analysis run on **[librosa](https://librosa.org)**; loudness measurement uses **[pyloudnorm](https://github.com/csteinmetz1/pyloudnorm)** (ITU-R BS.1770). The macOS and Windows desktop shells are **[Tauri v2](https://tauri.app)** (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.
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，无框架、无构建步骤；波形在 `<canvas>` 上通过 min/max 采样渲染绘制。
*Thanks to the creators and maintainers of all the open-source libraries that make StemDeck possible.*
*感谢所有开源库的创作者与维护者，正是他们让 StemDeck 成为可能。*
---
## Build from Source
## 从源码构建
### macOS Native App
### macOS 原生应用
Requires Rust, Node.js, and Python 3.12. Builds a self-contained `.app` that downloads its own runtime on first launch.
需要 Rust、Node.js 和 Python 3.12。会构建一个自包含的 `.app`，首次启动时会自行下载运行时。
```sh
# First time only — add the cross-compilation targets
@@ -169,31 +175,31 @@ 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`.
`.app` 输出到 `desktop/src-tauri/target/<target>/release/bundle/macos/StemDeck.app`。DMG 输出到 `.build/macos-dist/StemDeck-macOS-<arch>.dmg`。
To run a fresh build directly without the DMG:
若要在不安装 DMG 的情况下直接运行全新构建：
```sh
open desktop/src-tauri/target/aarch64-apple-darwin/release/bundle/macos/StemDeck.app
```
If macOS blocks the app with a Gatekeeper prompt, run:
若 macOS 因 Gatekeeper 提示阻止应用运行，请执行：
```sh
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.
> **注意：** 开发过程中若要测试干净的首次启动，可先清除先前的应用数据：`rm -rf ~/Library/Application\ Support/StemDeck`。请勿在正式安装环境中执行此操作。
---
### Web Server (macOS / Linux / Windows with Python 3.12+)
### Web 服务器（macOS / Linux / 已安装 Python 3.12+ 的 Windows）
#### Prerequisites
#### 前置条件
Python 3.12 or newer, `ffmpeg` on your PATH, and [uv](https://github.com/astral-sh/uv). Around 170 MB of free disk for the Demucs model, which downloads automatically on first run.
Python 3.12 或更高版本，PATH 中可访问 `ffmpeg`，以及 [uv](https://github.com/astral-sh/uv).。Demucs 模型约需 170 MB 磁盘空间，首次运行时会自动下载。
#### macOS / Linux (one-shot)
#### macOS / Linux（一键脚本）
```sh
git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck
@@ -201,15 +207,15 @@ git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck
./run.sh start
```
Open <http://localhost:8000>.
打开 <http://localhost:8000>。
`setup` uses Homebrew on macOS and `apt-get` on Debian/Ubuntu. For other Linux distros, install `ffmpeg` and [uv](https://github.com/astral-sh/uv) manually, then run `uv sync` followed by `./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)
#### Windows（PowerShell）
Install prerequisites:
安装前置依赖：
- [uv](https://docs.astral.sh/uv/getting-started/installation/) — `winget install astral-sh.uv`
- [ffmpeg](https://ffmpeg.org/download.html) — `winget install Gyan.FFmpeg` (or Chocolatey: `choco install ffmpeg`)
- [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
@@ -217,11 +223,11 @@ uv sync
uv run uvicorn app.main:app --host 127.0.0.1 --port 8000
```
Open <http://localhost:8000>.
打开 <http://localhost:8000>。
> `run.sh` is macOS/Linux only. On Windows use the PowerShell commands above, or run inside WSL.
> `run.sh` 仅适用于 macOS/Linux。在 Windows 上请使用上述 PowerShell 命令，或在 WSL 中运行。
**NVIDIA GPU (CUDA):** install the CUDA-enabled torch build before starting:
**NVIDIA GPU（CUDA）：** 启动前先安装支持 CUDA 的 torch 构建：
```powershell
uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
@@ -231,7 +237,7 @@ uv run uvicorn app.main:app --host 127.0.0.1 --port 8000
---
#### Manual (any platform)
#### 手动安装（任意平台）
```sh
git clone https://github.com/stemdeckapp/stemdeck stemdeck && cd stemdeck
@@ -245,9 +251,9 @@ uv run uvicorn app.main:app --reload
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.
分离音轨会写入宿主机的 `./jobs/`。Demucs 权重缓存在命名卷中，重建时不会重新下载。注意：macOS Docker 不支持 GPU 透传。
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).
预构建镜像发布在 GHCR。标签：`edge`（滚动更新，每次合并到 main 时重建）、`latest`（最新稳定版发布）以及 `X.Y.Z`（固定到某一发布版本）。
```sh
docker run -d --name stemdeck -p 8000:8000 \
@@ -257,18 +263,18 @@ docker run -d --name stemdeck -p 8000:8000 \
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.
在已安装 NVIDIA 驱动与 NVIDIA Container Toolkit 的 Linux 宿主机上，添加 `--runtime=nvidia -e NVIDIA_VISIBLE_DEVICES=all`，StemDeck 会自动检测 CUDA。镜像已内置支持 CUDA 的 torch，无需单独安装 CUDA。
#### Unraid
StemDeck is available in Unraid Community Applications: open **Apps**, search "StemDeck", and install. Map the two volumes to persistent appdata paths:
StemDeck 可在 Unraid Community Applications 中获取：打开 **Apps**，搜索 "StemDeck" 并安装。将两个卷映射到持久化 appdata 路径：
- `/app/jobs` -> `/mnt/user/appdata/stemdeck/jobs` (library + stems)
- `/cache` -> `/mnt/user/appdata/stemdeck/cache` (model weights)
- `/app/jobs` -> `/mnt/user/appdata/stemdeck/jobs`（曲库 + 音轨）
- `/cache` -> `/mnt/user/appdata/stemdeck/cache`（模型权重）
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.
曲库默认持久化（`STEMDECK_PERSIST_LIBRARY=1`），因此曲目不会被自动删除。若要 GPU 加速，请安装 **Nvidia Driver** 插件，然后将容器的 Extra Parameters 设置为 `--runtime=nvidia`（模板中已包含 `NVIDIA_VISIBLE_DEVICES` 与 `NVIDIA_DRIVER_CAPABILITIES` 变量）。仅 CPU 模式无需额外配置。
#### `run.sh` control script
#### `run.sh` 控制脚本
```sh
./run.sh setup # one-shot: install ffmpeg + uv, then uv sync
@@ -280,81 +286,81 @@ The library is persistent by default (`STEMDECK_PERSIST_LIBRARY=1`), so tracks a
---
## How to Use
## 使用方法
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 MP3/WAV file, 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.
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 文件。
**Keyboard shortcuts:** `Space` play/pause · `[` seek -5s · `]` seek +5s · `L` loop · `I` loop in · `O` loop out
**键盘快捷键：** `Space` 播放/暂停 · `[` 后退 5 秒 · `]` 前进 5 秒 · `L` 循环 · `I` 循环入点 · `O` 循环出点
---
## Configuration
## 配置
| 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. |
| `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` 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).
`run.sh` 还会读取：`HOST`（默认 `127.0.0.1`）、`PORT`（默认 `8765`）、`RELOAD=1`（开发时启用 uvicorn 自动重载）、`FOREGROUND=1`（前台运行而非后台运行）。
---
## API
| 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) |
| 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}` | 从磁盘删除任务目录（仅限已结束任务） |
---
## Troubleshooting
## 故障排除
**`ffmpeg: command not found`:** install ffmpeg and restart with `./run.sh restart`.
**`ffmpeg: command not found`：** 安装 ffmpeg 并使用 `./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.
**`WARNING: [youtube] No supported JavaScript runtime`：** 安装 deno（macOS 上为 `brew install deno`）并重启。未安装时下载仍可用，但可能选择次优格式。
**First separation is very slow:** Demucs downloads `htdemucs_6s` weights (~170 MB) on first run; cached afterwards.
**首次分离非常慢：** Demucs 首次运行时会下载 `htdemucs_6s` 权重（约 170 MB）；之后会缓存。
**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.
**Demucs 仅在 CPU 上运行：** 检查启动日志中的 `device=mps` 或 `device=cuda`。若看到 `cpu`，你的 torch 安装可能仅为 CPU 版。
**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`.
**`./run.sh: Permission denied`：** 运行 `chmod +x run.sh`。
---
## Layout on Disk
## 磁盘布局
```
jobs/<job_id>/
@@ -369,25 +375,25 @@ jobs/<job_id>/
└── 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).
任务状态保存在内存中。重启服务器后任务列表会重置，但文件仍保留在磁盘上。旧目录会自动清理（TTL 24 小时，可配置）。
---
## Disclaimer
## 免责声明
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.
StemDeck 是一款本地音频 stem 分离工具，供个人学习、研究与实验使用。它不是下载服务，不会存储、缓存或再分发任何音频内容。所有处理均在用户本机运行，不会将音频传输到任何其他地方。
YouTube URL support is provided via [yt-dlp](https://github.com/yt-dlp/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.
YouTube URL 支持通过 [yt-dlp](https://github.com/yt-dlp/yt-dlp) 提供，仅为便利。自动下载可能违反 YouTube 的服务条款。你（用户）须自行确保对所提交音频拥有处理权利，遵守所下载网站的各项服务条款，并尊重所处理材料的版权。
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`).
你还须遵守本项目所依赖底层工具的许可证（yt-dlp、Demucs、FFmpeg、PyTorch 及 `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.
StemDeck 作者按“原样”提供本软件，不作任何形式的担保，且不对其使用方式承担任何责任。
---
## Community
## 社区
| Platform | Link |
| 平台 | 链接 |
|---|---|
| GitHub | [stemdeckapp/stemdeck](https://github.com/stemdeckapp/stemdeck) |
| Discord | [discord.gg/2MVsWqaPRe](https://discord.gg/2MVsWqaPRe) |
@@ -398,23 +404,23 @@ The author(s) of StemDeck provide this software "as is", without warranty of any
---
## Environment Variables
## 环境变量
These are for development and testing. Release builds only recognize the variables marked "release".
以下变量用于开发与测试。正式版构建仅识别标注为“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 |
| `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 |
---
## Contributing
## 贡献
Issues, feature suggestions, and pull requests are welcome. See open issues for what's planned.
欢迎提交 Issue、功能建议与 Pull Request。可查看开放的 Issue 了解计划中的内容。
---