tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/spotify/engine.py

@@ -0,0 +1,568 @@
+"""The one Soloist of the box, with its sound (docs/developer/architecture.md, sections 2.5 and 4.1).
+
+It runs while an entry of Spotify plays because of a tag or a test, and - with the speaker switched on - while no tag
+is on the box: then the Spotify app of the account of the box can play on it. A tag that plays no Spotify ends it, so
+that the app does not offer a box that would not listen. Only one Soloist runs at a time: they share the data
+directory with the login. While "Connect" runs ``soloist --pair`` with it, none is started at all.
+
+What the buttons, the headset and the page ask of the speaker is done in a thread of its own, one after the other:
+``soloist ctl`` takes a moment and may hang for seconds, and the dispatch thread of the messages never waits
+(section 10).
+"""
+
+import logging
+import os
+import queue
+import shutil
+import threading
+import time
+from collections.abc import Callable
+from typing import Any, Protocol
+
+from tinyjukebox.albumplayer.simpleplayer import AudioOutput
+from tinyjukebox.core import unexpected
+from tinyjukebox.core.logging import get_child
+from tinyjukebox.messages import Button
+from tinyjukebox.spotify.account import EXPIRED, Busy, SpotifyAccount, Unavailable
+from tinyjukebox.spotify.soloist import Soloist
+from tinyjukebox.spotify.sound import PipeReader, PipeWire, SoundServer
+
+__all__ = ["SPEAKER_PAUSE_LIMIT", "Listener", "SpeakerPlayback", "SpotifyEngine"]
+
+SPEAKER_PAUSE_LIMIT = 600.0
+"""Seconds that what the phone played may be paused before the box is free again (LED green)."""
+CACHE_LIMIT = 300 * 2**20
+"""Bytes of the cache of Soloist after which the speaker ends Soloist while nothing plays, to empty it."""
+IDLE_SECONDS = 5.0
+"""Seconds without a command after which the thread of the commands ends - the next command starts it again."""
+
+
+class Listener(Protocol):
+    """The playback of an entry that uses Soloist (:class:`~tinyjukebox.albumplayer.spotifyplayer.SpotifyPlayer`)."""
+
+    def event(self, event: dict[str, Any]) -> None: ...
+
+    def exited(self, code: int) -> None:
+        """Soloist ended by itself (``code``: its exit code)."""
+        ...
+
+    def suspended(self) -> None:
+        """Soloist was ended by the box - for "Connect", or because the box ends: the playback waits until it may
+        start Soloist again. No failure."""
+        ...
+
+    def output_lost(self) -> None: ...
+
+
+SoloistFactory = Callable[[SpotifyAccount, SoundServer], Soloist]
+SoundFactory = Callable[[], SoundServer]
+
+
+class _Commands:
+    """Runs functions one after the other in a thread of its own - started when there is something to do, it ends
+    when it has had nothing to do for ``idle`` seconds."""
+
+    def __init__(self, logger: logging.Logger, name: str, idle: float = IDLE_SECONDS) -> None:
+        self._logger = logger
+        self._name = name
+        self._idle = idle
+        self._lock = threading.Lock()
+        self._queue: queue.Queue[Callable[[], None]] = queue.Queue()
+        self._thread: threading.Thread | None = None
+
+    def put(self, function: Callable[[], None]) -> None:
+        """Queue ``function`` - returns at once."""
+        with self._lock:
+            self._queue.put(function)
+            if self._thread is None:
+                self._thread = threading.Thread(target=self._run, name=self._name, daemon=True)
+                self._thread.start()
+
+    def wait_until_done(self, timeout: float | None = None) -> bool:
+        """Wait until what was queued before has been done (tests)."""
+        done = threading.Event()
+        self.put(done.set)
+        return done.wait(timeout)
+
+    def _run(self) -> None:
+        while True:
+            try:
+                function = self._queue.get(timeout=self._idle)
+            except queue.Empty:
+                with self._lock:
+                    if self._queue.empty():
+                        self._thread = None
+                        return
+                continue
+            try:
+                function()
+            except Exception as error:
+                self._logger.exception("a command of the Spotify speaker failed")
+                unexpected.report(error, f"thread {self._name}")
+
+
+class SpotifyEngine:
+    """Starts and ends Soloist and its sound for whoever needs it: the playback of an entry (:meth:`open`,
+    :meth:`close`) or the speaker (:meth:`idle`, :meth:`taken`). "Connect" of the account suspends it, :meth:`stop`
+    ends it for good."""
+
+    def __init__(
+        self,
+        account: SpotifyAccount,
+        output: AudioOutput,
+        logger: logging.Logger,
+        device_name: Callable[[], str],
+        soloist_factory: SoloistFactory | None = None,
+        sound_factory: SoundFactory | None = None,
+        clock: Callable[[], float] = time.monotonic,
+        speaker_pause_limit: float = SPEAKER_PAUSE_LIMIT,
+    ) -> None:
+        self.account = account
+        self._logger = get_child(logger, type(self).__name__)
+        self._device_name = device_name
+        self._soloist_factory = soloist_factory or self._create_soloist
+        self._sound_factory = sound_factory or (lambda: PipeWire(os.path.join(account.folder, "sound"), output, logger))
+        self._clock = clock
+        self._speaker_pause_limit = speaker_pause_limit
+        self._lock = threading.RLock()
+        self._sound_lock = threading.Lock()  # what of the speaker is heard - never held while anything waits
+        self._commands = _Commands(self._logger, "Spotify.commands")
+        self._soloist: Soloist | None = None
+        self._sound: SoundServer | None = None
+        self._listener: Listener | None = None
+        self._box_idle = False
+        self._suspended = False  # "Connect" runs soloist --pair with the data directory
+        self._ended = False  # the box ends
+        self._heard = False  # SPOTIFY_SPEAKER: what the phone plays is heard
+        self._losses = 0  # losses of the headset: an output change queued before one does not make the box heard
+        self._speaker_playing = False
+        self._speaker_paused_at: float | None = None
+        self._timer: threading.Timer | None = None
+        self.on_speaker_plays: Callable[[], None] = lambda: None
+        """Something plays from the Spotify app while no tag is on the box (STMOperation: SPOTIFY_SPEAKER)."""
+        self.on_speaker_ends: Callable[[], None] = lambda: None
+        """What the Spotify app played has ended, was paused for long or was taken to another device."""
+        self.on_speaker_paused: Callable[[bool], None] = lambda paused: None
+        """What the Spotify app plays on the box was paused (True) or continues (False) - the LED."""
+        self.speaker_info: dict[str, Any] | None = None
+        """What the phone plays on the box: title and state - for the tab "Now"."""
+        account.on_speaker = self._speaker_switched
+        account.before_connect = self._suspend
+        account.after_connect = self._resume
+
+    # --- Soloist -----------------------------------------------------------------------------------------------------
+
+    def _create_soloist(self, account: SpotifyAccount, sound: SoundServer) -> Soloist:
+        return Soloist(account.usable(), str(account.key), self._device_name(), account.data_dir, account.cache_dir,
+                       self._logger, sound.env, sound.device)  # fmt: skip
+
+    @property
+    def running(self) -> bool:
+        return self._soloist is not None
+
+    @property
+    def reader(self) -> PipeReader | None:
+        sound = self._sound
+        return sound.reader if sound is not None else None
+
+    def _busy(self) -> Busy | None:
+        """Why no Soloist may be started now - None: it may."""
+        if self._ended:
+            return Busy("the box is ending.")
+        if self._suspended:
+            return Busy("the box is being connected to an account of Spotify.")
+        return None
+
+    def _start(self) -> Soloist:
+        """Soloist and its sound - started if they do not run. :raises Busy, Unavailable, OSError:"""
+        with self._lock:
+            busy = self._busy()
+            if busy is not None:
+                raise busy
+            if self._soloist is not None and self._soloist.running:
+                return self._soloist
+            self._stop()
+            self.account.usable()
+            if not self.account.connected:
+                raise Unavailable("not_connected", "the box is not connected to an account of Spotify.")
+            sound = self._sound_factory()
+            sound.start()
+            try:
+                soloist = self._soloist_factory(self.account, sound)
+                soloist.on_event = self._event
+                soloist.on_exit = lambda code: self._exited(soloist, code)
+                sound.reader.on_output_lost = self._output_lost
+                # known before it starts: if it ends at once, _exited (waiting for the lock) sees that it was this one
+                self._sound, self._soloist = sound, soloist
+                soloist.start()
+            except Exception:
+                self._sound = self._soloist = None
+                sound.stop()
+                raise
+            return soloist
+
+    def _stop(self) -> None:
+        with self._lock:
+            soloist, sound = self._soloist, self._sound
+            self._soloist = self._sound = None
+            self._speaker_playing = False
+            self.speaker_info = None
+            self._cancel_timer()
+        if soloist is not None:
+            soloist.stop()
+        if sound is not None:
+            sound.stop()
+        if soloist is not None:
+            # Soloist does not keep to the size of its cache (open report no. 8); it shares the card with the albums
+            shutil.rmtree(self.account.cache_dir, ignore_errors=True)
+
+    def stop(self) -> None:
+        """End Soloist for good - the end of the box. A playback that still runs waits until it is stopped."""
+        with self._lock:
+            self._ended = True
+            listener, self._listener = self._listener, None
+        if listener is not None:
+            listener.suspended()
+        self._stop()
+
+    def _suspend(self) -> None:
+        """Before "Connect" or "Disconnect" (the account's ``before_connect``): Soloist ends, and none is started until
+        :meth:`_resume` - it would share the data directory with ``soloist --pair``. A playback waits meanwhile; what
+        the phone played on the box has ended."""
+        with self._lock:
+            self._suspended = True
+            listener, self._listener = self._listener, None
+            playing = self._speaker_playing
+        if listener is not None:
+            listener.suspended()
+        self._end_speaker_playback()  # what the phone played on the box is paused
+        self._stop()
+        self._logger.info("Spotify: no Soloist until the login of the box has changed")
+        if playing:
+            self.on_speaker_ends()
+
+    def _resume(self) -> None:
+        """After "Connect" or "Disconnect" (the account's ``after_connect``): Soloist may run again - for the speaker at
+        once, if no tag is on the box. A playback that waits starts it with its next try."""
+        with self._lock:
+            self._suspended = False
+            idle = self._box_idle
+        if idle:
+            self.idle()
+
+    def _exited(self, soloist: Soloist, code: int) -> None:
+        """``soloist`` ended by itself."""
+        with self._lock:
+            if soloist is not self._soloist:
+                return  # one that has been replaced already
+            self._soloist = None
+            sound, self._sound = self._sound, None
+        if sound is not None:
+            sound.stop()
+        if code == EXPIRED:
+            self.account.expired()
+        listener = self._listener
+        if listener is not None:
+            listener.exited(code)
+        elif self._box_idle:
+            self._speaker_ended()
+
+    def _output_lost(self) -> None:
+        """``aplay`` failed on the headset (the reader has muted itself): whatever plays pauses."""
+        listener = self._listener
+        if listener is not None:
+            listener.output_lost()
+            return
+        with self._sound_lock:
+            self._losses += 1
+        self.button(Button.PAUSE)
+
+    # --- the playback of an entry ------------------------------------------------------------------------------------
+
+    def open(self, listener: Listener) -> Soloist:
+        """Soloist for the playback of an entry - started if it does not run (blocks).
+        :raises Busy: "Connect" runs or the box ends - the playback tries again later. :raises Unavailable, OSError:"""
+        with self._lock:
+            busy = self._busy()
+            if busy is not None:
+                raise busy
+            self._listener = listener
+            self._end_speaker_playback()
+            try:
+                return self._start()
+            except Exception:
+                self._listener = None
+                raise
+
+    def close(self, listener: Listener) -> None:
+        """The playback of an entry has ended. Soloist keeps running for the speaker, if it is wanted."""
+        with self._lock:
+            if self._listener is not listener:
+                return
+            self._listener = None
+            keep = self._box_idle and self.account.speaker
+        if not keep:
+            self._stop()
+
+    # --- the speaker -------------------------------------------------------------------------------------------------
+
+    def idle(self) -> None:
+        """No tag is on the box (WAIT_FOR_TAG, IDLE_LONG): with the speaker switched on, Soloist runs - started in the
+        thread of the commands."""
+        with self._lock:
+            self._box_idle = True
+            wanted = self._speaker_wanted() and self._soloist is None
+        if wanted:
+            self._commands.put(self._start_speaker)
+
+    def _speaker_wanted(self) -> bool:
+        return self._box_idle and self._listener is None and self._busy() is None and self.account.speaker
+
+    def taken(self, spotify: bool) -> None:
+        """A tag was placed or a test started; ``spotify``: it plays an entry of Spotify, which uses the running
+        Soloist. Anything else ends Soloist."""
+        with self._lock:
+            self._box_idle = False
+            self._end_speaker_playback()
+            stop = not spotify and self._listener is None
+        if stop:
+            self._stop()
+
+    def _start_speaker(self) -> None:
+        """In the thread of the commands: Soloist for the speaker - if it is still wanted."""
+        with self._lock:
+            if not self._speaker_wanted():
+                return
+        try:
+            self._start()
+        except (Busy, Unavailable, OSError) as e:
+            self._logger.info("Spotify speaker not available: %s", e)
+            return
+        with self._lock:
+            if not self._box_idle or self._listener is not None:
+                return
+        self._logger.info("Spotify speaker: the box waits for the Spotify app")
+        if self._cache_too_large():
+            self._logger.info("Spotify speaker: the cache of Soloist is emptied")
+            self._stop()
+            self._commands.put(self._start_speaker)
+
+    def _cache_too_large(self) -> bool:
+        total = 0
+        for root, _, names in os.walk(self.account.cache_dir):
+            for name in names:
+                try:
+                    total += os.path.getsize(os.path.join(root, name))
+                except OSError:
+                    continue
+        return total > CACHE_LIMIT
+
+    def _speaker_switched(self, enabled: bool) -> None:
+        if enabled and self._box_idle:
+            self.idle()
+        elif not enabled and self._listener is None:
+            self._end_speaker_playback()
+            self._stop()
+            if self._box_idle:
+                self.on_speaker_ends()
+
+    def playback(self) -> "SpeakerPlayback":
+        """What the phone plays on the box, as the playback that STMOperation shows and steers."""
+        return SpeakerPlayback(self)
+
+    def listen(self) -> None:
+        """SPOTIFY_SPEAKER: what the phone plays is heard."""
+        with self._sound_lock:
+            self._heard = True
+            reader = self.reader
+            if reader is not None:
+                reader.sound()
+
+    def silence(self) -> None:
+        """SPOTIFY_SPEAKER is left: what the phone played is not heard any more - at once, and what is in the buffer of
+        ``aplay`` neither - and it is paused."""
+        with self._sound_lock:
+            self._heard = False
+            reader = self.reader
+            if reader is not None:
+                reader.muted = True
+        if reader is not None:
+            reader.silence()
+        self._end_speaker_playback()
+
+    def button(self, button: Button) -> None:
+        """A button of the box while the Spotify app plays on it: play/pause, "next" and "back" steer what the phone
+        started; the volume is the box's anyway. Returns at once: ``soloist ctl`` runs in the thread of the commands."""
+        command = {Button.PLAY: "play", Button.PAUSE: "pause", Button.NEXT: "next", Button.PREV: "prev"}.get(button)
+        if command is not None:
+            self._commands.put(lambda: self._speaker_command(command))
+
+    def speaker_output_lost(self, then: Callable[[], None] | None = None) -> None:
+        """The headset has gone while the phone plays on the box: muted at once - nothing reaches ``aplay`` any more,
+        whatever it plays on - and the phone's playback is paused in the thread of the commands, after what was queued
+        before; then ``then`` is called. Returns at once."""
+        with self._sound_lock:
+            self._losses += 1
+            reader = self.reader
+            if reader is not None:
+                reader.muted = True
+        self._commands.put(lambda: self._pause_for_output(then))
+
+    def _pause_for_output(self, then: Callable[[], None] | None) -> None:
+        try:
+            self._speaker_command("pause")
+        finally:
+            if then is not None:
+                then()
+
+    def speaker_output_changed(self) -> None:
+        """Another output while the phone plays on the box: the sound goes on there - another ``aplay``, in the thread
+        of the commands. A loss of the headset meanwhile keeps it muted. Returns at once."""
+        with self._sound_lock:
+            loss = self._losses
+        self._commands.put(lambda: self._output_changed(loss))
+
+    def _output_changed(self, loss: int) -> None:
+        reader = self.reader
+        if reader is None:
+            return
+        reader.restart_output()
+        with self._sound_lock:
+            if self._heard and self._losses == loss and reader is self.reader:
+                reader.sound()
+
+    def _speaker_command(self, command: str) -> None:
+        """``soloist ctl <command>`` for what the phone plays - only while it is heard (SPOTIFY_SPEAKER)."""
+        with self._lock:
+            soloist = self._soloist if self._listener is None else None
+        if soloist is None or not self._heard:
+            return
+        try:
+            soloist.ctl(command)
+        except Exception as e:  # Soloist has ended meanwhile
+            self._logger.info("Spotify speaker: %s: %s", command, e)
+
+    def wait_until_done(self, timeout: float | None = None) -> bool:
+        """Wait until the commands queued before have been done (tests)."""
+        return self._commands.wait_until_done(timeout)
+
+    def _end_speaker_playback(self) -> None:
+        with self._lock:
+            playing, self._speaker_playing = self._speaker_playing, False
+            self.speaker_info = None
+            self._cancel_timer()
+            soloist = self._soloist if self._listener is None else None
+        if playing and soloist is not None and soloist.running:
+            try:
+                soloist.ctl("pause")
+            except Exception as e:  # the phone has taken it away already, or Soloist has ended
+                self._logger.info("Spotify speaker: pause: %s", e)
+
+    def _cancel_timer(self) -> None:
+        timer, self._timer = self._timer, None
+        if timer is not None:
+            timer.cancel()
+
+    def _event(self, event: dict[str, Any]) -> None:
+        listener = self._listener
+        if listener is not None:
+            listener.event(event)
+            return
+        if not self._box_idle:
+            return
+        kind = event.get("type")
+        if kind in ("playback_state", "playback_changed"):
+            status = event.get("status")
+            if kind == "playback_state":
+                self._speaker_track(event.get("item"))
+            if status == "playing":
+                self._speaker_started()
+            elif status == "paused":
+                self._speaker_paused()
+            elif status == "idle":
+                self._speaker_ended()
+        elif kind == "track_changed":
+            self._speaker_track(event.get("item"))
+        elif kind in ("device_changed", "auth_state") and event.get("is_active") is False:
+            self._speaker_ended()
+
+    def _speaker_track(self, item: object) -> None:
+        if isinstance(item, dict):
+            identity = (item.get("decorations") or {}).get("identity") or {}
+            self.speaker_info = {**(self.speaker_info or {}), "title": identity.get("name"), "uri": item.get("uri")}
+
+    def _speaker_started(self) -> None:
+        with self._lock:
+            self._cancel_timer()
+            self._speaker_paused_at = None
+            started = not self._speaker_playing
+            self._speaker_playing = True
+            self.speaker_info = {**(self.speaker_info or {}), "state": "playing"}
+        if started:
+            self._logger.info("Spotify speaker: the Spotify app plays on the box")
+            self.on_speaker_plays()
+        else:
+            self.on_speaker_paused(False)
+
+    def _speaker_paused(self) -> None:
+        with self._lock:
+            if not self._speaker_playing:
+                return
+            self.speaker_info = {**(self.speaker_info or {}), "state": "paused"}
+            self._cancel_timer()
+            self._timer = threading.Timer(self._speaker_pause_limit, self._speaker_ended)
+            self._timer.daemon = True
+            self._timer.start()
+        self.on_speaker_paused(True)
+
+    def _speaker_ended(self) -> None:
+        with self._lock:
+            playing, self._speaker_playing = self._speaker_playing, False
+            self.speaker_info = None
+            self._cancel_timer()
+        if playing:
+            self._logger.info("Spotify speaker: the Spotify app does not play on the box any more")
+            self.on_speaker_ends()
+
+
+class SpeakerPlayback:
+    """What the Spotify app plays on the box while no tag is on it - steered like an album by the buttons, the headset
+    and the page (:class:`~tinyjukebox.stm.stmoperation.AlbumControl`). Every command returns at once; ``soloist ctl``
+    runs in the thread of the commands of the engine."""
+
+    def __init__(self, engine: SpotifyEngine) -> None:
+        self._engine = engine
+
+    def start(self) -> None:
+        self._engine.listen()
+
+    def stop(self) -> None:
+        self._engine.silence()
+
+    def cmd_next_handler(self) -> None:
+        self._engine.button(Button.NEXT)
+
+    def cmd_prev_handler(self) -> None:
+        self._engine.button(Button.PREV)
+
+    def cmd_restart_album(self) -> None:
+        """What the phone plays has no beginning the box knows."""
+
+    def cmd_pause(self) -> None:
+        self._engine.button(Button.PAUSE)
+
+    def cmd_play(self) -> None:
+        self._engine.button(Button.PLAY)
+
+    def cmd_output_lost(self, then: Callable[[], None] | None = None) -> None:
+        """The headset has gone: the sound is muted at once, the phone's playback pauses; ``then`` is called once the
+        pause has been handled - in the thread of the commands, after what was queued before."""
+        self._engine.speaker_output_lost(then)
+
+    def cmd_output_changed(self) -> None:
+        self._engine.speaker_output_changed()
+
+    def get_info(self) -> dict[str, Any]:
+        info = self._engine.speaker_info or {}
+        return {"target_type": "speaker", "name": info.get("title"), "uri": info.get("uri"),
+                "state": info.get("state", "playing")}  # fmt: skip

tinyjukebox/spotify/oembed.py

@@ -0,0 +1,65 @@
+"""Name and cover of an entry of Spotify, from Spotify's oEmbed address - it needs no account.
+
+What it returns depends on the kind: an album, a playlist, a track and an artist come with their name and a square
+cover. For a podcast (``show``) it returns its newest episode: that title is not taken, and its picture only if it is
+square. An audiobook or an episode often returns nothing. Whatever fails leaves the name or the cover out - the entry
+is then named by hand.
+"""
+
+import json
+import logging
+import urllib.parse
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Any
+
+from tinyjukebox.data.target import spotify_kind, spotify_link
+from tinyjukebox.images import MAX_IMAGE_SIZE, image_extension
+
+__all__ = ["OEMBED", "Found", "Opener", "look_up"]
+
+OEMBED = "https://open.spotify.com/oembed?url="
+TIMEOUT = 10.0
+MAX_ANSWER = 64 * 1024
+
+Opener = Callable[..., Any]
+
+
+@dataclass(frozen=True)
+class Found:
+    """What Spotify says about an entry: ``name`` and ``image`` (jpeg, png or webp) or ``None``."""
+
+    name: str | None = None
+    image: bytes | None = None
+
+
+def _read(opener: Opener, url: str, limit: int) -> bytes:
+    with opener(url, timeout=TIMEOUT) as response:
+        return response.read(limit + 1)  # type: ignore[no-any-return]
+
+
+def look_up(uri: str, logger: logging.Logger, opener: Opener = urllib.request.urlopen, image: bool = True) -> Found:
+    """Name and cover of the entry ``uri`` (``spotify:<kind>:<id>``); ``image``: fetch the cover as well."""
+    try:
+        raw = _read(opener, OEMBED + urllib.parse.quote(spotify_link(uri), safe=""), MAX_ANSWER)
+        answer = json.loads(raw[:MAX_ANSWER].decode("utf-8"))
+    except (OSError, ValueError) as e:
+        logger.info("no name and cover from Spotify for %s: %s", uri, e)
+        return Found()
+    if not isinstance(answer, dict):
+        return Found()
+    podcast = spotify_kind(uri) == "show"
+    title = answer.get("title")
+    name = title.strip()[:100] if isinstance(title, str) and title.strip() and not podcast else None
+    width, height = answer.get("thumbnail_width"), answer.get("thumbnail_height")
+    thumbnail = answer.get("thumbnail_url")
+    data = None
+    if image and isinstance(thumbnail, str) and thumbnail.startswith("https://") and (not podcast or width == height):
+        try:
+            data = _read(opener, thumbnail, MAX_IMAGE_SIZE)
+        except OSError as e:
+            logger.info("no cover from Spotify for %s: %s", uri, e)
+        if data is not None and (len(data) > MAX_IMAGE_SIZE or image_extension(data) is None):
+            data = None
+    return Found(name, data)