tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/schema/targets.py

@@ -0,0 +1,83 @@
+"""Schema of the targets json file."""
+
+from typing import Any
+
+__all__ = ["schema"]
+
+_COMMON: dict[str, Any] = {
+    "target-id": {"description": "same as the key of this entry", "type": "string"},
+    "created": {"description": "timestamp when this entry has been added", "type": "string"},
+}
+
+schema: dict[str, Any] = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": {
+        "oneOf": [
+            {
+                "description": "album",
+                "type": "object",
+                "required": ["target-id", "target-type", "album-folder", "playlist", "created"],
+                "additionalProperties": False,
+                "properties": {
+                    **_COMMON,
+                    "target-type": {"description": "type of the target", "type": "string", "enum": ["album"]},
+                    "album-folder": {
+                        "description": "folder of the album (relative to albums-folder) with the mp3 files and the "
+                        "playlist",
+                        "type": "string",
+                    },
+                    "playlist": {"description": "m3u playlist in the album folder", "type": "string"},
+                    "title": {
+                        "description": "title of the album - without it the title comes from the tracks or the folder",
+                        "type": "string",
+                    },
+                    "cover": {
+                        "description": "cover of the album: name of an image in the images folder - without it the "
+                        "album shows an image of its folder or of its tracks",
+                        "type": "string",
+                    },
+                },
+            },
+            {
+                "description": "internet radio station",
+                "type": "object",
+                "required": ["target-id", "target-type", "name", "url", "created"],
+                "additionalProperties": False,
+                "properties": {
+                    **_COMMON,
+                    "target-type": {"description": "type of the target", "type": "string", "enum": ["radio"]},
+                    "name": {"description": "name of the station", "type": "string"},
+                    "url": {
+                        "description": "http(s) url of the stream or of an m3u/pls playlist with the stream",
+                        "type": "string",
+                    },
+                    "cover": {
+                        "description": "cover of the station: name of an image in the images folder",
+                        "type": "string",
+                    },
+                },
+            },
+            {
+                "description": "entry of Spotify: an album, playlist, track, episode, podcast, audiobook or artist",
+                "type": "object",
+                "required": ["target-id", "target-type", "name", "uri", "created"],
+                "additionalProperties": False,
+                "properties": {
+                    **_COMMON,
+                    "target-type": {"description": "type of the target", "type": "string", "enum": ["spotify"]},
+                    "name": {"description": "name of the entry", "type": "string"},
+                    "uri": {
+                        "description": "address that Spotify plays: spotify:<kind>:<id>",
+                        "type": "string",
+                        "pattern": "^spotify:(album|playlist|track|episode|show|audiobook|artist):[A-Za-z0-9]{1,64}$",
+                    },
+                    "cover": {
+                        "description": "cover of the entry: name of an image in the images folder",
+                        "type": "string",
+                    },
+                },
+            },
+        ]
+    },
+}

tinyjukebox/schema/tinyjukebox.py

@@ -0,0 +1,217 @@
+"""Schema of the config section ``tinyjukebox``."""
+
+from typing import Any
+
+__all__ = ["get_schema"]
+
+
+def _string(description: str) -> dict[str, str]:
+    return {"description": description, "type": "string"}
+
+
+def get_schema() -> dict[str, Any]:
+    """``{"tinyjukebox": schema}`` - combined with the sections ``logger`` and ``drivers`` by
+    ``TinyJukebox.get_schema()``."""
+    return {
+        "tinyjukebox": {
+            "description": "Tiny Jukebox box",
+            "type": "object",
+            "properties": {
+                "albums-folder": _string(
+                    "root folder of all albums - album folders in the targets json are relative to it"
+                ),
+                "backups-folder": _string(
+                    "folder of the backups that a box without a library makes by itself, until another folder is set "
+                    "on its page (optional, default: folder 'backups' beside the albums folder)"
+                ),
+                "playlist-filename": _string("name of the m3u playlist in each album folder (e.g. playlist.m3u)"),
+                "volume": {
+                    "type": "object",
+                    "properties": {
+                        "max-volume": {"description": "maximum volume in %", "type": "number"},
+                        "default-volume": {"description": "volume on startup in %", "type": "number"},
+                        "volume-step": {"description": "change of the volume per button press in %", "type": "number"},
+                        "volume-step-hold": {
+                            "description": "change of the volume in % per hold event of a volume button that is kept "
+                            "pressed (optional, default: 1) - 'hold_timeout' and 'hold_repeat' of its input driver "
+                            "say how often",
+                            "type": "number",
+                            "minimum": 0,
+                        },
+                        "mixer-control": _string(
+                            "alsa mixer control of the default card (default: Master) - list: 'amixer scontrols'"
+                        ),
+                    },
+                    "required": ["max-volume", "default-volume", "volume-step"],
+                    "additionalProperties": False,
+                },
+                "bluetooth": {
+                    "description": "volume of the bluetooth headset (optional) - start value and maximum of speaker "
+                    "and headset can be changed at runtime (web page, command line); the changed values are stored "
+                    "in the volume json file and apply instead of the config",
+                    "type": "object",
+                    "properties": {
+                        "default-volume": {
+                            "description": "volume in % whenever the headset connects (default: 40)",
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 100,
+                        },
+                        "max-volume": {
+                            "description": "maximum volume of the headset in % (default: 75) - 100: the box does "
+                            "not limit it",
+                            "type": "number",
+                            "minimum": 0,
+                            "maximum": 100,
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+                "albumplayer": {
+                    "type": "object",
+                    "properties": {
+                        "rewind-max-time": {
+                            "description": "'previous' within this many seconds of a track goes to the previous "
+                            "track, later it restarts the current track",
+                            "type": "number",
+                        },
+                        "update-schedule": {
+                            "description": "store the playback position every n seconds",
+                            "type": "number",
+                            "exclusiveMinimum": 0,
+                        },
+                        "pause-between-tracks": {
+                            "description": "pause between two tracks in seconds",
+                            "type": "number",
+                            "minimum": 0,
+                        },
+                        "buffer-time": {
+                            "description": "alsa buffer of aplay in ms (optional, default: aplay's default, usually "
+                            "500 ms) - smaller starts the sound faster; raise it if the sound stutters",
+                            "type": "number",
+                            "minimum": 20,
+                            "maximum": 2000,
+                        },
+                    },
+                    "required": ["rewind-max-time", "update-schedule", "pause-between-tracks"],
+                    "additionalProperties": False,
+                },
+                "json": {
+                    "type": "object",
+                    "properties": {
+                        "tags": _string("tags json file, e.g. /srv/tinyjukebox/json/tags.json"),
+                        "targets": _string("targets (albums) json file, e.g. /srv/tinyjukebox/json/targets.json"),
+                        "activities": _string("activities json file, e.g. /srv/tinyjukebox/json/activity.json"),
+                        "volume": _string(
+                            "start value and maximum of the volumes changed at runtime (optional, default: "
+                            "volume.json next to the tags json)"
+                        ),
+                    },
+                    "required": ["tags", "targets", "activities"],
+                    "additionalProperties": False,
+                },
+                "sync": {
+                    "description": "synchronization with the library (optional) - the box works with a library as "
+                    "soon as its address was entered (web page, or the file 'library' in the identity folder)",
+                    "type": "object",
+                    "properties": {
+                        "folder": _string(
+                            "what the library delivered, the changes of this box that it has not confirmed, the "
+                            "journal (default: folder 'sync' next to the folder of the tags json)"
+                        ),
+                        "identity": _string(
+                            "what identifies this box: its id, its key, address and certificate of the library "
+                            "(default: folder 'identity' next to the folder of the tags json)"
+                        ),
+                        "retry-seconds": {
+                            "description": "how often the library is tried again while it cannot be reached "
+                            "(default: 30)",
+                            "type": "number",
+                            "exclusiveMinimum": 0,
+                        },
+                        "keep-free": {
+                            "description": "MB that stay free on the card of a box that works with a library "
+                            "(default: 500, 0: never delete): when less is free, the audio files of albums are "
+                            "deleted here, the album not played for the longest time first - the library has them, "
+                            "and they are fetched again when their tag is placed",
+                            "type": "number",
+                            "minimum": 0,
+                        },
+                        "stage1-seconds": {
+                            "description": "health check of a new version: seconds after the start in which no "
+                            "unexpected exception may occur and everything must run (default: 10)",
+                            "type": "number",
+                            "exclusiveMinimum": 0,
+                        },
+                        "stage2-seconds": {
+                            "description": "health check of a new version: seconds an album must have played "
+                            "without an unexpected exception before the version is confirmed (default: 60)",
+                            "type": "number",
+                            "exclusiveMinimum": 0,
+                        },
+                        "look-hours": {
+                            "description": "a box with slots and without a library: hours between two looks for a "
+                            "new version at the releases of the git server (default: 24)",
+                            "type": "number",
+                            "exclusiveMinimum": 0,
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+                "rest-api": {
+                    "description": "https rest api and web page (optional)",
+                    "type": "object",
+                    "properties": {
+                        "enabled": {"description": "default: true", "type": "boolean"},
+                        "host": _string("address to listen on (default: 0.0.0.0)"),
+                        "port": {"description": "default: 8443", "type": "integer", "minimum": 0, "maximum": 65535},
+                        "certificate": _string(
+                            "certificate file (pem) - a self signed certificate is created if it "
+                            "does not exist (default: ~/.config/tinyjukebox/tinyjukebox.crt)"
+                        ),
+                        "private-key": _string(
+                            "private key file (pem, default: ~/.config/tinyjukebox/tinyjukebox.key)"
+                        ),
+                        "hostnames": {
+                            "description": "additional host names / ip addresses for the self signed certificate",
+                            "type": "array",
+                            "items": {"type": "string"},
+                        },
+                        "users-file": _string(
+                            "users and password hashes - manage with 'tinyjukebox-users' "
+                            "(default: ~/.config/tinyjukebox/users.yaml)"
+                        ),
+                        "images-folder": _string(
+                            "covers of albums, radio stations and entries of Spotify (default: folder 'images' next "
+                            "to the tags json)"
+                        ),
+                        "session-timeout": {
+                            "description": "logout after this many seconds without request (default: 604800 = 7 days)",
+                            "type": "number",
+                            "exclusiveMinimum": 0,
+                        },
+                        "idle-timeout": {
+                            "description": "logout after this many seconds in which the user of the page did nothing "
+                            "(default: 1800 = 30 minutes; 0: never)",
+                            "type": "number",
+                            "minimum": 0,
+                        },
+                        "max-upload-size": {
+                            "description": "maximum size of an uploaded mp3 file in MB (default: 500)",
+                            "type": "number",
+                            "exclusiveMinimum": 0,
+                        },
+                    },
+                    "additionalProperties": False,
+                },
+            },
+            "required": [
+                "volume",
+                "albums-folder",
+                "playlist-filename",
+                "albumplayer",
+                "json",
+            ],
+            "additionalProperties": False,
+        }
+    }

tinyjukebox/schema/volume.py

@@ -0,0 +1,28 @@
+"""Schema of the volume json file (start value and maximum changed at runtime)."""
+
+from typing import Any
+
+__all__ = ["schema"]
+
+_PERCENT = {"type": "number", "minimum": 0, "maximum": 100}
+_LIMITS = {
+    "type": "object",
+    "required": ["default-volume", "max-volume"],
+    "additionalProperties": False,
+    "properties": {
+        "default-volume": dict(_PERCENT, description="volume on startup / when the headset connects in %"),
+        "max-volume": dict(_PERCENT, description="maximum volume in %"),
+    },
+}
+
+schema: dict[str, Any] = {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "additionalProperties": False,
+    "properties": {
+        "speaker": dict(_LIMITS, description="volume of the speaker - overrides tinyjukebox/volume of the config"),
+        "headphones": dict(
+            _LIMITS, description="volume of the headset - overrides tinyjukebox/bluetooth of the config"
+        ),
+    },
+}

tinyjukebox/slots.py

@@ -0,0 +1,234 @@
+"""Which version of the box software runs, and whether it is healthy (docs/developer/library.md, section 6).
+
+The box has slots with a version each; the start script and ``tinyjukebox-slot`` (deploy/slot, outside the slots)
+install, switch and go back. They do the "how". The application does the "when": it asks the script to look for a
+version, and it tells the script how the health check of a new version went:
+
+- stage 1, seconds after the start: the software runs, everything the config asks for runs, and no unexpected
+  exception arrived at the central place (:mod:`tinyjukebox.core.unexpected`),
+- stage 2, in use: an album was played because of a tag, and a configured time passed after that without an
+  unexpected exception.
+
+A version on probation that fails ends at once; the start script starts the previous version. On a box without slots -
+the PC, a box that was not set up with them - nothing of this happens.
+
+A library announces a new version. A box without a library has nobody who does: the application lets the script
+look after the start and once a day (section 6.16).
+"""
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+import threading
+from collections.abc import Callable
+from typing import Any
+
+from tinyjukebox.core import unexpected
+from tinyjukebox.core.logging import get_child
+
+__all__ = ["COMMANDS", "DEFECT", "LOOK", "Health", "Slots"]
+
+DEFECT = 70  # exit status of a version that ends itself because its health check failed
+NO_ANSWER = 69  # exit status of "tinyjukebox-slot update --auto" if the releases did not answer: ask again soon
+LOOK = (60.0, 24 * 3600.0, 600.0)
+"""Seconds until a box without a library looks for a version: after the start, between two looks, and after a look
+that got no answer."""
+COMMANDS = ("check", "update", "revert", "use", "fallback", "promote", "mode", "skip")
+"""What the tab "System" of the web page may ask the slot script for."""
+
+
+class Slots:
+    """The slot script as the application uses it. ``state/`` is written by the scripts only."""
+
+    def __init__(self, logger: logging.Logger, command: str = "tinyjukebox-slot") -> None:
+        self._logger = get_child(logger, type(self).__name__)
+        self._command = shutil.which(command)
+        self._lock = threading.Lock()  # held while a command of the page runs
+        self.available = False
+        if self._command is not None:
+            # the script alone is not enough: the box must have been set up with slots, and one must be active
+            self.available = bool(self.status().get("active"))
+
+    def run(self, *arguments: str, timeout: float | None = None) -> subprocess.CompletedProcess[str]:
+        """Call the script. What it prints goes to the log, except for the calls the application makes all the
+        time."""
+        if self._command is None:
+            return subprocess.CompletedProcess(arguments, 127, "", "tinyjukebox-slot is not installed")
+        try:
+            result = subprocess.run(
+                [self._command, *arguments], capture_output=True, text=True, check=False, timeout=timeout
+            )
+        except (OSError, subprocess.TimeoutExpired) as error:
+            return subprocess.CompletedProcess(arguments, 1, "", str(error))
+        if not arguments[0].startswith("_") and arguments[:2] != ("status", "--json"):
+            for line in (result.stdout + result.stderr).splitlines():
+                self._logger.info("tinyjukebox-slot %s: %s", arguments[0], line)
+        return result
+
+    def status(self) -> dict[str, Any]:
+        """Slots, active slot, update mode, states of the versions, switches - empty without slots."""
+        result = self.run("status", "--json", timeout=30)
+        try:
+            status = json.loads(result.stdout) if result.returncode == 0 else {}
+        except ValueError:
+            status = {}
+        return status if isinstance(status, dict) else {}
+
+    def command(self, command: str, arguments: list[str], by: str) -> dict[str, Any]:
+        """A command of the tab "System". The lock makes a restart that the command asks for wait until the page
+        has its answer (:meth:`wait_for_command`)."""
+        if command not in COMMANDS:
+            raise ValueError(f"unknown command '{command}'")
+        with self._lock:
+            result = self.run(command, "--by", by, *arguments)
+        return {"status": result.returncode, "output": result.stdout + result.stderr}
+
+    def wait_for_command(self, timeout: float = 5.0) -> None:
+        """Called when the service stops: a command of the page may have asked for this restart itself."""
+        if self._lock.acquire(timeout=timeout):
+            self._lock.release()
+
+
+class Health:
+    """The health check of the running version (section 6.4), and what the application decides about versions."""
+
+    def __init__(
+        self,
+        slots: Slots,
+        logger: logging.Logger,
+        stage1_seconds: float = 10.0,
+        stage2_seconds: float = 60.0,
+        journal: Callable[..., None] | None = None,
+        end: Callable[[int], None] = os._exit,
+        look: tuple[float, float, float] = LOOK,
+        alone: Callable[[], bool] = lambda: False,
+    ) -> None:
+        """``journal(event, **fields)`` notes what happened for the library; ``end(status)`` ends the process.
+        ``alone()``: the box is not linked to a library, so it looks for versions by itself, at the times of
+        ``look`` (:data:`LOOK`)."""
+        self._slots = slots
+        self._logger = get_child(logger, type(self).__name__)
+        self._stage1_seconds = stage1_seconds
+        self._stage2_seconds = stage2_seconds
+        self._journal = journal or (lambda event, **fields: None)
+        self._end = end
+        self._look_first, self._look_every, self._look_again = look
+        self._alone = alone
+        self._lock = threading.Lock()
+        self._timers: list[threading.Timer] = []
+        self._failed = False
+        self._proof = False
+        self._wake = threading.Event()
+        self._stop = threading.Event()
+        self._updater: threading.Thread | None = None
+        self.on_change: Callable[[], None] | None = None  # the library hears of it at once
+        active = slots.status() if slots.available else {}
+        self.slot = str(active.get("active", ""))
+        self.probation = active.get("slots", {}).get(self.slot, {}).get("state") == "probation"
+
+    # --- start and stop ----------------------------------------------------------------------------------------------
+
+    def start(self, missing: Callable[[], list[str]]) -> None:
+        """The service has started. ``missing()`` names what the config asks for and does not run."""
+        unexpected.subscribe(self.unexpected)
+        if not self._slots.available:
+            return
+        self._stop.clear()
+        self._timer(self._stage1_seconds, lambda: self._stage1(missing))
+        self._updater = threading.Thread(target=self._look, name="Health.updater", daemon=True)
+        self._updater.start()
+
+    def stop(self) -> None:
+        unexpected.unsubscribe(self.unexpected)
+        self._stop.set()
+        self._wake.set()
+        with self._lock:
+            timers, self._timers = self._timers, []
+        for timer in timers:
+            timer.cancel()
+        if self._updater is not None:
+            self._updater.join(timeout=5)
+            self._updater = None
+
+    def _timer(self, seconds: float, action: Callable[[], None]) -> None:
+        timer = threading.Timer(seconds, action)
+        timer.name = "Health.timer"
+        timer.daemon = True
+        with self._lock:
+            self._timers.append(timer)
+        timer.start()
+
+    # --- the health check --------------------------------------------------------------------------------------------
+
+    def unexpected(self, error: BaseException, where: str) -> None:
+        """An exception that nobody expected. During the probation it ends this version; afterwards it is only
+        reported to the library."""
+        self._failed = True
+        try:
+            self._journal("unexpected", error=repr(error), where=where, probation=self.probation)
+        except Exception:  # e.g. the card is full: a version on probation ends all the same
+            self._logger.exception("the unexpected exception cannot be noted in the journal")
+        if self.probation and self._slots.available:
+            self._logger.error("unexpected exception during the probation (%s): this version ends", where)
+            self._slots.run("_failure", f"unexpected exception in {where}: {error!r}")
+            logging.shutdown()
+            self._end(DEFECT)
+        elif self.on_change is not None:
+            self.on_change()
+
+    def _stage1(self, missing: Callable[[], list[str]]) -> None:
+        lacking = missing()
+        if self._failed or lacking:
+            # the start script ends a version on probation that does not pass in time
+            self._logger.error("stage 1 of the health check not passed: %s", lacking or "unexpected exception")
+            return
+        self._slots.run("_passed", "1")
+        self._logger.info("stage 1 of the health check passed")
+
+    def played(self, kind: str) -> None:
+        """Something is playing because of a tag. An album confirms a version; a radio station never does, and
+        never condemns one: if a stream fails, the cause is mostly the station or the internet."""
+        if kind != "album" or not self.probation or self._proof or not self._slots.available:
+            return
+        self._proof = True
+        self._timer(self._stage2_seconds, self._stage2)
+
+    def _stage2(self) -> None:
+        if self._failed or not self.probation:
+            return
+        self._slots.run("_passed", "2")
+        self.probation = False
+        self._logger.info("stage 2 of the health check passed: this version is confirmed")
+        self._journal("confirmed", slot=self.slot)
+        if self.on_change is not None:
+            self.on_change()
+
+    # --- looking for a version ---------------------------------------------------------------------------------------
+
+    def look_for_versions(self) -> None:
+        """The library may have another version, or changed the state of one: let the script find out."""
+        self._wake.set()
+
+    def _look(self) -> None:
+        """The script fetches and installs (section 6.11); it may take minutes, so it has a thread of its own.
+
+        A box with a library looks when the library says so. A box without one looks by the clock: after the start,
+        once a day, and soon again if nobody answered - no WLAN yet, or a clock that is not set."""
+        wait = self._look_first
+        while True:
+            asked = self._wake.wait(wait)
+            if self._stop.is_set():
+                return
+            self._wake.clear()
+            wait = self._look_every
+            if not asked and not self._alone():
+                continue
+            result = self._slots.run("update", "--auto")
+            if result.returncode == NO_ANSWER:
+                wait = self._look_again
+            elif result.returncode != 0:
+                self._logger.error("looking for a version failed (%d)", result.returncode)
+            if self.on_change is not None:
+                self.on_change()  # report what happened

tinyjukebox/spotify/__init__.py

@@ -0,0 +1 @@
+"""Spotify: entries of Spotify on a tag, played with Spotify Soloist (docs/developer/architecture.md, section 4.1)."""