3.8 KiB
3.8 KiB
StemEngine User Guide
1) What StemEngine does
StemEngine helps you:
- Separate songs into stems (vocals, drums, bass, etc.)
- Transcribe audio to MIDI
- Generate and align lyrics (LRC/ELRC)
- Create karaoke-ready project outputs
2) Requirements
- Docker + Docker Compose
- NVIDIA GPU + NVIDIA Container Toolkit for best performance
- Browser access to the StemEngine UI
3) Quick start
-
Copy
.env.exampleto.env. -
Set required variables (
SEFOLDER,ENGINEFOLDER,PROJECTS,SECRET_KEY). -
Start StemEngine:
docker compose up -d --build
-
Open
http://localhost:8000.
4) Core workflows
The WebUI now supports direct page URLs for the main screens. For example, refreshing a project page keeps you on that same project instead of returning to the home screen.
The WebUI also now restores key working context on refresh:
- sidebar open/collapsed state,
- project search text in the sidebar,
- separator settings and project name,
- imported-file selection when the imported file still exists,
- Auto Pipeline project-name drafts via restore/discard prompt.
PWA hardening is also now in place:
- install button appears when the browser exposes install capability,
- update-ready banner provides explicit reload-to-update flow,
- offline banner clarifies that live project/job data resumes after reconnect.
Cross-tab session hygiene is also now enabled:
- deleting a project in one tab removes stale project state in other open tabs,
- tabs currently viewing a deleted project are redirected out of that route,
- theme and appearance changes propagate across open tabs.
WebUI QoL release acceptance is tracked in WEBUI_QOL_QA_CHECKLIST.md.
A. Separate a track into stems
- Go to the separation workflow in the UI.
- Upload audio.
- Choose a model family and model.
- Start job and monitor progress.
- Download outputs or open the generated project.
Notes:
- Generated stems are automatically normalized to canonical project-style filenames.
- Stems with no significant audio are removed automatically so they do not clutter the project or downstream auto-pipeline stages.
B. Transcribe to MIDI
- Select a project/audio source.
- Run MIDI transcription (polyphonic or melody mode).
- Export MIDI and optionally convert to ABC notation.
C. Create synced lyrics
- Open Lyric Transcription.
- Choose engine:
WhisperXfor richer options (alignment/diarization paths)Parakeetfor sidecar ASR flow
- Choose output format (
lrc,elrc,txt,json,srt,vtt). - Run job and save outputs.
D. Align existing lyrics
- Open LRC/Lyrics alignment workflow.
- Paste/upload existing lyrics.
- Run alignment to generate timed output.
5) Output locations
Generated artifacts are stored in the configured project/output directories. Typical output includes:
- Source audio copy
- Separated stems (
Stems/) - Optional mixes (
Instrumental/,Static/,Dynamic/) - Lyrics artifacts (
.lrc,.elrc,.txt,.json,.srt,.vtt)
6) Troubleshooting
- GPU memory issues: reduce model size, lower workload, or increase reserve tuning variables.
- Slow runs: verify GPU container runtime is enabled.
- Parakeet unavailable: confirm sidecar URL and health endpoint configuration.
- No/poor lyric alignment: prefer vocals stem input and verify language settings.
7) Best practices
- Use vocals-focused stems for lyric transcription quality.
- Start with balanced models, then move to large models only when needed.
- Keep project names and source metadata clean for easier downstream workflows.
8) Known limits
- Some advanced options are engine-specific.
- Sidecar-dependent features require correctly configured auxiliary services.
- CPU-only operation is supported but can be significantly slower.