Dodaios is an open-source agent OS for your desktop: it runs your coding agents, browser and apps by voice or chat, on your own machine. Formerly Personal Jarvis.
Python agent-orchestrationai-agentai-coding-assistantclaude-codecoding-agentcomputer-usedesktop-applocal-firstmcppersonal-jarvisvoice-assistantvoice-coding
feat(music): a background player instead of a browser tab, and a preferred service
Harald619cccb5b9b3
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 39204c1c91..3d7c5b7af4 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -36,8 +36,27 @@ versioning per [SemVer](https://semver.org/).instead of a fake success (`docs/os-parity.md` P-33).- **Honest limits, said out loud.** Google allows 100 searches a day perproject (each "play <name>" is one; repeats are cached, own playlists cost- none); volume and "queue next" do not exist in YouTube's API and the skill- says so instead of guessing. Setup: `docs/marketplace/youtube-music-setup.md`.+ none); "queue next" does not exist in YouTube's API and the skill says so+ instead of guessing. Setup: `docs/marketplace/youtube-music-setup.md`.+ - **A background player instead of a browser tab (default).** "Play X" no+ longer pops a browser: a small player window of its own (a pywebview+ companion process with a persistent profile — log in once, keep Premium)+ starts minimized, loads each song in place, and answers pause / skip /+ "what is playing" — and, new, **volume by voice**, which no OS media+ session offers. First run shows YouTube's cookie choice once. Where the+ player cannot run (headless, no desktop extras) or when Settings → Music+ says *Browser*, the browser path stays. Measured, not assumed: a truly+ hidden WebView2 window never starts media, a minimized one does.+ - **Two connectors, one domain — a preference instead of a coin toss.**+ With Spotify AND YouTube Music connected, "spiel Musik" went to whichever+ music skill was registered first, and the LLM router picked arbitrarily+ on the turns no skill captured. New `[music] preferred_service`+ (Settings → Music, `PUT /api/settings/music`, `jarvis api settings`):+ a named service always wins ("on YouTube Music"), else the preference,+ else on *Automatic* the only connected one. ONE resolver+ (`jarvis/core/music_service.py`) feeds both the deterministic skill+ capture and the two tools' descriptions, so the router and the capture+ can never disagree. Five-layer vocabulary with a parity test.- **Google Cloud Vertex AI as a provider family of its own, on every tier.**Vertex serves the same Gemini models as Google AI Studio, but bills a Clouddiff --git a/docs/marketplace/google-oauth-setup.md b/docs/marketplace/google-oauth-setup.mdindex 5f69f322d8..32dd543447 100644--- a/docs/marketplace/google-oauth-setup.md+++ b/docs/marketplace/google-oauth-setup.md@@ -38,7 +38,10 @@ still set it as an env var / credential-manager secret or editread events across ALL your calendars, not just the primary one, so a lessonon a secondary "School" calendar isn't missed. See "Keeping it connected".)5. **Test users** → add your own Google address. In Testing mode only listed- users can authorize.+ users can authorize — an unlisted account ends Connect on Google's+ **"Access blocked: <app> has not completed the Google verification process+ / Error 403: access_denied"** page. That page means exactly this missing+ entry (or: publish the app, see "Keeping it connected").6. **Credentials → Create credentials → OAuth client ID** → Application type**Desktop app** → Create. Copy the **Client ID**(looks like `1234567890-abc….apps.googleusercontent.com`).diff --git a/docs/marketplace/youtube-music-setup.md b/docs/marketplace/youtube-music-setup.mdindex 654446e505..c21e744a25 100644--- a/docs/marketplace/youtube-music-setup.md+++ b/docs/marketplace/youtube-music-setup.md@@ -17,16 +17,23 @@ redesign and sit outside YouTube's terms, so this project does not ship one.| You say | What happens ||---|---|-| "play Radiohead" · "play Karma Police" · "play the album OK Computer" · "play my running playlist" · "play my liked songs" | Jarvis finds it and opens it in **YouTube Music in your browser** — your own account, your Premium, your history. A song opens as its own radio, so music keeps coming. |-| "pause" · "carry on" · "skip this" · "go back" | Sent to the browser through the system's media session — the same channel your keyboard's play/pause key uses. |-| "what song is this?" | Read from that media session: track, artist, album, and which app it comes out of. |+| "play Radiohead" · "play Karma Police" · "play the album OK Computer" · "play my running playlist" · "play my liked songs" | Jarvis finds it and starts it in **YouTube Music** — in the background player (default) or your browser — on your own account, with your Premium and history. A song opens as its own radio, so music keeps coming. |+| "pause" · "carry on" · "skip this" · "go back" | Steers the background player directly; in browser mode it goes through the system's media session — the same channel your keyboard's play/pause key uses. |+| "what song is this?" | Read from the player (or the media session): track, artist, album, and which app it comes out of. || "like this song" · "add this to my running playlist" · "create a playlist called Late night" · "what is in my chill playlist?" | Written to your YouTube library through the official API. |-| "turn it up" | **Not available.** YouTube exposes no volume control; use the system or app volume. |+| "turn it up" · "volume 30" | Works in the background player (Jarvis drives YouTube Music's own volume slider). In browser mode YouTube exposes no volume control — use the system or app volume. || "queue this next" | **Not available.** There is no queue API; Jarvis offers to play it now or add it to a playlist instead. |--Playback happens **in YouTube Music, not in Jarvis** — exactly like the Spotify-plugin, where the music comes out of Spotify. That is deliberate: it keeps your-Premium (no ads), your recommendations and your history in your own account.+| "open YouTube Music" · "hide the player" | Brings the background player forward (login, cookie choice, the queue) or minimizes it again. |++Playback happens **in YouTube Music, not in Jarvis's own audio** — exactly+like the Spotify plugin, where the music comes out of Spotify. By default it+runs in a **background player**: a small window of its own that starts+minimized (a taskbar entry, no browser tab, no focus steal) and simply loads+the next song when you ask for one. Say "open YouTube Music" to bring it+forward — that is where you log in once (for your Premium, no ads) and make+YouTube's one-time cookie choice. Settings → Music can switch playback to the+system browser instead, and the browser is also the automatic fallback where+the player cannot run (no display, no desktop extras).## Part A — the Google Cloud project (once)@@ -38,7 +45,17 @@ project:2. **APIs & Services → OAuth consent screen → Scopes** → add`https://www.googleapis.com/auth/youtube` (it is a *sensitive* scope; forpersonal use in Testing mode no verification is needed).-3. That is all — the OAuth client itself is the one you already have. Nothing+3. **Test users.** While the OAuth app is in *Testing* mode, Google lets ONLY+ the accounts you list as test users sign in. Open **Google Auth Platform →+ Audience → Test users → Add users** and add your own Google address (the one+ you will connect with). Without this, Connect ends on Google's page+ **"Access blocked: <app> has not completed the Google verification process+ / Error 403: access_denied"** — that is this missing entry, nothing else.+ Alternatively **publish the app** (*Audience → Publish app*, In production):+ then any account can sign in after clicking through Google's "unverified+ app" warning (Advanced → continue), and the seven-day expiry below goes+ away too.+4. That is all — the OAuth client itself is the one you already have. Nothingto register: the loopback redirect works out of the box for a Google**Desktop app** client.@@ -52,9 +69,22 @@ project:3. Your browser opens Google's approval page. Approve the **YouTube** permission.4. The tab reports `Connected.` and can be closed.-## Part C — playback control on your machine+## Part C — playback on your machine++**Background player (default).** Music plays in Jarvis's own small player+window, which needs a display and the desktop extras (pywebview — the same+`[desktop]` extra the desktop app uses). It starts minimized and keeps playing+minimized; "open YouTube Music" brings it forward. First run: YouTube shows its+cookie choice once, and you can log in there once so playback uses your account+and Premium — both are remembered in a profile of their own under+`data/music_player/`. Pause, skip, "what is playing" and volume all go through+that window directly, on every OS the window can open on. Where it cannot+(headless, Linux without a GTK/Qt WebKit backend), Jarvis falls back to the+browser and says why.-Reading "what is playing" and pause/skip use the OS media session:+**Browser mode** (Settings → Music → Where YouTube Music plays → Browser).+Playing opens a YouTube Music tab; reading "what is playing" and pause/skip+then use the OS media session:| OS | Out of the box | If not ||---|---|---|@@ -84,14 +114,22 @@ truly gone.once — after that it starts on its own.- **A song is a video.** YouTube's top hit is sometimes the music video or alive version. Jarvis says what it actually started so you notice at once.-- **Two tabs.** Each "play" opens a new YouTube Music tab; Jarvis pauses the- old one first, so only one plays. Close the extras whenever you like.+- **Two tabs (browser mode only).** Each "play" opens a new YouTube Music tab;+ Jarvis pauses the old one first, so only one plays. The background player has+ no such pile-up — it navigates one window.+- **Spotify and YouTube Music both connected?** A request that names a service+ ("on Spotify", "on YouTube Music") goes there. One that names none goes to+ the service chosen under **Settings → Music → Preferred service** — or, on+ *Automatic*, to the only connected one (Spotify if both are).## When something does not work| What you see | What it means ||---|---|+| Google: "Access blocked: … has not completed the Google verification process — Error 403: access_denied" | Your account is not on the OAuth app's **Test users** list (Part A step 3), or publish the app. || "The YouTube Data API v3 is not enabled" | Part A step 1 was skipped in the Cloud project behind your client. |+| "YouTube asks for your cookie choice once" | First run of the background player: pick your cookie choice in the window that opened; it is remembered. |+| "The player opened the song but did not start — press play once" | The player window came forward; one click on play, then it starts on its own. || "The stored Google authorization does not include YouTube" | The scope was not approved — reconnect and tick the YouTube permission. || "100 YouTube searches a day … used up" | Google's daily search bucket. Resets at midnight Pacific. || "opened, but playback not confirmed" | The browser withheld autoplay; press play once. |diff --git a/docs/os-parity.md b/docs/os-parity.mdindex 540dc90080..03408e8aab 100644--- a/docs/os-parity.md+++ b/docs/os-parity.md@@ -248,8 +248,9 @@ experiences today.| P-32 | Low | Local models | The in-app Ollama runtime install (the plug-and-go path for local models: detect → install → start → pull, no terminal) has one silent path per OS and an honest refusal elsewhere: Windows uses winget or the official per-user OllamaSetup.exe (built, not yet live-run on a machine WITHOUT Ollama); macOS automates only Homebrew — a dmg drag cannot be scripted honestly, so brew-less Macs get the download pointer; Linux runs the official install.sh only when non-interactive sudo exists (the script escalates internally; without it the refusal names the one terminal command instead of hanging on an invisible password prompt). Detection and start are cross-platform | `jarvis/brain/ollama_runtime.py`, `jarvis/ui/web/provider_routes.py` (ollama-runtime routes), `jarvis/realtime/local_server/install.py::_setup_local_brain` | Every OS gets the same three-state truth (not installed / stopped / running) and the same buttons; only the INSTALL leg differs. Refusals are one honest sentence with the exact fixing action. All install legs are unit-tested with fakes; no leg has been live-run on a machine without Ollama yet — the cold-machine drill is the recorded release gate || P-31 | Low | Detached views | The "own window" detach (Agentic IDE / Voice into a second pywebview window) creates the window at RUNTIME, after `webview.start()`. pywebview documents runtime multi-window, and the code path is OS-neutral (worker-thread create, distinct title, shared backend), but it has only been RUN against the Windows/WebView2 backend; whether the cocoa and GTK backends accept a runtime `create_window` is unverified from this machine. Browser-lock auth in the second window additionally relies on a shared cookie jar, which is verified for WebView2 only | `jarvis/ui/desktop_app.py::open_detached_window`, `jarvis/platform/probes.py::webview_backend_available`, `jarvis/ui/web/desktop_routes.py` | Every failure is honest and keeps the feature usable: a shell whose backend refuses the runtime create answers `ok: false` with the solo URL and the frontend opens it in the user's real browser tab (via open-external); plain-browser clients open the tab directly; headless answers `no_desktop_shell` the same way. macOS/Linux desktop live check pending: detach, close main, reattach, tray-reopen — on success this row shrinks to the cookie-jar note or disappears |-| P-33 | Low | Music control (YouTube Music) | Pause / resume / next / previous and "what is playing" for the YouTube Music plugin go through the OS media session — the registry the keyboard's media keys use — because Google publishes no remote-playback API. Windows reads and steers it through WinRT (`winrt-Windows.Media.Control`, in the `[desktop]` extra; measured live 2026-08-18 against YouTube Music in Chrome, including the two-tabs-same-app-id case) and falls back to blind media keys without the extra. Linux has no binding in the base install and needs the `playerctl` CLI (MPRIS); macOS has no public API at all and needs the Homebrew `nowplaying-cli`, whose MediaRemote access Apple has been narrowing on recent releases | `jarvis/platform/media_session.py::make_media_session_controller`, `WindowsMediaSession`, `LinuxMediaSession`, `MacMediaSession`, `jarvis/plugins/tool/youtube_music_rest.py::_control` | Playing (search + open the `music.youtube.com` deep link) works on every desktop OS. Without the CLI, `now_playing` and the transport verbs answer with the exact install command instead of a fake success, and the play deep link plus the library actions (like, playlists) stay fully usable. Headless: no player exists, so the tool returns the link and says so. Linux `playerctl` and macOS `nowplaying-cli` backends are unit-tested with fake CLI output, not live-run from this machine |+| P-33 | Low | Music control (YouTube Music) | With the default **background player** (`jarvis/platform/music_player.py` + `music_player_host.py`: a pywebview companion window with its own persistent profile, driven over stdin/stdout JSON lines) pause / resume / next / previous / volume / "what is playing" go through the player's page directly and need only a display plus the `[desktop]` extra (pywebview) — verified live on Windows/WebView2 (a hidden window does NOT start media; minimized does, hence the minimized start); macOS WKWebView and Linux GTK/Qt WebKit are the same code, unverified from this machine, and autoplay policy there may need one press of play (the tool shows the window and says so). In **browser mode**, and wherever the player cannot run, the same verbs go through the OS media session — the registry the keyboard's media keys use — because Google publishes no remote-playback API. Windows reads and steers it through WinRT (`winrt-Windows.Media.Control`, in the `[desktop]` extra; measured live 2026-08-18 against YouTube Music in Chrome, including the two-tabs-same-app-id case) and falls back to blind media keys without the extra. Linux has no binding in the base install and needs the `playerctl` CLI (MPRIS); macOS has no public API at all and needs the Homebrew `nowplaying-cli`, whose MediaRemote access Apple has been narrowing on recent releases | `jarvis/platform/media_session.py::make_media_session_controller`, `WindowsMediaSession`, `LinuxMediaSession`, `MacMediaSession`, `jarvis/plugins/tool/youtube_music_rest.py::_control` | Playing (search + open the `music.youtube.com` deep link) works on every desktop OS. Without the CLI, `now_playing` and the transport verbs answer with the exact install command instead of a fake success, and the play deep link plus the library actions (like, playlists) stay fully usable. Headless: no player exists, so the tool returns the link and says so. Linux `playerctl` and macOS `nowplaying-cli` backends are unit-tested with fake CLI output, not live-run from this machine || P-34 | Low | Drop-path bridge | The desktop shell reports the REAL path of a file or folder dropped onto the UI (`jarvis-native-drop` DOM event from `jarvis/ui/native_drop.py`, consumed by `src/lib/nativeDrop.ts` in the Agentic IDE folder picker). Built on pywebview's own cross-platform drop handling (`pywebviewFullPath` — WebView2 on Windows, WKWebView on macOS, WebKitGTK on Linux); live-verified for a dropped FOLDER on Windows/WebView2 only | `jarvis/ui/native_drop.py::register_native_drop`, `jarvis/ui/desktop_app.py::_register_native_drop`, `jarvis/ui/web/frontend/src/lib/nativeDrop.ts` | Honest degradation everywhere: without the announcement (plain browser, headless, a shell whose backend does not resolve paths) the picker falls back to searching for the dropped NAME after 2 s, exactly as before. macOS/Linux live check pending: drop a folder onto the folder step and confirm the exact path is used without a candidate list |+| P-35 | Low | Desktop shell | The embedded browser's profile is PERSISTENT (`webview.start(private_mode=False, storage_path=<data>/webview)`) so the frontend's `localStorage` — wallpaper pick, deck/classic surface, pane sizes, favourites, theme cache — survives a restart (2026-08-18: pywebview's default private mode parked the WebView2 profile in a fresh `%TEMP%` folder per launch and the interface forgot every pick). The same call is honoured by every pywebview backend (Edge `UserDataFolder`, WebKitGTK `WebsiteDataManager`, Qt profile path, Cocoa's default persistent data store) but has only been RUN against Windows/WebView2 | `jarvis/ui/desktop_app.py::webview_storage_dir` | Honest everywhere: a checkout without a writable data directory falls back to the per-user directory, then to private mode with a logged warning — the interface still works, it only forgets its cosmetic picks. macOS/Linux live check pending: pick a wallpaper, restart, confirm it is still there |## Maintenancediff --git a/jarvis/brain/manager.py b/jarvis/brain/manager.pyindex 0b5bdb4fbc..f89b299a26 100644--- a/jarvis/brain/manager.py+++ b/jarvis/brain/manager.py@@ -5442,6 +5442,10 @@ class BrainManager:vetoed_by=guards.VETO_PLUGIN_NOT_CONNECTED, skill=skill,)return None+ # Two music connectors, one domain: the request goes to the service+ # the user named, else the preferred one, else the only connected+ # one — never to whichever music skill happened to be first.+ skill = self._prefer_music_service(skill, user_text, ctx.registry)self._skill_match_band = decision.bandself._skill_match_class = classify(skill)@@ -5634,10 +5638,56 @@ class BrainManager:except Exception: # noqa: BLE001return False- @staticmethod- def _paired_plugin_disconnected(skill: Any, *, store: Any | None = None) -> bool:+ def _prefer_music_service(self, skill: Any, user_text: str, registry: Any) -> Any:+ """Swap a matched MUSIC skill for its sibling when the resolver says the+ request belongs to the other service (see ``jarvis.core.music_service``).++ Reads ``[music] preferred_service``. Never raises and never swaps to a+ skill that is missing or whose plugin is not connected — a fault keeps+ the match as it was."""+ try:+ from jarvis.core.music_constants import MUSIC_PLUGIN_IDS+ from jarvis.core.music_service import resolve_music_service++ fm = getattr(skill, "frontmatter", None)+ plugin_id = str(getattr(fm, "plugin_id", "") or "").strip()+ if plugin_id not in MUSIC_PLUGIN_IDS:+ return skill+ connected = [+ pid for pid in MUSIC_PLUGIN_IDS if not self._plugin_disconnected(pid)+ ]+ music_cfg = getattr(self._config, "music", None)+ preferred = str(getattr(music_cfg, "preferred_service", "auto") or "auto")+ target = resolve_music_service(+ user_text, preferred=preferred, connected=connected, matched=plugin_id+ )+ if not target or target == plugin_id or target not in connected:+ return skill+ sibling = registry.get(f"plugin-{target}")+ if sibling is None:+ return skill+ log.info(+ "music request routed to %s instead of %s (preferred=%s, connected=%s)",+ target, plugin_id, preferred, connected,+ )+ return sibling+ except Exception as exc: # noqa: BLE001 — a routing nicety must never break a turn+ log.debug("music preference routing skipped: %s", exc)+ return skill++ @classmethod+ def _paired_plugin_disconnected(cls, skill: Any, *, store: Any | None = None) -> bool:"""True when ``skill`` is paired to a CATALOG plugin whose credential is- absent or flagged for re-auth.+ absent or flagged for re-auth (see :meth:`_plugin_disconnected`)."""+ fm = getattr(skill, "frontmatter", None)+ plugin_id = str(getattr(fm, "plugin_id", "") or "").strip()+ if not plugin_id:+ return False+ return cls._plugin_disconnected(plugin_id, store=store)++ @staticmethod+ def _plugin_disconnected(plugin_id: str, *, store: Any | None = None) -> bool:+ """True when catalog plugin ``plugin_id`` holds no usable credential.Only catalog plugins are judged — every one of them authenticates, so"no token" really means "not connected". A community skill naming an@@ -5651,8 +5701,6 @@ class BrainManager:plugin per :data:`_PAIRED_CONNECTION_TTL_S`, not one per matched turn.A connect made inside that window merely routes without the skill'sguidance for a few seconds — the tool itself is callable at once."""- fm = getattr(skill, "frontmatter", None)- plugin_id = str(getattr(fm, "plugin_id", "") or "").strip()if not plugin_id:return Falsenow = time.monotonic()diff --git a/jarvis/core/config.py b/jarvis/core/config.pyindex fd5f3f2d63..8bd4eb147a 100644--- a/jarvis/core/config.py+++ b/jarvis/core/config.py@@ -1736,6 +1736,65 @@ class DuckingConfig(BaseModel):macos_master_fallback: bool = False+class MusicConfig(BaseModel):+ """Music connectors — two services, one domain (2026-08-18).++ ``preferred_service`` says which connector a music request that names no+ service goes to when Spotify AND YouTube Music are connected; ``auto`` keeps+ the pre-setting behaviour (the only connected one, else Spotify by catalog+ order). ``playback`` says where YouTube Music plays: the hidden in-app+ player window (``background`` — no browser tab, no focus steal, one window+ that navigates) or the system browser (``browser``, also the fallback+ wherever the player cannot run: no display, no pywebview backend). The+ vocabulary lives in ``jarvis/core/music_constants.py`` (five-layer L0) and+ the ``Literal``s below are asserted against it at import time.+ """++ model_config = ConfigDict(extra="allow")++ preferred_service: Literal["auto", "spotify", "youtube_music"] = "auto"+ playback: Literal["background", "browser"] = "background"++ @field_validator("preferred_service", mode="before")+ @classmethod+ def _sanitize_preferred_service(cls, v: object) -> object:+ # A persisted unknown value (a renamed plugin, a typo from a hand edit)+ # must not brick the config load — it falls back to "auto".+ from jarvis.core.music_constants import MUSIC_SERVICE_AUTO, MUSIC_SERVICES++ if isinstance(v, str) and v.strip().lower() in MUSIC_SERVICES:+ return v.strip().lower()+ return MUSIC_SERVICE_AUTO++ @field_validator("playback", mode="before")+ @classmethod+ def _sanitize_playback(cls, v: object) -> object:+ from jarvis.core.music_constants import (+ MUSIC_PLAYBACK_BACKGROUND,+ MUSIC_PLAYBACK_MODES,+ )++ if isinstance(v, str) and v.strip().lower() in MUSIC_PLAYBACK_MODES:+ return v.strip().lower()+ return MUSIC_PLAYBACK_BACKGROUND+++def _assert_music_literals_match_constants() -> None:+ """Five-layer pattern (L3): the Literals on ``MusicConfig`` must spell+ exactly the tuples in ``music_constants`` — a drift here would be a+ Pydantic ``literal_error`` at load."""+ from jarvis.core.music_constants import MUSIC_PLAYBACK_MODES, MUSIC_SERVICES++ fields = MusicConfig.model_fields+ if set(get_args(fields["preferred_service"].annotation)) != set(MUSIC_SERVICES):+ raise RuntimeError("MusicConfig.preferred_service drifted from MUSIC_SERVICES")+ if set(get_args(fields["playback"].annotation)) != set(MUSIC_PLAYBACK_MODES):+ raise RuntimeError("MusicConfig.playback drifted from MUSIC_PLAYBACK_MODES")+++_assert_music_literals_match_constants()++class AutostartConfig(BaseModel):"""Cross-platform login autostart (the 7th cross-platform port).@@ -3652,6 +3711,8 @@ class JarvisConfig(BaseModel):ui: UIConfig = Field(default_factory=UIConfig)# Audio ducking — "Mute music while dictating" (Taskbar section).ducking: DuckingConfig = Field(default_factory=DuckingConfig)+ # Music connectors: preferred service + where YouTube Music plays.+ music: MusicConfig = Field(default_factory=MusicConfig)# Cross-platform login autostart (Windows .lnk / macOS LaunchAgent / Linux# XDG .desktop). Default ON; headless host = graceful no-op.autostart: AutostartConfig = Field(default_factory=AutostartConfig)diff --git a/jarvis/core/config_writer.py b/jarvis/core/config_writer.pyindex e9e2e6ff27..4aa60b5fc1 100644--- a/jarvis/core/config_writer.py+++ b/jarvis/core/config_writer.py@@ -1471,6 +1471,28 @@ def set_mute_music(enabled: bool, *, path: Path = DEFAULT_CONFIG_FILE) -> None:_patch_table(path, "ducking", "enabled", bool(enabled))+def set_preferred_music_service(service: str, *, path: Path = DEFAULT_CONFIG_FILE) -> None:+ """Persist ``[music] preferred_service`` — which connector a music request+ that names no service goes to (``auto`` | ``spotify`` | ``youtube_music``).++ Validated by the caller against ``jarvis.core.music_constants.MUSIC_SERVICES``+ (the Settings route is the layer that knows the accepted set); this only+ writes. TOML-only by design: not in the drift-guard's reference snapshot,+ so the drift-guard never reverts it.+ """+ _patch_table(path, "music", "preferred_service", service)+++def set_music_playback(mode: str, *, path: Path = DEFAULT_CONFIG_FILE) -> None:+ """Persist ``[music] playback`` — where YouTube Music plays+ (``background`` = the hidden in-app player, ``browser`` = the system browser).++ Validated by the caller against ``MUSIC_PLAYBACK_MODES``; TOML-only, not+ drift-guarded.+ """+ _patch_table(path, "music", "playback", mode)++def set_sound_effects(enabled: bool, *, path: Path = DEFAULT_CONFIG_FILE) -> None:"""Persist ``[ui] sound_effects`` (the global earcon master switch).diff --git a/jarvis/core/music_constants.py b/jarvis/core/music_constants.pynew file mode 100644index 0000000000..d4687f8407--- /dev/null+++ b/jarvis/core/music_constants.py@@ -0,0 +1,47 @@+"""Music-plugin vocabulary — the single source of truth (five-layer pattern L0).++Two music connectors (Spotify, YouTube Music) share one domain, so two+settings arbitrate them: which service a request that names no service goes+to, and where YouTube Music playback happens. Every layer imports THESE+symbols — the config ``Literal`` is asserted against them at import time, the+REST route derives its accepted set from them, the frontend mirrors them as a+TypeScript union (``src/lib/musicSettings.ts``) pinned by a parity test — so a+value can never be spelled differently in one place than in another (BUG-008).+"""+from __future__ import annotations++# `preferred_service`: the connector a music request goes to when the user+# does not name one. "auto" = the only connected service, else the first+# music skill by catalog order (Spotify) — the same behaviour as before the+# setting existed.+MUSIC_SERVICE_AUTO = "auto"+MUSIC_SERVICE_SPOTIFY = "spotify"+MUSIC_SERVICE_YOUTUBE_MUSIC = "youtube_music"+MUSIC_SERVICES: tuple[str, ...] = (+ MUSIC_SERVICE_AUTO,+ MUSIC_SERVICE_SPOTIFY,+ MUSIC_SERVICE_YOUTUBE_MUSIC,+)++# `playback`: where YouTube Music plays. "background" = the hidden in-app+# player window (no browser tab, no focus steal); "browser" = the system+# browser, the pre-2026-08-18 behaviour and the fallback wherever the player+# cannot run.+MUSIC_PLAYBACK_BACKGROUND = "background"+MUSIC_PLAYBACK_BROWSER = "browser"+MUSIC_PLAYBACK_MODES: tuple[str, ...] = (MUSIC_PLAYBACK_BACKGROUND, MUSIC_PLAYBACK_BROWSER)++# The catalog plugin ids that count as music services (their paired skills are+# ``plugin-<id>``). Order = the "auto" tie-break order.+MUSIC_PLUGIN_IDS: tuple[str, ...] = (MUSIC_SERVICE_SPOTIFY, MUSIC_SERVICE_YOUTUBE_MUSIC)++__all__ = [+ "MUSIC_PLAYBACK_BACKGROUND",+ "MUSIC_PLAYBACK_BROWSER",+ "MUSIC_PLAYBACK_MODES",+ "MUSIC_PLUGIN_IDS",+ "MUSIC_SERVICES",+ "MUSIC_SERVICE_AUTO",+ "MUSIC_SERVICE_SPOTIFY",+ "MUSIC_SERVICE_YOUTUBE_MUSIC",+]diff --git a/jarvis/core/music_service.py b/jarvis/core/music_service.pynew file mode 100644index 0000000000..ed9ab717fe--- /dev/null+++ b/jarvis/core/music_service.py@@ -0,0 +1,163 @@+"""Which music connector a request goes to — Spotify or YouTube Music.++Two connectors, one domain: "spiel Musik" is a valid request to either. This+module is the one place that decides, pure and unit-testable:++1. A service the user NAMES wins ("… auf YouTube Music", "… on Spotify").+2. Otherwise the ``[music] preferred_service`` setting, when that service is+ connected.+3. Otherwise ``auto``: the only connected service, else the skill that matched+ the turn (Spotify by catalog order — the behaviour before the setting).++The brain applies the answer to the deterministic skill capture; the two+music tools carry it in their descriptions so the LLM router makes the same+choice on the turns no skill captures. Both read the SAME resolver, so a+preference can never be honoured in one place and ignored in the other.+"""+from __future__ import annotations++import logging+import re+import threading+import time+from collections.abc import Iterable++from jarvis.core.music_constants import (+ MUSIC_PLUGIN_IDS,+ MUSIC_SERVICE_AUTO,+ MUSIC_SERVICE_SPOTIFY,+ MUSIC_SERVICE_YOUTUBE_MUSIC,+)++# The brand mentions that name a service outright. Word-boundaried; "youtube"+# alone counts for YouTube Music because in a MUSIC request that is what the+# user means (spoken input rarely says the full brand).+_EXPLICIT: tuple[tuple[str, re.Pattern[str]], ...] = (+ (MUSIC_SERVICE_SPOTIFY, re.compile(r"\bspotify\b", re.IGNORECASE)),+ (+ MUSIC_SERVICE_YOUTUBE_MUSIC,+ re.compile(r"\b(?:youtube(?:\s*music)?|yt\s*music|ytmusic|yt)\b", re.IGNORECASE),+ ),+)++_LABELS = {MUSIC_SERVICE_SPOTIFY: "Spotify", MUSIC_SERVICE_YOUTUBE_MUSIC: "YouTube Music"}++log = logging.getLogger(__name__)++# Which music connectors hold a usable credential is a keyring read; the tool+# descriptions ask on every turn, so the answer is remembered briefly.+_CONNECTED_TTL_S = 15.0+_connected_cache: tuple[float, tuple[str, ...]] | None = None+_connected_lock = threading.Lock()+++def connected_music_services(*, store: object | None = None) -> tuple[str, ...]:+ """Music plugin ids with a usable credential (access token, not flagged+ for re-auth). Cached for a few seconds; a store fault answers the last+ known value or nothing — never raises. ``store`` is injectable for tests."""+ global _connected_cache+ now = time.monotonic()+ if store is None:+ with _connected_lock:+ if _connected_cache is not None and _connected_cache[0] > now:+ return _connected_cache[1]+ live: list[str] = []+ try:+ if store is None:+ from jarvis.marketplace.token_store import TokenStore++ store = TokenStore()+ for plugin_id in MUSIC_PLUGIN_IDS:+ try:+ tokens = store.load(plugin_id) # type: ignore[attr-defined]+ except Exception as exc: # noqa: BLE001 — one broken credential stays isolated+ log.debug("music connection probe: %s unreadable: %s", plugin_id, exc)+ continue+ if (+ tokens is not None+ and getattr(tokens, "access", None)+ and not getattr(tokens, "needs_reauth", False)+ ):+ live.append(plugin_id)+ except Exception as exc: # noqa: BLE001 — a store fault must not decide a turn+ log.debug("music connection probe failed: %s", exc)+ return _connected_cache[1] if _connected_cache else ()+ result = tuple(live)+ with _connected_lock:+ _connected_cache = (now + _CONNECTED_TTL_S, result)+ return result+++def forget_connected_music_services() -> None:+ """Drop the cached connection answer (a connect/disconnect just happened)."""+ global _connected_cache+ with _connected_lock:+ _connected_cache = None+++def service_label(service_id: str) -> str:+ return _LABELS.get(service_id, service_id)+++def explicit_music_service(text: str) -> str | None:+ """The service the utterance names, or None when it names none (or both)."""+ hits = [service for service, pattern in _EXPLICIT if pattern.search(text or "")]+ if len(hits) == 1:+ return hits[0]+ return None+++def resolve_music_service(+ text: str,+ *,+ preferred: str,+ connected: Iterable[str],+ matched: str | None = None,+) -> str | None:+ """The connector this request should go to (see the module docstring).++ ``connected`` are the music plugin ids holding a usable credential;+ ``matched`` is the plugin id of the skill the deterministic matcher picked,+ if any. Returns None only when nothing is connected and nothing matched.+ """+ live = [pid for pid in MUSIC_PLUGIN_IDS if pid in set(connected)]+ named = explicit_music_service(text)+ if named:+ return named+ pref = (preferred or MUSIC_SERVICE_AUTO).strip().lower()+ if pref != MUSIC_SERVICE_AUTO and pref in live:+ return pref+ if len(live) == 1:+ return live[0]+ if matched in MUSIC_PLUGIN_IDS:+ return matched+ return live[0] if live else None+++def preference_hint(service_id: str, *, preferred: str, connected: Iterable[str]) -> str:+ """One sentence for a music tool's description, so the LLM router honours+ the same preference the skill capture does. Empty when there is nothing to+ say (one service, or no preference)."""+ live = [pid for pid in MUSIC_PLUGIN_IDS if pid in set(connected)]+ pref = (preferred or MUSIC_SERVICE_AUTO).strip().lower()+ if len(live) < 2 or pref == MUSIC_SERVICE_AUTO or pref not in live:+ return ""+ if service_id == pref:+ return (+ f" The user prefers {service_label(pref)} for music: use this tool for any music "+ "request that does not name another service."+ )+ return (+ f" The user prefers {service_label(pref)} for music: use this tool only when the "+ f"request names {service_label(service_id)} explicitly."+ )+++__all__ = [+ "connected_music_services",+ "explicit_music_service",+ "forget_connected_music_services",+ "preference_hint",+ "resolve_music_service",+ "service_label",+]diff --git a/jarvis/marketplace/seed_catalog.json b/jarvis/marketplace/seed_catalog.jsonindex 9ab79a3337..4beb24b15c 100644--- a/jarvis/marketplace/seed_catalog.json+++ b/jarvis/marketplace/seed_catalog.json@@ -594,7 +594,7 @@"offline_access": true},"native_tool": "youtube_music",- "post_install_hint_md": "Setup: see docs/marketplace/youtube-music-setup.md — it shares the Google OAuth client with Gmail, Drive and Calendar; only **enable the YouTube Data API v3** in that Cloud project and add the `youtube` scope. Google publishes no YouTube Music API, so this talks to the official YouTube Data API v3 (search, your playlists, likes) and plays by opening YouTube Music in your browser — your own account and Premium. Pause, skip and \"what is playing\" go through the system's media session (Windows out of the box; Linux needs `playerctl`, macOS `nowplaying-cli`). Google allows **100 searches a day** per project — enough for one household, not for a party. Volume is not controllable here."+ "post_install_hint_md": "Setup: see docs/marketplace/youtube-music-setup.md — it shares the Google OAuth client with Gmail, Drive and Calendar; only **enable the YouTube Data API v3** in that Cloud project, add the `youtube` scope, and list your own account under the app's **Test users** (or publish the app) — otherwise Google answers `403 access_denied`. Google publishes no YouTube Music API, so this talks to the official YouTube Data API v3 (search, your playlists, likes) and plays in a **background player** — a small window of its own that starts minimized, where you log in once for your Premium (Settings → Music can switch to the browser instead). Pause, skip, volume and \"what is playing\" steer that player; in browser mode they go through the system's media session (Windows out of the box; Linux needs `playerctl`, macOS `nowplaying-cli`). Google allows **100 searches a day** per project — enough for one household, not for a party."}]}diff --git a/jarvis/marketplace/usage_cards/youtube_music.md b/jarvis/marketplace/usage_cards/youtube_music.mdindex ca58200a9b..cc4a3d8c73 100644--- a/jarvis/marketplace/usage_cards/youtube_music.md+++ b/jarvis/marketplace/usage_cards/youtube_music.md@@ -5,9 +5,9 @@ keywords: youtube music, youtube, yt music, ytmusic, musik, music, música, liedUse the youtube_music tool to play and control the user's music on YouTube Music.- To start something, pass what the user said as `query` and set `type`: `song` for a track, `artist` for a band (their top song starts and the radio continues with them), `album`, `playlist` for one of their own lists, `liked` for their liked songs. The tool searches and opens the hit in YouTube Music in one step; a song opens as its own radio, so music keeps coming.-- `play` without a query resumes what is paused; `pause`, `next` and `previous` steer what is already running. There is no volume action — say the system or app volume does that.+- `play` without a query resumes what is paused; `pause`, `next`, `previous` and `set_volume` steer what is already running (volume only in the background player).- `now_playing` answers "what song is this" — it reports track, artist and which app it comes out of. If it names another player (Spotify, a YouTube video), say so; it is not a wrong answer.- Report the track the response names, not the words the user used. YouTube's top hit is sometimes not what they meant, and saying it aloud is how they notice.-- Playing opens YouTube Music in the browser. When the response says playback is not confirmed, tell the user to press play once — the browser blocks autoplay on a site until it has been used there. That is the browser's rule, not a broken connection.+- Playing starts YouTube Music in a background player window (default) or the browser. When the response carries `needs_attention`, the player window has already come forward — say in one sentence what to do there (pick the cookie choice once, or press play once). That is not a broken connection. `open` brings the player forward, `hide_player` minimizes it.- `like`, `add_to_playlist` and `create_playlist` change their library; without a `query` they act on the song playing right now.- Google allows 100 searches a day for this app. When the response says they are used up, say so plainly — playing their own playlists, pausing and skipping still work.diff --git a/jarvis/platform/music_player.py b/jarvis/platform/music_player.pynew file mode 100644index 0000000000..e250272be9--- /dev/null+++ b/jarvis/platform/music_player.py@@ -0,0 +1,326 @@+"""Background music player — parent side of the companion host.++Talks to ``jarvis.platform.music_player_host`` (a hidden pywebview window in+its own process with a persistent browser profile) over stdin/stdout JSON+lines: load a URL, read the player state, pause / play / next / previous /+volume, show or hide the window. This is what lets "play Radiohead" happen+without a browser tab appearing or the focus moving — and what gives volume+control, which no OS media session offers.++Capability, honestly: the player needs a display and the ``pywebview``+package (the ``[desktop]`` extra); a headless host, or a Linux box without a+GTK/Qt WebKit backend, gets ``available() == (False, why)`` and the caller+falls back to the system browser. The host process dies with its parent+(stdin EOF), so a crashed Jarvis leaves no ghost player.++Synchronous by design — one pipe round-trip per call, bounded by a timeout —+callers on the event loop wrap it in ``asyncio.to_thread``. The process spawn+is injectable so the unit tests drive a fake host in-process.+"""+from __future__ import annotations++import atexit+import importlib.util+import json+import logging+import subprocess+import sys+import threading+from collections.abc import Callable+from pathlib import Path+from typing import Any++from jarvis.core.process_utils import NO_WINDOW_CREATIONFLAGS++log = logging.getLogger(__name__)++_HOST_MODULE = "jarvis.platform.music_player_host"+_READY_TIMEOUT_S = 20.0+_REQUEST_TIMEOUT_S = 10.0+++class MusicPlayerError(RuntimeError):+ """The host is not there, did not answer in time, or refused a command."""+++def _has_webview() -> bool:+ try:+ return importlib.util.find_spec("webview") is not None+ except (ImportError, ValueError): # a broken parent package reads as "not installed"+ return False+++def _default_storage_dir() -> Path:+ from jarvis.core.config import DATA_DIR++ return Path(DATA_DIR) / "music_player"+++def _default_title() -> str:+ from jarvis.core.branding import PRODUCT_NAME++ return f"{PRODUCT_NAME} — Music"+++def _default_spawn(argv: list[str]) -> Any:+ return subprocess.Popen( # noqa: S603 — fixed argv, own interpreter+ argv,+ stdin=subprocess.PIPE,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ encoding="utf-8",+ errors="replace",+ bufsize=1,+ creationflags=NO_WINDOW_CREATIONFLAGS,+ )+++class MusicPlayer:+ """Client for one background player process (lazy: spawned on first use)."""++ def __init__(+ self,+ *,+ storage_dir: Path | None = None,+ title: str | None = None,+ spawn: Callable[[list[str]], Any] | None = None,+ display_present: Callable[[], bool] | None = None,+ has_webview: Callable[[], bool] | None = None,+ ) -> None:+ self._storage_dir = storage_dir+ self._title = title+ self._spawn = spawn or _default_spawn+ self._display_present = display_present+ self._has_webview = has_webview or _has_webview+ self._proc: Any | None = None+ self._lock = threading.Lock()+ self._cond = threading.Condition()+ self._replies: dict[int, dict[str, Any]] = {}+ self._events: list[dict[str, Any]] = []+ self._ready = threading.Event()+ self._unavailable_reason = ""+ self._next_id = 0++ # -- capability -----------------------------------------------------------++ def available(self) -> tuple[bool, str]:+ """(can run here, why not). Never raises."""+ try:+ if self._display_present is not None:+ display = self._display_present()+ else:+ from jarvis.platform.capabilities import detect_capabilities++ display = bool(detect_capabilities().display_present)+ except Exception: # noqa: BLE001 — a probe fault reads as "no display"+ display = False+ if not display:+ return False, "This machine has no desktop session, so there is no player to run."+ if not self._has_webview():+ return (+ False,+ "The background player needs the desktop extras "+ "(`pip install \"personal-jarvis[desktop]\"` adds pywebview).",+ )+ if self._unavailable_reason:+ return False, self._unavailable_reason+ return True, ""++ def is_running(self) -> bool:+ proc = self._proc+ return proc is not None and proc.poll() is None and self._ready.is_set()++ # -- lifecycle ------------------------------------------------------------++ def start(self, timeout: float = _READY_TIMEOUT_S) -> bool:+ """Spawn the host if needed and wait for its ready line."""+ with self._lock:+ if self.is_running():+ return True+ ok, why = self.available()+ if not ok:+ log.info("music player unavailable: %s", why)+ return False+ self._ready.clear()+ self._replies.clear()+ self._events.clear()+ storage = self._storage_dir or _default_storage_dir()+ title = self._title or _default_title()+ argv = [sys.executable, "-m", _HOST_MODULE, "--storage", str(storage), "--title", title]+ try:+ self._proc = self._spawn(argv)+ except Exception as exc: # noqa: BLE001 — degrade to the browser, never raise+ log.warning("music player spawn failed: %s", exc)+ self._proc = None+ return False+ threading.Thread(+ target=self._pump, args=(self._proc,), name="music-player-pump", daemon=True+ ).start()+ if getattr(self._proc, "stderr", None) is not None:+ threading.Thread(+ target=self._pump_stderr,+ args=(self._proc,),+ name="music-player-stderr",+ daemon=True,+ ).start()+ if not self._ready.wait(timeout):+ if self._unavailable_reason:+ log.info("music player host unavailable: %s", self._unavailable_reason)+ else:+ log.warning("music player host not ready within %.0fs", timeout)+ self.stop()+ return False+ atexit.register(self.stop)+ return True++ def stop(self) -> None:+ proc = self._proc+ self._proc = None+ self._ready.clear()+ if proc is None:+ return+ try:+ if proc.poll() is None:+ try:+ proc.stdin.write(json.dumps({"id": 0, "cmd": "quit"}) + "\n")+ proc.stdin.flush()+ except Exception as exc: # noqa: BLE001 — a closed pipe means it is already going+ log.debug("music player quit write: %s", exc)+ try:+ proc.wait(timeout=5)+ except Exception: # noqa: BLE001 — then it gets killed+ proc.kill()+ except Exception as exc: # noqa: BLE001 — teardown must never raise+ log.debug("music player stop: %s", exc)++ # -- transport --------------------------------------------------------------++ def _pump(self, proc: Any) -> None:+ try:+ for raw in proc.stdout:+ line = raw.strip()+ if not line:+ continue+ try:+ msg = json.loads(line)+ except ValueError: # a stray non-protocol line from the host: skip it+ continue+ if "event" in msg:+ if msg["event"] == "ready":+ self._ready.set()+ elif msg["event"] == "unavailable":+ self._unavailable_reason = (+ "The background player could not start here: "+ f"{msg.get('error') or 'no GUI backend'}."+ )+ with self._cond:+ self._events.append(msg)+ self._cond.notify_all()+ continue+ with self._cond:+ self._replies[int(msg.get("id") or 0)] = msg+ self._cond.notify_all()+ except Exception as exc: # noqa: BLE001 — a dead pipe ends the pump, nothing else+ log.debug("music player pump ended: %s", exc)+ finally:+ self._ready.clear()+ with self._cond:+ self._cond.notify_all()++ @staticmethod+ def _pump_stderr(proc: Any) -> None:+ try:+ for raw in proc.stderr:+ line = raw.rstrip()+ if line:+ log.debug("music player host: %s", line)+ except Exception as exc: # noqa: BLE001 — a dead pipe ends the pump+ log.debug("music player stderr pump ended: %s", exc)++ def request(self, cmd: str, *, timeout: float = _REQUEST_TIMEOUT_S, **kw: Any) -> Any:+ """One command → its result. Raises :class:`MusicPlayerError`."""+ if not self.is_running() and not self.start():+ ok, why = self.available()+ raise MusicPlayerError(why or self._unavailable_reason or "player did not start")+ with self._lock:+ self._next_id += 1+ req_id = self._next_id+ payload = json.dumps({"id": req_id, "cmd": cmd, **kw}, ensure_ascii=False)+ proc = self._proc+ if proc is None:+ raise MusicPlayerError("player is not running")+ try:+ proc.stdin.write(payload + "\n")+ proc.stdin.flush()+ except Exception as exc: # noqa: BLE001 — pipe gone → the host is gone+ self.stop()+ raise MusicPlayerError(f"player went away: {exc}") from exc+ deadline = timeout+ with self._cond:+ while req_id not in self._replies:+ if not self._cond.wait(deadline):+ raise MusicPlayerError(f"player did not answer '{cmd}' in {timeout:.0f}s")+ if not self._ready.is_set() and req_id not in self._replies:+ raise MusicPlayerError("player exited")+ reply = self._replies.pop(req_id)+ if not reply.get("ok"):+ raise MusicPlayerError(str(reply.get("error") or f"'{cmd}' failed"))+ return reply.get("result")++ # -- commands ---------------------------------------------------------------++ def load(self, url: str) -> bool:+ return bool(self.request("load", url=url))++ def state(self) -> dict[str, Any]:+ result = self.request("state")+ return result if isinstance(result, dict) else {}++ def play(self) -> bool:+ return bool(self.request("play"))++ def pause(self) -> bool:+ return bool(self.request("pause"))++ def toggle(self) -> bool:+ return bool(self.request("toggle"))++ def next(self) -> bool:+ return bool(self.request("next"))++ def previous(self) -> bool:+ return bool(self.request("previous"))++ def set_volume(self, level: int) -> bool:+ return bool(self.request("volume", level=int(level)))++ def show(self) -> bool:+ return bool(self.request("show"))++ def hide(self) -> bool:+ return bool(self.request("hide"))+++_PLAYER: MusicPlayer | None = None+_PLAYER_LOCK = threading.Lock()+++def get_music_player() -> MusicPlayer:+ """The process-wide player (one hidden window per Jarvis)."""+ global _PLAYER+ with _PLAYER_LOCK:+ if _PLAYER is None:+ _PLAYER = MusicPlayer()+ return _PLAYER+++def background_player_available() -> bool:+ return get_music_player().available()[0]+++__all__ = [+ "MusicPlayer",+ "MusicPlayerError",+ "background_player_available",+ "get_music_player",+]diff --git a/jarvis/platform/music_player_host.py b/jarvis/platform/music_player_host.pynew file mode 100644index 0000000000..a276fd472d--- /dev/null+++ b/jarvis/platform/music_player_host.py@@ -0,0 +1,258 @@+"""Companion process hosting the background music player window.++``python -m jarvis.platform.music_player_host --storage <dir> --title <title>``++A pywebview window that starts MINIMIZED (a taskbar entry, no focus, no tab —+and unlike a truly hidden window, WebView2 does start media in it), keeps its+own persistent browser profile (so a YouTube Music login survives restarts),+and takes JSON-line commands on stdin — ``load`` a URL, ``show`` / ``hide`` the window, read the+player ``state``, ``pause`` / ``play`` / ``next`` / ``previous`` / ``volume``+— answering one JSON line per command on stdout. Playback therefore happens+in the background: no browser tab, no focus steal, one window that navigates+instead of piling up tabs.++Why its own process rather than a window in the desktop shell: pywebview+holds one browser profile per process, and the shell runs in private mode on+purpose. This host runs a second, persistent profile without touching that,+works the same from ``--headless`` mode as long as a display exists, and dies+with its parent — stdin EOF is the lifeline, so a crashed Jarvis never leaves a+ghost player behind.++Autoplay: a hidden window never sees a user gesture, so on Windows the+WebView2 environment is asked to allow autoplay outright (the documented+``WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS`` override, set before the runtime is+created). Other backends fall back to reporting "not playing", which the tool+turns into showing the window with an honest "press play once".++Never imported by Jarvis proper (HN-7): the parent talks to it over pipes via+``jarvis.platform.music_player``.+"""+from __future__ import annotations++import argparse+import json+import os+import sys+from typing import Any++# What the tool needs from the page: the media-session metadata YouTube Music+# publishes plus the <video> element's transport state. Pure DOM, no login.+_STATE_JS = """+(() => {+ const v = document.querySelector('video');+ const m = (navigator.mediaSession && navigator.mediaSession.metadata) || null;+ const t = document.title || '';+ return JSON.stringify({+ url: location.href,+ title: m ? m.title : (t.replace(/\\s*[|\\-]\\s*YouTube Music\\s*$/, '') || ''),+ artist: m ? m.artist : '',+ album: m ? m.album : '',+ has_video: !!v,+ paused: v ? v.paused : null,+ ended: v ? v.ended : null,+ position: v ? v.currentTime : null,+ duration: v && isFinite(v.duration) ? v.duration : null,+ volume: v ? Math.round(v.volume * 100) : null,+ ready: !!document.querySelector('ytmusic-player-bar'),+ consent: /consent\\.(youtube|google)\\./.test(location.hostname),+ signed_in: !!document.querySelector(+ 'ytmusic-settings-button, ytmusic-nav-bar #right-content img'),+ });+})()+"""++# YouTube Music's player-bar buttons. The <video> element itself is the+# reliable play/pause surface; next/previous only exist as buttons.+_JS = {+ "play": (+ "(() => { const v = document.querySelector('video'); if (!v) return false; "+ "v.play(); return true; })()"+ ),+ "pause": (+ "(() => { const v = document.querySelector('video'); if (!v) return false; "+ "v.pause(); return true; })()"+ ),+ "toggle": (+ "(() => { const v = document.querySelector('video'); if (!v) return false; "+ "if (v.paused) v.play(); else v.pause(); return true; })()"+ ),+ "next": (+ "(() => { const b = document.querySelector('ytmusic-player-bar .next-button, "+ "ytmusic-player-bar tp-yt-paper-icon-button.next-button, .next-button'); "+ "if (!b) return false; b.click(); return true; })()"+ ),+ "previous": (+ "(() => { const b = document.querySelector('ytmusic-player-bar .previous-button, "+ "ytmusic-player-bar tp-yt-paper-icon-button.previous-button, .previous-button'); "+ "if (!b) return false; b.click(); return true; })()"+ ),+}+++def _volume_js(level: int) -> str:+ frac = max(0, min(int(level), 100)) / 100.0+ # Drive YouTube Music's own slider when it is there (it re-applies its+ # value on every track change), and the element directly as the fallback.+ return (+ "(() => { const v = document.querySelector('video'); "+ "const s = document.querySelector('ytmusic-player-bar #volume-slider'); "+ f"if (s) {{ s.value = {int(frac * 100)}; "+ "s.dispatchEvent(new CustomEvent('change', {bubbles: true})); } "+ f"if (v) v.volume = {frac}; return !!(v || s); }})()"+ )+++def _log(text: str) -> None:+ """Diagnostics go to stderr; stdout is the protocol channel."""+ sys.stderr.write(text + "\n")+ sys.stderr.flush()+++def _emit(payload: dict[str, Any]) -> None:+ sys.stdout.write(json.dumps(payload, ensure_ascii=False) + "\n")+ sys.stdout.flush()+++def _serve(window: Any) -> None:+ """Command loop on a worker thread — every window call marshals to the UI+ thread inside pywebview, so this thread only ever blocks on stdin."""+ _emit({"event": "ready"})+ for raw in sys.stdin:+ line = raw.strip()+ if not line:+ continue+ try:+ msg = json.loads(line)+ except ValueError:+ _emit({"id": None, "ok": False, "error": "bad json"})+ continue+ req_id = msg.get("id")+ cmd = str(msg.get("cmd") or "")+ try:+ result = _dispatch(window, cmd, msg)+ except Exception as exc: # noqa: BLE001 — one bad command must not kill the player+ _emit({"id": req_id, "ok": False, "error": f"{type(exc).__name__}: {exc}"})+ continue+ if cmd == "quit":+ _emit({"id": req_id, "ok": True})+ break+ _emit({"id": req_id, "ok": True, "result": result})+ # stdin closed (parent gone or asked to quit): the caller takes the window+ # down so webview.start() returns and the process ends.+++def _dispatch(window: Any, cmd: str, msg: dict[str, Any]) -> Any:+ if cmd == "load":+ window.load_url(str(msg.get("url") or "about:blank"))+ return True+ if cmd == "show":+ # Bring the (minimized) player forward for the user to log in, pick a+ # cookie choice, or press play once.+ try:+ window.restore()+ except Exception as exc: # noqa: BLE001 — not every backend has restore+ _log(f"restore skipped: {exc}")+ window.show()+ return True+ if cmd == "hide":+ # Minimize, never hide: WebView2 does not start media in a window that+ # has never been visible (measured 2026-08-18: position stayed at 0+ # while hidden, advanced the moment the window was shown), and a+ # minimized window keeps playing. The taskbar entry is the "background".+ try:+ window.minimize()+ except Exception as exc: # noqa: BLE001 — a backend without minimize hides instead+ _log(f"minimize skipped, hiding: {exc}")+ window.hide()+ return True+ if cmd == "state":+ raw = window.evaluate_js(_STATE_JS)+ return json.loads(raw) if isinstance(raw, str) else raw+ if cmd == "eval":+ return window.evaluate_js(str(msg.get("js") or ""))+ if cmd == "volume":+ return window.evaluate_js(_volume_js(int(msg.get("level") or 0)))+ if cmd in _JS:+ return window.evaluate_js(_JS[cmd])+ if cmd == "quit":+ return True+ raise ValueError(f"unknown command {cmd!r}")+++def main(argv: list[str] | None = None) -> int:+ parser = argparse.ArgumentParser(description="Background music player host")+ parser.add_argument("--storage", required=True, help="persistent browser profile dir")+ parser.add_argument("--title", default="Music", help="window title")+ parser.add_argument(+ "--start",+ choices=("minimized", "hidden", "offscreen", "visible"),+ default="minimized",+ help="initial window state (minimized plays from the start; hidden does not)",+ )+ args = parser.parse_args(argv)++ # Must be in the environment before the WebView2 runtime is created.+ flag = "--autoplay-policy=no-user-gesture-required"+ existing = os.environ.get("WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS", "")+ if flag not in existing:+ os.environ["WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS"] = f"{existing} {flag}".strip()++ try:+ import webview # noqa: PLC0415 — [desktop] extra, never module-level+ except Exception as exc: # noqa: BLE001 — the parent reads this line and degrades+ _emit({"event": "unavailable", "error": f"{type(exc).__name__}: {exc}"})+ return 2++ os.makedirs(args.storage, exist_ok=True)+ extra: dict[str, Any] = {}+ if args.start == "hidden":+ extra["hidden"] = True+ elif args.start == "minimized":+ extra["minimized"] = True+ elif args.start == "offscreen":+ extra["x"] = -32000+ extra["y"] = -32000+ window = webview.create_window(+ args.title,+ "about:blank",+ width=1080,+ height=720,+ min_size=(720, 480),+ confirm_close=False,+ **extra,+ )++ quitting = {"flag": False}++ def _on_closing() -> bool:+ # The user's X minimizes the player instead of ending playback; only+ # the parent's quit (or its death) really closes the window.+ if quitting["flag"]:+ return True+ try:+ window.minimize()+ except Exception as exc: # noqa: BLE001 — minimizing a dying window is fine+ _log(f"minimize on close skipped: {exc}")+ return False++ window.events.closing += _on_closing++ def _serve_then_quit() -> None:+ _serve(window)+ quitting["flag"] = True+ try:+ window.destroy()+ except Exception as exc: # noqa: BLE001 — already gone is fine+ _log(f"destroy skipped: {exc}")++ try:+ # pywebview runs ``func`` on its own worker thread once the GUI loop is up.+ webview.start(func=_serve_then_quit, private_mode=False, storage_path=args.storage)+ except Exception as exc: # noqa: BLE001 — no GUI backend here (Linux without GTK/Qt)+ _emit({"event": "unavailable", "error": f"{type(exc).__name__}: {exc}"})+ return 2+ return 0+++if __name__ == "__main__":+ sys.exit(main())diff --git a/jarvis/plugins/tool/spotify_rest.py b/jarvis/plugins/tool/spotify_rest.pyindex ee99a86e6a..935b583d8c 100644--- a/jarvis/plugins/tool/spotify_rest.py+++ b/jarvis/plugins/tool/spotify_rest.py@@ -84,6 +84,20 @@ async def _default_refresher(observed_access_token: str | None = None) -> bool:return attempt.usable+def _preference_hint_for(service_id: str) -> str:+ """One sentence about ``[music] preferred_service`` for the tool description,+ empty when there is nothing to say. Never raises (a description must not)."""+ try:+ from jarvis.core.config import load_config+ from jarvis.core.music_service import connected_music_services, preference_hint++ preferred = str(load_config().music.preferred_service)+ connected = connected_music_services()+ return preference_hint(service_id, preferred=preferred, connected=connected)+ except Exception: # noqa: BLE001 — a config/store fault means no hint, not no tool+ return ""++def _artists(item: dict[str, Any]) -> str:names = [a.get("name") for a in item.get("artists") or [] if a.get("name")]return ", ".join(n for n in names if n)@@ -143,7 +157,7 @@ def _summarize_playback(state: dict[str, Any]) -> dict[str, Any]:class SpotifyRestTool:name: str = "spotify"risk_tier: str = "monitor"- description: str = (+ _BASE_DESCRIPTION: str = ("Play and control the user's Spotify: start a song, artist, album or ""playlist, pause, skip, go back, set the volume, queue something up, or ""say what is currently playing. Use for 'play Radiohead', 'skip this "@@ -153,6 +167,14 @@ class SpotifyRestTool:"Requires the Spotify plugin to be connected in the Plugins view; ""controlling playback needs Spotify Premium.")++ @property+ def description(self) -> str:+ """The static description plus the user's music preference (see+ ``jarvis.core.music_service``): with YouTube Music also connected, the+ LLM router must send an unnamed music request where the setting says."""+ return self._BASE_DESCRIPTION + _preference_hint_for(self.name)+schema: dict[str, Any] = {"type": "object","properties": {diff --git a/jarvis/plugins/tool/youtube_music_rest.py b/jarvis/plugins/tool/youtube_music_rest.pyindex f0d1e51e73..c47fe5033c 100644--- a/jarvis/plugins/tool/youtube_music_rest.py+++ b/jarvis/plugins/tool/youtube_music_rest.py@@ -83,6 +83,24 @@ _NO_SESSION_READ = ("Nothing is registered as playing on this machine, so there is nothing to ""report or control here.")+_PLAYER_APP = "the background player"+_VOLUME_NEEDS_PLAYER = (+ "Volume can only be set for the background player. Whatever plays elsewhere "+ "keeps its own volume — use the system or app volume there."+)+_CONSENT_NOTE = (+ "YouTube asks for your cookie choice once before it plays — the player "+ "window just opened for that; pick, and it is remembered."+)+_PRESS_PLAY_NOTE = (+ "The player opened the song but did not start — press play once in the "+ "player window that just opened; after that it starts on its own."+)++# How long `play` watches the background player before it stops claiming to+# know. A page load plus buffering takes four to five seconds (measured+# 2026-08-18: position starts advancing ~4.5 s after load).+_PLAYER_CONFIRM_TIMEOUT_S = 9.0# Music category on YouTube. Songs on YouTube Music are videos in it._MUSIC_CATEGORY_ID = "10"@@ -140,6 +158,27 @@ def _default_opener(url: str) -> bool:return open_url(url)+def _default_playback_mode() -> str:+ """``[music] playback`` — where YouTube Music plays (background | browser)."""+ from jarvis.core.config import load_config++ return str(load_config().music.playback)+++def _preference_hint_for(service_id: str) -> str:+ """One sentence about ``[music] preferred_service`` for a tool description,+ empty when there is nothing to say. Never raises (a description must not)."""+ try:+ from jarvis.core.config import load_config+ from jarvis.core.music_service import connected_music_services, preference_hint++ preferred = str(load_config().music.preferred_service)+ connected = connected_music_services()+ return preference_hint(service_id, preferred=preferred, connected=connected)+ except Exception: # noqa: BLE001 — a config/store fault means no hint, not no tool+ return ""++def _clean(text: Any) -> str:return html.unescape(str(text or "")).strip()@@ -227,7 +266,7 @@ def _slim_video(item: dict[str, Any]) -> dict[str, Any]:class YouTubeMusicRestTool:name: str = "youtube_music"risk_tier: str = "monitor"- description: str = (+ _BASE_DESCRIPTION: str = ("Play and control the user's YouTube Music: start a song, artist, album, ""one of their playlists or their liked songs (opens in YouTube Music in the ""browser and keeps playing like a radio), pause, resume, skip, go back, say "@@ -236,10 +275,19 @@ class YouTubeMusicRestTool:"'skip this', 'what song is this', 'pause the music', 'like this song', ""'add this to my running playlist'. Actions: now_playing, play, pause, ""next, previous, search, list_playlists, playlist_tracks, liked_songs, "- "like, add_to_playlist, create_playlist, open. Requires the YouTube Music "- "plugin to be connected in the Plugins view. Volume is not controllable "- "here — use the system or app volume."+ "like, add_to_playlist, create_playlist, open (show the player), "+ "hide_player, set_volume. Music plays in a background player window "+ "(or the browser, per the Settings), so 'set_volume' works there. "+ "Requires the YouTube Music plugin to be connected in the Plugins view.")++ @property+ def description(self) -> str:+ """The static description plus the user's music preference, so the+ LLM router makes the same Spotify-vs-YouTube Music choice the skill+ capture does (one resolver, ``jarvis.core.music_service``)."""+ return self._BASE_DESCRIPTION + _preference_hint_for(self.name)+schema: dict[str, Any] = {"type": "object","properties": {@@ -259,6 +307,8 @@ class YouTubeMusicRestTool:"add_to_playlist","create_playlist","open",+ "hide_player",+ "set_volume",],"default": "now_playing",},@@ -291,6 +341,10 @@ class YouTubeMusicRestTool:"description": "for like: 'none' removes an earlier like or dislike",},"limit": {"type": "integer", "default": 5, "description": "results, max 25"},+ "volume_percent": {+ "type": "integer",+ "description": "0-100, for set_volume (background player only)",+ },},"required": ["action"],}@@ -303,6 +357,9 @@ class YouTubeMusicRestTool:media: Any | None = None,opener: Callable[[str], bool] | None = None,confirm_timeout_s: float = _CONFIRM_TIMEOUT_S,+ player: Any | None = None,+ playback_mode: Callable[[], str] | None = None,+ player_confirm_timeout_s: float = _PLAYER_CONFIRM_TIMEOUT_S,) -> None:from ._http_pool import HttpClientPool@@ -311,6 +368,11 @@ class YouTubeMusicRestTool:self._media = mediaself._opener = opener or _default_openerself._confirm_timeout_s = confirm_timeout_s+ # The background player (jarvis.platform.music_player) and the setting+ # that says whether to use it; both injectable so tests use fakes.+ self._player = player+ self._playback_mode = playback_mode or _default_playback_mode+ self._player_confirm_timeout_s = player_confirm_timeout_sself._pool = HttpClientPool(transport=transport)# search.list is the rationed call (100/day). Same words → same answer# within a session, so a repeat costs nothing.@@ -328,6 +390,172 @@ class YouTubeMusicRestTool:async def _capability(self) -> Any:return await self._media_controller().capability()+ # -- background player ------------------------------------------------------++ def _player_client(self) -> Any:+ if self._player is None:+ from jarvis.platform.music_player import get_music_player++ self._player = get_music_player()+ return self._player++ def _wants_player(self) -> bool:+ try:+ return str(self._playback_mode()) == "background"+ except Exception: # noqa: BLE001 — a config fault means the browser path+ return False++ async def _player_state(self) -> dict[str, Any] | None:+ """The background player's page state, or None when it is not running+ or does not answer. Never raises."""+ player = self._player_client()+ if not player.is_running():+ return None+ try:+ return await asyncio.to_thread(player.state)+ except Exception as exc: # noqa: BLE001 — a dead player reads as "not running"+ log.debug("background player state failed: %s", exc)+ return None++ @staticmethod+ def _player_now(state: dict[str, Any]) -> dict[str, Any]:+ out: dict[str, Any] = {+ "is_playing": bool(state.get("has_video")) and state.get("paused") is False,+ "status": "playing"+ if state.get("has_video") and state.get("paused") is False+ else "paused",+ "track": str(state.get("title") or ""),+ "artist": str(state.get("artist") or ""),+ "app": _PLAYER_APP,+ "source": "background_player",+ }+ if state.get("album"):+ out["album"] = state["album"]+ if isinstance(state.get("position"), int | float):+ out["position_s"] = round(float(state["position"]))+ if isinstance(state.get("duration"), int | float) and state["duration"]:+ out["duration_s"] = round(float(state["duration"]))+ if isinstance(state.get("volume"), int | float):+ out["volume_percent"] = int(state["volume"])+ return out++ async def _play_in_player(self, url: str, started: dict[str, Any] | None) -> dict[str, Any]:+ """Load the deep link into the background player and watch it start.++ Three outcomes, each said plainly: playing (with what plays), YouTube's+ one-time cookie choice or a login wall (the window comes forward for+ it), or a start that did not happen (the window comes forward with+ "press play once"). Raises MusicPlayerError only when the player itself+ is unusable, so the caller can fall back to the browser."""+ player = self._player_client()+ await asyncio.to_thread(player.load, url)+ out: dict[str, Any] = {"ok": True, "url": url, "sink": "background_player"}+ if started:+ out["started"] = started+ elapsed = 0.0+ last: dict[str, Any] = {}+ nudged = False+ while elapsed < self._player_confirm_timeout_s:+ await asyncio.sleep(_CONFIRM_STEP_S)+ elapsed += _CONFIRM_STEP_S+ try:+ last = await asyncio.to_thread(player.state)+ except Exception as exc: # noqa: BLE001 — a blink while the page turns+ log.debug("background player state during confirm: %s", exc)+ continue+ if last.get("consent"):+ await asyncio.to_thread(player.show)+ out.update(playback_confirmed=False, needs_attention="consent", note=_CONSENT_NOTE)+ return out+ playing = last.get("has_video") and last.get("paused") is False+ if playing and (last.get("position") or 0) > 0:+ out.update(playback_confirmed=True, now=self._player_now(last))+ return out+ # The page is up but paused: one programmatic nudge before asking+ # the user (autoplay may be allowed but the player idle).+ if last.get("ready") and last.get("has_video") and last.get("paused") and not nudged:+ nudged = True+ try:+ await asyncio.to_thread(player.play)+ except Exception as exc: # noqa: BLE001 — the nudge is best-effort+ log.debug("background player nudge failed: %s", exc)+ try:+ await asyncio.to_thread(player.show)+ except Exception as exc: # noqa: BLE001 — showing is best-effort+ log.debug("background player show failed: %s", exc)+ out.update(playback_confirmed=False, needs_attention="press_play", note=_PRESS_PLAY_NOTE)+ if last:+ out["now"] = self._player_now(last)+ return out++ async def _start_playback(self, url: str, started: dict[str, Any] | None) -> dict[str, Any]:+ """Where music comes out: the background player when the setting asks+ for it and this host can run it, else the system browser."""+ if self._wants_player():+ player = self._player_client()+ try:+ ok, why = await asyncio.to_thread(player.available)+ except Exception as exc: # noqa: BLE001 — a probe fault means the browser path+ ok, why = False, str(exc)+ if ok:+ try:+ return await self._play_in_player(url, started)+ except Exception as exc: # noqa: BLE001 — player unusable → browser, and say so+ log.info("background player unusable, opening the browser: %s", exc)+ why = f"The background player could not start ({exc})."+ out = await self._open_and_confirm(url, started)+ out["sink"] = "browser"+ if why:+ out["fallback_reason"] = why+ return out+ out = await self._open_and_confirm(url, started)+ out["sink"] = "browser"+ return out++ async def set_volume(self, *, volume_percent: int) -> dict[str, Any]:+ level = max(0, min(int(volume_percent), 100))+ state = await self._player_state()+ if not state or not state.get("has_video"):+ return {"error": _VOLUME_NEEDS_PLAYER}+ try:+ ok = await asyncio.to_thread(self._player_client().set_volume, level)+ except Exception as exc: # noqa: BLE001 — a dead player is an honest error+ return {"error": f"The background player did not take the volume: {exc}"}+ if not ok:+ return {"error": _VOLUME_NEEDS_PLAYER}+ return {"ok": True, "volume_percent": level, "app": _PLAYER_APP}++ async def show_player(self) -> dict[str, Any]:+ """Bring the background player forward (log in, cookie choice, look at+ the queue). Starts it on the home page when it is not running yet."""+ if not self._wants_player():+ return await self._open_browser_home()+ player = self._player_client()+ try:+ ok, why = await asyncio.to_thread(player.available)+ if not ok:+ out = await self._open_browser_home()+ out["fallback_reason"] = why+ return out+ if not player.is_running():+ await asyncio.to_thread(player.load, HOME_URL)+ await asyncio.to_thread(player.show)+ except Exception as exc: # noqa: BLE001 — player unusable → browser, and say so+ out = await self._open_browser_home()+ out["fallback_reason"] = f"The background player could not start ({exc})."+ return out+ return {"ok": True, "shown": True, "app": _PLAYER_APP}++ async def hide_player(self) -> dict[str, Any]:+ state = await self._player_state()+ if state is None:+ return {"ok": True, "hidden": False, "message": "The background player is not running."}+ try:+ await asyncio.to_thread(self._player_client().hide)+ except Exception as exc: # noqa: BLE001 — a dead player is already hidden+ return {"ok": True, "hidden": False, "message": str(exc)}+ return {"ok": True, "hidden": True}+# -- HTTP -----------------------------------------------------------------def _bearer(self) -> dict[str, str] | None:@@ -463,6 +691,18 @@ class YouTubeMusicRestTool:# -- public actions ------------------------------------------------------async def now_playing(self) -> dict[str, Any]:+ state = await self._player_state()+ if state and state.get("consent"):+ # The player is parked on YouTube's cookie-choice page: nothing plays+ # there, and its title is not a song.+ return {+ "is_playing": False,+ "app": _PLAYER_APP,+ "needs_attention": "consent",+ "message": _CONSENT_NOTE,+ }+ if state and state.get("has_video"):+ return self._player_now(state)media = self._media_controller()cap = await media.capability()entry = await media.now_playing() if cap.can_read else None@@ -482,6 +722,25 @@ class YouTubeMusicRestTool:return outasync def _control(self, verb: str) -> dict[str, Any]:+ state = await self._player_state()+ if state and state.get("has_video"):+ player = self._player_client()+ try:+ ok = bool(await asyncio.to_thread(getattr(player, verb)))+ except Exception as exc: # noqa: BLE001 — a dead player is an honest error+ return {"error": f"The background player did not accept '{verb}': {exc}"}+ if not ok:+ return {"error": f"The background player did not accept '{verb}'."}+ via_player: dict[str, Any] = {"ok": True, "action": verb, "app": _PLAYER_APP}+ if verb in ("next", "previous"):+ await asyncio.sleep(1.2)+ after = await self._player_state()+ if after:+ via_player["now"] = self._player_now(after)+ else:+ via_player["track"] = str(state.get("title") or "")+ via_player["artist"] = str(state.get("artist") or "")+ return via_playermedia = self._media_controller()cap = await media.capability()if not cap.can_control:@@ -608,18 +867,18 @@ class YouTubeMusicRestTool:if kind == "liked":liked = await self._liked(headers, 1)if not liked:- return await self._open_and_confirm(+ return await self._start_playback(LIKED_PAGE_URL, {"type": "liked", "title": "Liked songs"})first = liked[0]- return await self._open_and_confirm(+ return await self._start_playback(playlist_url("LM", first["video_id"]),{"type": "liked", "title": "Liked songs", "first": first},)if kind == "playlist":mine = await self._resolve_playlist(headers, query)if mine is not None:- return await self._open_and_confirm(+ return await self._start_playback(mine["url"], {"type": "playlist", "own": True, **mine})hits = await self._search_raw(headers, query=query, kind="playlist", limit=1)@@ -627,13 +886,13 @@ class YouTubeMusicRestTool:return {"error": f"No playlist called {query!r} — neither yours nor a public one."}- return await self._open_and_confirm(hits[0]["url"], hits[0])+ return await self._start_playback(hits[0]["url"], hits[0])if kind == "album":hits = await self._search_raw(headers, query=query, kind="album", limit=3)albums = [h for h in hits if h.get("type") == "album"] or hitsif not albums:return {"error": f"YouTube Music has no album called {query!r}."}- return await self._open_and_confirm(albums[0]["url"], albums[0])+ return await self._start_playback(albums[0]["url"], albums[0])# song or artist: top song, then its radio keeps the artist's world goinghits = await self._search_raw(headers, query=query, kind="song", limit=1)if not hits:@@ -641,15 +900,21 @@ class YouTubeMusicRestTool:started = dict(hits[0])if kind == "artist":started["note"] = "Started the artist's top song; the radio continues with them."- return await self._open_and_confirm(started["url"], started)+ return await self._start_playback(started["url"], started)return await self._with_auth_retry(_do)- async def open_home(self) -> dict[str, Any]:+ async def _open_browser_home(self) -> dict[str, Any]:opened = self._opener(HOME_URL)if not opened:return {"error": _NO_BROWSER, "url": HOME_URL}- return {"ok": True, "url": HOME_URL}+ return {"ok": True, "url": HOME_URL, "sink": "browser"}++ async def open_home(self) -> dict[str, Any]:+ """"Open YouTube Music": the background player comes forward (that is+ where a login or cookie choice happens), or the browser when the+ setting says so / the player cannot run here."""+ return await self.show_player()async def list_playlists(self) -> dict[str, Any]:async def _do(headers: dict[str, str]) -> dict[str, Any]:@@ -781,8 +1046,8 @@ class YouTubeMusicRestTool:if action in ("now_playing", "search", "list_playlists", "playlist_tracks", "liked_songs"):return "safe"if action in (- "play", "pause", "next", "previous", "open", "like",- "add_to_playlist", "create_playlist",+ "play", "pause", "next", "previous", "open", "hide_player", "set_volume",+ "like", "add_to_playlist", "create_playlist",):return "monitor"return "ask"@@ -827,6 +1092,13 @@ class YouTubeMusicRestTool:out = await self.create_playlist(name=playlist or query)elif action == "open":out = await self.open_home()+ elif action == "hide_player":+ out = await self.hide_player()+ elif action == "set_volume":+ level = args.get("volume_percent")+ if level is None:+ return ToolResult(success=False, output=None, error="volume_percent missing")+ out = await self.set_volume(volume_percent=int(level))else:return ToolResult(success=False, output=None, error=f"unknown action {action!r}")except Exception as exc: # noqa: BLE001 — every failure becomes a spoken, actionable errordiff --git a/jarvis/skills/builtin/plugin-youtube_music/SKILL.md b/jarvis/skills/builtin/plugin-youtube_music/SKILL.mdindex 14e922b579..6c8bc88206 100644--- a/jarvis/skills/builtin/plugin-youtube_music/SKILL.md+++ b/jarvis/skills/builtin/plugin-youtube_music/SKILL.md@@ -20,8 +20,9 @@ Use the connected YouTube Music to play and steer the user's music.- Play by name, not by id: pass what the user said as `query` and set `type` to what they meant — `song`, `artist`, `album`, `playlist` for "my running playlist", `liked` for "my liked songs". The tool searches and opens the top hit in YouTube Music in one step; a song opens as its own radio so playback continues.- "Play" with no name resumes what is paused. Do not search for something to fill the gap.- Say what actually started. The result carries the track and artist YouTube matched, which is often not literally what the user said — reporting it is how they catch a wrong hit immediately.-- YouTube Music plays in the browser, not in this app. When the result says playback is not confirmed, ask the user to press play once — browsers block autoplay on a site until it has been used there. It is not an error and not a broken connection.-- Pause, next, previous and "what is playing" go through the system's media session. If the result names another app (Spotify, a YouTube video), report that honestly. If the machine cannot control playback, say what the result says would fix it (playerctl on Linux, nowplaying-cli on macOS).-- Volume cannot be changed here. Say so and point to the system or app volume.+- Music plays in a background player window (default) or in the browser, per the user's Settings — never in this app's own audio. When the result carries `needs_attention` (YouTube's one-time cookie choice, or a player that did not start), the player window has already come forward: tell the user in one sentence what to do there. It is not an error and not a broken connection.+- Pause, next, previous, volume and "what is playing" steer the background player when it runs, else the system's media session. If the result names another app (Spotify, a YouTube video), report that honestly. If the machine cannot control playback, say what the result says would fix it (playerctl on Linux, nowplaying-cli on macOS).+- Volume works in the background player (`set_volume`, 0-100). Elsewhere it cannot be changed here — say so and point to the system or app volume.+- "Open YouTube Music" / "show the player" → `open` brings the player forward (that is where the user logs in once); "hide the player" → `hide_player`.- "Like this", "add this to my X playlist": call without a `query` to act on the song playing now; the result names the song that was actually liked or added.- Google allows 100 searches a day for this app. When they are used up, say so plainly and offer what still works: their own playlists, pause, skip, what is playing.diff --git a/jarvis/ui/web/frontend/src/hooks/useMusicSettings.ts b/jarvis/ui/web/frontend/src/hooks/useMusicSettings.tsnew file mode 100644index 0000000000..46e268eede--- /dev/null+++ b/jarvis/ui/web/frontend/src/hooks/useMusicSettings.ts@@ -0,0 +1,65 @@+import { useCallback, useEffect, useState } from "react";+import type {+ MusicPlaybackMode,+ MusicService,+ MusicSettings,+} from "@/lib/musicSettings";++/** Preferred music service + where YouTube Music plays (`[music]`). */+export interface MusicSettingsResult {+ ok: boolean;+ preferred_service: MusicService;+ playback: MusicPlaybackMode;+ persisted: boolean;+}++export function useMusicSettings() {+ const [settings, setSettings] = useState<MusicSettings | null>(null);+ const [loading, setLoading] = useState(true);+ const [error, setError] = useState<string | null>(null);++ const refetch = useCallback(async () => {+ setError(null);+ try {+ const res = await fetch("/api/settings/music");+ if (!res.ok) throw new Error(`HTTP ${res.status}`);+ setSettings((await res.json()) as MusicSettings);+ } catch (e) {+ setError((e as Error).message);+ } finally {+ setLoading(false);+ }+ }, []);++ useEffect(() => {+ void refetch();+ }, [refetch]);++ const save = useCallback(+ async (patch: {+ preferred_service?: MusicService;+ playback?: MusicPlaybackMode;+ }): Promise<MusicSettingsResult> => {+ const res = await fetch("/api/settings/music", {+ method: "PUT",+ headers: { "Content-Type": "application/json" },+ body: JSON.stringify(patch),+ });+ const body = await res.json().catch(() => ({}));+ if (!res.ok) throw new Error(body.detail ?? `HTTP ${res.status}`);+ setSettings((prev) =>+ prev+ ? {+ ...prev,+ preferred_service: body.preferred_service,+ playback: body.playback,+ }+ : prev,+ );+ return body as MusicSettingsResult;+ },+ [],+ );++ return { settings, loading, error, refetch, save };+}diff --git a/jarvis/ui/web/frontend/src/i18n/locales/de.json b/jarvis/ui/web/frontend/src/i18n/locales/de.jsonindex 7b54984390..0eae5c6d20 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/de.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/de.json@@ -1636,6 +1636,35 @@"subtitle": "Wake-Word, Hotkeys, Safety-Policies, Autostart.","overlay_taskbar_group_title": "Leiste & Overlay","languages_group_title": "Sprachen",+ "music_group_title": "Musik",+ "music": {+ "service_section": "Bevorzugter Dienst",+ "service_hint": "Wohin eine Musik-Anfrage geht, wenn du keinen Dienst nennst. Ein genannter Dienst („auf Spotify“, „auf YouTube Music“) gewinnt immer.",+ "service_labels": {+ "auto": "Automatisch",+ "spotify": "Spotify",+ "youtube_music": "YouTube Music"+ },+ "service_options": {+ "auto": "Der einzige verbundene Dienst; sind beide verbunden, Spotify.",+ "spotify": "Musik-Anfragen ohne Dienstnamen gehen an Spotify.",+ "youtube_music": "Musik-Anfragen ohne Dienstnamen gehen an YouTube Music."+ },+ "connected": "verbunden",+ "not_connected": "nicht verbunden — unter Plugins verbinden",+ "playback_section": "Wo YouTube Music spielt",+ "playback_hint": "Der Hintergrund-Player ist ein eigenes kleines Fenster, das minimiert startet: kein Browser-Tab, kein Fokusklau, Lautstärke per Stimme. Dort einmal anmelden, um dein Premium zu nutzen.",+ "playback_labels": {+ "background": "Hintergrund-Player",+ "browser": "Browser"+ },+ "playback_options": {+ "background": "Ein minimiertes Player-Fenster; „öffne YouTube Music“ holt es nach vorn.",+ "browser": "Öffnet jedes Mal einen YouTube-Music-Tab im Browser."+ },+ "player_unavailable": "auf diesem Rechner nicht verfügbar (kein Bildschirm oder keine Desktop-Extras); es wird der Browser benutzt",+ "saved_toast": "Musik-Einstellungen gespeichert."+ },"team_proxy": {"title": "Team-Modus (geteilter Schlüssel-Proxy)","hint": "Provider über einen geteilten Schlüssel-Proxy mit persönlichem Token leiten, statt echte Anbieter-Schlüssel auf diesem Gerät zu speichern. Für das normale lokale Setup ausgeschaltet lassen.",diff --git a/jarvis/ui/web/frontend/src/i18n/locales/en.json b/jarvis/ui/web/frontend/src/i18n/locales/en.jsonindex 12c5391897..3ec486894e 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/en.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/en.json@@ -1636,6 +1636,35 @@"subtitle": "Wake-word, hotkeys, safety policies, autostart.","overlay_taskbar_group_title": "Bar & Overlay","languages_group_title": "Languages",+ "music_group_title": "Music",+ "music": {+ "service_section": "Preferred service",+ "service_hint": "Where a music request goes when you do not name a service. Naming one (\"on Spotify\", \"on YouTube Music\") always wins.",+ "service_labels": {+ "auto": "Automatic",+ "spotify": "Spotify",+ "youtube_music": "YouTube Music"+ },+ "service_options": {+ "auto": "The only connected service; with both connected, Spotify.",+ "spotify": "Unnamed music requests go to Spotify.",+ "youtube_music": "Unnamed music requests go to YouTube Music."+ },+ "connected": "connected",+ "not_connected": "not connected — connect it in Plugins",+ "playback_section": "Where YouTube Music plays",+ "playback_hint": "The background player is a small window of its own that starts minimized: no browser tab, no focus steal, and volume control by voice. Log in there once to use your Premium.",+ "playback_labels": {+ "background": "Background player",+ "browser": "Browser"+ },+ "playback_options": {+ "background": "A minimized player window; say \"open YouTube Music\" to bring it forward.",+ "browser": "Opens a YouTube Music tab in your browser each time."+ },+ "player_unavailable": "not available on this machine (no display or no desktop extras); the browser is used instead",+ "saved_toast": "Music settings saved."+ },"team_proxy": {"title": "Team mode (shared key proxy)","hint": "Route providers through a shared key proxy with a per-user token instead of storing real vendor keys on this machine. Leave off for the normal local-key setup.",diff --git a/jarvis/ui/web/frontend/src/i18n/locales/es.json b/jarvis/ui/web/frontend/src/i18n/locales/es.jsonindex 2856fe4afd..ec55c20ffd 100644--- a/jarvis/ui/web/frontend/src/i18n/locales/es.json+++ b/jarvis/ui/web/frontend/src/i18n/locales/es.json@@ -1636,6 +1636,35 @@"subtitle": "Palabra de activación, atajos, políticas de seguridad, inicio automático.","overlay_taskbar_group_title": "Barra y superposición","languages_group_title": "Idiomas",+ "music_group_title": "Música",+ "music": {+ "service_section": "Servicio preferido",+ "service_hint": "A dónde va una petición de música cuando no nombras un servicio. Nombrar uno («en Spotify», «en YouTube Music») siempre gana.",+ "service_labels": {+ "auto": "Automático",+ "spotify": "Spotify",+ "youtube_music": "YouTube Music"+ },+ "service_options": {+ "auto": "El único servicio conectado; con ambos conectados, Spotify.",+ "spotify": "Las peticiones sin nombre de servicio van a Spotify.",+ "youtube_music": "Las peticiones sin nombre de servicio van a YouTube Music."+ },+ "connected": "conectado",+ "not_connected": "no conectado — conéctalo en Plugins",+ "playback_section": "Dónde suena YouTube Music",+ "playback_hint": "El reproductor en segundo plano es una ventana propia que arranca minimizada: sin pestaña del navegador, sin robar el foco y con volumen por voz. Inicia sesión ahí una vez para usar tu Premium.",+ "playback_labels": {+ "background": "Reproductor en segundo plano",+ "browser": "Navegador"+ },+ "playback_options": {+ "background": "Una ventana de reproductor minimizada; «abre YouTube Music» la trae al frente.",+ "browser": "Abre cada vez una pestaña de YouTube Music en el navegador."+ },+ "player_unavailable": "no disponible en este equipo (sin pantalla o sin extras de escritorio); se usa el navegador",+ "saved_toast": "Ajustes de música guardados."+ },"team_proxy": {"title": "Modo equipo (proxy de claves compartido)","hint": "Enruta los proveedores a través de un proxy de claves compartido con un token por usuario, en lugar de guardar las claves reales en este equipo. Déjalo desactivado para la configuración local normal.",diff --git a/jarvis/ui/web/frontend/src/lib/musicSettings.ts b/jarvis/ui/web/frontend/src/lib/musicSettings.tsnew file mode 100644index 0000000000..c3751008f8--- /dev/null+++ b/jarvis/ui/web/frontend/src/lib/musicSettings.ts@@ -0,0 +1,37 @@+/**+ * Music settings vocabulary — the TypeScript mirror (five-layer pattern L4) of+ * `jarvis/core/music_constants.py`. A Python parity test regex-extracts the+ * unions below and fails when they drift from the tuples there, so a value+ * cannot be spelled one way in the config and another in the UI.+ */++/** Which connector a music request that names no service goes to. */+export const MUSIC_SERVICES = ["auto", "spotify", "youtube_music"] as const;+export type MusicService = (typeof MUSIC_SERVICES)[number];++/** Where YouTube Music plays. */+export const MUSIC_PLAYBACK_MODES = ["background", "browser"] as const;+export type MusicPlaybackMode = (typeof MUSIC_PLAYBACK_MODES)[number];++export function isMusicService(value: unknown): value is MusicService {+ return (+ typeof value === "string" && (MUSIC_SERVICES as readonly string[]).includes(value)+ );+}++export function isMusicPlaybackMode(value: unknown): value is MusicPlaybackMode {+ return (+ typeof value === "string" &&+ (MUSIC_PLAYBACK_MODES as readonly string[]).includes(value)+ );+}++/** What GET /api/settings/music answers. */+export interface MusicSettings {+ preferred_service: MusicService;+ playback: MusicPlaybackMode;+ service_options: MusicService[];+ playback_options: MusicPlaybackMode[];+ connected: string[];+ background_player_available: boolean;+}diff --git a/jarvis/ui/web/frontend/src/views/SettingsView.tsx b/jarvis/ui/web/frontend/src/views/SettingsView.tsxindex 34895ce0f5..75be109a24 100644--- a/jarvis/ui/web/frontend/src/views/SettingsView.tsx+++ b/jarvis/ui/web/frontend/src/views/SettingsView.tsx@@ -12,6 +12,7 @@ import { Button } from "@/components/ui/button";import { BrandedSelect } from "@/components/ui/select";import { OverlayTaskbarGroup } from "@/views/settings/OverlayTaskbarGroup";import { LanguagesGroup } from "@/views/settings/LanguagesGroup";+import { MusicGroup } from "@/views/settings/MusicGroup";import { AppSettingsGroup } from "@/views/settings/AppSettingsGroup";import { PermissionsPanel } from "@/views/settings/PermissionsPanel";import { RealtimeVoiceGroup } from "@/views/settings/RealtimeVoiceGroup";@@ -121,6 +122,9 @@ export function SettingsView() {<SettingsGroupBoundary group="audio-devices"><AudioDevicesGroup /></SettingsGroupBoundary>+ <SettingsGroupBoundary group="music">+ <MusicGroup />+ </SettingsGroupBoundary><SettingsGroupBoundary group="keybinds"><KeybindsPanel /></SettingsGroupBoundary>diff --git a/jarvis/ui/web/frontend/src/views/settings/MusicGroup.test.tsx b/jarvis/ui/web/frontend/src/views/settings/MusicGroup.test.tsxnew file mode 100644index 0000000000..08a44e8fe2--- /dev/null+++ b/jarvis/ui/web/frontend/src/views/settings/MusicGroup.test.tsx@@ -0,0 +1,82 @@+import { cleanup, fireEvent, render, screen } from "@testing-library/react";+import { afterEach, describe, expect, it, vi } from "vitest";++// Identity translator so assertions can match exact i18n keys.+vi.mock("@/i18n", () => ({+ useT: () => (key: string) => key,+}));++vi.mock("@/store/events", () => ({+ useEventStore: (selector: (s: { pushToast: () => void }) => unknown) =>+ selector({ pushToast: vi.fn() }),+}));++const save = vi.fn().mockResolvedValue({+ ok: true,+ preferred_service: "youtube_music",+ playback: "background",+ persisted: true,+});+vi.mock("@/hooks/useMusicSettings", () => ({+ useMusicSettings: () => ({+ settings: {+ preferred_service: "auto",+ playback: "background",+ service_options: ["auto", "spotify", "youtube_music"],+ playback_options: ["background", "browser"],+ connected: ["spotify"],+ background_player_available: false,+ },+ loading: false,+ error: null,+ refetch: vi.fn(),+ save,+ }),+}));++import { MusicGroup } from "@/views/settings/MusicGroup";++afterEach(() => {+ cleanup();+ vi.clearAllMocks();+});++describe("MusicGroup", () => {+ it("renders both sections with one row per value", () => {+ render(<MusicGroup />);+ expect(screen.getByText("settings_view.music_group_title")).toBeDefined();+ expect(screen.getByText("settings_view.music.service_section")).toBeDefined();+ expect(screen.getByText("settings_view.music.playback_section")).toBeDefined();+ for (const key of ["auto", "spotify", "youtube_music"]) {+ expect(screen.getByText(`settings_view.music.service_labels.${key}`)).toBeDefined();+ }+ for (const key of ["background", "browser"]) {+ expect(screen.getByText(`settings_view.music.playback_labels.${key}`)).toBeDefined();+ }+ });++ it("marks the active rows and says which services are connected", () => {+ render(<MusicGroup />);+ const pressed = screen+ .getAllByRole("button")+ .filter((b) => b.getAttribute("aria-pressed") === "true");+ expect(pressed).toHaveLength(2); // one per section+ // Spotify is connected, YouTube Music is not — the row descriptions say so.+ expect(+ screen.getByText(/service_options\.spotify — settings_view\.music\.connected/),+ ).toBeDefined();+ expect(+ screen.getByText(/service_options\.youtube_music — settings_view\.music\.not_connected/),+ ).toBeDefined();+ // The background player cannot run in this fake host — the row says so.+ expect(screen.getByText(/settings_view\.music\.player_unavailable/)).toBeDefined();+ });++ it("clicking a row saves that value only", () => {+ render(<MusicGroup />);+ fireEvent.click(screen.getByText("settings_view.music.service_labels.youtube_music"));+ expect(save).toHaveBeenCalledWith({ preferred_service: "youtube_music" });+ fireEvent.click(screen.getByText("settings_view.music.playback_labels.browser"));+ expect(save).toHaveBeenCalledWith({ playback: "browser" });+ });+});diff --git a/jarvis/ui/web/frontend/src/views/settings/MusicGroup.tsx b/jarvis/ui/web/frontend/src/views/settings/MusicGroup.tsxnew file mode 100644index 0000000000..dd24ec18c6--- /dev/null+++ b/jarvis/ui/web/frontend/src/views/settings/MusicGroup.tsx@@ -0,0 +1,155 @@+import { Check } from "lucide-react";+import { cn } from "@/lib/utils";+import { useT } from "@/i18n";+import { useEventStore } from "@/store/events";+import { useMusicSettings } from "@/hooks/useMusicSettings";+import {+ MUSIC_PLAYBACK_MODES,+ MUSIC_SERVICES,+ type MusicPlaybackMode,+ type MusicService,+} from "@/lib/musicSettings";++/**+ * "Music" group inside the Settings view — two connectors, one domain.+ *+ * Which service a request that names no service goes to (Spotify vs YouTube+ * Music), and where YouTube Music plays (the background player window or the+ * browser). Same row-button idiom as the Languages group; both option lists+ * are the frozen TS mirror of `music_constants.py`, and the row descriptions+ * say which connectors are actually connected so a choice never looks live+ * when it would do nothing.+ */+export function MusicGroup() {+ const t = useT();+ const pushToast = useEventStore((s) => s.pushToast);+ const { settings, loading, save } = useMusicSettings();++ const connected = new Set(settings?.connected ?? []);+ const playerAvailable = settings?.background_player_available ?? true;++ const choose = async (patch: {+ preferred_service?: MusicService;+ playback?: MusicPlaybackMode;+ }) => {+ try {+ await save(patch);+ pushToast("success", t("settings_view.music.saved_toast"));+ } catch (e) {+ pushToast("error", (e as Error).message);+ }+ };++ const serviceDescription = (service: MusicService): string => {+ if (service === "auto") return t("settings_view.music.service_options.auto");+ const state = connected.has(service)+ ? t("settings_view.music.connected")+ : t("settings_view.music.not_connected");+ return `${t(`settings_view.music.service_options.${service}`)} — ${state}`;+ };++ const playbackDescription = (mode: MusicPlaybackMode): string => {+ const base = t(`settings_view.music.playback_options.${mode}`);+ if (mode === "background" && !playerAvailable) {+ return `${base} — ${t("settings_view.music.player_unavailable")}`;+ }+ return base;+ };++ return (+ <div className="mb-8 space-y-4">+ <h3 className="font-display text-xs font-semibold uppercase tracking-wide text-muted-foreground">+ {t("settings_view.music_group_title")}+ </h3>++ <Section+ title={t("settings_view.music.service_section")}+ hint={t("settings_view.music.service_hint")}+ >+ {MUSIC_SERVICES.map((service) => (+ <ChoiceRow+ key={`service-${service}`}+ active={settings?.preferred_service === service}+ disabled={loading}+ label={t(`settings_view.music.service_labels.${service}`)}+ description={serviceDescription(service)}+ onClick={() => void choose({ preferred_service: service })}+ />+ ))}+ </Section>++ <Section+ title={t("settings_view.music.playback_section")}+ hint={t("settings_view.music.playback_hint")}+ >+ {MUSIC_PLAYBACK_MODES.map((mode) => (+ <ChoiceRow+ key={`playback-${mode}`}+ active={settings?.playback === mode}+ disabled={loading}+ label={t(`settings_view.music.playback_labels.${mode}`)}+ description={playbackDescription(mode)}+ onClick={() => void choose({ playback: mode })}+ />+ ))}+ </Section>+ </div>+ );+}++function Section({+ title,+ hint,+ children,+}: {+ title: string;+ hint: string;+ children: React.ReactNode;+}) {+ return (+ <div>+ <div className="mb-1 text-[10px] uppercase tracking-wider text-muted-foreground">+ {title}+ </div>+ <div className="mb-3 text-xs text-muted-foreground">{hint}</div>+ <ul className="space-y-2">{children}</ul>+ </div>+ );+}++function ChoiceRow({+ active,+ disabled,+ label,+ description,+ onClick,+}: {+ active: boolean;+ disabled: boolean;+ label: string;+ description: string;+ onClick: () => void;+}) {+ return (+ <li>+ <button+ type="button"+ onClick={onClick}+ disabled={disabled}+ aria-pressed={active}+ className={cn(+ "flex w-full items-center gap-3 rounded-lg border px-4 py-3 text-left text-sm transition-colors disabled:opacity-60",+ active+ ? "border-primary/40 bg-primary/5 shadow-[0_0_0_1px_hsl(var(--primary)/0.15)]"+ : "border-border bg-card/60 hover:border-primary/30 hover:bg-card/80",+ )}+ >+ <div className="flex-1">+ <div className="font-medium">{label}</div>+ <div className="mt-0.5 text-xs text-muted-foreground">{description}</div>+ </div>+ {active && <Check className="h-4 w-4 shrink-0 text-primary" />}+ </button>+ </li>+ );+}diff --git a/jarvis/ui/web/marketplace_routes.py b/jarvis/ui/web/marketplace_routes.pyindex b8db99f70c..ea43b4a394 100644--- a/jarvis/ui/web/marketplace_routes.py+++ b/jarvis/ui/web/marketplace_routes.py@@ -96,6 +96,14 @@ def _refresh_plugin_in_live_registry(plugin_id: str) -> None:No-op when no shared registry is published (headless without web boot)."""+ try:+ # The music tools remember which connectors are connected for a few+ # seconds; a connect/disconnect must be seen at once, not after the TTL.+ from jarvis.core.music_service import forget_connected_music_services++ forget_connected_music_services()+ except Exception: # noqa: BLE001 — a cache miss is the worst case here+ log.debug("music connection cache reset skipped", exc_info=True)try:from jarvis.marketplace.plugin_shared import get_active_plugin_registrydiff --git a/jarvis/ui/web/settings_routes.py b/jarvis/ui/web/settings_routes.pyindex e51e0daf16..94ab519660 100644--- a/jarvis/ui/web/settings_routes.py+++ b/jarvis/ui/web/settings_routes.py@@ -666,6 +666,151 @@ async def put_appearance(body: AppearanceBody, request: Request) -> dict[str, obreturn {"ok": True, "theme": theme, "persisted": persisted}+# ----------------------------------------------------------------------+# Music — two connectors, one domain (2026-08-18)+# ----------------------------------------------------------------------++from jarvis.core.music_constants import ( # noqa: E402 — the settings vocabulary, five-layer L0+ MUSIC_PLAYBACK_BACKGROUND,+ MUSIC_PLAYBACK_MODES,+ MUSIC_PLUGIN_IDS,+ MUSIC_SERVICE_AUTO,+ MUSIC_SERVICES,+)+++class MusicSettingsBody(BaseModel):+ preferred_service: str | None = Field(+ default=None, description="auto | spotify | youtube_music (omit to leave unchanged)"+ )+ playback: str | None = Field(+ default=None, description="background | browser (omit to leave unchanged)"+ )+++def _current_music(request: Request) -> tuple[str, str]:+ """(preferred_service, playback) — fresh from disk, boot config as fallback."""+ try:+ from jarvis.core.config import load_config++ music = load_config().music+ return str(music.preferred_service), str(music.playback)+ except Exception as exc: # noqa: BLE001 — never 500 a settings read+ log.debug("music settings fresh read failed, using boot config: %s", exc)+ cfg = getattr(request.app.state, "config", None)+ music = getattr(cfg, "music", None)+ return (+ str(getattr(music, "preferred_service", MUSIC_SERVICE_AUTO)),+ str(getattr(music, "playback", MUSIC_PLAYBACK_BACKGROUND)),+ )+++def _connected_music_services() -> list[str]:+ """Which music connectors currently hold a usable credential — so the+ Settings card can say which of the choices would actually do something."""+ try:+ from jarvis.marketplace.token_store import TokenStore++ store = TokenStore()+ out: list[str] = []+ for plugin_id in MUSIC_PLUGIN_IDS:+ try:+ tokens = store.load(plugin_id)+ except Exception as exc: # noqa: BLE001 — one broken credential stays isolated+ log.debug("music connection probe: %s unreadable: %s", plugin_id, exc)+ continue+ if tokens is not None and tokens.access and not tokens.needs_reauth:+ out.append(plugin_id)+ return out+ except Exception as exc: # noqa: BLE001 — a store fault must not fail a settings read+ log.debug("music connection probe failed: %s", exc)+ return []+++def _background_player_available() -> bool:+ try:+ from jarvis.platform.music_player import background_player_available++ return background_player_available()+ except Exception as exc: # noqa: BLE001 — a probe fault reads as "not available"+ log.debug("background player probe failed: %s", exc)+ return False++[email protected]("/music")+async def get_music_settings(request: Request) -> dict[str, object]:+ """Preferred music service + where YouTube Music plays, with the accepted+ values, which connectors are connected, and whether the background player+ can run on this host."""+ preferred, playback = _current_music(request)+ return {+ "preferred_service": preferred,+ "playback": playback,+ "service_options": list(MUSIC_SERVICES),+ "playback_options": list(MUSIC_PLAYBACK_MODES),+ "connected": _connected_music_services(),+ "background_player_available": _background_player_available(),+ }++[email protected]("/music")+async def put_music_settings(body: MusicSettingsBody, request: Request) -> dict[str, object]:+ """Change the preferred music service and/or where YouTube Music plays."""+ preferred_now, playback_now = _current_music(request)+ preferred = preferred_now+ playback = playback_now+ if body.preferred_service is not None:+ preferred = body.preferred_service.strip().lower()+ if preferred not in MUSIC_SERVICES:+ raise HTTPException(+ status_code=400,+ detail=(+ f"Unknown music service {body.preferred_service!r} "+ f"(allowed: {list(MUSIC_SERVICES)})"+ ),+ )+ if body.playback is not None:+ playback = body.playback.strip().lower()+ if playback not in MUSIC_PLAYBACK_MODES:+ raise HTTPException(+ status_code=400,+ detail=(+ f"Unknown playback mode {body.playback!r} "+ f"(allowed: {list(MUSIC_PLAYBACK_MODES)})"+ ),+ )++ persisted = False+ try:+ from jarvis.core import config_writer+ from jarvis.core.config import resolve_config_path++ path = resolve_config_path()+ if preferred != preferred_now:+ config_writer.set_preferred_music_service(preferred, path=path)+ if playback != playback_now:+ config_writer.set_music_playback(playback, path=path)+ persisted = True+ except Exception as exc: # noqa: BLE001 — persist is best-effort+ log.warning("music settings persist failed: %s", exc)++ cfg = getattr(request.app.state, "config", None)+ music = getattr(cfg, "music", None)+ if music is not None:+ try:+ music.preferred_service = preferred # type: ignore[attr-defined]+ music.playback = playback # type: ignore[attr-defined]+ except Exception as exc: # noqa: BLE001 — frozen model is not an error+ log.debug("in-memory cfg.music update skipped: %s", exc)++ return {+ "ok": True,+ "preferred_service": preferred,+ "playback": playback,+ "persisted": persisted,+ }++# ----------------------------------------------------------------------# STT recognition language — the language Whisper TRANSCRIBES the user's voice# into. Distinct from BOTH the UI language (what the user sees) and the replydiff --git a/tests/integration/test_music_settings_route.py b/tests/integration/test_music_settings_route.pynew file mode 100644index 0000000000..72b2d3cbab--- /dev/null+++ b/tests/integration/test_music_settings_route.py@@ -0,0 +1,79 @@+"""GET/PUT /api/settings/music — preferred music service + where YouTube Music+plays (2026-08-18). JARVIS_CONFIG points the writer at a temp file so the real+jarvis.toml is never touched; the connection probe and the player probe are+faked so no keyring or window is involved.+"""+from __future__ import annotations++import tomllib++import pytest+from fastapi import FastAPI+from fastapi.testclient import TestClient++from jarvis.core import config as cfg_mod+from jarvis.core import config_writer+from jarvis.ui.web import settings_routes+++def ctx(monkeypatch, tmp_path):+ config_file = tmp_path / "jarvis.toml"+ config_file.write_text('[ui]\nlanguage = "en"\n', encoding="utf-8")+ monkeypatch.setenv("JARVIS_CONFIG", str(config_file))+ monkeypatch.setattr(+ settings_routes, "_connected_music_services", lambda: ["spotify", "youtube_music"]+ )+ monkeypatch.setattr(settings_routes, "_background_player_available", lambda: True)+ app = FastAPI()+ app.state.config = cfg_mod.load_config()+ app.include_router(settings_routes.router)+ return TestClient(app), config_file+++def test_get_returns_defaults_options_and_context(ctx) -> None:+ tc, _ = ctx+ body = tc.get("/api/settings/music").json()+ assert body["preferred_service"] == "auto" and body["playback"] == "background"+ assert set(body["service_options"]) == {"auto", "spotify", "youtube_music"}+ assert set(body["playback_options"]) == {"background", "browser"}+ assert body["connected"] == ["spotify", "youtube_music"]+ assert body["background_player_available"] is True+++def test_put_persists_each_field_independently(ctx) -> None:+ tc, config_file = ctx+ res = tc.put("/api/settings/music", json={"preferred_service": "youtube_music"})+ assert res.status_code == 200, res.text+ assert res.json() == {+ "ok": True,+ "preferred_service": "youtube_music",+ "playback": "background",+ "persisted": True,+ }+ res = tc.put("/api/settings/music", json={"playback": "browser"})+ assert res.json()["preferred_service"] == "youtube_music"+ assert res.json()["playback"] == "browser"+ data = tomllib.loads(config_file.read_text(encoding="utf-8"))+ assert data["music"] == {"preferred_service": "youtube_music", "playback": "browser"}+ assert data["ui"]["language"] == "en" # sibling preserved+ body = tc.get("/api/settings/music").json()+ assert body["preferred_service"] == "youtube_music" and body["playback"] == "browser"+++def test_put_rejects_unknown_values_with_the_allowed_list(ctx) -> None:+ tc, _ = ctx+ res = tc.put("/api/settings/music", json={"preferred_service": "deezer"})+ assert res.status_code == 400 and "youtube_music" in res.json()["detail"]+ res = tc.put("/api/settings/music", json={"playback": "tab"})+ assert res.status_code == 400 and "background" in res.json()["detail"]+++def test_writer_round_trip_preserves_siblings(tmp_path) -> None:+ cfg = tmp_path / "jarvis.toml"+ cfg.write_text('[ui]\norb_style = "jarvis_bar"\n', encoding="utf-8")+ config_writer.set_preferred_music_service("spotify", path=cfg)+ config_writer.set_music_playback("browser", path=cfg)+ data = tomllib.loads(cfg.read_text(encoding="utf-8"))+ assert data["music"] == {"preferred_service": "spotify", "playback": "browser"}+ assert data["ui"]["orb_style"] == "jarvis_bar"diff --git a/tests/unit/brain/test_paired_plugin_capture_veto.py b/tests/unit/brain/test_paired_plugin_capture_veto.pyindex 44a1b2fd3c..8cf8741d01 100644--- a/tests/unit/brain/test_paired_plugin_capture_veto.py+++ b/tests/unit/brain/test_paired_plugin_capture_veto.py@@ -85,3 +85,54 @@ def test_production_path_remembers_the_answer_per_plugin(monkeypatch) -> None:assert BrainManager._paired_plugin_disconnected(_skill("youtube_music")) is Trueassert BrainManager._paired_plugin_disconnected(_skill("spotify")) is Trueassert loads == ["youtube_music", "spotify"]+++# -- preferred music service (2026-08-18) ---------------------------------------+++class _Registry:+ def __init__(self, skills: dict[str, Any]) -> None:+ self._skills = skills++ def get(self, name: str) -> Any:+ return self._skills.get(name)+++def _manager_with(preferred: str, connected: set[str]) -> Any:+ """A BrainManager stand-in: only what `_prefer_music_service` touches."""+ music = SimpleNamespace(preferred_service=preferred)+ mgr = SimpleNamespace(_config=SimpleNamespace(music=music))+ mgr._plugin_disconnected = lambda pid, store=None: pid not in connected+ mgr._prefer_music_service = BrainManager._prefer_music_service.__get__(mgr)+ return mgr+++def test_generic_music_request_is_swapped_to_the_preferred_connected_service() -> None:+ spotify, ytm = _skill("spotify"), _skill("youtube_music")+ reg = _Registry({"plugin-spotify": spotify, "plugin-youtube_music": ytm})+ mgr = _manager_with("youtube_music", {"spotify", "youtube_music"})+ assert mgr._prefer_music_service(spotify, "spiel mal musik", reg) is ytm+ # a named service still wins over the preference+ named = "spiel das auf spotify" # i18n-allow: spoken-input sample+ assert mgr._prefer_music_service(ytm, named, reg) is spotify+++def test_only_connected_service_wins_under_auto() -> None:+ spotify, ytm = _skill("spotify"), _skill("youtube_music")+ reg = _Registry({"plugin-spotify": spotify, "plugin-youtube_music": ytm})+ mgr = _manager_with("auto", {"youtube_music"})+ assert mgr._prefer_music_service(spotify, "spiel musik", reg) is ytm+++def test_no_swap_when_the_match_already_fits_or_the_sibling_is_missing() -> None:+ spotify, ytm = _skill("spotify"), _skill("youtube_music")+ reg = _Registry({"plugin-spotify": spotify, "plugin-youtube_music": ytm})+ mgr = _manager_with("spotify", {"spotify", "youtube_music"})+ assert mgr._prefer_music_service(spotify, "spiel musik", reg) is spotify+ # non-music skills are never touched+ gmail = _skill("gmail")+ assert mgr._prefer_music_service(gmail, "spiel musik", reg) is gmail+ # sibling absent from the registry → keep the match+ lonely = _Registry({"plugin-spotify": spotify})+ mgr = _manager_with("youtube_music", {"spotify", "youtube_music"})+ assert mgr._prefer_music_service(spotify, "spiel musik", lonely) is spotifydiff --git a/tests/unit/core/test_music_constants_parity.py b/tests/unit/core/test_music_constants_parity.pynew file mode 100644index 0000000000..fda2e35a49--- /dev/null+++ b/tests/unit/core/test_music_constants_parity.py@@ -0,0 +1,64 @@+"""Parity test for the layers that share the music-settings vocabulary+(five-layer pattern, BUG-008 class).++1. ``jarvis/core/music_constants.py`` — the Python tuples (source of truth)+2. ``jarvis/core/config.py::MusicConfig`` — the Pydantic Literals (asserted at import)+3. ``jarvis/ui/web/settings_routes.py`` — the accepted set the route answers+4. ``jarvis/ui/web/frontend/src/lib/musicSettings.ts`` — the TS const tuples+5. ``jarvis/ui/web/frontend/src/i18n/locales/{en,de,es}.json``+ — a label + description per value++A drift shows up here as one failing test instead of a Pydantic+``literal_error`` on load, a 400 on a value the UI offers, or a row that+renders its raw i18n key.+"""+from __future__ import annotations++import json+import re+from pathlib import Path+from typing import get_args++from jarvis.core.config import MusicConfig+from jarvis.core.music_constants import MUSIC_PLAYBACK_MODES, MUSIC_SERVICES++REPO_ROOT = Path(__file__).resolve().parents[3]+TS_FILE = REPO_ROOT / "jarvis/ui/web/frontend/src/lib/musicSettings.ts"+LOCALES = REPO_ROOT / "jarvis/ui/web/frontend/src/i18n/locales"+++def _ts_tuple(name: str) -> set[str]:+ src = TS_FILE.read_text(encoding="utf-8")+ match = re.search(rf"export const {name} = \[([^\]]*)\] as const;", src)+ assert match, f"{name} const tuple missing from {TS_FILE.name}"+ return set(re.findall(r'"([a-z_]+)"', match.group(1)))+++def test_python_literals_match_the_tuples() -> None:+ fields = MusicConfig.model_fields+ assert set(get_args(fields["preferred_service"].annotation)) == set(MUSIC_SERVICES)+ assert set(get_args(fields["playback"].annotation)) == set(MUSIC_PLAYBACK_MODES)+++def test_typescript_mirror_matches_the_tuples() -> None:+ assert _ts_tuple("MUSIC_SERVICES") == set(MUSIC_SERVICES)+ assert _ts_tuple("MUSIC_PLAYBACK_MODES") == set(MUSIC_PLAYBACK_MODES)+++def test_every_locale_labels_every_value() -> None:+ for lang in ("en", "de", "es"):+ data = json.loads((LOCALES / f"{lang}.json").read_text(encoding="utf-8"))+ music = data["settings_view"]["music"]+ assert set(music["service_labels"]) == set(MUSIC_SERVICES), lang+ assert set(music["service_options"]) == set(MUSIC_SERVICES), lang+ assert set(music["playback_labels"]) == set(MUSIC_PLAYBACK_MODES), lang+ assert set(music["playback_options"]) == set(MUSIC_PLAYBACK_MODES), lang+ for group in ("service_labels", "service_options", "playback_labels", "playback_options"):+ assert all(str(v).strip() for v in music[group].values()), (lang, group)+++def test_route_accepts_exactly_the_tuples() -> None:+ from jarvis.ui.web import settings_routes++ assert set(settings_routes.MUSIC_SERVICES) == set(MUSIC_SERVICES)+ assert set(settings_routes.MUSIC_PLAYBACK_MODES) == set(MUSIC_PLAYBACK_MODES)diff --git a/tests/unit/core/test_music_service.py b/tests/unit/core/test_music_service.pynew file mode 100644index 0000000000..d0ca4d30e7--- /dev/null+++ b/tests/unit/core/test_music_service.py@@ -0,0 +1,89 @@+"""The one resolver that decides Spotify vs YouTube Music (2026-08-18).++Named service wins, then the preference, then the only connected one, then+whatever matched — and the tool-description hint says the same thing, so the+skill capture and the LLM router can never disagree.+"""+from __future__ import annotations++from types import SimpleNamespace++from jarvis.core import music_service as ms+from jarvis.core.config import JarvisConfig, MusicConfig+from jarvis.core.music_constants import (+ MUSIC_PLAYBACK_MODES,+ MUSIC_SERVICES,+)+++def test_named_service_wins_over_everything():+ assert ms.explicit_music_service("spiel karma police auf spotify") == "spotify"+ assert ms.explicit_music_service("play it on youtube music") == "youtube_music"+ assert ms.explicit_music_service("spiel das auf yt music") == "youtube_music" # i18n-allow+ assert ms.explicit_music_service("spiel das auf youtube") == "youtube_music" # i18n-allow+ assert ms.explicit_music_service("spiel musik") is None+ # naming both is not naming one+ assert ms.explicit_music_service("spotify oder youtube music?") is None+ both = ("spotify", "youtube_music")+ assert ms.resolve_music_service(+ "spiel radiohead auf youtube music", preferred="spotify", connected=both, matched="spotify"+ ) == "youtube_music"+++def test_preference_applies_only_when_that_service_is_connected():+ both = ("spotify", "youtube_music")+ assert ms.resolve_music_service("spiel musik", preferred="youtube_music", connected=both) == (+ "youtube_music"+ )+ assert ms.resolve_music_service(+ "spiel musik", preferred="youtube_music", connected=("spotify",), matched="spotify"+ ) == "spotify"+++def test_auto_takes_the_only_connected_service_else_the_match():+ def auto(connected, matched=None):+ return ms.resolve_music_service(+ "spiel musik", preferred="auto", connected=connected, matched=matched+ )++ both = ("spotify", "youtube_music")+ assert auto(("youtube_music",)) == "youtube_music"+ assert auto(both, matched="spotify") == "spotify"+ assert auto(both) == "spotify"+ assert auto(()) is None+ assert auto((), matched="spotify") == "spotify"+++def test_preference_hint_only_when_both_connected_and_a_preference_exists():+ both = ("spotify", "youtube_music")+ assert ms.preference_hint("spotify", preferred="auto", connected=both) == ""+ assert ms.preference_hint("spotify", preferred="youtube_music", connected=("spotify",)) == ""+ pro = ms.preference_hint("youtube_music", preferred="youtube_music", connected=both)+ con = ms.preference_hint("spotify", preferred="youtube_music", connected=both)+ assert "prefers YouTube Music" in pro and "does not name another service" in pro+ assert "prefers YouTube Music" in con and "names Spotify explicitly" in con+++def test_connected_music_services_reads_the_store_and_isolates_faults():+ class Store:+ def load(self, plugin_id):+ if plugin_id == "spotify":+ raise RuntimeError("corrupt")+ return SimpleNamespace(access="tok", needs_reauth=False)++ assert ms.connected_music_services(store=Store()) == ("youtube_music",)++ class Empty:+ def load(self, plugin_id):+ return None++ assert ms.connected_music_services(store=Empty()) == ()+++def test_music_config_defaults_and_sanitising():+ cfg = JarvisConfig()+ assert cfg.music.preferred_service == "auto" and cfg.music.playback == "background"+ assert MusicConfig(preferred_service="Nope", playback="???").preferred_service == "auto"+ assert MusicConfig(playback="Browser").playback == "browser"+ assert set(MUSIC_SERVICES) == {"auto", "spotify", "youtube_music"}+ assert set(MUSIC_PLAYBACK_MODES) == {"background", "browser"}diff --git a/tests/unit/platform/test_music_player.py b/tests/unit/platform/test_music_player.pynew file mode 100644index 0000000000..9c0c70be47--- /dev/null+++ b/tests/unit/platform/test_music_player.py@@ -0,0 +1,203 @@+"""Unit tests for the background music player client (``jarvis/platform/music_player``).++The host process is replaced by an in-process fake that speaks the same+JSON-line protocol over pipe-shaped objects, so these tests cover the client's+spawn, ready-wait, request/reply matching, error mapping and teardown without+a window, a browser or a display.+"""+from __future__ import annotations++import io+import json+import threading+import time+from typing import Any++import pytest++from jarvis.platform.music_player import MusicPlayer, MusicPlayerError+++class _Pipe:+ """A blocking line pipe: ``write`` on one side, iteration on the other."""++ def __init__(self) -> None:+ self._cond = threading.Condition()+ self._lines: list[str] = []+ self._closed = False++ def write(self, text: str) -> None:+ with self._cond:+ self._lines.append(text)+ self._cond.notify_all()++ def flush(self) -> None:+ pass++ def close(self) -> None:+ with self._cond:+ self._closed = True+ self._cond.notify_all()++ def __iter__(self):+ return self++ def __next__(self) -> str:+ with self._cond:+ while not self._lines and not self._closed:+ self._cond.wait(0.05)+ if self._lines:+ return self._lines.pop(0)+ raise StopIteration+++class FakeHost:+ """Answers like ``music_player_host``: ready on start, JSON replies per id."""++ def __init__(self, *, ready: bool = True, unavailable: str | None = None) -> None:+ self.stdin = _Pipe()+ self.stdout = _Pipe()+ self.stderr = io.StringIO()+ self.commands: list[dict[str, Any]] = []+ self.state: dict[str, Any] = {"has_video": True, "paused": False, "title": "T"}+ self._alive = True+ self._killed = False+ if unavailable:+ self.stdout.write(json.dumps({"event": "unavailable", "error": unavailable}) + "\n")+ elif ready:+ self.stdout.write(json.dumps({"event": "ready"}) + "\n")+ threading.Thread(target=self._serve, daemon=True).start()++ def _serve(self) -> None:+ for raw in self.stdin:+ msg = json.loads(raw)+ self.commands.append(msg)+ cmd = msg.get("cmd")+ if cmd == "quit":+ self.stdout.write(json.dumps({"id": msg["id"], "ok": True}) + "\n")+ self._alive = False+ self.stdout.close()+ return+ if cmd == "state":+ result: Any = dict(self.state)+ elif cmd == "boom":+ self.stdout.write(+ json.dumps({"id": msg["id"], "ok": False, "error": "ValueError: nope"}) + "\n"+ )+ continue+ elif cmd == "silent":+ continue # never answers → the client must time out+ else:+ result = True+ self.stdout.write(json.dumps({"id": msg["id"], "ok": True, "result": result}) + "\n")++ def poll(self):+ return None if self._alive else 0++ def wait(self, timeout=None):+ return 0++ def kill(self) -> None:+ self._killed = True+ self._alive = False+ self.stdout.close()+++def _player(host: FakeHost, **kw) -> MusicPlayer:+ return MusicPlayer(+ spawn=lambda argv: host,+ display_present=lambda: True,+ has_webview=lambda: True,+ **kw,+ )+++def test_available_reports_missing_display_and_missing_webview():+ no_display = MusicPlayer(display_present=lambda: False, has_webview=lambda: True)+ ok, why = no_display.available()+ assert not ok and "desktop session" in why+ no_webview = MusicPlayer(display_present=lambda: True, has_webview=lambda: False)+ ok, why = no_webview.available()+ assert not ok and "desktop extras" in why+++def test_start_load_state_and_commands_round_trip():+ host = FakeHost()+ player = _player(host)+ assert player.start() is True and player.is_running()+ assert player.load("https://music.youtube.com/watch?v=x") is True+ assert player.state()["title"] == "T"+ assert player.pause() and player.play() and player.next() and player.previous()+ assert player.set_volume(35) is True+ assert player.show() and player.hide()+ sent = [(c["cmd"], c.get("url"), c.get("level")) for c in host.commands]+ assert ("load", "https://music.youtube.com/watch?v=x", None) in sent+ assert ("volume", None, 35) in sent+ player.stop()+ for _ in range(50): # the fake host drains its pipe on its own thread+ if host.commands and host.commands[-1]["cmd"] == "quit":+ break+ time.sleep(0.02)+ assert host.commands[-1]["cmd"] == "quit"+ assert not player.is_running()+++def test_start_spawns_lazily_on_first_request():+ host = FakeHost()+ player = _player(host)+ assert not player.is_running()+ assert player.state()["has_video"] is True+ assert player.is_running()+ player.stop()+++def test_host_error_and_timeout_surface_as_music_player_error():+ host = FakeHost()+ player = _player(host)+ with pytest.raises(MusicPlayerError, match="nope"):+ player.request("boom")+ with pytest.raises(MusicPlayerError, match="did not answer"):+ player.request("silent", timeout=0.3)+ player.stop()+++def test_unavailable_host_makes_the_player_unavailable_with_its_reason():+ host = FakeHost(unavailable="WebViewException: no GTK")+ player = _player(host)+ assert player.start(timeout=1.0) is False+ ok, why = player.available()+ assert not ok and "no GTK" in why+++def test_spawn_failure_degrades_instead_of_raising():+ def spawn(argv):+ raise OSError("no such interpreter")++ player = MusicPlayer(spawn=spawn, display_present=lambda: True, has_webview=lambda: True)+ assert player.start() is False+ with pytest.raises(MusicPlayerError):+ player.load("x")+++def test_argv_carries_storage_and_title():+ seen: list[list[str]] = []++ def spawn(argv):+ seen.append(list(argv))+ return FakeHost()++ from pathlib import Path++ player = MusicPlayer(+ storage_dir=Path("C:/tmp/profile"),+ title="Nova — Music",+ spawn=spawn,+ display_present=lambda: True,+ has_webview=lambda: True,+ )+ assert player.start()+ argv = seen[0]+ assert "-m" in argv and "jarvis.platform.music_player_host" in argv+ assert argv[argv.index("--storage") + 1].endswith("profile")+ assert argv[argv.index("--title") + 1] == "Nova — Music"+ player.stop()diff --git a/tests/unit/plugins/tool/test_youtube_music_rest.py b/tests/unit/plugins/tool/test_youtube_music_rest.pyindex 6541560ff2..17c4a546c1 100644--- a/tests/unit/plugins/tool/test_youtube_music_rest.py+++ b/tests/unit/plugins/tool/test_youtube_music_rest.py@@ -110,7 +110,102 @@ class Opener:return self.ok-def _tool(handler, media=None, opener=None, token=_FAKE_TOKEN, refresher=None):+class FakePlayer:+ """The background player as the tool sees it: a state machine over a page.++ ``script`` lists the states ``state()`` answers in order (the last one+ repeats), so a test can stage "consent page, then playing" or "paused+ forever". Every command is recorded."""++ def __init__(+ self,+ script: list[dict[str, Any]] | None = None,+ *,+ available: tuple[bool, str] = (True, ""),+ running: bool = False,+ ) -> None:+ self.script = list(script or [])+ self._available = available+ self.running = running+ self.calls: list[tuple[str, Any]] = []+ self.loaded: list[str] = []+ self.shown = 0+ self.hidden = 0++ def available(self) -> tuple[bool, str]:+ return self._available++ def is_running(self) -> bool:+ return self.running++ def load(self, url: str) -> bool:+ self.loaded.append(url)+ self.running = True+ return True++ def state(self) -> dict[str, Any]:+ if not self.script:+ return {}+ if len(self.script) > 1:+ return self.script.pop(0)+ return dict(self.script[0])++ def show(self) -> bool:+ self.shown += 1+ return True++ def hide(self) -> bool:+ self.hidden += 1+ return True++ def play(self) -> bool:+ self.calls.append(("play", None))+ return True++ def pause(self) -> bool:+ self.calls.append(("pause", None))+ return True++ def next(self) -> bool:+ self.calls.append(("next", None))+ return True++ def previous(self) -> bool:+ self.calls.append(("previous", None))+ return True++ def set_volume(self, level: int) -> bool:+ self.calls.append(("volume", level))+ return True+++def _page(title="Karma Police", artist="Radiohead", *, paused=False, position=3.0, **extra):+ base = {+ "url": "https://music.youtube.com/watch?v=vid123",+ "title": title,+ "artist": artist,+ "album": "OK Computer",+ "has_video": True,+ "paused": paused,+ "position": position,+ "duration": 260.0,+ "volume": 40,+ "ready": True,+ "consent": False,+ }+ base.update(extra)+ return base+++def _tool(+ handler,+ media=None,+ opener=None,+ token=_FAKE_TOKEN,+ refresher=None,+ player=None,+ playback="browser",+):return YouTubeMusicRestTool(access_token_provider=lambda: token,transport=httpx.MockTransport(handler),@@ -118,6 +213,9 @@ def _tool(handler, media=None, opener=None, token=_FAKE_TOKEN, refresher=None):media=media or FakeMedia(),opener=opener or Opener(),confirm_timeout_s=0.6,+ player=player or FakePlayer(available=(False, "no player in this test")),+ playback_mode=lambda: playback,+ player_confirm_timeout_s=1.5,)@@ -210,7 +308,9 @@ async def test_search_playlist_prefers_the_users_own_lists():async def test_not_connected_without_token():- tool = YouTubeMusicRestTool(access_token_provider=lambda: None, media=FakeMedia())+ tool = YouTubeMusicRestTool(+ access_token_provider=lambda: None, media=FakeMedia(), playback_mode=lambda: "browser"+ )out = await tool.search(query="x")assert "not connected" in out["error"].lower()@@ -439,6 +539,89 @@ async def test_playlist_tracks_lists_a_named_playlist():]+# -- background player ---------------------------------------------------------+++async def test_play_prefers_the_background_player_and_confirms_from_its_page():+ player = FakePlayer([_page(position=0.0), _page(position=2.5)])+ opener = Opener()+ tool = _tool(_search_handler, opener=opener, player=player, playback="background")+ out = await tool.play(query="karma police")+ assert player.loaded == [song_url("vid123")]+ assert opener.urls == [] # no browser tab+ assert out["sink"] == "background_player" and out["playback_confirmed"] is True+ assert out["now"]["track"] == "Karma Police" and out["now"]["source"] == "background_player"+ assert out["now"]["volume_percent"] == 40+++async def test_play_shows_the_player_for_youtubes_cookie_choice():+ player = FakePlayer([{"url": "https://consent.youtube.com/m?x", "consent": True}])+ tool = _tool(_search_handler, player=player, playback="background")+ out = await tool.play(query="karma police")+ assert out["needs_attention"] == "consent" and player.shown == 1+ assert "cookie choice" in out["note"]+++async def test_play_nudges_then_shows_the_player_when_it_stays_paused():+ player = FakePlayer([_page(paused=True, position=0.0)])+ tool = _tool(_search_handler, player=player, playback="background")+ out = await tool.play(query="karma police")+ assert ("play", None) in player.calls # one programmatic nudge+ assert out["playback_confirmed"] is False and out["needs_attention"] == "press_play"+ assert player.shown == 1+++async def test_play_falls_back_to_the_browser_when_the_player_cannot_run():+ player = FakePlayer(available=(False, "no display here"))+ opener = Opener()+ tool = _tool(_search_handler, opener=opener, player=player, playback="background")+ out = await tool.play(query="karma police")+ assert opener.urls == [song_url("vid123")]+ assert out["sink"] == "browser" and out["fallback_reason"] == "no display here"+++async def test_browser_setting_never_touches_the_player():+ player = FakePlayer([_page()])+ opener = Opener()+ tool = _tool(_search_handler, opener=opener, player=player, playback="browser")+ out = await tool.play(query="karma police")+ assert player.loaded == [] and opener.urls == [song_url("vid123")]+ assert out["sink"] == "browser"+++async def test_controls_and_now_playing_go_to_the_running_player_first():+ player = FakePlayer([_page()], running=True)+ media = FakeMedia(now=_playing("Other", "Someone"))+ tool = _tool(_search_handler, media=media, player=player, playback="background")+ now = await tool.now_playing()+ assert now["source"] == "background_player" and now["track"] == "Karma Police"+ out = await tool.pause()+ assert out["app"] == "the background player" and ("pause", None) in player.calls+ assert media.calls == [] # the OS session was never asked+ out = await tool.set_volume(volume_percent=55)+ assert out["ok"] and ("volume", 55) in player.calls+++async def test_volume_without_the_player_is_an_honest_error():+ out = await _tool(_search_handler, playback="background").set_volume(volume_percent=30)+ assert "background player" in out["error"]+++async def test_open_shows_the_player_and_hide_minimizes_it():+ player = FakePlayer([_page()])+ tool = _tool(_search_handler, player=player, playback="background")+ out = await tool.open_home()+ assert out["shown"] is True and player.loaded == [HOME_URL] and player.shown == 1+ out = await tool.hide_player()+ assert out["hidden"] is True and player.hidden == 1+++async def test_open_in_browser_mode_opens_the_browser():+ opener = Opener()+ out = await _tool(_search_handler, opener=opener, playback="browser").open_home()+ assert opener.urls == [HOME_URL] and out["sink"] == "browser"++# -- auth + Google's refusals -------------------------------------------------@@ -503,10 +686,15 @@ async def test_execute_explains_search_quota_api_disabled_and_scope():def test_risk_tiers_reads_safe_everything_else_monitor():- tool = YouTubeMusicRestTool(access_token_provider=lambda: None, media=FakeMedia())+ tool = YouTubeMusicRestTool(+ access_token_provider=lambda: None, media=FakeMedia(), playback_mode=lambda: "browser"+ )for action in ("now_playing", "search", "list_playlists", "playlist_tracks", "liked_songs"):assert tool.risk_tier_for_args({"action": action}) == "safe"- for action in ("play", "pause", "next", "previous", "open", "like", "add_to_playlist"):+ for action in (+ "play", "pause", "next", "previous", "open", "like", "add_to_playlist",+ "set_volume", "hide_player",+ ):assert tool.risk_tier_for_args({"action": action}) == "monitor"assert tool.risk_tier_for_args({"action": "nuke"}) == "ask"