Homelabtoolkit v1
This commit is contained in:
@@ -1,97 +1,84 @@
|
||||
# Emby Thumbnail Generator
|
||||
# HomelabToolkit
|
||||
|
||||
A self-hosted web UI that generates landscape thumbnails from your Emby library posters. Uses AI-powered subject extraction (rembg/U2-Net, runs entirely locally) to isolate characters from poster art, then composites them into widescreen thumbnails with customisable layouts.
|
||||
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.
|
||||
|
||||
## What it does
|
||||
## Categories
|
||||
|
||||
1. Connects to your Emby server via API
|
||||
2. Search/browse your movie and TV library
|
||||
3. Pulls the poster for a selected item
|
||||
4. Extracts the subject (person/character) using rembg (offline, no external API)
|
||||
5. Generates a landscape thumbnail with the subject positioned to one side and the title on the other
|
||||
6. Optionally pushes the generated thumbnail back to Emby as a custom Thumb image
|
||||
### 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).
|
||||
|
||||
## Templates
|
||||
### 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.
|
||||
|
||||
- **Subject Left, Text Right** — character on the left, title text on the right
|
||||
- **Subject Right, Text Left** — character on the right, title text on the left
|
||||
- **Subject Center, Text Overlay** — character centered with title overlaid
|
||||
## Architecture
|
||||
|
||||
## Background Modes
|
||||
- **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.
|
||||
|
||||
- **Auto Gradient** — samples dominant colours from the poster and creates a dark gradient
|
||||
- **Blurred Poster** — darkened, heavily blurred version of the original poster
|
||||
- **Solid Colour** — pick your own background colour
|
||||
## Configuration (environment variables)
|
||||
|
||||
## Setup
|
||||
| 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 |
|
||||
|
||||
### Docker (recommended)
|
||||
|
||||
1. Edit `docker-compose.yml` with your Emby details:
|
||||
```yaml
|
||||
environment:
|
||||
- EMBY_URL=http://192.168.1.x:8096
|
||||
- EMBY_API_KEY=your-api-key
|
||||
```
|
||||
## 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`.
|
||||
|
||||
3. Open `http://localhost:8500`
|
||||
|
||||
### Manual
|
||||
|
||||
1. Install dependencies:
|
||||
```bash
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
2. Set environment variables:
|
||||
```bash
|
||||
export EMBY_URL=http://192.168.1.x:8096
|
||||
export EMBY_API_KEY=your-api-key
|
||||
```
|
||||
|
||||
3. Run:
|
||||
```bash
|
||||
python app.py
|
||||
```
|
||||
|
||||
4. Open `http://localhost:8500`
|
||||
|
||||
## Getting your Emby API Key
|
||||
|
||||
1. Open Emby Dashboard → Advanced → API Keys
|
||||
2. Click "New API Key"
|
||||
3. Give it a name (e.g. "Thumb Generator")
|
||||
4. Copy the key
|
||||
|
||||
## Optional Artwork Providers
|
||||
|
||||
The artwork editor always supports Emby images and Wikimedia Commons. You can enable additional search providers with environment variables:
|
||||
## Local development
|
||||
|
||||
Backend:
|
||||
```bash
|
||||
export TMDB_BEARER_TOKEN=your-tmdb-read-access-token
|
||||
# or: export TMDB_API_KEY=your-tmdb-v3-api-key
|
||||
|
||||
export GOOGLE_CUSTOM_SEARCH_API_KEY=your-google-api-key
|
||||
export GOOGLE_CUSTOM_SEARCH_ENGINE_ID=your-google-search-engine-id
|
||||
pip install -r requirements.txt
|
||||
python app.py # http://localhost:8500
|
||||
```
|
||||
|
||||
TMDB is the preferred external artwork source for posters and backdrops. Google Custom Search is optional and only uses Google's official Custom Search JSON API.
|
||||
Frontend (hot reload, proxies /api to :8500):
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev # http://localhost:5173
|
||||
```
|
||||
|
||||
## Notes
|
||||
Production build of the SPA (served by FastAPI):
|
||||
```bash
|
||||
cd frontend && npm run build
|
||||
```
|
||||
|
||||
- First generation will be slower as rembg downloads the U2-Net model (~170MB)
|
||||
- The model runs entirely offline after first download — no data leaves your network
|
||||
- Generated thumbnails are cached in the `cache/` directory
|
||||
- Works with both movies and TV series
|
||||
- The "Apply to Emby" button sets the generated image as the item's Thumb image type
|
||||
## Deploy to a NAS
|
||||
|
||||
## Tech Stack
|
||||
|
||||
- **Backend:** Python, FastAPI, Pillow, rembg (U2-Net)
|
||||
- **Frontend:** Vanilla HTML/CSS/JS
|
||||
- **Deployment:** Docker
|
||||
`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
|
||||
```
|
||||
|
||||
Reference in New Issue
Block a user