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

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"],
    "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_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"],
    "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": [],
    "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",
)


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"] + [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", "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()]

    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):
    """Run a game at stream/game brightness; full brightness after.
    Standalone LEDcommander: 100. Twitch stream mode: dimmed (70).
    """
    _refresh_stream_brightness()
    _apply_matrix_brightness(STREAM_GAME_BRIGHTNESS)
    try:
        return launch_fn()
    finally:
        _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). Weather ends when
    the scroll finishes. Rally Dot runs until game over.
    """
    # 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_dotinvaders", "duration": 5},
        {"Action": "launch_gravitysim", "duration": 5},
        {"Action": "launch_tron", "duration": 5},
        # outbreak paused from idle rotation for now
        # {"Action": "launch_outbreak", "duration": 5},
        {"Action": "launch_spacedot", "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_planet", "duration": 5},
        # One pinball slot per lap — table chosen at random when it runs
        {"Action": "launch_pinball_random", "duration": 5},
        {"Action": "launch_rallydot"},  # until game over
    ]

    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": "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}")

            # Handle off (force stop, proceed)
            if Action == "showonair_off":
                if IsOnAirActive:
                    print("[LEDcommander] Manual stop OnAir, 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

            # 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, hold the display until manual off or duration expiry.
            if IsOnAirActive and Action not in (
                "showonair", "showonair_off", "stop", "stopclock", "next", "quit",
            ):
                print(f"[LEDcommander] OnAir 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",
                        "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 == "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()


            #----------------------------------
            #-- 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}"
    )

    try:
        LED.TheMatrix.brightness = STREAM_CLOCK_BRIGHTNESS
        LED.DisplayDigitalClock(
            ClockStyle=ClockStyle,
            CenterHoriz=True,
            v=1,
            hh=24,
            RGB=LED.LowGreen,
            ShadowRGB      = LED.ShadowGreen,
            ZoomFactor     = ZoomFactor,
            AnimationDelay = AnimationDelay,
            RunMinutes     = RunMinutes,
            StopEvent      = StopEvent
        )
    finally:
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)



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}"
    )

    try:
        LED.TheMatrix.brightness = STREAM_CLOCK_BRIGHTNESS
        LED.DisplayDigitalClock(
            ClockStyle=ClockStyle,
            CenterHoriz=True,
            v=1,
            hh=24,
            RGB=LED.LowGreen,
            ShadowRGB      = LED.ShadowGreen,
            ZoomFactor     = ZoomFactor,
            AnimationDelay = AnimationDelay,
            RunMinutes     = RunMinutes,
            StopEvent      = StopEvent
        )
    finally:
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)


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}"
    )

    try:
        LED.TheMatrix.brightness = STREAM_CLOCK_BRIGHTNESS
        LED.DisplayDigitalClock(
            ClockStyle=6,
            CenterHoriz=True,
            v=1,
            hh=24,
            RunMinutes=RunMinutes,
            StopEvent=StopEvent,
        )
    finally:
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)


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}"
    )

    try:
        LED.TheMatrix.brightness = STREAM_CLOCK_BRIGHTNESS
        SSC.LaunchSevenSegClock(
            Duration=RunMinutes, ShowIntro=False, StopEvent=StopEvent,
        )
    finally:
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)


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}"
    )

    try:
        LED.TheMatrix.brightness = STREAM_CLOCK_BRIGHTNESS
        RC.LaunchRocketClock(
            Duration=RunMinutes, ShowIntro=False, StopEvent=StopEvent,
        )
    finally:
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)


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}"
    )

    try:
        LED.TheMatrix.brightness = STREAM_CLOCK_BRIGHTNESS
        WC.LaunchWaterClock(
            Duration=RunMinutes, ShowIntro=False, StopEvent=StopEvent,
        )
    finally:
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)


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 ShowOnAir(Command, StopEvent):
    import LEDarcade as LED
    LED.Initialize()

    MaxBrightness = 100

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

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

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

    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 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)
        )
    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)
        )
    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)
        )
    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)
        )
    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),
            )
        )
    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 empty/0 = play until game over (3 lives)."""
    import LEDarcade as LED
    LED.Initialize()
    import RallyDot as RD
    raw = Command.get("duration", None)
    # Default / 0 / blank → run until stock lives exhausted (not a wall-clock cut)
    until_game_over = raw in (None, "", 0, "0")
    if until_game_over:
        Duration = 100000
        print("[LEDcommander][LaunchRallyDot] Launching until game over...")
    else:
        try:
            Duration = int(raw)
        except (TypeError, ValueError):
            Duration = 100000
            until_game_over = True
            print("[LEDcommander][LaunchRallyDot] bad duration; until game over")
        else:
            if Duration <= 0:
                Duration = 100000
                until_game_over = True
                print("[LEDcommander][LaunchRallyDot] Launching until game over...")
            else:
                print(f"[LEDcommander][LaunchRallyDot] Launching for {Duration} minutes...")
    try:
        _run_game_dimmed(
            lambda: RD.LaunchRallyDot(Duration=Duration, ShowIntro=True, StopEvent=StopEvent)
        )
    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 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}"
    )

    try:
        LED.TheMatrix.brightness = STREAM_CLOCK_BRIGHTNESS
        AC.RunClock(Duration=Duration, StopEvent=StopEvent)
    finally:
        _apply_matrix_brightness(STREAM_MAX_BRIGHTNESS)





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)