@audiofool/moondog 0.3.0-beta.7 → 0.3.0-beta.9

package/src/core/moondog-application.mjs

@@ -19,10 +19,24 @@ 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 { normalizeConversationFolder, normalizeConversationLabel, normalizeMemoryContent, shortConversationTitle } from "../memory/local-memory-store.mjs";
 import { queueListeningIntent, queueCancellationRequested, unheardRequested } from "./spotify-listening-intent.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;
 
@@ -245,6 +259,8 @@ export class MoondogApplication {
     localGenerator = null,
     atmosphereStream = null,
     musicApp = null,
+    // The listener's library (src/core/library-store.mjs), shared by every conversation and both surfaces.
+    libraryStore = null,
     agentHostNotes = [],
     artistIdentityResolver = null,
     webResearch = null,
@@ -301,6 +317,7 @@ 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;
     // 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;
@@ -605,6 +622,210 @@ 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) };
+  }
+
+  /** 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
@@ -2286,7 +2507,11 @@ 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 chosen = 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.
@@ -2318,9 +2543,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;
   }
 
@@ -2444,7 +2672,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.");
@@ -2457,11 +2702,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 } : {}),
@@ -2597,12 +2868,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.");
     }
@@ -3714,7 +3985,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) {
@@ -4105,7 +4377,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?.();
     }

package/src/i18n/screen/es.mjs

@@ -1119,4 +1119,21 @@ export default {
   "downloading the model": "descargando el modelo",
   "checking the files": "comprobando los archivos",
   "Stable Audio 3's Python environment couldn't be set up. Check your connection, then use /generation download to try again.": "No se pudo preparar el entorno de Python de Stable Audio 3. Revisa tu conexión y usa /generation download para intentarlo de nuevo.",
+  "The library isn't available here.": "La biblioteca no está disponible aquí.",
+  "Saved": "Guardadas",
+  "Play one with `/library play <name>`, or keep the song playing now with `/library save`.": "Reproduce una con `/library play <nombre>` o guarda lo que suena con `/library save`.",
+  "No playlist is called “{name}”.": "No hay ninguna lista llamada “{name}”.",
+  "{name} has nothing in it yet.": "{name} aún no tiene nada.",
+  "None of its songs could be found.": "No se encontró ninguna de sus canciones.",
+  "Playing {name}.": "Reproduciendo {name}.",
+  "Moondog's tracks were left out. They play with Apple Music chosen.": "Las pistas de Moondog se quedaron fuera. Suenan con Apple Music elegido.",
+  "Some songs couldn't be found.": "No se encontraron algunas canciones.",
+  "Already in {name}.": "Ya está en {name}.",
+  "Saved.": "Guardada.",
+  "Saved to {name}.": "Guardada en {name}.",
+  "Use /library, /library play <name>, or /library save [playlist].": "Usa /library, /library play <nombre> o /library save [lista].",
+  "Your saved songs and playlists": "Tus canciones guardadas y tus listas",
+  "Look in the library": "Mirar en la biblioteca",
+  "Save to the library": "Guardar en la biblioteca",
+  "Play from the library": "Reproducir de la biblioteca",
 };

package/src/i18n/screen/ja.mjs

@@ -1119,4 +1119,21 @@ export default {
   "downloading the model": "モデルをダウンロード中",
   "checking the files": "ファイルを確認中",
   "Stable Audio 3's Python environment couldn't be set up. Check your connection, then use /generation download to try again.": "Stable Audio 3 の Python 環境を準備できませんでした。接続を確かめてから、/generation download でやり直してください。",
+  "The library isn't available here.": "ここではライブラリを使えません。",
+  "Saved": "保存済み",
+  "Play one with `/library play <name>`, or keep the song playing now with `/library save`.": "`/library play <名前>` で再生するか、`/library save` で再生中の曲を保存してください。",
+  "No playlist is called “{name}”.": "「{name}」というプレイリストはありません。",
+  "{name} has nothing in it yet.": "{name} にはまだ何もありません。",
+  "None of its songs could be found.": "曲がひとつも見つかりませんでした。",
+  "Playing {name}.": "{name} を再生しています。",
+  "Moondog's tracks were left out. They play with Apple Music chosen.": "Moondog の曲は再生されませんでした。Apple Music を選ぶと再生されます。",
+  "Some songs couldn't be found.": "見つからない曲がありました。",
+  "Already in {name}.": "すでに「{name}」にあります。",
+  "Saved.": "保存しました。",
+  "Saved to {name}.": "「{name}」に保存しました。",
+  "Use /library, /library play <name>, or /library save [playlist].": "/library、/library play <名前>、または /library save [プレイリスト] を使ってください。",
+  "Your saved songs and playlists": "保存した曲とプレイリスト",
+  "Look in the library": "ライブラリを見る",
+  "Save to the library": "ライブラリに保存",
+  "Play from the library": "ライブラリから再生",
 };

package/src/i18n/screen/pt.mjs

@@ -1119,4 +1119,21 @@ export default {
   "downloading the model": "baixando o modelo",
   "checking the files": "conferindo os arquivos",
   "Stable Audio 3's Python environment couldn't be set up. Check your connection, then use /generation download to try again.": "Não foi possível preparar o ambiente Python do Stable Audio 3. Verifique sua conexão e use /generation download para tentar de novo.",
+  "The library isn't available here.": "A biblioteca não está disponível aqui.",
+  "Saved": "Salvas",
+  "Play one with `/library play <name>`, or keep the song playing now with `/library save`.": "Toque uma com `/library play <nome>` ou salve o que está tocando com `/library save`.",
+  "No playlist is called “{name}”.": "Nenhuma playlist se chama “{name}”.",
+  "{name} has nothing in it yet.": "{name} ainda não tem nada.",
+  "None of its songs could be found.": "Nenhuma das músicas foi encontrada.",
+  "Playing {name}.": "Tocando {name}.",
+  "Moondog's tracks were left out. They play with Apple Music chosen.": "As faixas do Moondog ficaram de fora. Elas tocam com o Apple Music escolhido.",
+  "Some songs couldn't be found.": "Algumas músicas não foram encontradas.",
+  "Already in {name}.": "Já está em {name}.",
+  "Saved.": "Salva.",
+  "Saved to {name}.": "Salva em {name}.",
+  "Use /library, /library play <name>, or /library save [playlist].": "Use /library, /library play <nome> ou /library save [playlist].",
+  "Your saved songs and playlists": "Suas músicas salvas e playlists",
+  "Look in the library": "Olhar na biblioteca",
+  "Save to the library": "Salvar na biblioteca",
+  "Play from the library": "Tocar da biblioteca",
 };

package/src/i18n/screen/zh.mjs

@@ -1119,4 +1119,21 @@ export default {
   "downloading the model": "正在下载模型",
   "checking the files": "正在校验文件",
   "Stable Audio 3's Python environment couldn't be set up. Check your connection, then use /generation download to try again.": "没能准备好 Stable Audio 3 的 Python 环境。检查网络连接，再用 /generation download 重试。",
+  "The library isn't available here.": "这里用不了资料库。",
+  "Saved": "收藏",
+  "Play one with `/library play <name>`, or keep the song playing now with `/library save`.": "用 `/library play <名字>` 播放一个，或者用 `/library save` 收藏正在播放的歌。",
+  "No playlist is called “{name}”.": "没有叫“{name}”的播放列表。",
+  "{name} has nothing in it yet.": "{name} 里还是空的。",
+  "None of its songs could be found.": "里面的歌都没有找到。",
+  "Playing {name}.": "正在播放 {name}。",
+  "Moondog's tracks were left out. They play with Apple Music chosen.": "Moondog 做的曲子没有放。选择 Apple Music 时才会播放它们。",
+  "Some songs couldn't be found.": "有些歌没有找到。",
+  "Already in {name}.": "已经在“{name}”里了。",
+  "Saved.": "已收藏。",
+  "Saved to {name}.": "已收藏到“{name}”。",
+  "Use /library, /library play <name>, or /library save [playlist].": "用 /library、/library play <名字> 或 /library save [播放列表]。",
+  "Your saved songs and playlists": "你收藏的歌和播放列表",
+  "Look in the library": "翻翻资料库",
+  "Save to the library": "收进资料库",
+  "Play from the library": "播放资料库里的歌",
 };

package/src/integrations/apple-music/music-app.mjs

@@ -12,6 +12,8 @@ const READ_TIMEOUT_MS = 15_000;
 // A playlist longer than this is read as a window around the playing song.
 const PLAYLIST_WINDOW = 50;
 const PLAYLIST_BEFORE = 5;
+// Keeping the rest of a playlist reads up to as many songs as a library playlist holds.
+const REST_MAX = 2_000;
 const COLUMN_READ_MAX = 2_000;
 // Covers already drawn, by album, or by song for one without an album.
 const KNOWN_COVERS = 40;
@@ -47,13 +49,15 @@ function run(argv) {
     const playlist = music.currentPlaylist;
     answer.playlist = { id: playlist.persistentID(), name: playlist.name() };
     try { answer.playlist.special = playlist.specialKind(); } catch (error) {}
-    if (action === "tracks") {
+    if (action === "tracks" || action === "rest") {
       const tracks = playlist.tracks;
       const ids = tracks.persistentID();
       answer.playlist.count = ids.length;
       const at = answer.track ? ids.indexOf(answer.track.id) : -1;
-      const start = ids.length <= ${PLAYLIST_WINDOW} || at < 0 ? 0 : Math.max(0, Math.min(at - ${PLAYLIST_BEFORE}, ids.length - ${PLAYLIST_WINDOW}));
-      const end = Math.min(ids.length, start + ${PLAYLIST_WINDOW});
+      // "rest" reads from the playing song to the playlist's end, for keeping it in the library.
+      const start = action === "rest" ? Math.max(0, at)
+        : ids.length <= ${PLAYLIST_WINDOW} || at < 0 ? 0 : Math.max(0, Math.min(at - ${PLAYLIST_BEFORE}, ids.length - ${PLAYLIST_WINDOW}));
+      const end = Math.min(ids.length, start + (action === "rest" ? ${REST_MAX} : ${PLAYLIST_WINDOW}));
       answer.playlist.index = at;
       answer.playlist.start = start;
       answer.playlist.tracks = [];
@@ -197,6 +201,8 @@ export function createMusicAppPlayer({ platform = process.platform, run = osascr
   return {
     available,
     nowPlaying: ({ tracks = false } = {}) => read(tracks ? "tracks" : "read"),
+    // The playing song and the rest of its playlist, past the window nowPlaying reads, for keeping in the library.
+    remainingPlaylist: () => read("rest"),
     pause: () => read("pause"),
     resume: () => read("resume"),
     next: () => read("next"),

package/src/integrations/apple-music/terminal-preview-player.mjs

@@ -19,6 +19,8 @@ const systemPlayers = {
   ],
 };
 const longestQueue = 30;
+// A library playlist plays as many entries as the application sends it, as the window does.
+const longestPlaylist = 50;
 const largestPreview = 10 * 1024 * 1024;
 // Some routes to Apple's audio host take over 20 seconds for one preview.
 const downloadTimeoutMs = 60_000;
@@ -213,13 +215,29 @@ export async function createTerminalPreviewPlayer({
       });
       start(accepted);
     },
+    // A playlist from the listener's library: Apple Music previews and tracks Moondog made, in one queue.
+    // A song is { title, artist_credit, catalog_url, preview_url }; a made track { generated: true, id, title, file }.
+    playList(tracks) {
+      if (closed) return;
+      const accepted = (Array.isArray(tracks) ? tracks : []).map((track) => (track?.generated === true
+        ? { title: String(track.title ?? "").trim(), artist_credit: "", generated: true, id: String(track.id ?? ""),
+          file: typeof track.file === "string" && path.isAbsolute(track.file) ? track.file : null }
+        : { title: String(track?.title ?? "").trim(), artist_credit: String(track?.artist_credit ?? "").trim(),
+          catalog_url: https(track?.catalog_url, linkHost), preview: https(track?.preview_url, previewHost) }))
+        .filter((track) => track.title && (track.generated ? track.file : track.catalog_url && track.preview)).slice(0, longestPlaylist);
+      if (!accepted.length) return;
+      stop();
+      emit({ type: "queue", tracks: accepted.map(({ title, artist_credit, catalog_url, generated, id }) => (generated
+        ? { title, artist_credit: "", generated: true, id } : { title, artist_credit, catalog_url })), album: null });
+      start(accepted);
+    },
     // A track Moondog made on this Mac: { id, title, file }, played whole and kept after it ends.
     playGenerated({ id, title, file } = {}) {
       const name = String(title ?? "").trim();
       if (closed || !name || typeof file !== "string" || !path.isAbsolute(file)) return;
       stop();
       const track = { title: name, artist_credit: "", generated: true, id: String(id ?? "") };
-      emit({ type: "queue", tracks: [{ title: track.title, artist_credit: "", generated: true }], album: null });
+      emit({ type: "queue", tracks: [{ title: track.title, artist_credit: "", generated: true, id: track.id }], album: null });
       start([{ ...track, file }]);
     },
     // A made track queued behind the one playing, as Moondog's stream does; with nothing playing, it plays now.
@@ -228,7 +246,7 @@ export async function createTerminalPreviewPlayer({
       if (closed || !name || typeof file !== "string" || !path.isAbsolute(file)) return;
       if (!queue || !queue.tracks.every((track) => track.generated)) return this.playGenerated({ id, title, file });
       queue.tracks.push({ title: name, artist_credit: "", generated: true, id: String(id ?? ""), file });
-      now.appended({ title: name, generated: true });
+      now.appended({ title: name, generated: true, id: String(id ?? "") });
     },
     // Ends the song now playing, or still loading; the next one starts after it.
     skip() {
@@ -240,6 +258,8 @@ export async function createTerminalPreviewPlayer({
     stop,
     // What plays now, as createPlayerNow reads it: null, or { state, song, position, count, next }.
     nowPlaying: () => (closed ? null : now.read()),
+    // The song playing and every one after it, for keeping the whole queue in the library.
+    remaining: () => (closed ? [] : now.remaining()),
     // Leaving Apple Music stops its previews here, never the tracks Moondog made.
     holdsCatalogSongs: () => Boolean(queue?.tracks.some((track) => !track.generated)),
     subscribe(listener) {

package/src/integrations/stable-audio/local-generator.mjs

@@ -229,6 +229,8 @@ export function createLocalGenerator({
   arch = process.arch,
   spawnImpl = spawn,
   now = () => new Date(),
+  // Whether the listener's library holds a made track: a stream never drops the audio of one they kept.
+  keeps = () => false,
 } = {}) {
   let current = { state: "unknown", enabled: false, install: "unknown", path: null, source: null, model: DEFAULT_STABLE_AUDIO_MODEL, managed: false };
   let running = null;
@@ -437,6 +439,9 @@ export function createLocalGenerator({
           close(false);
           playing = { id: track.id, heardMs: 0, since: Date.now() };
         } else if (playing.since === null) playing.since = Date.now();
+      } else if (event?.type === "playing" && playing && track && track.generated !== true) {
+        // A song from the catalog after a made track in a library playlist: the made track's play ended there.
+        close(false);
       } else if (event?.type === "paused" && playing && playing.since !== null) {
         playing.heardMs += Date.now() - playing.since;
         playing.since = null;
@@ -452,9 +457,11 @@ export function createLocalGenerator({
     /** Waits for the outcomes still being written, as a room does before it closes. */
     flush: () => Promise.allSettled([...writing]),
     // A replay of the track playing now starts it over; that is not a skip.
-    // A stream keeps only its newest tracks' audio; the receipt and outcomes of the rest stay.
+    // A stream keeps only its newest tracks' audio; the receipt and outcomes of the rest stay. A track in the
+    // listener's library keeps its audio, and a library that can't be read keeps it too.
     async removeAudio(id) {
       if (!isGeneratedTrackId(id)) return;
+      try { if (keeps(id)) return; } catch { return; }
       await rm(path.join(tracksDirectory(), id, "track.wav"), { force: true }).catch(() => {});
       const entry = made.get(id);
       if (entry) entry.audio_kept = false;