🎉 | Project added

player.py

@@ -0,0 +1,864 @@
+"""Audio player using QMediaPlayer + yt-dlp with queue and local-file playback.
+
+Instead of streaming YouTube audio URLs directly (which expire within seconds
+and cause "Connection reset by peer" / "Demuxing failed" errors), we download
+each song to a temporary file and play from the local filesystem.  This is
+reliable because QMediaPlayer never touches the network directly.
+
+Architecture
+------------
+A single persistent ``DownloadWorker`` lives on a background ``QThread`` for
+the entire player lifetime.  Work is sent via Qt signals — no thread
+creation/teardown, no signal-disconnect dances, no ``quit()``/``wait()``
+timeouts.  Every download is tagged with a monotonically-increasing
+``task_id``; stale results (from superseded requests) are simply discarded.
+
+State machine::
+
+    IDLE ──▶ LOADING ──▶ READY ──▶ PLAYING ──▶ ENDED
+     ▲          │           │          │  ▲        │
+     │          ▼           │          │  │        │
+     │        FAILED ───────┘          ▼  │        │
+     └───────────────────────────────── PAUSED     │
+                                      │  ▲        │
+                                      └──┘        │
+                                                  │
+                                    (queue empty)─┘
+
+Set ``TEST_MODE = True`` below to bypass yt-dlp and generate a short test-tone
+WAV instead — useful for UI development without network access.
+"""
+
+import logging
+import os
+import struct
+import tempfile
+import atexit
+import math
+import shutil
+import threading
+from typing import Optional
+
+import yt_dlp
+from PySide6.QtCore import QObject, QThread, Signal, Slot, QUrl
+from PySide6.QtMultimedia import QMediaPlayer, QAudioOutput
+
+log = logging.getLogger("tunetti.player")
+
+# ── User-settable flags ────────────────────────────────────────────────────
+TEST_MODE: bool = False    # skip yt-dlp, use local test-tone WAV instead
+VERBOSE:   bool = False    # enable yt-dlp debug output
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Temp-file housekeeping
+# ═══════════════════════════════════════════════════════════════════════════════
+
+_TUNETTI_TMP: str | None = None
+
+
+def _tmp_dir() -> str:
+    """Return a scoped temp directory that lives for the process lifetime."""
+    global _TUNETTI_TMP
+    if _TUNETTI_TMP is None:
+        _TUNETTI_TMP = tempfile.mkdtemp(prefix="tunetti_")
+        atexit.register(shutil.rmtree, _TUNETTI_TMP, ignore_errors=True)
+    return _TUNETTI_TMP
+
+
+def _stale_files(video_id: str) -> list[str]:
+    """Return paths of existing non-temp files for *video_id*, newest first."""
+    td = _tmp_dir()
+    result = []
+    for fn in os.listdir(td):
+        if fn.startswith(video_id) and ".temp." not in fn:
+            path = os.path.join(td, fn)
+            if os.path.isfile(path) and os.path.getsize(path) > 0:
+                result.append(path)
+    result.sort(key=lambda p: os.path.getmtime(p), reverse=True)
+    return result
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Test-tone generator (used when TEST_MODE = True)
+# ═══════════════════════════════════════════════════════════════════════════════
+
+def _generate_test_wav(path: str, duration_s: int = 15) -> None:
+    """Write a 440 Hz sine wave to *path* as a 16-bit mono WAV file."""
+    sample_rate = 44100
+    num_samples = sample_rate * duration_s
+    frequency = 440.0
+    amplitude = 0.3
+
+    with open(path, "wb") as f:
+        data_size = num_samples * 2
+        f.write(b"RIFF")
+        f.write(struct.pack("<I", 36 + data_size))
+        f.write(b"WAVE")
+        f.write(b"fmt ")
+        f.write(struct.pack("<I", 16))
+        f.write(struct.pack("<H", 1))
+        f.write(struct.pack("<H", 1))
+        f.write(struct.pack("<I", sample_rate))
+        f.write(struct.pack("<I", sample_rate * 2))
+        f.write(struct.pack("<H", 2))
+        f.write(struct.pack("<H", 16))
+        f.write(b"data")
+        f.write(struct.pack("<I", data_size))
+        for i in range(num_samples):
+            t = i / sample_rate
+            sample = int(amplitude * math.sin(2 * math.pi * frequency * t) * 32767)
+            f.write(struct.pack("<h", sample))
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Download worker — lives on a single persistent QThread
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class DownloadWorker(QObject):
+    """Downloads song audio to temporary files via yt-dlp.
+
+    Lives on a *persistent* background ``QThread`` that is created once
+    when the ``AudioPlayer`` is initialised and never torn down until
+    shutdown.  This avoids all the fragile ``quit()``/``wait()``/signal-
+    disconnect races that plagued the previous design.
+
+    Work is requested via :attr:`download_requested` and cancellation is
+    signalled via :attr:`cancel_requested`.  Results are delivered on the
+    main thread via :attr:`download_finished`.
+    """
+
+    # ── Input (main thread → worker thread, queued connection) ──────────
+    download_requested = Signal(int, dict)   # task_id, song dict
+    cancel_requested   = Signal()            # discard current download
+
+    # ── Output (worker thread → main thread, queued connection) ─────────
+    download_succeeded = Signal(int, dict)  # task_id, resolved song dict
+    download_failed    = Signal(int)        # task_id
+
+    def __init__(self, parent: Optional[QObject] = None):
+        super().__init__(parent)
+        self._lock = threading.Lock()
+        self._cancelled = False
+        self._task_id: Optional[int] = None
+
+    @Slot(int, dict)
+    def _do_download(self, task_id: int, song: dict) -> None:
+        """Entry point — invoked on the worker thread."""
+        self._task_id = task_id
+        self._cancelled = False
+
+        video_id = song.get("videoId") or song.get("video_id", "")
+        temp_path: Optional[str] = None
+
+        try:
+            # Keep the stale cleanup at the start of each new download.
+            for stale in _stale_files(video_id):
+                try:
+                    os.unlink(stale)
+                except OSError:
+                    pass
+
+            # ── TEST MODE ────────────────────────────────────────────
+            if TEST_MODE:
+                wav_path = os.path.join(_tmp_dir(), f"{video_id}.wav")
+                _generate_test_wav(wav_path)
+                resolved = dict(song)
+                resolved["_local_path"] = wav_path
+                resolved["duration"] = 15
+                resolved["thumbnail"] = ""
+                resolved["title"] = song.get("title", f"Test {video_id}")
+                with self._lock:
+                    if not self._cancelled:
+                        self.download_succeeded.emit(task_id, resolved)
+                return
+
+            # ── Real download ────────────────────────────────────────
+            tmpl = os.path.join(_tmp_dir(), f"{video_id}.%(ext)s")
+            ydl_opts: dict = {
+                "quiet": not VERBOSE,
+                "no_warnings": not VERBOSE,
+                "verbose": VERBOSE,
+                "format": "worstaudio/worst",
+                "outtmpl": tmpl,
+                "noprogress": not VERBOSE,
+                "extract_flat": False,
+            }
+
+            with yt_dlp.YoutubeDL(ydl_opts) as ydl:
+                info = ydl.extract_info(
+                    f"https://music.youtube.com/watch?v={video_id}",
+                    download=True,
+                )
+
+            # Construct the expected path from the output template.
+            # The outtmpl is <tmp_dir>/<video_id>.%(ext)s and yt-dlp resolves
+            # %(ext)s from the downloaded format.  We avoid relying on
+            # info["requested_downloads"][0]["filepath"] because that key
+            # may be set *before* post-processor fixup renames the file.
+            actual_ext = info.get("ext", "")
+            expected_path = os.path.join(_tmp_dir(), f"{video_id}.{actual_ext}") if actual_ext else ""
+
+            temp_path = self._resolve_temp_path(video_id, expected_path)
+            if not temp_path:
+                raise RuntimeError(
+                    f"Download produced empty/missing file for {video_id}"
+                )
+
+            resolved = self._build_resolved_dict(song, info, temp_path)
+
+            with self._lock:
+                if not self._cancelled:
+                    self.download_succeeded.emit(task_id, resolved)
+
+        except Exception as exc:
+            log.error("Download error for %s: %s", video_id, exc)
+            self._cleanup_path(temp_path)
+            with self._lock:
+                if not self._cancelled:
+                    self.download_failed.emit(task_id)
+
+    def _resolve_temp_path(self, video_id: str, expected_path: str) -> Optional[str]:
+        """Resolve the actual temp file path after a download.
+
+        First checks the *expected_path* (built from the extension yt-dlp reported),
+        then falls back to scanning the temp directory for stale files.
+        """
+        # Debug: list every file in the temp dir for this video_id
+        td = _tmp_dir()
+        try:
+            all_matches = [
+                (fn, os.path.getsize(os.path.join(td, fn)))
+                for fn in os.listdir(td)
+                if fn.startswith(video_id)
+            ]
+            all_matches.sort()
+            log.debug("Temp files for %s: %s", video_id, all_matches)
+        except OSError as exc:
+            log.debug("Temp dir listing failed: %s", exc)
+
+        if expected_path:
+            log.debug("Checking expected path: %s", expected_path)
+        if expected_path and os.path.isfile(expected_path) and os.path.getsize(expected_path) > 0:
+            return expected_path
+
+        # Fallback: scan the temp directory for the most recent valid file.
+        candidates = _stale_files(video_id)
+        log.debug("_stale_files fallback for %s: %s", video_id, candidates)
+        if candidates:
+            return candidates[0]
+
+        return None
+
+    @staticmethod
+    def _build_resolved_dict(song: dict, info: dict, temp_path: str) -> dict:
+        """Build the resolved song dict with local path and metadata."""
+        resolved = dict(song)
+        resolved["_local_path"] = temp_path
+        resolved["duration"] = info.get("duration") or song.get("duration", 0)
+        resolved["thumbnail"] = info.get("thumbnail") or song.get("thumbnail", "")
+        resolved["title"] = info.get("title", song.get("title", ""))
+        return resolved
+
+    @Slot()
+    def _do_cancel(self) -> None:
+        """Mark the current download as cancelled."""
+        with self._lock:
+            self._cancelled = True
+
+    @staticmethod
+    def _cleanup_path(path: Optional[str]) -> None:
+        if path and os.path.isfile(path):
+            try:
+                os.unlink(path)
+            except OSError:
+                pass
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Search worker
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class SearchWorker(QObject):
+    """Runs a ytmusicapi search in a background thread.
+
+    Searches both songs and videos, returning categorised results
+    as a dict with ``"songs"`` and ``"videos"`` keys each containing
+    a list of normalised song dicts.
+    """
+
+    results_ready = Signal(dict)
+    failed        = Signal(str)
+
+    def __init__(self, query: str):
+        super().__init__()
+        self._query = query
+
+    @Slot()
+    def run(self) -> None:
+        if TEST_MODE:
+            dummy = [
+                {"videoId": f"dummy_{i}", "title": f"Test Song {i}",
+                 "artists": [{"name": f"Artist {i}"}],
+                 "album": None, "duration_seconds": 15,
+                 "duration": "0:15", "thumbnails": [],
+                 "videoType": "MUSIC_VIDEO_TYPE_ATV",
+                 "resultType": "song"}
+                for i in range(5)
+            ]
+            self.results_ready.emit({"songs": dummy, "videos": []})
+            return
+
+        from ytmusicapi import YTMusic
+        try:
+            yt = YTMusic()
+            # Always search both categories so the UI can display them
+            # side by side with a "Videos" and "Songs" header.
+            raw_songs = yt.search(self._query, filter="songs", limit=20)
+            raw_videos = yt.search(self._query, filter="videos", limit=20)
+
+            songs = [
+                _build_song_dict(r) for r in raw_songs if r.get("videoId")
+            ]
+            videos = [
+                _build_song_dict(r) for r in raw_videos if r.get("videoId")
+            ]
+            self.results_ready.emit({"songs": songs, "videos": videos})
+        except Exception as exc:
+            log.error("Search failed: %s", exc)
+            self.failed.emit(str(exc))
+
+
+# ═══════════════════════════════════════════════════════════════════════════════
+# Main AudioPlayer
+# ═══════════════════════════════════════════════════════════════════════════════
+
+class AudioPlayer(QObject):
+    """QObject-based audio player wrapping QMediaPlayer with local-file playback.
+
+    Every song is downloaded to a temporary file before playing.  A single
+    persistent ``DownloadWorker`` on a background ``QThread`` handles all
+    downloads — no thread creation/teardown, no signal-disconnect races, no
+    ``quit()``/``wait()`` timeouts.
+
+    Signals
+    -------
+    loading(video_id)
+    song_started(song_dict)
+    song_ended(video_id)
+    paused(song_dict)
+    resumed(song_dict)
+    error(dict)
+    position_changed(ms: int)
+    duration_changed(ms: int)
+    playback_state_changed(state: str)  — "playing"|"paused"|"stopped"
+    """
+
+    loading               = Signal(str)
+    song_started          = Signal(dict)
+    song_ended            = Signal(str)
+    paused                = Signal(dict)
+    resumed               = Signal(dict)
+    error                 = Signal(dict)
+    position_changed      = Signal(int)
+    duration_changed      = Signal(int)
+    playback_state_changed = Signal(str)
+    seeked                = Signal(int)  # position_ms after seek
+
+    def __init__(self, parent: Optional[QObject] = None):
+        super().__init__(parent)
+
+        # ── QMediaPlayer ──────────────────────────────────────────────
+        self._player = QMediaPlayer(self)
+        self._audio_output = QAudioOutput(self)
+        self._player.setAudioOutput(self._audio_output)
+        self._audio_output.setVolume(0.5)
+
+        self._player.mediaStatusChanged.connect(self._on_media_status)
+        self._player.positionChanged.connect(self._on_position)
+        self._player.durationChanged.connect(self._on_duration)
+        self._player.playbackStateChanged.connect(self._on_playback_state)
+        self._player.errorOccurred.connect(self._on_player_error_occurred)
+
+        # ── Queue & state ─────────────────────────────────────────────
+        self._queue: list[dict] = []
+        self._current: Optional[dict] = None
+        self._loop_mode = False
+
+        # ── Download worker (single persistent thread) ────────────────
+        self._next_task_id = 0
+        # The task ID that is "current" — results with other IDs are stale.
+        self._active_task_id: Optional[int] = None
+        # The task ID of the in-progress prefetch (if any).
+        self._prefetch_task_id: Optional[int] = None
+        # Cache of prefetched results: video_id → resolved dict with _local_path.
+        self._prefetch_cache: dict[str, dict] = {}
+
+        self._worker_thread = QThread(self)
+        self._worker = DownloadWorker()
+        self._worker.moveToThread(self._worker_thread)
+
+        # Connect worker signals (cross-thread → queued delivery).
+        self._worker.download_requested.connect(self._worker._do_download)
+        self._worker.cancel_requested.connect(self._worker._do_cancel)
+        self._worker.download_succeeded.connect(self._on_download_succeeded)
+        self._worker.download_failed.connect(self._on_download_failed)
+        self._worker_thread.start()
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # Public API
+    # ═══════════════════════════════════════════════════════════════════════
+
+    # ── Volume ──────────────────────────────────────────────────────────────
+
+    def set_volume(self, percent: int) -> None:
+        self._audio_output.setVolume(max(0, min(100, percent)) / 100.0)
+
+    def volume(self) -> int:
+        return int(self._audio_output.volume() * 100)
+
+    # ── Seek ────────────────────────────────────────────────────────────────
+
+    def seek(self, ms: int) -> None:
+        self._player.setPosition(max(0, ms))
+        self.seeked.emit(max(0, ms))
+
+    # ── Play / Queue ────────────────────────────────────────────────────────
+
+    def play(self, song: dict) -> None:
+        """Clear the queue and play *song* immediately."""
+        self._cleanup_temp_files()
+        self._queue.clear()
+        self._prefetch_cache.clear()
+        self._loop_mode = False
+        self._request_download(song)
+
+    def queue_song(self, song: dict) -> None:
+        self._queue.append(song)
+        if self._current is None and self._active_task_id is None:
+            self._pop_and_play()
+
+    def queue_next(self, song: dict) -> None:
+        """Insert *song* to play immediately after the current one."""
+        self._queue.insert(0, song)
+
+    def queue_list(self, songs: list[dict]) -> None:
+        self._queue.extend(songs)
+
+    def skip(self) -> None:
+        """Skip to the next song."""
+        # Cancel any in-progress download (the skip is our new intent).
+        self._cancel_active_downloads()
+        self._player.stop()
+        self._advance()
+
+    def stop_playback(self) -> None:
+        """Soft stop: halt playback, clear queue, cancel downloads."""
+        self._cancel_active_downloads()
+        self._cleanup_temp_files()
+        self._queue.clear()
+        self._prefetch_cache.clear()
+        self._loop_mode = False
+        self._current = None
+        self._player.stop()
+        self.playback_state_changed.emit("stopped")
+
+    @Slot()
+    def _pop_and_play(self) -> None:
+        """Pop the next song from the queue and start downloading it.
+
+        If it was already prefetched, the download is instant (already cached).
+        """
+        if not self._queue:
+            return
+        song = self._queue.pop(0)
+        vid = song.get("videoId") or song.get("video_id", "")
+        cached = self._prefetch_cache.pop(vid, None)
+        if cached is not None:
+            # Prefetched — play directly without downloading.
+            self._start_playback(cached)
+        else:
+            self._request_download(song)
+
+    # ── Pause / Resume ──────────────────────────────────────────────────────
+
+    def pause(self) -> None:
+        if self._player.playbackState() == QMediaPlayer.PlaybackState.PlayingState:
+            self._player.pause()
+
+    def resume(self) -> None:
+        if self._player.playbackState() == QMediaPlayer.PlaybackState.PausedState:
+            self._player.play()
+
+    def toggle_pause(self) -> bool:
+        state = self._player.playbackState()
+        if state == QMediaPlayer.PlaybackState.PlayingState:
+            self._player.pause()
+            return True
+        elif state == QMediaPlayer.PlaybackState.PausedState:
+            self._player.play()
+            return False
+        return False
+
+    def is_paused(self) -> bool:
+        return self._player.playbackState() == QMediaPlayer.PlaybackState.PausedState
+
+    def is_playing(self) -> bool:
+        return self._player.playbackState() == QMediaPlayer.PlaybackState.PlayingState
+
+    def is_stopped(self) -> bool:
+        return self._player.playbackState() == QMediaPlayer.PlaybackState.StoppedState
+
+    # ── Queue introspection ────────────────────────────────────────────────
+
+    def get_current(self) -> Optional[dict]:
+        return self._current
+
+    def get_queue(self) -> list[dict]:
+        return list(self._queue)
+
+    def get_queue_length(self) -> int:
+        return len(self._queue)
+
+    def get_loop(self) -> bool:
+        return self._loop_mode
+
+    def set_loop(self, enabled: bool) -> None:
+        self._loop_mode = enabled
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # Download lifecycle
+    # ═══════════════════════════════════════════════════════════════════════
+
+    def _request_download(self, song: dict) -> None:
+        """Request a download via the persistent worker.
+
+        Cancels any in-progress download and prefetch first, then assigns a
+        fresh task ID and emits the request signal.
+        """
+        vid = song.get("videoId") or song.get("video_id", "")
+
+        # Guard: don't re-download what's already playing.
+        current_vid = (
+            (self._current or {}).get("videoId")
+            or (self._current or {}).get("video_id", "")
+        )
+        if vid and vid == current_vid:
+            log.debug("Ignoring duplicate download request for %s", vid)
+            return
+
+        # Fast path: already has a local file (e.g. from prefetch cache).
+        if song.get("_local_path"):
+            self._start_playback(song)
+            return
+
+        # Cancel any in-flight work — this is a new intent.
+        self._cancel_active_downloads()
+
+        task_id = self._next_task_id
+        self._next_task_id += 1
+        self._active_task_id = task_id
+
+        self.loading.emit(vid)
+        self._worker.download_requested.emit(task_id, song)
+
+    def _cancel_active_downloads(self) -> None:
+        """Tell the worker to discard its current work and forget about it."""
+        if self._active_task_id is not None or self._prefetch_task_id is not None:
+            self._worker.cancel_requested.emit()
+        self._active_task_id = None
+        self._prefetch_task_id = None
+
+    @Slot(int, dict)
+    def _on_download_succeeded(self, task_id: int, song: dict) -> None:
+        """Called on the main thread when a download succeeds.
+
+        Checks *task_id* against ``_active_task_id`` and ``_prefetch_task_id``
+        to discard stale results from superseded requests.
+        """
+        log.debug("Download succeeded: task_id=%d, active=%s, prefetch=%s",
+                   task_id, self._active_task_id, self._prefetch_task_id)
+
+        # ── Stale check for active download ──────────────────────────
+        if task_id == self._active_task_id:
+            self._active_task_id = None
+
+            local_path = song.get("_local_path")
+            if not local_path or not os.path.isfile(local_path):
+                log.error("Download succeeded but file missing: %s", local_path)
+                self.error.emit({
+                    "video_id": song.get("videoId", ""),
+                    "error": "Downloaded file went missing",
+                })
+                self._try_next_song()
+                return
+
+            self._start_playback(song)
+            return
+
+        # ── Stale check for prefetch download ────────────────────────
+        if task_id == self._prefetch_task_id:
+            self._prefetch_task_id = None
+
+            vid = song.get("videoId") or song.get("video_id", "")
+            # Only cache if the song is still in the active queue.
+            if any(
+                (s.get("videoId") or s.get("video_id", "")) == vid
+                for s in self._queue
+            ):
+                log.debug("Caching prefetched result for %s (task %d)", vid, task_id)
+                self._prefetch_cache[vid] = song
+            else:
+                log.debug("Prefetched %s no longer in queue, discarding", vid)
+            return
+
+        # ── Otherwise: truly stale — discard ────────────────────────────
+        log.debug("Discarding stale download result for task %d (task_id=%d, active=%s, prefetch=%s)",
+                   task_id, task_id, self._active_task_id, self._prefetch_task_id)
+
+    @Slot(int)
+    def _on_download_failed(self, task_id: int) -> None:
+        """Called on the main thread when a download fails."""
+        log.debug("Download failed: task_id=%d, active=%s, prefetch=%s",
+                   task_id, self._active_task_id, self._prefetch_task_id)
+
+        if task_id == self._active_task_id:
+            self._active_task_id = None
+            log.warning("Download failed for task %d", task_id)
+            self.error.emit({
+                "video_id": "",
+                "error": "Failed to resolve audio URL",
+            })
+            self._try_next_song()
+        elif task_id == self._prefetch_task_id:
+            self._prefetch_task_id = None
+            log.debug("Prefetch failed for task %d (harmless)", task_id)
+        else:
+            log.debug("Ignoring stale download failure for task %d", task_id)
+
+    # ── Playback ───────────────────────────────────────────────────────
+
+    def _start_playback(self, song: dict) -> None:
+        """Begin playing a resolved song (already has ``_local_path``).
+
+        Always called on the main thread.
+        """
+        # Remove the previous song's temp file BEFORE updating _current.
+        self._cleanup_current_temp()
+
+        local_path = song.get("_local_path", "")
+        log.debug("Starting playback: path=%s, exists=%s, size=%s",
+                   local_path,
+                   os.path.isfile(local_path) if local_path else "N/A",
+                   os.path.getsize(local_path) if local_path and os.path.isfile(local_path) else "N/A")
+
+        self._player.stop()
+        self._current = song
+
+        self._player.setSource(QUrl.fromLocalFile(local_path))
+        self._player.play()
+        self.song_started.emit(song)
+
+        # Kick off prefetch for the next queued song.
+        self._start_prefetch()
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # End-of-song handling
+    # ═══════════════════════════════════════════════════════════════════════
+
+    def _on_media_status(self, status: QMediaPlayer.MediaStatus) -> None:
+        if status == QMediaPlayer.MediaStatus.EndOfMedia:
+            self._advance()
+        elif status == QMediaPlayer.MediaStatus.InvalidMedia:
+            if self._current is None:
+                return
+            if self._player.playbackState() == QMediaPlayer.PlaybackState.StoppedState:
+                return
+            self.error.emit({
+                "video_id": (self._current or {}).get("videoId", ""),
+                "error": "Invalid media",
+            })
+            # Don't call _advance here — the player will go to stopped state,
+            # and _on_playback_state will handle advancing if appropriate.
+            # But let's advance immediately for invalid media.
+            self._advance()
+
+    def _advance(self) -> None:
+        """Move to the next song (or stop if the queue is empty).
+
+        This is the single exit point from an actively-playing song.
+        It handles loop re-queuing, song_ended emission, and queue popping.
+        """
+        if self._current is None:
+            return
+
+        finished_song = self._current
+        finished_vid = finished_song.get("videoId") or finished_song.get(
+            "video_id", ""
+        )
+        self._current = None
+
+        self.song_ended.emit(finished_vid)
+
+        # Re-queue for loop mode.
+        if self._loop_mode:
+            self._queue.insert(0, finished_song)
+
+        self._try_next_song()
+
+    def _try_next_song(self) -> None:
+        """Attempt to play the next song, or stop if the queue is empty."""
+        if self._queue:
+            self._pop_and_play()
+        else:
+            self.playback_state_changed.emit("stopped")
+
+    # ── Position / duration / state ────────────────────────────────────
+
+    @Slot(int)
+    def _on_position(self, ms: int) -> None:
+        self.position_changed.emit(ms)
+
+    @Slot(int)
+    def _on_duration(self, ms: int) -> None:
+        self.duration_changed.emit(ms)
+
+    @Slot(QMediaPlayer.PlaybackState)
+    def _on_playback_state(self, state: QMediaPlayer.PlaybackState) -> None:
+        if state == QMediaPlayer.PlaybackState.PlayingState:
+            self.playback_state_changed.emit("playing")
+            if self._current:
+                self.resumed.emit(self._current)
+        elif state == QMediaPlayer.PlaybackState.PausedState:
+            self.playback_state_changed.emit("paused")
+            if self._current:
+                self.paused.emit(self._current)
+        else:
+            self.playback_state_changed.emit("stopped")
+
+    # ── errorOccurred handler ─────────────────────────────────────────
+
+    @Slot(QMediaPlayer.Error, str)
+    def _on_player_error_occurred(
+        self, error: QMediaPlayer.Error, error_string: str
+    ) -> None:
+        """Handle QMediaPlayer error signals."""
+        if error in (QMediaPlayer.Error.NetworkError, QMediaPlayer.Error.ResourceError):
+            vid = (self._current or {}).get("videoId", "")
+            log.warning("Player error (%s): %s — advancing", error, error_string)
+            self.error.emit({
+                "video_id": vid,
+                "error": f"{error_string} (local file issue)",
+            })
+            self._advance()
+
+    # ── Prefetch ──────────────────────────────────────────────────────────────
+
+    def _start_prefetch(self) -> None:
+        """Request a download of the next queued song (if any).
+
+        Called after playback of the current song starts.  Uses the same
+        persistent worker — no separate thread needed.
+        """
+        if not self._queue:
+            return
+
+        next_song = self._queue[0]
+        vid = next_song.get("videoId") or next_song.get("video_id", "")
+
+        # Already cached or already downloading.
+        if vid in self._prefetch_cache:
+            return
+        if vid == self._prefetch_task_id:
+            return
+        # Don't prefetch if it's already the active download target.
+        if self._active_task_id is not None:
+            # The active download might be for this same song (e.g. if
+            # _request_download was called but is still in flight).  Check by
+            # tracking task_id alone is enough — if there's an active download,
+            # the prefetch is redundant anyway.
+            return
+
+        task_id = self._next_task_id
+        self._next_task_id += 1
+        self._prefetch_task_id = task_id
+
+        self._worker.download_requested.emit(task_id, next_song)
+
+    # ═══════════════════════════════════════════════════════════════════════
+    # Temp-file cleanup
+    # ═══════════════════════════════════════════════════════════════════════
+
+    def _cleanup_current_temp(self) -> None:
+        """Remove the temp file of the song we're about to replace."""
+        if self._current is None:
+            return
+        lp = self._current.get("_local_path")
+        if lp and os.path.isfile(lp):
+            try:
+                os.unlink(lp)
+            except OSError:
+                pass
+
+    def _cleanup_temp_files(self) -> None:
+        """Remove all temp files we know about (current + prefetch cache)."""
+        if self._current:
+            lp = self._current.get("_local_path")
+            if lp and os.path.isfile(lp):
+                try:
+                    os.unlink(lp)
+                except OSError:
+                    pass
+        for cached in self._prefetch_cache.values():
+            lp = cached.get("_local_path")
+            if lp and os.path.isfile(lp):
+                try:
+                    os.unlink(lp)
+                except OSError:
+                    pass
+
+    # ── Shutdown ──────────────────────────────────────────────────────────────
+
+    def shutdown(self) -> None:
+        """Clean shutdown — stop playback, quit worker thread, remove temps."""
+        self._player.stop()
+        self._cancel_active_downloads()
+        self._cleanup_temp_files()
+        self._queue.clear()
+        self._prefetch_cache.clear()
+        self._current = None
+        self._loop_mode = False
+
+        # Tear down the persistent worker thread.
+        self._worker_thread.quit()
+        self._worker_thread.wait(3000)
+        # The worker and thread objects are owned by self (parented), so
+        # they'll be cleaned up by Qt when the AudioPlayer is destroyed.
+
+
+# ── Helpers ───────────────────────────────────────────────────────────────────
+
+def _best_thumbnail(thumbnails) -> str:
+    if not thumbnails:
+        return ""
+    if isinstance(thumbnails, str):
+        return thumbnails
+    if isinstance(thumbnails, list):
+        best = thumbnails[-1]
+        return best.get("url", "") if isinstance(best, dict) else str(best)
+    return str(thumbnails)
+
+
+def _build_song_dict(search_result: dict) -> dict:
+    """Normalise a ytmusicapi result into our standard song dict."""
+    return {
+        "videoId": search_result.get("videoId", ""),
+        "title": search_result.get("title", "Unknown"),
+        "artists": search_result.get("artists") or [],
+        "album": search_result.get("album"),
+        "duration": search_result.get("duration_seconds", 0),
+        "duration_label": search_result.get("duration", "?"),
+        "thumbnail": _best_thumbnail(search_result.get("thumbnails", [])),
+        "videoType": search_result.get("videoType", ""),
+        "resultType": search_result.get("resultType", "song"),
+    }