GitHub - deeptechhouse/Dr_KitMaker: Python CLI/GUI tool that analyzes audio samples, classifies them into drum kit slots and kit types, builds organized drum kits, and exports in DAW-ready formats.

Branches Tags
Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
_claudeMD_archive		_claudeMD_archive
src		src
tests		tests
.env.example		.env.example
.gitignore		.gitignore
.python-version		.python-version
CHANGELOG.html		CHANGELOG.html
DR_KITMAKER_BUILD_PROMPTS.html		DR_KITMAKER_BUILD_PROMPTS.html
NAVIGATION.md		NAVIGATION.md
README.html		README.html
config.yaml		config.yaml
dir_index.html		dir_index.html
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
Repository files navigation

<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Dr KitMaker — README</title>
<style>
  :root {
    --bg: #0d1117;
    --surface: #161b22;
    --border: #30363d;
    --text: #e6edf3;
    --muted: #8b949e;
    --accent: #58a6ff;
    --green: #3fb950;
    --purple: #d2a8ff;
    --orange: #f0883e;
    --red: #f85149;
    --code-bg: #0d1117;
  }
  * { box-sizing: border-box; margin: 0; padding: 0; }
  body {
    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-serif;
    background: var(--bg);
    color: var(--text);
    line-height: 1.6;
    padding: 2rem;
    max-width: 960px;
    margin: 0 auto;
  }
  h1 { font-size: 2.2rem; margin-bottom: 0.25rem; color: var(--accent); }
  h2 { font-size: 1.5rem; margin: 2.5rem 0 1rem; padding-bottom: 0.5rem; border-bottom: 1px solid var(--border); color: var(--text); }
  h3 { font-size: 1.15rem; margin: 1.5rem 0 0.5rem; color: var(--purple); }
  p { color: var(--muted); margin-bottom: 0.75rem; }
  a { color: var(--accent); text-decoration: none; }
  a:hover { text-decoration: underline; }
  ul, ol { color: var(--muted); padding-left: 1.5rem; margin-bottom: 0.75rem; }
  li { margin-bottom: 0.3rem; }
  code {
    font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
    background: var(--surface);
    padding: 0.15rem 0.4rem;
    border-radius: 4px;
    font-size: 0.88rem;
    color: var(--orange);
  }
  pre {
    background: var(--code-bg);
    border: 1px solid var(--border);
    border-radius: 6px;
    padding: 1rem;
    overflow-x: auto;
    font-family: 'SF Mono', 'Fira Code', 'Cascadia Code', monospace;
    font-size: 0.85rem;
    line-height: 1.5;
    color: var(--text);
    margin-bottom: 1rem;
  }
  table { width: 100%; border-collapse: collapse; margin: 1rem 0; font-size: 0.88rem; }
  th, td { padding: 0.55rem 0.8rem; border: 1px solid var(--border); text-align: left; }
  th { background: var(--surface); color: var(--accent); font-weight: 600; }
  td { color: var(--muted); }
  .badge {
    display: inline-block;
    padding: 0.2rem 0.6rem;
    border-radius: 4px;
    font-size: 0.75rem;
    font-weight: 600;
    margin-right: 0.4rem;
  }
  .badge-green { background: #1f3a2a; color: var(--green); }
  .badge-blue { background: #1a2a4a; color: var(--accent); }
  .badge-purple { background: #2a1a3a; color: var(--purple); }
  .badge-orange { background: #2a2010; color: var(--orange); }
  .subtitle { color: var(--muted); font-size: 1.1rem; margin-bottom: 1.5rem; }
  .arch-diagram {
    background: var(--surface);
    border: 1px solid var(--border);
    border-radius: 8px;
    padding: 1.5rem;
    font-family: 'SF Mono', monospace;
    font-size: 0.82rem;
    line-height: 1.6;
    color: var(--muted);
    white-space: pre;
    overflow-x: auto;
    margin: 1rem 0;
  }
  .pad-grid {
    display: grid;
    grid-template-columns: repeat(4, 1fr);
    gap: 0.5rem;
    max-width: 400px;
    margin: 1rem 0;
  }
  .pad {
    background: var(--surface);
    border: 1px solid var(--border);
    border-radius: 6px;
    padding: 0.6rem;
    text-align: center;
    font-size: 0.8rem;
    color: var(--accent);
    font-weight: 600;
  }
  .pad .midi { font-size: 0.7rem; color: var(--muted); font-weight: 400; }
</style>
</head>
<body>

<h1>Dr KitMaker</h1>
<p class="subtitle">Analyze drum samples. Build kits. Export to your DAW.</p>

<span class="badge badge-green">v0.1.0</span>
<span class="badge badge-blue">Python 3.12+</span>
<span class="badge badge-purple">MIT License</span>
<span class="badge badge-orange">CLI + GUI</span>

<h2>What It Does</h2>
<p>Dr KitMaker is a Python CLI/GUI tool that takes a folder of unorganized drum and percussion one-shots, analyzes them using signal processing and optional LLM classification, assigns each sample to a standard 8-slot drum kit layout, and exports ready-to-use kits in multiple DAW-compatible formats.</p>
<p>Built for producers, sound designers, and sample library curators who want to turn messy sample folders into organized, mapped drum kits in seconds.</p>

<h2>Architecture</h2>
<div class="arch-diagram">
Audio Files
    |
    v
<span style="color:var(--accent)">[AudioLoader]</span> ---- load WAV/AIFF/MP3/FLAC via librosa
    |
    v
<span style="color:var(--orange)">[DurationFilter]</span> -- exclude samples > 3s (configurable)
    |
    v
<span style="color:var(--green)">[FeatureCache]</span> ---- compute spectral/temporal features (LRU cached)
    |
    v
<span style="color:var(--purple)">[PercussiveAnalyzer]</span> -- classify into 8 kit slots via signal rules
    |
    v
<span style="color:var(--red)">[KitClassifier]</span> --- assign kit type (808, jazz, metal, etc.)
    |                   Rule-based | LLM | Hybrid
    v
<span style="color:var(--accent)">[KitBuilder]</span> ----- group by kit type, assign best samples per slot
    |
    v
<span style="color:var(--green)">[Exporters]</span> ----- WAV folder + manifest.json | SF2 | SFZ
</div>

<h2>Kit Slots</h2>
<div class="pad-grid">
  <div class="pad">Kick<br><span class="midi">MIDI 36</span></div>
  <div class="pad">Snare<br><span class="midi">MIDI 38</span></div>
  <div class="pad">Tom<br><span class="midi">MIDI 45</span></div>
  <div class="pad">Clap<br><span class="midi">MIDI 39</span></div>
  <div class="pad">CowBell<br><span class="midi">MIDI 56</span></div>
  <div class="pad">ClosedHat<br><span class="midi">MIDI 42</span></div>
  <div class="pad">OpenHat<br><span class="midi">MIDI 46</span></div>
  <div class="pad">Cymbal<br><span class="midi">MIDI 49</span></div>
</div>

<h2>Kit Types</h2>
<table>
  <tr><th>Kit Type</th><th>Description</th></tr>
  <tr><td><code>808</code></td><td>Synthesized, sub-bass heavy kicks, tight electronic hits</td></tr>
  <tr><td><code>jazz</code></td><td>Acoustic, warm, brush-like textures, natural dynamics</td></tr>
  <tr><td><code>pearl</code></td><td>Acoustic, strong transients, natural room character</td></tr>
  <tr><td><code>metal</code></td><td>High-energy, bright, aggressive transients</td></tr>
  <tr><td><code>hip-hop</code></td><td>Punchy, processed, mix of synthetic and sampled</td></tr>
  <tr><td><code>house</code></td><td>909-style, crisp hats, clap-forward</td></tr>
  <tr><td><code>generic</code></td><td>Default fallback for ambiguous samples</td></tr>
</table>

<h2>Prerequisites</h2>
<ul>
  <li><strong>Python 3.12+</strong> (see <code>.python-version</code>)</li>
  <li><strong>pip</strong> (package manager)</li>
  <li><strong>libsndfile</strong> (system library for soundfile — <code>brew install libsndfile</code> on macOS)</li>
  <li><em>Optional:</em> TogetherAI API key for LLM-based classification</li>
</ul>

<h2>Setup</h2>
<pre>
# Clone the repo
git clone https://github.com/deeptechhouse/Dr_KitMaker.git
cd Dr_KitMaker

# Create virtual environment
python3.12 -m venv .venv
source .venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -e .

# Set up environment variables (optional, for LLM mode)
cp .env.example .env
# Edit .env and add your TOGETHER_API_KEY
</pre>

<h2>Usage</h2>

<h3>CLI: Analyze a folder of samples</h3>
<pre>
dr-kitmaker analyze /path/to/drum-samples/ -o ./output
</pre>
<p>Options:</p>
<table>
  <tr><th>Flag</th><th>Description</th><th>Default</th></tr>
  <tr><td><code>--override-all</code></td><td>Include samples over duration limit</td><td>off</td></tr>
  <tr><td><code>-f / --format</code></td><td>Export format(s): <code>wav_manifest</code>, <code>sf2</code></td><td><code>wav_manifest</code></td></tr>
  <tr><td><code>-o / --output</code></td><td>Output directory</td><td><code>./output</code></td></tr>
  <tr><td><code>--config</code></td><td>Path to config.yaml</td><td><code>config.yaml</code></td></tr>
</table>

<h3>CLI: Analyze a single file</h3>
<pre>
dr-kitmaker info /path/to/kick.wav
</pre>
<p>Prints detected slot, confidence, kit type, full feature breakdown.</p>

<h3>GUI</h3>
<pre>
dr-kitmaker gui
</pre>
<p>Launches the Tkinter interface with drag-and-drop loading, visual drum-machine pad layout, and one-click export.</p>

<h2>Export Formats</h2>
<table>
  <tr><th>Format</th><th>Output</th><th>Description</th></tr>
  <tr><td><code>wav_manifest</code></td><td>Folder of WAVs + <code>manifest.json</code></td><td>Named WAV per slot (e.g. <code>Kick.wav</code>, <code>Snare.wav</code>), JSON manifest with metadata, confidence, MIDI mapping, missing slots</td></tr>
  <tr><td><code>sf2</code></td><td><code>.sf2</code> SoundFont file</td><td>Binary SoundFont 2 with samples mapped to General MIDI drum keys</td></tr>
  <tr><td><code>sfz</code></td><td><code>.sfz</code> text + WAVs</td><td>SFZ text descriptor (fallback if SF2 binary writing fails)</td></tr>
</table>

<h2>Configuration</h2>
<p>Edit <code>config.yaml</code> in the project root. Environment variables are resolved via <code>${VAR_NAME}</code> syntax.</p>
<table>
  <tr><th>Section</th><th>Key</th><th>Default</th><th>Description</th></tr>
  <tr><td><code>duration</code></td><td><code>max_seconds</code></td><td>3.0</td><td>Maximum sample duration (seconds) before filtering</td></tr>
  <tr><td><code>duration</code></td><td><code>prompt_for_override</code></td><td>true</td><td>Ask user to override excluded samples in CLI</td></tr>
  <tr><td><code>kit_type</code></td><td><code>mode</code></td><td>local</td><td>Classification mode: <code>local</code> | <code>llm</code> | <code>hybrid</code></td></tr>
  <tr><td><code>kit_type</code></td><td><code>llm_fallback_confidence_threshold</code></td><td>0.6</td><td>Below this, hybrid mode queries the LLM</td></tr>
  <tr><td><code>llm</code></td><td><code>provider</code></td><td>togetherai</td><td>LLM provider</td></tr>
  <tr><td><code>llm</code></td><td><code>model</code></td><td>Llama-3.3-70B-Instruct-Turbo</td><td>Model ID</td></tr>
  <tr><td><code>llm</code></td><td><code>api_key</code></td><td><code>${TOGETHER_API_KEY}</code></td><td>Resolved from environment</td></tr>
  <tr><td><code>export</code></td><td><code>default_formats</code></td><td>[wav_manifest, sf2]</td><td>Formats to export by default</td></tr>
  <tr><td><code>logging</code></td><td><code>level</code></td><td>INFO</td><td>Log level: DEBUG, INFO, WARN, ERROR</td></tr>
</table>

<h2>Project Structure</h2>
<pre>
Dr_KitMaker/
+-- config.yaml              # Runtime configuration
+-- pyproject.toml            # Package metadata, tool config
+-- requirements.txt          # Pinned dependencies
+-- src/dr_kitmaker/
|   +-- cli.py                # Click CLI (analyze, info, gui)
|   +-- config.py             # YAML + env var config loader
|   +-- models/               # AudioSample, DrumAnalysisResult, Kit, enums
|   +-- loader/               # AudioLoader (librosa/soundfile)
|   +-- filters/              # DurationFilter
|   +-- analysis/             # Engine, PercussiveAnalyzer, FeatureCache
|   +-- classification/       # Rule, LLM, Hybrid classifiers
|   +-- kit_builder/          # KitBuilder
|   +-- export/               # FolderExporter, SF2Exporter
|   +-- llm/                  # TogetherAIClient
|   +-- gui/                  # Tkinter GUI
+-- tests/
    +-- unit/                 # 21 unit test files
    +-- integration/          # Pipeline integration tests
</pre>

<h2>License</h2>
<p>MIT License. See <code>pyproject.toml</code> for details.</p>

</body>
</html>
About

Python CLI/GUI tool that analyzes audio samples, classifies them into drum kit slots and kit types, builds organized drum kits, and exports in DAW-ready formats.
Readme