stemit-cli 1.0.0

package/README.md

@@ -0,0 +1,399 @@
+# stemit
+
+> Separate any song into its stems — vocals, drums, bass, guitar, piano, and more.
+> Analyze BPM & musical key. Mute or solo any instrument. Works with YouTube URLs or local files.
+
+```
+      _                 _ _
+  ___| |_ ___ _ __ ___ (_) |_
+ / __| __/ _ \ '_ ` _ \| | __|
+ \__ \ ||  __/ | | | | | | |_
+ |___/\__\___|_| |_| |_|_|\__|
+  stem separator · BPM · key · mix
+```
+
+---
+
+## Table of Contents
+
+- [stemit](#stemit)
+  - [Table of Contents](#table-of-contents)
+  - [What it does](#what-it-does)
+  - [Prerequisites](#prerequisites)
+  - [Installation](#installation)
+    - [Using npx (no install required)](#using-npx-no-install-required)
+    - [Global install](#global-install)
+    - [Local install (in a project)](#local-install-in-a-project)
+  - [Quick Start](#quick-start)
+  - [Usage](#usage)
+    - [Basic split](#basic-split)
+    - [6-stem split (guitar + piano)](#6-stem-split-guitar--piano)
+    - [Mute a stem](#mute-a-stem)
+    - [Solo a stem](#solo-a-stem)
+    - [Export as MP3](#export-as-mp3)
+    - [Skip BPM/key analysis](#skip-bpmkey-analysis)
+    - [All options](#all-options)
+  - [Available Models](#available-models)
+  - [Output Structure](#output-structure)
+  - [How It Works](#how-it-works)
+  - [First-Run Setup](#first-run-setup)
+  - [Troubleshooting](#troubleshooting)
+    - [`demucs exited with code 1`](#demucs-exited-with-code-1)
+    - [`ImportError: TorchCodec is required`](#importerror-torchcodec-is-required)
+    - [`ffmpeg not found`](#ffmpeg-not-found)
+    - [`python3 not found` / `python not found`](#python3-not-found--python-not-found)
+    - [Progress bar cycles multiple times](#progress-bar-cycles-multiple-times)
+    - [Slow processing](#slow-processing)
+    - [Resetting the venv](#resetting-the-venv)
+  - [License](#license)
+
+---
+
+## What it does
+
+`stemit` takes a song (from a YouTube URL or a local audio file) and:
+
+1. **Downloads** it via `yt-dlp` if you pass a URL
+2. **Separates** it into individual instrument stems using [Demucs](https://github.com/facebookresearch/demucs) (Facebook Research's state-of-the-art source separation model)
+3. **Analyzes** the BPM and musical key of the result
+4. **Mixes** stems back together with specific instruments muted or soloed
+5. **Exports** everything as WAV or MP3
+
+You get back clean, studio-quality isolated tracks you can drop straight into your DAW.
+
+---
+
+## Prerequisites
+
+stemit requires two system-level dependencies. Everything else (including Demucs itself) is installed automatically on first run.
+
+| Dependency | Minimum Version | Install |
+|---|---|---|
+| **Node.js** | 18+ | https://nodejs.org |
+| **Python** | 3.9+ | https://www.python.org/downloads/ |
+| **ffmpeg** | any | `brew install ffmpeg` / `sudo apt install ffmpeg` / `winget install ffmpeg` |
+
+> **Note:** Demucs (the AI model) and all Python dependencies are installed automatically into a private virtualenv at `~/.stemit/venv` the first time you run any `stemit` command. You do not need to `pip install` anything yourself.
+
+---
+
+## Installation
+
+### Using npx (no install required)
+
+```bash
+npx stemit-cli split "https://www.youtube.com/watch?v=..."
+```
+
+### Global install
+
+```bash
+npm install -g stemit-cli
+stemit split "https://www.youtube.com/watch?v=..."
+```
+
+### Local install (in a project)
+
+```bash
+npm install stemit-cli
+npx stemit split ./my-song.wav
+```
+
+---
+
+## Quick Start
+
+```bash
+# Split a YouTube video into stems
+stemit split "https://www.youtube.com/watch?v=oTS0LLXaLF0"
+
+# Split a local file
+stemit split ./my-song.wav
+
+# Get 6 stems (adds guitar + piano)
+stemit split ./my-song.wav --model htdemucs_6s
+
+# Produce an instrumental (no vocals)
+stemit split ./my-song.wav --mute vocals
+
+# Isolate just the drums
+stemit split ./my-song.wav --solo drums
+
+# Export everything as MP3
+stemit split ./my-song.wav --format mp3
+```
+
+---
+
+## Usage
+
+### Basic split
+
+```bash
+stemit split <input> [options]
+```
+
+`<input>` can be:
+- A **YouTube URL** — `stemit split "https://www.youtube.com/watch?v=..."`
+- A **local file path** — `stemit split ./song.wav` or `stemit split ./song.mp3`
+
+The command will:
+1. Check dependencies (and auto-install Demucs if needed)
+2. Download the audio if a URL was provided
+3. Run Demucs stem separation with a live progress bar
+4. Analyze BPM and key of the result
+5. Print a summary box with all output file paths
+
+---
+
+### 6-stem split (guitar + piano)
+
+The `htdemucs_6s` model separates 6 instruments instead of the default 4, adding `guitar` and `piano` tracks:
+
+```bash
+stemit split ./my-song.wav --model htdemucs_6s
+```
+
+Output stems: `vocals`, `drums`, `bass`, `guitar`, `piano`, `other`
+
+> **Caveat:** This model works best on Western pop/rock. For songs without guitar or piano those tracks will be mostly silent, and their content stays in `other`.
+
+---
+
+### Mute a stem
+
+Muting removes one instrument and mixes the rest back together. Useful for creating instrumentals or karaoke tracks.
+
+```bash
+# Remove vocals → instrumental
+stemit split ./my-song.wav --mute vocals
+
+# Remove drums → no-drums mix
+stemit split ./my-song.wav --mute drums
+```
+
+Valid values: `vocals`, `drums`, `bass`, `guitar`, `piano`, `other`
+
+The mixed output is saved as `mute-<stem>.wav` inside the song's stem folder, alongside the individual stem files.
+
+---
+
+### Solo a stem
+
+Soloing keeps only one instrument and discards the rest. No mixing needed — the file is simply copied.
+
+```bash
+# Isolate only vocals
+stemit split ./my-song.wav --solo vocals
+
+# Isolate only drums
+stemit split ./my-song.wav --solo drums
+```
+
+Valid values: `vocals`, `drums`, `bass`, `guitar`, `piano`, `other`
+
+The output is saved as `solo-<stem>.wav` inside the song's stem folder.
+
+---
+
+### Export as MP3
+
+By default all output files are WAV. Pass `--format mp3` to convert everything to MP3 after splitting:
+
+```bash
+stemit split ./my-song.wav --format mp3
+```
+
+This converts all stem files (and the mixed output, if `--mute` or `--solo` was used) to MP3 using `ffmpeg` at variable bitrate (`-q:a 0`, highest quality).
+
+---
+
+### Skip BPM/key analysis
+
+BPM and key detection uses [essentia.js](https://mtg.github.io/essentia.js/) (WASM) and adds a few seconds. Skip it with `--no-analyze`:
+
+```bash
+stemit split ./my-song.wav --no-analyze
+```
+
+---
+
+### All options
+
+```
+stemit split <input> [options]
+
+Options:
+  --model <name>   Demucs model to use (default: "htdemucs_ft")
+                   htdemucs | htdemucs_ft | htdemucs_6s | mdx | mdx_extra | mdx_extra_q
+  --out <dir>      Output directory (default: "./stemit-output")
+  --mute <stem>    Mute one stem and mix the rest (vocals|drums|bass|guitar|piano|other)
+  --solo <stem>    Keep only one stem (vocals|drums|bass|guitar|piano|other)
+  --format <fmt>   Output format: wav or mp3 (default: "wav")
+  --no-analyze     Skip BPM and key detection
+  -h, --help       Show help
+  -V, --version    Show version
+```
+
+---
+
+## Available Models
+
+| Model | Stems | Notes |
+|---|---|---|
+| `htdemucs_ft` | vocals, drums, bass, other | **Default.** Fine-tuned hybrid transformer — best quality for 4 stems |
+| `htdemucs` | vocals, drums, bass, other | Slightly faster than `_ft`, marginally lower quality |
+| `htdemucs_6s` | vocals, drums, bass, **guitar, piano**, other | 6-stem model — adds guitar and piano separation |
+| `mdx_extra` | vocals, drums, bass, other | Alternative architecture, good for vocals |
+| `mdx` | vocals, drums, bass, other | Faster MDX variant |
+| `mdx_extra_q` | vocals, drums, bass, other | Quantized MDX — smallest model, fastest inference |
+
+**Which model should I use?**
+
+- Default (`htdemucs_ft`) — best all-round quality, use this unless you have a reason not to
+- `htdemucs_6s` — when you specifically need guitar or piano isolated
+- `mdx_extra` — when vocals quality is the priority
+- `mdx_extra_q` — when speed matters more than quality (e.g. batch processing)
+
+**Speed note:** Demucs runs on CPU by default. Processing time is roughly **2–5× the song length** on modern hardware (e.g. a 4-minute song takes 8–20 minutes). The `mdx_extra_q` model is significantly faster.
+
+---
+
+## Output Structure
+
+```
+stemit-output/
+└── htdemucs_ft/
+    └── My Song Title/
+        ├── vocals.wav
+        ├── drums.wav
+        ├── bass.wav
+        ├── other.wav
+        ├── mute-vocals.wav     ← produced when --mute vocals is used
+        └── solo-drums.wav      ← produced when --solo drums is used
+```
+
+All files are grouped under `--out/<model>/<song-name>/` (default: `./stemit-output`).
+
+---
+
+## How It Works
+
+```
+┌─────────────┐    yt-dlp      ┌────────────┐
+│  YouTube URL │ ─────────────▶ │  audio.wav │
+└─────────────┘                └─────┬──────┘
+                                     │
+                 local file ─────────┘
+                                     │
+                                     ▼
+                          ┌─────────────────────┐
+                          │   Demucs (Python)    │
+                          │   htdemucs_ft model  │
+                          │   ~/.stemit/venv     │
+                          └──────────┬──────────┘
+                                     │
+              ┌──────────────────────┼──────────────────────┐
+              ▼          ▼           ▼           ▼           ▼
+         vocals.wav  drums.wav   bass.wav   guitar.wav  other.wav
+              │
+              ▼
+   ┌─────────────────────┐
+   │   essentia.js WASM  │
+   │   BPM + Key detect  │
+   └─────────────────────┘
+
+  optional:
+   stems ──▶ ffmpeg amix ──▶ mute-vocals.wav
+   stems ──▶ ffmpeg copy ──▶ solo-drums.wav
+   *.wav  ──▶ ffmpeg      ──▶ *.mp3
+```
+
+**Tech stack:**
+
+| Component | Library | Notes |
+|---|---|---|
+| CLI framework | [commander](https://github.com/tj/commander.js) | Parses flags and subcommands |
+| YouTube download | [youtube-dl-exec](https://github.com/microlinkhq/youtube-dl-exec) | Wraps yt-dlp, auto-downloads binary |
+| Stem separation | [Demucs](https://github.com/facebookresearch/demucs) via `child_process.spawn` | Runs in managed Python venv |
+| Stem mixing | ffmpeg `amix` filter | `normalize=0` to preserve volume |
+| BPM + Key | [essentia.js](https://mtg.github.io/essentia.js/) | WASM, runs in Node |
+| Audio decode | [audio-decode](https://github.com/audiojs/audio-decode) | Decodes WAV/MP3 to float32 for essentia |
+| WAV→MP3 | ffmpeg | `-q:a 0` (VBR highest quality) |
+| Progress bars | [cli-progress](https://github.com/npkgjs/cli-progress) | Live chunk-by-chunk demucs progress |
+| Spinners | [ora](https://github.com/sindresorhus/ora) | Per-step feedback |
+| Summary panel | [boxen](https://github.com/sindresorhus/boxen) + [chalk](https://github.com/chalk/chalk) | Formatted terminal output |
+| ASCII banner | [figlet](https://github.com/patorjk/figlet.js) | Startup art |
+
+---
+
+## First-Run Setup
+
+The first time you run `stemit split`, it will:
+
+1. Verify Python 3.9+ and ffmpeg are installed
+2. Create a Python virtualenv at `~/.stemit/venv`
+3. Install Demucs and its dependencies into that venv (`pip install demucs soundfile torchcodec`)
+
+This one-time setup takes **2–5 minutes** depending on your internet connection (Demucs pulls in PyTorch, which is a large download). After that, the venv is reused on every run.
+
+The AI model weights (~300 MB per model) are downloaded by Demucs on first use of each model and cached in `~/.cache/torch/hub/`.
+
+---
+
+## Troubleshooting
+
+### `demucs exited with code 1`
+
+Run with a local file first to rule out download issues. The full Demucs error is printed below the message. Common causes:
+
+- **Out of memory** — Demucs needs ~4 GB RAM for `htdemucs_ft`. Try `--model mdx_extra_q` which is lighter.
+- **Corrupt audio file** — ensure the file plays correctly before passing it to stemit.
+- **Python version conflict** — stemit uses its own venv at `~/.stemit/venv`, but if you see import errors, try deleting the venv and re-running: `rm -rf ~/.stemit/venv`
+
+### `ImportError: TorchCodec is required`
+
+This happens with `torchaudio >= 2.5` on a fresh install if `torchcodec` wasn't installed. stemit handles this automatically during setup, but if you hit it manually:
+
+```bash
+~/.stemit/venv/bin/pip install torchcodec
+```
+
+### `ffmpeg not found`
+
+Install ffmpeg for your platform:
+
+- **macOS:** `brew install ffmpeg`
+- **Linux:** `sudo apt install ffmpeg`
+- **Windows:** `winget install ffmpeg`
+
+### `python3 not found` / `python not found`
+
+Install Python 3.9+ from https://www.python.org/downloads/ and ensure it's on your PATH.
+
+On Windows, the installer adds `python` (not `python3`) to PATH — stemit checks both.
+
+### Progress bar cycles multiple times
+
+This is normal. Demucs splits audio into overlapping chunks and processes them sequentially. Each chunk shows its own 0→100% progress. The label shows `chunk N/M` so you can track overall progress.
+
+### Slow processing
+
+Demucs runs on CPU by default — this is expected. A 4-minute song takes 8–20 minutes on modern hardware. There is no GPU acceleration option in stemit currently (Demucs supports CUDA if you have an NVIDIA GPU and install the CUDA version of PyTorch manually into `~/.stemit/venv`).
+
+### Resetting the venv
+
+If something goes wrong with the Python environment, delete the venv and re-run:
+
+```bash
+rm -rf ~/.stemit/venv
+stemit split ./any-file.wav
+```
+
+This re-creates the venv and re-installs Demucs from scratch.
+
+---
+
+## License
+
+MIT © saravanaraja25

package/bin/stemit.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/commands/split.js'

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "stemit-cli",
+  "version": "1.0.0",
+  "description": "CLI tool to split audio into stems (vocals/drums/bass/other), analyze BPM & key, and mute/solo tracks",
+  "type": "module",
+  "bin": {
+    "stemit": "bin/stemit.js",
+    "stemit-cli": "bin/stemit.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "audio",
+    "stem",
+    "demucs",
+    "music",
+    "bpm",
+    "key",
+    "vocals",
+    "split",
+    "remix",
+    "cli"
+  ],
+  "author": "saravanaraja25",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/saravanaraja25/stemit.git"
+  },
+  "homepage": "https://github.com/saravanaraja25/stemit#readme",
+  "bugs": {
+    "url": "https://github.com/saravanaraja25/stemit/issues"
+  },
+  "scripts": {
+    "start": "node bin/stemit.js"
+  },
+  "dependencies": {
+    "audio-decode": "^2.1.4",
+    "debug": "^4.3.7",
+    "boxen": "^7.1.1",
+    "chalk": "^5.3.0",
+    "cli-progress": "^3.12.0",
+    "commander": "^12.1.0",
+    "essentia.js": "^0.1.3",
+    "figlet": "^1.7.0",
+    "fs-extra": "^11.2.0",
+    "ora": "^8.0.1",
+    "which": "^4.0.0",
+    "youtube-dl-exec": "^3.0.12"
+  }
+}

package/src/commands/setup.js

@@ -0,0 +1,120 @@
+import { execSync, spawnSync } from 'child_process'
+import path from 'path'
+import fs from 'fs-extra'
+import which from 'which'
+import chalk from 'chalk'
+import os from 'os'
+
+const VENV_DIR = path.join(os.homedir(), '.stemit', 'venv')
+const VENV_PYTHON =
+  process.platform === 'win32'
+    ? path.join(VENV_DIR, 'Scripts', 'python.exe')
+    : path.join(VENV_DIR, 'bin', 'python3')
+const VENV_PIP =
+  process.platform === 'win32'
+    ? path.join(VENV_DIR, 'Scripts', 'pip.exe')
+    : path.join(VENV_DIR, 'bin', 'pip3')
+
+const FFMPEG_INSTALL = {
+  darwin: 'brew install ffmpeg',
+  linux:  'sudo apt install ffmpeg  (or your distro package manager)',
+  win32:  'winget install ffmpeg  (or https://ffmpeg.org/download.html)',
+}
+
+/**
+ * Ensure all system + Python dependencies are ready.
+ * Creates ~/.stemit/venv and auto-installs demucs into it if needed.
+ * @returns {Promise<{ pythonPath: string }>}
+ */
+export async function checkDependencies() {
+  const errors = []
+
+  // ── ffmpeg ──────────────────────────────────────────────────────────────────
+  try {
+    await which('ffmpeg')
+  } catch {
+    const hint = FFMPEG_INSTALL[process.platform] ?? 'https://ffmpeg.org/download.html'
+    errors.push(`ffmpeg not found.\n  Install: ${hint}`)
+  }
+
+  // ── python3 / python (Windows uses "python") ─────────────────────────────────
+  let systemPython = null
+  try {
+    // Try python3 first (macOS/Linux), fall back to python (Windows / some Linux)
+    for (const cmd of ['python3', 'python']) {
+      try {
+        await which(cmd)
+        systemPython = cmd
+        break
+      } catch {
+        // try next
+      }
+    }
+
+    if (!systemPython) throw new Error('not found')
+
+    const versionOutput = execSync(`${systemPython} --version`, { encoding: 'utf8' }).trim()
+    const match = versionOutput.match(/Python (\d+)\.(\d+)/)
+    if (!match) {
+      errors.push('Could not parse Python version.')
+    } else {
+      const [, major, minor] = match.map(Number)
+      if (major < 3 || (major === 3 && minor < 9)) {
+        errors.push(
+          `Python 3.9+ required, found ${versionOutput}.\n  Upgrade: https://www.python.org/downloads/`
+        )
+      }
+    }
+  } catch {
+    errors.push('Python not found.\n  Install Python 3.9+: https://www.python.org/downloads/')
+  }
+
+  if (errors.length > 0) {
+    console.error(chalk.red('\n✖ Missing dependencies:\n'))
+    errors.forEach((e) => console.error(chalk.red(`  • ${e}\n`)))
+    process.exit(1)
+  }
+
+  // ── venv + demucs (auto-managed) ─────────────────────────────────────────
+  const pythonPath = await ensureDemucsVenv(systemPython)
+  return { pythonPath }
+}
+
+async function ensureDemucsVenv(systemPython) {
+  // Create venv if it doesn't exist yet
+  if (!fs.existsSync(VENV_PYTHON)) {
+    console.log(chalk.cyan('\n  Creating Python venv at ~/.stemit/venv …'))
+    await fs.ensureDir(path.dirname(VENV_DIR))
+
+    const create = spawnSync(systemPython, ['-m', 'venv', VENV_DIR], { encoding: 'utf8' })
+    if (create.status !== 0) {
+      console.error(chalk.red(`\n  Failed to create venv:\n${create.stderr}`))
+      process.exit(1)
+    }
+    console.log(chalk.green('  ✔ venv created'))
+  }
+
+  // Install demucs if not already present in the venv
+  const demucsCheck = spawnSync(VENV_PYTHON, ['-m', 'demucs', '--help'], {
+    encoding: 'utf8',
+    stdio: 'pipe',
+  })
+
+  if (demucsCheck.status !== 0) {
+    console.log(chalk.cyan('  Installing demucs (one-time setup, may take a minute) …'))
+    const install = spawnSync(VENV_PIP, ['install', 'demucs', 'soundfile', 'torchcodec'], {
+      encoding: 'utf8',
+      stdio: 'inherit',
+    })
+    if (install.status !== 0) {
+      console.error(chalk.red(
+        '\n  Failed to install demucs. Try manually:\n' +
+        '    pip install demucs soundfile torchcodec'
+      ))
+      process.exit(1)
+    }
+    console.log(chalk.green('  ✔ demucs installed'))
+  }
+
+  return VENV_PYTHON
+}

package/src/commands/split.js

@@ -0,0 +1,173 @@
+import { Command } from 'commander'
+import path from 'path'
+import chalk from 'chalk'
+import ora from 'ora'
+
+import { checkDependencies } from './setup.js'
+import { resolveInput } from '../lib/downloader.js'
+import { splitStems, ALL_STEMS, MODEL_STEMS } from '../lib/splitter.js'
+import { mixStems } from '../lib/mixer.js'
+import { analyzeAudio } from '../lib/analyzer.js'
+import { wavToMp3 } from '../lib/converter.js'
+import { printBanner } from '../ui/banner.js'
+import { createBar, stopAll } from '../ui/progress.js'
+import { printSummary } from '../ui/summary.js'
+
+const VALID_FORMATS = ['wav', 'mp3']
+
+// Known models listed for help text
+const MODEL_LIST = Object.keys(MODEL_STEMS).join('|')
+
+const program = new Command()
+
+program
+  .name('stemit')
+  .description('Separate audio into stems, analyze BPM & key, mute/solo tracks')
+  .version('1.0.0')
+
+program
+  .command('split <input>')
+  .description('Split audio into stems (URL or local file)')
+  .option('--model <name>', `demucs model (${MODEL_LIST})`, 'htdemucs_ft')
+  .option('--out <dir>', 'output directory', './stemit-output')
+  .option('--mute <stem>', `mute a stem (${ALL_STEMS.join('|')})`)
+  .option('--solo <stem>', `keep only one stem (${ALL_STEMS.join('|')})`)
+  .option('--format <fmt>', `output format (${VALID_FORMATS.join('|')})`, 'wav')
+  .option('--no-analyze', 'skip BPM/key analysis')
+  .action(async (input, opts) => {
+    printBanner()
+
+    // Validate options
+    if (opts.mute && !ALL_STEMS.includes(opts.mute)) {
+      console.error(chalk.red(`Invalid --mute value. Choose from: ${ALL_STEMS.join(', ')}`))
+      process.exit(1)
+    }
+    if (opts.solo && !ALL_STEMS.includes(opts.solo)) {
+      console.error(chalk.red(`Invalid --solo value. Choose from: ${ALL_STEMS.join(', ')}`))
+      process.exit(1)
+    }
+    if (opts.mute && opts.solo) {
+      console.error(chalk.red('Cannot use --mute and --solo together.'))
+      process.exit(1)
+    }
+    if (!VALID_FORMATS.includes(opts.format)) {
+      console.error(chalk.red(`Invalid --format. Choose from: ${VALID_FORMATS.join(', ')}`))
+      process.exit(1)
+    }
+
+    // 1. Check system deps (auto-installs demucs into ~/.stemit/venv)
+    const setupSpinner = ora('Checking dependencies…').start()
+    let pythonPath
+    try {
+      ;({ pythonPath } = await checkDependencies())
+      setupSpinner.succeed('Dependencies OK')
+    } catch (err) {
+      setupSpinner.fail('Dependency check failed')
+      console.error(chalk.red(err.message))
+      process.exit(1)
+    }
+
+    // 2. Resolve input (download if URL)
+    const resolveSpinner = ora('Resolving input…').start()
+    let audioFile
+    try {
+      audioFile = await resolveInput(input, path.join(opts.out, '.tmp'))
+      resolveSpinner.succeed(`Input: ${path.basename(audioFile)}`)
+    } catch (err) {
+      resolveSpinner.fail('Failed to resolve input')
+      console.error(chalk.red(err.message))
+      process.exit(1)
+    }
+
+    // 3. Split stems via demucs
+    const modelStems = MODEL_STEMS[opts.model] ?? ['vocals', 'drums', 'bass', 'other']
+    console.log(
+      chalk.cyan(`\nSeparating stems…`) +
+      chalk.gray(` (model: ${opts.model} → ${modelStems.join(', ')})`)
+    )
+    const splitBar = createBar('chunk 1  ', 100)
+
+    let stemsDir, stemFiles
+    try {
+      const result = await splitStems(
+        audioFile,
+        opts.out,
+        opts.model,
+        (chunk, total, pct) => {
+          const label = total > 1 ? `chunk ${chunk}/${total}` : 'demucs    '
+          splitBar.update(pct, { label })
+        },
+        pythonPath
+      )
+      stemsDir = result.stemsDir
+      stemFiles = result.stems  // actual paths from the model, not hardcoded
+      splitBar.update(100)
+      stopAll()
+      console.log(chalk.green(`✔ Stems separated  (${stemFiles.length} tracks)`))
+    } catch (err) {
+      stopAll()
+      console.error(chalk.red(`\nStem separation failed: ${err.message}`))
+      process.exit(1)
+    }
+
+    // 4. Mix (mute/solo) if requested
+    let primaryFile = stemFiles.find((f) => f.endsWith('vocals.wav')) ?? stemFiles[0]
+
+    if (opts.mute || opts.solo) {
+      const mixSpinner = ora('Mixing stems…').start()
+      const mixLabel = opts.solo ? `solo-${opts.solo}` : `mute-${opts.mute}`
+      const mixOut = path.join(stemsDir, `${mixLabel}.wav`)
+      try {
+        await mixStems(stemsDir, mixOut, { mute: opts.mute, solo: opts.solo, availableStems: modelStems })
+        primaryFile = mixOut
+        mixSpinner.succeed(`Mixed output: ${path.basename(mixOut)}`)
+      } catch (err) {
+        mixSpinner.fail('Mixing failed')
+        console.error(chalk.red(err.message))
+        process.exit(1)
+      }
+    }
+
+    // 5. Convert to MP3 if requested
+    let finalFiles = [...stemFiles]
+
+    if (opts.format === 'mp3') {
+      const convertSpinner = ora('Converting to MP3…').start()
+      try {
+        const converted = await Promise.all(stemFiles.map((f) => wavToMp3(f)))
+        if (opts.mute || opts.solo) {
+          primaryFile = await wavToMp3(primaryFile)
+        }
+        finalFiles = converted
+        convertSpinner.succeed('Converted to MP3')
+      } catch (err) {
+        convertSpinner.fail('Conversion failed')
+        console.error(chalk.red(err.message))
+        process.exit(1)
+      }
+    }
+
+    // 6. Analyze BPM + key
+    let bpm, key
+    if (opts.analyze !== false) {
+      const analyzeSpinner = ora('Analyzing BPM & key…').start()
+      try {
+        const result = await analyzeAudio(primaryFile)
+        bpm = result.bpm
+        key = result.key
+        analyzeSpinner.succeed(`BPM: ${Math.round(bpm)}  Key: ${key}`)
+      } catch (err) {
+        analyzeSpinner.warn(`Analysis skipped: ${err.message}`)
+      }
+    }
+
+    // 7. Print summary
+    printSummary({
+      bpm,
+      key,
+      stems: finalFiles.map((f) => path.relative(process.cwd(), f)),
+      output: path.resolve(opts.out),
+    })
+  })
+
+program.parse()

package/src/lib/analyzer.js

@@ -0,0 +1,36 @@
+import fs from 'fs'
+import decode from 'audio-decode'
+
+// Init essentia WASM once at module load — avoids 1-2s penalty per call
+let _essentia = null
+
+async function getEssentia() {
+  if (_essentia) return _essentia
+  const { Essentia, EssentiaWASM } = await import('essentia.js')
+  _essentia = new Essentia(EssentiaWASM)
+  return _essentia
+}
+
+/**
+ * Analyze BPM and musical key of an audio file.
+ * @param {string} filePath - path to WAV or MP3
+ * @returns {Promise<{ bpm: number, key: string }>}
+ */
+export async function analyzeAudio(filePath) {
+  const essentia = await getEssentia()
+
+  const buffer = fs.readFileSync(filePath)
+  // audio-decode returns an AudioBuffer-like object
+  const audio = await decode(buffer)
+  // Use mono channel 0
+  const channelData = audio.getChannelData(0)
+  const data = essentia.arrayToVector(channelData)
+
+  const { bpm } = essentia.PercivalBpmEstimator(data)
+  const { key, scale } = essentia.KeyExtractor(data)
+
+  return {
+    bpm,
+    key: `${key} ${scale}`,
+  }
+}

package/src/lib/converter.js

@@ -0,0 +1,35 @@
+import { spawn } from 'child_process'
+import path from 'path'
+import fs from 'fs-extra'
+
+/**
+ * Convert a WAV file to MP3 using ffmpeg.
+ * @param {string} inputWav  - source WAV path
+ * @param {string} outputMp3 - destination MP3 path (defaults to same name with .mp3)
+ * @returns {Promise<string>} outputMp3 path
+ */
+export async function wavToMp3(inputWav, outputMp3) {
+  if (!outputMp3) {
+    outputMp3 = inputWav.replace(/\.wav$/i, '.mp3')
+  }
+  await fs.ensureDir(path.dirname(outputMp3))
+
+  return new Promise((resolve, reject) => {
+    const args = [
+      '-i', inputWav,
+      '-q:a', '0',
+      '-map', 'a',
+      '-y',
+      outputMp3,
+    ]
+
+    const proc = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] })
+
+    proc.on('error', (err) => reject(new Error(`ffmpeg error: ${err.message}`)))
+
+    proc.on('close', (code) => {
+      if (code !== 0) return reject(new Error(`ffmpeg exited with code ${code}`))
+      resolve(outputMp3)
+    })
+  })
+}

package/src/lib/downloader.js

@@ -0,0 +1,53 @@
+import youtubedl from 'youtube-dl-exec'
+import fs from 'fs-extra'
+import path from 'path'
+
+const URL_REGEX = /^https?:\/\//
+
+/**
+ * Resolve input to a local WAV file path.
+ * If input is a URL, download audio as WAV via yt-dlp.
+ * If input is a local path, use it directly.
+ *
+ * @param {string} input  - URL or local file path
+ * @param {string} tmpDir - directory to place downloaded files
+ * @returns {Promise<string>} resolved path to the audio file
+ */
+export async function resolveInput(input, tmpDir = 'tmp') {
+  await fs.ensureDir(tmpDir)
+
+  if (URL_REGEX.test(input)) {
+    return downloadUrl(input, tmpDir)
+  }
+
+  const resolved = path.resolve(input)
+  if (!fs.existsSync(resolved)) {
+    throw new Error(`File not found: ${resolved}`)
+  }
+  return resolved
+}
+
+async function downloadUrl(url, tmpDir) {
+  const outputTemplate = path.join(tmpDir, '%(title)s.%(ext)s')
+
+  await youtubedl(url, {
+    extractAudio: true,
+    audioFormat: 'wav',
+    output: outputTemplate,
+    noCheckCertificates: true,
+    noWarnings: true,
+  })
+
+  // Find the downloaded wav file
+  const files = (await fs.readdir(tmpDir)).filter((f) => f.endsWith('.wav'))
+  if (files.length === 0) {
+    throw new Error('Download succeeded but no WAV file found in tmp dir.')
+  }
+
+  // Return the most recently modified wav
+  const sorted = files
+    .map((f) => ({ name: f, mtime: fs.statSync(path.join(tmpDir, f)).mtimeMs }))
+    .sort((a, b) => b.mtime - a.mtime)
+
+  return path.resolve(path.join(tmpDir, sorted[0].name))
+}

package/src/lib/mixer.js

@@ -0,0 +1,63 @@
+import { spawn } from 'child_process'
+import path from 'path'
+import fs from 'fs-extra'
+
+const DEFAULT_STEMS = ['vocals', 'drums', 'bass', 'other']
+
+/**
+ * Mix stems according to mute/solo options.
+ *
+ * @param {string} stemsDir   - directory containing stem WAV files
+ * @param {string} outputFile - path for the mixed output WAV
+ * @param {{ mute?: string, solo?: string, availableStems?: string[] }} options
+ * @returns {Promise<string>} outputFile path
+ */
+export async function mixStems(stemsDir, outputFile, { mute, solo, availableStems } = {}) {
+  await fs.ensureDir(path.dirname(outputFile))
+
+  const stemSet = availableStems ?? DEFAULT_STEMS
+  let stemsToKeep
+
+  if (solo) {
+    stemsToKeep = [solo]
+  } else if (mute) {
+    stemsToKeep = stemSet.filter((s) => s !== mute)
+  } else {
+    stemsToKeep = [...stemSet]
+  }
+
+  const stemPaths = stemsToKeep.map((s) => path.join(stemsDir, `${s}.wav`))
+
+  for (const p of stemPaths) {
+    if (!fs.existsSync(p)) {
+      throw new Error(`Stem file not found: ${p}`)
+    }
+  }
+
+  if (stemPaths.length === 1) {
+    // Solo mode — simple copy, no ffmpeg amix needed
+    await fs.copy(stemPaths[0], outputFile)
+    return outputFile
+  }
+
+  return new Promise((resolve, reject) => {
+    const inputs = stemPaths.flatMap((p) => ['-i', p])
+    const filter = `amix=inputs=${stemPaths.length}:duration=longest:normalize=0`
+
+    const args = [
+      ...inputs,
+      '-filter_complex', filter,
+      '-y',
+      outputFile,
+    ]
+
+    const proc = spawn('ffmpeg', args, { stdio: ['ignore', 'ignore', 'pipe'] })
+
+    proc.on('error', (err) => reject(new Error(`ffmpeg error: ${err.message}`)))
+
+    proc.on('close', (code) => {
+      if (code !== 0) return reject(new Error(`ffmpeg exited with code ${code}`))
+      resolve(outputFile)
+    })
+  })
+}

package/src/lib/splitter.js

@@ -0,0 +1,100 @@
+import { spawn } from 'child_process'
+import path from 'path'
+import fs from 'fs'
+
+// Stems produced by each model. Falls back to 4-stem list for unknown models.
+export const MODEL_STEMS = {
+  htdemucs:      ['vocals', 'drums', 'bass', 'other'],
+  htdemucs_ft:   ['vocals', 'drums', 'bass', 'other'],
+  htdemucs_6s:   ['vocals', 'drums', 'bass', 'guitar', 'piano', 'other'],
+  mdx:           ['vocals', 'drums', 'bass', 'other'],
+  mdx_extra:     ['vocals', 'drums', 'bass', 'other'],
+  mdx_extra_q:   ['vocals', 'drums', 'bass', 'other'],
+}
+
+const DEFAULT_STEMS = ['vocals', 'drums', 'bass', 'other']
+
+// All possible stems across all models (for CLI validation)
+export const ALL_STEMS = ['vocals', 'drums', 'bass', 'guitar', 'piano', 'other']
+
+/**
+ * Run demucs to separate stems from inputFile.
+ * @param {string} inputFile    - path to WAV/MP3
+ * @param {string} outputDir    - root output directory
+ * @param {string} model        - demucs model name (e.g. 'htdemucs_ft')
+ * @param {function} onProgress - called with (chunk: number, total: number, pct: number)
+ * @param {string} pythonPath   - path to python binary (defaults to system python3)
+ * @returns {Promise<{stemsDir: string, stems: string[]}>}
+ */
+export function splitStems(
+  inputFile,
+  outputDir,
+  model = 'htdemucs_ft',
+  onProgress = () => {},
+  pythonPath = 'python3'
+) {
+  return new Promise((resolve, reject) => {
+    const args = ['-m', 'demucs', '-n', model, '--out', outputDir, inputFile]
+    const proc = spawn(pythonPath, args, {
+      env: { ...process.env, TORCHAUDIO_BACKEND: 'soundfile' },
+    })
+
+    const stderrLines = []
+    let chunkIndex = 0
+    let totalChunks = 0
+
+    proc.stderr.on('data', (buf) => {
+      const text = buf.toString()
+      stderrLines.push(text)
+
+      // Detect "Separated track … (N chunks)" to know total segments
+      // demucs logs e.g.: "Separated track song (4 chunks)"
+      const totalMatch = text.match(/\((\d+)\s+chunks?\)/i)
+      if (totalMatch) {
+        totalChunks = parseInt(totalMatch[1], 10)
+      }
+
+      // Each new tqdm bar starting from 0% signals a new chunk
+      const zeroMatch = text.match(/^\s*0%\|/)
+      if (zeroMatch && totalChunks > 0) {
+        chunkIndex++
+      }
+
+      // Parse percentage from tqdm-style output:  87%|████...
+      const pctMatch = text.match(/\b(\d{1,3})%\|/)
+      if (pctMatch) {
+        const pct = parseInt(pctMatch[1], 10)
+        const effectiveChunk = Math.max(chunkIndex, 1)
+        const effectiveTotal = Math.max(totalChunks, 1)
+        onProgress(effectiveChunk, effectiveTotal, pct)
+      }
+    })
+
+    proc.on('error', (err) => reject(new Error(`Failed to start demucs: ${err.message}`)))
+
+    proc.on('close', (code) => {
+      if (code !== 0) {
+        const detail = stderrLines.join('').trim().split('\n').slice(-10).join('\n')
+        return reject(
+          new Error(`demucs exited with code ${code}\n\ndemucs output:\n${detail}`)
+        )
+      }
+
+      // Resolve stems directory: <outputDir>/<model>/<songname>/
+      const songName = path.basename(inputFile, path.extname(inputFile))
+      const stemsDir = path.join(outputDir, model, songName)
+
+      if (!fs.existsSync(stemsDir)) {
+        return reject(new Error(`Expected stems dir not found: ${stemsDir}`))
+      }
+
+      // Use the known stem list for this model, or discover from actual files
+      const expectedStems = MODEL_STEMS[model] ?? DEFAULT_STEMS
+      const stems = expectedStems
+        .map((s) => path.join(stemsDir, `${s}.wav`))
+        .filter((p) => fs.existsSync(p))
+      resolve({ stemsDir, stems })
+    })
+  })
+}
+

package/src/ui/banner.js

@@ -0,0 +1,8 @@
+import figlet from 'figlet'
+import chalk from 'chalk'
+
+export function printBanner() {
+  const text = figlet.textSync('stemit', { font: 'Standard' })
+  console.log(chalk.cyan(text))
+  console.log(chalk.gray('  stem separator · BPM · key · mix\n'))
+}

package/src/ui/progress.js

@@ -0,0 +1,37 @@
+import cliProgress from 'cli-progress'
+import chalk from 'chalk'
+
+let multibar = null
+
+export function getMultibar() {
+  if (!multibar) {
+    multibar = new cliProgress.MultiBar(
+      {
+        clearOnComplete: false,
+        hideCursor: true,
+        format:
+          chalk.cyan('{bar}') +
+          ' {percentage}%  {label}',
+      },
+      cliProgress.Presets.shades_classic
+    )
+  }
+  return multibar
+}
+
+/**
+ * Create a new progress bar.
+ * @param {string} label
+ * @param {number} total
+ */
+export function createBar(label, total = 100) {
+  const mb = getMultibar()
+  return mb.create(total, 0, { label })
+}
+
+export function stopAll() {
+  if (multibar) {
+    multibar.stop()
+    multibar = null
+  }
+}

package/src/ui/summary.js

@@ -0,0 +1,38 @@
+import boxen from 'boxen'
+import chalk from 'chalk'
+
+/**
+ * Print the final summary panel.
+ * @param {{ bpm?: number, key?: string, stems: string[], output: string }} result
+ */
+export function printSummary({ bpm, key, stems, output }) {
+  const lines = [
+    chalk.bold.cyan('stemit — done!'),
+    '',
+  ]
+
+  if (bpm !== undefined) {
+    lines.push(`${chalk.gray('BPM  ')} ${chalk.yellow(Math.round(bpm))}`)
+  }
+  if (key) {
+    lines.push(`${chalk.gray('Key  ')} ${chalk.yellow(key)}`)
+  }
+
+  lines.push('')
+  lines.push(chalk.gray('Stems:'))
+  for (const s of stems) {
+    lines.push(`  ${chalk.green('✔')} ${s}`)
+  }
+
+  lines.push('')
+  lines.push(`${chalk.gray('Output dir')}  ${chalk.white(output)}`)
+
+  console.log(
+    boxen(lines.join('\n'), {
+      padding: 1,
+      margin: 1,
+      borderStyle: 'round',
+      borderColor: 'cyan',
+    })
+  )
+}