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

### Docker Compose

```bash
docker compose up -d

---

## 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](https://musicbrainz.org/doc/MusicBrainz_API/Rate_Limiting#Provide_meaningful_User-Agent_strings). 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` | RSS 2.0 feed |
| `GET` | `/feed/opml` | OPML subscription file |

---

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

```bash
mvn clean package

Run tests

mvn test

Live reload

mvn quarkus:dev

Changes to Java source and templates are hot-reloaded.

---

License

MIT