∞╱╲_╱╲∞
    (=◕ᴥ◕=)  LOOPCAT
    ╰─────╯  ═══════○

A CLI tool to catalog WAV files from a Boss RC-300 looper pedal with AI-powered audio analysis.

• Import loops from RC-300 USB or backup folders with automatic deduplication
• Analyze patches using Gemini AI (mood, style, instruments) and librosa (BPM, key)
• Search your catalog with full-text search
• Export metadata to JSON or CSV for use in DAWs and sample managers

# Clone and install with uv
git clone <repo-url>
cd loopcat
uv sync

# Install ffmpeg (required for MP3 conversion)
brew install ffmpeg

# Set up Gemini API key (required for AI analysis)
loopcat auth

# 1. Connect your RC-300 via USB, then import
loopcat import

# 2. Convert WAVs to MP3 (needed for Gemini analysis)
loopcat convert

# 3. Analyze with AI
loopcat analyze

# 4. Browse your catalog
loopcat list
loopcat search "funky guitar"

# 5. Play with TUI (RC-300 style controls)
loopcat                   # Launch TUI (default command)
loopcat play 42           # Play specific patch directly

Import WAV files from an RC-300 or backup folder.

loopcat import                              # Default: /Volumes/BOSS_RC-300
loopcat import ~/Backups/RC-300/2026-01-17  # From a backup folder

• Parses RC-300 folder structure (ROLAND/WAVE/{bank}_{track}/)
• Fast duplicate detection using partial hashing (first 64KB)
• Copies WAVs to managed storage (~/.loopcat/wav/)
• Extracts duration, sample rate, and channel info

Convert WAV files to MP3 for Gemini analysis.

loopcat convert              # Convert all unconverted tracks
loopcat convert --patch 42   # Convert specific patch

• Requires ffmpeg to be installed
• Outputs to ~/.loopcat/mp3/ at 192 kbps

Analyze patches with Gemini AI and librosa.

loopcat analyze              # Analyze all unanalyzed patches
loopcat analyze --patch 42   # Analyze specific patch

Gemini analysis (all tracks uploaded together for context):

• Patch: suggested name, description, mood, musical style, energy level, tags, use case
• Tracks: suggested name, role (rhythm/lead/bass/drums), instruments, description

Local analysis (per track):

• BPM detection via librosa
• Key detection via librosa

List patches and tracks in the catalog.

loopcat list                 # List all patches
loopcat list --patch 42      # Show specific patch (by catalog number)
loopcat list --bank 40       # Filter by original RC-300 bank

Full-text search across patches and tracks.

loopcat search "funky guitar"
loopcat search "ambient pad"

Searches patch names, descriptions, moods, tags, track names, roles, and instruments.

Show catalog statistics.

loopcat stats

Displays:

• Total patches and tracks
• Analyzed and converted counts
• Total duration
• BPM range
• Style distribution (top 5)
• Energy level distribution (high/medium/low)

Launch the TUI player with RC-300 style controls. This is the default command when running loopcat with no arguments.

loopcat                   # Shows patch picker (default command)
loopcat play              # Same as above
loopcat play 42           # Play specific patch directly

Patch Picker Controls:

Player Controls:

Navigation flow:

loopcat
    │
    ▼
┌─────────────────┐
│  Patch Picker   │◄────────┐
│ (type to filter)│         │
└────────┬────────┘         │
         │ Enter            │ q or ,
         ▼                  │
┌─────────────────┐         │
│   TUI Player    │─────────┘
│ (auto-plays)    │
└────────┬────────┘
         │ Esc
         ▼
       Exit

Export catalog metadata to various formats.

loopcat export --format json --output ./metadata   # JSON sidecars
loopcat export --format csv --output catalog.csv   # CSV spreadsheet
loopcat export --format folder --output ~/Music    # Organized folder with symlinks
loopcat export --format folder --output ~/Music --wav  # Use WAV instead of MP3

JSON format: Creates per-patch and per-track sidecar files with full metadata.

CSV format: Flat export with all track metadata, suitable for spreadsheets or sample managers.

Folder format: Creates an organized folder structure with symlinks to audio files:

{output}/loopcat/
├── 001-Midnight_Funk_Groove/
│   ├── 1-Pocket_Bass_Line.mp3 → ~/.local/share/loopcat/mp3/...
│   ├── 2-Rhythm_Guitar.mp3 → ~/.local/share/loopcat/mp3/...
│   ├── 3-Wah_Lead.mp3 → ~/.local/share/loopcat/mp3/...
│   └── _metadata.json
├── 002-Ambient_Dreamscape/
│   └── ...

Ideal for importing into DAWs like Bitwig Studio via the browser. Use --wav to link to WAV files instead of MP3s.

Follows XDG Base Directory standard:

~/.config/loopcat/
└── config.yaml   # API keys and settings

~/.local/share/loopcat/
├── catalog.db    # SQLite database with full-text search
├── wav/          # Managed WAV files
└── mp3/          # Converted MP3 files

Respects XDG_CONFIG_HOME and XDG_DATA_HOME if set.

• Original bank (--bank): The RC-300 bank number (1-99) at import time
• Catalog number (--patch): Auto-assigned sequential ID (1, 2, 3, ...) that supports unlimited patches

This allows you to import from the same RC-300 multiple times without conflicts.

$ loopcat list --patch 42

#42 Midnight Funk Groove (bank 40)
  Laid-back funk jam with a driving bass line and rhythmic guitar.
  Style: funk | Energy: 7/10
  Mood: groovy, mellow, late-night
  Tags: guitar, bass, practice

 Track  Name              Role    Duration  BPM  Key
 1      Pocket Bass Line  bass    32.5s     92   E minor
 2      Rhythm Guitar     rhythm  32.5s     92   E minor
 3      Wah Lead          lead    32.5s     92   E minor

• Python 3.11+
• ffmpeg (for MP3 conversion)
• Google API key with Gemini access (for AI analysis) - run loopcat auth to configure