server.py

#!/usr/bin/env python3
"""
Church Media Player - Web Edition
-----------------------------------
Runs on the church media PC and serves a browser-based control page so
the playlist can be operated from any device on the same LAN (laptop,
tablet, phone) while audio plays through this machine's PA output.

This process is the single source of truth for playback -- it's the
only thing that ever touches VLC directly. Both the browser control
page AND the desktop app (church_player.py, running in client mode)
talk to this same server over HTTP, so there's never a risk of two
separate players fighting over the audio/video output: whichever
control surface you use, you're controlling the exact same live
session. Keep this running permanently (see the systemd setup notes
below) so mobile control works even when nobody's at the church PC.

Two separate libraries are supported: a Music folder (background
worship music, which may include mp4 files played as audio-only by
default) and a Video folder (standalone video content, e.g. course
sessions, shown with video on the church PC's screen by default). A
"Show video" toggle lets you switch either kind of file between
audio-only and video-visible. When video is shown, it automatically
opens fullscreen on your second display (the projector) if one is
detected via xrandr -- see "Choose Video Display" in either control
surface if auto-detection picks the wrong screen.

Note: showing video requires this process to have access to the
church PC's actual display (the same way it needed access to its
audio session -- see the audio troubleshooting notes in the README).
If the video toggle doesn't produce a visible window, that's the
first thing to check.

If the process is stopped or restarted (e.g. "systemctl restart") while
a Stop fade-out is still in progress, the volume is restored to normal
before the process exits, so it can never be left faded down.

Dependencies:
  sudo apt install vlc
  pip install Flask python-vlc

Run with:
  python3 server.py
"""

import atexit
import json
import os
import re
import signal
import subprocess
import sys
import threading
import time

from flask import Flask, jsonify, render_template, request

try:
    import vlc
except ImportError:
    print("python-vlc is required. Install it with: pip install python-vlc")
    sys.exit(1)


CONFIG_DIR = os.path.join(os.path.expanduser("~"), ".config", "church_player")
CONFIG_FILE = os.path.join(CONFIG_DIR, "config.json")

MEDIA_EXTENSIONS = {
    ".mp3", ".wav", ".flac", ".ogg", ".m4a", ".aac", ".wma",
    ".mp4", ".mkv", ".avi", ".mov", ".wmv", ".webm",
}
VIDEO_EXTENSIONS = {".mp4", ".mkv", ".avi", ".mov", ".wmv", ".webm"}

# The two libraries this app manages.
LIBRARIES = ("music", "video")

# Matches a trailing "(...)" group at the end of a filename, e.g.
# "Amazing Grace (John Newton)" -> song="Amazing Grace", artist="John Newton"
ARTIST_PATTERN = re.compile(r"^(.*?)\s*\(([^()]+)\)\s*$")

FADE_OUT_SECONDS = 3.0
FADE_TICK_SECONDS = 0.05
# How far down (in dB) the fade-out ramps VLC's internal equalizer
# preamp. This is deliberately NOT the same as the volume PulseAudio
# sees (see the fade mechanism notes on _fade_worker for why).
FADE_PREAMP_MIN_DB = -20.0
# How many libvlc calls must hang back-to-back before we conclude the
# instance is wedged and rebuild it (see _note_vlc_timeout).
VLC_TIMEOUTS_BEFORE_REBUILD = 3

PORT = 5000


def load_config():
    if os.path.exists(CONFIG_FILE):
        try:
            with open(CONFIG_FILE, "r") as f:
                return json.load(f)
        except (json.JSONDecodeError, OSError):
            pass
    return {}


def save_config(cfg):
    os.makedirs(CONFIG_DIR, exist_ok=True)
    with open(CONFIG_FILE, "w") as f:
        json.dump(cfg, f, indent=2)


def parse_song_and_artist(filename_no_ext):
    match = ARTIST_PATTERN.match(filename_no_ext)
    if match:
        song = match.group(1).strip()
        artist = match.group(2).strip()
        if song:
            return song, artist
    return filename_no_ext, ""


def is_video_file(path):
    if not path:
        return False
    ext = os.path.splitext(path)[1].lower()
    return ext in VIDEO_EXTENSIONS


def scan_media_folder(folder):
    """Scan a folder for media files, including one level of
    subfolders. Returns a list of (subfolder_name, filename, full_path)
    tuples -- subfolder_name is "" for files directly in the root
    folder. Root-level files come first, then each subfolder's files
    (grouped together, subfolders in alphabetical order). Only goes one
    level deep -- subfolders inside subfolders are not scanned."""
    entries = []

    def is_media(name):
        return os.path.splitext(name)[1].lower() in MEDIA_EXTENSIONS

    try:
        top_level = sorted(os.listdir(folder))
    except OSError:
        return entries

    for name in top_level:
        full = os.path.join(folder, name)
        if os.path.isfile(full) and is_media(name):
            entries.append(("", name, full))

    for name in top_level:
        full = os.path.join(folder, name)
        if not os.path.isdir(full):
            continue
        try:
            sub_names = sorted(os.listdir(full))
        except OSError:
            continue
        for sub_name in sub_names:
            sub_full = os.path.join(full, sub_name)
            if os.path.isfile(sub_full) and is_media(sub_name):
                entries.append((name, sub_name, sub_full))

    return entries


SCREEN_LINE_PATTERN = re.compile(
    r"^(\S+) connected (primary )?(\d+)x(\d+)\+(\d+)\+(\d+)"
)
# Physical size, e.g. "410mm x 230mm", reported at the end of an
# xrandr "connected" line. A real monitor reports a non-zero physical
# size; "0mm x 0mm" is a strong hint the output is a stale/phantom
# entry rather than a display anyone can actually see.
PHYSICAL_SIZE_PATTERN = re.compile(r"(\d+)mm x (\d+)mm")


def detect_screens():
    """Detect connected displays via xrandr (X11 only). Returns a list
    of dicts: {index, name, width, height, x, y, primary}. Returns an
    empty list if xrandr isn't available or nothing could be parsed
    (e.g. on Wayland) -- callers should treat that as "can't reposition,
    just show video wherever VLC opens it by default"."""
    try:
        result = subprocess.run(
            ["xrandr", "--query"], capture_output=True, text=True, timeout=3
        )
        output = result.stdout
    except Exception as e:
        print(f"[church-player] xrandr detection failed: {e}")
        return []

    screens = []
    for line in output.splitlines():
        m = SCREEN_LINE_PATTERN.match(line)
        if not m:
            continue
        name, is_primary, w, h, x, y = m.groups()
        size_m = PHYSICAL_SIZE_PATTERN.search(line)
        phys_w = int(size_m.group(1)) if size_m else 0
        phys_h = int(size_m.group(2)) if size_m else 0
        screens.append({
            "index": len(screens),
            "name": name,
            "width": int(w),
            "height": int(h),
            "x": int(x),
            "y": int(y),
            "primary": bool(is_primary),
            # A real, physically present monitor reports its size in mm.
            # Outputs reporting 0mm x 0mm are usually stale/ghost entries
            # (a disconnected adapter, a virtual output, etc.) -- they
            # show as "connected" but nobody can actually see them, so
            # auto-selection should avoid them.
            "physical_mm": (phys_w, phys_h),
            "likely_real": phys_w > 0 and phys_h > 0,
        })
    return screens


class XVideoWindow:
    """A single, reusable, borderless (override-redirect) X11 window
    that VLC's video output is embedded into directly, at a position
    and size we control completely.

    override_redirect means the window manager never touches this
    window at all -- no re-snapping to "the current monitor," no
    decorations, no focus-stealing, no interference of any kind. This
    replaces the previous approach of letting VLC open its own window
    and then hunting it down afterward with xdotool to move and
    fullscreen it, which depended on window-manager behavior outside
    our control and could race with VLC's own window setup -- that's
    what caused the wrong-monitor and hung-fullscreen-call problems.

    This mirrors exactly what the desktop app already does
    successfully (embedding video into a Qt-owned window it creates
    and positions itself, before playback starts) -- just implemented
    directly against X11 since this process has no GUI toolkit.
    "Fullscreen" is just this window's geometry matching the target
    monitor exactly; there's no separate libvlc fullscreen call
    involved, so that entire failure mode goes away.
    """

    def __init__(self):
        self._display = None
        self._window = None

    def _ensure_connected(self):
        if self._display is not None:
            return True
        try:
            from Xlib import display
            self._display = display.Display()
            return True
        except Exception as e:
            print(f"[church-player] couldn't connect to X server for the "
                  f"video window: {e}")
            self._display = None
            return False

    def show(self, x, y, width, height):
        """Create the window if it doesn't exist yet, or reposition
        and resize it if it does; make sure it's mapped and raised.
        Returns the window's X11 id (for player.set_xwindow()), or
        None if anything went wrong -- callers should fall back to
        letting VLC open its own window in that case."""
        if not self._ensure_connected():
            return None
        try:
            from Xlib import X
            width = max(1, int(width))
            height = max(1, int(height))
            if self._window is None:
                screen = self._display.screen()
                self._window = screen.root.create_window(
                    int(x), int(y), width, height, 0,
                    screen.root_depth,
                    X.InputOutput,
                    X.CopyFromParent,
                    background_pixel=screen.black_pixel,
                    override_redirect=1,
                    event_mask=X.StructureNotifyMask,
                )
                self._window.map()
            else:
                self._window.configure(
                    x=int(x), y=int(y), width=width, height=height,
                    stack_mode=X.Above,
                )
                self._window.map()
            self._window.configure(stack_mode=X.Above)
            self._display.sync()
            return self._window.id
        except Exception as e:
            print(f"[church-player] video window show() failed: {e}")
            # Drop everything so the next call reconnects from scratch
            # rather than retrying against a possibly-broken connection.
            self._display = None
            self._window = None
            return None

    def hide(self):
        if self._display is None or self._window is None:
            return
        try:
            self._window.unmap()
            self._display.sync()
        except Exception as e:
            print(f"[church-player] video window hide() failed: {e}")
            self._display = None
            self._window = None


class PlayerState:
    """Holds both playlists and wraps the VLC player. All access goes
    through `lock` (an RLock, so helper methods can call each other
    safely while already holding it)."""

    def __init__(self):
        self.lock = threading.RLock()
        self.config = load_config()
        self.folders = {
            "music": self.config.get("music_folder", ""),
            "video": self.config.get("video_folder", ""),
        }

        # --aout=pulse: force PulseAudio explicitly rather than letting
        # VLC auto-detect, since auto-detection can pick plain ALSA in
        # this systemd-service context and silently miss the PA system.
        # No --no-video here (unlike before) -- video is now controlled
        # per-track via a ":no-video" media option, so the instance
        # itself stays capable of showing video when asked to.
        # (No --quiet here on purpose, so audio-device errors show up
        # in the terminal instead of being suppressed.)
        self.vlc_instance = vlc.Instance(["--aout=pulse"])
        self.player = self.vlc_instance.media_player_new()

        self.playlists = {"music": [], "video": []}  # each: {id, song, artist, path}
        self.next_id = 1
        self.current_id = None
        self.current_list = None
        self.video_enabled = False
        self.desired_volume = 80
        self.player.audio_set_volume(self.desired_volume)

        # Bumped every time play() starts a (new or replacement) track.
        # Background operations that apply their effects after a delay
        # (the fade-out worker, the post-play reassertion timers)
        # capture the generation active when they were scheduled and
        # check it's still current before touching anything -- this
        # stops a stale operation left over from a track that's already
        # been superseded from clobbering whatever's actually playing
        # now (e.g. an old fade finishing just as a new track starts,
        # muting/stopping the NEW track instead of doing nothing).
        self.generation = 0

        # Watchdog state for recovering a wedged libvlc instance.
        self.consecutive_vlc_timeouts = 0
        self.rebuilding = False

        # Used for the Stop fade-out. Deliberately a preamp (an
        # internal VLC gain stage), NOT the PulseAudio-visible stream
        # volume -- see the notes on _fade_worker for why that matters.
        self.fade_equalizer = vlc.AudioEqualizer()

        # Which physical display to show video on. None means
        # "auto-detect" (prefer whichever screen isn't the primary
        # one). Set explicitly via /api/video_screen if auto-detection
        # guesses wrong for your setup. Identified by NAME (e.g.
        # "HDMI-1"), not list position -- a numeric index recomputed
        # fresh from xrandr's current output order isn't stable enough
        # once there are 3+ displays involved, since the order it's
        # reported in can shift between the moment you pick one and the
        # moment we actually need it.
        self.video_screen_name = self.config.get("video_screen_name")

        # Our own borderless window video is embedded into (see
        # XVideoWindow). True = sized to cover the whole target
        # monitor ("fullscreen"); False = a small preview window in
        # its corner. Purely a matter of this window's geometry -- no
        # libvlc fullscreen call is involved.
        self.video_window = XVideoWindow()
        self.video_fullscreen = True

        self.fading = False

        # Auto-advance to the next song when the current one finishes
        # naturally (not on manual Stop, which is a different event).
        # VLC fires this on its own internal thread, so we hand off to a
        # fresh Python thread rather than doing playback work directly
        # inside the callback.
        self.player.event_manager().event_attach(
            vlc.EventType.MediaPlayerEndReached, self._on_end_reached
        )

        for kind in LIBRARIES:
            if self.folders[kind] and os.path.isdir(self.folders[kind]):
                self.rescan(kind)

    # ------------------------------------------------------------------
    # Playlist scanning
    # ------------------------------------------------------------------
    def rescan(self, kind=None):
        with self.lock:
            kinds = LIBRARIES if kind is None else (kind,)
            for k in kinds:
                folder = self.folders.get(k, "")
                self.playlists[k] = []
                if not folder or not os.path.isdir(folder):
                    continue
                for subfolder, name, full_path in scan_media_folder(folder):
                    base_name = os.path.splitext(name)[0]
                    song, artist = parse_song_and_artist(base_name)
                    self.playlists[k].append({
                        "id": self.next_id,
                        "song": song,
                        "artist": artist,
                        "folder": subfolder,
                        "path": full_path,
                    })
                    self.next_id += 1

    def set_folder(self, kind, folder):
        with self.lock:
            self.folders[kind] = folder
            self.config[f"{kind}_folder"] = folder
            save_config(self.config)
            self.rescan(kind)

    def reorder(self, kind, id_order):
        with self.lock:
            playlist = self.playlists[kind]
            by_id = {item["id"]: item for item in playlist}
            new_list = [by_id[i] for i in id_order if i in by_id]
            missing = [item for item in playlist if item["id"] not in id_order]
            self.playlists[kind] = new_list + missing

    def _find_track(self, track_id):
        """Search both libraries for a track id. Returns
        (kind, index, item) or None."""
        for kind in LIBRARIES:
            for idx, item in enumerate(self.playlists[kind]):
                if item["id"] == track_id:
                    return kind, idx, item
        return None

    def move_to_top(self, kind, track_id):
        with self.lock:
            playlist = self.playlists[kind]
            item = next((t for t in playlist if t["id"] == track_id), None)
            if item is None:
                return
            playlist.remove(item)
            playlist.insert(0, item)

    # ------------------------------------------------------------------
    # Playback
    # ------------------------------------------------------------------
    def _target_screen(self):
        """Figure out which physical display should show video, or
        None if we can't tell (e.g. xrandr unavailable/Wayland) -- in
        that case VLC just opens wherever it opens by default.

        Always re-detects fresh rather than trusting a cache, and
        matches by display NAME rather than list position -- see the
        comment on video_screen_name for why."""
        screens = detect_screens()
        if not screens:
            return None

        if self.video_screen_name is not None:
            for s in screens:
                if s["name"] == self.video_screen_name:
                    return s
            print(f"[church-player] selected display {self.video_screen_name!r} "
                  f"not found among currently detected displays "
                  f"({[s['name'] for s in screens]}) -- falling back to auto")

        # Auto: prefer a non-primary display that looks physically real
        # (see "likely_real" in detect_screens -- an output reporting
        # 0mm x 0mm is usually a ghost/stale entry that nobody can
        # actually see, and picking it sends video into the void).
        for s in screens:
            if not s.get("primary") and s.get("likely_real", True):
                return s
        # Nothing non-primary looked real; fall back to any real display,
        # preferring a non-primary one, before giving up and using the
        # first entry.
        for s in screens:
            if s.get("likely_real", True):
                return s
        return screens[0]

    def _make_media(self, path, want_video):
        media = self.vlc_instance.media_new(path)
        if not want_video:
            media.add_option(":no-video")
        else:
            # Force software decoding. Hardware-accelerated decode/output
            # has shown real instability on some machines (failed VA-API
            # drivers, decode errors, and in the worst case a hung X
            # connection) -- software decoding is slower but far more
            # reliable for something that has to run unattended.
            media.add_option(":avcodec-hw=none")
        return media

    # ------------------------------------------------------------------
    # Safe wrappers around direct libvlc calls
    #
    # None of these ever run while self.lock is held, and the riskiest
    # ones (play/stop/fullscreen -- the calls that actually talk to the
    # X server) go through _call_with_timeout so that even a genuinely
    # hung call can't block the request that triggered it forever. This
    # matters because things outside our control can put VLC's video
    # output into a bad state -- e.g. force-closing its window with
    # Alt+F4, or a flaky graphics driver -- and when that happens we'd
    # rather have one action fail/time out than freeze the whole server
    # for every connected device.
    # ------------------------------------------------------------------
    def _call_with_timeout(self, func, timeout=3.0, name="vlc call"):
        result = {}

        def runner():
            try:
                result["value"] = func()
            except Exception as e:
                result["error"] = e

        t = threading.Thread(target=runner, daemon=True)
        t.start()
        t.join(timeout)
        if t.is_alive():
            print(f"[church-player] {name} did not return within {timeout}s -- "
                  f"giving up waiting on it (it may finish in the background, "
                  f"but we're not blocking on it any further)")
            self._note_vlc_timeout(name)
            return None
        if "error" in result:
            print(f"[church-player] {name} raised: {result['error']}")
            return None
        self._note_vlc_success()
        return result.get("value")

    def _note_vlc_success(self):
        with self.lock:
            self.consecutive_vlc_timeouts = 0

    def _note_vlc_timeout(self, name):
        """Track consecutive hung libvlc calls and rebuild the player
        when they pile up.

        A single slow call is survivable, but once several in a row
        hang it means the underlying libvlc instance is wedged -- we've
        seen this happen when its X/video output gets into a bad state
        (a force-closed video window, a flaky graphics driver). Once
        wedged, EVERY subsequent call hangs, so nothing works until the
        process is restarted by hand. Rebuilding the instance and
        player in place recovers automatically instead."""
        with self.lock:
            self.consecutive_vlc_timeouts += 1
            count = self.consecutive_vlc_timeouts
            already_rebuilding = self.rebuilding

        if count >= VLC_TIMEOUTS_BEFORE_REBUILD and not already_rebuilding:
            with self.lock:
                self.rebuilding = True
            threading.Thread(target=self._rebuild_player, daemon=True).start()

    def _rebuild_player(self):
        """Throw away the wedged libvlc instance and build a fresh one.
        The old one is deliberately NOT released -- calling release()
        on a wedged instance can itself hang. We just drop our
        reference and let it be; leaking one dead instance is far
        better than an unusable player until someone restarts the
        service."""
        print("[church-player] libvlc appears wedged (several calls hung in a "
              "row) -- rebuilding the VLC instance to recover")
        try:
            new_instance = vlc.Instance(["--aout=pulse", "--avcodec-hw=none"])
            new_player = new_instance.media_player_new()
            new_equalizer = vlc.AudioEqualizer()
            new_player.event_manager().event_attach(
                vlc.EventType.MediaPlayerEndReached, self._on_end_reached
            )
            new_player.audio_set_volume(self.desired_volume)
        except Exception as e:
            print(f"[church-player] failed to rebuild VLC instance: {e}")
            with self.lock:
                self.rebuilding = False
                self.consecutive_vlc_timeouts = 0
            return

        with self.lock:
            self.vlc_instance = new_instance
            self.player = new_player
            self.fade_equalizer = new_equalizer
            self.current_id = None
            self.current_list = None
            self.video_enabled = False
            self.fading = False
            self.generation += 1
            self.consecutive_vlc_timeouts = 0
            self.rebuilding = False
        print("[church-player] VLC instance rebuilt -- press play to resume")

    def _safe_play(self):
        self._call_with_timeout(self.player.play, name="player.play()")

    def _safe_stop(self):
        self._call_with_timeout(self.player.stop, name="player.stop()")

    def _safe_set_media(self, media):
        self._call_with_timeout(lambda: self.player.set_media(media), name="player.set_media()")

    def _safe_set_xwindow(self, win_id):
        self._call_with_timeout(lambda: self.player.set_xwindow(win_id), name="player.set_xwindow()")

    def _safe_audio_set_volume(self, value):
        try:
            self.player.audio_set_volume(value)
        except Exception as e:
            print(f"[church-player] audio_set_volume failed: {e}")

    def _safe_set_preamp(self, db):
        """Adjust VLC's internal equalizer preamp (in dB). This is the
        fade mechanism -- it never touches the PulseAudio-visible
        stream volume, so it can't affect what an audio server
        "remembers" for next time. 0.0 = normal/unfaded."""
        try:
            self.fade_equalizer.set_preamp(db)
            self.player.set_equalizer(self.fade_equalizer)
        except Exception as e:
            print(f"[church-player] set_preamp failed: {e}")

    def _safe_set_mute(self, value):
        try:
            self.player.audio_set_mute(bool(value))
        except Exception as e:
            print(f"[church-player] audio_set_mute failed: {e}")

    def _safe_get_time(self):
        try:
            return self.player.get_time()
        except Exception as e:
            print(f"[church-player] get_time failed: {e}")
            return None

    def _safe_set_time(self, value):
        try:
            self.player.set_time(value)
        except Exception as e:
            print(f"[church-player] set_time failed: {e}")

    def _video_window_geometry(self, screen):
        if self.video_fullscreen:
            return screen["x"], screen["y"], screen["width"], screen["height"]
        # Windowed/preview mode: a small window in the target screen's
        # top-left corner, still on the correct monitor.
        w = max(320, screen["width"] // 4)
        h = max(180, screen["height"] // 4)
        return screen["x"], screen["y"], w, h

    def _apply_video_window(self):
        """Show our own window at the right place for the currently
        selected display and fullscreen/windowed state, and return its
        X11 id for player.set_xwindow(). Returns None if no display
        info is available or the window couldn't be created/positioned
        (e.g. no X connection) -- callers fall back to letting VLC
        open its own window in that case.

        This runs synchronously, before play() -- unlike the previous
        approach (find VLC's own window afterward and move it with
        xdotool), there's nothing to wait for here: we own the window,
        so positioning it is just a normal, fast, local X11 call with
        no race against window-manager behavior."""
        screen = self._target_screen()
        if screen is None:
            return None
        x, y, w, h = self._video_window_geometry(screen)
        win_id = self.video_window.show(x, y, w, h)
        if win_id:
            print(f"[church-player] video window on {screen['name']} "
                  f"at ({x},{y}) {w}x{h}")
        return win_id

    def _reassert_playback_state_soon(self, generation):
        """A moment after playback starts, reassert normal volume,
        preamp, and mute state -- once, then again a bit later for
        extra safety.

        Some of these settings don't reliably "stick" if applied
        before the new stream's audio pipeline actually exists:
        - Audio servers (PulseAudio/PipeWire's stream-restore) can
          apply a remembered volume to a brand new stream the instant
          it's created, silently overriding whatever we set beforehand
          (especially right after a fade left the last stream near
          zero).
        - VLC's own equalizer/preamp setting has shown the same kind
          of issue: setting it before play() doesn't always carry over
          once the new stream's pipeline spins up, which is what was
          causing the *next* track after a fade to start inaudible
          even though the volume slider looked correct.
        Reasserting again once the stream is confirmed live makes sure
        our values win either way.

        Only applies if `generation` still matches the current
        playback generation -- otherwise a newer play() has already
        superseded whatever this was scheduled for, and applying it now
        would be reasserting state for the WRONG (stale) track."""
        def _do():
            with self.lock:
                if generation != self.generation:
                    return
            self._safe_audio_set_volume(self.desired_volume)
            self._safe_set_preamp(0.0)
            self._safe_set_mute(False)
        threading.Timer(0.3, _do).start()
        threading.Timer(0.8, _do).start()

    def play(self, track_id, move_to_top=False, video_enabled=None):
        self.cancel_fade()

        with self.lock:
            found = self._find_track(track_id)
            if found is None:
                return False
            kind, idx, item = found

            if move_to_top:
                self.move_to_top(kind, track_id)

            # Video-folder items show video by default; music-folder
            # items (even mp4s) default to audio-only, unless the
            # caller explicitly requested a state.
            if video_enabled is None:
                video_enabled = (kind == "video")
            video_enabled = bool(video_enabled) and is_video_file(item["path"])
            path = item["path"]
            song = item["song"]

            # New generation: any background operation still working on
            # behalf of a previous track (a fade winding down, a delayed
            # reassertion) will see this and know to leave the new track
            # alone rather than muting/stopping it by mistake.
            self.generation += 1
            my_generation = self.generation

        # The actual VLC calls happen outside the lock, so a hang here
        # (e.g. a broken video output) can't block other clients.
        self._safe_set_preamp(0.0)  # start every track unfaded
        self._safe_set_mute(False)

        if video_enabled:
            # Position our own window BEFORE anything plays -- this is
            # synchronous and fast (a local X11 call), so there's no
            # timing window for it to race against anything else, and
            # nothing to search for or move afterward.
            win_id = self._apply_video_window()
        else:
            self.video_window.hide()
            win_id = None

        media = self._make_media(path, video_enabled)
        self._safe_set_media(media)
        if video_enabled and win_id:
            self._safe_set_xwindow(win_id)
        self._safe_audio_set_volume(self.desired_volume)
        self._safe_play()
        self._reassert_playback_state_soon(my_generation)

        with self.lock:
            self.current_id = track_id
            self.current_list = kind
            self.video_enabled = video_enabled

        print(f"[church-player] play requested: {song!r} "
              f"list={kind} video={video_enabled} path={path!r}")
        return True

    def toggle_pause(self):
        self.cancel_fade()
        try:
            self.player.pause()
        except Exception as e:
            print(f"[church-player] pause failed: {e}")

    def set_volume(self, value):
        value = max(0, min(100, int(value)))
        with self.lock:
            self.desired_volume = value
            fading = self.fading
        if not fading:
            self._safe_audio_set_volume(value)

    def seek(self, fraction):
        try:
            length = self.player.get_length()
        except Exception as e:
            print(f"[church-player] get_length failed: {e}")
            return
        if length and length > 0:
            fraction = max(0.0, min(1.0, fraction))
            self._safe_set_time(int(fraction * length))

    def set_video_enabled(self, value):
        """Toggle video on/off for whatever's currently playing. Only
        applies to actual video files; hot-swaps without losing your
        place if something is already playing."""
        self.cancel_fade()  # in case this is toggled mid-fade

        with self.lock:
            if self.current_id is None:
                return
            found = self._find_track(self.current_id)
            if found is None:
                return
            _, _, item = found
            if not is_video_file(item["path"]):
                return
            want = bool(value)
            if want == self.video_enabled:
                return
            path = item["path"]
            self.generation += 1
            my_generation = self.generation

        current_time = self._safe_get_time()
        self._safe_set_preamp(0.0)
        self._safe_set_mute(False)
        self._safe_stop()

        if want:
            win_id = self._apply_video_window()
        else:
            self.video_window.hide()
            win_id = None

        media = self._make_media(path, want)
        self._safe_set_media(media)
        if want and win_id:
            self._safe_set_xwindow(win_id)
        self._safe_audio_set_volume(self.desired_volume)
        self._safe_play()
        self._reassert_playback_state_soon(my_generation)

        with self.lock:
            self.video_enabled = want

        print(f"[church-player] video toggled: now {want}")
        if current_time and current_time > 0:
            threading.Timer(0.3, lambda: self._safe_set_time(current_time)).start()

    def set_fullscreen(self, value):
        """Toggle between covering the whole target monitor and a small
        preview window in its corner. Purely a matter of resizing our
        own window (see XVideoWindow) -- no libvlc call involved at
        all, so this can't hang the way the old approach (calling
        libvlc's own set_fullscreen(), directly touching the fragile
        X/video-output machinery) sometimes did."""
        with self.lock:
            self.video_fullscreen = bool(value)
            currently_showing = self.current_id is not None and self.video_enabled
        if currently_showing:
            self._apply_video_window()

    def refresh_screens(self):
        return detect_screens()

    def set_video_screen(self, name):
        """Change which display video shows on (by name, e.g. 'HDMI-1',
        or None for auto). If something's currently showing video,
        reposition it immediately -- this just moves our own window,
        so playback isn't interrupted at all."""
        with self.lock:
            self.video_screen_name = name
            self.config["video_screen_name"] = name
            save_config(self.config)
            currently_showing = self.current_id is not None and self.video_enabled
        if currently_showing:
            self._apply_video_window()

    def play_next(self):
        """Advance to the next track in the current library's order, if
        there is one. Called when a track finishes naturally."""
        print("[church-player] play_next() invoked")
        next_id = None
        with self.lock:
            if self.current_id is None or self.current_list is None:
                print("[church-player] play_next: nothing currently playing")
                return
            playlist = self.playlists[self.current_list]
            idx = next(
                (i for i, t in enumerate(playlist) if t["id"] == self.current_id),
                None,
            )
            if idx is None:
                print(f"[church-player] play_next: current_id {self.current_id} "
                      f"not found in {self.current_list} list, aborting")
                return
            next_idx = idx + 1
            print(f"[church-player] play_next: list={self.current_list} "
                  f"idx={idx}, next_idx={next_idx}, len={len(playlist)}")
            if next_idx < len(playlist):
                next_id = playlist[next_idx]["id"]
            else:
                print("[church-player] play_next: reached end of playlist")
                self.current_id = None
                self.current_list = None
                self.video_enabled = False

        if next_id is not None:
            self.play(next_id)  # outside the lock -- play() takes its own

    def _on_end_reached(self, event):
        # Runs on VLC's internal event thread. We deliberately wait a
        # short moment before calling back into libvlc: calling play()
        # again immediately from inside (or right at the tail end of)
        # this callback can silently no-op, because libvlc is often
        # still finishing its own internal teardown of the track that
        # just ended at the exact moment this fires.
        print("[church-player] MediaPlayerEndReached event received")
        threading.Timer(0.3, self.play_next).start()

    # ------------------------------------------------------------------
    # Fade-out on stop
    # ------------------------------------------------------------------
    def stop(self):
        with self.lock:
            if self.fading:
                return  # already fading out, let it finish
        try:
            state = self.player.get_state()
        except Exception as e:
            print(f"[church-player] get_state failed: {e}")
            state = None

        if state in (vlc.State.Playing, vlc.State.Paused):
            self._start_fade_out()
        else:
            self._safe_stop()
            with self.lock:
                self.current_id = None
                self.current_list = None
                self.video_enabled = False

    def _start_fade_out(self):
        with self.lock:
            # Bump the generation here too: this invalidates any
            # still-pending post-play reassertion timers from whatever
            # play() started the track now being faded out, so they
            # can't fire mid-fade and stomp the preamp back to 0,
            # undoing the fade.
            self.generation += 1
            my_generation = self.generation
            self.fading = True
        threading.Thread(target=self._fade_worker, args=(my_generation,), daemon=True).start()

    def _fade_worker(self, generation):
        """Ramps VLC's internal equalizer preamp down to near-silent
        over FADE_OUT_SECONDS, then stops.

        Deliberately does NOT touch audio_set_volume() (the
        PulseAudio-visible stream volume) during the ramp. On some
        systems, PulseAudio/PipeWire remember a stream's volume at the
        moment it closes and apply that remembered value to future
        streams -- so fading via that volume would either (a) leave
        the next playback silent if we let the fade finish naturally,
        or (b) cause an audible jump back up to full volume right
        before cutting off, if we tried to restore it just before
        stopping. The equalizer preamp is a gain stage entirely inside
        VLC's own audio pipeline, invisible to PulseAudio -- so it
        fades what you actually hear without ever giving anything
        wrong for the audio server to remember.

        Checks `generation` on every tick (not just `fading`) before
        touching anything: if a new play() has started a different
        track since this fade began, `fading` gets cleared by
        cancel_fade() as usual, but the generation check is a second,
        independent guard against the rare case where this worker is
        right on the verge of calling _finish_stop() (which would mute
        and stop) at the exact moment a new track starts -- without it,
        a stale fade finishing late could cut off/mute a track that
        only just started playing.
        """
        start_time = time.monotonic()
        while True:
            time.sleep(FADE_TICK_SECONDS)
            with self.lock:
                if not self.fading or generation != self.generation:
                    return  # cancelled, or superseded by a newer track
                elapsed = time.monotonic() - start_time
                done = elapsed >= FADE_OUT_SECONDS
                if not done:
                    fraction = elapsed / FADE_OUT_SECONDS
                    preamp = FADE_PREAMP_MIN_DB * fraction
            if done:
                with self.lock:
                    if generation != self.generation:
                        return  # superseded right at the finish line
                self._finish_stop()
                return
            self._safe_set_preamp(preamp)

    def _reset_system_output_volume(self):
        """Directly reset every detected OS-level audio sink's volume
        AND mute state via pactl, as a mechanism-agnostic safety net
        alongside our own libvlc volume calls.

        This exists because fading THIS app's stream volume down can,
        on some systems, bleed through into the shared system output
        level (flat-volumes / stream-restore-style behavior) -- and
        once that's happened, calling libvlc's own audio_set_volume()
        afterward isn't reliably enough to fix it, since there may be
        no live stream left for that call to act on (e.g. right after
        stop(), or at process exit). Directly resetting the shared
        sink(s) sidesteps whatever the exact underlying cause is, and
        matters beyond just this app -- a stuck-low or muted sink
        affects everything that plays audio on the machine, not just
        this player.

        Resets volume AND mute (a separate flag from volume -- 80%
        volume on a muted sink is still silent), and targets every
        sink pactl reports rather than just "@DEFAULT_SINK@", in case
        there's more than one audio device and the wrong one ends up
        being the actual default. Uses pactl since that works against
        both real PulseAudio and PipeWire's PulseAudio-compatible
        layer.
        """
        try:
            result = subprocess.run(
                ["pactl", "list", "short", "sinks"],
                capture_output=True, text=True, timeout=2,
            )
            sink_names = [
                line.split("\t")[1]
                for line in result.stdout.strip().splitlines()
                if line.strip() and "\t" in line
            ]
        except FileNotFoundError:
            print("[church-player] pactl not installed -- can't reset system "
                  "volume/mute. Install with: sudo apt install pulseaudio-utils")
            return
        except Exception as e:
            print(f"[church-player] pactl list sinks failed: {e}")
            sink_names = []

        targets = sink_names or ["@DEFAULT_SINK@"]
        for sink in targets:
            try:
                subprocess.run(
                    ["pactl", "set-sink-volume", sink, f"{self.desired_volume}%"],
                    capture_output=True, timeout=2,
                )
                subprocess.run(
                    ["pactl", "set-sink-mute", sink, "0"],
                    capture_output=True, timeout=2,
                )
            except Exception as e:
                print(f"[church-player] pactl reset failed for sink {sink!r}: {e}")
        print(f"[church-player] reset volume/mute on sink(s): {targets}")

    def _finish_stop(self):
        with self.lock:
            self.fading = False
        # The preamp fade has already brought the audible level down to
        # near-silent by this point (see _fade_worker). Deliberately do
        # NOT mute before stop() -- that reintroduces the exact same
        # bug volume had: whatever remembers a stream's state at the
        # moment it closes (PulseAudio/PipeWire stream-restore) would
        # remember "muted", and apply that to the NEXT stream created --
        # including a completely separate VLC window, not just this
        # app. So instead, set everything to its correct final state
        # BEFORE stopping, exactly like we do for volume.
        self._safe_set_mute(False)
        self._safe_set_preamp(0.0)
        self._safe_audio_set_volume(self.desired_volume)
        self._safe_stop()
        self._reset_system_output_volume()
        with self.lock:
            self.current_id = None
            self.current_list = None
            self.video_enabled = False

    def cancel_fade(self):
        """Abort an in-progress fade-out (e.g. because Play was pressed
        again, or video got toggled mid-fade) and immediately return to
        normal, unfaded playback."""
        with self.lock:
            if not self.fading:
                return
            self.fading = False
        self._safe_set_preamp(0.0)

    def restore_volume_now(self):
        """Unconditionally push the volume back to its normal level and
        clear any fade state, regardless of what was happening.
        Used as a shutdown safety net so the process can never exit
        (whether stopped normally, restarted by systemd, or killed)
        while a fade-out has left things quiet -- on many systems an
        app's own volume changes affect the shared system volume, so
        this matters beyond just this app."""
        with self.lock:
            self.fading = False
        self._safe_set_mute(False)
        self._safe_set_preamp(0.0)
        self._safe_audio_set_volume(self.desired_volume)
        self._reset_system_output_volume()

    # ------------------------------------------------------------------
    # Status snapshot for the frontend
    # ------------------------------------------------------------------
    def snapshot(self):
        # Query the player itself OUTSIDE the shared lock. These calls
        # can in principle hang if the underlying graphics driver/X
        # connection wedges (see _note_vlc_timeout) -- if that ever
        # happens, it should only affect the one request doing the
        # querying, not freeze the shared lock that every other API
        # call (from every other client) also needs.
        try:
            vlc_state = self.player.get_state()
        except Exception:
            vlc_state = None
        try:
            length = self.player.get_length()
        except Exception:
            length = 0
        try:
            current = self.player.get_time()
        except Exception:
            current = 0
        # "fullscreen" is now purely our own window's geometry (see
        # XVideoWindow / video_fullscreen) rather than a libvlc call --
        # nothing to query here that could hang.
        fullscreen = self.video_fullscreen

        is_playing = vlc_state == vlc.State.Playing
        is_paused = vlc_state == vlc.State.Paused
        if length is None or length < 0:
            length = 0
        if current is None or current < 0:
            current = 0

        with self.lock:
            current_item = None
            if self.current_id is not None:
                found = self._find_track(self.current_id)
                if found is not None:
                    current_item = found[2]

            return {
                "playlists": {
                    kind: [
                        {"id": t["id"], "song": t["song"], "artist": t["artist"], "folder": t.get("folder", "")}
                        for t in self.playlists[kind]
                    ]
                    for kind in LIBRARIES
                },
                "current_id": self.current_id,
                "current_list": self.current_list,
                "current_song": current_item["song"] if current_item else None,
                "current_artist": current_item["artist"] if current_item else None,
                "current_is_video": is_video_file(current_item["path"]) if current_item else False,
                "video_enabled": self.video_enabled,
                "fullscreen": fullscreen,
                "playing": is_playing,
                "paused": is_paused,
                "fading": self.fading,
                "elapsed_ms": current,
                "length_ms": length,
                "volume": self.desired_volume,
                "folders": dict(self.folders),
                "video_screen_name": self.video_screen_name,
            }


state = PlayerState()

app = Flask(__name__)


@app.route("/")
def index():
    return render_template("index.html")


@app.route("/api/state")
def api_state():
    return jsonify(state.snapshot())


@app.route("/api/play", methods=["POST"])
def api_play():
    data = request.get_json(force=True) or {}
    track_id = data.get("id")
    move_to_top = bool(data.get("move_to_top", False))
    if track_id is None:
        return jsonify({"error": "missing id"}), 400
    ok = state.play(int(track_id), move_to_top=move_to_top)
    if not ok:
        return jsonify({"error": "track not found"}), 404
    return jsonify(state.snapshot())


@app.route("/api/pause", methods=["POST"])
def api_pause():
    state.toggle_pause()
    return jsonify(state.snapshot())


@app.route("/api/stop", methods=["POST"])
def api_stop():
    state.stop()
    return jsonify(state.snapshot())


@app.route("/api/volume", methods=["POST"])
def api_volume():
    data = request.get_json(force=True) or {}
    value = data.get("value")
    if value is None:
        return jsonify({"error": "missing value"}), 400
    state.set_volume(value)
    return jsonify(state.snapshot())


@app.route("/api/seek", methods=["POST"])
def api_seek():
    data = request.get_json(force=True) or {}
    fraction = data.get("fraction")
    if fraction is None:
        return jsonify({"error": "missing fraction"}), 400
    state.seek(float(fraction))
    return jsonify(state.snapshot())


@app.route("/api/video", methods=["POST"])
def api_video():
    data = request.get_json(force=True) or {}
    value = data.get("value")
    if value is None:
        return jsonify({"error": "missing value"}), 400
    state.set_video_enabled(bool(value))
    return jsonify(state.snapshot())


@app.route("/api/fullscreen", methods=["POST"])
def api_fullscreen():
    data = request.get_json(force=True) or {}
    value = data.get("value")
    if value is None:
        return jsonify({"error": "missing value"}), 400
    state.set_fullscreen(bool(value))
    return jsonify(state.snapshot())


@app.route("/api/screens")
def api_screens():
    screens = state.refresh_screens()
    return jsonify({"screens": screens, "selected_name": state.video_screen_name})


@app.route("/api/video_screen", methods=["POST"])
def api_video_screen():
    data = request.get_json(force=True) or {}
    name = data.get("name", None)  # null/None means "auto"
    state.set_video_screen(name if name else None)
    return jsonify(state.snapshot())


@app.route("/api/reorder", methods=["POST"])
def api_reorder():
    data = request.get_json(force=True) or {}
    kind = data.get("list")
    order = data.get("order")
    if kind not in LIBRARIES:
        return jsonify({"error": "missing or invalid 'list'"}), 400
    if not isinstance(order, list):
        return jsonify({"error": "missing order"}), 400
    state.reorder(kind, [int(i) for i in order])
    return jsonify(state.snapshot())


@app.route("/api/settings", methods=["POST"])
def api_settings():
    data = request.get_json(force=True) or {}
    kind = data.get("list")
    folder = (data.get("folder") or "").strip()
    if kind not in LIBRARIES:
        return jsonify({"error": "missing or invalid 'list'"}), 400
    if not folder:
        return jsonify({"error": "missing folder"}), 400
    if not os.path.isdir(folder):
        return jsonify({"error": f"'{folder}' is not a valid folder on the server machine"}), 400
    state.set_folder(kind, folder)
    return jsonify(state.snapshot())


@app.route("/api/refresh", methods=["POST"])
def api_refresh():
    data = request.get_json(silent=True) or {}
    kind = data.get("list")
    state.rescan(kind if kind in LIBRARIES else None)
    return jsonify(state.snapshot())


def _handle_shutdown_signal(signum, frame):
    print(f"[church-player] received signal {signum}, restoring volume before exit")
    state.restore_volume_now()
    sys.exit(0)


def main():
    # Safety net: whether we're stopped normally (Ctrl+C), restarted by
    # systemd, or killed outright, make sure the volume is never left
    # faded down from an in-progress Stop.
    signal.signal(signal.SIGTERM, _handle_shutdown_signal)
    signal.signal(signal.SIGINT, _handle_shutdown_signal)
    atexit.register(state.restore_volume_now)

    print(f"Church Media Player web server starting on port {PORT}...")
    print("On this machine, open: http://localhost:%d" % PORT)
    print("From another device on the LAN, use this machine's LAN IP address, e.g.:")
    print("  http://<this-computer's-ip-address>:%d" % PORT)
    app.run(host="0.0.0.0", port=PORT, threaded=True)


if __name__ == "__main__":
    main()