sample-tagger

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)

# Analyse their library (can take hours for large libraries, resumable)
sample-tag /path/to/samples

# Creates samples.db in that directory

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:

# Copy into tag-based folders
sample-organise samples.db --output ~/Music/Organised

# Use symlinks to save disk space
sample-organise samples.db --output ~/Music/Organised --symlink

# Preview first
sample-organise samples.db --output ~/Music/Organised --dry-run

# Just samples with a specific tag
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 sample
• Enter – Play selected sample
• a – Toggle autoplay (plays samples as you browse)
• t – Edit tags on highlighted sample
• T – Bulk edit tags on all displayed samples
• c – Copy path to clipboard
• o – Open containing folder
• / – Focus search
• r – Reload database
• Esc – Clear filters
• q – 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  # Only processes new/changed files

"Force re-analyse everything"

sample-tag /path/to/samples --force