cloudspin 0.1.0__py3-none-any.whl

cloudspin/canvas.py

@@ -0,0 +1,321 @@
+"""A truecolor pixel canvas drawn with half-block characters.
+
+Every terminal cell holds two stacked pixels: the upper one is the foreground
+of a ``▀`` and the lower one is the background. Pixels live in three flat
+bytearrays so whole rows and columns can be copied or recoloured in C.
+"""
+
+from __future__ import annotations
+
+import math
+
+from rich.cells import cell_len
+from rich.color import Color
+from rich.segment import Segment
+from rich.style import Style
+
+from .color import RGB
+
+_PIXEL_STYLES: dict[int, Style] = {}
+_TEXT_STYLES: dict[tuple, Style] = {}
+_CACHE_LIMIT = 60_000
+
+#: Per-row text overlay: cell x -> (character, packed fg, bold) or None for
+#: the trailing half of a double-width character.
+RowText = dict[int, tuple[str, int, bool] | None]
+
+
+def pack(c: RGB) -> int:
+    return (c[0] << 16) | (c[1] << 8) | c[2]
+
+
+def text_style(
+    fg: RGB | None,
+    bg: RGB | None,
+    bold: bool = False,
+    italic: bool = False,
+    underline: bool = False,
+) -> Style:
+    key = (fg, bg, bold, italic, underline)
+    style = _TEXT_STYLES.get(key)
+    if style is None:
+        if len(_TEXT_STYLES) > _CACHE_LIMIT:
+            _TEXT_STYLES.clear()
+        style = Style(
+            color=Color.from_rgb(*fg) if fg is not None else None,
+            bgcolor=Color.from_rgb(*bg) if bg is not None else None,
+            bold=bold or None,
+            italic=italic or None,
+            underline=underline or None,
+        )
+        _TEXT_STYLES[key] = style
+    return style
+
+
+def _pixel_style(fg: int, bg: int) -> Style:
+    key = (fg << 24) | bg
+    style = _PIXEL_STYLES.get(key)
+    if style is None:
+        if len(_PIXEL_STYLES) > _CACHE_LIMIT:
+            _PIXEL_STYLES.clear()
+        style = Style(
+            color=Color.from_rgb(fg >> 16, (fg >> 8) & 255, fg & 255),
+            bgcolor=Color.from_rgb(bg >> 16, (bg >> 8) & 255, bg & 255),
+        )
+        _PIXEL_STYLES[key] = style
+    return style
+
+
+def _fill_style(bg: int) -> Style:
+    key = -1 - bg
+    style = _PIXEL_STYLES.get(key)
+    if style is None:
+        if len(_PIXEL_STYLES) > _CACHE_LIMIT:
+            _PIXEL_STYLES.clear()
+        style = Style(bgcolor=Color.from_rgb(bg >> 16, (bg >> 8) & 255, bg & 255))
+        _PIXEL_STYLES[key] = style
+    return style
+
+
+def lay_text(rows: dict[int, RowText], x: int, row: int, text: str, fg: RGB, bold: bool = False) -> int:
+    """Place text into an overlay map; returns the cell width that was used."""
+    target = rows.setdefault(row, {})
+    packed = pack(fg)
+    start = x
+    for ch in text:
+        width = cell_len(ch)
+        if width <= 0:
+            continue
+        target[x] = (ch, packed, bold)
+        if width == 2:
+            target[x + 1] = None
+        x += width
+    return x - start
+
+
+class Canvas:
+    __slots__ = ("w", "h", "r", "g", "b")
+
+    def __init__(self, w: int = 0, h: int = 0) -> None:
+        self.w = 0
+        self.h = 0
+        self.r = bytearray()
+        self.g = bytearray()
+        self.b = bytearray()
+        self.resize(w, h)
+
+    def resize(self, w: int, h: int) -> None:
+        self.w = max(0, w)
+        self.h = max(0, h)
+        n = self.w * self.h
+        self.r = bytearray(n)
+        self.g = bytearray(n)
+        self.b = bytearray(n)
+
+    # -- whole-buffer operations -------------------------------------------
+
+    def fill(self, c: RGB) -> None:
+        n = self.w * self.h
+        self.r[:] = bytes((c[0],)) * n
+        self.g[:] = bytes((c[1],)) * n
+        self.b[:] = bytes((c[2],)) * n
+
+    def blit(self, other: Canvas) -> None:
+        self.r[:] = other.r
+        self.g[:] = other.g
+        self.b[:] = other.b
+
+    def fill_rows(self, colors: list[RGB]) -> None:
+        """Paint one colour per pixel row, top to bottom."""
+        w = self.w
+        for y, c in enumerate(colors[: self.h]):
+            i = y * w
+            self.r[i : i + w] = bytes((c[0],)) * w
+            self.g[i : i + w] = bytes((c[1],)) * w
+            self.b[i : i + w] = bytes((c[2],)) * w
+
+    def lighten(self, amount: int) -> None:
+        """Add a flat amount of white to every pixel (lightning)."""
+        if amount <= 0:
+            return
+        table = bytes(min(255, v + amount) for v in range(256))
+        self.r[:] = self.r.translate(table)
+        self.g[:] = self.g.translate(table)
+        self.b[:] = self.b.translate(table)
+
+    def remap_column(self, x: int, y_end: int, table: bytes) -> None:
+        """Run the pixels of column x, rows [0, y_end), through a lookup table."""
+        if not (0 <= x < self.w) or y_end <= 0:
+            return
+        end = min(y_end, self.h) * self.w
+        w = self.w
+        self.r[x:end:w] = self.r[x:end:w].translate(table)
+        self.g[x:end:w] = self.g[x:end:w].translate(table)
+        self.b[x:end:w] = self.b[x:end:w].translate(table)
+
+    def fill_column(self, x: int, y_start: int, c: RGB) -> None:
+        """Fill column x from row y_start down to the bottom edge."""
+        if not (0 <= x < self.w):
+            return
+        y_start = max(0, y_start)
+        n = self.h - y_start
+        if n <= 0:
+            return
+        start = y_start * self.w + x
+        w = self.w
+        self.r[start::w] = bytes((c[0],)) * n
+        self.g[start::w] = bytes((c[1],)) * n
+        self.b[start::w] = bytes((c[2],)) * n
+
+    # -- single pixels -----------------------------------------------------
+
+    def put(self, x: int, y: int, c: RGB) -> None:
+        if 0 <= x < self.w and 0 <= y < self.h:
+            i = y * self.w + x
+            self.r[i] = c[0]
+            self.g[i] = c[1]
+            self.b[i] = c[2]
+
+    def blend(self, x: int, y: int, c: RGB, a: int) -> None:
+        """Alpha-blend a colour onto a pixel; ``a`` runs 0..256."""
+        if a > 0 and 0 <= x < self.w and 0 <= y < self.h:
+            i = y * self.w + x
+            v = self.r[i]
+            self.r[i] = v + ((c[0] - v) * a >> 8)
+            v = self.g[i]
+            self.g[i] = v + ((c[1] - v) * a >> 8)
+            v = self.b[i]
+            self.b[i] = v + ((c[2] - v) * a >> 8)
+
+    def add(self, x: int, y: int, c: RGB, a: int) -> None:
+        """Additively blend light onto a pixel; ``a`` runs 0..256."""
+        if a > 0 and 0 <= x < self.w and 0 <= y < self.h:
+            i = y * self.w + x
+            v = self.r[i] + (c[0] * a >> 8)
+            self.r[i] = 255 if v > 255 else v
+            v = self.g[i] + (c[1] * a >> 8)
+            self.g[i] = 255 if v > 255 else v
+            v = self.b[i] + (c[2] * a >> 8)
+            self.b[i] = 255 if v > 255 else v
+
+    # -- shapes ------------------------------------------------------------
+
+    def disc(self, cx: float, cy: float, radius: float, c: RGB, a: int = 256) -> None:
+        """Anti-aliased filled circle."""
+        y0 = max(0, int(cy - radius - 1))
+        y1 = min(self.h - 1, int(cy + radius + 2))
+        x0 = max(0, int(cx - radius - 1))
+        x1 = min(self.w - 1, int(cx + radius + 2))
+        for y in range(y0, y1 + 1):
+            dy = y - cy
+            for x in range(x0, x1 + 1):
+                cover = radius + 0.5 - math.hypot(x - cx, dy)
+                if cover > 0.0:
+                    self.blend(x, y, c, a if cover >= 1.0 else int(a * cover))
+
+    def glow(self, cx: float, cy: float, radius: float, c: RGB, strength: float) -> None:
+        """Additive radial glow with a quadratic falloff."""
+        if radius <= 0 or strength <= 0:
+            return
+        y0 = max(0, int(cy - radius))
+        y1 = min(self.h - 1, int(cy + radius + 1))
+        x0 = max(0, int(cx - radius))
+        x1 = min(self.w - 1, int(cx + radius + 1))
+        inv = 1.0 / radius
+        peak = strength * 256.0
+        for y in range(y0, y1 + 1):
+            dy = y - cy
+            for x in range(x0, x1 + 1):
+                f = 1.0 - math.hypot(x - cx, dy) * inv
+                if f > 0.0:
+                    self.add(x, y, c, int(peak * f * f))
+
+    def line(
+        self, x0: float, y0: float, x1: float, y1: float, c: RGB, a: int = 256, width: float = 1.0
+    ) -> None:
+        """Anti-aliased line with round caps."""
+        half = width / 2.0
+        pad = half + 1.0
+        bx0 = max(0, int(min(x0, x1) - pad))
+        bx1 = min(self.w - 1, int(max(x0, x1) + pad + 1))
+        by0 = max(0, int(min(y0, y1) - pad))
+        by1 = min(self.h - 1, int(max(y0, y1) + pad + 1))
+        dx = x1 - x0
+        dy = y1 - y0
+        length_sq = dx * dx + dy * dy
+        for y in range(by0, by1 + 1):
+            for x in range(bx0, bx1 + 1):
+                if length_sq > 0.0:
+                    t = ((x - x0) * dx + (y - y0) * dy) / length_sq
+                    t = 0.0 if t < 0.0 else 1.0 if t > 1.0 else t
+                else:
+                    t = 0.0
+                cover = half + 0.5 - math.hypot(x - (x0 + dx * t), y - (y0 + dy * t))
+                if cover > 0.0:
+                    self.blend(x, y, c, a if cover >= 1.0 else int(a * cover))
+
+    # -- output ------------------------------------------------------------
+
+    def row_key(self, row: int) -> bytes:
+        """The raw pixels behind one text row, for change detection."""
+        i = row * 2 * self.w
+        j = i + 2 * self.w
+        return bytes(self.r[i:j]) + bytes(self.g[i:j]) + bytes(self.b[i:j])
+
+    def segments(self, row: int, text: RowText | None = None) -> list[Segment]:
+        """Render one text row (two pixel rows) as Rich segments."""
+        w = self.w
+        top = row * 2 * w
+        bottom = top + w
+        r, g, b = self.r, self.g, self.b
+        has_bottom = bottom + w <= len(r)
+        out: list[Segment] = []
+        run_key = None
+        run_len = 0
+        run_style: Style | None = None
+        run_char = " "
+        for x in range(w):
+            i = top + x
+            fg = (r[i] << 16) | (g[i] << 8) | b[i]
+            if has_bottom:
+                j = bottom + x
+                bg = (r[j] << 16) | (g[j] << 8) | b[j]
+            else:
+                bg = fg
+            if text is not None and x in text:
+                if run_len:
+                    out.append(Segment(run_char * run_len, run_style))
+                    run_len = 0
+                    run_key = None
+                cell = text[x]
+                if cell is not None:
+                    ch, tfg, bold = cell
+                    ur = ((fg >> 16) + (bg >> 16)) >> 1
+                    ug = (((fg >> 8) & 255) + ((bg >> 8) & 255)) >> 1
+                    ub = ((fg & 255) + (bg & 255)) >> 1
+                    light = (ur * 3 + ug * 6 + ub) // 10
+                    if light > 150:
+                        # Words stay readable when a bright cloud drifts behind them.
+                        ur, ug, ub = ur * 150 // light, ug * 150 // light, ub * 150 // light
+                    under = (ur, ug, ub)
+                    out.append(
+                        Segment(ch, text_style((tfg >> 16, (tfg >> 8) & 255, tfg & 255), under, bold))
+                    )
+                continue
+            key = (fg << 24) | bg
+            if key == run_key:
+                run_len += 1
+                continue
+            if run_len:
+                out.append(Segment(run_char * run_len, run_style))
+            run_key = key
+            run_len = 1
+            if fg == bg:
+                run_char = " "
+                run_style = _fill_style(bg)
+            else:
+                run_char = "▀"
+                run_style = _pixel_style(fg, bg)
+        if run_len:
+            out.append(Segment(run_char * run_len, run_style))
+        return out

cloudspin/cli.py

@@ -0,0 +1,98 @@
+"""Command line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="cloudspin",
+        description="A terminal music player under a living sky.",
+        epilog="Settings live in ~/.config/cloudspin/config.toml. Press ? inside the app for the keys.",
+    )
+    parser.add_argument("music", nargs="*", help="files, folders or stream URLs to play (default: your music folder)")
+    parser.add_argument("--city", help="city for the weather, for example --city \"New Delhi\"")
+    parser.add_argument("--sky", metavar="MODE", help="song, weather, or a scene: storm, rain, evening, night, day, dawn, snow, fog, overcast")
+    parser.add_argument("--colors", metavar="THEME", help="sky, cover, amber, orchid, lagoon, moss, rose, mono, or one of your own")
+    parser.add_argument("--units", choices=("metric", "imperial"), help="°C and km/h, or °F and mph")
+    parser.add_argument("--fps", type=int, metavar="N", help="animation frames per second (4-60, default 24)")
+    parser.add_argument("--demo", action="store_true", help="run a silent demo with made-up songs")
+    parser.add_argument("--version", action="version", version=f"cloudspin {__version__}")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    # Imported late so --help and --version stay instant.
+    from . import library, mood, weather
+    from .app import CloudspinApp
+    from .config import Config
+    from .player import DEMO_TRACKS, BackendError, Deck, DemoBackend, MpvBackend
+    from .themes import load_themes
+
+    config = Config.load()
+    if args.units:
+        config.units = args.units
+    if args.fps:
+        config.fps = max(4, min(60, args.fps))
+    if args.sky:
+        if args.sky not in ("song", "weather") and args.sky not in mood.SCENES:
+            print(f"cloudspin: unknown sky “{args.sky}”. Try: song, weather, {', '.join(mood.SCENES)}", file=sys.stderr)
+            return 2
+        config.sky = args.sky
+    if args.colors:
+        themes = load_themes(config.themes)
+        if args.colors not in themes:
+            print(f"cloudspin: unknown theme “{args.colors}”. Try: {', '.join(themes)}", file=sys.stderr)
+            return 2
+        config.colors = args.colors
+    if args.city:
+        try:
+            place = weather.geocode(args.city)
+        except weather.WeatherError as error:
+            print(f"cloudspin: {error}", file=sys.stderr)
+            return 1
+        config.city, config.country = place.name, place.country
+        config.latitude, config.longitude = place.latitude, place.longitude
+        config.save()
+
+    notice = ""
+    silent_reason = ""
+    if args.demo:
+        tracks = [type(t)(**vars(t)) for t in DEMO_TRACKS]
+        backend = DemoBackend()
+        silent_reason = "Silent demo"
+    else:
+        sources = args.music or [config.music]
+        tracks = library.scan(sources)
+        if not tracks:
+            where = ", ".join(str(Path(s).expanduser()) if "://" not in s else s for s in sources)
+            tracks = [type(t)(**vars(t)) for t in DEMO_TRACKS]
+            backend = DemoBackend()
+            silent_reason = "Silent demo"
+            notice = f"No music found in {where}. Showing a silent demo; start with: cloudspin <folder>"
+        else:
+            try:
+                backend = MpvBackend(volume=config.volume)
+            except BackendError as error:
+                backend = DemoBackend()
+                silent_reason = "No sound"
+                notice = str(error)
+
+    deck = Deck(backend, tracks, volume=config.volume)
+    app = CloudspinApp(config, deck, silent_reason=silent_reason, notice=notice)
+    try:
+        app.run()
+    finally:
+        deck.close()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

cloudspin/color.py

@@ -0,0 +1,78 @@
+"""Small RGB helpers. Colours are plain ``(r, g, b)`` tuples of 0-255 ints."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+RGB = tuple[int, int, int]
+
+WHITE: RGB = (255, 255, 255)
+BLACK: RGB = (0, 0, 0)
+
+
+def parse(value: str) -> RGB:
+    """Parse ``#rgb`` or ``#rrggbb`` into an RGB tuple."""
+    text = value.strip().lstrip("#")
+    if len(text) == 3:
+        text = "".join(ch * 2 for ch in text)
+    if len(text) != 6:
+        raise ValueError(f"not a hex colour: {value!r}")
+    try:
+        return (int(text[0:2], 16), int(text[2:4], 16), int(text[4:6], 16))
+    except ValueError:
+        raise ValueError(f"not a hex colour: {value!r}") from None
+
+
+def to_hex(c: RGB) -> str:
+    return f"#{c[0]:02x}{c[1]:02x}{c[2]:02x}"
+
+
+def clamp(v: float, lo: float = 0.0, hi: float = 1.0) -> float:
+    return lo if v < lo else hi if v > hi else v
+
+
+def lerp(a: RGB, b: RGB, t: float) -> RGB:
+    t = 0.0 if t < 0.0 else 1.0 if t > 1.0 else t
+    return (
+        int(a[0] + (b[0] - a[0]) * t + 0.5),
+        int(a[1] + (b[1] - a[1]) * t + 0.5),
+        int(a[2] + (b[2] - a[2]) * t + 0.5),
+    )
+
+
+def scale(c: RGB, k: float) -> RGB:
+    return (
+        min(255, max(0, int(c[0] * k + 0.5))),
+        min(255, max(0, int(c[1] * k + 0.5))),
+        min(255, max(0, int(c[2] * k + 0.5))),
+    )
+
+
+def ramp(stops: Sequence[tuple[float, RGB]], t: float) -> RGB:
+    """Piecewise-linear gradient through ``(position, colour)`` stops."""
+    if t <= stops[0][0]:
+        return stops[0][1]
+    for (p0, c0), (p1, c1) in zip(stops, stops[1:]):
+        if t <= p1:
+            return lerp(c0, c1, (t - p0) / (p1 - p0) if p1 > p0 else 0.0)
+    return stops[-1][1]
+
+
+def smoothstep(lo: float, hi: float, v: float) -> float:
+    if hi == lo:
+        return 0.0 if v < lo else 1.0
+    t = clamp((v - lo) / (hi - lo))
+    return t * t * (3.0 - 2.0 * t)
+
+
+def approach(current: RGB, target: RGB, k: float) -> RGB:
+    """Move a colour toward a target; snaps once it is a rounding step away."""
+    if current == target:
+        return current
+    out = []
+    for a, b in zip(current, target):
+        step = (b - a) * k
+        if abs(step) < 1.0:
+            step = 1.0 if b > a else -1.0 if b < a else 0.0
+        out.append(int(a + step))
+    return (out[0], out[1], out[2])

cloudspin/config.py

@@ -0,0 +1,105 @@
+"""Settings in ``~/.config/cloudspin/config.toml``.
+
+The file is yours to edit. Cloudspin only rewrites the handful of values it
+changes from inside the app (city, colours, sky, volume) and keeps your
+``[themes]`` and ``[moods]`` tables as they are.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from pathlib import Path
+
+
+def config_path() -> Path:
+    root = os.environ.get("XDG_CONFIG_HOME") or str(Path.home() / ".config")
+    return Path(root) / "cloudspin" / "config.toml"
+
+
+def cache_dir() -> Path:
+    root = os.environ.get("XDG_CACHE_HOME") or str(Path.home() / ".cache")
+    return Path(root) / "cloudspin"
+
+
+@dataclass
+class Config:
+    city: str = ""
+    latitude: float | None = None
+    longitude: float | None = None
+    country: str = ""
+    units: str = "metric"  # or "imperial"
+    colors: str = "sky"  # "sky", "cover", or a theme name
+    sky: str = "song"  # "song", "weather", or a scene name
+    music: str = "~/Music"
+    volume: int = 70
+    fps: int = 24
+    themes: dict[str, dict[str, str]] = field(default_factory=dict)
+    moods: dict[str, str] = field(default_factory=dict)
+    path: Path | None = None
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> Config:
+        path = path or config_path()
+        config = cls(path=path)
+        try:
+            data = tomllib.loads(path.read_text(encoding="utf-8"))
+        except (OSError, tomllib.TOMLDecodeError, UnicodeDecodeError):
+            return config
+        for key in ("city", "country", "units", "colors", "sky", "music"):
+            if isinstance(data.get(key), str):
+                setattr(config, key, data[key])
+        for key in ("latitude", "longitude"):
+            if isinstance(data.get(key), (int, float)) and not isinstance(data.get(key), bool):
+                setattr(config, key, float(data[key]))
+        for key, lo, hi in (("volume", 0, 100), ("fps", 4, 60)):
+            if isinstance(data.get(key), int) and not isinstance(data.get(key), bool):
+                setattr(config, key, max(lo, min(hi, data[key])))
+        if config.units not in ("metric", "imperial"):
+            config.units = "metric"
+        themes = data.get("themes")
+        if isinstance(themes, dict):
+            config.themes = {
+                str(name): {str(k): str(v) for k, v in table.items() if isinstance(v, str)}
+                for name, table in themes.items()
+                if isinstance(table, dict)
+            }
+        moods = data.get("moods")
+        if isinstance(moods, dict):
+            config.moods = {str(word): str(scene) for word, scene in moods.items() if isinstance(scene, str)}
+        return config
+
+    def save(self) -> None:
+        if self.path is None:
+            return
+
+        def quote(text: str) -> str:
+            return '"' + text.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+        lines = [
+            "# Cloudspin settings. Edit freely; see the README for every option.",
+            f"city = {quote(self.city)}",
+        ]
+        if self.latitude is not None and self.longitude is not None:
+            lines += [f"latitude = {self.latitude:.4f}", f"longitude = {self.longitude:.4f}"]
+        lines += [
+            f"country = {quote(self.country)}",
+            f"units = {quote(self.units)}",
+            f"colors = {quote(self.colors)}",
+            f"sky = {quote(self.sky)}",
+            f"music = {quote(self.music)}",
+            f"volume = {self.volume}",
+            f"fps = {self.fps}",
+        ]
+        if self.moods:
+            lines += ["", "[moods]"]
+            lines += [f"{quote(word)} = {quote(scene)}" for word, scene in self.moods.items()]
+        for name, table in self.themes.items():
+            lines += ["", f"[themes.{quote(name)}]"]
+            lines += [f"{key} = {quote(value)}" for key, value in table.items()]
+        try:
+            self.path.parent.mkdir(parents=True, exist_ok=True)
+            self.path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+        except OSError:
+            pass