Skip to content

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.

feat(music): a background player instead of a browser tab, and a preferred service

Harald619cccb5b9b3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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 per
project (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 Cloud
diff --git a/docs/marketplace/google-oauth-setup.md b/docs/marketplace/google-oauth-setup.md
index 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 edit
read events across ALL your calendars, not just the primary one, so a lesson
on 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.md
index 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; for
personal 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. Nothing
to 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 a
live 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.md
index 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 |
## Maintenance
diff --git a/jarvis/brain/manager.py b/jarvis/brain/manager.py
index 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.band
self._skill_match_class = classify(skill)
@@ -5634,10 +5638,56 @@ class BrainManager:
except Exception: # noqa: BLE001
return 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's
guidance 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 False
now = time.monotonic()
diff --git a/jarvis/core/config.py b/jarvis/core/config.py
index 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.py
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.json
index 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.md
index 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, lied
Use 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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.py
index 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 = media
self._opener = opener or _default_opener
self._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_s
self._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 out
async 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_player
media = 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 hits
if 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 going
hits = 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 error
diff --git a/jarvis/skills/builtin/plugin-youtube_music/SKILL.md b/jarvis/skills/builtin/plugin-youtube_music/SKILL.md
index 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.ts
new file mode 100644
index 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.json
index 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.json
index 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.json
index 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.ts
new file mode 100644
index 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.tsx
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.py
index 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_registry
diff --git a/jarvis/ui/web/settings_routes.py b/jarvis/ui/web/settings_routes.py
index 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, ob
return {"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
+
+
+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(),
+ }
+
+
+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 reply
diff --git a/tests/integration/test_music_settings_route.py b/tests/integration/test_music_settings_route.py
new file mode 100644
index 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.py
index 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 True
assert BrainManager._paired_plugin_disconnected(_skill("spotify")) is True
assert 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 spotify
diff --git a/tests/unit/core/test_music_constants_parity.py b/tests/unit/core/test_music_constants_parity.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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"