stemkit README

The project's README from github.com/danielravina/stemkit. As one markdown file: README.md.

StemKit

Split any YouTube song into isolated stems — vocals, drums, bass, guitar, piano and more — right on your machine.

Search YouTube or paste a link, pick the instruments you want, and play the result like a mini DAW: the video on one side, every stem on its own fader, all perfectly in sync. Karaoke, acapellas and instrumentals are one click away.

Everything runs locally — no accounts, no cloud, no API keys.

platform local

StemKit splitting Queen's Bohemian Rhapsody into six stems — video player, presets and color-coded waveform lanes

Features

Download

Grab installers from Releases:

First launch creates a private Python environment and downloads the separation engine (~2 GB) — one time. ffmpeg is bundled — nothing else to install.

Optional quality upgrades live behind a gear icon in the app (Settings), each with its own one-time download:

macOS first launch: builds are signed with a Developer ID but not notarized, so macOS may say it "cannot verify the developer". One-time fix: System Settings → Privacy & Security → Open Anyway (or xattr -cr /Applications/StemKit.app).

Windows: SmartScreen may warn on first run — "More info → Run anyway".

Requirements

Develop

npm install
npm run dev

Wrong Node version? Scripts auto-relaunch with a suitable one (nvm / nvm-windows).

Build & release

bash scripts/fetch-ffmpeg.sh        # mac/linux (one time)
powershell scripts/fetch-ffmpeg.ps1 # windows (one time)

npm run dist        # mac dmg -> release/
npm run dist:win    # windows nsis+zip -> release/
npm run dist:linux  # linux AppImage+deb (x64) -> release/
npm run dist:all    # both (on the matching OS)

Linux: building the .deb needs dpkg + fakeroot on the host; running the .AppImage needs FUSE. In-app self-update works on the AppImage — .deb installs update by re-downloading.

Releases are built by GitHub Actions:

macOS builds are Developer-ID-signed when the certificate is available — see Signing in CI below for the one-time setup, plus optional notarization.

Signing in CI (one-time setup)

Local builds sign with your keychain cert automatically. CI runners have empty keychains, so hand them the certificate via repo secrets:

  1. Keychain Access → My Certificates → right-click Developer ID Application: ... → Export → .p12 (set an export password)
  2. Base64 it and add these repo secrets:
    • CSC_MAC_P12 — the base64 string: base64 -i developer-id.p12 | pbcopy
    • CSC_MAC_PASSWORD — the export password from step 1
  3. Optional (full notarization, zero Gatekeeper prompts): add APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, APPLE_TEAM_ID and set repo variable ENABLE_NOTARIZATION to true (Settings → Secrets and variables → Actions → Variables). Requires an active Apple Developer membership — Apple's notary service rejects expired accounts.

Without these secrets CI falls back to ad-hoc signing (app runs, but Gatekeeper complains on download).

How it works

YouTube URL ──► yt-dlp (+JS runtime) ──► bundled ffmpeg ──► mel-band roformer (vocals) ─┐
                                        │                                               ├─► stems/*.wav
                                        └─────────────► demucs htdemucs ────────────────┘
                                             (drums/bass/other, shift-averaged)

Electron renderer ◄──── IPC events ─────┘
video iframe (muted) + Web Audio stem playback · master clock = the audio itself

Notes

Layout

src/main         Electron main process (pipeline, env bootstrap, library)
src/preload      IPC bridge
src/renderer     React UI (player, sync engine, waveforms)
python/          separate.py (demucs) and roformer.py (neural vocals) with JSON progress output
python/vendor/   patched model code — see python/vendor/README.md
scripts/         node runner, ffmpeg fetchers
build/           icon sources

stemkit (danielravina/stemkit)

auto-update
Searching Database…

1.1K ·GitHub
Stemkit
What is this?StemKit splits any YouTube song into isolated stems — vocals, drums, bass, guitar, piano and more — running entirely on your own machine, with a mini DAW-style player to mix/mute/solo each stem.
Is this a web app, or something I install on my computer?It is a native desktop app built with Electron and TypeScript, distributed as installers (DMG, EXE, AppImage/deb), not a web service.
How do I get it running?Download the matching installer from the GitHub Releases page — DMG for Apple Silicon Macs, an EXE installer or portable zip for Windows, or an AppImage/deb for Linux — and run it.
Do I need to install Python or ffmpeg myself first?No — on first launch StemKit automatically downloads a private Python runtime if needed (a one-time ~2GB download for the separation engine), and ffmpeg is bundled with the app.
Any install pitfalls I should know about?On macOS the app is signed but not notarized, so Gatekeeper will say it 'cannot verify the developer' until you allow it manually; on Windows, SmartScreen may warn on first run and needs 'Run anyway'.
Does it work on Intel Macs, or only Apple Silicon?Only Apple Silicon Macs are supported on macOS (12+); Windows 10/11 x64 and Linux x64 are also supported.
Does it need an internet connection after I've set it up?Once the one-time setup (runtime + separation engine) finishes, StemKit runs fully offline — you only need internet to initially search/download the YouTube audio itself.
Does my audio or YouTube link get sent anywhere?No — everything, including the separation itself, runs locally on your machine with no accounts, cloud services, or API keys involved.
Is downloading YouTube audio with this actually legal?The project itself is MIT licensed, but the README is upfront that pulling audio from YouTube violates its Terms of Service for public products, so it's meant for personal use only.
Do I need an NVIDIA GPU, or does it work on CPU too?A GPU speeds things up (Apple Silicon via MPS, NVIDIA via CUDA), but separation also runs on plain CPU if no GPU is available.
What instruments can StemKit separate?Vocals, drums, bass, guitar, piano and more — you pick the instruments and StemKit automatically selects the right separation engine for them.
What are the one-click presets?All, Karaoke, Acapella, and Drums + Bass presets instantly give you the stem combination you want without manual selection.
Can I export the separated stems?Yes, any single stem or all of them can be exported as WAV files.
Are there higher-quality separation options?Yes, optional one-time downloads in the Settings gear icon add Mel-Band Roformer studio-quality vocals (+913MB), a fine-tuned Demucs model (+~320MB, up to 4x slower), and extra refinement passes (up to 3x slower).
What are similar projects?ISpotify, ultimatevocalremovergui, yovoice, ytDownloader, openspot-music-app, SCM, course2md, demucs
Which topics is it in?karaoke, music-downloader, yt-dlp, auto-update, linux-app, electron-app, audio-processing, youtube, music, installer, privacy-first, ffmpeg
Creator
danielravina
Size
12.6 MB
Stars
1.1K
Updated
CommitOct 19Releasev0.2.0Oct 19
Age
1mo
Commits · 90 Days