Pixelfin – Jellyfin Image Inspector

Do you want your images on your Jellyfin instance to be perfect?

Do you ever wonder which image types you're missing or are low resolution?

Do you want an easy way to back up your Jellyfin library images?

Pixelfin is a lightweight Flask app paired with a generator script that lets you quickly create HTML galleries of your Jellyfin libraries. It highlights which image types — such as Primary, ClearArt, Backdrops, Logos, and more — are present, which are missing, and which fall below a minimum resolution threshold you specify. The result is a clean, scrollable gallery with clickable images, accompanied by a summary table showing missing and low-resolution images. In addition, Pixelfin lets you bundle images into either embedded HTML files or ZIP archives, choose exactly which ones to include, and even override filenames so you can save them under names that fit your own organization.

---

Screenshots

Dark Mode

Light Mode

All Image Types - Summary Table

All Image Types - Entry with Missing Images

Certain Image Types - Summary Table

Certain Image Types - Entry with No Missing Images

Certain Image Types - Entry with Missing Images

Certain Image Types - Entry with Low Resolution Images

Certain Image Types - Entry with Both a Missing Image and a Low Resolution Image

Lightbox with Navigation

Pick Your Colors 1

Pick Your Colors 2

Pick Your Colors 3

🙋 About This Project

This project is functional, not perfect or polished.

If you try it out:

• Depending on the size of the library, it can take some time to generate an HTML or ZIP file.
• If it doesn't work on http://localhost:1280 try http://<local-ip>:1280

I vibe-coded this project entirely with ChatGPT, because I have literally zero coding experience. It works for me, and I actively use it to keep track of artwork across my Jellyfin instance. If you’re more experienced with coding than I am (which is basically everyone), you’ll almost certainly see ways to improve it. Contributions, fixes, and feedback are all very welcome.

✨ Features

Interactive Web Interface

• Connect with your Jellyfin server using your API key and selected library name
• Choose gallery colors and image types to include
• Generate new HTML reports or ZIP files with a single click
• Browse previously generated galleries, download them with embedded images, or delete them
• Download or delete previously generated ZIP files
• Light and dark mode

Clean, Actionable Galleries

• Summary table at the top showing missing/low-resolution types; click an item’s title to jump directly to it
• Each library item displayed with its available images
  • Each item’s title links directly to its Jellyfin page for quick editing
  • Left column: Primary, Thumb, ClearArt, Menu
  • Right column: Backdrop, Banner, Box, BoxRear, Disc, Logo
  • Image type and resolution labels under each image
  • Missing images highlighted with red placeholders
  • Low-resolution images flagged with red captions
  • Missing or low-resolution image types clearly listed in red on the bottom left
  • “Scroll to top” links for easy navigation
  • Clickable images with a lightbox viewer (Prev / Next / Close)

Custom ZIP Exports

• Bundle selected images into a downloadable ZIP archive
• Override filenames so images are saved under your preferred naming scheme
• Perfect for exporting, reorganizing, or sharing artwork outside Jellyfin

---

🚀 Installation (Without Docker)

Requirements

• Python 3.9+
• Pip
• A Jellyfin server + API key

Install dependencies

pip install flask pillow requests

Run the app

python app.py

Then open your browser to:

http://localhost:1280

If that doesn't work, try:

http://<local-ip>:1280

---

🐳 Running with Docker

If you prefer Docker, you can run it without installing Python locally.

Build the image

docker build -t ghcr.io/nothing2obvi/pixelfin:latest .

Run the container

1. Change directory to wherever you want Pixelfin to live:

cd /path/to/pixelfin

2. Start the container

docker run -d \
  -p 1280:1280 \
  -e TZ=America/Chicago \
  -v ./output:/app/output \
  -v ./data:/app/data \
  ghcr.io/nothing2obvi/pixelfin:latest

output/ will store the generated HTML and ZIP files.

data/history.json will persist your server/library selections and other settings.

3. Open Pixelfin

Go to: http://localhost:1280 to access Pixelfin. If it doesn't work on http://localhost:1280 try http://<local-ip>:1280

---

🐙 Docker Compose

Here’s a simple docker-compose.yml:

services:
  pixelfin:
    image: ghcr.io/nothing2obvi/pixelfin:latest
    container_name: pixelfin
    ports:
      - "1280:1280"
    environment:
      - TZ=America/Chicago
    volumes:
      - ./output:/app/output
      - ./data:/app/data
    restart: unless-stopped

Run it with:

docker compose up -d

Go to: http://localhost:1280 to access Pixelfin. If it doesn't work on http://localhost:1280 try http://<local-ip>:1280

---

🛠 How It Works

1. Start the app (python app.py or via Docker). See About this Project if it’s not working.
2. Fill in:
   • Server URL – your Jellyfin base URL (e.g. http://192.168.1.100:8096)
   • Library Name – the library you want to inspect (e.g. Movies)
   • API Key – create this in Jellyfin’s admin dashboard
   • Pick the colors, image types, and optional minimum resolution thresholds you want
3. Hit Generate.
   • A background thread runs generate_html.py, which talks to Jellyfin’s API, fetches all your items, and checks every image type.
   • A timestamped .html file gets saved under output/<LibraryName>/.
4. Browse results:
   • View the gallery in your browser
   • Click an item’s title to jump directly into Jellyfin and fix missing images
   • Download an “embedded” version where all images are base64-encoded (for sharing/archiving)
5. Create ZIP files of your images (optional):
   • Select which images you want to bundle into a .zip archive
   • Use the Filename Override column in the table to rename images before exporting
   • Handy for reorganizing or sharing artwork outside Jellyfin

⚡ Note: The Resolution columns are only used when generating HTML galleries, while the Filename Override column applies only when creating ZIP archives. All 3 columns are optional. If the resolution columns are left empty, Pixelfin won't flag any images as having low resolution.

---

📝 Note About Embedded HTML Files

• When opening the downloaded, embedded HTML files directly from your filesystem, you may see bits of text like class="...", alt="...", or loading="lazy" appearing beneath the images. This is just a browser rendering quirk and does not affect how the gallery works.
• For a clean viewing experience, place the HTML files inside the /output directory of your Pixelfin instance — either within one of the existing library folders or a new folder you create (it must be inside a folder). The files will then appear on the main page, and selecting View will display them properly.

---

⚠️ Limitations

• Error handling is minimal
• Only tested with my setup (Mac + Jellyfin 10.10.7)
• Only tested with the following library types: Shows, Movies, Music Videos, Music

---

🤝 Want to Contribute?

Pixelfin is a work in progress, and contributions from the community are what make it better!

Some Ideas for Features / Improvements

• Enhance the UI and make it sleeker
• Add a way to "check off" media items as completed
• Create a dashboard tab showing completed vs. pending items, with links to each item in Jellyfin
• AI upscale low-resolution images to chosen resolutions (individually or in bulk) and update them directly in Jellyfin
• One-click to fill in gaps with images of selected resolutions

Have an idea or want to help out? Open a pull request -- it’d awesome to see these features come to life together.

---

📝 License

MIT – feel free to use, modify, and share.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

LoV432 💻

avassor 🤔 👀

This project follows the all-contributors specification. Contributions of any kind welcome!