discdrop/README.md

DiscDrop

Self-hosted RSS feed generator for MusicBrainz release groups.

Track your favourite artists and get a unified RSS feed of their release groups — albums, singles, EPs, and more. No duplicates (release groups, not individual releases), per-artist type monitoring, and a clean modern UI.

Built with Quarkus + HTMX + daisyUI.

---

Features

• Unified RSS feed — One feed for all tracked artists, ordered chronologically by first release date
• Per-artist monitoring — Choose which release types to track per artist (Album, Single, EP, Broadcast, Other)
• Artist search — Autocomplete search against the MusicBrainz API with disambiguation info
• Release group deduplication — Tracks release groups instead of individual releases (no duplicate vinyl/CD/digital entries)
• OPML export — Subscribe in any RSS reader
• Theme switching — daisyUI themes: Dark, Light, Synthwave, Retro, Dracula, Night, Dim, Nord
• Settings — Configurable cache TTL (6/12/24h) and default release types
• Zero infrastructure — SQLite single-file database, no external services needed

---

Quick Start

Prerequisites

• Java 21+
• Maven 3.9+

Development

# Run in dev mode with live reload
mvn quarkus:dev

The app starts at http://localhost:8080.

Production (JAR)

# Build
mvn clean package

# Run
java -jar target/quarkus-app/quarkus-run.jar

Docker

Multi-stage build — no host pre-build needed, Maven runs inside the container.

# Build (from project root)
docker build -t discdrop .

# Run
docker run -p 8080:8080 \
  -e DISC_DROP_BASE_URL=http://localhost:8080 \
  -v discdrop-data:/app/data \
  discdrop

---

Configuration

All configuration is via environment variables:

Variable	Default	Description
DISC_DROP_DB_PATH	data/discdrop.db	Path to the SQLite database file
DISC_DROP_CACHE_TTL	8	Cache TTL in hours
DISC_DROP_BASE_URL	http://localhost:8080	Public URL for RSS feed links
DISC_DROP_USER_AGENT	DiscDrop/1.0 (https://gitea.t3du.com/…)	User-Agent sent to MusicBrainz API

The User-Agent header is sent with every MusicBrainz API request per their etiquette. It can be changed via DISC_DROP_USER_AGENT.

---

Usage

1. Add artists

Use the search bar in the navbar (available on all pages) to find artists. Each result shows the artist name, disambiguation, and country/area. If an artist is already tracked, it shows "✓ Added".

Click + Add to start tracking an artist. DiscDrop immediately fetches their release groups from MusicBrainz and caches them locally.

2. Configure monitoring

On the Artists page, toggle release type checkboxes per artist:

• Album (monitored by default)
• Single
• EP
• Broadcast
• Other

Changes take effect immediately. The feed updates on next refresh.

3. Subscribe to the feed

On the Releases page, use the RSS Feed button to get the feed URL:

• RSS: http://your-instance/feed/rss.xml
• OPML: http://your-instance/feed/opml

The feed includes:

• Release title and artist name
• Cover art from Cover Art Archive
• Release type (Album, Single, etc.)
• First release date
• Link to MusicBrainz release group page

4. Settings

Click the ⚙️ icon in the navbar to configure:

• Cache refresh interval (6, 8, 12, or 24 hours)
• Default release types for newly added artists

---

Architecture

Browser (HTMX + daisyUI)        RSS Reader
       │                            │
       │ HTML fragments             │ RSS/XML
       ▼                            ▼
┌──────────────────────────────────────┐
│        Quarkus HTTP Server            │
│  ┌────────┐  ┌────────┐  ┌────────┐  │
│  │ Qute   │  │ REST   │  │ RSS    │  │
│  │ Pages  │  │ API    │  │ Feed   │  │
│  └───┬────┘  └───┬────┘  └───┬────┘  │
│      └───────────┼────────────┘       │
│                  ▼                    │
│         Service Layer                 │
│  ArtistService · ReleaseGroupService  │
│  FeedService · CacheService          │
│         │              │             │
│  ┌──────┴──────┐ ┌─────┴──────┐      │
│  │ SQLite      │ │ MusicBrainz│      │
│  │ (raw JDBC)  │ │ REST       │      │
│  └─────────────┘ └────────────┘      │
└──────────────────────────────────────┘

Stack

Layer	Technology
Framework	Quarkus 3.x
Language	Java 21
Templating	Qute + HTMX 2.x
CSS	daisyUI 4.x (Tailwind CSS)
Database	SQLite via raw JDBC
RSS	Rome (rometools)
Build	Maven
Deployment	Docker (JVM)

---

API Endpoints

Pages

Endpoint	Description
GET /	Releases feed page
GET /artists	Tracked artists management page

HTMX API

Method	Endpoint	Description
GET	/api/artists/search?q=	Artist search autocomplete (HTML fragment)
POST	/api/artists/{mbid}/track	Add artist to tracking
DELETE	/api/artists/{mbid}	Remove artist
PATCH	/api/artists/{mbid}/monitor?type=	Toggle release type monitoring
GET	/api/artists/list	Tracked artists list (HTML fragment)
GET	/api/artists/feed-table	Feed entries table (HTML fragment)
GET	/api/settings/form	Settings form (HTML fragment)
PATCH	/api/settings	Save settings

RSS / Export

Endpoint	Description
GET	/feed/rss.xml
GET	/feed/opml

---

Data Model

Two SQLite tables:

• tracked_artist — Artists you're tracking with per-type monitoring flags
• release_group_cache — Cached release groups from MusicBrainz
• settings — Key-value app settings (cache TTL, default types)

Database file location is configurable via DISC_DROP_DB_PATH.

---

Comparison: mbz-rss-feeder → DiscDrop

Feature	mbz-rss-feeder (Flask)	DiscDrop (Quarkus)
Multiple feeds	Yes	Single unified feed
Tracks	Individual releases	Release groups (no duplicates)
Artist search	Simple list	Autocomplete with disambiguation
Type filtering	None	Per-artist monitoring (Album/Single/EP etc.)
RSS order	Newest first	Chronological ascending by release date
Theme	Plain CSS	daisyUI themes (7 themes)
Cache	File-based	Database-level TTL cache
Persistence	YAML files	SQLite (zero infra)

---

Development

Prerequisites

• Java 21 (Corretto or OpenJDK)
• Apache Maven 3.9+

Build

mvn clean package

Run tests

mvn test

Live reload

mvn quarkus:dev

Changes to Java source and templates are hot-reloaded.

---

License

MIT