# HomelabToolkit

A self-hosted control room for your media stack. HomelabToolkit pairs an Emby
artwork toolkit with a Navidrome music-library manager behind one beautiful React
UI, served by a FastAPI backend.

## Categories

### Emby
- **Thumbnail Generator** — composite landscape thumbnails from posters, logos and
  backdrops (subject-aware), then push them back to Emby as custom Thumb images.
- **Collection Art** — design Thumb/Primary cover artwork for your collections.
- **Airing & New Seasons** — track currently-airing series and stamp "New Season"
  artwork on eligible premieres.
- **Bulk Assign** — generate and apply thumbnails across the whole library, plus
  per-studio artwork resets.
- **User Favorites** — browse collections with per-user watched status, prune
  watched items, and top up with recommendations (dry-run by default).

### Navidrome
- **Music Library** — browse artists and albums over the Subsonic API.
- **Cover Manager** — the former `music-covers.py` script, now a web tool: scan the
  library, normalize album folders, rename tracks, remove stray files, and fetch
  missing covers/lyrics. **Runs in dry-run mode by default** — nothing on disk
  changes until you explicitly switch to apply mode.

## Architecture

- **Backend:** Python, FastAPI, Pillow, rembg (U2-Net). API-only; serves the built
  SPA and owns every `/api/*` route.
- **Frontend:** React + TypeScript + Vite (`frontend/`), built to `frontend/dist`.
- **Music tooling:** mutagen + musicbrainzngs + Cover Art Archive + LRCLIB.

## Configuration (environment variables)

| Variable | Purpose |
| --- | --- |
| `EMBY_URL` | Emby server URL |
| `EMBY_API_KEY` | Emby API key |
| `NAVIDROME_URL` | Navidrome server URL (Subsonic API) |
| `NAVIDROME_USER` | Navidrome username |
| `NAVIDROME_PASSWORD` | Navidrome password |
| `MUSIC_ROOT` | Path to the music library for the Cover Manager |
| `TMDB_BEARER_TOKEN` / `TMDB_API_KEY` | Optional artwork providers |
| `GOOGLE_CUSTOM_SEARCH_API_KEY` / `..._ENGINE_ID` | Optional artwork search |

## Run with Docker (recommended)

1. Edit `docker-compose.yml` with your Emby/Navidrome details and mount your music
   share to match `MUSIC_ROOT`.
2. Build and run:
   ```bash
   docker compose up -d --build
   ```
   The image builds the React SPA in a Node stage, then serves it from FastAPI.
3. Open `http://localhost:8500`.

## Local development

Backend:
```bash
pip install -r requirements.txt
python app.py            # http://localhost:8500
```

Frontend (hot reload, proxies /api to :8500):
```bash
cd frontend
npm install
npm run dev              # http://localhost:5173
```

Production build of the SPA (served by FastAPI):
```bash
cd frontend && npm run build
```

## Deploy to a NAS

`deploy.ps1` syncs the project (including the `frontend/` source) over SSH and runs
`docker compose build && up -d` remotely. The frontend is built inside the image:
```powershell
.\deploy.ps1 -NasHost MATT-NAS -NasUser ssh
```