mbirnbach/plex-overlay repository overview

⁠Plex-Overlay

A lightweight, self-contained Docker container that listens to Plex webhooks and displays the currently playing movie or TV show poster on a public image URL — ideal for use in dashboards like DAKboard, hallway displays, or home automation setups.

⁠📦 What It Does

• Listens for media.play, media.resume, and media.stop Plex webhooks
• Filters out trailers, extras, and Plex preroll content (type: clip)
• Automatically selects the right image:
  • For movies: uses the movie poster
  • For TV episodes: uses the show poster (grandparentThumb)
• Resizes and centers the image onto a configurable canvas (e.g. 1080x1920) with black background to avoid cropping
• Replaces image with a transparent placeholder when nothing is playing
• Serves the image directly via HTTP — no external volume or second container needed

⁠🚀 Quick Start

⁠Run via Docker

docker run -d \
  --name plex-overlay \
  -e PLEX_HOST=http://192.168.1.10:32400 \
  -e PLEX_TOKEN=your_plex_token \
  -e CANVAS_WIDTH=1080 \
  -e CANVAS_HEIGHT=1920 \
  -e WEBHOOK_PORT=8080 \
  -e STATIC_PORT=8081 \
  -p 8080:8080 \
  -p 8081:8081 \
  youruser/plex-overlay:latest

Then:

• Set Plex webhook URL to:
  http://<your-host>:8080/webhook

• Set your dashboard image URL (e.g. DAKboard) to:
  http://<your-host>:8081/now-playing.png

⁠⚙️ Environment Variables

⁠🧩 How It Works

1. Receives Plex webhook
2. Parses metadata
3. Ignores clips/trailers
4. Downloads the appropriate poster image
5. Resizes and centers it onto a black canvas
6. Saves it as now-playing.png and serves it via HTTP

When nothing is playing, it replaces the image with a fully transparent placeholder.

⁠🖥 Example Use Case

You have a vertically mounted hallway display running DAKboard. This container provides a "Now Playing" poster overlay that appears only while media is playing on Plex — with no need for remote access, no authentication mess, and no third-party tools.

⁠💡 Notes

• Transparent placeholder is included inside the container
• No volume mounts required
• No dependencies on other containers
• Optimized for privacy and simplicity

⁠🔗 Source Code

GitHub: https://github.com/mbirnbach/plex-overlay⁠

Enjoy classy movie night vibes. 🍿🖼️📺