| name | sample-tagger |
| description | Help users manage, search, and organise audio sample libraries. Use when the user mentions samples, sample libraries, loops, one-shots, drum sounds, or wants to find/organise/tag audio files. Provides a pip-installable tool (in assets/) and assists with installation, searching, browsing, and organisation tasks. |
Sample Tagger
Assist users with audio sample library management using the sample-tagger CLI tools.
Installation
The tool is in assets/sample-tagger-pkg/. Provide it to the user and instruct them to:
cd sample-tagger-pkg
pip install .
This installs four commands: sample-tag, sample-search, sample-browse, sample-organise.
Workflow
1. Initial setup (user runs once)
sample-tag /path/to/samples
2. Help with searches
When the user asks to find samples, translate their request into a sample-search command using --tag/-t flags. Tags use AND logic — multiple -t flags narrow the results.
| User says | Command |
|---|
| "find kicks around 128bpm" | sample-search samples.db -t drums -t kick --bpm-min 125 --bpm-max 131 |
| "show me pads in A minor" | sample-search samples.db -t synth -t pad -k A |
| "loops between 2-4 seconds" | sample-search samples.db --loop --duration-min 2 --duration-max 4 |
| "anything with 'techno' in the name" | sample-search samples.db -q "techno" |
| "all my bass sounds" | sample-search samples.db -t bass |
| "one-shot hihats" | sample-search samples.db -t drums -t hihat --oneshot |
| "find rumbles" | sample-search samples.db -t bass -t rumble |
| "risers and uplifters" | sample-search samples.db -t fx -t riser |
| "claps and snares" | sample-search samples.db -t clap then -t snare (separate searches — AND logic means both tags required) |
| "atmospheric textures" | sample-search samples.db -t texture -t atmosphere |
| "stabs for techno" | sample-search samples.db -t synth -t stab |
| "808 bass" | sample-search samples.db -t bass -t 808 |
| "glitchy fx" | sample-search samples.db -t fx -t glitch |
| "industrial sounds" | sample-search samples.db -t texture -t industrial |
Key options:
-t, --tag: Filter by tag (repeatable, AND logic). Common tags: drums, bass, synth, vocal, fx, texture, kick, snare, hihat, pad, lead, riser, etc.--bpm-min, --bpm-max: BPM range-k, --key: Musical key (C, C#, D, etc.)--duration-min, --duration-max: Length in seconds-q, --query: Text search in filename/path--oneshot, --loop: Filter by type--paths-only, -p: Output paths only (useful for scripting)--stats: Show statistics for matched samples
3. Help with organisation
When the user wants to reorganise their library:
sample-organise samples.db --output ~/Music/Organised
sample-organise samples.db --output ~/Music/Organised --symlink
sample-organise samples.db --output ~/Music/Organised --dry-run
sample-organise samples.db --output ~/Music/Kicks --tag drums --tag kick
Folder structure uses first tag as primary directory, second tag as subdirectory (e.g. drums/kick/, synth/pad/).
4. Browsing
For visual exploration with audio preview, suggest the TUI:
sample-browse samples.db
The sidebar shows a flat list of tags with [x]/[ ] selection indicators. Clicking a tag toggles it — multiple selected tags filter with AND logic. Click "All" to clear selection.
Keys:
Space – Play/stop selected sampleEnter – Play selected samplea – Toggle autoplay (plays samples as you browse)t – Edit tags on highlighted sampleT – Bulk edit tags on all displayed samplesc – Copy path to clipboardo – Open containing folder/ – Focus searchr – Reload databaseEsc – Clear filtersq – Quit
Playback auto-stops when navigating to a different sample. With autoplay on (a), samples play automatically as the cursor moves.
Tag editing (t/T) opens a modal with comma-separated add/remove inputs. Single mode shows current tags; bulk mode shows sample count.
Database location
After running sample-tag, the database is at samples.db in the scanned directory. If the user doesn't know where it is, it's wherever they pointed sample-tag at.
Auto-migration
Databases created with older versions (v1, using category/subcategory columns) are automatically migrated to the tags system when opened. The migration converts each sample's category and subcategory into tags.
Detection capabilities
| Property | Method | Notes |
|---|
| BPM | Beat tracking | Loops > 1 second, validated against filename hints |
| Key | Chroma analysis | Major key assumed |
| Tags | Filename + spectral | See tag list below |
| One-shot/Loop | Onset density + RMS variance | Audio-based detection |
Available tags
Samples are assigned 1-2 tags from filename keyword matching or spectral analysis fallback.
Primary tags (broad category): drums, bass, synth, vocal, fx, texture, unknown
Secondary tags (specific type):
- Drums: kick, snare, clap, hihat, hihat_closed, hihat_open, cymbal, crash, ride, tom, percussion, shaker, conga, bongo, tambourine, cowbell, rimshot, break, tops, click, zap, blip, snap
- Bass: sub, 808, rumble, reese, acid, wobble, loop
- Synth: lead, pad, arp, pluck, stab, chord, keys, piano, organ, strings, brass, bell, mallet, poly, mono, sequence, loop
- Vocal: spoken, chop, phrase, adlib, hook
- FX: riser, downlifter, sweep, impact, transition, whoosh, swell, noise, glitch, distortion, reverse, scrape, scratch, laser, beep, bleep
- Texture: atmosphere, ambient, drone, foley, field_recording, room, space, dark, cinematic, evolving, industrial, machine, metallic
Common tasks
"How many kicks do I have?"
sample-search samples.db -t drums -t kick --stats
"Find samples that might work at 130bpm in C"
sample-search samples.db --bpm-min 127 --bpm-max 133 -k C
"Export a list of all my vocal samples"
sample-search samples.db -t vocal --paths-only > vocals.txt
"Re-analyse after adding new samples"
sample-tag /path/to/samples
"Force re-analyse everything"
sample-tag /path/to/samples --force
