259 lines
7.5 KiB
Markdown
259 lines
7.5 KiB
Markdown
# 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
|