tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/tools/import_covers.py

@@ -0,0 +1,138 @@
+"""Set the titles and the covers of the albums and the covers of the radio stations of a box or of the library from
+a folder on this computer::
+
+    tinyjukebox-import-covers https://tinyjukebox.local --user admin /path/to/covers
+
+The folder holds the images and ``captions.json``, which names the image and the title of an album under its id::
+
+    {"14": {"image": "album-14.jpg", "title": "Artist - Album (2010)"}}
+
+An entry may leave out ``image`` or ``title``. The cover of a radio station is the image that is named after its id:
+``radio-115.jpg`` (or ``.jpeg``, ``.png``, ``.webp``).
+
+The command shows what it is going to change and asks before it does. It can be repeated: a title that is the same
+as in ``captions.json`` is skipped, every other one is replaced.
+"""
+
+import argparse
+import getpass
+import os
+import re
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+from tinyjukebox.sync.client import Client, HttpError, Unreachable, WrongCertificate
+from tinyjukebox.sync.util import read_json
+from tinyjukebox.tools.fill_library import _client
+
+__all__ = ["CAPTIONS_FILE", "import_covers", "main", "plan"]
+
+CAPTIONS_FILE = "captions.json"
+STATION_COVER = re.compile(r"radio-(.+)\.(jpe?g|png|webp)", re.IGNORECASE)
+
+Step = tuple[str, str, str | None, str | None]
+"""("album" or "radio", id, new title or None, image file or None)"""
+NAMES = {"album": "album", "radio": "radio station"}
+
+
+def _say(text: str) -> None:
+    print(text)
+
+
+def plan(
+    folder: str, albums: dict[str, dict[str, Any]], say: Any = _say, radios: dict[str, dict[str, Any]] | None = None
+) -> list[Step]:
+    """What is to be done: the steps for the albums of ``captions.json`` in ``folder`` that are there (``albums``:
+    the albums of the box or library by id), then for the images ``radio-<id>`` of the stations that are there
+    (``radios``: the stations by id). What cannot be done is said and left out.
+
+    :raises ValueError: if ``captions.json`` is missing or not of the form above.
+    """
+    captions = read_json(os.path.join(folder, CAPTIONS_FILE), None)
+    if not isinstance(captions, dict) or not all(isinstance(entry, dict) for entry in captions.values()):
+        raise ValueError(f"{os.path.join(folder, CAPTIONS_FILE)} must map album ids to their image and title")
+    steps: list[Step] = []
+    for album_id, entry in captions.items():
+        album = albums.get(album_id)
+        if album is None:
+            say(f"album {album_id}: not there - skipped")
+            continue
+        title, image = entry.get("title"), entry.get("image")
+        filename = os.path.join(folder, str(image)) if image else None
+        if filename is not None and (os.path.basename(str(image)) != image or not os.path.isfile(filename)):
+            say(f"album {album_id}: image '{image}' not found in the folder - the image is skipped")
+            filename = None
+        new_title = title.strip() if isinstance(title, str) and title.strip() != album["title"] else None
+        if new_title or filename:
+            steps.append(("album", album_id, new_title or None, filename))
+    for name in sorted(os.listdir(folder)):
+        match = STATION_COVER.fullmatch(name)
+        if match is None:
+            continue
+        if match.group(1) not in (radios or {}):
+            say(f"radio station {match.group(1)}: not there - skipped")
+            continue
+        steps.append(("radio", match.group(1), None, os.path.join(folder, name)))
+    return steps
+
+
+def import_covers(client: Client, folder: str, confirm: Any = None, say: Any = _say) -> dict[str, int]:
+    """Set titles and covers as :func:`plan` says. ``confirm(steps)`` may refuse (returns False): nothing is changed
+    then. Returns how many titles and covers were set and how many albums and stations failed."""
+    albums = {album["id"]: album for album in client.get("/api/albums")}
+    radios = {radio["id"]: radio for radio in client.get("/api/radios")}
+    steps = plan(folder, albums, say, radios)
+    counts = {"titles": 0, "covers": 0, "failed": 0}
+    if not steps or (confirm is not None and not confirm(steps)):
+        return counts
+    for kind, target_id, title, filename in steps:
+        try:
+            if title is not None:
+                client.request("PATCH", f"/api/albums/{target_id}", {"title": title})
+                counts["titles"] += 1
+            if filename is not None:
+                client.request("PUT", f"/api/{kind}s/{target_id}/cover", upload=filename)
+                counts["covers"] += 1
+        except HttpError as error:
+            say(f"{NAMES[kind]} {target_id}: failed - {error}")
+            counts["failed"] += 1
+    return counts
+
+
+def _ask(steps: list[Step], shown: int = 200) -> bool:
+    for kind, target_id, title, filename in steps[:shown]:
+        changes = [f"title '{title}'" if title else "", f"image {os.path.basename(filename)}" if filename else ""]
+        _say(f"{NAMES[kind]} {target_id}: " + ", ".join(change for change in changes if change))
+    if len(steps) > shown:
+        _say(f"... and {len(steps) - shown} more")
+    return input(f"Change these {len(steps)} albums and radio stations? [y/N] ").strip().lower() == "y"
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    """Console script ``tinyjukebox-import-covers``."""
+    parser = argparse.ArgumentParser(
+        description="Set titles and covers of albums and covers of radio stations from a folder with captions.json."
+    )
+    parser.add_argument("address", help="address of the box or of the library, e.g. https://tinyjukebox.local")
+    parser.add_argument("folder", help=f"folder with the images and {CAPTIONS_FILE}")
+    parser.add_argument("--user", required=True, help="an admin of the web page")
+    parser.add_argument("--password-file", help="file with the password (default: asked for)")
+    parser.add_argument("--fingerprint", help="sha256 fingerprint of the certificate (else: shown and asked)")
+    parser.add_argument("--yes", action="store_true", help="do not ask before anything is changed")
+    arguments = parser.parse_args(argv)
+    if arguments.password_file:
+        with open(arguments.password_file, encoding="utf-8") as infile:
+            password = infile.read().strip()
+    else:
+        password = getpass.getpass(f"Password of {arguments.user}: ")
+    try:
+        client = _client(arguments.address.rstrip("/"), arguments.fingerprint, True, "the box or library")
+        token = client.post("/api/login", {"username": arguments.user, "password": password})["token"]
+        client.headers["Authorization"] = f"Bearer {token}"
+        counts = import_covers(client, os.path.expanduser(arguments.folder), None if arguments.yes else _ask)
+    except (Unreachable, WrongCertificate, HttpError, ValueError) as error:
+        sys.exit(f"nothing more was changed: {error}")
+    _say(f"{counts['titles']} titles and {counts['covers']} covers set, {counts['failed']} failed")
+    if counts["failed"]:
+        sys.exit(1)

tinyjukebox/tools/migrate_box01.py

@@ -0,0 +1,151 @@
+"""tinyjukebox-migrate-01 - convert the json files of the old box (version 0.1) into the current format.
+
+    tinyjukebox-migrate-01 /path/to/old-card/json /srv/tinyjukebox/json
+
+Reads albums.json and tags.json from the old folder and writes targets.json, tags.json and an empty activity.json into
+the new folder. The albums themselves are not touched - copy the albums folder separately.
+
+    old albums.json: "45": {"folder": "/srv/tinyjukebox/albums/Album A/", "id": "45", "playlist": "playlist.m3u"}
+    new targets.json: "45": {"target-id": "45", "target-type": "album", "album-folder": "Album A",
+                             "playlist": "playlist.m3u", "created": "..."}
+
+The old format does not know when an album was added: 'created' is the date of the oldest tag linked to the album (or
+now, for albums without tag). The positions of the old activity.json are not taken over - every album starts at its
+beginning.
+"""
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Sequence
+from typing import Any
+
+import jsonschema
+
+from tinyjukebox.data.common import TargetType, is_valid_timestamp, now
+from tinyjukebox.schema.activities import schema as activities_schema
+from tinyjukebox.schema.tags import schema as tags_schema
+from tinyjukebox.schema.targets import schema as targets_schema
+
+__all__ = ["convert_albums", "main"]
+
+OLD_ALBUMS_FOLDER = "/srv/tinyjukebox/albums"
+ALBUMS_FILE, TAGS_FILE, TARGETS_FILE, ACTIVITIES_FILE = "albums.json", "tags.json", "targets.json", "activity.json"
+
+
+def _load(filename: str) -> dict[str, Any]:
+    try:
+        with open(filename, encoding="utf-8") as f:
+            data = json.load(f)
+    except (OSError, ValueError) as e:
+        raise SystemExit(f"cannot read '{filename}': {e}") from e
+    if not isinstance(data, dict):
+        raise SystemExit(f"'{filename}' must contain a json object.")
+    return data
+
+
+def _created_by_album(tags: dict[str, Any]) -> dict[str, str]:
+    """Album id -> 'created' of the oldest tag linked to it (the timestamps sort like their dates)."""
+    created: dict[str, str] = {}
+    for tag in tags.values():
+        target = tag.get("target", {})
+        stamp = tag.get("created")
+        if target.get("type") != TargetType.album.name or not is_valid_timestamp(stamp):
+            continue
+        album_id = str(target.get("id"))
+        if album_id not in created or stamp < created[album_id]:
+            created[album_id] = stamp
+    return created
+
+
+def convert_albums(albums: dict[str, Any], tags: dict[str, Any], old_albums_folder: str) -> dict[str, Any]:
+    """The targets of the old ``albums`` - their folders become relative to ``old_albums_folder``.
+
+    :raises ValueError: if an entry cannot be converted (all problems in one message).
+    """
+    root = os.path.normpath(old_albums_folder)
+    created = _created_by_album(tags)
+    default_created = now()
+    targets: dict[str, Any] = {}
+    problems = []
+    for key, album in albums.items():
+        if not isinstance(album, dict) or not all(isinstance(album.get(k), str) for k in ("folder", "playlist")):
+            problems.append(f"album '{key}': 'folder' and 'playlist' are required.")
+            continue
+        if str(album.get("id", key)) != key:
+            problems.append(f"album '{key}': its 'id' is '{album['id']}'.")
+            continue
+        folder = os.path.normpath(album["folder"])
+        if os.path.commonpath([root, folder]) != root or folder == root:
+            problems.append(f"album '{key}': folder '{album['folder']}' is not inside '{old_albums_folder}'.")
+            continue
+        targets[key] = {
+            "target-id": key,
+            "target-type": TargetType.album.name,
+            "album-folder": os.path.relpath(folder, root),
+            "playlist": album["playlist"],
+            "created": created.get(key, default_created),
+        }
+    if problems:
+        raise ValueError("\n".join(problems))
+    return targets
+
+
+def _write(filename: str, data: dict[str, Any]) -> None:
+    with open(filename, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=4)
+        f.flush()
+        os.fsync(f.fileno())
+
+
+def _validate(name: str, data: dict[str, Any], schema: dict[str, Any]) -> None:
+    try:
+        jsonschema.validate(data, schema)
+    except jsonschema.ValidationError as e:
+        raise SystemExit(f"{name}: {e.message} (at {'/'.join(str(p) for p in e.absolute_path)})") from e
+
+
+def main(argv: Sequence[str] | None = None) -> None:
+    parser = argparse.ArgumentParser(
+        prog="tinyjukebox-migrate-01", description="Convert the json files of the old box (version 0.1)."
+    )
+    parser.add_argument("old", help=f"folder with {ALBUMS_FILE} and {TAGS_FILE} of the old box")
+    parser.add_argument("new", help=f"folder for {TARGETS_FILE}, {TAGS_FILE} and {ACTIVITIES_FILE} (json folder)")
+    parser.add_argument(
+        "--old-albums-folder",
+        default=OLD_ALBUMS_FOLDER,
+        help=f"albums folder of the old box - the album folders become relative to it (default: {OLD_ALBUMS_FOLDER})",
+    )
+    parser.add_argument("--force", action="store_true", help="overwrite existing files in the new folder")
+    args = parser.parse_args(argv)
+
+    albums = _load(os.path.join(args.old, ALBUMS_FILE))
+    tags = _load(os.path.join(args.old, TAGS_FILE))
+    _validate(TAGS_FILE, tags, tags_schema)  # the format of the tags did not change
+    try:
+        targets = convert_albums(albums, tags, args.old_albums_folder)
+    except ValueError as e:
+        raise SystemExit(str(e)) from e
+    activities: dict[str, Any] = {}
+    _validate(TARGETS_FILE, targets, targets_schema)
+    _validate(ACTIVITIES_FILE, activities, activities_schema)
+    output = {TARGETS_FILE: targets, TAGS_FILE: tags, ACTIVITIES_FILE: activities}
+
+    os.makedirs(args.new, exist_ok=True)
+    existing = [name for name in output if os.path.exists(os.path.join(args.new, name))]
+    if existing and not args.force:
+        raise SystemExit(f"'{args.new}' already contains {', '.join(existing)} - use --force to overwrite.")
+    for name, data in output.items():
+        _write(os.path.join(args.new, name), data)
+
+    linked = {str(tag["target"].get("id")) for tag in tags.values() if tag["target"].get("type")}
+    for album_id in sorted(linked - set(targets), key=str):
+        print(f"warning: a tag is linked to album '{album_id}', which does not exist.", file=sys.stderr)
+    for album_id in sorted(set(targets) - linked, key=lambda i: targets[i]["album-folder"]):
+        print(f"album without tag: {album_id}  {targets[album_id]['album-folder']}")
+    print(f"{len(targets)} albums, {len(tags)} tags written to '{args.new}'.", file=sys.stderr)
+
+
+if __name__ == "__main__":
+    main()

tinyjukebox/volumemanager.py

@@ -0,0 +1,355 @@
+"""Volume: limits and steps (VolumeManager) of the speaker and the headset (Volumes) and the mixer that applies it
+(ALSA, virtual or the bluetooth driver)."""
+
+import collections
+import importlib
+import logging
+import select
+import threading
+import time
+from collections.abc import Callable, Mapping
+from enum import StrEnum
+from typing import Any, Protocol
+
+from tinyjukebox.core.logging import get_child
+from tinyjukebox.core.threads import LoggerThread
+from tinyjukebox.data.volumelimits import VolumeLimits
+
+__all__ = [
+    "HOLD_STEP",
+    "AlsaVolumeControl",
+    "VirtualVolumeControl",
+    "VolumeControl",
+    "VolumeManager",
+    "VolumeProfile",
+    "Volumes",
+    "check_limits",
+]
+
+WATCH_POLL_MS = 500  # the watch thread checks for stop at least this often
+WATCH_RETRY = 5.0  # seconds until the watch thread opens the mixer again after an error
+OWN_CHANGE_WINDOW = 1.0  # seconds in which a reported volume that VolumeManager has set itself is ignored
+
+
+class VolumeControl(Protocol):
+    def set_volume(self, volume: float) -> object:
+        """Set the volume in % (0-100)."""
+
+
+class AlsaVolumeControl:
+    """Sets the volume of an ALSA mixer control (e.g. 'Master', 'PCM', 'Headphone') of the default card - or of the
+    mixer ``device`` (e.g. the one of BlueALSA for a headset) - with pyalsaaudio, in the same scale as
+    ``amixer sset <control> N%`` (linear over the raw range of the control).
+
+    pyalsaaudio is imported on first use: it is only installed on the Pi. Its thread safety is not documented - the
+    lock serializes the calls of state machines, rest api and command line. If the mixer fails (e.g. sound card
+    re-plugged), it is created once more before the error is logged.
+
+    :meth:`watch` reports the volume of the control whenever it changes - also changes made outside tinyjukebox, e.g.
+    with alsamixer or (later) by a bluetooth headset.
+    """
+
+    def __init__(
+        self, control: str, logger: logging.Logger, device: str | None = None, watch_retry: float | None = None
+    ) -> None:
+        """``watch_retry``: seconds until :meth:`watch` opens a failing mixer again (default: :data:`WATCH_RETRY`)."""
+        self._logger = get_child(logger, type(self).__name__)
+        self._control = control
+        self._device = device
+        self._watch_retry = watch_retry
+        self._lock = threading.Lock()
+        self._mixer: Any = None
+        self._watch_stop = threading.Event()
+        self._watch_thread: LoggerThread | None = None
+
+    def set_volume(self, volume: float) -> bool:
+        """Set the volume in % - False if that failed (logged)."""
+        with self._lock:
+            try:
+                alsaaudio = importlib.import_module("alsaaudio")
+            except ImportError:
+                self._logger.error("set_volume - pyalsaaudio not installed (only on the pi, needs libasound2-dev).")
+                return False
+            for attempt in (1, 2):
+                try:
+                    if self._mixer is None:
+                        self._mixer = self._open(alsaaudio)
+                    self._mixer.setvolume(round(volume))
+                    return True
+                except alsaaudio.ALSAAudioError as e:
+                    self._mixer = None
+                    if attempt == 2:
+                        self._logger.error("set_volume - '%s' %s%% failed: %s", self._control, round(volume), e)
+            return False
+
+    def _open(self, alsaaudio: Any) -> Any:
+        """A new mixer of the control. :raises alsaaudio.ALSAAudioError: if it does not exist."""
+        if self._device is None:
+            return alsaaudio.Mixer(self._control)
+        return alsaaudio.Mixer(self._control, device=self._device)
+
+    def watch(self, callback: Callable[[float], None]) -> None:
+        """Call ``callback`` with the volume (mean of the channels, %) whenever the control changes - in the watch
+        thread, also for the changes made with :meth:`set_volume`."""
+        if self._watch_thread is not None:
+            return
+        self._watch_stop.clear()
+        self._watch_thread = LoggerThread(
+            target=self._watch, args=(callback,), name="AlsaVolumeControl.watch", logger=self._logger, daemon=True
+        )
+        self._watch_thread.start()
+
+    def stop_watching(self) -> None:
+        self._watch_stop.set()
+        if self._watch_thread is not None:
+            self._watch_thread.join()
+            self._watch_thread = None
+
+    def _watch(self, callback: Callable[[float], None]) -> None:
+        try:
+            alsaaudio = importlib.import_module("alsaaudio")
+        except ImportError:
+            self._logger.error("watch - pyalsaaudio not installed (only on the pi, needs libasound2-dev).")
+            return
+        retry = WATCH_RETRY if self._watch_retry is None else self._watch_retry
+        failure: str | None = None
+        while not self._watch_stop.is_set():
+            try:
+                # a mixer of its own: alsa delivers the events to the handle that is polled
+                mixer = self._open(alsaaudio)
+                try:
+                    poller = select.poll()
+                    for fd, eventmask in mixer.polldescriptors():
+                        # the mixer of BlueALSA reports -1 for a descriptor that is unused at the moment - poll(2)
+                        # ignores those, register() raises
+                        if fd >= 0:
+                            poller.register(fd, eventmask)
+                    failure = None
+                    while not self._watch_stop.is_set():
+                        if poller.poll(WATCH_POLL_MS) and mixer.handleevents():
+                            callback(self._read_volume(alsaaudio))
+                finally:
+                    mixer.close()
+            except alsaaudio.ALSAAudioError as e:
+                # the same reason is reported once - a mixer may be missing for a while (headset not ready yet)
+                level = logging.DEBUG if str(e) == failure else logging.WARNING
+                failure = str(e)
+                self._logger.log(level, "watch - mixer '%s' failed: %s - retrying in %s s", self._control, e, retry)
+                self._watch_stop.wait(retry)
+
+    def _read_volume(self, alsaaudio: Any) -> float:
+        """The volume (mean of the channels, %), read with a mixer of its own - never with the watched one.
+
+        pyalsaaudio looks the control up for every call without checking the result. Once the watched mixer has
+        handled the removal of the control (headset disconnected - and perhaps connected again at once, e.g. when
+        bluetoothd restarts), its getvolume() aborts the whole process in alsa-lib (assertion 'elem' in
+        snd_mixer_selem_has_playback_channel). A new mixer finds the control when it is created - or raises - and
+        handles no events until it is closed.
+
+        :raises alsaaudio.ALSAAudioError: if the control is gone.
+        """
+        mixer = self._open(alsaaudio)
+        try:
+            volumes: list[int] = mixer.getvolume()
+        finally:
+            mixer.close()
+        return sum(volumes) / len(volumes)
+
+
+class VirtualVolumeControl:
+    """Only remembers the volume - for running without hardware (--no-hardware): the mixer of the pc stays as it is."""
+
+    def __init__(self, logger: logging.Logger) -> None:
+        self._logger = get_child(logger, type(self).__name__)
+        self.volume: float | None = None
+
+    def set_volume(self, volume: float) -> None:
+        self.volume = volume
+        self._logger.info("set_volume - virtual volume %s%%", round(volume))
+
+
+HOLD_STEP = 1.0
+"""Change of the volume in % per hold event of a volume button unless the config (``volume-step-hold``) says
+otherwise - as ``volumecontrol.py`` of the old box."""
+
+
+class VolumeManager:
+    """Current volume between 0 and ``max-volume``; changed by buttons, web page and command line concurrently.
+    A button press changes it by ``volume-step``, every hold event of a button by ``volume-step-hold``.
+
+    The lock is held while the mixer is set - never from a pubsub handler directly.
+
+    :meth:`mixer_changed` takes over volumes that were set outside tinyjukebox; ``max-volume`` stays a limit for them.
+    """
+
+    def __init__(
+        self,
+        volume_control: VolumeControl | None,
+        config: Mapping[str, Any],
+        logger: logging.Logger,
+        logger_name: str | None = None,
+    ) -> None:
+        self._logger = get_child(logger, logger_name or type(self).__name__)
+        self._volume_control = volume_control
+        self._max_volume: float = config["max-volume"]
+        self._default_volume: float = config["default-volume"]
+        self._volume_step: float = config["volume-step"]
+        self._hold_step: float = config.get("volume-step-hold", HOLD_STEP)
+        self._lock = threading.RLock()  # the mixer may report a change while it is set
+        self._current_volume: float = min(self._default_volume, self._max_volume)
+        self._own_changes: collections.deque[tuple[float, int]] = collections.deque(maxlen=50)  # (time, volume)
+        self._logger.info(
+            "__init__ - default %s, max %s, step %s", self._default_volume, self._max_volume, self._volume_step
+        )
+        self.update_volume()
+
+    @property
+    def default_volume(self) -> float:
+        return self._default_volume
+
+    @property
+    def max_volume(self) -> float:
+        return self._max_volume
+
+    @property
+    def volume_step(self) -> float:
+        return self._volume_step
+
+    def set_limits(self, default_volume: float, max_volume: float) -> None:
+        """New start value and maximum (see :func:`check_limits`) - a current volume above the new maximum is lowered
+        at once, the start value applies from the next start (:meth:`reset`)."""
+        check_limits(default_volume, max_volume)
+        with self._lock:
+            self._logger.info("set_limits - default %s, max %s", default_volume, max_volume)
+            self._default_volume, self._max_volume = default_volume, max_volume
+            if self._current_volume > max_volume:
+                self._apply(max_volume)
+
+    def reset(self) -> None:
+        """Back to the start value (e.g. whenever the headset connects)."""
+        with self._lock:
+            self._apply(self._default_volume)
+
+    def update_volume(self) -> None:
+        """Apply the current volume (limited to 0..max-volume) to the mixer."""
+        with self._lock:
+            self._apply(self._current_volume)
+
+    def _apply(self, volume: float) -> None:
+        self._current_volume = min(max(volume, 0), self._max_volume)
+        self._own_changes.append((time.monotonic(), round(self._current_volume)))
+        self._logger.info("volume %s", self._current_volume)
+        if self._volume_control is not None:
+            self._volume_control.set_volume(self._current_volume)
+
+    def get_volume(self) -> float:
+        return self._current_volume
+
+    def mixer_changed(self, volume: float) -> None:
+        """The mixer reports ``volume`` (%): volumes set outside tinyjukebox become the current volume; above
+        ``max-volume`` the mixer is set back to it. The reports of the own changes are ignored - also late ones, which
+        would otherwise undo a quick second button press for a moment."""
+        with self._lock:
+            now = time.monotonic()
+            if any(now - at < OWN_CHANGE_WINDOW and own == round(volume) for at, own in self._own_changes):
+                return
+            if volume > self._max_volume:
+                self._logger.warning("volume %s%% set outside tinyjukebox - limited to max-volume", round(volume))
+                self._apply(self._max_volume)
+            elif round(volume) != round(self._current_volume):
+                self._logger.info("volume %s%% set outside tinyjukebox", round(volume))
+                self._current_volume = volume
+
+    def set_volume(self, volume: float) -> None:
+        with self._lock:
+            self._apply(volume)
+
+    def volume_up(self, held: bool = False) -> None:
+        """One step up - ``held``: the small step of a button that is kept pressed."""
+        with self._lock:
+            self._apply(self._current_volume + (self._hold_step if held else self._volume_step))
+
+    def volume_down(self, held: bool = False) -> None:
+        with self._lock:
+            self._apply(self._current_volume - (self._hold_step if held else self._volume_step))
+
+    def volume_off(self) -> None:
+        with self._lock:
+            self._apply(0)
+
+
+def _number(value: object) -> float:
+    if isinstance(value, bool) or not isinstance(value, (int, float)):
+        raise ValueError("start value and maximum must be numbers.")
+    return value
+
+
+def check_limits(default_volume: object, max_volume: object) -> tuple[float, float]:
+    """(start value, maximum). :raises ValueError: unless they are numbers with 0 <= start value <= maximum <= 100."""
+    start, maximum = _number(default_volume), _number(max_volume)
+    if not 0 <= start <= maximum <= 100:
+        raise ValueError("0 <= start value <= maximum <= 100 is required.")
+    return start, maximum
+
+
+class VolumeProfile(StrEnum):
+    """Which volume the buttons change - value: name in the rest api, the command line and ``volume.json``."""
+
+    SPEAKER = "speaker"
+    HEADPHONES = "headphones"
+
+
+class Volumes:
+    """The volumes of speaker and headset - buttons, web page and command line change the active one (the headset's
+    while it is connected). Start value and maximum of both can be changed at runtime; they are stored in
+    :class:`~tinyjukebox.data.volumelimits.VolumeLimits` and override the config from then on."""
+
+    def __init__(
+        self, speaker: VolumeManager, headphones: VolumeManager, limits: VolumeLimits | None, logger: logging.Logger
+    ) -> None:
+        self._logger = get_child(logger, type(self).__name__)
+        self._managers = {VolumeProfile.SPEAKER: speaker, VolumeProfile.HEADPHONES: headphones}
+        self._limits = limits
+        self._active = VolumeProfile.SPEAKER
+        self._lock = threading.Lock()  # changes of the limits are stored one after the other
+
+    @property
+    def active(self) -> VolumeProfile:
+        return self._active
+
+    def manager(self, profile: VolumeProfile | None = None) -> VolumeManager:
+        """The volume of ``profile`` (default: the active one)."""
+        return self._managers[profile or self._active]
+
+    def use(self, profile: VolumeProfile) -> None:
+        if profile != self._active:
+            self._logger.info("buttons change the volume of the %s now", profile.value)
+        self._active = profile
+
+    def set_limits(self, profile: VolumeProfile, default_volume: float, max_volume: float) -> None:
+        """:raises ValueError: for invalid values (see :func:`check_limits`)."""
+        with self._lock:
+            self._managers[profile].set_limits(default_volume, max_volume)
+            if self._limits is not None:
+                self._limits.store(profile.value, default_volume, max_volume)
+
+    # --- the active volume (buttons, web page, command line) ------------------------------------------------------
+
+    def get_volume(self) -> float:
+        return self.manager().get_volume()
+
+    def set_volume(self, volume: float) -> None:
+        self.manager().set_volume(volume)
+
+    def volume_up(self, held: bool = False) -> None:
+        self.manager().volume_up(held)
+
+    def volume_down(self, held: bool = False) -> None:
+        self.manager().volume_down(held)
+
+    def update_volume(self) -> None:
+        self.manager().update_volume()
+
+    def volume_off(self) -> None:
+        """Mute the speaker (shutdown) - the headset is disconnected anyway."""
+        self._managers[VolumeProfile.SPEAKER].volume_off()

tinyjukebox/web/__init__.py

@@ -0,0 +1 @@
+"""REST api and web page of the Tiny Jukebox box (https with a self signed certificate, login with users and roles)."""