b4cddf41ea
- Fork elmeg-demo codebase for multi-band support - Add data importer infrastructure with base class - Create band-specific importers: - phish.py: Phish.net API v5 - grateful_dead.py: Grateful Stats API - setlistfm.py: Dead & Company, Billy Strings (Setlist.fm) - Add spec-kit configuration for Gemini - Update README with supported bands and architecture
217 lines
4.8 KiB
Markdown
217 lines
4.8 KiB
Markdown
# Bandcamp & Nugs Integration Spec
|
|
|
|
**Date:** 2023-12-23
|
|
**Purpose:** Link shows and performances to official audio sources
|
|
|
|
---
|
|
|
|
## Overview
|
|
|
|
Add support for linking to official audio releases on:
|
|
|
|
- **Bandcamp** - Official studio/live releases, digital purchases
|
|
- **Nugs.net** - Live show streams/downloads, SBD recordings
|
|
|
|
---
|
|
|
|
## Database Changes
|
|
|
|
### Option A: Simple Link Fields (MVP)
|
|
|
|
Add to existing models:
|
|
|
|
```python
|
|
# Show model
|
|
class Show(SQLModel, table=True):
|
|
# ... existing fields ...
|
|
nugs_link: Optional[str] = None # Full Nugs.net URL
|
|
bandcamp_link: Optional[str] = None # Full Bandcamp URL
|
|
|
|
# Performance model
|
|
class Performance(SQLModel, table=True):
|
|
# ... existing fields ...
|
|
nugs_link: Optional[str] = None # Link to specific track on Nugs
|
|
bandcamp_link: Optional[str] = None # Link to specific track on Bandcamp
|
|
```
|
|
|
|
### Option B: Structured Link Table (Future)
|
|
|
|
For more flexibility:
|
|
|
|
```python
|
|
class ExternalLink(SQLModel, table=True):
|
|
id: Optional[int] = Field(default=None, primary_key=True)
|
|
|
|
# Polymorphic reference
|
|
entity_type: str # "show" | "performance" | "song"
|
|
entity_id: int
|
|
|
|
# Link info
|
|
platform: str # "nugs" | "bandcamp" | "youtube" | "archive" | "spotify"
|
|
url: str
|
|
label: Optional[str] = None # Custom label like "SBD Recording"
|
|
is_official: bool = True
|
|
|
|
created_at: datetime
|
|
created_by: Optional[int] # User who added it
|
|
```
|
|
|
|
---
|
|
|
|
## API Endpoints
|
|
|
|
### Update Show (Admin)
|
|
|
|
```
|
|
PATCH /admin/shows/{id}
|
|
{
|
|
"nugs_link": "https://nugs.net/...",
|
|
"bandcamp_link": "https://bandcamp.com/..."
|
|
}
|
|
```
|
|
|
|
### Update Performance (Admin)
|
|
|
|
```
|
|
PATCH /admin/performances/{id}
|
|
{
|
|
"nugs_link": "https://nugs.net/...",
|
|
"bandcamp_link": "https://bandcamp.com/..."
|
|
}
|
|
```
|
|
|
|
### Bulk Import Links
|
|
|
|
```
|
|
POST /admin/import/external-links
|
|
{
|
|
"links": [
|
|
{"show_id": 123, "platform": "nugs", "url": "..."},
|
|
{"performance_id": 456, "platform": "bandcamp", "url": "..."}
|
|
]
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Frontend Display
|
|
|
|
### Show Page
|
|
|
|
```
|
|
┌────────────────────────────────────────────┐
|
|
│ 📅 December 13, 2025 @ The Anthem │
|
|
│ │
|
|
│ [▶ Watch on YouTube] [🎧 Nugs] [🎵 Bandcamp]│
|
|
│ │
|
|
│ Set 1: │
|
|
│ 1. Song Title [🎧] [🎵] ← per-track │
|
|
│ 2. Another Song │
|
|
└────────────────────────────────────────────┘
|
|
```
|
|
|
|
### Icon/Button Design
|
|
|
|
```tsx
|
|
const PLATFORM_ICONS = {
|
|
nugs: { icon: Headphones, label: "Nugs.net", color: "#ff6b00" },
|
|
bandcamp: { icon: Music, label: "Bandcamp", color: "#629aa9" },
|
|
youtube: { icon: Youtube, label: "YouTube", color: "#ff0000" },
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Data Sources
|
|
|
|
### Nugs.net
|
|
|
|
- Shows listed at: <https://nugs.net/artist/>...
|
|
- Direct track links available
|
|
- May have SBD vs AUD quality indicators
|
|
|
|
### Bandcamp
|
|
|
|
- Live releases often on artist's Bandcamp
|
|
- Track-level linking possible
|
|
- May include "pay what you want" vs fixed price
|
|
|
|
---
|
|
|
|
## Import Workflow
|
|
|
|
### Manual Entry (Admin UI)
|
|
|
|
1. Admin navigates to show/performance
|
|
2. Clicks "Add External Links"
|
|
3. Pastes URL, selects platform
|
|
4. Saves
|
|
|
|
### Bulk CSV Import
|
|
|
|
```csv
|
|
show_date,platform,url
|
|
2024-12-13,nugs,https://nugs.net/live/...
|
|
2024-12-13,bandcamp,https://bandcamp.com/album/...
|
|
```
|
|
|
|
### API Scraping (Future)
|
|
|
|
- Could auto-detect new releases on Nugs
|
|
- Match by date/venue
|
|
- Requires API access or web scraping
|
|
|
|
---
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 1: MVP (Database + Admin)
|
|
|
|
- [ ] Add `nugs_link`, `bandcamp_link` to Show model
|
|
- [ ] Add `nugs_link`, `bandcamp_link` to Performance model
|
|
- [ ] Run migration
|
|
- [ ] Add admin endpoints to update links
|
|
|
|
### Phase 2: Frontend Display
|
|
|
|
- [ ] Show links on Show page (next to YouTube)
|
|
- [ ] Show links on Performance rows
|
|
- [ ] Add platform icons/colors
|
|
|
|
### Phase 3: Import Tools
|
|
|
|
- [ ] CSV import endpoint
|
|
- [ ] Admin bulk edit UI
|
|
|
|
### Phase 4: User Features (Optional)
|
|
|
|
- [ ] Users can suggest links (moderated)
|
|
- [ ] "I own this" tracking for collectors
|
|
|
|
---
|
|
|
|
## Estimated Effort
|
|
|
|
| Phase | Time |
|
|
|-------|------|
|
|
| Phase 1 | 30 min |
|
|
| Phase 2 | 1 hour |
|
|
| Phase 3 | 1 hour |
|
|
| Phase 4 | 2+ hours |
|
|
|
|
---
|
|
|
|
## Questions to Resolve
|
|
|
|
1. **Should users be able to add links?** Or admin-only?
|
|
2. **Verify link quality?** Some Nugs links are AUD, some SBD
|
|
3. **Other platforms?** Spotify, Apple Music, Archive.org, Relisten?
|
|
4. **Affiliate links?** If monetizing, need affiliate program setup
|
|
|
|
---
|
|
|
|
## Next Steps
|
|
|
|
1. Run database migration
|
|
2. Add admin API endpoints
|
|
3. Update Show page UI with link buttons
|