Files
stemengine_old/docs/plans/USER_GUIDE.md
T
2026-04-06 14:49:06 +09:00

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

  1. Copy .env.example to .env.

  2. Set required variables (SEFOLDER, ENGINEFOLDER, PROJECTS, SECRET_KEY).

  3. Start StemEngine:

    • docker compose up -d --build
  4. 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

  1. Go to the separation workflow in the UI.
  2. Upload audio.
  3. Choose a model family and model.
  4. Start job and monitor progress.
  5. 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

  1. Select a project/audio source.
  2. Run MIDI transcription (polyphonic or melody mode).
  3. Export MIDI and optionally convert to ABC notation.

C. Create synced lyrics

  1. Open Lyric Transcription.
  2. Choose engine:
    • WhisperX for richer options (alignment/diarization paths)
    • Parakeet for sidecar ASR flow
  3. Choose output format (lrc, elrc, txt, json, srt, vtt).
  4. Run job and save outputs.

D. Align existing lyrics

  1. Open LRC/Lyrics alignment workflow.
  2. Paste/upload existing lyrics.
  3. 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.