embycovers/README.md

# Emby Thumbnail Generator

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.

## What it does

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

## Templates

- **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

## Background Modes

- **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

## Setup

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

2. Build and run:
   ```bash
   docker compose up -d --build
   ```

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:

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

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.

## Notes

- 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

## Tech Stack

- **Backend:** Python, FastAPI, Pillow, rembg (U2-Net)
- **Frontend:** Vanilla HTML/CSS/JS
- **Deployment:** Docker