@audiofool/moondog 0.3.0-beta.1 → 0.3.0-beta.10

package/src/core/moondog-application.mjs

@@ -4,8 +4,8 @@ import { setTimeout as delay } from "node:timers/promises";
 import { compactListenerProfile, readListenerProfile } from "../profile/listener-profile-build.mjs";
 import { mixCounts, songKeys } from "../profile/moondog-suggestions.mjs";
 import { ARTIST_CREDIT_SEPARATORS } from "./listener-avoids.mjs";
-import { textNamesSong } from "./track-title.mjs";
-import { compileTaste, tasteSources } from "../profile/taste-compiler.mjs";
+import { foldedWords, normalizedTrackTitle, textNamesSong } from "./track-title.mjs";
+import { acceptableRecordTitle, compileTaste, tasteSources } from "../profile/taste-compiler.mjs";
 import { stableAudioPrompt } from "../integrations/stable-audio/local-generator.mjs";
 
 import {
@@ -19,9 +19,41 @@ import {
 import { recoverArtistReleasesWithCrossCatalogIdentity } from "../integrations/cross-catalog-artist-identity.mjs";
 import { webProviderName } from "../integrations/web/web-result.mjs";
 import { musicAppSource, readListeningNow } from "./listening-now.mjs";
+import { SAVED_PLAYLIST_ID } from "./library-store.mjs";
+import { parsePlaylistLink, readApplePlaylist, readPublicPlaylistLink } from "../integrations/playlist-links.mjs";
 import { normalizeConversationFolder, normalizeConversationLabel, normalizeMemoryContent, shortConversationTitle } from "../memory/local-memory-store.mjs";
 import { queueListeningIntent, queueCancellationRequested, unheardRequested } from "./spotify-listening-intent.mjs";
-import { DEFAULT_LOCALE, normalizeLocale } from "../i18n/index.mjs";
+import { DEFAULT_LOCALE, LOCALES, messageLocale, normalizeLocale } from "../i18n/index.mjs";
+
+// Runs work over a list with at most limit calls at once, keeping the list's order.
+async function mapLimited(list, limit, work) {
+  const results = new Array(list.length);
+  let next = 0;
+  await Promise.all(Array.from({ length: Math.min(limit, list.length) }, async () => {
+    while (next < list.length) {
+      const at = next++;
+      results[at] = await work(list[at], at);
+    }
+  }));
+  return results;
+}
+
+// How long a record's title in the wrong language waits to be named again before the agent's stays.
+const TITLE_LANGUAGE_TIMEOUT_MS = 10_000;
+
+// Whether a record's name is written in a language. A short name gives the word-based guess little to
+// go on, and the guess then falls back to the setting, so the script decides first: Chinese, Japanese
+// and Korean names are in their own script, and the other languages Moondog speaks in none of those.
+const CJK = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Hangul}]/u;
+const SCRIPTS = { zh: /\p{Script=Han}/u, "zh-Hant": /\p{Script=Han}/u, ja: /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}]/u, ko: /\p{Script=Hangul}/u };
+export function nameFitsLanguage(name, locale) {
+  const text = String(name ?? "");
+  if (SCRIPTS[locale] ? !SCRIPTS[locale].test(text) : CJK.test(text)) return false;
+  const guess = messageLocale(text, locale);
+  // Kanji with no kana, such as 月夜 or 雨音, is Japanese as much as Chinese, so the Japanese setting decides.
+  if (locale === "ja" && (guess === "zh" || guess === "zh-Hant") && !/\p{Script=Hangul}/u.test(text)) return true;
+  return guess === locale;
+}
 import { createPlaybackSelection, DEFAULT_PLAYBACK_SERVICE, normalizePlaybackService } from "./playback-preferences.mjs";
 
 const minimumNodeVersion = [22, 19, 0];
@@ -222,10 +254,16 @@ export class MoondogApplication {
     musicCatalog = null,
     musicSimilarity = null,
     musicPreviewPlayer = null,
+    languageSelection = null,
+    modelSwitch = null,
     neteasePlayer = null,
     localGenerator = null,
     atmosphereStream = null,
     musicApp = null,
+    // The listener's library (src/core/library-store.mjs), shared by every conversation and both surfaces.
+    libraryStore = null,
+    // Adds an imported playlist's songs to the listener's taste evidence: async ({ provider, id, url, name, tracks }) => receipt.
+    playlistTaste = null,
     agentHostNotes = [],
     artistIdentityResolver = null,
     webResearch = null,
@@ -249,6 +287,7 @@ export class MoondogApplication {
     // The language of the conversation so far. A reply such as "2" or "ok" carries none of
     // its own, so it keeps this one rather than switching to the setting mid-conversation.
     this.conversationLocale = null;
+    this.replyLanguagePin = null;
     this.domainServices = domainServices;
     this.domainServicesError =
       typeof domainServicesError === "string" &&
@@ -268,6 +307,10 @@ export class MoondogApplication {
     // Hosts that can play audio pass { play(tracks, { album }) }: the website, and the
     // terminal when the system has a player.
     this.musicPreviewPlayer = musicPreviewPlayer;
+    // Shared with every surface and conversation of this core, so a language chosen in words is saved and shown everywhere.
+    this.languageSelection = languageSelection;
+    // The listener's model menu, and the way a model asked for in words reaches the surface that runs this agent.
+    this.modelSwitch = modelSwitch;
     // NetEase Cloud Music through ncm-cli (src/integrations/netease), shared by every conversation.
     this.neteasePlayer = neteasePlayer;
     // Stable Audio 3 on this Mac (src/integrations/stable-audio), shared by every conversation, so one track is made at a time.
@@ -277,6 +320,10 @@ export class MoondogApplication {
     // The Music app on this Mac (src/integrations/apple-music/music-app.mjs), read for what the
     // listener plays there themselves.
     this.musicApp = musicApp;
+    this.libraryStore = libraryStore;
+    this.playlistTaste = playlistTaste;
+    // Playlists read from links and waiting for the listener's yes, by token, newest last.
+    this.pendingPlaylistImports = new Map();
     // Hosts can tell the agent where it runs; the terminal passes none.
     this.hostNotes = Array.isArray(agentHostNotes) ? agentHostNotes.filter((note) => typeof note === "string") : [];
     this.artistIdentityResolver = artistIdentityResolver;
@@ -563,7 +610,7 @@ export class MoondogApplication {
     const file = await this.localGenerator.trackFile(id);
     if (!file) throw Object.assign(new Error("That track was part of a stream, which keeps only its newest tracks' audio; its receipt is still here."), { code: "made_track_audio_not_kept" });
     // Playing one of Moondog's tracks again ends its stream, on every surface.
-    await this.#endStream("replaced");
+    const endedStream = await this.#endStream("replaced");
     const title = String(receipt.title ?? "");
     // Named means quoted, or the title with Moondog, as on every play path: an open request shares
     // words with the plain titles Moondog gives its records ("something for a rainy day").
@@ -571,7 +618,9 @@ export class MoondogApplication {
     await this.quietOtherPlayers("apple_music", { signal });
     // A reply stopped before the track starts plays nothing, and no replay is recorded.
     if (signal?.aborted) throw Object.assign(new Error("Nothing was played, because the reply was stopped."), { code: "generation_stopped" });
-    // Nothing waits between this check and the play; the replay is written once it plays.
+    // Nothing waits between this check and the play; the replay is written once it plays. The ended
+    // stream's track it cuts off, or its queued one that started meanwhile, says nothing about the listener.
+    if (endedStream) this.localGenerator.discard?.();
     this.localGenerator.restart?.(id);
     this.musicPreviewPlayer.playGenerated({ id, title, seconds: receipt.audio?.duration_seconds, file });
     if (!named) this.#noteGeneratedPlay({ id, title });
@@ -579,25 +628,298 @@ export class MoondogApplication {
     return { state: "playing", track: { id, title, seconds: receipt.audio?.duration_seconds ?? null }, chosen_by: named ? "listener" : "moondog" };
   }
 
+  // The listener's library: their playlists and the songs and made tracks they kept, side by side.
+  libraryReady() {
+    return Boolean(this.libraryStore);
+  }
+
+  requireLibrary() {
+    if (!this.libraryStore) throw Object.assign(new Error("The library is not available here."), { code: "library_not_ready" });
+    return this.libraryStore;
+  }
+
+  libraryView() {
+    return this.libraryReady() ? this.libraryStore.view() : null;
+  }
+
+  // One playlist with its entries; a made track says whether its audio is still on this Mac.
+  async libraryPlaylist(id) {
+    const playlist = this.requireLibrary().playlist(id);
+    if (!playlist) return null;
+    for (const entry of playlist.entries) {
+      if (entry.kind === "made") entry.audio_kept = Boolean(await this.localGenerator?.trackFile?.(entry.made_id));
+    }
+    return playlist;
+  }
+
+  // The song or made track one listening source plays now, as a library entry.
+  #entryOfSong(song) {
+    if (!song?.title) return null;
+    if (song.made_track_id) return { kind: "made", id: song.made_track_id, title: song.title };
+    const artist = Array.isArray(song.artists) ? song.artists.join(", ") : "";
+    if (!artist) return null;
+    const album = typeof song.album === "string" ? song.album : song.album?.name;
+    return { kind: "song", title: song.title, artist_credit: artist, ...(album ? { album } : {}) };
+  }
+
+  // What to save: the song playing now, what plays from now on (its playlist or queue), songs the agent names,
+  // or a made track by id.
+  async #entriesToSave({ from, songs, madeTrackId }, { signal } = {}) {
+    if (madeTrackId) {
+      const receipt = await this.localGenerator?.receipt?.(madeTrackId);
+      if (!receipt) throw Object.assign(new Error("There is no track Moondog made with that id on this Mac."), { code: "made_track_not_found" });
+      if (!(await this.localGenerator.trackFile(madeTrackId))) {
+        throw Object.assign(new Error("Only the receipt of that track is left, so it can't be kept."), { code: "made_track_audio_not_kept" });
+      }
+      return [{ kind: "made", id: madeTrackId, title: String(receipt.title ?? "Moondog") }];
+    }
+    if (Array.isArray(songs) && songs.length) {
+      return songs.map((song) => ({ kind: "song", title: song.title, artist_credit: song.artist ?? song.artist_credit, ...(song.album ? { album: song.album } : {}) }));
+    }
+    const now = await readListeningNow(this, { signal });
+    const active = now.sources.find((source) => source.service === now.active);
+    if (!active?.song) throw Object.assign(new Error("Nothing is playing, so there is nothing to save."), { code: "library_nothing_playing" });
+    if (from === "queue") {
+      // What plays from now on: Moondog's whole remaining queue (its status shows only the next ten); the Music
+      // app's playlist from the song playing, which it places; otherwise the song and the service's own queue.
+      const remaining = active.service === "moondog" ? this.musicPreviewPlayer?.remaining?.() : null;
+      let playing = active.from;
+      // The Music app's status reads a window around the playing song; a longer playlist is read on to its end.
+      if (active.service === "apple_music" && playing?.tracks?.length && Number.isInteger(playing.tracks_total) &&
+          (playing.first_position ?? 1) - 1 + playing.tracks.length < playing.tracks_total && typeof this.musicApp?.remainingPlaylist === "function") {
+        const rest = await this.musicApp.remainingPlaylist().then((now) => musicAppSource(now).from, () => null);
+        if (rest?.tracks?.length && Number.isInteger(rest.position) && Number.isInteger(rest.first_position)) playing = rest;
+      }
+      const tracks = playing?.tracks;
+      const placed = tracks?.length && Number.isInteger(playing.position) && Number.isInteger(playing.first_position);
+      const list = remaining?.length ? remaining.map((track) => ({ title: track.title, artists: track.generated ? ["Moondog"] : [track.artist_credit].filter(Boolean),
+        ...(track.generated && track.id ? { made_track_id: track.id } : {}) }))
+        : placed ? tracks.slice(Math.max(0, playing.position - playing.first_position))
+          : [active.song, ...(active.next ?? [])];
+      return list.map((song) => this.#entryOfSong(song)).filter(Boolean);
+    }
+    const one = this.#entryOfSong(active.song);
+    if (!one) throw Object.assign(new Error("The song playing now has no artist to keep it by."), { code: "library_nothing_playing" });
+    return [one];
+  }
+
+  /**
+   * Keeps songs or made tracks in the library: in Saved when no playlist is named, in a playlist by id, or
+   * in a new playlist by name. by says who chose to keep them: the listener, or Moondog at their request.
+   */
+  async saveToLibrary({ from = "now_playing", songs, madeTrackId, playlistId, playlistName, folderId, artwork } = {}, { by = "listener", signal } = {}) {
+    const library = this.requireLibrary();
+    const entries = await this.#entriesToSave({ from, songs, madeTrackId }, { signal });
+    if (!entries.length) throw Object.assign(new Error("There is nothing to save."), { code: "library_nothing_playing" });
+    // The window passes the cover it shows for the song playing now.
+    if (artwork && from === "now_playing" && !songs?.length && !madeTrackId && entries[0].kind === "song") entries[0].refs = { artwork_url: artwork };
+    if (!playlistId && playlistName) {
+      const made = library.savePlaylist({ name: playlistName, folderId: folderId ?? null, origin: by === "moondog" ? "moondog" : "listener", entries, addedBy: by });
+      return { playlist: { id: made.id, name: library.playlist(made.id).name, created: true }, added: made.added, already: made.already,
+        titles: entries.map((entry) => entry.title) };
+    }
+    const target = playlistId ?? SAVED_PLAYLIST_ID;
+    const added = library.addEntries(target, entries, { addedBy: by });
+    const playlist = library.playlist(target);
+    return { playlist: { id: playlist.id, name: playlist.saved ? "Saved" : playlist.name, ...(playlist.saved ? { saved: true } : {}) },
+      added: added.added, already: added.already, titles: entries.map((entry) => entry.title) };
+  }
+
+  /**
+   * Reads a playlist link (Spotify, Apple Music, NetEase Music, QQ Music) and holds what it found for the
+   * listener to import: { token, provider, name, read, total, owned, sample }. owned is true for a playlist the
+   * listener made, false for one a service or someone else made, and null when the service doesn't say.
+   */
+  async previewPlaylistLink({ link } = {}, { signal } = {}) {
+    this.requireLibrary();
+    const parsed = parsePlaylistLink(link);
+    let found;
+    if (parsed.provider === "spotify") {
+      if (!this.spotifyReady()) throw Object.assign(new Error("Connect Spotify first, so Moondog can read its playlists."), { code: "spotify_not_ready" });
+      const playlist = await this.requireSpotifyService().readPlaylist({ playlistId: parsed.id }, { signal });
+      found = { provider: "spotify", id: parsed.id, url: parsed.url, name: playlist.name || "Spotify playlist", total: playlist.tracks_total, owned: playlist.owned,
+        tracks: playlist.tracks.map((track) => { const credit = track.artists.join(", "); return { id: track.uri, title: track.name, artist: credit,
+          ...(track.album ? { album: track.album } : {}), ...(track.isrc ? { isrc: track.isrc } : {}),
+          refs: { spotify_uri: track.uri, spotify_title: track.name, spotify_credit: credit } }; }) };
+    } else if (parsed.provider === "apple_music") {
+      const playlist = await readApplePlaylist(parsed, { signal });
+      // A playlist a listener shared has a pl.u- id; the others are Apple's own.
+      found = { ...playlist, owned: parsed.id.startsWith("pl.u-") ? null : false,
+        tracks: playlist.tracks.map((track) => ({ id: track.id, title: track.title, artist: track.artist, refs: { apple_music_id: track.id, ...(track.artwork ? { artwork_url: track.artwork } : {}) } })) };
+    } else {
+      const playlist = await readPublicPlaylistLink(parsed);
+      found = { ...playlist, owned: null, tracks: playlist.tracks.map((track) => ({ ...track, ...(playlist.provider === "netease" ? { refs: { netease_id: String(track.id) } } : {}) })) };
+    }
+    signal?.throwIfAborted();
+    // A library playlist holds up to 2,000 songs; a longer one comes in from its start, and total says how long it is.
+    found.tracks = found.tracks.filter((track) => track.title && track.artist).slice(0, 2000);
+    if (found.total === null || found.total === undefined) found.total = null;
+    if (!found.tracks.length) throw Object.assign(new Error("No songs could be read from this playlist."), { code: "playlist_empty" });
+    const token = randomUUID();
+    this.pendingPlaylistImports.set(token, found);
+    while (this.pendingPlaylistImports.size > 5) this.pendingPlaylistImports.delete(this.pendingPlaylistImports.keys().next().value);
+    return { token, provider: found.provider, name: found.name, read: found.tracks.length, total: found.total ?? null, owned: found.owned,
+      sample: found.tracks.slice(0, 3).map((track) => `${track.title} - ${track.artist}`) };
+  }
+
+  /**
+   * Imports a previewed playlist: a copy in the library that remembers its link, and, when taste is true, its songs
+   * as evidence of what the listener keeps. A playlist the listener didn't make shapes their taste only when they say so.
+   */
+  async importPlaylistLink({ token, taste, name, folderId } = {}) {
+    const library = this.requireLibrary();
+    const found = this.pendingPlaylistImports.get(String(token ?? ""));
+    if (!found) throw Object.assign(new Error("That preview is gone. Paste the link again."), { code: "playlist_preview_gone" });
+    const shapes = typeof taste === "boolean" ? taste : found.owned === true;
+    const made = library.savePlaylist({ name: typeof name === "string" && name.trim() ? name : found.name, folderId: folderId ?? null,
+      origin: found.provider, source: { provider: found.provider, id: found.id, url: found.url },
+      entries: found.tracks.map((track) => ({ kind: "song", title: track.title, artist_credit: track.artist,
+        ...(track.album ? { album: track.album } : {}), ...(track.isrc ? { isrc: track.isrc } : {}), refs: track.refs ?? {} })) });
+    this.pendingPlaylistImports.delete(String(token));
+    let tasteState = "not_added";
+    if (shapes) {
+      if (typeof this.playlistTaste !== "function") tasteState = "unavailable";
+      else tasteState = await this.playlistTaste(found).then(() => "added", () => "failed");
+    }
+    return { playlist: { id: made.id, name: library.playlist(made.id).name }, added: made.added, read: found.tracks.length,
+      total: found.total ?? null, owned: found.owned, taste: tasteState };
+  }
+
+  /** Reads and imports a playlist link in one step, as the agent and the terminal do. */
+  async importPlaylistFromLink({ link, taste, name, folderId } = {}, { signal } = {}) {
+    const preview = await this.previewPlaylistLink({ link }, { signal });
+    return { ...(await this.importPlaylistLink({ token: preview.token, taste, name, folderId })), provider: preview.provider };
+  }
+
+  /** Playlists by name for the agent, or the newest ones when no words are given. */
+  findLibraryPlaylists(query) {
+    return this.requireLibrary().findPlaylists(query).map(({ id, name, count, made, origin, saved }) => ({
+      id, name: saved ? "Saved" : name, count, made, origin, ...(saved ? { saved: true } : {}) }));
+  }
+
+  /**
+   * Plays a playlist from the library, from its first entry or from one entry. It plays on the listener's
+   * chosen service: Moondog's own player holds Apple Music songs and made tracks in one queue; Spotify and
+   * NetEase play its songs, and its made tracks wait for Moondog's own player (left_out_made says how many).
+   * The listener's own playlist is their pick, so nothing of it goes in the suggestions ledger.
+   */
+  async playLibrary({ playlistId, entryId, shuffle = false } = {}, { signal } = {}) {
+    const playlist = await this.libraryPlaylist(playlistId);
+    if (!playlist) throw Object.assign(new Error("That playlist is not in the library."), { code: "library_playlist_not_found" });
+    const named = { id: playlist.id, name: playlist.saved ? "Saved" : playlist.name };
+    let entries = playlist.entries;
+    const start = entryId ? entries.findIndex((entry) => entry.id === entryId) : 0;
+    entries = entries.slice(Math.max(0, start));
+    if (shuffle) entries = entries.map((entry) => [Math.random(), entry]).sort((a, b) => a[0] - b[0]).map(([, entry]) => entry);
+    const avoided = entries.filter((entry) => entry.kind === "song" && !this.avoidAllows({ title: entry.title, artist_credit: entry.artist_credit }));
+    entries = entries.filter((entry) => !avoided.includes(entry) && (entry.kind === "song" || entry.audio_kept));
+    const extra = avoided.length ? { skipped_avoided_count: avoided.length } : {};
+    if (!entries.length) return { state: "empty", playlist: named, ...extra };
+    const songs = entries.filter((entry) => entry.kind === "song");
+    const service = this.playbackService;
+    // Only made tracks, or Apple Music chosen: Moondog's own player, with both in one queue.
+    if ((!songs.length || service === "apple_music") && typeof this.musicPreviewPlayer?.playList === "function") {
+      const refs = [];
+      const avoidedFound = [];
+      const found = await mapLimited(entries.slice(0, 50), 6, async (entry) => {
+        if (entry.kind === "made") return { generated: true, id: entry.made_id, title: entry.title, file: await this.localGenerator.trackFile(entry.made_id) };
+        if (!this.musicCatalog) return null;
+        const result = await this.musicCatalog.findPreview({ title: entry.title, artist: entry.artist_credit }).catch(() => null);
+        if (result?.state !== "resolved") return null;
+        // The catalog's recording can credit more than the entry named (a feature, a longer title); an Avoid still holds.
+        if (!this.avoidAllows(result.track)) { avoidedFound.push(entry.id); return null; }
+        if (result.track.catalog_id) refs.push({ entryId: entry.id, refs: { apple_music_id: String(result.track.catalog_id),
+          ...(entry.refs?.artwork_url || !result.track.artwork_url ? {} : { artwork_url: result.track.artwork_url }) } });
+        return result.track;
+      });
+      signal?.throwIfAborted();
+      const tracks = found.filter(Boolean);
+      const notFound = found.length - tracks.length - avoidedFound.length;
+      const skipped = avoided.length + avoidedFound.length;
+      Object.assign(extra, skipped ? { skipped_avoided_count: skipped } : {});
+      if (!tracks.length) return { state: "not_found", playlist: named, not_found: notFound, ...extra };
+      this.libraryStore.rememberRefs(refs);
+      // A playlist replaces Moondog's stream and quiets the other players, as any music Moondog starts does.
+      await this.#endStream("replaced");
+      await this.quietOtherPlayers("apple_music", { signal });
+      signal?.throwIfAborted();
+      this.musicPreviewPlayer.playList(tracks);
+      return { state: "playing", player: "moondog", playlist: named, playing: tracks.length, not_found: notFound,
+        whole_songs: this.musicPreviewPlayer.wholeSongs?.() === true, ...extra };
+    }
+    const leftOut = entries.length - songs.length;
+    if (service === "spotify") {
+      if (!this.spotifyPlaybackReady()) throw Object.assign(new Error("Spotify is not ready to play here."), { code: "spotify_not_ready" });
+      const list = songs.slice(0, 100);
+      const refs = [];
+      const avoidedFound = [];
+      // A recording's own title and credit can name more than the entry does (a feature); an Avoid holds against it.
+      const allowed = (title, credit) => this.avoidAllows({ title, artist_credit: credit });
+      const uris = await mapLimited(list, 4, async (entry) => {
+        // A cached recording plays without a search, once its own credit passes today's Avoids.
+        if (entry.refs?.spotify_uri && entry.refs.spotify_credit) {
+          if (allowed(entry.refs.spotify_title ?? entry.title, entry.refs.spotify_credit)) return entry.refs.spotify_uri;
+          avoidedFound.push(entry.id);
+          return null;
+        }
+        const { matched } = await this.spotifyResolveSongs([{ title: entry.title, artist: entry.artist_credit }], { signal }).catch(() => ({ matched: [] }));
+        // A match reaches the model without its URI; the host keeps it under the match's reference.
+        const ref = matched[0]?.item_ref_id;
+        const known = ref ? this.spotifyHostReadItems().find((item) => item.item_ref_id === ref) : null;
+        const uri = typeof known?.uri === "string" ? known.uri : typeof matched[0]?.uri === "string" ? matched[0].uri : null;
+        if (!uri) return null;
+        const title = known?.name ?? matched[0]?.name ?? entry.title;
+        const credit = (known?.artists ?? matched[0]?.artists ?? []).join(", ") || entry.artist_credit;
+        refs.push({ entryId: entry.id, refs: { spotify_uri: uri, spotify_title: title, spotify_credit: credit } });
+        if (!allowed(title, credit)) { avoidedFound.push(entry.id); return null; }
+        return uri;
+      });
+      signal?.throwIfAborted();
+      this.libraryStore.rememberRefs(refs);
+      const playable = uris.filter(Boolean);
+      const skipped = avoided.length + avoidedFound.length;
+      Object.assign(extra, skipped ? { skipped_avoided_count: skipped } : {});
+      const unfound = list.length - playable.length - avoidedFound.length;
+      if (!playable.length) return { state: "not_found", playlist: named, not_found: unfound, left_out_made: leftOut, ...extra };
+      await this.quietOtherPlayers("spotify", { signal });
+      const receipt = await this.#resumeSpotifySelection({ uris: playable }, { signal, played: [] });
+      return { state: receipt.state === "accepted" ? "playing" : receipt.state, player: "spotify", playlist: named, playing: playable.length,
+        not_found: unfound, left_out_made: leftOut, ...extra };
+    }
+    if (service === "netease" && this.neteaseReady()) {
+      const player = this.requireNetease();
+      await this.quietOtherPlayers("netease", { signal });
+      const receipt = await player.play({ items: songs.slice(0, 20).map((entry) => ({ title: entry.title, artist: entry.artist_credit })), mode: "play",
+        intent: "播放听者自己的歌单", allow: (song) => this.avoidAllows(Array.isArray(song.artists)
+          ? { title: song.title, artist_credit: song.artists.join(", "), artists: song.artists } : song) });
+      return { state: receipt?.mode === "playing" ? "playing" : "not_found", player: "netease", playlist: named,
+        playing: receipt?.songs?.length ?? 0, left_out_made: leftOut, ...extra };
+    }
+    throw Object.assign(new Error("No player here can play this playlist."), { code: "library_no_player" });
+  }
+
   // Makes one instrumental track from the listener's taste and plays it in Moondog's own player.
   // The agent proposes sound descriptors, each with its source; the taste compiler keeps only the
   // ones it can trace and none that names an artist or a song. The track and its receipt stay on
   // this Mac, and its play goes in the ledger as Moondog's own, never as the listener's attention.
   // moment and request come from the agent's host, not from the model.
-  async makeTrack({ descriptors, bpm, bpmSource, seconds, title } = {}, { moment = null, request = null, transient = false, signal, onProgress } = {}) {
+  async makeTrack({ descriptors, bpm, bpmSource, seconds, title } = {}, { moment = null, request = null, transient = false, signal, onProgress, nameRecord } = {}) {
     const { compiled, receipt } = await this.#compileForGeneration({ descriptors, bpm, bpmSource, title }, { moment, request, transient });
     if (!compiled.usable) {
       return { state: "not_made", reason: compiled.descriptors.length ? "needs_a_sound" : "no_traceable_descriptors", dropped: compiled.dropped };
     }
     const prompt = stableAudioPrompt(compiled);
-    await this.#endStream("replaced");
-    const made = await this.localGenerator.generate({ prompt, seconds, title: compiled.title, receipt }, { signal, onProgress });
+    const endedStream = await this.#endStream("replaced");
+    const named = await this.#titleInSettingLanguage(compiled, nameRecord, signal);
+    const made = await this.localGenerator.generate({ prompt, seconds, title: named, receipt }, { signal, onProgress });
     // A reply stopped as the track finished keeps the track, but plays nothing over what is on now.
     await this.quietOtherPlayers("apple_music", { signal });
     // The terminal plays the file itself; the window asks for it by id and never sees the path.
     const file = await this.localGenerator.trackFile(made.id);
     // A reply stopped while the track was made, or while the other players paused, keeps the track but plays nothing.
     if (signal?.aborted) throw Object.assign(new Error("The track was made but not played, because the reply was stopped."), { code: "generation_stopped" });
+    // The replaced stream's track it cuts off was stopped by Moondog, not left by the listener.
+    if (endedStream) this.localGenerator.discard?.();
     this.musicPreviewPlayer.playGenerated({ id: made.id, title: made.title, seconds: made.duration_seconds, file });
     this.#noteGeneratedPlay(made);
     return { state: "playing", track: { id: made.id, title: made.title, seconds: made.duration_seconds, seed: made.seed },
@@ -632,26 +954,71 @@ export class MoondogApplication {
 
   // Starts Moondog's atmosphere stream from the listener's taste: its first track plays now, and
   // each next one is made while the last plays. Every track goes in the ledger as Moondog's pick.
-  async startStream({ descriptors, bpm, bpmSource, seconds, minutes, title } = {}, { moment = null, request = null, transient = false, signal, onProgress } = {}) {
+  async startStream({ descriptors, bpm, bpmSource, seconds, minutes, title } = {}, { moment = null, request = null, transient = false, signal, onProgress, nameRecord } = {}) {
     if (!this.streamReady()) throw Object.assign(new Error("A stream can't run here. Music making must be on, in the terminal room or the window."), { code: "stream_not_ready" });
     const { compiled, receipt } = await this.#compileForGeneration({ descriptors, bpm, bpmSource, title }, { moment, request, transient });
     if (!compiled.usable) {
       return { state: "not_made", reason: compiled.descriptors.length ? "needs_a_sound" : "no_traceable_descriptors", dropped: compiled.dropped };
     }
     await this.#endStream("replaced");
+    // The stream's name, which its first track carries, in the language Moondog is set to.
+    const named = await this.#titleInSettingLanguage(compiled, nameRecord, signal);
     // Other music pauses only once the first track exists, as for a single track.
-    const { made, prompt } = await this.atmosphereStream.start({ compiled, title: compiled.title, seconds, minutes, receipt },
-      { signal, onProgress, onTrack: (track) => this.#noteGeneratedPlay(track), beforePlay: () => this.quietOtherPlayers("apple_music", { signal }) });
+    let started;
+    try {
+      started = await this.atmosphereStream.start({ compiled, title: named, seconds, minutes, receipt },
+        { signal, onProgress, onTrack: (track) => this.#noteGeneratedPlay(track), beforePlay: () => this.quietOtherPlayers("apple_music", { signal }),
+          nameTrack: typeof nameRecord === "function" ? this.#streamNamer(nameRecord, compiled) : undefined });
+    } catch (error) {
+      // The listener turned it off while its first track was made: their choice, not a failure to retry.
+      if (error?.code === "generation_stopped" && error.ended === "asked" && !signal?.aborted) return { state: "not_made", reason: "stopped_by_listener" };
+      throw error;
+    }
+    const { made, prompt } = started;
     return { state: "streaming", minutes, track: { id: made.id, title: made.title, seconds: made.duration_seconds, seed: made.seed },
       prompt, shaped_by: compiled.descriptors, sources: tasteSources(compiled.descriptors), left_out: compiled.dropped,
       ...(compiled.bpm ? { bpm: compiled.bpm } : {}), elapsed_ms: made.elapsed_ms };
   }
 
+  // The agent writes a record's title itself, but can follow the conversation's language instead of
+  // the one Moondog is set to. A title in another language is named again in the setting's language,
+  // keeping its picture; if that cannot be done in time, the agent's title stays.
+  async #titleInSettingLanguage(compiled, nameRecord, signal) {
+    if (typeof nameRecord !== "function" || nameFitsLanguage(compiled.title, this.locale)) return compiled.title;
+    const terms = compiled.descriptors.map((descriptor) => descriptor.term);
+    const timeout = AbortSignal.timeout(TITLE_LANGUAGE_TIMEOUT_MS);
+    try {
+      const name = await Promise.race([
+        this.#streamNamer(nameRecord, compiled)({ draft: compiled.title, featured: terms.slice(0, 3), sound: terms.slice(3),
+          ...(compiled.bpm ? { bpm: compiled.bpm } : {}), earlier: [] }, { signal: signal ? AbortSignal.any([signal, timeout]) : timeout }),
+        new Promise((resolve) => { timeout.addEventListener("abort", () => resolve(null), { once: true }); }),
+      ]);
+      return name ?? compiled.title;
+    } catch {
+      return compiled.title;
+    }
+  }
+
+  // Names a stream's later tracks: the agent's namer asks the model, with the names of Moondog's recent
+  // tracks so it does not repeat them, and a name passes the same check as the agent's own titles and
+  // must be in the language Moondog is set to.
+  #streamNamer(nameRecord, compiled) {
+    return async (context, options) => {
+      const recent = (this.localGenerator?.recentTracks?.(8) ?? []).map((track) => track.title).filter(Boolean);
+      const name = acceptableRecordTitle(await nameRecord({ ...context, recent }, options), compiled.names);
+      // A name in another language than Moondog's setting is not kept.
+      return name && nameFitsLanguage(name, this.locale) ? name : null;
+    };
+  }
+
   // A single track or a new stream takes over from a running stream, once its next track stops being made.
+  // The stream's track plays on until the new one starts, so nothing goes silent while that is made.
+  // Says whether a stream ended.
   async #endStream(reason) {
-    if (!this.atmosphereStream?.active?.()) return;
+    if (!this.atmosphereStream?.active?.()) return false;
     this.atmosphereStream.stop(reason);
     for (let waited = 0; this.localGenerator?.busy?.() && waited < 5_000; waited += 100) await delay(100);
+    return true;
   }
 
   stopStream() {
@@ -659,6 +1026,21 @@ export class MoondogApplication {
     return stopped ? { state: "stopped", tracks_made: stopped.tracks_made } : { state: "not_running" };
   }
 
+  // What the window and the terminal show of the stream: { phase, started_at, ends_at, tracks_made }, or null.
+  streamView() {
+    return this.atmosphereStream?.view?.() ?? null;
+  }
+
+  // Each change of the stream, as { view, ended }; a host without a stream hears nothing.
+  subscribeStream(listener) {
+    return this.atmosphereStream?.subscribe?.(listener) ?? (() => {});
+  }
+
+  // Whether a Spotify device is this Mac, where its music and Moondog's would play over each other.
+  spotifyOnThisMac(device) {
+    return spotifyOnThisMac(device);
+  }
+
   // What the compiler may trace a descriptor to. Each cited finding is read from the saved reading.
   async #tasteContext({ descriptors, moment, request }) {
     const choices = this.domainServices?.listenerChoices?.()?.items ?? [];
@@ -708,10 +1090,13 @@ export class MoondogApplication {
   async playNetease({ items, mode, intent } = {}) {
     const player = this.requireNetease();
     this.requireListenerAvoids();
-    if (mode !== "queue") await this.quietOtherPlayers("netease");
+    const quiet = () => this.quietOtherPlayers("netease");
+    if (mode !== "queue") await quiet();
     // A found song lists its artists; a song asked for by name has only the name it was asked by.
-    const receipt = await player.play({ items, mode, intent, allow: (song) => this.avoidAllows(Array.isArray(song.artists)
-      ? { title: song.title, artist_credit: song.artists.join(", "), artists: song.artists } : song) });
+    // A queue with nothing loaded starts its first song, and quiets the others just before.
+    const receipt = await player.play({ items, mode, intent, ...(mode === "queue" ? { beforePlay: quiet } : {}),
+      allow: (song) => this.avoidAllows(Array.isArray(song.artists)
+        ? { title: song.title, artist_credit: song.artists.join(", "), artists: song.artists } : song) });
     if (["playing", "queued"].includes(receipt?.mode)) {
       const songs = receipt.songs ?? [];
       const slots = this.#mixSlots(songs.map((song) => ({ title: song.title, artists: song.artists })));
@@ -726,8 +1111,13 @@ export class MoondogApplication {
 
   async controlNetease({ action, positionSeconds } = {}) {
     const player = this.requireNetease();
+    const quiet = () => this.quietOtherPlayers("netease");
+    if (action === "resume") await quiet();
     if (action === "seek") await player.seek({ positionMs: Math.max(0, Number(positionSeconds) || 0) * 1000 });
-    else if (["pause", "resume", "next", "previous", "stop"].includes(action)) await player[action]();
+    // Next and previous start a song, so the other players go quiet just before; a refusal or a
+    // previous that only rewinds starts none.
+    else if (action === "next" || action === "previous") await player[action]({ beforePlay: quiet });
+    else if (["pause", "resume", "stop"].includes(action)) await player[action]();
     else throw Object.assign(new Error(`Unknown NetEase action: ${action}`), { code: "netease_failed" });
     return await player.nowPlaying();
   }
@@ -736,9 +1126,10 @@ export class MoondogApplication {
     return this.requireNetease().nowPlaying();
   }
 
-  // Whether any player the listener uses can be read: the Music app, Spotify or NetEase.
+  // Whether any player the listener uses can be read: Moondog's own, the Music app, Spotify or NetEase.
   listeningReadable() {
-    return this.musicApp?.available === true || this.spotifyReady() || this.neteaseReady();
+    return typeof this.musicPreviewPlayer?.nowPlaying === "function" || this.musicApp?.available === true ||
+      this.spotifyReady() || this.neteaseReady();
   }
 
   // What the listener plays right now on any of them, and what it plays from (src/core/listening-now.mjs).
@@ -829,12 +1220,13 @@ export class MoondogApplication {
     ]);
   }
 
-  // The service just left stops playing, so two services never play at once.
+  // The service just left stops playing, so two services never play at once. Moondog's stream is its
+  // own channel, not a service: its made tracks play on, and it ends only when a service song plays.
   async #stopPlaybackService(service) {
     try {
       if (service === "apple_music") {
-        this.atmosphereStream?.stop?.("service_change");
-        this.musicPreviewPlayer?.stop?.();
+        // Apple Music's songs in Moondog's player stop; a player that can't say what it holds stops, as before.
+        if (this.musicPreviewPlayer?.holdsCatalogSongs?.() !== false) this.musicPreviewPlayer?.stop?.();
         // The listener's own Music app too, when it plays.
         if ((await this.musicApp?.nowPlaying?.())?.state === "playing") await this.musicApp.pause();
       } else if (service === "netease" && this.neteasePlayer?.ready?.() === true) await this.neteasePlayer.stop();
@@ -846,6 +1238,52 @@ export class MoondogApplication {
     return this.playbackSelection.subscribe(listener);
   }
 
+  // What the agent can tell the listener about its own setup, and what it can change when asked.
+  async settingsStatus(runtime = {}) {
+    const playback = this.playbackStatus();
+    const choices = await this.modelSwitch?.choices().catch(() => []) ?? [];
+    return {
+      model: { provider: runtime.provider ?? null, model: runtime.model ?? null, ...(runtime.effort ? { effort: runtime.effort } : {}),
+        ...(this.modelSwitch ? { change: "moondog_settings model", choices } : { change: "not_by_agent" }),
+        where: "Settings › Models in the window, or /model in the terminal" },
+      music_service: { selected: playback.selected_service ?? null, effective: playback.effective_service ?? null,
+        available: (playback.services ?? []).filter((entry) => entry.available).map((entry) => entry.service),
+        change: "moondog_playback_service" },
+      reply_language: { current: this.locale, choices: Object.keys(LOCALES), change: "moondog_settings reply_language" },
+    };
+  }
+
+  // The reply language the listener asked for in words: used from the next reply on, saved like
+  // the language picker's choice, and shown by each surface.
+  async setReplyLanguage(code, runtime = {}) {
+    const locale = normalizeLocale(code);
+    if (!locale) throw Object.assign(new Error("Unsupported reply language."), { code: "unsupported_reply_language" });
+    const previous = this.locale;
+    this.locale = locale;
+    this.conversationLocale = locale;
+    // Asked for in words, the language holds in this conversation whatever language the listener writes in.
+    this.replyLanguagePin = locale;
+    await this.languageSelection?.change(locale);
+    return { ...await this.settingsStatus(runtime), changed: { setting: "reply_language", from: previous, to: locale } };
+  }
+
+  // A model the listener asked for in words, from their model menu: by provider/model, model ID or
+  // name. It takes over when this reply ends; a model not set up, or not signed in, is refused.
+  async requestModel(wanted, runtime = {}) {
+    if (!this.modelSwitch) throw Object.assign(new Error("This host cannot change the model from a conversation."), { code: "model_change_unavailable" });
+    const choices = await this.modelSwitch.choices();
+    const key = String(wanted ?? "").trim().toLowerCase();
+    const folded = (value) => String(value).toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "");
+    const match = choices.find((choice) => choice.model.toLowerCase() === key) ??
+      choices.find((choice) => choice.model.split("/").slice(1).join("/").toLowerCase() === key) ??
+      choices.find((choice) => folded(choice.name) === folded(key));
+    if (!match) throw Object.assign(new Error(`That model is not in the listener's model menu. Choose one of: ${choices.map((choice) => choice.model).join(", ") || "none"}. Others are added in Settings › Models or with /model.`), { code: "model_not_listed" });
+    if (!match.ready) throw Object.assign(new Error(`${match.model} is in the menu but not signed in. The listener signs in from Settings › Models or with /auth.`), { code: "model_not_signed_in" });
+    const [provider, ...rest] = match.model.split("/");
+    this.modelSwitch.request(this, { provider, model: rest.join("/") });
+    return { ...await this.settingsStatus(runtime), changed: { setting: "model", from: `${runtime.provider}/${runtime.model}`, to: match.model, takes_effect: "after this reply" } };
+  }
+
   // A host-only in-memory change, kept for hosts with no saved settings.
   setPlaybackService(service) {
     return this.playbackSelection.set(service);
@@ -1981,6 +2419,43 @@ export class MoondogApplication {
       truncated: result.truncated === true || raw.length > 10 };
   }
 
+  // Songs the listener named, by title and artist: the host searches Spotify for each one and
+  // keeps the result whose artist and title match, so the model passes no references and makes
+  // no second call. A song without a clear match is never guessed; its closest results come back
+  // with item_ref_id values, to choose from and play by reference.
+  async spotifyResolveSongs(songs, { signal, otherSources = [] } = {}) {
+    // Songs and a reference together are two choices of what to play; neither wins silently.
+    if (otherSources.length) throw spotifyResolutionError("spotify_playback_source_conflict", "Choose one playback source for resume: songs, or one reference. Nothing was played.");
+    if (!Array.isArray(songs) || songs.length < 1 || songs.length > 12 ||
+        songs.some((song) => typeof song?.title !== "string" || !song.title.trim() || typeof song?.artist !== "string" || !song.artist.trim())) {
+      throw spotifyResolutionError("invalid_spotify_songs", "Give from 1 to 12 songs, each with a title and an artist.");
+    }
+    const fold = (value) => foldedWords(normalizedTrackTitle(value));
+    const matched = [];
+    const unmatched = [];
+    for (const song of songs) {
+      const result = await this.spotifySearchTracks({ query: `${song.title} ${song.artist}`, type: "track", limit: 10 }, { signal });
+      const tracks = result.items.filter((item) => item.type === "track" && item.track_ref_id);
+      const wantedTitle = foldedWords(song.title);
+      const wantedCore = fold(song.title);
+      // The same artist: equal names, or one credited artist of a joint credit ("伍佰" in
+      // "伍佰 & China Blue"). A name inside another act's name ("Adele Tribute Band") is another act.
+      const credited = (name) => [name, ...String(name).split(ARTIST_CREDIT_SEPARATORS)].map(foldedWords).filter(Boolean);
+      const wantedArtists = new Set(credited(song.artist));
+      const byArtist = tracks.filter((item) => item.artists.some((artist) => credited(artist).some((name) => wantedArtists.has(name))));
+      // The exact title first. A version the listener named (a live take, a duet) must match as
+      // named; otherwise the same song in another version (a remaster) is the song asked for.
+      // Nothing looser is guessed: a shared prefix ("One", "One Tree Hill") is another song.
+      const versionNamed = wantedTitle !== wantedCore;
+      const pick = byArtist.find((item) => foldedWords(item.name) === wantedTitle) ??
+        (versionNamed ? undefined : byArtist.find((item) => fold(item.name) === wantedCore));
+      if (pick) matched.push(pick);
+      else unmatched.push({ title: song.title, artist: song.artist,
+        candidates: tracks.slice(0, 5).map(({ item_ref_id, name, artists, album }) => ({ item_ref_id, name, artists, ...(album ? { album } : {}) })) });
+    }
+    return { matched, unmatched };
+  }
+
   spotifyDiscoveryAllowed(item) {
     return this.avoidAllows({ title: item.name, artist_credit: item.artists.join(", "), artists: item.artists });
   }
@@ -2093,8 +2568,6 @@ export class MoondogApplication {
     this.requireSpotifyNonRemovalAction();
     const transaction = this.pendingPlaylistPromptTransaction;
     if (!transaction) throw spotifyResolutionError("spotify_queue_request_required", "Queueing runs inside a listener request.");
-    // An idle device starts the first song.
-    await this.quietOtherPlayers("spotify", { signal });
     // The model acts on the listener's words, as for a single queue entry. A parsed
     // count only sizes the batch; failing to parse a phrasing never blocks it.
     const intent = transaction.queueIntent ?? null;
@@ -2106,7 +2579,18 @@ export class MoondogApplication {
     // named in their language; otherwise a sensible batch from the candidates.
     const requested = intent?.requested ?? count ?? Math.min(itemRefs.length, 12);
     if (!Number.isInteger(requested) || requested < 1 || requested > 12) throw spotifyResolutionError("spotify_queue_count_limit", "A queue request supports 1 to 12 songs. No write was sent.");
-    const items = itemRefs.map(ref => this.requireSpotifyReadItem(ref, ["track"]));
+    // A reference the host never issued (a model's slip) is left out and counted; only a batch
+    // with no usable reference at all is refused.
+    const chosen = itemRefs.map((ref) => { try { return this.requireSpotifyReadItem(ref, ["track"]); } catch { return null; } }).filter(Boolean);
+    const skippedUnavailable = itemRefs.length - chosen.length;
+    if (!chosen.length) this.requireSpotifyReadItem(itemRefs[0], ["track"]);
+    // The rest of this request's verified discovery results by the artists the model picked stand
+    // behind its picks, in the order found, so a pick skipped as a duplicate or an Avoid still
+    // leaves the count asked for. A song by another artist may have been left out on purpose.
+    const pickedArtists = new Set(chosen.flatMap(item => item.artists));
+    const backups = transaction.discoveryPoolStarted ? (this.spotifyReadSelections.get("discovery") ?? [])
+      .filter(item => item.type === "track" && item.uri && !itemRefs.includes(item.item_ref_id) && item.artists.some(artist => pickedArtists.has(artist))) : [];
+    const items = [...chosen, ...backups].slice(0, 36);
     this.requireSpotifyWriteScopes(["user-modify-playback-state"]);
     this.requireSpotifyScopes(["user-read-playback-state"]);
     transaction.queueBatchAttempted = true;
@@ -2131,9 +2615,12 @@ export class MoondogApplication {
       knownTrack: intent?.excludeKnown ? track => this.domainServices?.isKnownDiscoveryTrack?.(track) === true : null });
     if (!receipt.queued.length && !receipt.stopped) transaction.queueBatchAttempted = false;
     const result = { ...receipt, action: "queue.batch", requested, queued_count: receipt.queued.length,
-      shortfall: requested - receipt.queued.length, queue_observation_truncated: observed.truncated === true };
+      shortfall: requested - receipt.queued.length, queue_observation_truncated: observed.truncated === true,
+      ...(skippedUnavailable ? { skipped_unavailable_count: skippedUnavailable } : {}) };
     this.spotifyDisplayedChoices = null;
     if (this.spotifyQueueRequest && (receipt.queued.length || receipt.stopped)) Object.assign(this.spotifyQueueRequest, { attempted: true, receipt: structuredClone(result) });
+    // Kept on the request itself, so a fill finds the batch even when no queue intent was parsed.
+    if (receipt.queued.length) transaction.batchReceipt = structuredClone(result);
     return result;
   }
 
@@ -2146,6 +2633,10 @@ export class MoondogApplication {
     const rest = new Set();
     while (album && queue.at(-1)?.album_uri === album && !rest.has(queue.at(-1).uri)) rest.add(queue.pop().uri);
     const seen = new Set([observed.currently_playing?.uri, ...queue.map(track => track.uri)].filter(Boolean));
+    // With nothing playing and nothing queued, Spotify has dropped what Moondog queued (its device
+    // went idle), so those songs were not heard: a new request may queue them again.
+    // A player that could not be read says nothing, so the songs stay held back.
+    if (!seen.size && player && player.is_playing !== true && !player.item) this.recentSimilarQueueUris.clear();
     for (const [uri, acceptedAt] of this.recentSimilarQueueUris) {
       if (Date.now() - acceptedAt > 15 * 60_000) this.recentSimilarQueueUris.delete(uri);
       else seen.add(uri);
@@ -2253,7 +2744,24 @@ export class MoondogApplication {
 
   async spotifyAddToQueue(input, { signal } = {}) {
     signal?.throwIfAborted();
-    this.requireSpotifyNonRemovalAction();
+    // A batch that came up short may be filled by single adds of songs it did not queue, one per
+    // missing song; anything else after a batch is refused as before.
+    const transaction = this.pendingPlaylistPromptTransaction;
+    const batch = transaction?.queueBatchAttempted && transaction.batchReceipt?.action === "queue.batch" ? transaction.batchReceipt : null;
+    // The retained receipt takes in each accepted fill, so its queued songs are the count so far.
+    const missing = batch ? (batch.requested ?? 0) - (batch.queued?.length ?? 0) : 0;
+    // Either supported reference names the song: a read's item_ref_id, or a retained or resolved track_ref_id.
+    const fillRef = input?.itemRefId ?? input?.trackRefId;
+    const resolved = batch && input?.trackRefId !== undefined ? this.spotifyResolutions.get(input.trackRefId) : null;
+    const candidate = !batch || fillRef === undefined ? null
+      : this.spotifyHostReadItems().find((entry) => entry.item_ref_id === fillRef || entry.track_ref_id === fillRef) ??
+        (resolved?.uri ? { type: "track", uri: resolved.uri, name: resolved.matched?.title ?? "", artists: resolved.matched?.artists ?? [] } : null);
+    // The same song is the same title by the same primary artist, as the batch itself decides.
+    const candidateSongs = candidate ? songKeys({ title: candidate.name, artist_credit: candidate.artists?.join(", ") ?? "", artists: candidate.artists ?? [] }) : [];
+    const fillsBatch = missing > 0 && candidate?.type === "track" &&
+      !batch.queued.some((queued) => songKeys(queued).some((key) => candidateSongs.includes(key))) &&
+      !(transaction.batchFillUris ?? []).includes(candidate.uri);
+    this.requireSpotifyNonRemovalAction({ batchFill: fillsBatch });
     let uri;
     if (input?.itemRefId !== undefined) {
       if (input.trackRefId !== undefined || input.uri !== undefined) throw spotifyResolutionError("spotify_queue_selection_conflict", "Choose one queue item.");
@@ -2266,11 +2774,37 @@ export class MoondogApplication {
     const item = this.spotifyHostReadItems().find(item => item.uri === uri);
     if (item && !this.#spotifyItemAllowed(item)) throw listenerAvoidError();
     const track = { track_ref_id: "single", title: item?.name ?? "the selected track", artist_credit: item?.artists?.join(", ") ?? "", artists: item?.artists ?? [], ...(item?.isrc ? { isrc: item.isrc } : {}) };
+    // A fill keeps the batch's own rules: nothing already in Spotify's queue or playing, and only
+    // unheard songs when the listener asked for those.
+    let fillRules = {};
+    if (fillsBatch) {
+      const service = this.requireSpotifyService();
+      const [observed, player] = await Promise.all([service.queue({ signal }), service.currentPlayer({ signal }).catch(() => null)]);
+      signal?.throwIfAborted();
+      const seenUris = this.#observedQueueUris(observed, player);
+      if (player?.item?.uri) seenUris.add(player.item.uri);
+      fillRules = { seenUris, ...(transaction.queueIntent?.excludeKnown ? { knownTrack: (entry) => this.domainServices?.isKnownDiscoveryTrack?.(entry) === true } : {}) };
+    }
     // One entry takes the same path as a batch: one device decision, start
     // playback when nothing is playing, and a check of Spotify's real queue.
-    const receipt = await this.#queueSpotifyTracks([track], new Map([["single", uri]]), { signal, deviceId: input.deviceId, rethrow: true });
+    const receipt = await this.#queueSpotifyTracks([track], new Map([["single", uri]]), { signal, deviceId: input.deviceId, rethrow: true, ...fillRules });
+    if (fillsBatch && !receipt.queued.length) {
+      throw spotifyResolutionError("spotify_queue_fill_skipped", receipt.skipped_known_count
+        ? "That song is one the listener already knows, and they asked for unheard songs only. Nothing was queued."
+        : "That song is already in Spotify's queue or playing. Nothing was queued; choose another song for the missing place.");
+    }
     this.recentSimilarQueueUris.set(uri, Date.now());
     while (this.recentSimilarQueueUris.size > 100) this.recentSimilarQueueUris.delete(this.recentSimilarQueueUris.keys().next().value);
+    if (fillsBatch) {
+      transaction.batchFillUris = [...(transaction.batchFillUris ?? []), uri];
+      // The receipt a later "queue, not playlist" reply shows says what is queued now.
+      for (const kept of [batch, this.spotifyQueueRequest?.receipt?.action === "queue.batch" ? this.spotifyQueueRequest.receipt : null]) {
+        if (!kept) continue;
+        kept.queued = [...kept.queued, ...receipt.queued];
+        kept.queued_count = kept.queued.length;
+        kept.shortfall = Math.max(0, (kept.requested ?? 0) - kept.queued.length);
+      }
+    }
     return { provider: "spotify", ok: true, effect: "write_external", action: "playback.queue.add", state: "accepted",
       ...(item?.name ? { targets: [{ title: item.name, artist_credit: item.artists.join(", ") }] } : {}),
       ...(receipt.device ? { device: receipt.device } : {}), ...(receipt.started_playback ? { started_playback: true } : {}),
@@ -2406,12 +2940,12 @@ export class MoondogApplication {
     }
   }
 
-  requireSpotifyNonRemovalAction({ quickEdit = false } = {}) {
+  requireSpotifyNonRemovalAction({ quickEdit = false, batchFill = false } = {}) {
     const requested = this.pendingPlaylistPromptTransaction?.queueIntent?.requested;
     if (requested != null && (!Number.isInteger(requested) || requested < 1 || requested > 12)) {
       throw spotifyResolutionError("spotify_queue_count_limit", "Specify one exact queue count from 1 to 12 songs. No write was sent.");
     }
-    if (this.pendingPlaylistPromptTransaction?.queueBatchAttempted) throw spotifyResolutionError("spotify_queue_batch_already_attempted", "The requested queue batch was already attempted. Keep its receipt; do not replay or add another action.");
+    if (this.pendingPlaylistPromptTransaction?.queueBatchAttempted && !batchFill) throw spotifyResolutionError("spotify_queue_batch_already_attempted", "The requested queue batch was already attempted. Keep its receipt; do not replay or add another action.");
     if (this.pendingPlaylistPromptTransaction?.quickEditIntent && !quickEdit) {
       throw spotifyResolutionError("spotify_quick_edit_action_conflict", "This request authorizes only its exact quick playlist edit. An earlier preview or another Spotify action needs its own explicit request.");
     }
@@ -3289,8 +3823,11 @@ export class MoondogApplication {
         const service = this.requireSpotifyService();
         target ??= await service.queueTarget({ ...(deviceId ? { deviceId } : {}) }, { signal });
         const device = target.deviceId ? { deviceId: target.deviceId } : {};
-        // Nothing is playing, so a queue entry has nowhere to go: start this song instead.
+        // Nothing is playing, so a queue entry has nowhere to go: start this song instead. That starts
+        // music, so the other players go quiet first; a queue behind a song already there starts none.
         const start = async () => {
+          await this.quietOtherPlayers("spotify", { signal });
+          signal?.throwIfAborted();
           dispatching = true;
           const receipt = await service.resume({ uris: [uri], ...device }, { signal });
           started = label(track);
@@ -3520,7 +4057,8 @@ export class MoondogApplication {
       musicPreviewReady: this.musicPreviewReady(),
       tasteChoicesReady: this.tasteChoicesReady(),
       localGenerationReady: this.localGenerationReady(),
-    }).filter(descriptor => !this.#playbackServiceExcludes(descriptor.capability_id));
+    }).filter(descriptor => !this.#playbackServiceExcludes(descriptor.capability_id) &&
+      (this.libraryReady() || !descriptor.capability_id.startsWith("collection.")));
   }
 
   async findArtistReleases(input) {
@@ -3911,7 +4449,7 @@ export class MoondogApplication {
       this.pendingPlaylistPromptTransaction = null;
     } finally {
       const owned = this.ownsServices
-        ? [this.memoryStore, this.domainServices, this.musicCatalog, this.musicSimilarity, this.musicPreviewPlayer, this.webResearch]
+        ? [this.memoryStore, this.libraryStore, this.domainServices, this.musicCatalog, this.musicSimilarity, this.musicPreviewPlayer, this.webResearch]
         : [this.domainServices];
       for (const service of owned) service?.close?.();
     }