Bandcamp Feed

A local Django web application that connects to your Gmail via IMAP, filters for Bandcamp "New Release" emails, parses them for metadata (album art, artist/label, release link), and displays them in a chronologically ordered feed.

Features

• Gmail IMAP Integration: Connects to Gmail to fetch Bandcamp notification emails from all folders
• Email Parsing: Extracts uploader (artist/label), release name, artwork URL, and Bandcamp links from email HTML using BeautifulSoup
• SQLite Caching: Stores parsed releases locally to avoid re-processing emails
• Two-Phase Sync: Prioritizes recent emails first, then processes historical backlog incrementally
• Real-time Progress: Server-Sent Events (SSE) provide live feedback during email sync
• Inline Audio Playback: Stream tracks directly in the browser via scraped Bandcamp MP3 URLs with auto-refreshing tokens
• Favourite Uploaders: Star artists/labels to filter your feed down to favourites
• Search & Filter: Filter releases by text search, release type, date range, favourites, and sort order
• Custom Domain Support: Handles both *.bandcamp.com URLs and custom artist domains

Tech Stack

• Backend: Django 5.2, Python 3.11+
• Email Processing: imap-tools (IMAP), BeautifulSoup4
• Bandcamp Scraping: Requests
• Frontend: Django Templates, Tailwind CSS (CDN), HTMX 1.9
• Database: SQLite
• Real-time Updates: Server-Sent Events (SSE)

Prerequisites

• Python 3.11+
• A Gmail account with Bandcamp notification emails
• Gmail App Password (see setup below)

Installation

1. Clone and navigate to the project:

   cd bandcamp-feed

2. Create and activate a virtual environment:

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt

4. Set up environment variables:

   cp env.example .env

   Edit .env and add your Gmail credentials:

   EMAIL_USER=your-email@gmail.com
   EMAIL_PASSWORD=your-app-password
   EMAIL_SYNC_LIMIT=500
   

5. Run database migrations:

   python manage.py migrate

6. Start the development server:

   python manage.py runserver

7. Open your browser: Navigate to http://127.0.0.1:8000

Gmail App Password Setup

Gmail requires an App Password for IMAP access (your regular password won't work).

Step 1: Enable 2-Factor Authentication

1. Go to your Google Account
2. Navigate to Security → 2-Step Verification
3. Follow the prompts to enable 2FA if not already enabled

Step 2: Create an App Password

1. Go to App Passwords
2. Select Mail as the app
3. Select Other and enter "Bandcamp Feed"
4. Click Generate
5. Copy the 16-character password (without spaces)

Step 3: Add to .env

EMAIL_USER=your-email@gmail.com
EMAIL_PASSWORD=abcd efgh ijkl mnop

Configuration

Environment Variable	Description	Default
EMAIL_USER	Gmail address	Required
EMAIL_PASSWORD	Gmail App Password	Required
EMAIL_SYNC_LIMIT	Max emails to process per sync (0 = unlimited)	500

Usage

1. View Feed: The main page displays all cached Bandcamp releases in a paginated grid
2. Sync: Click Sync Emails to fetch new releases from Gmail (progress shown in real-time)
3. Search: Type in the search box to filter by uploader or release name
4. Filter: Use the dropdowns to filter releases by date (last week, month, 3 months, or year), release type (album or track), or favourites only
5. Sort: Order by newest, oldest, or uploader name (A-Z or Z-A)
6. Play: Click a release card to stream its tracks directly in the browser
7. Favourite: Star an uploader to add them to your favourites for quick filtering
8. Browse: Click the Bandcamp link on a release card to open it on Bandcamp

Project Structure

bandcamp-feed/
├── bandcamp_feed/              # Django project package
│   ├── settings.py             # Configuration with .env support
│   ├── urls.py                 # Root URL routing
│   └── wsgi.py
├── feed/                       # Main application
│   ├── models.py               # Release & FavouriteUploader models
│   ├── services.py             # IMAP fetching, email parsing & stream scraping
│   ├── views.py                # Views, SSE streaming & JSON endpoints
│   ├── urls.py                 # App URL routing
│   ├── admin.py                # Django admin registration
│   ├── apps.py                 # App config
│   ├── migrations/             # Database migrations
│   ├── static/feed/            # Static assets
│   │   ├── css/main.css
│   │   └── js/
│   │       ├── player.js       # Inline audio player
│   │       └── toast.js        # Toast notifications
│   └── templates/feed/         # HTML templates
│       ├── base.html           # Base layout with Tailwind config
│       ├── index.html          # Main feed page
│       └── partials/           # HTMX partials
│           ├── releases.html   # Release grid partial
│           └── favourite_btn.html
├── .env                        # Environment variables (not in git)
├── env.example                 # Template for .env
├── requirements.txt            # Python dependencies
└── manage.py

Security Notes

• The .env file containing credentials is excluded from git via .gitignore
• Use Gmail App Passwords instead of your main account password
• This application is designed for local/personal use only