# DiscDrop

> Self-hosted RSS feed generator for [MusicBrainz](https://musicbrainz.org) 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

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

The app starts at [http://localhost:8080](http://localhost:8080).

### Production (JAR)

```bash
# 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.

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

```bash
mvn test
```

### Live reload

```bash
mvn quarkus:dev
```

Changes to Java source and templates are hot-reloaded.

---

## License

MIT