BeltScout 🎵

Discover new music artists through intelligent label exploration

BeltScout is a sophisticated music discovery application that connects your local CSV music library to the Discogs API to find new artists by exploring the labels of artists you already know and love.

✨ Features

• Smart Label Mapping: Intelligent CSV label name → Discogs label ID matching with scoring algorithms
• Budgeted API Usage: Configurable request budgets with adaptive retries, delays, and cooldown handling
• Global Deduplication: Eliminates duplicate releases across labels with per-label artist caps
• Persistent Caching: 7-day TTL for label metadata and persistent label mappings in IndexedDB
• Export Options: CSV (with UTF-8 BOM) and JSON export for discovered artists
• Dark Theme UI: Modern, clean interface built with Tailwind CSS
• Real-time Progress: Phase-based progress tracking with budget monitoring

🚀 Quick Start

Prerequisites

• Node.js 18+
• Discogs API token

Installation

1. Clone and install dependencies:

   git clone <repository-url>
   cd BeltScout
   npm install

2. Set up environment variables:

   cp env.example .env
   # Edit .env and add your Discogs API token
   VITE_DISCOGS_TOKEN=your_discogs_token_here

3. Start the development server:

   npm run dev

4. Open your browser to http://localhost:3000

📦 Releases

• Automatic releases via GitHub Actions: pushing a tag v* triggers a build and creates a GitHub Release.
• Versioning with SemVer. Example: npm version patch → creates a commit and tag vX.Y.Z.
• Changelog follows the "Keep a Changelog" style: see CHANGELOG.md.

How to cut a release

1. Bump version and create tag (choose one):

   npm version patch  -m "chore(release): %s"
   npm version minor  -m "chore(release): %s"
   npm version major  -m "chore(release): %s"
   # or pre-release
   npm version prerelease --preid=alpha -m "chore(release): %s"

2. Push commit and tag to trigger CI:

   git push --follow-tags origin <your-branch>

3. A GitHub Release is created automatically with a zipped build artifact.

📁 Project Structure

src/
├── components/          # React components
│   ├── LibraryPanel.tsx      # CSV upload and library management
│   ├── SettingsPanel.tsx     # App configuration
│   ├── SearchBar.tsx         # Artist search with autocomplete
│   ├── ProgressBar.tsx       # Phase and budget progress
│   ├── LabelProofDialog.tsx  # Label mapping confirmation
│   ├── LabelChips.tsx        # Label status indicators
│   ├── ResultsList.tsx       # Search results with export
│   └── ResetCachesButton.tsx # Cache management
├── lib/                # Core utilities
│   ├── csv.ts               # CSV parsing and processing
│   ├── normalize.ts         # String normalization
│   ├── scoring.ts           # Label matching algorithms
│   ├── budgetFetch.ts       # Rate-limited API client
│   ├── exporters.ts         # Data export functions
│   └── storage/             # Data persistence
│       ├── idb.ts           # IndexedDB operations
│       └── localSettings.ts # LocalStorage settings
├── api/                 # External API integration
│   └── discogsClient.ts     # Discogs API client
├── state/               # Application state
│   ├── types.ts             # TypeScript interfaces
│   └── searchEngine.ts      # Search orchestration
└── App.tsx              # Main application component

🔧 Configuration

UI Settings (Defaults)

• CSV Processing: Max labels per artist: 5
• Data Fetching: Max releases per label: 10; Max new artists per label: 5
• API Limits: Request budget: 100; Delay between requests: 800 ms
• Behavior: Force label proof dialogs or use cached mappings

Environment Variables

• VITE_DISCOGS_TOKEN (required): Your Discogs API token
• VITE_API_BASE (optional): Custom API base URL

📊 How It Works

1. Library Import: Upload your music library CSV (sample auto-load is supported)
2. Artist Search: Search for an artist from your library
3. Label Extraction: BeltScout extracts associated labels from your CSV
4. Label Proof: Confirm Discogs label matches with intelligent scoring
5. Data Fetching: Retrieve releases and discover new artists
6. Results Export: Export findings to CSV or JSON

🎯 Use Cases

• Music Discovery: Find new artists through label exploration
• Library Analysis: Understand your music collection's label distribution
• A&R Research: Discover emerging artists on specific labels
• Music Journalism: Research label rosters and artist relationships

🛠️ Built With

• Frontend: React 18 + TypeScript + Vite
• Styling: Tailwind CSS with dark theme
• Icons: Lucide React
• Data Processing: PapaParse for CSV, custom normalization
• Storage: IndexedDB (via idb) + LocalStorage
• Validation: Zod schema validation
• API: Custom budgeted fetch with retry logic

📝 CSV Format

Your CSV should include these columns (case-insensitive):

artist,label,genre,albumTitle,title
Aphex Twin,Warp Records,Electronic,Selected Ambient Works 85-92,Xtal
Boards of Canada,Warp Records,Electronic,Music Has the Right to Children,ROYGBIV

Note: BeltScout automatically detects and maps common column variations. For example:

• artist column can also be named performer
• label column can also be named company
• genre column can also be named style
• albumTitle column can also be named album, record
• title column can also be named track, song

The app will work with your existing CSV structure and automatically normalize the data.

Auto-loading the sample CSV

• If a file named public/Track.csv exists, the app auto-loads it on startup. If unavailable, it falls back to public/Track.csv.example. This is convenient for demos and local testing.

🔒 API Rate Limiting

BeltScout includes sophisticated rate limiting:

• Configurable delays between requests
• Automatic retry with exponential backoff
• Cooldown periods for rate limit errors
• Request budget management
• Network error handling

🧪 Scripts

• npm run dev: Start the Vite dev server on port 3000
• npm run build: Type-check and build production assets into dist/
• npm run preview: Preview the production build locally
• npm run lint: Run ESLint on the codebase

🚨 Troubleshooting

Common Issues

1. "VITE_DISCOGS_TOKEN required": Set your API token in .env
2. CSV parsing errors: Ensure your CSV has proper headers and formatting
3. API rate limits: Increase delays or reduce request budgets in settings
4. IndexedDB errors: Clear browser data or use the reset button

Performance Tips

• Use smaller request budgets for testing
• Enable "Always ask proof" only when needed
• Monitor the progress bar for API usage
• Export results regularly to avoid data loss

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Discogs for the comprehensive music database API
• Vite for the fast build tool
• Tailwind CSS for the utility-first CSS framework
• Lucide for the beautiful icons

---

Happy music discovery! 🎶