@audiofool/moondog 0.1.0 → 0.2.0-beta.2

package/src/importers/apple-music-library/index.mjs

@@ -3,7 +3,6 @@ import {
   normalizeAppleMusicLibrary,
   summarizeAppleMusicLibrary,
 } from "./normalize.mjs";
-import { writeAppleMusicImportBatch } from "./import-batch.mjs";
 
 export {
   AppleMusicImportError,
@@ -33,7 +32,6 @@ export {
   computeAppleSqliteLogicalDigest,
   defaultAppleMusicProjectionPath,
   defaultAppleMusicProjectionPathFor,
-  legacyAppleMusicProjectionPath,
   openAppleMusicSqliteProjection,
   rebuildAppleMusicSqliteProjection,
 } from "./sqlite-projection.mjs";
@@ -60,17 +58,3 @@ export async function buildAppleMusicLibraryImport(
   const parsed = await readAppleMusicLibrary(inputPath, { limits });
   return normalizeAppleMusicLibrary(parsed, { subjectId });
 }
-
-export async function importAppleMusicLibraryFile(
-  inputPath,
-  { subjectId, outputRoot, outputBoundary, limits } = {},
-) {
-  const records = await buildAppleMusicLibraryImport(inputPath, {
-    subjectId,
-    limits,
-  });
-  return writeAppleMusicImportBatch(records, {
-    outputRoot,
-    boundaryRoot: outputBoundary,
-  });
-}

package/src/importers/apple-music-library/sqlite-projection.mjs

@@ -9,13 +9,13 @@ import {
   unlink,
 } from "node:fs/promises";
 import path from "node:path";
-import { fileURLToPath } from "node:url";
 
 import {
   canonicalizeJson,
   sha256Hex,
 } from "../../../scripts/contract-semantics.mjs";
 import { resolveMoondogStateDirectory } from "../../core/state-directory.mjs";
+import { uuidV5 } from "../../core/uuid-v5.mjs";
 import { AppleMusicImportError } from "./parse-plist.mjs";
 import { listAppleMusicImportBatches } from "./read-batch.mjs";
 import { promoteAppleMusicImportBatches } from "./projection-records.mjs";
@@ -25,14 +25,6 @@ export const APPLE_SQLITE_PROJECTION_VERSION = 1;
 export const APPLE_LIBRARY_SEARCH_HARD_LIMIT = 25;
 export const APPLE_LIBRARY_SEARCH_HARD_OFFSET = 10_000;
 export const APPLE_PROFILE_SUMMARY_HARD_LIMIT = 50;
-// Earlier versions kept the projection inside the source checkout.
-export const legacyAppleMusicProjectionPath = fileURLToPath(
-  new URL(
-    "../../../data/private/apple-music-library/projection.sqlite",
-    import.meta.url,
-  ),
-);
-
 export function defaultAppleMusicProjectionPathFor(environment = process.env) {
   return path.join(resolveMoondogStateDirectory(environment), "apple-music-library", "projection.sqlite");
 }
@@ -1188,6 +1180,56 @@ class AppleMusicSqliteProjection {
     };
   }
 
+  getProfileCatalog({ excludePreference = () => false } = {}) {
+    this.#assertOpen();
+    // Aggregate preference evidence per track before joining, so a loved and
+    // rated track contributes once to each facet's track count.
+    const tracks = this.#database.prepare(`SELECT s.track_ref_id, s.title AS label,
+      s.artist_credit, s.release_title AS release, s.genre_label AS genre,
+      s.play_count, s.loved, s.favorited, s.rating_value, s.rating_computed,
+      COALESCE(p.strength, 0) AS preference_strength, p.evidence_id
+      FROM library_search s LEFT JOIN (
+        SELECT subject_id, track_ref_id, MAX(strength) AS strength, MIN(evidence_id) AS evidence_id
+        FROM profile_evidence WHERE claim_dimension = 'taste.track_preference' AND direction = 'supports'
+        GROUP BY subject_id, track_ref_id
+      ) p ON p.subject_id = s.subject_id AND p.track_ref_id = s.track_ref_id
+      WHERE s.subject_id = ? ORDER BY preference_strength DESC, s.play_count DESC, s.track_ref_id`)
+      .all(this.#subjectId).map((row) => ({
+        ...Object.fromEntries(Object.entries(row).filter(([, value]) => value !== null)),
+        preference_strength: excludePreference(row) ? 0 : row.preference_strength,
+      })).sort((a, b) => b.preference_strength - a.preference_strength ||
+        (b.play_count ?? -1) - (a.play_count ?? -1) || a.track_ref_id.localeCompare(b.track_ref_id));
+    const facets = (field) => {
+      const grouped = new Map();
+      for (const track of tracks) {
+        if (!track[field]?.trim()) continue;
+        const key = normalizedText(track[field]);
+        const item = grouped.get(key) ?? {
+          name: track[field], library_tracks: 0, preferred_tracks: 0, play_count: 0,
+          tracks_with_play_count: 0, preference_strength: 0,
+          evidence_id: uuidV5(`${this.#subjectId}\0apple-${field}\0${key}`, "5d9a8b8d-c66c-547f-98c2-c8a0559f56be"),
+        };
+        item.library_tracks++;
+        if (track.preference_strength > 0) item.preferred_tracks++;
+        item.preference_strength += track.preference_strength;
+        if (track.play_count !== undefined) { item.play_count += track.play_count; item.tracks_with_play_count++; }
+        grouped.set(key, item);
+      }
+      return [...grouped.values()].sort((a, b) => b.preference_strength - a.preference_strength ||
+        b.library_tracks - a.library_tracks || a.name.localeCompare(b.name));
+    };
+    return {
+      coverage: {
+        apple_library_tracks: tracks.length,
+        apple_preferred_tracks: tracks.filter((track) => track.preference_strength > 0).length,
+        apple_tracks_with_play_count: tracks.filter((track) => track.play_count !== undefined).length,
+        apple_aggregate_plays: tracks.reduce((sum, track) => sum + (track.play_count ?? 0), 0),
+        apple_snapshot_at: readMeta(this.#database, "projection.source_timestamp"),
+      },
+      sections: { apple_tracks: tracks, apple_artists: facets("artist_credit"), apple_genres: facets("genre") },
+    };
+  }
+
   explainProfileEvidence({ evidenceId } = {}) {
     this.#assertOpen();
     if (!isUuid(evidenceId)) {

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

@@ -1,4 +1,5 @@
 import { uuidV5 } from "../../core/uuid-v5.mjs";
+import { appleMusicStorefront } from "./storefront.mjs";
 
 export const APPLE_MUSIC_CATALOG_TRACK_NAMESPACE =
   "2837a09e-e5f0-5aa5-b271-bb99d8b0de20";
@@ -115,6 +116,45 @@ function safeAppleMusicUrl(value) {
   }
 }
 
+// Apple serves 30-second previews only from its own audio host.
+function safePreviewUrl(value) {
+  const cleaned = safeText(value, 2_048);
+  if (!cleaned) return null;
+  try {
+    const url = new URL(cleaned);
+    return url.protocol === "https:" && url.hostname === "audio-ssl.itunes.apple.com" ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+// Cover art comes only from Apple's image hosts, at the size a small player needs.
+function safeArtworkUrl(value) {
+  const cleaned = safeText(value, 2_048);
+  if (!cleaned) return null;
+  try {
+    const url = new URL(cleaned);
+    if (url.protocol !== "https:" || !url.hostname.endsWith(".mzstatic.com")) return null;
+    return url.toString().replace(/\/100x100bb\./u, "/300x300bb.");
+  } catch {
+    return null;
+  }
+}
+
+function normalizeAlbum(raw) {
+  if (!isPlainObject(raw) || raw.wrapperType !== "collection") return null;
+  const catalogId = safeCatalogId(raw.collectionId);
+  const title = safeText(raw.collectionName, 512);
+  const artistCredit = safeText(raw.artistName, 256);
+  if (!catalogId || !title || !artistCredit) return null;
+  const album = { catalog_id: catalogId, title, artist_credit: artistCredit };
+  const catalogUrl = safeAppleMusicUrl(raw.collectionViewUrl);
+  const artworkUrl = safeArtworkUrl(raw.artworkUrl100);
+  if (catalogUrl) album.catalog_url = catalogUrl;
+  if (artworkUrl) album.artwork_url = artworkUrl;
+  return album;
+}
+
 function releaseDate(value) {
   if (typeof value !== "string") return null;
   const matched = /^(\d{4}-\d{2}-\d{2})T/u.exec(value);
@@ -214,6 +254,10 @@ function normalizeTrack(raw) {
   if (primaryGenre) track.primary_genre = primaryGenre;
   if (catalogUrl) track.catalog_url = catalogUrl;
   if (date) track.release_date = date;
+  const previewUrl = safePreviewUrl(raw.previewUrl);
+  const artworkUrl = safeArtworkUrl(raw.artworkUrl100);
+  if (previewUrl) track.preview_url = previewUrl;
+  if (artworkUrl) track.artwork_url = artworkUrl;
   return track;
 }
 
@@ -237,7 +281,7 @@ function deduplicateAndSortReleases(releases) {
   });
 }
 
-function sourceMetadata(now) {
+function sourceMetadata(now, storefront) {
   const current = now();
   if (!Number.isFinite(current)) {
     fail("apple_music_catalog_clock_invalid", "The catalog clock is invalid.");
@@ -245,10 +289,10 @@ function sourceMetadata(now) {
   return {
     provider: "apple_music",
     catalog: "itunes_search_api",
-    storefront: "US",
+    storefront: storefront(),
     retrieved_at: new Date(current).toISOString(),
     coverage:
-      "Apple Music US storefront catalog only. This is not a claim about every music platform.",
+      `Apple Music ${storefront()} storefront catalog only. This is not a claim about every music platform.`,
   };
 }
 
@@ -353,6 +397,7 @@ export function createAppleMusicCatalogClient({
   fetchImpl = globalThis.fetch,
   now = Date.now,
   cacheTtlMs = APPLE_MUSIC_CATALOG_LIMITS.cacheTtlMs,
+  storefront = appleMusicStorefront,
 } = {}) {
   if (typeof fetchImpl !== "function") {
     throw new TypeError("A fetch implementation is required.");
@@ -386,11 +431,11 @@ export function createAppleMusicCatalogClient({
 
   async function artistCatalog(artistId) {
     const catalogId = cleanArtistCatalogId(artistId);
-    const key = `artist-catalog|US|${catalogId}`;
+    const key = `artist-catalog|${storefront()}|${catalogId}`;
     return cachedRequest(cache, key, cacheTtlMs, now, async () => {
       const results = await request("/lookup", {
         id: catalogId,
-        country: "us",
+        country: storefront().toLowerCase(),
         entity: "album",
         limit: APPLE_MUSIC_CATALOG_LIMITS.releasesPerArtistMax,
         sort: "recent",
@@ -415,11 +460,11 @@ export function createAppleMusicCatalogClient({
         "apple_music_catalog_query_invalid",
         "catalog query",
       );
-      const key = `tracks|US|${normalizeForMatch(cleaned)}`;
+      const key = `tracks|${storefront()}|${normalizeForMatch(cleaned)}`;
       return cachedRequest(cache, key, cacheTtlMs, now, async () => {
         const results = await request("/search", {
           term: cleaned,
-          country: "us",
+          country: storefront().toLowerCase(),
           media: "music",
           entity: "song",
           limit: APPLE_MUSIC_CATALOG_LIMITS.trackSearchResultsMax,
@@ -429,6 +474,31 @@ export function createAppleMusicCatalogClient({
       });
     },
 
+    async searchAlbums(query) {
+      const cleaned = cleanInputText(query, APPLE_MUSIC_CATALOG_LIMITS.discoveryQueryLengthMax, "apple_music_catalog_query_invalid", "album query");
+      const key = `albums|${storefront()}|${normalizeForMatch(cleaned)}`;
+      return cachedRequest(cache, key, cacheTtlMs, now, async () => {
+        const results = await request("/search", { term: cleaned, country: storefront().toLowerCase(), media: "music", entity: "album", limit: 10 });
+        return results.map(normalizeAlbum).filter(Boolean);
+      });
+    },
+
+    // Every song on one album, in disc and track order.
+    async albumTracks(albumId) {
+      const catalogId = typeof albumId === "string" && /^\d{1,20}$/u.test(albumId) ? albumId : null;
+      if (!catalogId) fail("apple_music_catalog_query_invalid", "The album identity is invalid.");
+      const key = `album-tracks|${storefront()}|${catalogId}`;
+      return cachedRequest(cache, key, cacheTtlMs, now, async () => {
+        const results = await request("/lookup", { id: catalogId, country: storefront().toLowerCase(), entity: "song", limit: 200 });
+        const order = (raw) => (Number.isSafeInteger(raw?.discNumber) ? raw.discNumber : 1) * 1000 + (Number.isSafeInteger(raw?.trackNumber) ? raw.trackNumber : 999);
+        return results
+          .filter((raw) => isPlainObject(raw) && raw.kind === "song")
+          .sort((left, right) => order(left) - order(right))
+          .map(normalizeTrack)
+          .filter(Boolean);
+      });
+    },
+
     async searchArtists(artistName) {
       const cleaned = cleanInputText(
         artistName,
@@ -436,11 +506,11 @@ export function createAppleMusicCatalogClient({
         "apple_music_catalog_artist_invalid",
         "artist name",
       );
-      const key = `artists|US|${normalizeForMatch(cleaned)}`;
+      const key = `artists|${storefront()}|${normalizeForMatch(cleaned)}`;
       return cachedRequest(cache, key, cacheTtlMs, now, async () => {
         const results = await request("/search", {
           term: cleaned,
-          country: "us",
+          country: storefront().toLowerCase(),
           media: "music",
           entity: "musicArtist",
           attribute: "artistTerm",
@@ -472,7 +542,8 @@ function candidateSummary(artist, releases = []) {
 }
 
 export function createAppleMusicCatalog({
-  client = createAppleMusicCatalogClient(),
+  storefront = appleMusicStorefront,
+  client = createAppleMusicCatalogClient({ storefront }),
   now = Date.now,
 } = {}) {
   if (
@@ -526,9 +597,9 @@ export function createAppleMusicCatalog({
         resultSets.push(await client.searchTracks(query));
       }
       const source = {
-        ...sourceMetadata(now),
+        ...sourceMetadata(now, storefront),
         coverage:
-          "Keyword relevance from the Apple Music US storefront. Results are external catalog candidates, not proof of personal fit, novelty, or cross-platform availability.",
+          `Keyword relevance from the Apple Music ${storefront()} storefront. Results are external catalog candidates, not proof of personal fit, novelty, or cross-platform availability.`,
       };
       const tracks = interleaveTrackResults(
         resultSets,
@@ -544,6 +615,44 @@ export function createAppleMusicCatalog({
       };
     },
 
+    // One named recording with a playable preview: the exact title first, then a version of it.
+    async findPreview({ title, artist } = {}) {
+      const cleanedTitle = cleanInputText(title, APPLE_MUSIC_CATALOG_LIMITS.discoveryQueryLengthMax, "apple_music_catalog_query_invalid", "track title");
+      const cleanedArtist = cleanInputText(artist, APPLE_MUSIC_CATALOG_LIMITS.discoveryQueryLengthMax, "apple_music_catalog_query_invalid", "artist");
+      const wantedTitle = normalizeForMatch(cleanedTitle);
+      const wantedArtist = normalizeForMatch(cleanedArtist);
+      const results = (await client.searchTracks(`${cleanedArtist} ${cleanedTitle}`))
+        .filter((track) => track.preview_url && normalizeForMatch(track.artist_credit).includes(wantedArtist));
+      const track = results.find((candidate) => normalizeForMatch(candidate.title) === wantedTitle) ??
+        results.find((candidate) => normalizeForMatch(candidate.title).startsWith(wantedTitle));
+      return {
+        state: track ? "resolved" : "not_found",
+        source: sourceMetadata(now, storefront),
+        ...(track ? { track } : {}),
+      };
+    },
+
+    // One named album's previews, in order: the exact title first, then an edition of it.
+    async findAlbumPreviews({ title, artist } = {}) {
+      if (typeof client.searchAlbums !== "function" || typeof client.albumTracks !== "function") {
+        fail("apple_music_catalog_unavailable", "Album previews are unavailable.");
+      }
+      const cleanedTitle = cleanInputText(title, APPLE_MUSIC_CATALOG_LIMITS.discoveryQueryLengthMax, "apple_music_catalog_query_invalid", "album title");
+      const cleanedArtist = cleanInputText(artist, APPLE_MUSIC_CATALOG_LIMITS.discoveryQueryLengthMax, "apple_music_catalog_query_invalid", "artist");
+      const wantedTitle = normalizeForMatch(cleanedTitle);
+      const wantedArtist = normalizeForMatch(cleanedArtist);
+      const albums = (await client.searchAlbums(`${cleanedArtist} ${cleanedTitle}`))
+        .filter((candidate) => normalizeForMatch(candidate.artist_credit).includes(wantedArtist));
+      const album = albums.find((candidate) => normalizeForMatch(candidate.title) === wantedTitle) ??
+        albums.find((candidate) => normalizeForMatch(candidate.title).startsWith(wantedTitle));
+      const tracks = album ? (await client.albumTracks(album.catalog_id)).filter((track) => track.preview_url).slice(0, 30) : [];
+      return {
+        state: tracks.length ? "resolved" : "not_found",
+        source: sourceMetadata(now, storefront),
+        ...(tracks.length ? { album, tracks } : {}),
+      };
+    },
+
     async findArtistReleasesByCatalogId({
       artistCatalogId,
       limit = 6,
@@ -565,7 +674,7 @@ export function createAppleMusicCatalog({
           "Explicit Apple Music artist lookup is unavailable.",
         );
       }
-      const source = sourceMetadata(now);
+      const source = sourceMetadata(now, storefront);
       const artist = await client.artistIdentity(catalogId);
       if (!artist) {
         return {
@@ -635,7 +744,7 @@ export function createAppleMusicCatalog({
         );
       }
 
-      const source = sourceMetadata(now);
+      const source = sourceMetadata(now, storefront);
       const normalizedArtist = normalizeForMatch(artist);
       let selected = null;
       let selectedReleases = [];

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

@@ -0,0 +1,232 @@
+// The Music app on this Mac, read and controlled through Apple Events (osascript). Moondog sees what
+// the listener plays there themselves, and the playlist it comes from. Nothing is sent until the app
+// is running, so reading never opens Music. The first read asks the listener to let Moondog (or the
+// terminal it runs in) control Music; until they allow it, reads answer "not_allowed".
+import { execFile } from "node:child_process";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+// The first read waits while macOS asks the listener; later ones answer in well under a second.
+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;
+const COLUMN_READ_MAX = 2_000;
+// Covers already drawn, by album, or by song for one without an album.
+const KNOWN_COVERS = 40;
+const COVER_SIZE = 600;
+// After a refusal, Moondog asks macOS again only this often.
+const REFUSED_RETRY_MS = 60_000;
+
+const failure = (code, message) => Object.assign(new Error(message), { code });
+
+// One JSON answer per run. argv: the action, then its argument.
+const SCRIPT = String.raw`
+function run(argv) {
+  const action = argv[0];
+  const music = Application("Music");
+  if (!music.running()) return JSON.stringify({ running: false });
+  if (action === "pause") music.pause();
+  else if (action === "resume") music.play();
+  else if (action === "next") music.nextTrack();
+  else if (action === "previous") music.backTrack();
+  else if (action === "seek") music.playerPosition = Number(argv[1]);
+  const state = music.playerState();
+  const answer = { running: true, state: state };
+  if (state === "stopped") return JSON.stringify(answer);
+  try {
+    const track = music.currentTrack.properties();
+    answer.track = { id: track.persistentID, title: track.name, artist: track.artist, album: track.album,
+      albumArtist: track.albumArtist, duration: track.duration };
+  } catch (error) {}
+  try { answer.stream = music.currentStreamTitle(); } catch (error) {}
+  try { answer.position = music.playerPosition(); } catch (error) {}
+  try { answer.shuffle = music.shuffleEnabled(); answer.repeat = music.songRepeat(); } catch (error) {}
+  try {
+    const playlist = music.currentPlaylist;
+    answer.playlist = { id: playlist.persistentID(), name: playlist.name() };
+    try { answer.playlist.special = playlist.specialKind(); } catch (error) {}
+    if (action === "tracks") {
+      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});
+      answer.playlist.index = at;
+      answer.playlist.start = start;
+      answer.playlist.tracks = [];
+      // A playlist of ordinary length comes back fastest a column at a time; a long one, song by song.
+      if (ids.length <= ${COLUMN_READ_MAX}) {
+        const titles = tracks.name(), artists = tracks.artist(), albums = tracks.album(), durations = tracks.duration();
+        for (let index = start; index < end; index++) {
+          answer.playlist.tracks.push({ id: ids[index], title: titles[index], artist: artists[index], album: albums[index], duration: durations[index] });
+        }
+      } else {
+        for (let index = start; index < end; index++) {
+          const entry = tracks[index].properties();
+          answer.playlist.tracks.push({ id: entry.persistentID, title: entry.name, artist: entry.artist, album: entry.album, duration: entry.duration });
+        }
+      }
+    }
+  } catch (error) {}
+  return JSON.stringify(answer);
+}`;
+
+// Music hands a cover over only as AppleScript data, which JavaScript for Automation cannot write.
+// argv: the file to write, then the persistent id of the playing song or of one in its playlist.
+const COVER_SCRIPT = String.raw`
+on run argv
+  if application "Music" is not running then return "none"
+  set wanted to item 2 of argv
+  tell application "Music"
+    try
+      if persistent ID of current track is wanted then
+        set chosen to current track
+      else
+        set chosen to first track of current playlist whose persistent ID is wanted
+      end if
+      set cover to raw data of artwork 1 of chosen
+    on error
+      return "none"
+    end try
+  end tell
+  set target to open for access (POSIX file (item 1 of argv)) with write permission
+  set eof target to 0
+  write cover to target
+  close access target
+  return "ok"
+end run`;
+
+function osascript(args, { timeout = READ_TIMEOUT_MS } = {}) {
+  return new Promise((resolve, reject) => {
+    execFile("/usr/bin/osascript", args, { timeout, maxBuffer: 4 * 1024 * 1024 }, (error, stdout, stderr) => {
+      if (!error) return resolve(String(stdout).trim());
+      // -1743: the listener has not let this app control Music (System Settings, Privacy & Security, Automation).
+      if (/-1743|Not authori[sz]ed/iu.test(String(stderr))) {
+        return reject(failure("music_app_not_allowed", "Moondog is not allowed to control the Music app. Turn it on in System Settings, Privacy & Security, Automation."));
+      }
+      reject(failure("music_app_failed", `The Music app did not answer: ${String(stderr || error.message).trim().slice(0, 200)}`));
+    });
+  });
+}
+
+const text = (value) => (typeof value === "string" && value.trim() ? value.trim() : null);
+const milliseconds = (seconds) => (Number.isFinite(seconds) && seconds >= 0 ? Math.round(seconds * 1000) : null);
+
+function songOf(track) {
+  return {
+    id: text(track.id),
+    title: text(track.title) ?? "",
+    artists: text(track.artist) ? [text(track.artist)] : [],
+    album: text(track.album),
+    duration_ms: milliseconds(track.duration),
+  };
+}
+
+// A radio station names its song only in the stream's title, "Artist - Title".
+function streamSongOf(answer) {
+  const stream = text(answer.stream);
+  if (!stream) return answer.track ? songOf(answer.track) : null;
+  const [artist, ...title] = stream.split(" - ");
+  return title.length ? { id: null, title: title.join(" - "), artists: [artist], album: text(answer.track?.title), duration_ms: null }
+    : { id: null, title: stream, artists: [], album: text(answer.track?.title), duration_ms: null };
+}
+
+/**
+ * What the Music app plays: { state, song, position_ms, shuffle, repeat, playlist }.
+ * state is "playing", "paused" or "stopped"; "not_running" while the app is closed,
+ * "not_allowed" until the listener lets Moondog control it, "unavailable" off macOS.
+ * playlist.tracks, with the playing song's place among them, comes only when asked for.
+ */
+function nowPlayingOf(answer) {
+  if (!answer?.running) return { state: "not_running" };
+  const state = answer.state === "playing" || answer.state === "fast forwarding" || answer.state === "rewinding" ? "playing"
+    : answer.state === "paused" ? "paused" : "stopped";
+  const song = state === "stopped" ? null : streamSongOf(answer);
+  if (!song?.title) return { state: "stopped" };
+  const playlist = answer.playlist && text(answer.playlist.name) ? {
+    id: text(answer.playlist.id),
+    name: text(answer.playlist.name),
+    // "Library" or "Music" when the song plays from the whole library rather than a playlist.
+    library: ["Library", "Music"].includes(answer.playlist.special),
+    ...(Number.isInteger(answer.playlist.count) ? { tracks_total: answer.playlist.count } : {}),
+    ...(Array.isArray(answer.playlist.tracks) ? {
+      position: answer.playlist.index >= 0 ? answer.playlist.index + 1 : null,
+      first_position: answer.playlist.start + 1,
+      tracks: answer.playlist.tracks.map(songOf),
+    } : {}),
+  } : null;
+  return {
+    state,
+    song,
+    position_ms: milliseconds(answer.position) ?? 0,
+    shuffle: answer.shuffle === true,
+    repeat: answer.repeat === "one" ? "track" : answer.repeat === "all" ? "context" : "off",
+    playlist,
+  };
+}
+
+export function createMusicAppPlayer({ platform = process.platform, run = osascript, now = Date.now } = {}) {
+  const available = platform === "darwin";
+  let refusedAt = null;
+  const covers = new Map();
+
+  async function ask(action, argument) {
+    if (!available) return null;
+    if (refusedAt !== null && now() - refusedAt < REFUSED_RETRY_MS) throw failure("music_app_not_allowed", "Moondog is not allowed to control the Music app. Turn it on in System Settings, Privacy & Security, Automation.");
+    try {
+      const answer = JSON.parse(await run(["-l", "JavaScript", "-e", SCRIPT, action, ...(argument === undefined ? [] : [String(argument)])]));
+      refusedAt = null;
+      return answer;
+    } catch (error) {
+      if (error?.code === "music_app_not_allowed") refusedAt = now();
+      throw error;
+    }
+  }
+  const read = async (action, argument) => {
+    try {
+      return available ? nowPlayingOf(await ask(action, argument)) : { state: "unavailable" };
+    } catch (error) {
+      if (error?.code === "music_app_not_allowed") return { state: "not_allowed", reason: error.message };
+      throw error;
+    }
+  };
+
+  return {
+    available,
+    nowPlaying: ({ tracks = false } = {}) => read(tracks ? "tracks" : "read"),
+    pause: () => read("pause"),
+    resume: () => read("resume"),
+    next: () => read("next"),
+    previous: () => read("previous"),
+    seek: ({ positionMs = 0 } = {}) => read("seek", Math.max(0, positionMs) / 1000),
+
+    // The cover of the playing song, or of one in its playlist, as a data URL. It is read from Music
+    // and scaled down once per album.
+    async cover(song) {
+      if (!available || !song?.id) return null;
+      const key = song.album ? `${song.artists?.[0] ?? ""}\n${song.album}` : song.id;
+      if (covers.has(key)) return covers.get(key);
+      const folder = await mkdtemp(path.join(tmpdir(), "moondog-cover-"));
+      let url = null;
+      try {
+        const original = path.join(folder, "cover");
+        const scaled = path.join(folder, "cover.jpg");
+        if (await run(["-e", COVER_SCRIPT, original, song.id]) === "ok") {
+          await new Promise((resolve, reject) => execFile("/usr/bin/sips", ["-s", "format", "jpeg", "-Z", String(COVER_SIZE), original, "--out", scaled],
+            { timeout: READ_TIMEOUT_MS }, (error) => (error ? reject(error) : resolve())));
+          url = `data:image/jpeg;base64,${(await readFile(scaled)).toString("base64")}`;
+        }
+      } catch {
+        url = null;
+      } finally {
+        await rm(folder, { recursive: true, force: true });
+      }
+      covers.set(key, url);
+      if (covers.size > KNOWN_COVERS) covers.delete(covers.keys().next().value);
+      return url;
+    },
+  };
+}

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

@@ -0,0 +1,28 @@
+// The Apple Music storefront the catalog searches: the listener's own account's when the desktop
+// app's MusicKit helper reports it, otherwise the Mac's region as the desktop app passes it, otherwise
+// the region of the process's locale, otherwise the US.
+// Catalog ids and previews differ between storefronts, so whole songs need the account's one.
+
+const code = (value) => (typeof value === "string" && /^[a-z]{2}$/iu.test(value) ? value.toUpperCase() : null);
+
+function localeRegion() {
+  try {
+    return code(new Intl.Locale(Intl.DateTimeFormat().resolvedOptions().locale).maximize().region);
+  } catch {
+    return null;
+  }
+}
+
+let account = null;
+
+/** The storefront's two-letter country code, upper case, such as "US". */
+export function appleMusicStorefront() {
+  return account ?? code(process.env.MOONDOG_SYSTEM_REGION) ?? localeRegion() ?? "US";
+}
+
+/** Records the listener's account storefront; an invalid code leaves the current one. */
+export function setAppleMusicStorefront(value) {
+  const valid = code(value);
+  if (valid) account = valid;
+  return Boolean(valid);
+}