LEDcommander.py

# LEDcommander.py - Multiprocessing Command Dispatcher for LEDarcade

# To do
# =====
#
# - work on transitions between displays
#   - this is tough because each different display type is spawned as a process
#   - perhaps the calling function can take a screen shot (deep copy ScreenArray)
#     and put that in the CommandQueue so we can fade back to it later


"""
===============================================================================
LEDcommander.py - Multiprocessing Command Dispatcher for LEDarcade
===============================================================================
Author: William McEvoy (@datagod)

DESCRIPTION:
This module coordinates all LED display tasks by acting as a command-and-control
process. It uses Python's `multiprocessing` library to delegate screen updates
(such as digital clocks, terminal messages, or titles) to subprocesses.

KEY ARCHITECTURE:
- The main `Run()` function monitors a shared `CommandQueue`.
- Based on the command type (`Action`), it starts/stops worker processes.
- Each subprocess initializes and controls the hardware via `LEDarcade` safely.

IMPORTANT: Display + GPIO Access
- The `LEDarcade` module interfaces directly with LED matrices via GPIO or
  framebuffer libraries (like `rpi-rgb-led-matrix`).
- Due to hardware constraints, **display initialization must be done inside child processes** only.
- Initializing the display in the main process can lead to:
    - corrupted hardware state
    - silent failures
    - GPIO conflicts and undefined behavior

✅ Always import `LEDarcade` and call `LED.Initialize()` inside the subprocess
✅ Never use GPIO display functions from the parent process

MULTIPROCESS DESIGN:
- Subprocesses are spawned using `multiprocessing.Process` (fork model).
- Only one active `DisplayProcess` is allowed at any time to avoid buffer collisions.
- A shared `StopEvent` is used to gracefully shut down current subprocesses.

COMMANDQUEUE:
- A shared `multiprocessing.Queue` used to deliver structured command dictionaries.
- `Run()` consumes commands in order (FIFO) and dispatches the corresponding worker.
- For TerminalMode, `Run()` forwards terminal messages back into the same queue
  (this avoids direct queue collisions between parent and subprocess).

TERMINAL MODE:
- A persistent terminal subprocess that waits for new text messages.
- Displays each message sequentially with typing and scrolling effects.
- Maintains a local FIFO queue (`message_queue`) to handle rapid incoming messages.
- When idle, shows a blinking cursor until the next message arrives.

SPAWN METHOD (OPTIONAL SAFETY):
For more isolation (especially with native libraries), consider:
    import multiprocessing
    multiprocessing.set_start_method("spawn")

This ensures new interpreter processes are used instead of forks. It's slightly
slower but more reliable when working with C/C++ extensions like GPIO.

EXAMPLES:
To start TerminalMode and send a message:
    CommandQueue.put({"Action": "terminalmode_on", "Message": "Hello", ...})
To send more messages:
    CommandQueue.put({"Action": "terminalmessage", "Message": "Next line!", ...})
To stop TerminalMode:
    CommandQueue.put({"Action": "terminalmode_off"})

"""


print("")
print("=============================================")
print("== LEDcommander.py                           =")
print("=============================================")
print("")




import time
import traceback
import random
import itertools  # for generator function


from multiprocessing import Event, Process, Queue
import queue

from flask import Flask, request, jsonify
import logging
import os
import LEDupdate
import LEDpanel

#GLOBAL VARS
RotateClockDelay = 5  # minutes between rotation of different display styles
IsOnAirActive = False
IsStockTickerPinned = False
ON_AIR_DEFAULT_MINUTES = 30
ON_AIR_DEFAULT_SECONDS = ON_AIR_DEFAULT_MINUTES * 60
SIGN_DEFAULT_SECONDS = 60
SIGN_HOLD_ACTIONS = (
    "showonair", "showonair_off", "showsign", "showsign_off",
    "stop", "stopclock", "next", "quit",
)

REPO_DIR = os.path.dirname(os.path.abspath(__file__))
IMAGE_DIR = os.path.join(REPO_DIR, "images")

VALID_WEB_ACTIONS = {
    "showclock": [],
    "stopclock": [],
    "stop": [],
    "next": [],
    "showtitlescreen": [
        "BigText", "LittleText", "LittleTextRGB", "ScrollText", "ScrollTextRGB",
        "ScrollSleep", "DisplayTime", "ExitEffect", "LittleTextZoom",
    ],
    "analogclock": [],
    "retrodigital": [],
    "flipclock": ["duration"],
    "sevensegclock": ["duration"],  # full-panel 7-segment digital clock
    "rocketclock": ["duration"],    # full-panel digital HH:MM with rocket digit transitions
    "waterclock": ["duration"],
    "wheelclock": ["duration"],    # HH:MM:SS digit-wheel clock
    "nixieclock": ["duration"],    # HH:MM nixie-tube clock
    "laserclock": ["duration"],    # HH:MM laser-forged clock
    "launch_planet": ["duration"],
    "ledarcade_intro": [],
    "starrynightdisplaytext": ["text1", "text2", "text3"],
    "launch_dotinvaders": ["duration"],
    "launch_defender": ["duration"],
    "launch_defender2": ["duration"],
    "launch_tron": ["duration"],
    "launch_outbreak": ["duration"],
    "launch_originals": ["duration"],  # random Originals game at launch
    "launch_ledtv": ["duration", "effect", "youtube_url", "channel"],
    "launch_spacedot": ["duration"],
    "launch_pacdot": ["duration"],
    "launch_dotzerk": ["duration"],
    "launch_blasteroids": ["duration"],
    "launch_stockticker": ["duration", "symbols"],
    "launch_fallingsand": ["duration"],
    "launch_particles": ["duration"],
    "launch_fractal": ["duration"],
    "launch_pinball": ["duration"],
    "launch_pinball2": ["duration"],
    "launch_pinball_random": ["duration"],  # picks a random table at launch
    "launch_gravitysim": ["duration"],
    "launch_mazecar": ["duration"],
    "launch_rallydot": ["duration"],
    "launch_spaceexplorer": ["duration"],
    "launch_skyfall": ["duration"],
    "launch_artillerytime": ["duration"],
    "launch_nightdriver": ["duration"],
    "launch_spaceclock": ["duration"],
    "twitchtimer_on": ["StreamStartedDateTime", "StreamDurationHHMMSS"],
    "twitchtimer_off": [],
    "terminalmode_on": ["Message", "RGB", "ScrollSleep"],
    "terminalmessage": ["Message", "RGB", "ScrollSleep"],
    "terminalmode_off": [],
    "weatherterminal": ["Location", "Units", "RGB", "ScrollSleep", "TypeSpeed", "Repeat", "PostScrollWait"],
    "stockterminal": ["symbols", "RGB", "ScrollSleep", "TypeSpeed", "Repeat", "PostScrollWait"],
    "showheart": [],
    "showintro": [],
    "showonair": ["duration"],
    "showonair_off": [],
    "showsign": ["message", "duration"],
    "showsign_off": [],
    "showdemotivate": [],
    "showgif": ["GIF", "loops", "sleep"],
    "showviewers": ["chatusers"],
    "showimagezoom": ["image", "zoommin", "zoommax", "zoomfinal", "sleep", "step"],
    "quit": [],
}

# Specific tables available to ?pinball / rotation random picker.
# Add new tables here as they are wired into the commander.
PINBALL_TABLE_ACTIONS = (
    "launch_pinball",
    "launch_pinball2",
)

# Original arcade games — one rotation slot picks a random member at launch.
ORIGINALS_ACTIONS = (
    "launch_dotinvaders",
    "launch_tron",
    "launch_spacedot",
)


def sanitize_web_command(data, action):
    """Normalize and validate web command fields before queueing."""
    if "Loops" in data and "loops" not in data:
        data["loops"] = data["Loops"]
    if "Image" in data and "image" not in data:
        data["image"] = data["Image"]
    if "Duration" in data and "duration" not in data and action in ["showonair", "showsign"] + [a for a in VALID_WEB_ACTIONS if a.startswith("launch_")]:
        data["duration"] = data["Duration"]

    for key in data:
        if "RGB" in key and isinstance(data[key], str):
            try:
                data[key] = tuple(map(int, data[key].split(",")))
            except Exception:
                data[key] = (255, 255, 255)

    if action in ["showgif", "showimagezoom", "showtitlescreen", "terminalmode_on", "terminalmessage", "weatherterminal", "showonair", "showsign", "twitchtimer_on"] or action.startswith("launch_"):
        for key in ["Duration", "loops", "sleep", "ScrollSleep", "DisplayTime", "zoommin", "zoommax", "zoomfinal", "step", "duration"]:
            if key in data:
                try:
                    data[key] = float(data[key]) if '.' in str(data[key]) else int(data[key])
                except ValueError:
                    pass

    if action == "terminalmode_on":
        for key in ["Style", "Speed"]:
            if key in data:
                try:
                    data[key] = int(data[key])
                except ValueError:
                    pass

    if action == "showgif" and "GIF" in data and not str(data["GIF"]).startswith("/"):
        data["GIF"] = os.path.join(IMAGE_DIR, os.path.basename(data["GIF"]))

    if action == "showimagezoom" and "image" in data and not str(data["image"]).startswith("/"):
        data["image"] = os.path.join(IMAGE_DIR, os.path.basename(data["image"]))

    if action == "showviewers" and "chatusers" in data and isinstance(data["chatusers"], str):
        data["chatusers"] = [user.strip() for user in data["chatusers"].split(",") if user.strip()]

    if action == "weatherterminal":
        import WeatherClock as WC
        data["Units"] = WC.NormalizeUnits(data.get("Units", "C"))
        for key in ["TypeSpeed", "ScrollSleep"]:
            if key in data:
                try:
                    data[key] = float(data[key])
                except ValueError:
                    pass
        if "Repeat" in data:
            try:
                data["Repeat"] = max(int(data["Repeat"]), 1)
            except ValueError:
                data["Repeat"] = WC.WEATHER_SCROLL_REPEAT
        if "PostScrollWait" in data:
            try:
                data["PostScrollWait"] = max(float(data["PostScrollWait"]), 0)
            except ValueError:
                data["PostScrollWait"] = WC.WEATHER_POST_SCROLL_WAIT

    if action == "stockterminal":
        import StockReport as SR
        for key in ["TypeSpeed", "ScrollSleep"]:
            if key in data:
                try:
                    data[key] = float(data[key])
                except ValueError:
                    pass
        if "Repeat" in data:
            try:
                data["Repeat"] = max(int(data["Repeat"]), 1)
            except ValueError:
                data["Repeat"] = SR.STOCK_SCROLL_REPEAT
        if "PostScrollWait" in data:
            try:
                data["PostScrollWait"] = max(float(data["PostScrollWait"]), 0)
            except ValueError:
                data["PostScrollWait"] = SR.STOCK_POST_SCROLL_WAIT
        if "symbols" in data:
            parsed = SR.ParseStockSymbols(data["symbols"])
            if parsed:
                data["symbols"] = parsed

    if action == "launch_stockticker" and "symbols" in data:
        if isinstance(data["symbols"], str):
            data["symbols"] = [s.strip().upper() for s in data["symbols"].split(",") if s.strip()]
        elif isinstance(data["symbols"], list):
            data["symbols"] = [str(s).strip().upper() for s in data["symbols"] if str(s).strip()]

    if action == "showsign":
        if "Message" in data and "message" not in data:
            data["message"] = data["Message"]
        raw = data.get("message", "ALERT")
        text = " ".join(str(raw or "").split())
        data["message"] = (text or "ALERT").upper()[:16]

    return data



def serve_web_control(queue, port=5055):
    """
    LED Commander web control panel and /command API.
    This is the single source of truth for remote display commands.
    """
    log = logging.getLogger('werkzeug')
    log.setLevel(logging.ERROR)

    app = Flask(__name__)
    LEDupdate.register_update_routes(app, queue)

    @app.route('/command', methods=['POST'])
    def handle_command():
        data = request.get_json() if request.is_json else request.form.to_dict()
        print(f"[LEDcommander][web] Received: {data}")
        action = data.get("Action")
        if isinstance(action, str):
            action = action.lower()
            data["Action"] = action
        print(f"[LEDcommander][web] Action: {action}")
        if not action or action not in VALID_WEB_ACTIONS:
            return jsonify({'status': 'error', 'message': f'Invalid or missing action: {action}'}), 400
        data = sanitize_web_command(data, action)
        allowed_fields = set(VALID_WEB_ACTIONS[action] + ["Action"])
        filtered_data = {k: v for k, v in data.items() if k in allowed_fields}
        queue.put(filtered_data)
        return jsonify({'status': 'ok', 'message': f"Queued: {action}"}), 200

    @app.route('/', methods=['GET'])
    def homepage():
        return LEDpanel.render_homepage(VALID_WEB_ACTIONS)

    app.run(host='0.0.0.0', port=port, threaded=False)

















CursorH   = 0
CursorV   = 0
StopEvent = Event()
DisplayProcess       = None
CurrentDisplayMode   = None
TerminalQueue        = Queue()
ClockFallbackEnabled = True

# Matrix brightness (0–100).
# Standalone LEDcommander: always full blast (100).
# Twitch stream mode: dim games/clocks for camera (set via LEDARCADE_STREAM_MODE).
STREAM_MAX_BRIGHTNESS = 100


def _detect_stream_mode():
    """True when LEDcommander is driven by Twitch (dim for stream)."""
    env = os.environ.get("LEDARCADE_STREAM_MODE", "").strip().lower()
    if env in ("1", "true", "yes", "on"):
        return True
    if env in ("0", "false", "no", "off"):
        return False
    # Fallback: parent process is twitch.py
    try:
        ppid = os.getppid()
        with open("/proc/{}/cmdline".format(ppid), "rb") as f:
            cmd = f.read().replace(b"\0", b" ").decode(errors="replace")
        if "twitch.py" in cmd:
            return True
    except Exception:
        pass
    return False


def _refresh_stream_brightness():
    """Resolve game/clock brightness from current stream mode (call live, not once)."""
    global STREAM_MODE, STREAM_GAME_BRIGHTNESS, STREAM_CLOCK_BRIGHTNESS
    STREAM_MODE = _detect_stream_mode()
    if STREAM_MODE:
        STREAM_GAME_BRIGHTNESS = 70
        STREAM_CLOCK_BRIGHTNESS = 80
    else:
        STREAM_GAME_BRIGHTNESS = STREAM_MAX_BRIGHTNESS
        STREAM_CLOCK_BRIGHTNESS = STREAM_MAX_BRIGHTNESS
    return STREAM_MODE, STREAM_GAME_BRIGHTNESS, STREAM_CLOCK_BRIGHTNESS


STREAM_MODE = False
STREAM_GAME_BRIGHTNESS = STREAM_MAX_BRIGHTNESS
STREAM_CLOCK_BRIGHTNESS = STREAM_MAX_BRIGHTNESS
_refresh_stream_brightness()


def _apply_matrix_brightness(level):
    try:
        import LEDarcade as LED
        LED.TheMatrix.brightness = int(level)
    except Exception:
        pass


def _run_game_dimmed(launch_fn, fade_in=False, fade_out=True):
    """Run a game at stream/game brightness; full brightness after.
    Standalone LEDcommander: 100. Twitch stream mode: dimmed (70).

    fade_in: ramp from black unless the program has its own start/intro.
    fade_out: ramp to black unless the program has its own exit routine.
    """
    import LEDarcade as LED
    _refresh_stream_brightness()
    _apply_matrix_brightness(STREAM_GAME_BRIGHTNESS)
    try:
        if fade_in:
            try:
                LED.PrepareFadeIn()
            except Exception:
                pass
        return launch_fn()
    finally:
        if fade_out:
            try:
                LED.FadeOutDisplay()
            except Exception:
                pass
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)


def _run_clock(run_fn, fade_in=True, fade_out=True):
    """Run a clock at stream/clock brightness with optional fade in/out."""
    import LEDarcade as LED
    _refresh_stream_brightness()
    _apply_matrix_brightness(STREAM_CLOCK_BRIGHTNESS)
    try:
        if fade_in:
            try:
                LED.PrepareFadeIn()
            except Exception:
                pass
        return run_fn()
    finally:
        if fade_out:
            try:
                LED.FadeOutDisplay()
            except Exception:
                pass
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)



def fallback_action_generator():
    """
    Idle rotation for LEDcommander / LEDsim:

      1) Spectacular LED ARCADE intro (once per process start)
      2) Forever: shuffle content each lap; clocks sit *between* games.
         Pattern: content → clock → content → clock → …
         So after the intro the first item is always a game, never a clock.

    Timed content runs 5 minutes (including Planet Blast, LEDtv, Rally Dot,
    Night Driver). Weather ends when the scroll finishes. Originals is one
    slot that picks Dot Invaders, Tron, or Space Dot at random when it runs.
    """
    # Boot title — once
    yield {"Action": "ledarcade_intro"}

    content_pool = [
        {"Action": "launch_skyfall", "duration": 5},
        {"Action": "launch_pacdot", "duration": 5},
        {"Action": "launch_dotzerk", "duration": 5},
        {"Action": "launch_spaceexplorer", "duration": 5},
        {"Action": "launch_defender2", "duration": 5},
        {"Action": "weatherterminal"},  # natural scroll end
        {"Action": "launch_gravitysim", "duration": 5},
        # outbreak paused from idle rotation for now
        # {"Action": "launch_outbreak", "duration": 5},
        {"Action": "launch_fallingsand", "duration": 5},
        {"Action": "launch_particles", "duration": 5},
        # Fractal Blaster — multi-type tour, color cycle, digital clock, 5 min
        {"Action": "launch_fractal", "duration": 5},
        {"Action": "launch_artillerytime", "duration": 5},
        {"Action": "launch_nightdriver", "duration": 5},
        {"Action": "launch_spaceclock", "duration": 5},
        {"Action": "launch_planet", "duration": 5},
        {"Action": "launch_ledtv", "duration": 5},
        # One Originals slot per lap — game chosen at random when it runs
        {"Action": "launch_originals", "duration": 5},
        # One pinball slot per lap — table chosen at random when it runs
        {"Action": "launch_pinball_random", "duration": 5},
        {"Action": "launch_rallydot", "duration": 5},
    ]

    clock_pool = [
        {"Action": "retrodigital", "duration": 5},
        {"Action": "flipclock", "duration": 5},
        {"Action": "sevensegclock", "duration": 5},
        {"Action": "rocketclock", "duration": 5},
        {"Action": "waterclock", "duration": 5},
        {"Action": "analogclock", "duration": 5},
        {"Action": "wheelclock", "duration": 5},
        {"Action": "nixieclock", "duration": 5},
        {"Action": "laserclock", "duration": 5},
        {"Action": "showclock", "Style": 1, "Zoom": 3, "duration": 5, "Delay": 20},
        {"Action": "showclock", "Style": 3, "Zoom": 2, "duration": 5, "Delay": 10},
        {"Action": "showclock", "Style": 5, "Zoom": 1, "duration": 5, "Delay": 10},
    ]

    lap = 0
    while True:
        content = list(content_pool)
        random.shuffle(content)
        # One random clock order for this lap; cycle that order for separators
        clocks = list(clock_pool)
        random.shuffle(clocks)
        lap += 1
        print(
            "[LEDcommander] Fallback lap {} — {} content slots (game first), "
            "clock cycle: {}".format(
                lap,
                len(content),
                " → ".join(
                    c.get("Action")
                    + (f" s{c['Style']}" if "Style" in c else "")
                    for c in clocks
                ),
            )
        )
        clock_i = 0
        for item in content:
            # Game first, then a clock before the next game
            yield item
            yield clocks[clock_i % len(clocks)]
            clock_i += 1


 


def stop_current_display(preempted_by, join_timeout=5):
    """Stop the active display subprocess and log what interrupted it.

    Sets the shared StopEvent so well-behaved games (Skyfall, LEDtv, …) exit
    their loops promptly. Waits up to join_timeout seconds, then terminates
    the process if it is still alive so the next LEDcommander action can run.
    """
    global StopEvent, DisplayProcess, CurrentDisplayMode
    if DisplayProcess and DisplayProcess.is_alive():
        mode = CurrentDisplayMode or "unknown"
        print(f"[LEDcommander] Stopping '{mode}' (preempted by: {preempted_by})")
        try:
            StopEvent.set()
        except Exception:
            pass
        DisplayProcess.join(timeout=join_timeout)
        if DisplayProcess.is_alive():
            print(
                f"[LEDcommander] '{mode}' did not exit after "
                f"{join_timeout}s — terminating process"
            )
            try:
                DisplayProcess.terminate()
            except Exception:
                pass
            DisplayProcess.join(timeout=2)
            if DisplayProcess.is_alive():
                try:
                    DisplayProcess.kill()
                except Exception:
                    pass
                DisplayProcess.join(timeout=1)
        DisplayProcess = None
        if CurrentDisplayMode == mode:
            CurrentDisplayMode = None


def Run(CommandQueue):
    # Log brightness mode once at dispatcher start
    _refresh_stream_brightness()
    print(
        "[LEDcommander] brightness mode: {} "
        "(game={}, clock={}, max={})".format(
            "STREAM/Twitch" if STREAM_MODE else "STANDALONE full",
            STREAM_GAME_BRIGHTNESS,
            STREAM_CLOCK_BRIGHTNESS,
            STREAM_MAX_BRIGHTNESS,
        )
    )
    global StopEvent, DisplayProcess, CurrentDisplayMode, TerminalQueue
    global IsOnAirActive, IsStockTickerPinned, FallbackGenerator
    print("\n" + "=" * 65)
    print("🧠 LEDcommander Launched")
    print("=" * 65)
    print("Multiprocessing control engine for LEDarcade.")
    print("Handles dynamic screen updates, effects, and real-time commands.")
    print("Developed by William McEvoy (@datagod) for Raspberry Pi environments.")
    print("Core Features:")
    print(" - Isolated subprocess rendering (clock, titles, etc.)")
    print(" - Clean LED shutdown via command queue")
    print(" - Expandable message-based architecture")
    print(" - Safe multiprocessing for GPIO hardware")
    print("-------------------------------------------------------------")
    print("Command your pixels like a pro — with LEDcommander.")
    print("=" * 65 + "\n")
    print("")
    print("")

    # On first start: check GitHub, show status on the panel, pull + restart if needed.
    # (Runs in a child process so GPIO/matrix init stays off the commander process.)
    try:
        LEDupdate.run_boot_update_check()
    except Exception as BootUpdateError:
        print(f"[LEDcommander] Boot update check failed (continuing): {BootUpdateError}")
        traceback.print_exc()

    while True:
        try:
            # Get command or handle empty
            try:
                Command = CommandQueue.get(timeout=1)
            except queue.Empty:
                # Check for timed-out OnAir
                if IsOnAirActive and DisplayProcess and not DisplayProcess.is_alive():
                    print("[LEDcommander] OnAir timed out, proceeding to next")
                    IsOnAirActive = False
                    CurrentDisplayMode = None
                if IsStockTickerPinned and DisplayProcess and not DisplayProcess.is_alive():
                    print("[LEDcommander] Stock ticker finished, releasing pin")
                    IsStockTickerPinned = False
                    CurrentDisplayMode = None
                # If idle (no OnAir, no pinned stock ticker, no process), pull generator
                if (not IsOnAirActive and not IsStockTickerPinned
                        and (DisplayProcess is None or not DisplayProcess.is_alive())):
                    print("[LEDcommander] Queue empty and idle—using fallback generator")
                    Command = next(FallbackGenerator)
                else:
                    continue  # Wait if something's running

            print(f"[LEDcommander][Run] Received command: {Command}")
            
            if not isinstance(Command, dict):
                continue

            Action = Command.get("Action", "").lower()
            print(f"<-- [LEDcommander] Action: {Action}")

            # Originals group: one rotation slot → random classic game
            if Action == "launch_originals":
                chosen = random.choice(ORIGINALS_ACTIONS)
                print(
                    f"[LEDcommander][Run] Originals → {chosen} "
                    f"(from {len(ORIGINALS_ACTIONS)} games)"
                )
                Action = chosen
                Command = dict(Command)
                Command["Action"] = chosen

            # Handle off (force stop, proceed)
            if Action in ("showonair_off", "showsign_off"):
                if IsOnAirActive:
                    print(f"[LEDcommander] Manual stop {Action}, proceeding to next")
                    stop_current_display(Action)
                    IsOnAirActive = False
                continue  # Loop will now pull next queue/generator

            # Handle on (start with duration)
            if Action == "showonair":
                print("[LEDcommander] Starting OnAir")
                stop_current_display(Action)
                StopEvent.clear()
                if "duration" not in Command:
                    Command["duration"] = ON_AIR_DEFAULT_SECONDS
                CurrentDisplayMode = "onair"
                IsOnAirActive = True
                DisplayProcess = Process(target=ShowOnAir, args=(Command, StopEvent))
                DisplayProcess.start()
                continue

            if Action == "showsign":
                print("[LEDcommander] Starting custom sign")
                stop_current_display(Action)
                StopEvent.clear()
                if "duration" not in Command:
                    Command["duration"] = SIGN_DEFAULT_SECONDS
                CurrentDisplayMode = "sign"
                IsOnAirActive = True
                DisplayProcess = Process(target=ShowCustomSign, args=(Command, StopEvent))
                DisplayProcess.start()
                continue

            # Explicit stop: clear pin flags and preempt Skyfall / any display
            if Action in ("stop", "stopclock"):
                print(f"[LEDcommander] Stop command ({Action}) — ending '{CurrentDisplayMode}'")
                IsOnAirActive = False
                IsStockTickerPinned = False
                stop_current_display(Action)
                CurrentDisplayMode = "stopped"
                continue

            # Skip to next rotation item (idle fallback queue / playlist)
            if Action == "next":
                print(
                    f"[LEDcommander] Next — ending '{CurrentDisplayMode}' "
                    "and advancing playlist"
                )
                IsOnAirActive = False
                IsStockTickerPinned = False
                stop_current_display("next")
                CurrentDisplayMode = None
                try:
                    nxt = next(FallbackGenerator)
                    print(f"[LEDcommander] Next program: {nxt.get('Action', nxt)}")
                    CommandQueue.put(nxt)
                except Exception as NextErr:
                    print(f"[LEDcommander] Next failed to pull fallback: {NextErr}")
                continue

            # While On Air / custom sign, hold the display until manual off or duration expiry.
            if IsOnAirActive and Action not in SIGN_HOLD_ACTIONS:
                print(f"[LEDcommander] Sign active—ignoring command: {Action}")
                continue

            # While stock ticker is pinned (user set duration), hold until it finishes.
            if (IsStockTickerPinned
                    and Action not in (
                        "launch_stockticker", "showonair", "showonair_off",
                        "showsign", "showsign_off",
                        "quit", "stop", "stopclock", "next",
                    )):
                print(f"[LEDcommander] Stock ticker pinned—ignoring command: {Action}")
                continue



            #----------------------------------
            #-- CLOCK MODE
            #----------------------------------

            if Action == "showclock":
                print("Starting the clock")
                stop_current_display(Action)
                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(target=ShowDigitalClock, args=(Command, StopEvent))
                DisplayProcess.start()



            #----------------------------------
            #-- TITLE SCREEN
            #----------------------------------

            elif Action == "showtitlescreen":
                print("Showing title screen")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "title"
                DisplayProcess = Process(target=ShowTitleScreen, args=(Command, StopEvent))
                DisplayProcess.start()


            #----------------------------------
            #-- ANALOG CLOCK
            #----------------------------------

            elif Action == "analogclock":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(target=ShowAnalogClock, args=(Command, StopEvent))
                DisplayProcess.start()


            elif Action == "retrodigital":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(target=ShowRetroDigital, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "flipclock":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(target=ShowFlipClock, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "sevensegclock":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(
                    target=ShowSevenSegClock, args=(Command, StopEvent)
                )
                DisplayProcess.start()

            elif Action == "rocketclock":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(
                    target=ShowRocketClock, args=(Command, StopEvent)
                )
                DisplayProcess.start()

            elif Action == "waterclock":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(
                    target=ShowWaterClock, args=(Command, StopEvent)
                )
                DisplayProcess.start()

            elif Action == "wheelclock":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(
                    target=ShowWheelClock, args=(Command, StopEvent)
                )
                DisplayProcess.start()

            elif Action == "nixieclock":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(
                    target=ShowNixieClock, args=(Command, StopEvent)
                )
                DisplayProcess.start()

            elif Action == "laserclock":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "clock"
                DisplayProcess = Process(
                    target=ShowLaserClock, args=(Command, StopEvent)
                )
                DisplayProcess.start()

            elif Action == "ledarcade_intro":
                stop_current_display(Action)
                StopEvent.clear()
                CurrentDisplayMode = "intro"
                DisplayProcess = Process(target=ShowLEDArcadeIntro, args=(Command, StopEvent))
                DisplayProcess.start()


            #----------------------------------
            #-- STARRY NIGHT VARIATIONS
            #----------------------------------


            elif Action == "starrynightdisplaytext":
                print("[LEDcommander][Run] Starry Night Display Text")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "starrynight"
                DisplayProcess = Process(target=StarryNightDisplayText, args=(Command, StopEvent))
                DisplayProcess.start()



            #----------------------------------
            #-- LAUNCH PROGRAMS
            #----------------------------------


            elif Action == "launch_dotinvaders":
                print("[LEDcommander][Run] Launching DotInvaders")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "dotinvaders"
                DisplayProcess = Process(target=LaunchDotInvaders, args=(Command, StopEvent))
                DisplayProcess.start()


            elif Action in ("launch_defender", "launch_defender2"):
                # Always Defender2 (superior rewrite); launch_defender is an alias
                print("[LEDcommander][Run] Launching Defender2")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "defender"
                DisplayProcess = Process(target=LaunchDefender, args=(Command, StopEvent))
                DisplayProcess.start()


            elif Action == "launch_tron":
                print("[LEDcommander][Run] Launching Tron")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "tron"
                DisplayProcess = Process(target=LaunchTron, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_outbreak":
                print("[LEDcommander][Run] Launching Outbreak")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "outbreak"
                DisplayProcess = Process(target=LaunchOutbreak, args=(Command, StopEvent))
                DisplayProcess.start()



            elif Action == "launch_ledtv":
                print("[LEDcommander][Run] Launching LEDtv")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "ledtv"
                DisplayProcess = Process(target=LaunchLEDtv, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_spacedot":
                print("[LEDcommander][Run] Launching SpaceDot")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "spacedot"
                DisplayProcess = Process(target=LaunchSpaceDot, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_pacdot":
                print("[LEDcommander][Run] Launching PacDot")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "pacdot"
                DisplayProcess = Process(target=LaunchPacDot, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_dotzerk":
                print("[LEDcommander][Run] Launching DotZerk")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "dotzerk"
                DisplayProcess = Process(target=LaunchDotZerk, args=(Command, StopEvent))
                DisplayProcess.start()


            elif Action == "launch_blasteroids":
                print("[LEDcommander][Run] Launching Blasteroids")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "blasteroids"
                DisplayProcess = Process(target=LaunchBlasteroids, args=(Command, StopEvent))
                DisplayProcess.start()



            elif Action == "launch_stockticker":
                duration = Command.get("duration", 10)
                pin = "duration" in Command
                print(f"[LEDcommander][Run] Launching StockTicker (duration={duration} min, pinned={pin})")
                stop_current_display(Action)
                StopEvent.clear()
                CurrentDisplayMode = "stockticker"
                IsStockTickerPinned = pin
                DisplayProcess = Process(target=LaunchStockTicker, args=(Command, StopEvent))
                DisplayProcess.start()



            elif Action == "launch_fallingsand":
                print("[LEDcommander][Run] Launching fallingsand")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "tron"
                DisplayProcess = Process(target=LaunchFallingSand, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_particles":
                print("[LEDcommander][Run] Launching Particles")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "particles"
                DisplayProcess = Process(target=LaunchParticles, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_fractal":
                print("[LEDcommander][Run] Launching Fractal")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "fractal"
                DisplayProcess = Process(target=LaunchFractal, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_planet":
                print("[LEDcommander][Run] Launching Planet Blast")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "planet"
                DisplayProcess = Process(
                    target=LaunchPlanetFly, args=(Command, StopEvent)
                )
                DisplayProcess.start()

            elif Action == "launch_pinball_random":
                # ?pinball / idle rotation: pick a random table at launch time
                chosen = random.choice(PINBALL_TABLE_ACTIONS)
                print(
                    f"[LEDcommander][Run] Random pinball → {chosen} "
                    f"(from {len(PINBALL_TABLE_ACTIONS)} tables)"
                )
                Action = chosen
                Command = dict(Command)
                Command["Action"] = chosen
                if chosen == "launch_pinball":
                    print("[LEDcommander][Run] Launching Pinball")
                    stop_current_display(Action)
                    StopEvent.clear()
                    CurrentDisplayMode = "pinball"
                    DisplayProcess = Process(
                        target=LaunchPinball, args=(Command, StopEvent)
                    )
                    DisplayProcess.start()
                elif chosen == "launch_pinball2":
                    print(
                        "[LEDcommander][Run] Launching Pinball2 "
                        "(Central Park 1966)"
                    )
                    stop_current_display(Action)
                    StopEvent.clear()
                    CurrentDisplayMode = "pinball2"
                    DisplayProcess = Process(
                        target=LaunchPinball2, args=(Command, StopEvent)
                    )
                    DisplayProcess.start()

            elif Action == "launch_pinball":
                print("[LEDcommander][Run] Launching Pinball")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "pinball"
                DisplayProcess = Process(target=LaunchPinball, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_pinball2":
                print("[LEDcommander][Run] Launching Pinball2 (Central Park 1966)")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "pinball2"
                DisplayProcess = Process(target=LaunchPinball2, args=(Command, StopEvent))
                DisplayProcess.start()


            elif Action == "launch_gravitysim":
                print("[LEDcommander][Run] Launching GravitySim")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "gravitysim"
                DisplayProcess = Process(target=LaunchGravitySim, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_mazecar":
                print("[LEDcommander][Run] Launching MazeCar")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "mazecar"
                DisplayProcess = Process(target=LaunchMazeCar, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_rallydot":
                print("[LEDcommander][Run] Launching RallyDot")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "rallydot"
                DisplayProcess = Process(target=LaunchRallyDot, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_spaceexplorer":
                print("[LEDcommander][Run] Launching SpaceExplorer")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "spaceexplorer"
                DisplayProcess = Process(target=LaunchSpaceExplorer, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_skyfall":
                print("[LEDcommander][Run] Launching Skyfall")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "skyfall"
                DisplayProcess = Process(target=LaunchSkyfall, args=(Command, StopEvent))
                DisplayProcess.start()

            elif Action == "launch_artillerytime":
                print("[LEDcommander][Run] Launching Artillery Time")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "artillerytime"
                DisplayProcess = Process(
                    target=LaunchArtilleryTime, args=(Command, StopEvent)
                )
                DisplayProcess.start()

            elif Action == "launch_nightdriver":
                print("[LEDcommander][Run] Launching Night Driver")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "nightdriver"
                DisplayProcess = Process(
                    target=LaunchNightDriver, args=(Command, StopEvent)
                )
                DisplayProcess.start()

            elif Action == "launch_spaceclock":
                print("[LEDcommander][Run] Launching Space Clock")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "spaceclock"
                DisplayProcess = Process(
                    target=LaunchSpaceClock, args=(Command, StopEvent)
                )
                DisplayProcess.start()


            #----------------------------------
            #-- TWITCH TIMER
            #----------------------------------

            elif Action == "twitchtimer_on":
                print("Showing title screen")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "twitch"
                DisplayProcess = Process(target=StartTwitchTimer, args=(Command, StopEvent))
                DisplayProcess.start()


            elif Action == "twitchtimer_off":
                print("Showing title screen")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "stopped"




            #----------------------------------
            #-- TERMINAL MODE
            #----------------------------------

            elif Action == "terminalmode_on":
                if DisplayProcess and DisplayProcess.is_alive() and CurrentDisplayMode == "terminal":
                    print("[LEDcommander][Run] TerminalMode already active; queueing message.")
                    TerminalQueue.put(Command)
                else:
                    stop_current_display(Action)
                    StopEvent.clear()
                    CurrentDisplayMode = "terminal"
                    TerminalQueue = Queue()
                    DisplayProcess = Process(
                        target=StartTerminalMode,
                        args=(TerminalQueue, StopEvent, Command),
                    )
                    DisplayProcess.start()


            elif Action == "weatherterminal":
                import WeatherClock as WC

                location = WC.LoadWeatherLocation(Command.get("Location", ""))
                units = WC.NormalizeUnits(Command.get("Units", "C"))
                report = WC.FetchWeatherReport(location, units=units)
                terminal_action = "terminalmessage" if (
                    DisplayProcess and DisplayProcess.is_alive() and CurrentDisplayMode == "terminal"
                ) else "terminalmode_on"

                print(f"[LEDcommander] Queueing weather via {terminal_action} for {location}")

                if terminal_action == "terminalmode_on":
                    stop_current_display(Action)

                terminal_cmd = {
                    "Action": terminal_action,
                    "RGB": Command.get("RGB", (0, 200, 0)),
                    "ScrollSleep": Command.get("ScrollSleep", 0.05),
                    "TypeSpeed": Command.get("TypeSpeed", WC.WEATHER_TYPE_SPEED),
                    "Repeat": Command.get("Repeat", WC.WEATHER_SCROLL_REPEAT),
                    "PostScrollWait": Command.get("PostScrollWait", WC.WEATHER_POST_SCROLL_WAIT),
                    "HeaderRGB": WC.WEATHER_HEADER_RGB,
                }
                if isinstance(report, dict):
                    terminal_cmd["MessageHeader"] = report.get("header", "")
                    terminal_cmd["MessageBody"] = report.get("body", "")
                    terminal_cmd["Message"] = " ".join(
                        part for part in [report.get("header", ""), report.get("body", "")] if part
                    )
                else:
                    terminal_cmd["Message"] = report

                CommandQueue.put(terminal_cmd)


            elif Action == "stockterminal":
                import StockReport as SR

                symbols = Command.get("symbols")
                if isinstance(symbols, str) and not symbols.strip():
                    symbols = None
                report = SR.FetchStockReport(symbols)
                terminal_action = "terminalmessage" if (
                    DisplayProcess and DisplayProcess.is_alive() and CurrentDisplayMode == "terminal"
                ) else "terminalmode_on"

                print(f"[LEDcommander] Queueing stock report via {terminal_action}")

                if terminal_action == "terminalmode_on":
                    stop_current_display(Action)

                terminal_cmd = {
                    "Action": terminal_action,
                    "RGB": Command.get("RGB", (0, 200, 0)),
                    "ScrollSleep": Command.get("ScrollSleep", 0.05),
                    "TypeSpeed": Command.get("TypeSpeed", SR.STOCK_TYPE_SPEED),
                    "Repeat": Command.get("Repeat", SR.STOCK_SCROLL_REPEAT),
                    "PostScrollWait": Command.get("PostScrollWait", SR.STOCK_POST_SCROLL_WAIT),
                    "HeaderRGB": SR.STOCK_HEADER_RGB,
                    "SymbolRGB": SR.STOCK_SYMBOL_RGB,
                    "StockLines": report.get("stock_lines", []),
                    "MessageHeader": report.get("header", ""),
                    "MessageBody": report.get("body", ""),
                    "Message": " ".join(
                        part for part in [report.get("header", ""), report.get("body", "")] if part
                    ),
                }
                if report.get("errors"):
                    terminal_cmd["ErrorText"] = f"Unavailable: {', '.join(report['errors'])}."

                CommandQueue.put(terminal_cmd)


            elif Action == "terminalmessage":
                if DisplayProcess and DisplayProcess.is_alive() and CurrentDisplayMode == "terminal":
                    TerminalQueue.put(Command)
                else:
                    print("[LEDcommander] TerminalMode not active. Auto-starting it.")
                    stop_current_display(Action)
                    StopEvent.clear()
                    CurrentDisplayMode = "terminal"
                    TerminalQueue = Queue()  # reset queue to avoid stale messages
                    DisplayProcess = Process(target=StartTerminalMode, args=(TerminalQueue, StopEvent, Command))
                    DisplayProcess.start()

            # In StartTerminalMode(), replace CommandQueue with TerminalQueue


            elif Action == "terminalmode_off":
                print("[LEDcommander] terminalmode_OFF detected")
                stop_current_display(Action)
                StopEvent.clear()
                CurrentDisplayMode = "stopped"
                print("[LEDcommander] TerminalMode stopped.")



            #----------------------------------------
            # ANIMATIONS                           --
            #----------------------------------------

            elif Action == "showheart":
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "heart"
                DisplayProcess = Process(target=ShowHeart, args=(Command, StopEvent))
                DisplayProcess.start()



            elif Action == "showintro":
                print("[LEDcommander][Run] Launching Intro")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "showintro"
                DisplayProcess = Process(target=ShowIntro, args=(Command, StopEvent))
                DisplayProcess.start()





            elif Action == "showdemotivate":
                print("[LEDcommander][Run] Launching Demotivate")
                stop_current_display(Action)

                StopEvent.clear()
                CurrentDisplayMode = "showdemotivate"
                DisplayProcess = Process(target=ShowDemotivate, args=(Command, StopEvent))
                DisplayProcess.start()



            elif Action == "showgif":
                stop_current_display(Action)
                StopEvent.clear()
                CurrentDisplayMode = "gif"
                DisplayProcess = Process(target=ShowGIF, args=(Command, StopEvent))
                DisplayProcess.start()


            elif Action == "showviewers":
                stop_current_display(Action)
                StopEvent.clear()
                CurrentDisplayMode = "gif"
                DisplayProcess = Process(target=ShowViewers, args=(Command, StopEvent))
                DisplayProcess.start()


            elif Action == "showimagezoom":
                stop_current_display(Action)
                StopEvent.clear()
                CurrentDisplayMode = "image"
                DisplayProcess = Process(target=ShowImageZoom, args=(Command, StopEvent))
                
                #After showing Image, we restart the clock
                CommandQueue.put(OldCommand)
                DisplayProcess.start()



            elif Action == "quit":
                print("[LEDcommander] Quit received.")
                stop_current_display(Action)
                print("[LEDcommander][Run] Shutdown complete.")
                break  # Exit the loop and end the process


        except Exception as e:
            print(f"[LEDcommander] Run error: {e}")
            traceback.print_exc()
            if ClockFallbackEnabled:
                CommandQueue.put({"Action": "showclock"})  # Fallback









#----------------------------------------------------------
#-- Action functions
#----------------------------------------------------------

def ShowDigitalClock(Command,StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    print("RedR: ",LED.RedR)

    ClockStyle = Command.get("Style", 1)
    ZoomFactor = Command.get("Zoom", 2)
    RunMinutes = Command.get("duration", 1)
    AnimationDelay = Command.get("Delay", 30)

    print(
        f"[LEDcommander] Showing clock: Style={ClockStyle}, Zoom={ZoomFactor}, "
        f"Duration={RunMinutes}, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    _run_clock(
        lambda: LED.DisplayDigitalClock(
            ClockStyle=ClockStyle,
            CenterHoriz=True,
            v=1,
            hh=24,
            RGB=LED.LowGreen,
            ShadowRGB      = LED.ShadowGreen,
            ZoomFactor     = ZoomFactor,
            AnimationDelay = AnimationDelay,
            RunMinutes     = RunMinutes,
            StopEvent      = StopEvent
        )
    )



def ShowRetroDigital(Command,StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    ClockStyle = Command.get("Style", 4)
    ZoomFactor = Command.get("Zoom", 1)
    RunMinutes = Command.get("duration", 5)
    AnimationDelay = Command.get("Delay", 30)

    print(
        f"[LEDcommander] Showing retro clock: Style={ClockStyle}, Zoom={ZoomFactor}, "
        f"Duration={RunMinutes}, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    _run_clock(
        lambda: LED.DisplayDigitalClock(
            ClockStyle=ClockStyle,
            CenterHoriz=True,
            v=1,
            hh=24,
            RGB=LED.LowGreen,
            ShadowRGB      = LED.ShadowGreen,
            ZoomFactor     = ZoomFactor,
            AnimationDelay = AnimationDelay,
            RunMinutes     = RunMinutes,
            StopEvent      = StopEvent
        )
    )


def ShowFlipClock(Command, StopEvent):
    """1970s flip-card clock — white digits on black (ClockStyle 6)."""
    import LEDarcade as LED
    LED.Initialize()

    RunMinutes = Command.get("duration", 10)
    try:
        RunMinutes = float(RunMinutes)
    except (TypeError, ValueError):
        RunMinutes = 10

    print(
        f"[LEDcommander] Showing flip clock: Style=6, "
        f"Duration={RunMinutes}, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    _run_clock(
        lambda: LED.DisplayDigitalClock(
            ClockStyle=6,
            CenterHoriz=True,
            v=1,
            hh=24,
            RunMinutes=RunMinutes,
            StopEvent=StopEvent,
        )
    )


def ShowSevenSegClock(Command, StopEvent):
    """Full-panel classic red 7-segment digital clock (HH:MM)."""
    import LEDarcade as LED
    LED.Initialize()
    import SevenSegClock as SSC

    RunMinutes = Command.get("duration", 10)
    try:
        RunMinutes = float(RunMinutes)
    except (TypeError, ValueError):
        RunMinutes = 10.0

    print(
        f"[LEDcommander] Showing 7-seg clock: "
        f"Duration={RunMinutes}, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    _run_clock(
        lambda: SSC.LaunchSevenSegClock(
            Duration=RunMinutes, ShowIntro=False, StopEvent=StopEvent,
        )
    )


def ShowRocketClock(Command, StopEvent):
    """Full-panel digital HH:MM — digits rocket away and land with exhaust."""
    import LEDarcade as LED
    LED.Initialize()
    import RocketClock as RC

    RunMinutes = Command.get("duration", 10)
    try:
        RunMinutes = float(RunMinutes)
    except (TypeError, ValueError):
        RunMinutes = 10.0

    print(
        f"[LEDcommander] Showing rocket clock: "
        f"Duration={RunMinutes}, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    _run_clock(
        lambda: RC.LaunchRocketClock(
            Duration=RunMinutes, ShowIntro=False, StopEvent=StopEvent,
        )
    )


def ShowWaterClock(Command, StopEvent):
    """Shaded HH:MM with tide water washing around the clock."""
    import LEDarcade as LED
    LED.Initialize()
    import WaterClock as WC

    RunMinutes = Command.get("duration", 10)
    try:
        RunMinutes = float(RunMinutes)
    except (TypeError, ValueError):
        RunMinutes = 10.0

    print(
        f"[LEDcommander] Showing water clock: "
        f"Duration={RunMinutes}, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    _run_clock(
        lambda: WC.LaunchWaterClock(
            Duration=RunMinutes, ShowIntro=False, StopEvent=StopEvent,
        )
    )


def ShowWheelClock(Command, StopEvent):
    """Full-panel HH:MM:SS rolling digit-wheel clock."""
    import LEDarcade as LED
    LED.Initialize()
    import WheelClock as WHC

    RunMinutes = Command.get("duration", 10)
    try:
        RunMinutes = float(RunMinutes)
    except (TypeError, ValueError):
        RunMinutes = 10.0

    print(
        f"[LEDcommander] Showing wheel clock: "
        f"Duration={RunMinutes}, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    _run_clock(
        lambda: WHC.LaunchWheelClock(
            Duration=RunMinutes, ShowIntro=False, StopEvent=StopEvent,
        )
    )


def ShowNixieClock(Command, StopEvent):
    """Full-panel HH:MM nixie-tube clock."""
    import LEDarcade as LED
    LED.Initialize()
    import NixieClock as NX

    RunMinutes = Command.get("duration", 10)
    try:
        RunMinutes = float(RunMinutes)
    except (TypeError, ValueError):
        RunMinutes = 10.0

    print(
        f"[LEDcommander] Showing nixie clock: "
        f"Duration={RunMinutes}, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    _run_clock(
        lambda: NX.LaunchNixieClock(
            Duration=RunMinutes, ShowIntro=False, StopEvent=StopEvent,
        )
    )


def ShowLaserClock(Command, StopEvent):
    """HH:MM forged by one continuous laser, left to right, top to bottom."""
    import LEDarcade as LED
    LED.Initialize()
    import LaserClock as LZ

    RunMinutes = Command.get("duration", 10)
    try:
        RunMinutes = float(RunMinutes)
    except (TypeError, ValueError):
        RunMinutes = 10.0

    print(
        f"[LEDcommander] Showing laser clock: "
        f"Duration={RunMinutes}, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    # LaserClock fades its own frames. The shared brightness ramp would
    # stack on top of that and hold black after the picture is already gone.
    _run_clock(
        lambda: LZ.LaunchLaserClock(
            Duration=RunMinutes, ShowIntro=False, StopEvent=StopEvent,
        ),
        fade_in=False,
        fade_out=False,
    )


def ShowLEDArcadeIntro(Command, StopEvent):
    """Spectacular multi-layer star + letter-circle boot title."""
    import LEDarcade as LED
    LED.Initialize()
    try:
        LED.TheMatrix.brightness = STREAM_MAX_BRIGHTNESS
    except Exception:
        pass
    print("[LEDcommander] LED ARCADE intro")
    try:
        import LEDArcadeIntro as INTRO
        INTRO.PlayLEDArcadeIntro(StopEvent=StopEvent)
    except Exception as e:
        print(f"[LEDcommander] Intro failed: {e}")
        traceback.print_exc()
    finally:
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)












def StartTwitchTimer(Command,StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    
    StreamStartedDateTime     = Command.get("StreamStartedDateTime", 1)
    StreamDurationHHMMSS      = Command.get("StreamDurationHHMMSS", 1)
    print(f"[LEDcommander][StartTwitchTimer] StreamDurationHHMMSS: ",StreamDurationHHMMSS)

    LED.DisplayTwitchTimer(
        CenterHoriz = True,
        CenterVert  = False,
        h   = 0,
        v   = 1, 
        hh  = 24,
        RGB              = LED.LowGreen,
        ShadowRGB        = LED.ShadowGreen,
        ZoomFactor       = 3,
        AnimationDelay   = 30,
        RunMinutes       = 10,
        StartDateTimeUTC = StreamStartedDateTime,
        HHMMSS           = StreamDurationHHMMSS,
        StopEvent        = StopEvent
    )
    LED.SweepClean()
          




def ShowTitleScreen(Command,StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    #Extract values from the Command dictionary
    #Populate input variables
    BigText             = Command.get("BigText","?")
    BigTextRGB          = Command.get("BigTextRGB",(255,0,0))
    BigTextShadowRGB    = Command.get("BigTextShadowRGB",(255,0,0))
    LittleText          = Command.get("LittleText","??")
    LittleTextRGB       = Command.get("LittleTextRGB",(255,0,0))
    LittleTextShadowRGB = Command.get("LittleTextShadowRGB",(255,0,0))
    ScrollText          = Command.get("ScrollText","??")
    ScrollTextRGB       = Command.get("ScrollTextRGB",(255,0,0))
    ScrollSleep         = Command.get("ScrollSleep",0.05)
    DisplayTime         = Command.get("DisplayTime",1)
    ExitEffect          = Command.get("ExitEffect",0)
    LittleTextZoom      = Command.get("LittleTextZoom",1)
    
    
    print(f"[LEDcommander] Showing title screen: BigText={BigText}, LittleText={LittleText}, ScrollText={ScrollText}")


    LED.ShowTitleScreen(
      BigText             = BigText,
      BigTextRGB          = BigTextRGB,
      BigTextShadowRGB    = BigTextShadowRGB,
      LittleText          = LittleText,
      LittleTextRGB       = LittleTextRGB,
      LittleTextShadowRGB = LittleTextShadowRGB,
      ScrollText          = ScrollText,
      ScrollTextRGB       = ScrollTextRGB,
      ScrollSleep         = ScrollSleep,
      DisplayTime         = DisplayTime,
      ExitEffect          = ExitEffect,
      LittleTextZoom      = LittleTextZoom
      )
    LED.SweepClean()












def StopTerminalMode():
    import LEDarcade as LED
    LED.Initialize()
    global CursorH, CursorV

    message_queue = []
    TerminalTypeSpeed = 0.08
    TerminalScrollSpeed = 0.08
    CursorRGB = (0, 255, 0)
    CursorDarkRGB = (0, 50, 0)
    
    print("=========================")
    print("== STOP TERMINAL MODE ==")
    print("=========================")
    LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
        LED.ScreenArray,
        Message="Stopping terminal...",
        CursorH=CursorH,
        CursorV=CursorV,
        MessageRGB=(100,100,0),
        CursorRGB=(0, 255, 0),
        CursorDarkRGB=(0, 50, 0),
        StartingLineFeed=1,
        TypeSpeed=TerminalTypeSpeed,
        ScrollSpeed=TerminalScrollSpeed
    )
    LED.ZoomScreen(LED.ScreenArray, 32, 1, Fade=True, ZoomSleep=0.05)
    LED.SweepClean()




def StartTerminalMode(TerminalQueue, StopEvent, InitialCommand=None):
    import LEDarcade as LED
    LED.Initialize()
    CursorH, CursorV = 0, 0
    message_queue = []
    TerminalTypeSpeed = 0.08
    TerminalScrollSpeed = 0.08
    CursorRGB = (0, 255, 0)
    CursorDarkRGB = (0, 50, 0)

    def _StopTerminalMode():
        nonlocal CursorH, CursorV
        print("=========================")
        print("== STOP TERMINAL MODE ==")
        print("=========================")
        LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
            LED.ScreenArray,
            Message="Stopping terminal...",
            CursorH=CursorH,
            CursorV=CursorV,
            MessageRGB=(0,200, 0),
            CursorRGB=CursorRGB,
            CursorDarkRGB=CursorDarkRGB,
            StartingLineFeed=1,
            TypeSpeed=TerminalTypeSpeed,
            ScrollSpeed=TerminalScrollSpeed
        )
        LED.ZoomScreen(LED.ScreenArray, 32, 1, Fade=True, ZoomSleep=0.03)

    print("=========================")
    print("== START TERMINAL MODE ==")
    print("=========================")

    if InitialCommand:
        message_queue.append(InitialCommand)

    while not StopEvent.is_set():
        try:
            try:
                Command = TerminalQueue.get(timeout=0.1)
                Action = Command.get("Action", "").lower()

                if Action == "terminalmessage":
                    message_queue.append(Command)
                    print(f"[TerminalMode] Queued: {Command.get('Message')[:40]}...")

                elif Action == "terminalmode_off":
                    print("[LEDcommander] RUN: terminalmode_OFF detected")
                    _StopTerminalMode()
                    StopEvent.set()

            except queue.Empty:
                pass

            if message_queue:
                Command = message_queue.pop(0)
                msg = Command.get("Message", None)
                if isinstance(msg, str):
                    rgb = Command.get("RGB", (255, 255, 255))
                    scroll_speed = Command.get("ScrollSleep", 0.05)
                    type_speed = Command.get("TypeSpeed", TerminalTypeSpeed)
                    repeat = max(int(Command.get("Repeat", 1)), 1)
                    header = Command.get("MessageHeader", "")
                    body = Command.get("MessageBody", "")
                    header_rgb = Command.get("HeaderRGB", (200, 200, 0))
                    stock_lines = Command.get("StockLines", [])
                    symbol_rgb = Command.get("SymbolRGB", (200, 0, 200))
                    error_text = Command.get("ErrorText", "")

                    for repeat_index in range(repeat):
                        if stock_lines:
                            import StockReport as SR
                            if header:
                                LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
                                    LED.ScreenArray, header + " ",
                                    CursorH=CursorH, CursorV=CursorV,
                                    MessageRGB=header_rgb,
                                    CursorRGB=CursorRGB, CursorDarkRGB=CursorDarkRGB,
                                    StartingLineFeed=1,
                                    TypeSpeed=type_speed,
                                    ScrollSpeed=scroll_speed
                                )
                            for stock_index, entry in enumerate(stock_lines):
                                blank_line_count = (
                                    SR.STOCK_BLANK_LINES_BEFORE_FIRST
                                    if stock_index == 0
                                    else SR.STOCK_BLANK_LINES_BETWEEN
                                )
                                for _ in range(blank_line_count):
                                    LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
                                        LED.ScreenArray, "",
                                        CursorH=CursorH, CursorV=CursorV,
                                        MessageRGB=rgb,
                                        CursorRGB=CursorRGB, CursorDarkRGB=CursorDarkRGB,
                                        StartingLineFeed=1,
                                        TypeSpeed=0,
                                        ScrollSpeed=scroll_speed
                                    )

                                symbol = entry.get("symbol", "")
                                if symbol:
                                    LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
                                        LED.ScreenArray, symbol,
                                        CursorH=CursorH, CursorV=CursorV,
                                        MessageRGB=symbol_rgb,
                                        CursorRGB=CursorRGB, CursorDarkRGB=CursorDarkRGB,
                                        StartingLineFeed=0,
                                        TypeSpeed=type_speed,
                                        ScrollSpeed=scroll_speed
                                    )

                                for detail_line in entry.get("detail_lines", []):
                                    LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
                                        LED.ScreenArray, detail_line,
                                        CursorH=CursorH, CursorV=CursorV,
                                        MessageRGB=rgb,
                                        CursorRGB=CursorRGB, CursorDarkRGB=CursorDarkRGB,
                                        StartingLineFeed=1,
                                        TypeSpeed=type_speed,
                                        ScrollSpeed=scroll_speed
                                    )
                            if error_text:
                                LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
                                    LED.ScreenArray, error_text,
                                    CursorH=CursorH, CursorV=CursorV,
                                    MessageRGB=rgb,
                                    CursorRGB=CursorRGB, CursorDarkRGB=CursorDarkRGB,
                                    StartingLineFeed=1,
                                    TypeSpeed=type_speed,
                                    ScrollSpeed=scroll_speed
                                )
                        elif header and body:
                            LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
                                LED.ScreenArray, header,
                                CursorH=CursorH, CursorV=CursorV,
                                MessageRGB=header_rgb,
                                CursorRGB=CursorRGB, CursorDarkRGB=CursorDarkRGB,
                                StartingLineFeed=1,
                                TypeSpeed=type_speed,
                                ScrollSpeed=scroll_speed
                            )
                            LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
                                LED.ScreenArray, body,
                                CursorH=CursorH, CursorV=CursorV,
                                MessageRGB=rgb,
                                CursorRGB=CursorRGB, CursorDarkRGB=CursorDarkRGB,
                                StartingLineFeed=0,
                                TypeSpeed=type_speed,
                                ScrollSpeed=scroll_speed
                            )
                        else:
                            LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
                                LED.ScreenArray, msg,
                                CursorH=CursorH, CursorV=CursorV,
                                MessageRGB=rgb,
                                CursorRGB=CursorRGB, CursorDarkRGB=CursorDarkRGB,
                                StartingLineFeed=1,
                                TypeSpeed=type_speed,
                                ScrollSpeed=scroll_speed
                            )

                        if repeat_index < repeat - 1:
                            LED.ScreenArray, CursorH, CursorV = LED.TerminalScroll(
                                LED.ScreenArray, "",
                                CursorH=CursorH, CursorV=CursorV,
                                MessageRGB=rgb,
                                CursorRGB=CursorRGB, CursorDarkRGB=CursorDarkRGB,
                                StartingLineFeed=1,
                                TypeSpeed=0,
                                ScrollSpeed=scroll_speed
                            )

                    if "PostScrollWait" in Command:
                        post_scroll_wait = float(Command.get("PostScrollWait", 0))
                        if post_scroll_wait > 0:
                            print(f"[TerminalMode] Post-scroll wait: {post_scroll_wait}s")
                            wait_end = time.time() + post_scroll_wait
                            while time.time() < wait_end and not StopEvent.is_set():
                                LED.BlinkCursor(
                                    CursorH=CursorH,
                                    CursorV=CursorV,
                                    CursorRGB=CursorRGB,
                                    CursorDarkRGB=CursorDarkRGB,
                                    BlinkSpeed=0.50,
                                    BlinkCount=2
                                )
                        if not StopEvent.is_set():
                            _StopTerminalMode()
                            StopEvent.set()
                            break
                else:
                    print("[TerminalMode] Skipped invalid or missing 'Message'.")

        except Exception as e:
            print(f"[TerminalMode] Error: {e}")

        if StopEvent.is_set():
            break

        LED.BlinkCursor(
            CursorH=CursorH,
            CursorV=CursorV,
            CursorRGB=CursorRGB,
            CursorDarkRGB=CursorDarkRGB,
            BlinkSpeed=0.50,
            BlinkCount=2
        )





def ShowHeart(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    StreamBrightness = 80
    GifBrightness    = 50
    MaxBrightness    = 100
    print("[LEDcommander][ShowHeart] Show beating heart")

    LED.TheMatrix.brightness = GifBrightness
    LED.ShowBeatingHeart(h=16, v=0, beats=5, Sleep=0.01) 
    LED.TheMatrix.brightness = MaxBrightness
    LED.SweepClean()



def _parse_sign_duration(Command, default_seconds, label):
    duration_str = Command.get("duration", default_seconds)
    try:
        duration = int(duration_str)
        if duration <= 0:
            duration = default_seconds
    except (ValueError, TypeError):
        print(f"[LEDcommander][{label}] Invalid duration provided, using default {default_seconds}s")
        duration = default_seconds
    return duration


def ShowOnAir(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    MaxBrightness = 100
    duration = _parse_sign_duration(Command, ON_AIR_DEFAULT_SECONDS, "ShowOnAir")
    message = Command.get("message") or Command.get("Message") or "ON AIR"

    print(f"[LEDcommander][ShowOnAir] Show {message} sign for {duration}s ({duration / 60:.0f} minutes)")

    LED.TheMatrix.brightness = MaxBrightness
    LED.ShowOnAir(StopEvent, duration=duration, message=message)

    print("[LEDcommander][ShowOnAir] Ending")
    if StopEvent.is_set():
        print("[LEDcommander][ShowOnAir] Stopped by showonair_off")
    else:
        print("[LEDcommander][ShowOnAir] Duration expired")
    LED.ZoomScreen(LED.ScreenArray, 32, 1, Fade=True, ZoomSleep=0.05)


def ShowCustomSign(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    MaxBrightness = 100
    duration = _parse_sign_duration(Command, SIGN_DEFAULT_SECONDS, "ShowCustomSign")
    message = Command.get("message") or Command.get("Message") or "ALERT"

    print(f"[LEDcommander][ShowCustomSign] Show {message} sign for {duration}s")

    LED.TheMatrix.brightness = MaxBrightness
    LED.ShowSign(StopEvent, duration=duration, message=message)

    print("[LEDcommander][ShowCustomSign] Ending")
    if StopEvent.is_set():
        print("[LEDcommander][ShowCustomSign] Stopped by showsign_off")
    else:
        print("[LEDcommander][ShowCustomSign] Duration expired")
    LED.ZoomScreen(LED.ScreenArray, 32, 1, Fade=True, ZoomSleep=0.05)



def ShowOnAir_old(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    StreamBrightness = 80
    GifBrightness    = 50
    MaxBrightness    = 100
    try:
      duration = int(Command.get("duration", 1800))
    except ValueError:
      duration = 1800
    print("[LEDcommander][ShowOnAir] Show ON AIR sign",duration)

    LED.TheMatrix.brightness = MaxBrightness
    LED.ShowOnAir(StopEvent,duration=duration) 
    LED.ZoomScreen(LED.ScreenArray, 32, 1, Fade=True, ZoomSleep=0.05)

    #LED.SweepClean()



def ShowIntro(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    StreamBrightness = 80
    GifBrightness    = 50
    MaxBrightness    = 100
    print("[LEDcommander][ShowIntro] Now scrolling text, star wars style")


    LED.TheMatrix.brightness = MaxBrightness
    LED.scroll_random_movie_intro(StopEvent=StopEvent)
    LED.SweepClean()


def ShowDemotivate(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    StreamBrightness = 80
    GifBrightness    = 50
    MaxBrightness    = 100
    print("[LEDcommander][ShowDemotivate] Now scrolling text, star wars style")


    LED.TheMatrix.brightness = MaxBrightness
    LED.scroll_random_demotivational_quote(StopEvent=StopEvent)
    LED.SweepClean()



def ShowGIF(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    StreamBrightness = 80
    GifBrightness    = 50
    MaxBrightness    = 100

    GIF              = Command.get("GIF",'./images/redalert.gif')
    loops            = Command.get("loops",5)
    sleep            = Command.get("sleep",0.06)

    print("[LEDcommander][ShowGIF] displaying a GIF: ",GIF)

    LED.TheMatrix.brightness = GifBrightness
    LED.DisplayGIF(GIFName=GIF,width=64,height=32,Loops=loops,sleep=sleep)
    LED.TheMatrix.brightness = MaxBrightness
    LED.SweepClean()




def ShowViewers(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    StreamBrightness = 80
    GifBrightness    = 50
    MaxBrightness    = 100

    print("[LEDcommander][ShowViewers] Showing image" )

    ChatUsers = Command.get("chatusers",["Nobody"])


    LED.TheMatrix.brightness = GifBrightness
    LED.ScrollJustJoinedUser(ChatUsers,'JustJoined.png',0.04)
    LED.TheMatrix.brightness = MaxBrightness
    
    #clean up the screen using animations
    LED.SweepClean()




def ShowImageZoom(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    StreamBrightness = 80
    GifBrightness    = 25
    MaxBrightness    = 100

    image            = Command.get("image",'./images/UserProfile.png')
    zoommin          = Command.get("zoommin",1)
    zoommax          = Command.get("zoommax",100)
    zoomfinal        = Command.get("zoomfinal",16)
    sleep            = Command.get("sleep",0.001)
    step             = Command.get("step",1)

    print("[LEDcommander][ShowImageZoom] Zoom an image  ZoomMin ZoomMax ZoomFinal",zoommin, zoommax, zoomfinal)
    

    LED.TheMatrix.brightness = GifBrightness
    LED.ZoomImage(ImageName=image,ZoomStart=zoommin,ZoomStop=zoommax,ZoomSleep=sleep,Step=step)
    LED.ZoomImage(ImageName=image,ZoomStart=zoommax,ZoomStop=zoomfinal,ZoomSleep=sleep,Step=step)
    time.sleep(3)
    LED.TheMatrix.brightness = MaxBrightness
    LED.SweepClean()


def LaunchDotInvaders(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import DotInvaders as DI

    Duration         = Command.get("duration",1)

    print("[LEDcommander][LaunchDotInvaders] Launching...")
    try:
        _run_game_dimmed(
            lambda: DI.LaunchDotInvaders(Duration=Duration, ShowIntro=True, StopEvent=StopEvent),
            fade_out=False,
        )
    finally:
        LED.SweepClean()



def LaunchDefender(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import Defender2 as DE
    Duration         = Command.get("duration",1)
    print(f"[LEDcommander][LaunchDefender] Launching Defender2 for {Duration} minutes...")
    try:
        _run_game_dimmed(
            lambda: DE.LaunchDefender2(Duration=Duration, ShowIntro=True, StopEvent=StopEvent),
            fade_out=False,
        )
    finally:
        LED.SweepClean()


def LaunchGravitySim(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import gravitysim as GR
    Duration         = Command.get("duration",30)
    if Duration=='':
        Duration = 30
    print("[LEDcommander][LaunchGravitySim] Launching...")
    _run_game_dimmed(
        lambda: GR.Launch(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchTron(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import Tron as TR
    Duration         = Command.get("duration",10)
    print("[LEDcommander][LaunchTron] Launching...")
    _run_game_dimmed(
        lambda: TR.LaunchTron(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchSpaceDot(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import SpaceDot as SD
    Duration         = Command.get("duration",10)
    print("[LEDcommander][LaunchSpaceDot] Launching...")
    _run_game_dimmed(
        lambda: SD.LaunchSpaceDot(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchPacDot(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import PacDot as PD
    Duration = Command.get("duration", 5)
    if Duration == "" or Duration is None:
        Duration = 5
    try:
        Duration = int(Duration)
    except (TypeError, ValueError):
        Duration = 5
    print(f"[LEDcommander][LaunchPacDot] Launching PacDot for {Duration} minutes...")
    try:
        _run_game_dimmed(
            lambda: PD.LaunchPacDot(Duration=Duration, ShowIntro=True, StopEvent=StopEvent),
            fade_out=False,
        )
    finally:
        LED.SweepClean()
    print("[LEDcommander][LaunchPacDot] PacDot finished — returning to rotation")


def LaunchDotZerk(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import DotZerk as DZ
    Duration = Command.get("duration", 5)
    if Duration == "" or Duration is None:
        Duration = 5
    try:
        Duration = int(Duration)
    except (TypeError, ValueError):
        Duration = 5
    print(f"[LEDcommander][LaunchDotZerk] Launching DotZerk for {Duration} minutes...")
    try:
        _run_game_dimmed(
            lambda: DZ.LaunchDotZerk(Duration=Duration, ShowIntro=True, StopEvent=StopEvent),
            fade_out=False,
        )
    finally:
        LED.SweepClean()
    print("[LEDcommander][LaunchDotZerk] DotZerk finished — returning to rotation")


def LaunchOutbreak(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import Outbreak as OB
    Duration         = Command.get("duration",10)
    print("[LEDcommander][LaunchOutbreak] Launching...")
    _run_game_dimmed(
        lambda: OB.LaunchOutbreak(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchLEDtv(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import LEDtv as TV
    # Default: 5 min channel surf — title drop → static → flashes → video
    # Only switches to YouTube/local play when a non-empty URL is provided.
    Duration = Command.get("duration", 5)
    try:
        Duration = float(Duration) if Duration not in (None, "") else 5.0
    except (TypeError, ValueError):
        Duration = 5.0
    YoutubeUrl = Command.get("youtube_url") or Command.get("url") or ""
    YoutubeUrl = str(YoutubeUrl).strip() or None
    Channel = Command.get("channel")
    if Channel is not None and str(Channel).strip() == "":
        Channel = None
    elif Channel is not None:
        try:
            Channel = int(Channel)
        except (TypeError, ValueError):
            Channel = None
    # Empty/missing URL → always full channel-surf sequence (ignore blank effect)
    if YoutubeUrl:
        Effect = (Command.get("effect") or "youtube")
    else:
        Effect = "channels"
    # show_intro / boot_intro: ?tv full cold open; ?tvN tunes fast (no title/static)
    ShowIntro = Command.get("show_intro", True)
    if isinstance(ShowIntro, str):
        ShowIntro = ShowIntro.strip().lower() not in ("0", "false", "no", "off")
    BootIntro = Command.get("boot_intro", True)
    if isinstance(BootIntro, str):
        BootIntro = BootIntro.strip().lower() not in ("0", "false", "no", "off")
    # Tuning to a channel: skip intros unless explicitly requested
    if Channel is not None and "show_intro" not in Command:
        ShowIntro = False
    if Channel is not None and "boot_intro" not in Command:
        BootIntro = False
    print(
        "[LEDcommander][LaunchLEDtv] duration={} effect={!r} url={!r} "
        "channel={!r} intro={} boot={} brightness={}".format(
            Duration, Effect, YoutubeUrl, Channel, ShowIntro, BootIntro,
            STREAM_GAME_BRIGHTNESS,
        )
    )
    try:
        _run_game_dimmed(
            lambda: TV.LaunchLEDtv(
                duration=Duration,
                show_intro=bool(ShowIntro),
                stop_event=StopEvent,
                effect=Effect,
                youtube_url=YoutubeUrl,
                channel=Channel,
                boot_intro=bool(BootIntro),
            ),
            fade_in=not (bool(ShowIntro) or bool(BootIntro)),
            fade_out=False,
        )
    finally:
        try:
            LED.SweepClean()
        except Exception:
            pass


def LaunchBlasteroids(Command, StopEvent):
    import LEDarcade as LED
    #LED.Initialize()
    import Blasteroids as BL
    Duration         = Command.get("duration",10)
    print("[LEDcommander][LaunchBlasteroids] Launching...")
    _run_game_dimmed(
        lambda: BL.LaunchBlasteroids(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchStockTicker(Command, StopEvent):
    import LEDarcade as LED
    #LED.Initialize()
    import StockTicker as ST
    Duration         = Command.get("duration",10)
    Symbols          = Command.get("symbols")
    print("[LEDcommander][LaunchStockTicker] Launching...")
    ST.main(Duration=Duration, StopEvent=StopEvent, Symbols=Symbols)




def LaunchMazeCar(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import MazeCar as MC
    Duration = Command.get("duration", 10)
    print(f"[LEDcommander][LaunchMazeCar] Launching for {Duration} minutes...")
    _run_game_dimmed(
        lambda: MC.LaunchMazeCar(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchRallyDot(Command, StopEvent):
    """Launch Rally Dot. Default duration is 5 minutes (same as idle rotation)."""
    import LEDarcade as LED
    LED.Initialize()
    import RallyDot as RD
    Duration = Command.get("duration", 5)
    if Duration == "" or Duration is None:
        Duration = 5
    try:
        Duration = int(Duration)
    except (TypeError, ValueError):
        Duration = 5
    if Duration <= 0:
        Duration = 5
    print(f"[LEDcommander][LaunchRallyDot] Launching for {Duration} minutes...")
    try:
        _run_game_dimmed(
            lambda: RD.LaunchRallyDot(Duration=Duration, ShowIntro=True, StopEvent=StopEvent),
            fade_out=False,
        )
    finally:
        try:
            LED.SweepClean()
        except Exception:
            pass
    print("[LEDcommander][LaunchRallyDot] finished — returning to rotation")


def LaunchSpaceExplorer(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import SpaceExplorer as SE
    Duration = Command.get("duration", 10)
    print(f"[LEDcommander][LaunchSpaceExplorer] Launching for {Duration} minutes...")
    _run_game_dimmed(
        lambda: SE.LaunchSpaceExplorer(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchSkyfall(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import Skyfall as SF
    Duration = Command.get("duration", 10)
    try:
        Duration = float(Duration) if Duration not in (None, "") else 10.0
    except (TypeError, ValueError):
        Duration = 10.0
    print(
        f"[LEDcommander][LaunchSkyfall] Launching for {Duration} minutes "
        f"(StopEvent wired, brightness={STREAM_GAME_BRIGHTNESS})..."
    )
    try:
        _run_game_dimmed(
            lambda: SF.LaunchSkyfall(Duration=Duration, ShowIntro=False, StopEvent=StopEvent)
        )
    finally:
        print("[LEDcommander][LaunchSkyfall] Process exit")
        try:
            LED.ClearBigLED()
            LED.ClearBuffers()
        except Exception:
            pass


def LaunchSpaceClock(Command, StopEvent):
    """Space Clock — parallax fly-through with clocks on planets (5 min)."""
    import LEDarcade as LED
    LED.Initialize()
    import SpaceClock as SC
    Duration = Command.get("duration", 5)
    if Duration in (None, ""):
        Duration = 5
    try:
        Duration = float(Duration)
    except (TypeError, ValueError):
        Duration = 5.0
    if Duration <= 0:
        Duration = 5.0
    print(
        f"[LEDcommander][LaunchSpaceClock] Space Clock — "
        f"{Duration} minutes..."
    )
    try:
        _run_game_dimmed(
            lambda: SC.LaunchSpaceClock(
                Duration=Duration, ShowIntro=True, StopEvent=StopEvent
            ),
            fade_in=True,
        )
    finally:
        print("[LEDcommander][LaunchSpaceClock] finished")
        try:
            LED.ClearBigLED()
            LED.ClearBuffers()
        except Exception:
            pass


def LaunchNightDriver(Command, StopEvent):
    """Night Driver — 1976-style auto-play night drive (5 min)."""
    import LEDarcade as LED
    LED.Initialize()
    import NightDriver as ND
    Duration = Command.get("duration", 5)
    if Duration in (None, ""):
        Duration = 5
    try:
        Duration = float(Duration)
    except (TypeError, ValueError):
        Duration = 5.0
    if Duration <= 0:
        Duration = 5.0
    print(
        f"[LEDcommander][LaunchNightDriver] Night Driver — "
        f"{Duration} minutes..."
    )
    try:
        _run_game_dimmed(
            lambda: ND.LaunchNightDriver(
                Duration=Duration, ShowIntro=True, StopEvent=StopEvent
            )
        )
    finally:
        print("[LEDcommander][LaunchNightDriver] finished")
        try:
            LED.ClearBigLED()
            LED.ClearBuffers()
        except Exception:
            pass


def LaunchArtilleryTime(Command, StopEvent):
    """Artillery Time — best-of-3 duel on a wide scrolling battlefield (5 min)."""
    import LEDarcade as LED
    LED.Initialize()
    import ArtilleryTime as AT
    Duration = Command.get("duration", 5)
    if Duration in (None, ""):
        Duration = 5
    try:
        Duration = float(Duration)
    except (TypeError, ValueError):
        Duration = 5.0
    if Duration <= 0:
        Duration = 5.0
    print(
        f"[LEDcommander][LaunchArtilleryTime] Artillery Time — "
        f"{Duration} minutes..."
    )
    try:
        _run_game_dimmed(
            lambda: AT.LaunchArtilleryTime(
                Duration=Duration, ShowIntro=True, StopEvent=StopEvent
            )
        )
    finally:
        print("[LEDcommander][LaunchArtilleryTime] finished")
        try:
            LED.ClearBigLED()
            LED.ClearBuffers()
        except Exception:
            pass


def LaunchFallingSand(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import FallingSand as FS
    Duration         = Command.get("duration",10)
    print("[LEDcommander][LaunchFallingSand] Launching...")
    _run_game_dimmed(
        lambda: FS.LaunchFallingSand(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchParticles(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import particles as PT
    Duration = Command.get("duration", 10)
    print(f"[LEDcommander][LaunchParticles] Launching for {Duration} minutes...")
    # ShowIntro=True so title / open screens match other games (and LEDsim flush path)
    _run_game_dimmed(
        lambda: PT.LaunchParticles(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchFractal(Command, StopEvent):
    """Fractal Blaster — multi-type zoom tour + clock reveal (idle rotation: 5 min)."""
    import LEDarcade as LED
    LED.Initialize()
    import Fractal as FR
    Duration = Command.get("duration", 5)
    if Duration in (None, ""):
        Duration = 5
    try:
        Duration = float(Duration)
    except (TypeError, ValueError):
        Duration = 5.0
    if Duration <= 0:
        Duration = 5.0
    print(f"[LEDcommander][LaunchFractal] Fractal Blaster — {Duration} minutes...")
    _run_game_dimmed(
        lambda: FR.LaunchFractal(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchPlanetFly(Command, StopEvent):
    """Planet Blast — default 5 minutes; exits early on StopEvent (next/stop)."""
    import LEDarcade as LED
    LED.Initialize()
    import planetblast as PF
    Duration = Command.get("duration", 5)
    if Duration in (None, ""):
        Duration = 5
    try:
        Duration = float(Duration)
    except (TypeError, ValueError):
        Duration = 5.0
    print(
        f"[LEDcommander][LaunchPlanetFly] Planet Blast for {Duration} minutes "
        f"(StopEvent wired)..."
    )
    try:
        _run_game_dimmed(
            lambda: PF.LaunchPlanetFly(
                Duration=Duration, ShowIntro=True, StopEvent=StopEvent
            )
        )
    finally:
        print("[LEDcommander][LaunchPlanetFly] finished — returning to rotation")


def LaunchPinball(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import Pinball as PB
    Duration = Command.get("duration", 10)
    print(f"[LEDcommander][LaunchPinball] Launching for {Duration} minutes...")
    _run_game_dimmed(
        lambda: PB.LaunchPinball(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
    )


def LaunchPinball2(Command, StopEvent):
    """Gottlieb Central Park (1966) inspired table."""
    import LEDarcade as LED
    LED.Initialize()
    import Pinball2 as PB2
    Duration = Command.get("duration", 10)
    print(
        f"[LEDcommander][LaunchPinball2] Central Park — {Duration} minutes..."
    )
    _run_game_dimmed(
        lambda: PB2.LaunchPinball2(
            Duration=Duration, ShowIntro=True, StopEvent=StopEvent
        )
    )



def ShowAnalogClock(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    import AnalogClock as AC
    Duration = Command.get("duration", 10)
    try:
        Duration = float(Duration)
    except (TypeError, ValueError):
        Duration = 10.0
    print(
        f"[LEDcommander][ShowAnalogClock] Launching... "
        f"duration={Duration:g} min, brightness={STREAM_CLOCK_BRIGHTNESS}"
    )

    _run_clock(
        lambda: AC.RunClock(Duration=Duration, StopEvent=StopEvent)
    )





def StarryNightDisplayText(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()
    print("[LEDcommander][StarryNightDisplay] Launching...")
    Text1  = Command.get("text1",'')
    Text2  = Command.get("text2",'')
    Text3  = Command.get("text3",'')

    LED.StarryNightDisplayText(
    Text1       = Text1,
    Text2       = Text2,
    Text3       = Text3, 
    ScrollSleep = 0.01,
    RunSeconds  = 30
    )







#-------------------------------------------------------------------------------
# Main Processing
#
#-------------------------------------------------------------------------------
FallbackGenerator = fallback_action_generator()

if __name__ == "__main__":
    LEDupdate.save_launcher("LEDcommander.py")
    # Standalone commander: full brightness (do not inherit a stale stream flag)
    os.environ["LEDARCADE_STREAM_MODE"] = "0"
    # Re-resolve after env change (module may have been imported already)
    globals()["STREAM_MODE"] = False
    globals()["STREAM_GAME_BRIGHTNESS"] = STREAM_MAX_BRIGHTNESS
    globals()["STREAM_CLOCK_BRIGHTNESS"] = STREAM_MAX_BRIGHTNESS

    CommandQueue = Queue()
    commander_process = Process(target=Run, args=(CommandQueue,))
    commander_process.start()

    webserver_process = Process(target=serve_web_control, args=(CommandQueue,))
    webserver_process.start()

    print("")
    print(
        "[LEDcommander][main] Processes started "
        "(standalone: game/clock brightness=100)"
    )
    
    # Remove joins for now
    # commander_process.join()
    # webserver_process.join()

    # Keep main thread alive so child processes aren't killed.
    # Display rotation when idle is handled inside Run(); do not push timed
    # commands here — that loop preempted web-panel launches every RotateClockDelay minutes.
    while True:
        time.sleep(60)