Update postergeist.py

# Changelog

All notable changes to **Postergeist** will be documented in this file.

---

## [1.3.0] - 2025-09-22
### Added
- **Animated Overlay Support**
  - Overlays can now be `.gif` and `.apng` files in addition to static images.
  - Frame-based animation support with correct duration handling.
- **Overlay Behavior Enhancements**
  - Overlays suppressed automatically when posters/videos nearly fill the entire display.
  - Overlays animate independently of the slideshow.
- **Performance Mode**
  - New `--performance-mode` flag disables heavy visual effects (like glow blur).
  - Optimized for low-powered devices such as Raspberry Pi.
- **Glow Effect**
  - Posters now have an optional glow effect (Gaussian blur behind the poster).
- **Cached Video Background**
  - Video backgrounds are blurred and cached for smoother playback.
- **New CLI Options**
  - `--fade-height`: sets the fade height at the bottom of posters as a percentage (default: 20).
  - `--performance-mode`: disables glow and other intensive effects.

### Changed
- **Overlay Handling**
  - Rewritten to support both static and animated overlays.
  - Uses separate scheduling for overlays (`overlay_job`) and slides (`slideshow_job`).
- **Image Processing**
  - Split into `prepare_base_frame()` (background + poster) and `_update_canvas()` (final composition with overlays).
- **Fade Transition Logic**
  - Now handled by `fade_to_new_slide()` for smoother overlay-aware blending.
- **Rotation**
  - Rotating posters resets cached video backgrounds to prevent blur misalignment.

### Removed
- Replaced the older single-pass overlay system with a more robust animated overlay management system.

---

## [1.2.0] - 2025-09-17
### Added
- **Initial slideshow engine** with image & video support.
- **Overlay support** for static `.png`/`.jpg` images.
- **Fade transitions** between slides.
- **Rotation support** via keyboard shortcut.
- **Multi-display support** with fullscreen or windowed mode.
- **Randomized slide delay** option.
- **Splash screen** when no media is available.

Author: pasiegel

postergeist.py

@@ -2,7 +2,7 @@
 import random
 import argparse
 import cv2
-from PIL import Image, ImageTk, ImageFilter
+from PIL import Image, ImageTk, ImageFilter, ImageSequence
 import tkinter as tk
 from screeninfo import get_monitors
 
@@ -12,26 +12,43 @@
 # -----------------------------------------
 
 class Postergeist:
-    FRAME_INTERVAL_MS = 1000 // 30  # Approx 30 FPS
+    FRAME_INTERVAL_MS = 1000 // 30
 
-    def __init__(self, root, folder, overlay_folder, delay, random_delay, start_rotation, fade_duration=1000):
+    def __init__(self, root, folder, overlay_folder, delay, random_delay, start_rotation, fade_duration=1000,
+                 fade_height=20, performance_mode=False):
         self.root = root
         self.folder = folder
         self.overlay_folder = overlay_folder
         self.delay = delay
         self.random_delay = random_delay
+        self.fade_height_percent = fade_height
+        # --- NEW ---
+        self.performance_mode = performance_mode
 
         self.files = self.load_files(folder)
         self.overlays = self.load_overlays(overlay_folder)
 
         self.running = True
         self.video_capture = None
         self.tk_img = None
-        self.current_pil_img = None
+
+        # --- State Management ---
+        self.current_pil_img_no_overlay = None
+        self.current_pil_img_final = None
         self.rotation = start_rotation
         self.index = 0
-        self.after_id = None
-        self.splash_text_id = None
+        self.suppress_overlay = False
+        self.cached_video_background = None
+
+        # --- Job Scheduling IDs ---
+        self.slideshow_job = None
+        self.overlay_job = None
+
+        # --- Overlay Animation State ---
+        self.active_overlay_path = None
+        self.active_overlay_frames = []
+        self.active_overlay_index = 0
+        self.active_overlay_duration = 100
 
         self.fade_duration = fade_duration
         self.fade_steps = 20
@@ -62,7 +79,7 @@ def load_files(self, folder):
             return []
 
     def load_overlays(self, overlay_folder):
-        exts = (".png", ".jpg", ".jpeg", ".webp")
+        exts = (".png", ".jpg", ".jpeg", ".webp", ".gif", ".apng")
         overlays = []
         if overlay_folder and os.path.exists(overlay_folder):
             for f in os.listdir(overlay_folder):
@@ -82,57 +99,87 @@ def refresh_files(self):
             self.shuffle_files()
             self.show_file()
 
-    def prepare_image_frame(self, img_to_process):
+    def prepare_base_frame(self, img_to_process, is_video=False):
         screen_w = self.root.winfo_width()
         screen_h = self.root.winfo_height()
-
         is_portrait_rot = self.rotation in [90, 270]
         canvas_w = screen_h if is_portrait_rot else screen_w
         canvas_h = screen_w if is_portrait_rot else screen_h
 
-        background = img_to_process.resize((canvas_w, canvas_h), Image.LANCZOS).filter(ImageFilter.GaussianBlur(40))
+        if is_video and self.cached_video_background:
+            background = self.cached_video_background.copy()
+        else:
+            background = img_to_process.resize((canvas_w, canvas_h), Image.LANCZOS).filter(ImageFilter.GaussianBlur(40))
+            if is_video:
+                self.cached_video_background = background.copy()
 
         poster = img_to_process.copy()
         poster.thumbnail((canvas_w, canvas_h), Image.LANCZOS)
-        poster_x = (canvas_w - poster.width) // 2
+        p_w, p_h = poster.size
+
+        if p_h >= canvas_h * 0.99:
+            self.suppress_overlay = True
+        else:
+            self.suppress_overlay = False
+            # --- MODIFIED: Glow effect is skipped in performance mode ---
+            if not self.performance_mode:
+                glow = poster.filter(ImageFilter.GaussianBlur(25))
+                glow_x = (canvas_w - p_w) // 2
+                glow_y = 5
+                background.paste(glow, (glow_x, glow_y), glow)
+
+        poster_x = (canvas_w - p_w) // 2
         poster_y = 0
-        background.paste(poster, (poster_x, poster_y))
+        background.paste(poster, (poster_x, poster_y), poster)
+        self.current_pil_img_no_overlay = background
 
-        if self.overlays and poster.height < canvas_h:
-            overlay_path = random.choice(self.overlays)
+    def _update_canvas(self):
+        if not self.current_pil_img_no_overlay:
+            return
+        img_with_overlay = self.current_pil_img_no_overlay.copy()
+        if self.active_overlay_path and not self.suppress_overlay:
             try:
-                with Image.open(overlay_path) as overlay_img:
-                    overlay = overlay_img.copy()
-                    overlay.thumbnail((canvas_w, canvas_h // 3), Image.LANCZOS)
-                    overlay_x = (canvas_w - overlay.width) // 2
-                    overlay_y = canvas_h - overlay.height
-                    if overlay.mode in ("RGBA", "LA"):
-                        background.paste(overlay, (overlay_x, overlay_y), overlay)
-                    else:
-                        background.paste(overlay, (overlay_x, overlay_y))
+                overlay_img = None
+                if self.active_overlay_frames:
+                    overlay_img = self.active_overlay_frames[self.active_overlay_index]
+                else:
+                    overlay_img = Image.open(self.active_overlay_path)
+                canvas_w = img_with_overlay.width
+                canvas_h = img_with_overlay.height
+                overlay = overlay_img.copy()
+                overlay.thumbnail((canvas_w, canvas_h // 3), Image.LANCZOS)
+                overlay_x = (canvas_w - overlay.width) // 2
+                overlay_y = canvas_h - overlay.height
+                if overlay.mode in ("RGBA", "LA"):
+                    img_with_overlay.paste(overlay, (overlay_x, overlay_y), overlay)
+                else:
+                    img_with_overlay.paste(overlay, (overlay_x, overlay_y))
             except Exception as e:
-                print(f"Error loading overlay {os.path.basename(overlay_path)}: {e}")
+                print(f"Error processing overlay {os.path.basename(self.active_overlay_path)}: {e}")
+                self.active_overlay_path = None
 
         if self.rotation != 0:
-            final_img = background.rotate(self.rotation, expand=True)
+            final_img = img_with_overlay.rotate(self.rotation, expand=True)
         else:
-            final_img = background
-
-        return final_img
+            final_img = img_with_overlay
+        self.current_pil_img_final = final_img
+        self.tk_img = ImageTk.PhotoImage(final_img)
+        self.canvas.delete("all")
+        self.canvas.create_image(self.root.winfo_width() // 2, self.root.winfo_height() // 2, image=self.tk_img)
 
-    def fade_to_image(self, new_img, old_img):
-        if old_img is None or self.fade_duration == 0:
-            self.tk_img = ImageTk.PhotoImage(new_img)
-            self.canvas.delete("all")
-            self.canvas.create_image(self.root.winfo_width() // 2, self.root.winfo_height() // 2, image=self.tk_img)
+    def fade_to_new_slide(self, new_base_img):
+        old_final_img = self.current_pil_img_final
+        self.current_pil_img_no_overlay = new_base_img
+        self._update_canvas()
+        new_final_img = self.current_pil_img_final
+        if old_final_img is None or self.fade_duration == 0:
             return
-
         step_delay = self.fade_duration // self.fade_steps
 
         def do_step(step=0):
             if not self.running and step > 0: return
             alpha = step / self.fade_steps
-            blended = Image.blend(old_img, new_img, alpha)
+            blended = Image.blend(old_final_img, new_final_img, alpha)
             self.tk_img = ImageTk.PhotoImage(blended)
             self.canvas.delete("all")
             self.canvas.create_image(self.root.winfo_width() // 2, self.root.winfo_height() // 2, image=self.tk_img)
@@ -141,27 +188,57 @@ def do_step(step=0):
 
         do_step()
 
+    def _select_new_overlay(self):
+        self.active_overlay_path = None
+        self.active_overlay_frames = []
+        self.active_overlay_index = 0
+        if self.overlays:
+            self.active_overlay_path = random.choice(self.overlays)
+            if self.active_overlay_path.lower().endswith((".gif", ".apng")):
+                try:
+                    with Image.open(self.active_overlay_path) as img:
+                        self.active_overlay_duration = img.info.get('duration', 100)
+                        self.active_overlay_frames = [frame.copy() for frame in ImageSequence.Iterator(img)]
+                except Exception as e:
+                    print(f"Error loading animated overlay {os.path.basename(self.active_overlay_path)}: {e}")
+                    self.active_overlay_path = None
+
     def show_image(self, path):
-        old_img = self.current_pil_img
+        self.cached_video_background = None
+        self._select_new_overlay()
         try:
             with Image.open(path) as img:
-                img_rgb = img.convert("RGB")
-                final_frame = self.prepare_image_frame(img_rgb)
-                self.current_pil_img = final_frame
-                self.fade_to_image(final_frame, old_img)
+                img_rgba = img.convert("RGBA")
+                self.prepare_base_frame(img_rgba, is_video=False)
+                self.fade_to_new_slide(self.current_pil_img_no_overlay)
         except Exception as e:
             print(f"Error processing image '{os.path.basename(path)}': {e}. Skipping.")
-            self.after_id = self.root.after(100, self.next_slide)
+            self.slideshow_job = self.root.after(100, self.next_slide)
             return
-        self.after_id = self.root.after(self.get_delay(), self.next_slide)
+        if self.active_overlay_frames:
+            self._animate_overlay()
+        self.slideshow_job = self.root.after(self.get_delay(), self.next_slide)
 
     def show_video(self, path):
+        self.cached_video_background = None
         if self.video_capture: self.video_capture.release()
         self.video_capture = cv2.VideoCapture(path)
         if not self.video_capture.isOpened():
             print(f"Error opening video '{os.path.basename(path)}'. Skipping.")
             self.root.after(100, self.next_slide)
             return
+
+        vid_w = self.video_capture.get(cv2.CAP_PROP_FRAME_WIDTH)
+        vid_h = self.video_capture.get(cv2.CAP_PROP_FRAME_HEIGHT)
+        screen_w = self.root.winfo_width()
+        screen_h = self.root.winfo_height()
+        if vid_w < screen_w * 0.95 or vid_h < screen_h * 0.95:
+            self._select_new_overlay()
+        else:
+            self.active_overlay_path = None
+            self.active_overlay_frames = []
+        if self.active_overlay_frames:
+            self._animate_overlay()
         self.update_video_frame()
 
     def update_video_frame(self):
@@ -170,35 +247,36 @@ def update_video_frame(self):
         if not ret:
             self.video_capture.release()
             self.video_capture = None
-            self.after_id = self.root.after(self.get_delay(), self.next_slide)
+            self.slideshow_job = self.root.after(self.get_delay(), self.next_slide)
             return
-
-        frame_rgb = cv2.cvtColor(frame, cv2.COLOR_BGR2RGB)
-        img = Image.fromarray(frame_rgb)
-        final_frame = self.prepare_image_frame(img)
-        self.current_pil_img = final_frame
-        self.tk_img = ImageTk.PhotoImage(final_frame)
-        self.canvas.delete("all")
-        self.canvas.create_image(self.root.winfo_width() // 2, self.root.winfo_height() // 2, image=self.tk_img)
+        frame_rgba = cv2.cvtColor(frame, cv2.COLOR_BGR2RGBA)
+        img = Image.fromarray(frame_rgba)
+        self.prepare_base_frame(img, is_video=True)
+        self._update_canvas()
         self.root.after(self.FRAME_INTERVAL_MS, self.update_video_frame)
 
+    def _animate_overlay(self):
+        if not self.running or not self.active_overlay_frames: return
+        self.active_overlay_index = (self.active_overlay_index + 1) % len(self.active_overlay_frames)
+        self._update_canvas()
+        self.overlay_job = self.root.after(self.active_overlay_duration, self._animate_overlay)
+
     def get_delay(self):
         if self.random_delay:
             return random.randint(60, 300) * 1000
         else:
             return self.delay * 1000
 
-    def cancel_scheduled_next_slide(self):
-        if self.after_id:
-            self.root.after_cancel(self.after_id)
-            self.after_id = None
+    def cancel_scheduled_jobs(self):
+        if self.slideshow_job:
+            self.root.after_cancel(self.slideshow_job)
+        if self.overlay_job:
+            self.root.after_cancel(self.overlay_job)
+        self.slideshow_job = None
+        self.overlay_job = None
 
     def show_file(self):
-        if self.splash_text_id:
-            self.root.unbind("<Configure>")
-            self.splash_text_id = None
-
-        self.cancel_scheduled_next_slide()
+        self.cancel_scheduled_jobs()
         if not self.files:
             self.show_splash()
             return
@@ -224,7 +302,10 @@ def toggle_pause(self):
         if self.running:
             self.next_slide(manual=True)
         else:
-            self.cancel_scheduled_next_slide()
+            self.cancel_scheduled_jobs()
+            if self.video_capture:
+                self.video_capture.release()
+                self.video_capture = None
 
     def exit_slideshow(self):
         self.running = False
@@ -233,7 +314,13 @@ def exit_slideshow(self):
 
     def rotate_poster(self):
         self.rotation = (self.rotation + 90) % 360
-        self.show_file()
+        self.cached_video_background = None
+        if self.video_capture and self.video_capture.isOpened():
+            self.show_file()
+        else:
+            # Need to reload the static image to redraw it
+            if self.files:
+                self.show_image(self.files[self.index])
 
     def show_splash(self):
         w = self.root.winfo_width()
@@ -262,12 +349,17 @@ def on_resize_splash(self, event):
 def main():
     parser = argparse.ArgumentParser(description="Postergeist Slideshow")
     parser.add_argument("folder", nargs="?", default="posters", help="Folder with posters/videos")
-    parser.add_argument("--overlays", default="overlays", help="Folder with overlay images")
+    parser.add_argument("--overlays", default="overlays", help="Folder with overlay images/gifs/apngs")
     parser.add_argument("--delay", type=int, default=300, help="Delay between slides in seconds")
     parser.add_argument("--random-delay", action="store_true", help="Enable random delay between 1–5 minutes")
     parser.add_argument("--display", type=str, default="1", help="Which display to use (1, 2, 'all')")
     parser.add_argument("--windowed", action="store_true", help="Run in a window")
     parser.add_argument("--rotate", type=int, default=0, choices=[0, 90, 180, 270], help="Starting rotation")
+    parser.add_argument("--fade-height", type=int, default=20,
+                        help="Fade height at bottom of poster as a percentage (e.g., 20)")
+    # --- NEW ARGUMENT ---
+    parser.add_argument("--performance-mode", action="store_true",
+                        help="Disable intensive effects like glow for better performance")
     args = parser.parse_args()
 
     if not os.path.exists(args.folder):
@@ -303,7 +395,8 @@ def main():
         root.overrideredirect(True)
         root.config(cursor="none")
 
-    Postergeist(root, args.folder, overlay_folder, args.delay, args.random_delay, args.rotate)
+    Postergeist(root, args.folder, overlay_folder, args.delay, args.random_delay, args.rotate,
+                fade_height=args.fade_height, performance_mode=args.performance_mode)
     root.mainloop()