CrateMind is a local TypeScript/Node.js-based vibe sorter and audio router that leverages Gemini LLM to automatically categorize and sort your music files.
It runs directly in your terminal using a beautiful React-based TUI (powered by Ink 4 & Zustand), making it the perfect tool for DJs and music collectors to curate their libraries with zero manual friction.
A built-in RAG (Retrieval-Augmented Generation) memory layer accumulates every past routing decision and injects few-shot examples into each new Gemini prompt — so the more tracks you sort, the smarter and more consistent the vibe classification becomes.
CrateMind operates on a user-first, semi-automatic principle: the system suggests, the user decides. Every action touching your collection requires explicit confirmation.
Need to curate away from your desk? CrateMind Pocket extends the workspace to your
iPhone via a zero-Cloud-AI offline PWA (pocket-web/) and local macOS Wi-Fi
HTTP bridge (src/services/pocket/), caching up to 30 compressed AAC track
previews in IndexedDB and syncing verified crate decisions back over local Wi-Fi.
During the initial design phase, the system performed raw, un-cached Gemini API calls for every scanned track, resulting in significant token consumption and higher API request overhead during heavy catalog ingestions.
To eliminate redundant overhead, we implemented a multi-layered optimization strategy:
vibes.sqlite, persisting permanent profiles to local
track_intelligence.
yt_playlist_items(artist, title) and token overlap fuzzy
matching (≥ 0.85 Jaccard similarity) before triggering network requests.
m.db, bypassing LLM processing entirely for
previously sorted tracks.
Following these optimizations, active sorting runs achieved a 90–95% reduction in daily token consumption and API request costs, demonstrating that even highly advanced, LLM-based categorization can run at production scale with minimal resources.
Fetch incoming unorganized tracks over local Wi-Fi (no Cloud AI).
Click the Sorter, Queue (30), Inspector, and Sync tabs in the phone frame to preview all four Stitch mobile views, or tap crate pads in the 3×7 matrix to toggle multi-select glow.
INTR/DRP/BRK/OUT LED bar, 450ms long-press
1-tap route, and swipe-left skip.
All,
Pending, Tagged, Skipped) and sticky Mac commit
action.
navigator.storage.persist()), JSON export, and Clear Decisions Cache.
HTMLAudioElement with
navigator.mediaSession lockscreen controls.
BATCH_SIZE before starting analysis, while ignoring single leftover tracks
on boot scan.
file_metadata_cache table in cratemind.db to speed up
subsequent bootstrap folder crawls.
m.db) to retrieve playlists, folder paths, BPM, and keys. Uses
process-lifetime caching for high-performance library lookups.
vibes.sqlite). Preloads 57 curated vibes across 6 categories, measured
acoustic band levels (sub-bass, mid, high, onset density), 16-bin structural energy
shapes, and phase cues for zero-latency batch classification.
rag_examples table in cratemind.db and builds context strings
for LLM prompts.
llm_cache, api_stats) in
cratemind.db.
0.80 to filter out noisy, low-quality matches.
Incoming folder for analysis.
src/services/sync/: rsyncRunner (line-buffered stdout
telemetry, dry-run discovery, audio counting), archiveManager (in-memory
audio file indexing, smart track relocation across reorganized crates, and active track
recovery from Removed from SD/), and dbRewriter (Engine DJ
SQLite database absolute path updates via better-sqlite3).
useGlobalHotkeys) blocks conflicting keystrokes whenever any heavy
background task is running, while service-level pre-flight guards and watcher locks
(TrackWatcher) automatically defer pending batches and ensure zero resource
contention.
src/services/pocket/ &
pocket-web/):
Lightweight node:http Wi-Fi bridge (port 8080) serving a
compiled Vite/React/Tailwind offline PWA from dist/pocket-web/. Provides
GET /api/health, GET /api/batch (up to 30 tracks),
GET /api/audio/:id (FFmpeg AAC preview cache with
HTTP 206 Partial Content byte-range streaming), and
POST /api/commit (409 mutual exclusion lock, path traversal protection,
safe manual override, and RAG cache invalidation). Computes hints strictly via local
SQLite (rag_examples, 512-dim CLAP embeddings,
yt_playlist_items) with zero Cloud AI calls.
INTR/DRP/BRK/OUT energy waveform bar, and neon RAG XX% /
YT MATCH badges.
Nature,
Party, Cosmic,
Genres), hold any pad for 450ms (long-press with
haptic feedback) for instant 1-tap routing, or swipe left to skip tracks.
Auto-play starts the next track automatically upon routing or skipping.
00:00 once
to allow final decision, then stops completely. Reuses a single persistent
HTMLAudioElement with navigator.mediaSession lockscreen
controls, persisting batches, decisions, and audio blobs offline via idb.
VibeSorterView (pad matrix),
BatchQueueView (filterable 30-track queue),
InspectorBottomSheet (YT Scout and local CLAP RAG details), and
SyncBridgeView (Wi-Fi pull/commit, storage meter, Clear Decisions Cache,
JSON export).
npm run build then
npm run pocket (or npm run pocket:sandbox), open the printed
LAN URL on iPhone Safari, and tap Share → Add to Home Screen. Optional
overrides: POCKET_PORT (default 8080) and
CRATEMIND_DB_PATH (test DB isolation).
| Method | Endpoint | Query / Headers | Status Codes & Behavior |
|---|---|---|---|
GET |
/api/health |
— |
200 OK: Bridge uptime, incomingCount,
ragCount, isBusy, activeTask.
|
GET |
/api/batch |
?limit=30 (1–30) |
200 OK: Up to 30 tracks enriched with ID3, Vibes 4-band/energy curves,
local SQLite RAG hints, and YT Scout neighbors.
|
GET |
/api/audio/:id |
:id = base64url(filename)Range: bytes=start-endAccept-Ranges: bytes, Content-Range,
Content-Length
|
206 Partial Content (with Range) or
200 OK serving FFmpeg 256kbps AAC .m4a previews
(original-format fallback); 400 traversal, 404 missing,
416 bad range.
|
POST |
/api/commit |
JSON { batchId, decisions[] } |
200 OK: Routes tagged files, moves skips to
Sorted/skipped/, leaves pending/empty untouched in
Incoming/, invalidates RAG cache. Returns 400 invalid
crate/JSON, 409 Conflict if desktop task busy, 413 > 2
MB.
|
npm run build # Compile Node backend (dist/) + Vite PWA bundle (dist/pocket-web/) npm run build:node # Compile only Node TypeScript backend npm run build:pocket # Build only Vite PWA client bundle npm run pocket # Start Mac Wi-Fi HTTP bridge daemon (port 8080 or POCKET_PORT) npm run pocket:sandbox # Boot isolated sandbox with tagged mock WAVs, 21 crates & LAN IP banner npm test # Run full 4-tier Vitest suite (backend, client, 390x844 E2E) npm run test:pocket # Run Pocket backend unit & HTTP 206/409 integration tests npm run test:client # Run Pocket PWA IndexedDB, audio engine & UI tests npm run test:e2e # Run headless Chrome 390x844 mobile viewport E2E tests
./Incoming.BATCH_SIZE chunk of tracks before
starting analysis, optimizing Gemini API limits. Supports a dedicated interactive
Download-Only Mode (prompted upon starting sync) to fetch tracks into the
Incoming directory without spawning any LLM or analysis tasks. Includes automatic mix
protection to skip long DJ sets/podcasts based on duration limits, and a snippet filter
to skip files under a minimum size threshold (10 MB for lossless, 3 MB for lossy).
[S] Sync to
Collection. When both the master SD card and the target backup drive are mounted,
displays an interactive dual prompt: [Y] Sorted → SD or
[D] Mirror SD → EngineDJ Drive. Performs smart track relocation for
reorganized crates (e.g. into Atmosphere/ subcrates) via instant target
disk filesystem operations (avoiding redundant USB re-transfers), safely recovers any
active tracks previously archived in Removed from SD/, and archives
genuinely deleted tracks preserving folder structure. Automatically rewrites absolute
paths in target Engine DJ databases (m.db and hm.db) to match
the target drive volume prefix. Features a structured 4-stage pipeline ([1/4] Checking obsolete & relocated tracks, [2/4] Dry-run discovery, [3/4] Music Collection mirror,
[4/4] Engine Library & DB rewrite) with real-time ASCII progress
telemetry (SyncProgressBanner) powered by targeted file transfers
(--files-from) and --progress unbuffered streaming, displaying
live file counters, percentages, and active track filenames without 64 KB block
buffering lag.
BottomBar dynamically transitions into an amber status banner:
[Drive Mirror in progress...] Hotkeys locked | [Q] Exit Sorter,
[Vibe Indexing in progress...] Hotkeys locked | [Q] Exit Sorter, or
[Telegram Download in progress...] Hotkeys locked | [Q] Exit Sorter.
Attempting to trigger any background task while track analysis is actively listening or
classifying tracks prompts the user to pause first.
Incoming count (updated instantly via chokidar events), plus global
lifetime stats from rag_examples: Sorted total, AI hits, Manual fixes, and
AI accuracy rate calculated over actually classified tracks (auto ÷ (auto + manual)).
gemini-3.5-flash-lite with native responseSchema structured
output validation, ensuring deterministic multi-track batch routing across 21 custom
atmospheric folders without hallucinated crates.
vibes.sqlite to ingest 57 curated vibes across 6 categories, spectral
acoustics (sub-bass, mid, high, onset density), and 16-bin structural energy curves in 3
fast batch queries. Persists these profiles locally in the
track_intelligence table in cratemind.db.
source: 'manual') or files physically present in the
collection (source: 'scan'/'engine-dj'), ensuring automatic LLM
classifications from previous runs that were never confirmed do not bypass re-analysis
if they return to the Incoming folder. Features
unlimited RAG database capacity to retain all confirmed track vibes forever
without rotation or eviction.
m.db). Features:
m.db playlist associations or directory folder names, auto-routing them
directly without calling the Gemini API.
aubio and
keyfinder-cli) when metadata tags are missing or corrupt. Newly estimated
or database-matched BPM and key values are automatically written back into the source
track's metadata (ID3v2 for MP3, Vorbis Comments for FLAC) using FFmpeg before routing.
Bypassed completely if cached in the local database or if already matched inside Engine
DJ DB.
[Y/n] confirmation.
Sorted/skipped folder
to keep the incoming queue clean.
ffplay with precise seeking support..env toggle)
to test base SQLite DB, file watchers, Gemini classifications, and physical routing
without real dependencies.
.env) that allows all
background vector consensus, YouTube scouting, and Gemini classification pipelines to
run fully, but forces every single track into the Manual Override TUI with
recommendations pre-selected so you can review and approve every routing.
cratemind.log to cratemind.old.log when it
exceeds 5MB.
yt-dlp directly into the Incoming folder, and run the RAG-vibe
classification pipeline.
vibes.sqlite database for unified
DJ library management.