tinyjukebox 0.47.0__py3-none-any.whl

tinyjukebox/albumplayer/simpleplayer.py

@@ -0,0 +1,419 @@
+"""Player implementation with external processes: ffmpeg decodes, aplay (alsa-utils) plays."""
+
+import collections
+import logging
+import re
+import subprocess
+import threading
+from collections.abc import Callable
+from typing import IO
+
+from tinyjukebox.albumplayer.aalbumplayer import AAlbumPlayer, ATrack, TrackEndHook
+from tinyjukebox.albumplayer.clock import SYSTEM_CLOCK, Clock
+from tinyjukebox.albumplayer.player_interface import Hook
+from tinyjukebox.data.target import TargetAlbum
+
+__all__ = [
+    "STREAM_TIMEOUT",
+    "AudioOutput",
+    "AudioPipeline",
+    "SimplePlayer",
+    "SimpleTrack",
+    "bluealsa_device",
+    "decoder_command",
+    "output_command",
+]
+
+
+STREAM_TIMEOUT = 15.0
+"""Seconds without data from a stream until ffmpeg gives up (the radio player then connects again)."""
+CD_BYTES_PER_SECOND = 44100 * 2 * 2
+"""What ffmpeg writes to aplay per second of audio: 16 bit stereo pcm at 44.1 kHz."""
+
+
+def decoder_command(source: str, start_time: float = 0, stream: bool = False) -> list[str]:
+    """ffmpeg decodes the source to raw 16 bit stereo pcm (44.1 kHz) on stdout.
+
+    ``stream``: ``source`` is the url of an internet radio stream - no start time; ffmpeg reconnects after short
+    interruptions and gives up after :data:`STREAM_TIMEOUT` seconds without data.
+    """
+    if stream:
+        position = [
+            "-reconnect",
+            "1",
+            "-reconnect_streamed",
+            "1",
+            "-reconnect_delay_max",
+            "10",
+            "-rw_timeout",
+            str(round(STREAM_TIMEOUT * 1_000_000)),  # µs
+        ]
+    else:
+        position = ["-ss", str(start_time)]
+    return [
+        "ffmpeg",
+        "-nostdin",
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        *position,
+        "-i",
+        source,
+        "-vn",
+        "-f",
+        "s16le",
+        "-ac",
+        "2",
+        "-ar",
+        "44100",
+        "-",
+    ]
+
+
+def output_command(null_output: bool = False, buffer_time: float | None = None, device: str | None = None) -> list[str]:
+    """aplay plays raw pcm from stdin on ``device`` (``None``: the default device - the speaker) in cd format (16 bit
+    little endian, 44100 Hz, stereo).
+
+    ffmpeg's own alsa output ('-f alsa') can hang in ALSA and ignore SIGTERM - piping into aplay avoids that.
+    ``null_output`` (``--no-audio``): ffmpeg consumes the audio in real time and discards it - no sound card needed.
+    ``buffer_time``: alsa buffer of aplay in ms (``None``: aplay's default, usually 500 ms) - the sound starts once the
+    buffer is filled; a smaller buffer starts faster but tolerates shorter stalls of the decoder.
+    """
+    if null_output:
+        return [
+            "ffmpeg",
+            "-nostdin",
+            "-loglevel",
+            "error",
+            "-f",
+            "s16le",
+            "-ar",
+            "44100",
+            "-ac",
+            "2",
+            "-i",
+            "-",
+            "-af",
+            "arealtime",  # not '-re': since ffmpeg 6.1 it reads the first 0.5 s at once (readrate_initial_burst)
+            "-f",
+            "null",
+            "-",
+        ]
+    command = ["aplay", "-q", "-t", "raw", "-f", "cd"]
+    if device is not None:
+        command += ["-D", device]
+    if buffer_time is not None:
+        command.append(f"--buffer-time={round(buffer_time * 1000)}")  # µs
+    return command
+
+
+def bluealsa_device(address: str, volume: float | None = None) -> str:
+    """The alsa device of BlueALSA for the headset with the bluetooth ``address`` - always stereo (A2DP).
+
+    ``volume`` (%): set (and unmuted) when the device is opened, i.e. before the first sound - BlueALSA remembers
+    the volume a headset had the last time, and a volume set via the mixer may arrive a moment after the playback
+    has started."""
+    device = f"bluealsa:DEV={address},PROFILE=a2dp"
+    return device if volume is None else f"{device},VOL={round(volume)}+"
+
+
+class AudioOutput:
+    """Where the players play: the speaker (default alsa device) or the bluetooth headset - looked up whenever a
+    playback starts, so that a switch applies to the next playback.
+
+    ``headset``: a failing output means the headset has gone (the players pause instead of skipping the track).
+    """
+
+    def __init__(self, null_output: bool = False, buffer_time: float | None = None) -> None:
+        self._null_output = null_output
+        self._buffer_time = buffer_time
+        self._lock = threading.Lock()
+        self._device: Callable[[], str] | None = None
+        self._headset = False
+
+    def use_speaker(self) -> None:
+        with self._lock:
+            self._device, self._headset = None, False
+
+    def use_headset(self, device: Callable[[], str] | None) -> None:
+        """``device``: returns the alsa device of the headset - asked for every playback, it may carry the current
+        volume (``None``: the default device - the virtual headset)."""
+        with self._lock:
+            self._device, self._headset = device, True
+
+    @property
+    def headset(self) -> bool:
+        return self._headset
+
+    @property
+    def buffer_time(self) -> float | None:
+        """Milliseconds of aplay's buffer (``None``: aplay's default)."""
+        return self._buffer_time
+
+    def current(self) -> tuple[list[str], bool]:
+        """(output command, headset)"""
+        with self._lock:
+            device, headset = self._device, self._headset
+        return output_command(self._null_output, self._buffer_time, device() if device is not None else None), headset
+
+
+DECODER_ERROR_LINES = 10  # the last lines of the decoder's error output are kept for the log
+
+
+PROGRESS = re.compile(rb"[a-z_0-9.]+= *\S*")
+"""A line of ``ffmpeg -progress``: how far the decoder is - no message about the source."""
+UNDERRUN = re.compile(rb"!!! \([^0-9]*([0-9]+(?:[.,][0-9]+)?)")
+"""What aplay says when its buffer ran empty: the sound broke off for at least this long. In the language of the box -
+``underrun!!! (at least 12.345 ms long)``, ``Unterlauf!!! (mindestens 12,345 ms)`` - so only its form is matched."""
+
+
+def _read_tail(stream: IO[bytes], tail: collections.deque[bytes], watch: Callable[[bytes], bool] | None = None) -> None:
+    """Keep the last lines of ``stream``; ``watch(line)`` sees every line first - True: it is no message to keep."""
+    with stream:
+        for line in stream:
+            if watch is None or not watch(line):
+                tail.append(line)
+
+
+class AudioPipeline:
+    """``ffmpeg | aplay`` - started by the constructor, stopped by :meth:`stop`; :meth:`wait` blocks until the
+    playback has ended (``stream``: see :func:`decoder_command`)."""
+
+    def __init__(
+        self,
+        source: str,
+        start_time: float = 0,
+        output: list[str] | None = None,
+        stream: bool = False,
+        on_output: Callable[[], None] | None = None,
+        on_underrun: Callable[[float], None] | None = None,
+        on_heard: Callable[[], None] | None = None,
+        heard_after: float = 0,
+    ) -> None:
+        """``on_output()``: the decoder has produced its first audio; ``on_underrun(ms)``: the sound broke off;
+        ``on_heard()``: the decoder has produced ``heard_after`` seconds of audio - aplay's buffer is full, and aplay
+        plays once it is full. All from a thread of the pipeline, for the radio (docs/developer/library.md, section
+        4.22)."""
+        command = decoder_command(source, start_time, stream)
+        progress = on_output is not None or on_heard is not None
+        if progress:  # ffmpeg says four times a second how much it has decoded
+            command[1:1] = ["-progress", "pipe:2", "-stats_period", "0.25"]
+        self._on_output = on_output
+        self._on_heard = on_heard
+        self._heard_bytes = max(1, round(heard_after * CD_BYTES_PER_SECOND))
+        self._on_underrun = on_underrun
+        self._decoder = subprocess.Popen(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
+        assert self._decoder.stdout is not None  # noqa: S101 - stdout=PIPE
+        assert self._decoder.stderr is not None  # noqa: S101 - stderr=PIPE
+        try:
+            self._output = subprocess.Popen(
+                output or output_command(),
+                stdin=self._decoder.stdout,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.PIPE,
+            )
+        except OSError:
+            # e.g. aplay not installed - do not leave the decoder running
+            self._decoder.kill()
+            self._decoder.communicate()
+            raise
+        # close our copy - the decoder gets SIGPIPE if the output process exits
+        self._decoder.stdout.close()
+        # ffmpeg logs every broken frame of a damaged file: its error output is read all the time - a full pipe would
+        # block the decoder and thus the playback forever. The thread ends when the decoder has ended.
+        self._decoder_errors: collections.deque[bytes] = collections.deque(maxlen=DECODER_ERROR_LINES)
+        self._decoder_reader = threading.Thread(
+            target=_read_tail,
+            args=(self._decoder.stderr, self._decoder_errors, self._progress if progress else None),
+            name="AudioPipeline.decoder_errors",
+            daemon=True,
+        )
+        self._decoder_reader.start()
+        # the stderr pipe of the output is read and closed by wait() - or by stop() if nobody waits. To hear of every
+        # underrun at once, a thread of its own reads it and closes it at its end
+        self._pipes_lock = threading.Lock()
+        self._pipes_owned_by_wait = False
+        self._pipes_closed = False
+        self._output_errors: collections.deque[bytes] = collections.deque(maxlen=DECODER_ERROR_LINES)
+        self._output_reader: threading.Thread | None = None
+        if on_underrun is not None:
+            assert self._output.stderr is not None  # noqa: S101 - stderr=PIPE
+            self._pipes_owned_by_wait = True
+            self._output_reader = threading.Thread(
+                target=_read_tail,
+                args=(self._output.stderr, self._output_errors, self._underrun),
+                name="AudioPipeline.output_errors",
+                daemon=True,
+            )
+            self._output_reader.start()
+
+    def _progress(self, line: bytes) -> bool:
+        if not PROGRESS.fullmatch(line.strip()):
+            return False
+        key, _, value = line.strip().partition(b"=")
+        if key != b"total_size" or not value.isdigit():
+            return True
+        size = int(value)
+        if size > 0 and self._on_output is not None:
+            on_output, self._on_output = self._on_output, None  # the first audio only
+            on_output()
+        if size >= self._heard_bytes and self._on_heard is not None:
+            on_heard, self._on_heard = self._on_heard, None
+            on_heard()
+        return True
+
+    def _underrun(self, line: bytes) -> bool:
+        found = UNDERRUN.search(line)
+        if found is None:
+            return False
+        if self._on_underrun is not None:
+            self._on_underrun(float(found.group(1).replace(b",", b".")))
+        return True
+
+    @property
+    def output_failed(self) -> bool:
+        """True if the output process has ended with an error (after :meth:`wait`)."""
+        return self._output.returncode not in (0, None)
+
+    @property
+    def decoder_errors(self) -> str:
+        """What the decoder said about a source that it could not decode as it is - its last lines; empty for a
+        source without a fault (after :meth:`wait`).
+
+        ffmpeg plays on through the broken parts of a damaged file and ends without an error: what it logs is the only
+        sign, and it logs nothing for a sound file. If the output failed, the decoder ended because nobody took what
+        it decoded - that says nothing about the source."""
+        if self._output.returncode != 0 or self._decoder.returncode is None:
+            return ""
+        said = b"".join(self._decoder_errors).decode("utf-8", errors="replace").strip()
+        if not said and self._decoder.returncode != 0:
+            said = f"the decoder ended with status {self._decoder.returncode}"
+        return said
+
+    def wait(self) -> tuple[bool, str]:
+        """Wait for the end of the playback - returns (success, error messages)."""
+        if self._output_reader is not None:
+            self._output.wait()
+            self._output_reader.join()
+            output_err = b"".join(self._output_errors)
+        else:
+            with self._pipes_lock:
+                if self._pipes_closed:
+                    return False, "stopped"
+                self._pipes_owned_by_wait = True
+            _, output_err = self._output.communicate()
+        self._decoder.wait()
+        self._decoder_reader.join()
+        decoder_err = b"".join(self._decoder_errors)
+        errors = [e.decode("utf-8", errors="replace").strip() for e in (decoder_err, output_err) if e]
+        success = self._decoder.returncode == 0 and self._output.returncode == 0
+        return success, "; ".join(e for e in errors if e)
+
+    def stop(self, timeout: float = 2.0) -> None:
+        """Terminate both processes; a process that ignores SIGTERM for ``timeout`` seconds is killed."""
+        # stop the output first -> sound stops immediately
+        for process in (self._output, self._decoder):
+            if process.poll() is None:
+                process.terminate()
+        for process in (self._output, self._decoder):
+            try:
+                process.wait(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+        with self._pipes_lock:
+            if not self._pipes_owned_by_wait and not self._pipes_closed:
+                self._pipes_closed = True
+                if self._output.stderr is not None:
+                    self._output.stderr.close()
+
+
+class SimpleTrack(ATrack):
+    """Plays one mp3 file with an :class:`AudioPipeline`; a monitor thread waits for the end of the playback."""
+
+    def __init__(
+        self,
+        filename: str | None,
+        logger: logging.Logger,
+        end_of_track_hook: TrackEndHook,
+        start_time: float = 0,
+        clock: Clock = SYSTEM_CLOCK,
+        null_output: bool = False,
+        on_play: Callable[[], None] | None = None,
+        buffer_time: float | None = None,
+        output: AudioOutput | None = None,
+    ) -> None:
+        """``output``: where to play (default: the speaker - ``null_output``/``buffer_time`` apply only then)."""
+        super().__init__(filename, logger, end_of_track_hook, start_time, clock)
+        self._output = output or AudioOutput(null_output, buffer_time)
+        self._pipeline: AudioPipeline | None = None
+        self._pipeline_lock = threading.Lock()  # the monitor thread and play/stop exchange the pipeline under it
+        self._on_play = on_play
+
+    def _play(self, play_id: int) -> None:
+        command, headset = self._output.current()
+        pipeline = AudioPipeline(self.filename, self._start_time, command)
+        with self._pipeline_lock:
+            self._pipeline = pipeline
+        if self._on_play is not None:
+            self._on_play()
+        threading.Thread(
+            target=self._monitor_playback, args=(pipeline, play_id, headset), name="SimpleTrack.monitor", daemon=True
+        ).start()
+
+    def _monitor_playback(self, pipeline: AudioPipeline, play_id: int, headset: bool) -> None:
+        success, errors = pipeline.wait()
+        with self._pipeline_lock:
+            if pipeline is not self._pipeline:
+                return  # stopped via stop() or replaced by a new pipeline
+            self._pipeline = None
+        if not success and headset and pipeline.output_failed:
+            # the headset has gone - the track has not been played to its end
+            self._logger.error("headset output failed for %s: %s", self.filename, errors)
+            self._output_lost(play_id)
+            return
+        if not success:
+            self._logger.error("playback failed for %s: %s", self.filename, errors)
+        damage = pipeline.decoder_errors
+        if damage:
+            if success:
+                self._logger.warning("%s is damaged: %s", self.filename, damage)
+            if self.failed_hook is not None:
+                self.failed_hook(damage)
+        self._end_of_track(play_id)
+
+    def _stop(self) -> None:
+        with self._pipeline_lock:
+            pipeline, self._pipeline = self._pipeline, None
+        if pipeline is not None:
+            pipeline.stop()
+
+
+class SimplePlayer(AAlbumPlayer):
+    """Album player with ffmpeg and aplay (``null_output``: no sound card, see :func:`output_command`).
+
+    ``on_play`` is called whenever ffmpeg has been started for a track.
+    """
+
+    def __init__(
+        self,
+        logger: logging.Logger,
+        album: TargetAlbum,
+        end_of_track_hook: Hook,
+        end_of_album_hook: Hook,
+        null_output: bool = False,
+        clock: Clock = SYSTEM_CLOCK,
+        on_play: Callable[[], None] | None = None,
+        buffer_time: float | None = None,
+        output: AudioOutput | None = None,
+    ) -> None:
+        """``output``: where to play (default: the speaker - ``null_output``/``buffer_time`` apply only then)."""
+        self._output = output or AudioOutput(null_output, buffer_time)
+        self._clock = clock
+        self._on_play = on_play
+        super().__init__(logger, album, end_of_track_hook, end_of_album_hook)
+
+    def _create_track(self, filename: str, end_of_track_hook: TrackEndHook) -> SimpleTrack:
+        return SimpleTrack(
+            filename, self._logger, end_of_track_hook, clock=self._clock, on_play=self._on_play, output=self._output
+        )