staticfx 2.0.0__py3-none-any.whl

staticfx/__init__.py

@@ -0,0 +1,3 @@
+"""StaticFX: animated ASCII effects for your terminal."""
+
+__version__ = "2.0.0"

staticfx/__main__.py

@@ -0,0 +1,5 @@
+"""``python -m staticfx``."""
+
+from staticfx.cli import main
+
+raise SystemExit(main())

staticfx/app/__init__.py

@@ -0,0 +1 @@
+"""The interactive application: state, key map, player and run loop."""

staticfx/app/app.py

@@ -0,0 +1,335 @@
+"""The application: settings, the user's library, the player and the screen stack.
+
+Nothing here touches the terminal (see ``session.py``), so the whole app can
+be driven key by key in tests.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import random
+from pathlib import Path
+from typing import Any
+
+from staticfx import themes
+from staticfx.app.keymap import Keymap
+from staticfx.app.player import Player
+from staticfx.core.frame import Frame
+from staticfx.effects.engine import describe
+from staticfx.effects.registry import BUILTIN, USER, USER_CATEGORY, Registry
+from staticfx.effects.spec import EffectSpec, recipe_spec
+from staticfx.library import config
+from staticfx.library.config import Settings
+from staticfx.library.effects import EffectLibrary, UserEffect
+from staticfx.library.looks import Look, LookStore
+from staticfx.ui.play import PlayScreen
+from staticfx.ui.screen import Screen
+from staticfx.ui.widgets import ASCII, UNICODE, Canvas, Style, fit
+
+DEFAULT_EFFECT = "matrix"
+RECENT_LIMIT = 30
+MIN_WIDTH, MIN_HEIGHT = 40, 12
+
+
+class App:
+    def __init__(
+        self,
+        settings: Settings | None = None,
+        data_dir: Path | None = None,
+        *,
+        utf8: bool = True,
+        persist_settings: bool = True,
+        registry: Registry | None = None,
+        rng: random.Random | None = None,
+    ) -> None:
+        self.settings = settings or Settings()
+        self.data_dir = data_dir
+        # False for one-off commands and --no-save: nothing writes config.json or
+        # runs one-time migrations, so those only happen in a real session.
+        self.persist_settings = persist_settings and data_dir is not None
+        self.utf8 = utf8  # can the terminal show non-ASCII characters at all?
+        self.ascii_only, unicode = self._characters()
+        self.chrome = ASCII if self.ascii_only else UNICODE
+        self.rng = rng or random.Random()
+        self.registry = registry or Registry()
+        self.library = EffectLibrary(data_dir / "effects") if data_dir else None
+        self.looks = LookStore(data_dir / "looks.json" if data_dir else None)
+        self.keymap = Keymap()
+        self.notes: list[str] = []  # problems found while loading, shown once at startup
+        self._session_only: dict[str, Any] = {}  # setting -> value to save instead
+
+        self.player = Player(self.registry, self.rng, unicode=unicode, ascii_only=self.ascii_only)
+        self.player.speed = self.settings.speed
+        self.player.post.crt = self.settings.crt
+        self.player.post.glitch = self.settings.glitch
+        self.player.post.recolour = self.settings.recolour
+
+        self.screens: list[Screen] = []
+        self.running = True
+        self.suspend_requested = False
+        self.dirty = False  # settings changed since the last save
+        self.toast_text = ""
+        self.toast_time = 0.0
+        self.auto = False
+        self.auto_timer = 0.0
+        self.show_status = False
+        self.width, self.height = 80, 24
+
+    def start(self) -> None:
+        """Load the user's things and pick the first effect. Call once, before running."""
+        self.notes += self.keymap.apply_changes(self.settings.keybinds)
+        self.notes += self.looks.load()
+        if self.library is not None and self.data_dir is not None:
+            if self.persist_settings and not self.settings.imported_plugins:
+                self._import_plugins(self.library, self.data_dir / "plugins")
+            effects, problems = self.library.load()
+            self.notes += [f"skipped {problem}" for problem in problems]
+            for effect in effects:
+                self.registry.put_user(self.user_spec(effect))
+
+        self.settings.favorites = [k for k in self.settings.favorites if k in self.registry]
+        self.settings.recent = [k for k in self.settings.recent if k in self.registry]
+        if self.settings.theme == "strobe" and not self.settings.allow_flashing:
+            self.settings.theme = themes.DEFAULT
+        self.player.set_theme(self.settings.theme)
+
+        try:
+            self.play(self.registry.resolve(self.settings.effect), announce=False)
+        except KeyError:
+            self.notes.append(f"'{self.settings.effect}' no longer exists; playing Matrix Rain")
+            self.play(DEFAULT_EFFECT, announce=False)
+        self.screens = [PlayScreen(self)]
+
+    def override(self, name: str, value: Any) -> None:
+        """Change a setting for this session only, as command-line options do."""
+        self._session_only.setdefault(name, getattr(self.settings, name))
+        setattr(self.settings, name, value)
+
+    def keep(self, name: str) -> None:
+        """Make a session-only setting permanent (the user changed it in Settings)."""
+        self._session_only.pop(name, None)
+
+    def _import_plugins(self, library: EffectLibrary, folder: Path) -> None:
+        """One-time copy of 1.x plugin files into My Effects."""
+        self.settings.imported_plugins = True
+        self.dirty = True
+        if not folder.is_dir():
+            return
+        count, problems = library.import_legacy_plugins(folder)
+        self.notes += problems
+        if count:
+            self.notes.append(f"Copied {count} effect(s) from the old plugins folder to My Effects")
+        self.save_settings()  # record it now, so a crash can't make it copy them twice
+
+    def _characters(self) -> tuple[bool, bool]:
+        """(ascii_only, katakana) from the setting and what the terminal supports."""
+        ascii_only = self.settings.characters == "ascii" or not self.utf8
+        return ascii_only, self.settings.characters == "katakana" and not ascii_only
+
+    def apply_characters(self) -> None:
+        """Rebuild what's on screen after the Characters setting changed."""
+        self.ascii_only, unicode = self._characters()
+        self.chrome = ASCII if self.ascii_only else UNICODE
+        self.player.ascii_only, self.player.unicode = self.ascii_only, unicode
+        self.player.reload()
+
+    def user_spec(self, effect: UserEffect) -> EffectSpec:
+        description = effect.description or describe(effect.recipe)
+        return recipe_spec(effect.key, effect.name, description, USER_CATEGORY, USER, effect.recipe)
+
+    @property
+    def top(self) -> Screen:
+        return self.screens[-1]
+
+    def push(self, screen: Screen) -> None:
+        self.screens.append(screen)
+
+    def pop(self, screen: Screen | None = None) -> None:
+        """Remove ``screen`` (default: the top one). The play screen can't be removed."""
+        screen = screen or self.top
+        if screen in self.screens[1:]:
+            self.screens.remove(screen)
+            screen.on_close()
+
+    def handle_key(self, key: str) -> None:
+        if key == "ctrl-z":
+            self.suspend_requested = True
+        elif self.too_small and key in ("q", "ctrl-c"):
+            self.running = False
+        else:
+            self.top.handle(key)
+
+    @property
+    def too_small(self) -> bool:
+        return self.width < MIN_WIDTH or self.height < MIN_HEIGHT
+
+    def play(self, key: str, announce: bool = True) -> None:
+        self.player.play(key)
+        self.settings.effect = key
+        recent = self.settings.recent
+        if key in recent:
+            recent.remove(key)
+        recent.insert(0, key)
+        del recent[RECENT_LIMIT:]
+        self.dirty = True
+        self.auto_timer = self.settings.auto_seconds
+        if announce:
+            self.toast(self.registry[key].label)
+
+    def step(self, delta: int) -> None:
+        keys = self.registry.keys()
+        index = keys.index(self.player.key) if self.player.key in keys else 0
+        self.play(keys[(index + delta) % len(keys)])
+
+    def play_random(self) -> None:
+        choices = [k for k in self.auto_pool() if k != self.player.key and k in self.registry]
+        if choices:
+            self.play(self.rng.choice(choices))
+        else:
+            self.step(1)
+
+    def play_previous(self) -> None:
+        if len(self.settings.recent) < 2:
+            self.toast("Nothing to go back to yet")
+        else:
+            self.play(self.settings.recent[1])
+
+    def auto_pool(self) -> list[str]:
+        """What auto-cycle and random pick from: favourites if you have a few,
+        otherwise the built-ins plus the Gallery of the best generated effects."""
+        if len(self.settings.favorites) >= 2:
+            return list(self.settings.favorites)
+        builtins = [s.key for s in self.registry.specs() if s.kind == BUILTIN]
+        return builtins + list(self.registry.gallery)
+
+    def toggle_auto(self) -> None:
+        self.auto = not self.auto
+        self.auto_timer = self.settings.auto_seconds
+        source = "favourites" if len(self.settings.favorites) >= 2 else "built-ins and Gallery"
+        state = f"every {self.settings.auto_seconds:g}s from {source}" if self.auto else "off"
+        self.toast(f"Auto-cycle {state}")
+
+    def is_favorite(self, key: str) -> bool:
+        return key in self.settings.favorites
+
+    def toggle_favorite(self, key: str) -> bool:
+        """Returns True if ``key`` is now a favourite."""
+        favorites = self.settings.favorites
+        added = key not in favorites
+        if added:
+            favorites.append(key)
+        else:
+            favorites.remove(key)
+        self.dirty = True
+        return added
+
+    def set_theme(self, name: str) -> None:
+        self.player.set_theme(name)
+        self.settings.theme = self.player.theme_name
+        self.dirty = True
+
+    def theme_names(self) -> list[str]:
+        return themes.names(self.settings.allow_flashing)
+
+    def current_look(self, name: str) -> Look:
+        post = self.player.post
+        return Look(
+            name=name,
+            effect=self.player.key,
+            theme=self.player.theme_name,
+            speed=round(self.player.speed, 2),
+            crt=post.crt,
+            glitch=post.glitch,
+            recolour=post.recolour,
+        )
+
+    def apply_look(self, look: Look) -> None:
+        if look.effect not in self.registry:
+            self.toast(f"'{look.name}' uses an effect that no longer exists")
+            return
+        if look.theme == "strobe" and not self.settings.allow_flashing:
+            settings = self.keymap.label("settings", self.ascii_only)
+            self.toast(f"That look uses Strobe; allow flashing in Settings ({settings}) first")
+            return
+        self.set_theme(look.theme)
+        self.player.speed = look.speed
+        post = self.player.post
+        post.crt, post.glitch, post.recolour = look.crt, look.glitch, look.recolour
+        self.play(look.effect, announce=False)
+        self.toast(f"Look: {look.name}")
+
+    def save_effect(self, effect: UserEffect) -> bool:
+        if self.library is None:
+            self.toast("Can't save: StaticFX is running without a data folder")
+            return False
+        try:
+            self.library.save(effect)
+        except OSError as exc:
+            self.toast(f"Couldn't save: {exc.strerror or exc}")
+            return False
+        self.registry.put_user(self.user_spec(effect))
+        return True
+
+    def delete_effect(self, key: str) -> None:
+        if self.library is not None:
+            self.library.delete(key.removeprefix("my_"))
+        self.registry.remove_user(key)
+        for keys in (self.settings.favorites, self.settings.recent):
+            if key in keys:
+                keys.remove(key)
+        self.dirty = True
+        if self.player.key == key:
+            self.play(DEFAULT_EFFECT, announce=False)
+
+    def toast(self, text: str, seconds: float = 2.0) -> None:
+        self.toast_text, self.toast_time = text, seconds
+
+    def resize(self, width: int, height: int) -> None:
+        self.width, self.height = width, height
+        self.player.resize(width, height)
+
+    def update(self, dt: float) -> None:
+        self.player.update(dt)
+        for screen in self.screens:
+            screen.update(dt)
+        self.toast_time = max(0.0, self.toast_time - dt)
+        if self.auto and len(self.screens) == 1:
+            self.auto_timer -= dt
+            if self.auto_timer <= 0:
+                self.play_random()
+
+    def draw(self, frame: Frame) -> None:
+        theme = self.player.draw(frame)
+        canvas = Canvas(frame, self.chrome, Style.from_theme(theme))
+        if self.too_small:
+            self._draw_too_small(canvas)
+            return
+        for screen in self.screens:
+            screen.draw(canvas)
+        if self.toast_time > 0 and self.toast_text:
+            text = f" {fit(self.toast_text, frame.width - 4, self.chrome.ellipsis)} "
+            canvas.text(frame.width - len(text) - 1, frame.height - 1, text, canvas.style.accent)
+
+    def _draw_too_small(self, canvas: Canvas) -> None:
+        lines = ["Terminal too small", f"need {MIN_WIDTH}x{MIN_HEIGHT}", "(q quits)"]
+        top = max(0, canvas.height // 2 - 1)
+        for i, line in enumerate(lines):
+            line = fit(line, canvas.width, "")
+            canvas.text(max(0, (canvas.width - len(line)) // 2), top + i, line, canvas.style.title)
+
+    def save_settings(self) -> None:
+        """Write ``config.json`` if anything changed. Failures are reported, not raised."""
+        if not self.dirty:
+            return
+        self.dirty = False
+        settings = self.settings
+        post = self.player.post
+        settings.speed = round(self.player.speed, 2)
+        settings.crt, settings.glitch, settings.recolour = post.crt, post.glitch, post.recolour
+        settings.keybinds = self.keymap.changes()
+        if self.persist_settings and self.data_dir is not None:
+            try:
+                saved = dataclasses.replace(settings, **self._session_only)
+                config.save(saved, self.data_dir / "config.json")
+            except OSError as exc:
+                self.toast(f"Couldn't save settings: {exc.strerror or exc}")

staticfx/app/keymap.py

@@ -0,0 +1,163 @@
+"""Key bindings for the main view.
+
+There is one table of actions (shown in this order in the help screen) and
+one table of default keys. Only the user's changes are saved, so a future
+release can change a default without old config files pinning the old one.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+# action -> (group, description)
+ACTIONS: dict[str, tuple[str, str]] = {
+    "next": ("Browse", "Next effect"),
+    "previous": ("Browse", "Previous effect"),
+    "random": ("Browse", "Random effect"),
+    "back": ("Browse", "Back to the last effect"),
+    "auto": ("Browse", "Auto-cycle through effects"),
+    "browse": ("Menus", "Browse and search effects"),
+    "themes": ("Menus", "Choose a theme"),
+    "looks": ("Menus", "Saved looks"),
+    "settings": ("Menus", "Settings and key bindings"),
+    "help": ("Menus", "All keys"),
+    "new_effect": ("Create", "New effect in the Studio"),
+    "edit_effect": ("Create", "Edit this effect in the Studio"),
+    "favorite": ("Create", "Add to / remove from favourites"),
+    "save_look": ("Create", "Save effect + theme + filters as a look"),
+    "next_theme": ("Look", "Next theme"),
+    "crt": ("Look", "CRT scanlines filter"),
+    "glitch": ("Look", "Glitch filter"),
+    "recolour": ("Look", "Rainbow recolour filter"),
+    "pause": ("Playback", "Pause"),
+    "restart": ("Playback", "Restart the effect"),
+    "faster": ("Playback", "Faster"),
+    "slower": ("Playback", "Slower"),
+    "status": ("Playback", "Show or hide the status bar"),
+    "quit": ("Playback", "Quit"),
+}
+
+DEFAULT_KEYS: dict[str, str] = {
+    "right": "next",
+    "space": "next",
+    "left": "previous",
+    "x": "random",
+    "b": "back",
+    "a": "auto",
+    "m": "browse",
+    "enter": "browse",
+    "t": "themes",
+    "l": "looks",
+    "o": "settings",
+    "?": "help",
+    "h": "help",
+    "n": "new_effect",
+    "e": "edit_effect",
+    "f": "favorite",
+    "s": "save_look",
+    "c": "next_theme",
+    "v": "crt",
+    "g": "glitch",
+    "w": "recolour",
+    "p": "pause",
+    "z": "restart",
+    "up": "faster",
+    "+": "faster",
+    "=": "faster",
+    "down": "slower",
+    "-": "slower",
+    "i": "status",
+    "q": "quit",
+}
+
+# Keys that always mean the same thing and can't be rebound: Esc and Ctrl-C
+# back out of anything, Ctrl-Z suspends.
+RESERVED = frozenset({"escape", "ctrl-c", "ctrl-z"})
+UNBOUND = "none"
+
+KEY_LABELS = {
+    "left": "←",
+    "right": "→",
+    "up": "↑",
+    "down": "↓",
+    "space": "Space",
+    "enter": "Enter",
+    "tab": "Tab",
+    "escape": "Esc",
+    "backspace": "Backspace",
+    "delete": "Del",
+    "pageup": "PgUp",
+    "pagedown": "PgDn",
+    "home": "Home",
+    "end": "End",
+}
+ASCII_ARROWS = {"left": "Left", "right": "Right", "up": "Up", "down": "Down"}
+
+
+def key_label(key: str, ascii_only: bool = False) -> str:
+    """How a key is written for people: ``→``, ``Ctrl-E``, ``f``.
+
+    Letters are shown in lower case so nobody reaches for Shift.
+    """
+    if ascii_only and key in ASCII_ARROWS:
+        return ASCII_ARROWS[key]
+    if key in KEY_LABELS:
+        return KEY_LABELS[key]
+    if key.startswith("ctrl-"):
+        return "Ctrl-" + key[5:].upper()
+    return key
+
+
+@dataclass
+class Keymap:
+    bindings: dict[str, str] = field(default_factory=lambda: dict(DEFAULT_KEYS))
+
+    def action(self, key: str) -> str | None:
+        """The action for ``key``. Letters work with or without Shift (or Caps Lock)
+        unless the upper-case letter has a binding of its own."""
+        action = self.bindings.get(key)
+        if action is None and len(key) == 1 and key.isupper():
+            action = self.bindings.get(key.lower())
+        return None if action in (None, UNBOUND) else action
+
+    def keys_for(self, action: str) -> list[str]:
+        """Keys bound to ``action``, defaults first so labels stay familiar."""
+        order = list(DEFAULT_KEYS)
+        keys = [k for k, a in self.bindings.items() if a == action]
+        return sorted(keys, key=lambda k: order.index(k) if k in order else len(order))
+
+    def label(self, action: str, ascii_only: bool = False) -> str:
+        """The first key for ``action``, for hints like "press m to browse"."""
+        keys = self.keys_for(action)
+        return key_label(keys[0], ascii_only) if keys else "(unbound)"
+
+    def bind(self, key: str, action: str) -> str | None:
+        """Bind ``key`` to ``action``. Returns the action that lost the key, if any."""
+        if key in RESERVED:
+            raise ValueError(f"{key_label(key)} is reserved")
+        if action != UNBOUND and action not in ACTIONS:
+            raise ValueError(f"unknown action '{action}'")
+        previous = self.action(key)
+        self.bindings[key] = action
+        return previous if previous not in (None, action) else None
+
+    def unbind(self, action: str) -> None:
+        for key in self.keys_for(action):
+            self.bindings[key] = UNBOUND
+
+    def reset(self) -> None:
+        self.bindings = dict(DEFAULT_KEYS)
+
+    def changes(self) -> dict[str, str]:
+        """What differs from the defaults: all that gets saved."""
+        return {k: a for k, a in self.bindings.items() if DEFAULT_KEYS.get(k, UNBOUND) != a}
+
+    def apply_changes(self, changes: dict[str, str]) -> list[str]:
+        """Apply saved changes; returns a warning for each one that was invalid."""
+        warnings = []
+        for key, action in changes.items():
+            try:
+                self.bind(key, action)
+            except ValueError as exc:
+                warnings.append(f"key binding '{key}': {exc}")
+        return warnings

staticfx/app/player.py

@@ -0,0 +1,143 @@
+"""What is on screen: the current effect, theme, speed and filters."""
+
+from __future__ import annotations
+
+import random
+from collections import OrderedDict
+
+from staticfx import themes
+from staticfx.core.frame import Frame
+from staticfx.effects.base import Effect
+from staticfx.effects.registry import Registry
+from staticfx.postfx import PostFX
+from staticfx.themes import Strobe, Theme
+
+SPEED_MIN, SPEED_MAX = 0.1, 5.0
+SPEED_STEP = 1.2
+RAINBOW_SPEED = 0.18  # hue turns per second
+PREVIEW_CACHE = 6
+
+
+class Player:
+    """Owns the playing effect and anything that changes how it looks.
+
+    Menus can *preview* an effect or theme without committing to it: the
+    preview is drawn instead of the real choice until it is cleared.
+    """
+
+    def __init__(
+        self,
+        registry: Registry,
+        rng: random.Random,
+        *,
+        unicode: bool = False,
+        ascii_only: bool = False,
+    ) -> None:
+        self.registry = registry
+        self.rng = rng
+        self.unicode = unicode
+        self.ascii_only = ascii_only
+        self.width, self.height = 80, 24
+        self.speed = 1.0
+        self.paused = False
+        self.post = PostFX(rng=rng)
+        self.adaptive = False  # trade resolution for frame rate (interactive only)
+
+        self.theme_name = themes.DEFAULT
+        self.preview_theme: str | None = None
+        self._strobe = Strobe(rng)
+        self._clock = 0.0
+
+        self.key = ""
+        self.effect: Effect | None = None
+        self.preview_key: str | None = None
+        self._previews: OrderedDict[str, Effect] = OrderedDict()
+        self.override: Effect | None = None  # drawn instead of anything else (the Studio)
+
+    def _build(self, key: str) -> Effect:
+        effect = self.registry.make(key, self.rng, unicode=self.unicode, ascii_only=self.ascii_only)
+        effect.adaptive = self.adaptive
+        effect.resize(self.width, self.height)
+        return effect
+
+    def play(self, key: str) -> None:
+        """Switch to effect ``key`` (raises ``KeyError`` if there's no such effect)."""
+        self.effect = self._build(key)
+        self.key = key
+        self.preview_key = None
+
+    def reload(self) -> None:
+        """Rebuild the current effect, e.g. after its recipe was edited and saved."""
+        self._previews.clear()
+        if self.key in self.registry:
+            self.play(self.key)
+
+    def restart(self) -> None:
+        if self.effect is not None:
+            self.effect.reset()
+
+    def preview(self, key: str | None) -> None:
+        """Show ``key`` instead of the current effect (``None`` stops previewing).
+
+        Recently previewed effects are kept alive, so scrolling back and forth
+        in a menu doesn't restart them every time.
+        """
+        if key is None or key == self.key or key not in self.registry:
+            self.preview_key = None
+            return
+        if key not in self._previews:
+            self._previews[key] = self._build(key)
+            while len(self._previews) > PREVIEW_CACHE:
+                self._previews.popitem(last=False)
+        self._previews.move_to_end(key)
+        self.preview_key = key
+
+    @property
+    def showing(self) -> Effect | None:
+        if self.override is not None:
+            return self.override
+        if self.preview_key is not None:
+            return self._previews[self.preview_key]
+        return self.effect
+
+    def set_theme(self, name: str) -> None:
+        self.theme_name = themes.normalize(name)
+
+    def theme(self) -> Theme:
+        name = self.preview_theme or self.theme_name
+        if name == "rainbow":
+            return themes.rainbow(self._clock * RAINBOW_SPEED)
+        if name == "strobe":
+            return self._strobe.theme()
+        return themes.STATIC_THEMES[name]
+
+    def faster(self) -> None:
+        self.speed = min(SPEED_MAX, self.speed * SPEED_STEP)
+
+    def slower(self) -> None:
+        self.speed = max(SPEED_MIN, self.speed / SPEED_STEP)
+
+    def resize(self, width: int, height: int) -> None:
+        self.width, self.height = width, height
+        for effect in (self.effect, self.override, *self._previews.values()):
+            if effect is not None:
+                effect.resize(width, height)
+
+    def update(self, dt: float) -> None:
+        self._clock += dt
+        if (self.preview_theme or self.theme_name) == "strobe":
+            self._strobe.update(dt)
+        self.post.update(dt)
+        effect = self.showing
+        if effect is not None and not self.paused:
+            effect.update(dt * self.speed)
+
+    def draw(self, frame: Frame) -> Theme:
+        """Draw the effect and filters into ``frame``; returns the theme used."""
+        theme = self.theme()
+        frame.clear()
+        effect = self.showing
+        if effect is not None:
+            effect.draw(frame, theme)
+        self.post.apply(frame)
+        return theme