fediversion/docs/BANDCAMP_NUGS_SPEC.md

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:

# 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:

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

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

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