---
name: samplette
description: Sister skill to midi-cook — takes a sample from Glory MP3's library (~/.samplock/) and cooks MIDI layers that match its key. User downloads a sample via the Glory MP3 app (handles key/BPM detection automatically), then asks samplette to "cook a pack for this" / "samplette [sample name]" / "pack for this sample" / "match the last download" — skill reads the key from ~/.samplock/library.json, detects tuning offset from A=440Hz (older R&B samples are often -10 to -30 cents flat), then drives midi-cook to generate chords/lead/counter/melody4/808/hats all in the sample's exact key. Output is a folder on Desktop named after the sample, containing the original MP3 + 5 numbered takes, ready to drag into FL Studio. TRIGGER on "samplette", "sample this", "make a pack for [x]", "cook a pack", "match my last sample", "layers for [sample]", "match this sample", or any request that references a file in ~/.samplock/. Prefer samplette over plain midi-cook whenever the user has a specific sample they want MIDIs to layer over — samplette guarantees key match by reading Glory MP3's detection. Use midi-cook directly only when there's NO sample in the picture (pure-generation requests).
---


# samplette

Sister skill to `midi-cook`. Cooks MIDI layers that match a specific sample from the Glory MP3 library.

## The flow

1. **User downloads a sample** via the Glory MP3 app → saves to `~/.samplock/samples/` and appends metadata to `~/.samplock/library.json` (Glory MP3 auto-detects key + BPM).
2. **User asks samplette** ("samplette", "pack for [name]", "match my last sample", etc.)
3. **Skill reads library.json** to get the sample's key + BPM without re-analyzing
4. **Skill detects tuning offset** from A=440Hz (older records are often -10 to -30 cents flat)
5. **Skill drives midi-cook** with `force_tonic` + `force_mode` + `force_tempo_band` matching
6. **Skill builds a pack folder** on Desktop with the original MP3 + N takes of MIDIs

## Why a sister skill and not just midi-cook

`midi-cook` generates fresh random MIDIs for a vibe. `samplette` guarantees the MIDIs will **layer cleanly** over a specific sample because the key is forced to match what Glory MP3 detected. Without samplette you'd have to manually figure out the key, manually pass `force_tonic`/`force_mode` to cook_random, manually package everything — samplette does it all in one call.

## Usage

```python
import sys
sys.path.insert(0, '/Users/<you>/.claude/skills/samplette/scripts')
from samplette import samplette

# Cook a pack for the most recently-downloaded sample
samplette()

# Cook a pack for a specific sample by name (fuzzy-matches titles)
samplette(query="aaliyah")

# Cook more takes
samplette(query="stephanie mills", num_takes=10)

# By full path
samplette(path="/Users/tec/.samplock/samples/Fall In Love.mp3")
```

## Output

```
~/Desktop/<Sample Title> pack/
├── <Sample Title>.mp3                              ← original sample
├── PACK INFO.md                                    ← key/BPM/tuning offset/take summary
├── Take 1 - <engine> + <voicing> (<BPM> BPM)/
│   ├── chords.mid
│   ├── lead.mid
│   ├── counter.mid
│   ├── melody4.mid
│   ├── 808.mid
│   ├── snare.mid
│   ├── hats.mid
│   ├── open_hats.mid
│   └── info.md
├── Take 2 - ...
└── Take 5 - ...
```

## Tuning offset (A=440Hz)

Old R&B, Japanese city-pop, and a lot of the samples CCBBY digs tend to be off-pitch from the modern A=440Hz standard — usually because they were recorded on tape machines that drifted, or mastered to slightly different reference pitches. AutoKey (the Antares plugin) detects this in CCBBY's workflow; samplette writes the detected cents offset into PACK INFO.md so the producer knows to either (a) pitch-shift the sample onto the grid in FL, or (b) apply the same offset to the cooked MIDIs via their synth's global tuning.

If the offset is >15 cents, it'll sound noticeable. The pack info documents it as, e.g., `Tuning: A = 435.8 Hz (-17 cents flat)`.

## Glory MP3 integration

Glory MP3 is a macOS Electron app at `/Applications/Glory MP3.app`. It downloads YouTube audio and auto-detects key + BPM using its own engine, writing to `~/.samplock/library.json`:

```json
{
  "title": "Aaliyah - Rock The Boat (Instrumental)",
  "filePath": "/Users/tec/.samplock/samples/Aaliyah - Rock The Boat (Instrumental).mp3",
  "bpm": 92,
  "key": "G Minor",
  "sourceUrl": "https://www.youtube.com/watch?v=tMbx5ND4RSM",
  "addedAt": "2026-04-23T04:54:06.065Z"
}
```

samplette reads this file as source-of-truth for key + BPM. No re-analysis needed — Glory MP3 has already done it.

If the user says "download [X] first" or provides a YouTube URL directly, samplette tells them to drop it into Glory MP3 manually (no URL scheme exposed by the app), then re-invoke samplette — it'll pick up the new entry automatically.

## Channels CCBBY samples from (for reference, not exhaustive)

- @Musicforemptyrooms (ambient / chill lo-fi)
- @BigPeter1086RealMusicChannel (old R&B rips)
- @freal (samples / loops)
- Plus: Aaliyah, SWV, Destiny's Child, Chief Keef, Japanese R&B/city-pop

## Mapping key string → midi-cook params

Glory MP3 emits strings like `"G Minor"`, `"C# Minor"`, `"F Major"`. Parser converts to:
- `tonic` string matching `PITCH_BACK` in styles.py (e.g., "G", "C#", "Bb" — normalize `A#` → `Bb`, `D#` → `Eb`, `G#` → `Ab`)
- `mode` = `"minor"` or `"major"` (lowercase)
- `tempo_band`: `slow` if BPM ≤ 105, `mid` if 106-135, `fast` if ≥ 136. If BPM is unusual (like 199 — probably half-time misdetection), default to `slow`.

## Engine selection for CCBBY's vibe

CCBBY samples OLD R&B heavily. The R&B/soulful data-sourced engines in midi-cook are the best matches:
- `rio_leyva` — sultry, sparse, patient
- `nick_mira` — melodic hybrid
- `noah_dreamy` — dreamy plucky
- `taz_og` — classic Internet Money melodic trap
- `jrhit_melodic` — chord-per-beat melodic trap

samplette biases its engine picks toward these 5 over the more aggressive `bricc_rage` / `kc_dark`. The `close` voicing leads (Gold Flint validated).

## Error cases

- **No library.json or empty** → tell user to download a sample via Glory MP3 first
- **Query doesn't fuzzy-match** → list available samples, ask user to be more specific
- **BPM is 0 or missing** → default to `slow` tempo band
- **Key isn't parseable** → fail loudly with the unparseable string

## Future expansion (not MVP)

- Auto-download: take a YouTube URL → write it to Glory MP3's download queue (needs URL scheme or AppleScript automation)
- Sample chord transcription: use `engine-fux` to also rip the sample's actual chord progression, not just key — layer fresh MIDIs on top of the transcribed chords
- Multi-sample pack: cook in multiple keys at once for sample flips