tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/spotify/soloist.py

@@ -0,0 +1,198 @@
+"""One running Soloist: the process, its commands (``soloist ctl``) and its events (``soloist ctl trace``).
+
+Soloist is started with its WebSocket interface on a free port of 127.0.0.1; ``soloist ctl`` finds it through the files
+``ws.addr`` and ``ws.port`` in its data directory. Every event is one line ``<unix_epoch_ms> <json>``.
+"""
+
+import contextlib
+import json
+import logging
+import subprocess
+import threading
+from collections.abc import Callable, Mapping, Sequence
+from typing import IO, Any
+
+from tinyjukebox.core.logging import get_child
+
+__all__ = ["CACHE_MB", "CTL_TIMEOUT", "Soloist", "SoloistError", "parse_event"]
+
+CACHE_MB = 100
+"""--cache-size: the smallest value Soloist takes. It does not keep to it (open report no. 8): the box empties the
+cache whenever it ends Soloist."""
+CTL_TIMEOUT = 10.0
+
+EventHook = Callable[[dict[str, Any]], None]
+
+
+class SoloistError(Exception):
+    """A command of ``soloist ctl`` failed."""
+
+
+def parse_event(line: str) -> dict[str, Any] | None:
+    """The event of a line of ``soloist ctl trace`` - None for anything else."""
+    _, _, text = line.strip().partition(" ")
+    try:
+        event = json.loads(text)
+    except ValueError:
+        return None
+    return event if isinstance(event, dict) and isinstance(event.get("type"), str) else None
+
+
+class Soloist:
+    """Soloist of the box, started by :meth:`start` and ended by :meth:`stop`. ``on_event`` is called with every
+    event (from a thread of its own), ``on_exit`` with the exit code when Soloist ends without being stopped. Once it
+    is stopped, no event is passed on and no command is run any more: the next Soloist - or ``soloist --pair`` of
+    "Connect" - may use the data directory already."""
+
+    def __init__(
+        self,
+        program: str,
+        key: str,
+        name: str,
+        data_dir: str,
+        cache_dir: str,
+        logger: logging.Logger,
+        env: Mapping[str, str] | None = None,
+        device: str | None = None,
+        popen: Callable[..., subprocess.Popen[bytes]] = subprocess.Popen,
+        run: Callable[..., subprocess.CompletedProcess[str]] = subprocess.run,
+    ) -> None:
+        self._program = program
+        self._key = key
+        self._name = name
+        self._data_dir = data_dir
+        self._cache_dir = cache_dir
+        self._logger = get_child(logger, type(self).__name__)
+        self._env = dict(env) if env is not None else None
+        self._device = device
+        self._popen = popen
+        self._run = run
+        self._lock = threading.Lock()
+        self._process: subprocess.Popen[bytes] | None = None
+        self._trace: subprocess.Popen[bytes] | None = None
+        self._threads: list[threading.Thread] = []
+        self._stopped = threading.Event()
+        self.on_event: EventHook = lambda event: None
+        self.on_exit: Callable[[int], None] = lambda code: None
+
+    def command(self) -> list[str]:
+        command = [self._program, "-n", self._name, "-k", self._key, "-D", self._data_dir, "-C", self._cache_dir,
+                   "-z", str(CACHE_MB), "-i", "100", "-w", "127.0.0.1:0"]  # fmt: skip
+        if self._device is not None:
+            command += ["-d", self._device]
+        return command
+
+    def start(self) -> None:
+        """Start Soloist and follow its events. :raises OSError: if it cannot be started."""
+        self._stopped.clear()
+        process = self._popen(self.command(), stdout=subprocess.DEVNULL, stderr=subprocess.PIPE, env=self._env)
+        with self._lock:
+            self._process = process
+        self._logger.info("Soloist started (pid %s)", process.pid)
+        for target, name in ((self._follow, "Soloist.trace"), (self._watch, "Soloist.watch")):
+            thread = threading.Thread(target=target, args=(process,), name=name, daemon=True)
+            self._threads.append(thread)
+            thread.start()
+
+    @property
+    def running(self) -> bool:
+        process = self._process
+        return process is not None and process.poll() is None
+
+    def _watch(self, process: subprocess.Popen[bytes]) -> None:
+        """Wait for the end of Soloist; what it said last goes to the log."""
+        said: list[bytes] = []
+        if process.stderr is not None:
+            with contextlib.suppress(OSError, ValueError), process.stderr:
+                for line in process.stderr:
+                    said = [*said[-9:], line]
+        code = process.wait()
+        if self._stopped.is_set():
+            return
+        self._logger.warning(
+            "Soloist ended (%s): %s", code, b"".join(said).decode("utf-8", errors="replace").strip()[-500:]
+        )
+        self.on_exit(code)
+
+    def _follow(self, process: subprocess.Popen[bytes]) -> None:
+        """``soloist ctl trace`` - started again while Soloist runs (it needs a moment until its port is known)."""
+        while not self._stopped.is_set() and process.poll() is None:
+            try:
+                trace = self._popen(
+                    self._ctl("trace"), stdout=subprocess.PIPE, stderr=subprocess.DEVNULL, env=self._env
+                )
+            except OSError as e:
+                self._logger.error("cannot follow the events of Soloist: %s", e)
+                return
+            with self._lock:
+                self._trace = trace
+            self._read(trace.stdout)
+            if trace.stdout is not None:
+                trace.stdout.close()
+            trace.wait()
+            if not self._stopped.wait(0.5):
+                self._logger.debug("soloist ctl trace ended (%s) - following again", trace.returncode)
+
+    def _read(self, stream: IO[bytes] | None) -> None:
+        if stream is None:
+            return
+        with contextlib.suppress(OSError, ValueError):
+            for raw in stream:
+                if self._stopped.is_set():
+                    return  # what was still in the pipe comes from a Soloist that the box has ended
+                event = parse_event(raw.decode("utf-8", errors="replace"))
+                if event is not None:
+                    try:
+                        self.on_event(event)
+                    except Exception:
+                        self._logger.exception("handling the event %s failed", event.get("type"))
+
+    def _ctl(self, *args: str) -> list[str]:
+        return [self._program, "ctl", "-D", self._data_dir, *args]
+
+    def ctl(self, *args: str) -> str:
+        """A command of ``soloist ctl``; returns what it printed. :raises SoloistError: if it fails, or if Soloist
+        has been stopped."""
+        if self._stopped.is_set():
+            raise SoloistError(f"soloist ctl {' '.join(args)}: Soloist has been stopped")
+        try:
+            done = self._run(self._ctl(*args), capture_output=True, text=True, timeout=CTL_TIMEOUT, env=self._env)
+        except (OSError, subprocess.SubprocessError) as e:
+            raise SoloistError(f"soloist ctl {' '.join(args)}: {e}") from e
+        if done.returncode != 0:
+            raise SoloistError(f"soloist ctl {' '.join(args)}: {(done.stderr or done.stdout).strip()[-300:]}")
+        return done.stdout
+
+    def json(self, *args: str) -> dict[str, Any]:
+        """A command of ``soloist ctl`` that prints json (``now --json``, ``queue N --json``)."""
+        text = self.ctl(*args)
+        try:
+            value = json.loads(text)
+        except ValueError as e:
+            raise SoloistError(f"soloist ctl {' '.join(args)}: no json") from e
+        return value if isinstance(value, dict) else {}
+
+    def stop(self, timeout: float = 5.0) -> None:
+        self._stopped.set()
+        with self._lock:
+            processes: Sequence[subprocess.Popen[bytes] | None] = (self._trace, self._process)
+            self._trace = self._process = None
+        for process in processes:
+            if process is not None and process.poll() is None:
+                process.terminate()
+        for process in processes:
+            if process is None:
+                continue
+            try:
+                process.wait(timeout)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                try:
+                    process.wait(timeout)
+                except subprocess.TimeoutExpired:
+                    self._logger.error("Soloist does not end (pid %s) - left behind", process.pid)
+        for thread in self._threads:
+            if thread is not threading.current_thread():
+                thread.join(timeout)
+        self._threads = []
+        self._logger.info("Soloist stopped")

tinyjukebox/spotify/sound.py

@@ -0,0 +1,316 @@
+"""The sound of Soloist on the box: a PipeWire of its own whose only output is a named pipe, and the reader of that pipe
+that hands the sound to ``aplay`` (docs/developer/architecture.md, section 4.1).
+
+Soloist plays only into PipeWire or PulseAudio; the box plays with ``aplay``, to the speaker or through BlueALSA to the
+headset. PipeWire and WirePlumber are started with a setup of their own in the folder ``spotify``: no sound card, no
+Bluetooth, one sink that writes 16 bit stereo, 44.1 kHz into the pipe. The box reads the pipe itself. That way it sees
+whether sound comes (a playback that stands still while Soloist says "playing", open report no. 5), it starts another
+``aplay`` on another output without touching Soloist, and it drops the sound while it skips to a saved track.
+
+A process is ended with SIGTERM first and SIGKILL after a while, and every wait is bounded: an ``aplay`` that hangs in
+its driver never empties its pipe, and whoever ends it must not wait for that.
+"""
+
+import contextlib
+import errno
+import logging
+import os
+import select
+import shutil
+import subprocess
+import threading
+import time
+from collections.abc import Callable, Mapping
+from typing import IO, Any
+
+from tinyjukebox.albumplayer.simpleplayer import AudioOutput
+from tinyjukebox.core.logging import get_child
+
+__all__ = ["NODE", "PipeReader", "PipeWire", "SoundServer", "is_silent"]
+
+NODE = "tinyjukebox"
+"""Name of the sink of PipeWire into which Soloist plays (``--pipewire-device``)."""
+CHUNK = 4096
+FORMAT = "S16LE"
+END_TIMEOUT = 2.0
+"""Seconds a process has to end after SIGTERM, and again after SIGKILL."""
+
+PIPEWIRE_CONF = """# written by tinyjukebox: the only output of this PipeWire is the pipe that the box reads
+context.modules = [
+    {{ name = libpipewire-module-pipe-tunnel
+        args = {{
+            tunnel.mode = sink
+            pipe.filename = "{pipe}"
+            audio.format = {format}
+            audio.rate = 44100
+            audio.channels = 2
+            audio.position = [ FL FR ]
+            stream.props = {{
+                node.name = "{node}"
+                node.description = "Tiny Jukebox"
+                priority.session = 2000
+            }}
+        }}
+    }}
+]
+"""
+
+WIREPLUMBER_CONF = """# written by tinyjukebox: no sound card and no Bluetooth - those belong to the box and to BlueALSA
+wireplumber.profiles = {
+    main = {
+        monitor.alsa = disabled
+        monitor.alsa-midi = disabled
+        monitor.bluez = disabled
+        monitor.bluez.midi = disabled
+        monitor.v4l2 = disabled
+        monitor.libcamera = disabled
+        support.reserve-device = disabled
+        support.logind = disabled
+    }
+}
+"""
+
+
+def is_silent(chunk: bytes) -> bool:
+    """Digital silence: nothing but zeros."""
+    return not chunk.strip(b"\x00")
+
+
+class SoundServer:
+    """What Soloist plays into - ``env`` for Soloist, ``device`` its sink, ``reader`` the pipe."""
+
+    env: Mapping[str, str] | None = None
+    device: str | None = None
+    reader: "PipeReader"
+
+    def start(self) -> None: ...
+
+    def stop(self) -> None: ...
+
+
+class PipeReader:
+    """Reads the pipe and hands the sound to ``aplay`` on the current output. ``muted``: the sound is dropped.
+    ``on_output_lost``: ``aplay`` failed on the headset (it has gone)."""
+
+    def __init__(
+        self,
+        pipe: str,
+        output: AudioOutput,
+        logger: logging.Logger,
+        popen: Callable[..., subprocess.Popen[bytes]] = subprocess.Popen,
+        clock: Callable[[], float] = time.monotonic,
+    ) -> None:
+        self._pipe = pipe
+        self._output = output
+        self._logger = get_child(logger, type(self).__name__)
+        self._popen = popen
+        self._clock = clock
+        self._lock = threading.Lock()
+        self._aplay: subprocess.Popen[bytes] | None = None
+        self._headset = False
+        self._stopped = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._fds: tuple[int, int] | None = None
+        self.muted = True
+        self.last_sound = clock()
+        """When the last chunk that was not silent arrived (while not muted)."""
+        self.on_output_lost: Callable[[], None] = lambda: None
+
+    @property
+    def pipe(self) -> str:
+        return self._pipe
+
+    def open(self) -> None:
+        """Create the pipe and open it - before PipeWire starts, which writes into it."""
+        with contextlib.suppress(FileNotFoundError):
+            os.remove(self._pipe)
+        os.mkfifo(self._pipe, 0o600)
+        read = os.open(self._pipe, os.O_RDONLY | os.O_NONBLOCK)
+        # a writer of our own: without one, every read returns at once while PipeWire has not opened the pipe
+        write = os.open(self._pipe, os.O_WRONLY | os.O_NONBLOCK)
+        self._fds = (read, write)
+        self._stopped.clear()
+        self._thread = threading.Thread(target=self._run, name="Spotify.pipe", daemon=True)
+        self._thread.start()
+
+    def _run(self) -> None:
+        assert self._fds is not None  # noqa: S101 - set by open()
+        read = self._fds[0]
+        while not self._stopped.is_set():
+            ready, _, _ = select.select([read], [], [], 0.5)
+            if not ready:
+                continue
+            try:
+                chunk = os.read(read, CHUNK)
+            except BlockingIOError:
+                continue
+            except OSError:
+                break
+            if not chunk:
+                time.sleep(0.05)
+                continue
+            if self.muted:
+                continue
+            if not is_silent(chunk):
+                self.last_sound = self._clock()
+            self._play(chunk)
+
+    def _play(self, chunk: bytes) -> None:
+        with self._lock:
+            aplay = self._aplay
+            if aplay is None or aplay.poll() is not None:
+                if self.muted:  # silenced meanwhile: no aplay of its own any more
+                    return
+                command, self._headset = self._output.current()
+                try:
+                    # unbuffered: ending aplay never flushes into a pipe that a hung aplay does not empty
+                    aplay = self._popen(command, stdin=subprocess.PIPE, stdout=subprocess.DEVNULL,
+                                        stderr=subprocess.DEVNULL, bufsize=0)  # fmt: skip
+                except OSError as e:
+                    self._logger.error("cannot start %s: %s", command[0], e)
+                    return
+                self._aplay = aplay
+        try:
+            assert aplay.stdin is not None  # noqa: S101 - stdin=PIPE
+            _write_all(aplay.stdin, chunk)
+        except (BrokenPipeError, ValueError, OSError):
+            with self._lock:
+                if self._aplay is not aplay:
+                    return  # ended by the box: another output, or silence
+                headset, self._aplay = self._headset, None
+            if headset:
+                # never on to the speaker by itself: the box must not become loud unexpectedly
+                self.muted = True
+                self._logger.warning("the headset output failed - pause")
+                self.on_output_lost()
+
+    def restart_output(self) -> None:
+        """End ``aplay``: the next sound starts another one, on the output that is current then. Waits at most
+        twice :data:`END_TIMEOUT`."""
+        with self._lock:
+            aplay, self._aplay = self._aplay, None
+        if not _end(aplay):
+            self._logger.error("aplay does not end (pid %s) - left behind", getattr(aplay, "pid", None))
+
+    def silence(self) -> None:
+        """Drop the sound from now on, and end ``aplay``: what is in its buffer is not heard."""
+        self.muted = True
+        self.restart_output()
+
+    def sound(self) -> None:
+        """Hand the sound to ``aplay`` again."""
+        self.last_sound = self._clock()
+        self.muted = False
+
+    def close(self) -> None:
+        """End the reader and its ``aplay`` - aplay first: the reader may wait for it to take the sound."""
+        self._stopped.set()
+        self.silence()
+        thread, self._thread = self._thread, None
+        if thread is not None and thread is not threading.current_thread():
+            thread.join(2)
+        fds, self._fds = self._fds, None
+        for fd in fds or ():
+            with contextlib.suppress(OSError):
+                os.close(fd)
+        with contextlib.suppress(FileNotFoundError):
+            os.remove(self._pipe)
+
+
+def _write_all(stream: IO[bytes], chunk: bytes) -> None:
+    """All of ``chunk`` into an unbuffered pipe: a write interrupted by a signal takes only a part of it."""
+    written: int | None = stream.write(chunk)
+    while written is not None and 0 < written < len(chunk):
+        chunk = chunk[written:]
+        written = stream.write(chunk)
+
+
+def _end(process: subprocess.Popen[Any] | None, timeout: float | None = None) -> bool:
+    """End ``process``: SIGTERM, SIGKILL after ``timeout`` (:data:`END_TIMEOUT`) - every wait is bounded. Its input is
+    closed only then: closed first, it would be flushed into a pipe that a hung ``aplay`` never empties. Returns False
+    if it does not end (it hangs in a driver) - it is left behind."""
+    if process is None:
+        return True
+    timeout = END_TIMEOUT if timeout is None else timeout
+    ended = True
+    if process.poll() is None:
+        process.terminate()
+        try:
+            process.wait(timeout)
+        except subprocess.TimeoutExpired:
+            process.kill()
+            try:
+                process.wait(timeout)
+            except subprocess.TimeoutExpired:
+                ended = False
+    if process.stdin is not None:
+        with contextlib.suppress(OSError, ValueError):
+            process.stdin.close()
+    return ended
+
+
+class PipeWire(SoundServer):
+    """PipeWire and WirePlumber of the box, in ``folder`` (``spotify/sound``): config, runtime directory, pipe."""
+
+    def __init__(
+        self,
+        folder: str,
+        output: AudioOutput,
+        logger: logging.Logger,
+        popen: Callable[..., subprocess.Popen[bytes]] = subprocess.Popen,
+    ) -> None:
+        self._folder = folder
+        self._logger = get_child(logger, type(self).__name__)
+        self._popen = popen
+        self._processes: list[subprocess.Popen[bytes]] = []
+        runtime = os.path.join(folder, "run")
+        self._env: dict[str, str] = {
+            **os.environ,
+            "XDG_RUNTIME_DIR": runtime,
+            "PIPEWIRE_RUNTIME_DIR": runtime,
+            "XDG_CONFIG_HOME": os.path.join(folder, "config"),
+            "XDG_STATE_HOME": os.path.join(folder, "state"),
+        }
+        self._env.pop("DBUS_SESSION_BUS_ADDRESS", None)
+        self._env.pop("PULSE_SERVER", None)
+        self.env = self._env
+        self.device = NODE
+        self.reader = PipeReader(os.path.join(folder, "sound.pipe"), output, logger, popen)
+
+    def _write_config(self) -> None:
+        for name, content in (
+            (os.path.join("pipewire", "pipewire.conf.d", "tinyjukebox.conf"),
+             PIPEWIRE_CONF.format(pipe=self.reader.pipe, format=FORMAT, node=NODE)),
+            (os.path.join("wireplumber", "wireplumber.conf.d", "tinyjukebox.conf"), WIREPLUMBER_CONF),
+        ):  # fmt: skip
+            path = os.path.join(self._env["XDG_CONFIG_HOME"], name)
+            os.makedirs(os.path.dirname(path), exist_ok=True)
+            with open(path, "w", encoding="utf-8") as f:
+                f.write(content)
+
+    def start(self) -> None:
+        """:raises OSError: if PipeWire or WirePlumber cannot be started (e.g. not installed)."""
+        for program in ("pipewire", "wireplumber"):
+            if shutil.which(program) is None:
+                raise OSError(errno.ENOENT, f"{program} is not installed")
+        shutil.rmtree(self._env["XDG_RUNTIME_DIR"], ignore_errors=True)
+        os.makedirs(self._env["XDG_RUNTIME_DIR"], mode=0o700, exist_ok=True)
+        self._write_config()
+        self.reader.open()
+        try:
+            for program in ("pipewire", "wireplumber"):
+                self._processes.append(
+                    self._popen([program], env=self._env, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
+                )
+                time.sleep(0.3)  # WirePlumber connects to PipeWire
+        except OSError:
+            self.stop()
+            raise
+        self._logger.info("PipeWire for Spotify started")
+
+    def stop(self) -> None:
+        self.reader.close()
+        for process in reversed(self._processes):
+            if not _end(process):
+                self._logger.error("%s does not end (pid %s) - left behind", process.args, process.pid)
+        self._processes = []

tinyjukebox/stm/base.py

@@ -0,0 +1,174 @@
+"""Common base of the state machines: a robust tantamount machine, the state base class and diagram export."""
+
+import logging
+import threading
+import time
+from collections.abc import Callable
+from enum import Enum
+from pathlib import Path
+
+from tantamount.fsm2dot import GetDotNotation
+from tantamount.machine import Machine
+from tantamount.simplestate import SimpleState
+
+from tinyjukebox.core import unexpected
+from tinyjukebox.core.logging import get_child
+
+__all__ = [
+    "RESUME_WINDOW",
+    "OutputPause",
+    "PauseReason",
+    "PeriodicTask",
+    "SafeMachine",
+    "State",
+    "create_machine",
+    "mermaid_notation",
+    "write_dot_file",
+]
+
+RESUME_WINDOW = 600.0
+"""Seconds within which a headset that comes back continues a playback that its disconnection has paused."""
+_CALL = object()  # in the queue of the worker in place of an event: a function to call (SafeMachine.call_soon)
+
+
+class SafeMachine(Machine):  # type: ignore[misc]  # tantamount has no type information
+    """tantamount machine that ignores undefined events and whose async worker survives exceptions of states.
+
+    tantamount 0.3.2 has two problems that are worked around here:
+
+    * The constructor stores ``ignore_undefined_events`` under the wrong attribute name. Without the flag an
+      unexpected event (e.g. a button press while an album is finished) raises a ``KeyError`` in the worker thread.
+    * An exception in ``on_entry``/``on_exit`` of a state reached via ``asyncoperate()`` terminates the worker
+      thread - afterwards the machine silently ignores all events and ``stop()`` blocks forever.
+    """
+
+    def __init__(self, logger: logging.Logger) -> None:
+        super().__init__(ignore_undefined_events=True)
+        self._ignore_undefined_events = True
+        self._logger = logger
+
+    def call_soon(self, function: Callable[[], object]) -> None:
+        """Call ``function`` in the worker, after the events queued before it - e.g. what has to happen once a queued
+        event has been handled. A machine that is stopped before calls it no more."""
+        self._async_queue.put((_CALL, function, None))
+
+    def _async_worker(self) -> None:
+        while True:
+            params = self._async_queue.get()
+            if params is None or self._stopping:
+                self._async_queue.task_done()
+                break
+            eventid, source_stateid, source_activation_counter = params
+            try:
+                if eventid is _CALL:
+                    source_stateid()
+                else:
+                    self.operate(eventid, source_stateid, source_activation_counter)
+            except Exception as error:
+                self._logger.exception("_async_worker - processing event '%s' failed", eventid)
+                unexpected.report(error, f"state machine, event {eventid}")
+            self._async_queue.task_done()
+
+    def wait_until_idle(self) -> None:
+        """Block until all events queued with ``asyncoperate`` have been processed (tests)."""
+        self._async_queue.join()
+
+
+def create_machine(logger: logging.Logger) -> SafeMachine:
+    """A new :class:`SafeMachine` (a tantamount machine can be started only once)."""
+    return SafeMachine(logger)
+
+
+class State(SimpleState):  # type: ignore[misc]  # tantamount has no type information
+    """Base class of all states.
+
+    tantamount calls ``on_entry``/``on_exit`` with the machine's operate lock held - states are never entered or
+    left concurrently. ``_on_entry`` may return a transition that is processed immediately.
+    """
+
+    def __init__(self, state_id: Enum, logger: logging.Logger) -> None:
+        super().__init__(state_id, None)
+        self._logger = get_child(logger, type(self).__name__)
+
+    def on_entry(self) -> Enum | None:
+        self._logger.info("on_entry")
+        return self._on_entry()
+
+    def on_exit(self) -> None:
+        self._logger.info("on_exit")
+        self._on_exit()
+
+    def _on_entry(self) -> Enum | None:
+        return None
+
+    def _on_exit(self) -> None:
+        pass
+
+
+def write_dot_file(machine: Machine, filename: str | Path) -> None:
+    """Write a Graphviz representation of the machine (``dot -Tpng file.dot > file.png``)."""
+    Path(filename).write_text(GetDotNotation(machine).getdotnotation(), encoding="utf-8")
+
+
+def mermaid_notation(machine: Machine) -> str:
+    """Mermaid ``stateDiagram-v2`` of the machine - generates the diagrams in docs/developer/architecture.md."""
+    lines = ["stateDiagram-v2", f"    [*] --> {machine._start_state.id.name}"]
+    for source, transitions in machine._transitions.items():
+        for event, transition in transitions.items():
+            label = event.name
+            timeout = machine._timeoutevents.get(source)
+            if timeout is not None and timeout[0] == event:
+                label += " (timeout)"
+            lines.append(f"    {source.name} --> {transition.targetstateid.name}: {label}")
+    return "\n".join(lines)
+
+
+class PeriodicTask:
+    """Calls ``action`` every ``interval`` seconds in its own thread until :meth:`stop` is called."""
+
+    def __init__(self, interval: float, action: Callable[[], object], name: str, logger: logging.Logger) -> None:
+        self._interval = interval
+        self._action = action
+        self._logger = logger
+        self._stop = threading.Event()
+        self._thread = threading.Thread(target=self._run, name=name, daemon=True)
+
+    def _run(self) -> None:
+        while not self._stop.wait(self._interval):
+            try:
+                self._action()
+            except Exception as error:
+                self._logger.exception("periodic task '%s' failed", self._thread.name)
+                unexpected.report(error, f"periodic task {self._thread.name}")
+
+    def start(self) -> None:
+        self._thread.start()
+
+    def stop(self) -> None:
+        """Stop and wait for a running action to finish (unless called by the action itself)."""
+        self._stop.set()
+        if self._thread.is_alive() and self._thread is not threading.current_thread():
+            self._thread.join()
+
+
+class PauseReason(Enum):
+    USER = "user"  # play/pause button (headset, web page, command line)
+    OUTPUT = "output"  # the headset has gone (out of range, switched off, empty battery)
+
+
+class OutputPause:
+    """Why and since when a playback is paused - only a pause caused by the loss of the headset is continued when the
+    headset comes back, and only within :data:`RESUME_WINDOW` seconds."""
+
+    def __init__(self, clock: Callable[[], float] = time.monotonic) -> None:
+        self._clock = clock
+        self.reason: PauseReason | None = None
+        self.since = 0.0
+
+    def paused(self, reason: PauseReason) -> None:
+        self.reason = reason
+        self.since = self._clock()
+
+    def resumes_on_output(self) -> bool:
+        """True if the headset that has come back continues the playback."""
+        return self.reason is PauseReason.OUTPUT and self._clock() - self.since <= RESUME_WINDOW