Files
stemengine_old/docs/USER_GUIDE.md
T
2026-03-18 17:55:21 +09:00

2.5 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

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.

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.