RadioDJ-Album-art-downloader/README.md

# RDJ Art Manager 🎵

A production-ready, open-source web app to find, review, and apply **missing album artwork** for a [RadioDJ](https://www.radiodj.ro/) MySQL database.

- 🔍 **Free artwork lookup** — iTunes Search API first, MusicBrainz + Cover Art Archive fallback. No API keys, no credit cards.
- 🗂 **Multi-user with roles** — embedded SQLite (better-sqlite3) stores accounts and per-user RadioDJ connection profiles. First registered user becomes the **admin**.
- 🔐 **Secure by default** — scrypt password hashing, AES-256-GCM encrypted DB passwords, HttpOnly session cookies, rate-limited auth endpoints.
- 🎛 **Spreadsheet-style review grid** — preview artwork candidates per track, pick the right cover, filter, auto-search.
- 📦 **ZIP export** — images renamed to the base audio filename (`01 Track.mp3` → `01 Track.jpg`), plus an `export-report.json` manifest.
- 🗄 **Optional DB update** — sets `songs.image` in the RadioDJ database to the new file name.
- 🐳 **Docker** — one `docker compose up` with `./data` persisted.

## Quick start

### Local (Node.js ≥ 20)

```bash
npm install
npm start
# open http://localhost:3000
```

### Docker

```bash
docker compose up -d --build
# open http://localhost:3000
```

SQLite data is persisted in `./data` (mapped to `/app/data` in the container).

## Configuration

| Env var         | Default      | Description                                                                 |
| --------------- | ------------ | --------------------------------------------------------------------------- |
| `PORT`          | `3000`       | HTTP port.                                                                   |
| `DATA_DIR`      | `./data`     | Where the SQLite database lives.                                             |
| `APP_SECRET`    | *(auto)*     | **Set this in production** (min 16 chars). Encrypts stored RadioDJ DB passwords. If unset, a random secret is generated at `data/.app-secret`. Changing it makes stored DB passwords unreadable. |
| `COOKIE_SECURE` | `0`          | Set to `1` when serving over HTTPS so session cookies get the `Secure` flag. |
| `LOG_LEVEL`     | `info`       | `error`, `warn`, `info`, or `debug`. Selection and export summaries are logged at `info`; per-track export details and conversions are logged at `debug`. Logs go to stdout (terminal and Docker logs). |

## Usage

1. **Register** — the first account becomes the `admin`.
2. Open **Profiles** and add a RadioDJ MySQL connection (host, port, database, user, password). Use **Test** to verify connectivity — it also reports how many tracks are missing artwork.
3. Pick the station in the header dropdown and click **Load tracks missing artwork**. The query matches tracks where `song_type = 0` and `image` is `NULL`, empty, **or a RadioDJ default placeholder** (`%no_cover%`, `%no_image%`, `%no-cover%` — case-insensitive).
4. Pick a **primary art source** in the header (Auto chains iTunes → Deezer → MusicBrainz, or pin a single API), use the grid **pagination bar** (page size 10/25/30/50/all, prev/next, numbered pages), and correct the editable **Title**, **Artist**, or **Album** fields if needed before searching. These corrections are temporary, stay available while paging through the current load, and are used only for artwork searches; reloading tracks or refreshing the page discards them. They are never written to RadioDJ. Click **Search artwork** per row (or **Fetch Art for Current Page** for the whole page) to get artwork candidates. The final upload-icon option on each row lets you add a local PNG/JPEG/WebP image (up to 15 MB) or provide a direct image URL. Custom artwork goes through the same full-size preview and confirmation flow as search results. Hover a thumbnail to see its source (native tooltip), click it to open the **full-size preview overlay** (title, artist, source, “View Original Image”, and **✓ Confirm & Select This Art** — close with backdrop click or `Esc`). A row only becomes exportable once you tick its checkbox; fetching art never checks the box for you. Exports support up to 20 local uploads at a time. Confirmed artwork selections are logged with track ID and source; set `LOG_LEVEL=debug` for per-track export details.
5. Click **Download ZIP & Update Database**:
   - Uncheck **Update RadioDJ DB** to only download the ZIP.
   - When checked, the app runs `UPDATE songs SET image = '<new file name>' WHERE id = <song id>` for every successfully exported item. Exported images are always RadioDJ-compatible `.jpg` or `.png`; WebP sources (including URLs and uploads) are converted to JPEG.
6. Copy the images from the ZIP into the folder configured in RadioDJ under *Options → Options → Album Art*, so RadioDJ picks them up.

> **Note:** RadioDJ's `songs.image` column stores just the artwork file name (relative to its album-art folder). That is exactly what this app writes.
> Artwork logs do not include image URLs or file contents. Unsupported formats are reported as export errors rather than added to the ZIP.

Tracks without selected artwork display the bundled `Album-Art.png` in the web interface. It is only a visual fallback and is not selected, exported, or written to RadioDJ automatically.

### Admin

The admin header button opens the administration panel:

- List all users and change roles (`user` ⇄ `admin`). You can't change your own role or demote the last admin.
- Copy (clone) all station profiles from one user to another — encrypted passwords carry over.

## API overview

| Method | Endpoint                          | Description                                             |
| ------ | --------------------------------- | ------------------------------------------------------- |
| POST   | `/api/auth/register`              | Register (first user becomes admin).                    |
| POST   | `/api/auth/login` / `logout`      | Session auth (HttpOnly cookie).                         |
| GET    | `/api/auth/me`                    | Current session user.                                   |
| GET/POST | `/api/profiles`                 | List / create RadioDJ connection profiles.              |
| PUT/DELETE | `/api/profiles/:id`           | Update (blank password keeps stored one) / delete.      |
| POST   | `/api/profiles/:id/test`          | Test MySQL connectivity + count missing artwork.        |
| GET    | `/api/tracks?profileId=&page=&limit=` | Tracks missing artwork (`song_type=0` and `image` NULL/empty or a `no_cover`/`no_image`/`no-cover` placeholder); `limit=all` disables paging. Returns `{tracks,totalTracks,page,totalPages}`. |
| POST   | `/api/artwork/search`             | `{artist,title,album,source}` — source `auto` chains iTunes → Deezer → MusicBrainz/CAA; or `itunes`/`deezer`/`musicbrainz` only. |
| POST   | `/api/export`                     | JSON for URL artwork, or multipart form data with a JSON `payload` and uploaded artwork files → ZIP download + optional DB update. |
| GET    | `/api/admin/users`                | (admin) List users.                                     |
| PUT    | `/api/admin/users/:id/role`       | (admin) Change role.                                    |
| POST   | `/api/admin/clone-profiles`       | (admin) Copy all profiles between users.                |
| GET    | `/api/health`                     | Health check (used by Docker HEALTHCHECK).              |

## Project layout

```
├── server.js            # Express backend: auth, profiles, MySQL pools, artwork search, ZIP export
├── public/index.html    # Single-page Tailwind dashboard (vanilla JS)
├── Album-Art.png        # Web-interface fallback for tracks without selected artwork
├── data/                # SQLite storage (git-ignored, volume-mapped in Docker)
├── Dockerfile
├── docker-compose.yml
├── smoke-test.ps1       # Optional API smoke test (run while the server is up)
└── package.json
```

## Security notes

- Passwords: scrypt (N=16384) + constant-time comparison.
- RadioDJ DB passwords: AES-256-GCM encrypted at rest; never returned by the API.
- Sessions: random 256-bit tokens in SQLite, HttpOnly + SameSite=Lax cookies, 7-day expiry.
- Auth endpoints are rate-limited; all API routes require authentication; admin routes require the `admin` role.
- SQL access is parameterized; the RadioDJ connection user only needs `SELECT`/`UPDATE` on the `songs` table.

## License

MIT — see [LICENSE](LICENSE).