stemdeckapp--stemdeck
wehub-resource-sync
572aca14f1
CI / deps-audit (push) Has been cancelled
CI / lint (push) Has been cancelled
CI / test (push) Has been cancelled
CI / js-syntax (push) Has been cancelled
CI / sast-bandit (push) Has been cancelled
CI / trivy (push) Has been cancelled
Docker Publish / build-and-push (push) Has been cancelled
436 行
23 KiB
Markdown
436 行
23 KiB
Markdown
<!-- 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" />
|
||
|
||
**免费、本地音轨分离。无需账号。无需上传。无需订阅。**
|
||
|
||
<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>
|
||
<a href="https://github.com/stemdeckapp/stemdeck/stargazers"><img src="https://img.shields.io/github/stars/stemdeckapp/stemdeck?style=flat-square" alt="GitHub Stars"></a>
|
||
<a href="https://github.com/stemdeckapp/stemdeck/releases"><img src="https://img.shields.io/github/downloads/stemdeckapp/stemdeck/total?style=flat-square&color=52c65f" alt="Total Downloads"></a>
|
||
<a href="https://github.com/stemdeckapp/stemdeck/releases/latest"><img src="https://img.shields.io/github/v/release/stemdeckapp/stemdeck?style=flat-square" alt="Latest Release"></a>
|
||
<a href="https://github.com/stemdeckapp/stemdeck/blob/main/LICENSE"><img src="https://img.shields.io/github/license/stemdeckapp/stemdeck?style=flat-square" alt="License"></a>
|
||
</div>
|
||
|
||
<br>
|
||
|
||
<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>
|
||
<a href="https://www.reddit.com/r/StemDeckApp/"><img src="https://img.shields.io/badge/Reddit-r%2FStemDeckApp-FF4500?style=flat-square&logo=reddit&logoColor=white" alt="Reddit"></a>
|
||
<a href="https://www.instagram.com/stemdeck"><img src="https://img.shields.io/badge/Instagram-stemdeck-E4405F?style=flat-square&logo=instagram&logoColor=white" alt="Instagram"></a>
|
||
<a href="https://x.com/StemDeckApp"><img src="https://img.shields.io/badge/X-StemDeckApp-000000?style=flat-square&logo=x&logoColor=white" alt="X"></a>
|
||
<a href="https://stemdeck.app"><img src="https://img.shields.io/badge/Website-stemdeck.app-000000?style=flat-square&logo=safari&logoColor=white" alt="Website"></a>
|
||
</div>
|
||
|
||
</div>
|
||
|
||
<br>
|
||
|
||
拖入 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](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 或系统依赖。
|
||
|
||
---
|
||
|
||
## 技术栈
|
||
|
||
<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">
|
||
<img src="https://img.shields.io/badge/Powered_by-Demucs-FF6B35?style=flat-square" alt="Powered by Demucs">
|
||
<img src="https://img.shields.io/badge/CI-GitHub_Actions-2088FF?style=flat-square&logo=github-actions&logoColor=white" alt="CI: GitHub Actions">
|
||
</div>
|
||
|
||
<br>
|
||
|
||
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 采样渲染绘制。
|
||
|
||
*感谢所有开源库的创作者与维护者，正是他们让 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/<target>/release/bundle/macos/StemDeck.app`。DMG 输出到 `.build/macos-dist/StemDeck-macOS-<arch>.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
|
||
```
|
||
|
||
打开 <http://localhost:8000>。
|
||
|
||
`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
|
||
```
|
||
|
||
打开 <http://localhost: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` | `<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](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
|
||
|
||
<a href="https://www.star-history.com/?repos=stemdeckapp%2Fstemdeck&type=date&legend=top-left">
|
||
<picture>
|
||
<source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/chart?repos=stemdeckapp/stemdeck&type=date&theme=dark&legend=top-left" />
|
||
<source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/chart?repos=stemdeckapp/stemdeck&type=date&legend=top-left" />
|
||
<img alt="Star History Chart" src="https://api.star-history.com/chart?repos=stemdeckapp/stemdeck&type=date&legend=top-left" />
|
||
</picture>
|
||
</a>
|