Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/cocreating/4StemPlayer/llms.txt

Use this file to discover all available pages before exploring further.

4Stem Band Player is a static SvelteKit app with no backend, so the entire development workflow runs locally. The steps below take you from a fresh clone to a running dev server, then through type checking, testing, and a production build.
1

Install prerequisites

You need the following tools installed on your system before starting:
  • Node.js 18 or later — required to run Vite and the SvelteKit build
  • git — to clone the repository
  • ffmpeg (optional, but required for npm run songs:peaks) — used by the peak-generation script to extract waveform data from MP3 files
Verify your Node version:
node --version
# v18.0.0 or higher
2

Clone the repository

git clone https://github.com/cocreating/4StemPlayer.git && cd 4StemPlayer
3

Install dependencies

npm install
This installs SvelteKit, Svelte 5, Vite, TypeScript, WaveSurfer.js, the SoundTouch AudioWorklet package, Vitest, and all development tooling.
4

Start the development server

npm run dev
Open http://localhost:5173 in your browser. The dev server binds to 0.0.0.0 so it is also reachable from other devices on your local network.
  VITE v8.x.x  ready in Xms

  ➜  Local:   http://localhost:5173/
  ➜  Network: http://<your-ip>:5173/
  ➜  press h + enter to show help
Both npm run dev and npm run preview bind to 0.0.0.0, making the server accessible on your local network — useful for testing on a physical phone.
5

Explore the demo songs

The five bundled demo songs are already in static/songs/ with pre-generated waveform peak files and are ready to play immediately:
FolderTitleArtist
BambolaLa bambolaPatty Pravo
GloryBoxGlory BoxPortishead
IkesRap2Ike’s Rap 2Isaac Hayes
SendHLTMeSend His Love to MePJ Harvey
YouMightThinkYou Might ThinkThe Cars
Select a song from the dropdown in the header. The app fetches and decodes all stems, then displays waveforms for each one.
Press Space anywhere in the app (outside a text input) to toggle play/pause — the quickest way to start and stop playback without reaching for the mouse.
6

Regenerate peaks and manifest (optional)

If you add or modify song files, run the preparation script to validate folders, generate any missing waveform peak files, and rebuild static/songs/manifest.json:
npm run songs:prepare
To force-regenerate every peak file even if the source MP3 has not changed:
npm run songs:prepare -- --force-peaks
npm run songs:peaks (called internally by songs:prepare) requires ffmpeg on your PATH. If ffmpeg is not installed, peak generation will fail. Install it via your system package manager (brew install ffmpeg, apt install ffmpeg, etc.) before running this command.
7

Run the type checker

npm run check
This runs svelte-kit sync followed by svelte-check against tsconfig.json. The project currently reports zero Svelte errors and zero warnings.
8

Run the test suite

npm test
Vitest runs 17 test files covering the audio engine, song scripts, metadata formatting, keyboard shortcut guard, and more — 100 tests in total, all passing.
9

Build for production

npm run build
SvelteKit uses @sveltejs/adapter-static (configured in svelte.config.js) to prerender every route to static HTML and emit all client assets. The build writes the deployable output to public/, and also copies static/songs/ content into public/songs/ so the artifact is fully self-contained.
10

Preview the production build

npm run preview
Starts a local static file server at http://localhost:4173 serving the public/ output directory, with the same 0.0.0.0 binding as the dev server.

​
All npm Scripts

ScriptDescription
npm run devStart the Vite dev server (binds to 0.0.0.0, port 5173)
npm run buildCompile and write the static site to public/
npm run previewServe the production build locally (binds to 0.0.0.0, port 4173)
npm run checkRun svelte-kit sync and svelte-check for type and template errors
npm testRun the full Vitest test suite (17 files, 100 tests)
npm run test:unitAlias for npm test
npm run songs:prepareValidate songs, generate missing peaks, regenerate the manifest
npm run songs:releaseRun songs:prepare, then check, test, and build
npm run songs:manifestRegenerate static/songs/manifest.json only
npm run songs:validateValidate song folder completeness without making changes
npm run songs:peaksGenerate waveform peak JSON files (requires ffmpeg on PATH)

Build docs developers (and LLMs) love

Get started for freeTalk to us