grep for sound. describe what you hear, find it in your sample library.
you have 50K samples across Splice packs, freesound downloads, and random folders. right now you search by filename. good luck finding "dark atmospheric pad with slow attack" when the file is called Pad_07_Cm.wav.
this tool indexes every sample you own, converts each one into a 512-dimension embedding that captures what it actually sounds like, and lets you search by description. type what you hear in your head, get the closest matches from your own library. or drop in a reference file and find everything that sounds like it.
WAVS and Splice have similar features. but they only search their own catalog, they're closed source, and they require internet. this searches YOUR local packs, works offline, and you own the index.
on top of sample search: 7 AI agents that generate MIDI, separate stems, lay out tracks in Ableton, mix. you describe what you want, they build it.
$ soundgrep search "punchy 808 kick with long tail"
┌─────┬──────────────────────────────────┬───────┬────────┬──────────┐
│ # │ File │ BPM │ Key │ Score │
├─────┼──────────────────────────────────┼───────┼────────┼──────────┤
│ 1 │ 808_deep_sub_kick_01.wav │ - │ E1 │ 0.94 │
│ 2 │ tr808_kick_long_decay.wav │ - │ F1 │ 0.91 │
│ 3 │ analog_808_boom.wav │ - │ D#1 │ 0.89 │
└─────┴──────────────────────────────────┴───────┴────────┴──────────┘
- semantic sample search — find samples by describing the sound, not the filename. CLAP embeddings + FAISS. text-to-audio and audio-to-audio similarity. also searches Freesound (500K+ CC sounds) when local results are sparse.
- voice to MIDI — hum or sing a melody, get a MIDI file. basic-pitch with librosa pYIN fallback.
- MIDI generation — melodies, chord progressions, basslines, drum patterns. 16 scales, 6 drum styles. music21 for theory-aware harmony and voice leading.
- stem separation — split any track into vocals, drums, bass, other. Demucs on Apple Silicon MPS.
- audio effects — reverb, delay, chorus, compression, EQ, distortion. Spotify's pedalboard. chainable.
- auto-mastering — reference-based mastering via matchering. match EQ, loudness, stereo width to any reference track.
- chord detection — detect chords from any audio file. timestamped chord labels.
- song structure analysis — identify verse, chorus, bridge, intro, outro sections automatically.
- vocal transcription — extract lyrics/speech from audio via Whisper.
- full song generation — ACE-Step 1.5 for full songs with vocals + lyrics. MusicGen fallback for instrumental loops.
- Ableton control — create tracks, add clips, set tempo, arrange, mix. all via OSC. optional.
- audio analysis — BPM, key detection (Krumhansl-Schmuckler), spectral analysis, onset detection.
- agent orchestration — tell it what you want. conductor decomposes into tasks, routes to specialists. all reasoning via Claude.
- MCP server — use soundgrep from Claude Desktop or any MCP client. 17 tools exposed.
- Freesound — online sample search (500K+ Creative Commons sounds). needs API key.
- ACE-Step — full song generation with vocals. runs as separate server.
- REST API + WebSocket — FastAPI on port 7777. real-time task updates.
- web dashboard — monitor agents, browse samples, submit directives.
| agent | what it does |
|---|---|
| conductor | decomposes your directive into sub-tasks, assigns to specialists |
| sound scout | searches samples by description, audio similarity, or Freesound |
| melodist | generates MIDI — melodies, chords, drums, basslines. music21 theory engine for harmony |
| alchemist | stem separation, effects, voice-to-MIDI, chord detection, mastering, transcription |
| arranger | controls Ableton, analyzes song structure (verse/chorus/bridge) |
| mix engineer | levels, EQ, compression, panning, spectral analysis, auto-mastering |
| generator | ACE-Step full songs with vocals, MusicGen instrumental loops |
all LLM reasoning runs through claude -p using your Claude Max subscription. no API keys needed.
# clone
git clone https://github.com/fnsmdehip/soundgrep.git
cd soundgrep
# install (python 3.11+)
pip install -e ".[full]"
# copy env and edit paths
cp .env.example .env
# index your sample library
soundgrep index ~/Music/Samples
# start the daemon
soundgrep start
# search samples by sound
soundgrep search "warm analog pad, slow attack, dark"
# generate a drum pattern
soundgrep generate drums --style trap_hat --bars 4 --tempo 140
# hum a melody, get MIDI
soundgrep hum --duration 10
# tell it what to build
soundgrep directive "find atmospheric pads and ethereal vocals, generate a chord progression in D minor at 75 bpm, arrange an 8-bar intro"
# generate a full song
soundgrep generate song "ambient downtempo, 80 bpm, lots of reverb and space" --duration 30# minimal — sample search + analysis + MIDI generation. ~500MB.
pip install -e .
# full — adds CLAP, Demucs, MusicGen, basic-pitch. ~4GB model downloads on first run.
pip install -e ".[full]"
# pre-download models so first run isn't slow
python scripts/install_models.py# 1. you have a vague idea. search for the foundation.
soundgrep search "dusty vinyl drum break, 90 bpm"
# → finds 3 breaks in your Splice packs you forgot you had
# 2. hum the melody stuck in your head
soundgrep hum --duration 8
# → converts your humming to a MIDI file
# 3. tell the agents to build it
soundgrep directive "take the drum break at /samples/dusty_break_03.wav,
use my hummed melody, generate a bassline in F minor,
add tape saturation and lo-fi reverb,
arrange as 8-bar loop in Ableton"
# → conductor assigns tasks to sound scout, melodist, alchemist, arranger
# → you get a session in Ableton with everything laid out
# 4. iterate. change one thing.
soundgrep directive "replace the snare with something crunchier"
# → sound scout finds alternatives, arranger swaps it inyou (CLI / dashboard / Claude Desktop MCP)
→ conductor agent
→ sound scout (CLAP + FAISS local search, Freesound online search)
→ melodist (MIDI generation, music21 harmony)
→ alchemist (Demucs stems, pedalboard FX, voice-to-MIDI, mastering, chords, transcription)
→ arranger (Ableton OSC control, structure analysis)
→ mix engineer (spectral analysis, leveling, auto-mastering)
→ generator (ACE-Step full songs, MusicGen loops)
→ SQLite + FAISS (sample index, embeddings, task state)
→ Ableton Live (optional, via AbletonOSC)
→ Freesound (optional, online sample search)
→ ACE-Step server (optional, full song generation)
- python 3.11+
- macOS (tested on Apple Silicon M1 Max), Linux should work
- Ableton Live 11+ with AbletonOSC Max for Live device (optional — sample search, generation, analysis all work without it)
- Claude CLI with Max subscription (for agent reasoning via
claude -p) - ffmpeg (optional, for voice recording fallback)
add to your Claude Desktop config (claude_desktop_config.json):
{
"mcpServers": {
"soundgrep": {
"command": "python",
"args": ["-m", "soundgrep.bridges.mcp_server"]
}
}
}then ask Claude: "search my samples for a dark atmospheric pad" or "generate a drum pattern in the style of trap at 140 bpm"
- index — soundgrep scans your sample directories, analyzes each file (BPM, key, energy, duration), generates a 512-dim CLAP embedding, stores everything in SQLite + FAISS
- text search — your query ("punchy 808 kick") gets embedded with CLAP's text encoder into the same 512-dim space. FAISS finds the nearest samples by cosine similarity.
- audio search — drop in a reference audio file. CLAP embeds it. FAISS finds similar-sounding samples in your library. "find me 10 sounds like this one."
- fallback — if CLAP isn't installed, falls back to spectral feature extraction (MFCCs + chroma + spectral contrast). less accurate but still useful.
works on any sample format: WAV, MP3, FLAC, AIF, OGG. indexing 50K samples takes about 2 hours on M1 Max. after that, search is instant.
AbletonMCP controls Ableton through Claude. Magenta Studio does ML-based MIDI inside Live. Suno generates full songs. WAVS and Splice have AI sample browsers.
none of them search YOUR local sample library by description. none of them chain sample search + MIDI generation + stem separation + arrangement + mixing into one agentic workflow. soundgrep does both.
| component | library |
|---|---|
| audio embeddings | LAION CLAP |
| vector search | FAISS |
| audio analysis | librosa |
| stem separation | Demucs |
| audio effects | pedalboard (Spotify) |
| audio-to-MIDI | basic-pitch (Spotify) |
| song generation | ACE-Step 1.5 + MusicGen |
| auto-mastering | matchering |
| chord detection | autochord |
| structure analysis | allin1 |
| vocal transcription | Whisper |
| music theory | music21 |
| online samples | Freesound API |
| MIDI I/O | mido + python-rtmidi |
| Ableton control | AbletonOSC |
| API server | FastAPI |
| CLI | Typer + Rich |
| LLM reasoning | Claude via claude -p (Max subscription) |
soundgrep/
├── soundgrep/
│ ├── agents/ # 7 specialist agents
│ ├── api/ # FastAPI server + WebSocket
│ ├── bridges/ # Ableton OSC, MIDI I/O, MCP server
│ ├── cli/ # Typer CLI
│ ├── db/ # SQLite + FAISS vector index
│ ├── intelligence/ # audio analysis, CLAP, MIDI gen, Demucs, MusicGen
│ ├── orchestrator/ # daemon, task queue, event bus, Claude spawner
│ └── voice/ # mic recording, humming-to-MIDI
├── dashboard/ # React web UI
├── scripts/ # setup, indexing, model download
└── tests/
MIT