@audiofool/moondog 0.1.0 → 0.2.0-beta.3

package/src/integrations/netease/ncm-cli-player.mjs

@@ -0,0 +1,328 @@
+// NetEase Cloud Music through its official command line tool, ncm-cli (npm @music163/ncm-cli).
+// ncm-cli keeps its own App ID, key and sign-in and plays through mpv; Moondog only runs its
+// commands and reads their JSON. It serves listeners in mainland China: elsewhere, and for many
+// original recordings, NetEase marks songs as not playable (`visible: false`), most often for
+// copyright, and no membership changes that.
+import { execFile } from "node:child_process";
+import { access, constants, stat } from "node:fs/promises";
+import path from "node:path";
+
+const COMMAND_TIMEOUT_MS = 20_000;
+// Where Homebrew and npm put ncm-cli, the node it runs on, and mpv, for a PATH that lacks them.
+const EXTRA_FOLDERS = ["/opt/homebrew/bin", "/usr/local/bin"];
+// play returns before mpv runs, so Moondog waits for the player to report the song.
+const START_WAIT_MS = 8_000;
+const START_POLL_MS = 250;
+// ncm-cli's player daemon quits about three seconds after its last client leaves, even in the
+// middle of a song, so Moondog reads its state this often while a song plays or is paused.
+// state is read locally and sends NetEase nothing.
+const KEEP_ALIVE_MS = 1_500;
+const KNOWN_SONGS = 300;
+
+const failure = (code, message) => Object.assign(new Error(message), { code });
+
+const searchPath = (environment) => [...new Set([
+  ...String(environment.PATH ?? "").split(path.delimiter).filter((folder) => path.isAbsolute(folder)),
+  ...EXTRA_FOLDERS,
+])];
+
+/** The ncm-cli executable on PATH or in Homebrew's folders, or null. */
+export async function findNcmCli({ environment = process.env } = {}) {
+  for (const folder of searchPath(environment)) {
+    const file = path.join(folder, "ncm-cli");
+    try {
+      if (!(await stat(file)).isFile()) continue;
+      await access(file, constants.X_OK);
+      return file;
+    } catch {}
+  }
+  return null;
+}
+
+// Runs one ncm-cli command and parses its JSON. ncm-cli reports most failures as
+// { success: false, message } with exit status 0. play prints no JSON when it starts a song,
+// so its answer is {}; the player's state says whether the song started.
+function cliRunner({ environment }) {
+  let found;
+  return async (args) => {
+    found ??= findNcmCli({ environment });
+    const command = await found;
+    if (!command) throw failure("netease_cli_missing", "ncm-cli is not installed. Install it with: npm install -g @music163/ncm-cli");
+    const env = { ...environment, PATH: searchPath(environment).join(path.delimiter) };
+    const stdout = await new Promise((resolve, reject) => {
+      execFile(command, args, { env, timeout: COMMAND_TIMEOUT_MS, maxBuffer: 8 * 1024 * 1024 }, (error, out) =>
+        (error && !out ? reject(failure("netease_failed", `ncm-cli ${args[0]} failed: ${String(error.message).slice(0, 200)}`)) : resolve(String(out ?? ""))));
+    });
+    const start = stdout.indexOf("{");
+    if (start < 0 && args[0] === "play") return {};
+    try {
+      return JSON.parse(start >= 0 ? stdout.slice(start) : stdout);
+    } catch {
+      throw failure("netease_failed", `ncm-cli ${args[0]} returned no JSON.`);
+    }
+  };
+}
+
+function checked(result, what) {
+  const message = String(result?.message ?? "").trim();
+  if (result?.success === false || (result?.code !== undefined && result.code !== 200)) {
+    if (/请求总量超限/u.test(message)) throw failure("netease_rate_limited", "NetEase says today's request limit is used up (请求总量超限). Stop and tell the listener.");
+    if (/登录|login|token|授权/iu.test(message)) throw failure("netease_signed_out", `NetEase is not signed in (${message}). The listener can run: ncm-cli login`);
+    throw failure("netease_failed", `NetEase could not ${what}${message ? `: ${message}` : "."}`);
+  }
+  return result;
+}
+
+const https = (url) => (typeof url === "string" && /^http:\/\/[a-z0-9-]+\.music\.126\.net\//u.test(url) ? `https://${url.slice(7)}` : url ?? null);
+
+function songOf(record) {
+  return {
+    id: String(record.id),
+    original_id: String(record.originalId),
+    title: String(record.name ?? ""),
+    artists: (Array.isArray(record.artists) ? record.artists : []).map((artist) => String(artist?.name ?? "")).filter(Boolean),
+    album: record.album?.name ? String(record.album.name) : null,
+    duration_ms: Number.isFinite(record.duration) ? Math.round(record.duration) : null,
+    image: https(record.coverImgUrl),
+    // NetEase's own word for whether the listener may play it: false most often means copyright.
+    playable: record.visible === true,
+  };
+}
+
+const fold = (value) => String(value ?? "").normalize("NFKC").toLocaleLowerCase("en-US").replace(/[\s\p{P}\p{S}]+/gu, "");
+
+// The best playable recording of a named song: by the named artist before another artist's, and
+// the exact title before a longer one such as "稻香(治愈版)".
+function pick(songs, { title, artist }) {
+  const wantTitle = fold(title);
+  const wantArtist = fold(artist);
+  const exactTitle = (song) => fold(song.title) === wantTitle;
+  const titled = songs.filter((song) => exactTitle(song) || fold(song.title).startsWith(wantTitle));
+  const byArtist = (song) => !wantArtist || song.artists.some((name) => fold(name) === wantArtist);
+  const playable = titled.filter((song) => song.playable);
+  const own = playable.filter(byArtist);
+  const found = own.find(exactTitle) ?? own[0];
+  if (found) return { song: found, other_artist: false };
+  const other = playable.find(exactTitle) ?? playable[0];
+  if (other) return { song: other, other_artist: true };
+  return { song: null, unplayable: titled.length > 0 };
+}
+
+const shortIntent = (intent) => String(intent ?? "").replace(/\s+/gu, " ").trim().slice(0, 60) || "搜索歌曲";
+
+/**
+ * The NetEase player. check() reads whether ncm-cli is installed and signed in, and ready()
+ * answers from that. Moondog keeps the queue itself and plays each song with ncm-cli's play:
+ * ncm-cli's own queue needs the play client that its start handshake sometimes loses, and its
+ * queue file breaks under concurrent commands. While a song is loaded, Moondog reads the
+ * player's state every keepAliveMs, which keeps ncm-cli's daemon running and starts the next
+ * queued song when one ends.
+ */
+export function createNeteasePlayer({
+  environment = process.env,
+  run: runCli = cliRunner({ environment }),
+  wait = (ms) => new Promise((done) => setTimeout(done, ms)),
+  keepAliveMs = KEEP_ALIVE_MS,
+} = {}) {
+  // ncm-cli's commands share its state files, and two at once can corrupt them ("队列文件损坏"),
+  // so they run one at a time.
+  let line = Promise.resolve();
+  let running = 0;
+  const run = (args) => {
+    running += 1;
+    const result = line.then(() => runCli(args)).finally(() => { running -= 1; });
+    line = result.catch(() => {});
+    return result;
+  };
+  let status = { state: "unknown", message: null };
+  let queue = [];
+  let index = -1;
+  // The last state read while a song played, to tell the end of a song from a pause.
+  let last = null;
+  const known = new Map();
+  const remember = (songs) => {
+    for (const song of songs) {
+      known.delete(song.id);
+      known.set(song.id, song);
+    }
+    while (known.size > KNOWN_SONGS) known.delete(known.keys().next().value);
+  };
+  const titleOf = (now) => (typeof now?.title === "string" && now.title.trim() ? now.title.trim() : null);
+  const isSong = (now, song) => Boolean(song && titleOf(now)?.startsWith(song.title));
+
+  async function state() {
+    const result = checked(await run(["state"]), "read what is playing");
+    return result.state ?? {};
+  }
+
+  let keepAlive = null;
+  function stayConnected() {
+    if (keepAlive) return;
+    let idle = 0;
+    keepAlive = setInterval(async () => {
+      // A command already running keeps the daemon company.
+      if (running) return;
+      const now = await state().catch(() => null);
+      if (!now) return;
+      // The song that played to its end has stopped: the next queued one starts.
+      const ended = last && now.status !== "playing" && Number.isFinite(last.duration) && last.position >= last.duration - keepAliveMs / 1000 - 1.5;
+      if (ended && index + 1 < queue.length) {
+        await playAt(index + 1).catch(() => {});
+        return;
+      }
+      if (now.status === "playing") last = { position: Number(now.position) || 0, duration: Number(now.duration) };
+      idle = now.status === "playing" || titleOf(now) ? 0 : idle + 1;
+      if (idle >= 2) letGo();
+    }, keepAliveMs);
+    keepAlive.unref?.();
+  }
+  function letGo() {
+    clearInterval(keepAlive);
+    keepAlive = null;
+  }
+
+  // Plays one queued song and waits until the player reports it from its start, so a song of
+  // the same title still finishing is not taken for it.
+  async function playAt(position) {
+    const song = queue[position];
+    checked(await run(["play", "--song", "--encrypted-id", song.id, "--original-id", song.original_id]), `play ${song.title}`);
+    index = position;
+    last = null;
+    for (let waited = 0; waited < START_WAIT_MS; waited += START_POLL_MS) {
+      const now = await state();
+      if (now.status === "playing" && isSong(now, song) && (Number(now.position) || 0) < 5) {
+        stayConnected();
+        return;
+      }
+      await wait(START_POLL_MS);
+    }
+    throw failure("netease_not_started", `NetEase did not start ${song.title}. It may not be playable here, most often for copyright.`);
+  }
+
+  const player = {
+    status: () => ({ ...status }),
+    ready: () => status.state === "ready",
+
+    async check() {
+      try {
+        const result = await run(["login", "--check"]);
+        status = result?.success === true ? { state: "ready", message: null } : { state: "signed_out", message: String(result?.message ?? "") || null };
+      } catch (error) {
+        status = { state: error.code === "netease_cli_missing" ? "missing" : "unavailable", message: error.message };
+      }
+      return player.status();
+    },
+
+    /** Up to 20 songs for one search, playable or not. */
+    async search({ query, limit = 10, intent } = {}) {
+      const keyword = String(query ?? "").trim().slice(0, 100);
+      if (!keyword) throw failure("netease_failed", "Give a song, artist or album to search for.");
+      const count = Math.min(20, Math.max(1, Math.round(Number(limit) || 10)));
+      const result = checked(await run(["search", "song", "--keyword", keyword, "--limit", String(count), "--userInput", shortIntent(intent)]), "search");
+      const songs = (Array.isArray(result.data?.records) ? result.data.records : []).map(songOf);
+      remember(songs);
+      return songs;
+    },
+
+    /**
+     * Finds and plays songs: each item is a search result's id, or a title and artist to look
+     * up. mode "play" replaces the queue and starts the first; "queue" adds after what is
+     * playing. Songs NetEase marks as not playable are never sent to the player, nor songs
+     * allow(song) refuses, such as the listener's Avoids; those are only counted. Before a lookup,
+     * allow gets the title and artist asked for, as { title, artist_credit }.
+     */
+    async play({ items = [], mode = "play", intent, allow = () => true } = {}) {
+      const found = [];
+      const unplayable = [];
+      const notFound = [];
+      let avoided = 0;
+      for (const item of items.slice(0, 20)) {
+        if (item?.id) {
+          const song = known.get(String(item.id));
+          if (!song) notFound.push({ id: String(item.id) });
+          else if (!song.playable) unplayable.push(song);
+          else if (!allow(song)) avoided += 1;
+          else found.push({ song, other_artist: false });
+          continue;
+        }
+        const wanted = { title: String(item?.title ?? ""), artist: String(item?.artist ?? "") };
+        if (!allow({ title: wanted.title, artist_credit: wanted.artist })) { avoided += 1; continue; }
+        const result = pick(await player.search({ query: `${wanted.title} ${wanted.artist}`.trim(), limit: 10, intent }), wanted);
+        if (result.song && !allow(result.song)) avoided += 1;
+        else if (result.song) found.push(result);
+        else if (result.unplayable) unplayable.push({ title: wanted.title, artists: [wanted.artist].filter(Boolean) });
+        else notFound.push(wanted);
+      }
+      const songs = found.map((entry) => entry.song);
+      let outcome = "none";
+      if (songs.length) {
+        // A paused song still has its title; with nothing loaded, a queue request plays.
+        const loaded = mode === "queue" && index >= 0 && titleOf(await state()) !== null;
+        if (loaded) {
+          queue = [...queue, ...songs];
+          outcome = "queued";
+        } else {
+          queue = songs;
+          await playAt(0);
+          outcome = "playing";
+        }
+      }
+      return {
+        mode: outcome,
+        songs: found.map(({ song, other_artist: otherArtist }) => ({ ...song, other_artist: otherArtist })),
+        unplayable,
+        not_found: notFound,
+        ...(avoided ? { skipped_avoided_count: avoided } : {}),
+      };
+    },
+
+    async pause() { checked(await run(["pause"]), "pause"); },
+    async resume() {
+      checked(await run(["resume"]), "resume");
+      stayConnected();
+    },
+    async next() {
+      if (index + 1 >= queue.length) throw failure("netease_failed", "Nothing is queued after this song.");
+      await playAt(index + 1);
+    },
+    // Back to the start of the song, or to the one before when it has only just begun.
+    async previous() {
+      const now = await state();
+      if (index > 0 && (Number(now.position) || 0) <= 3) await playAt(index - 1);
+      else checked(await run(["seek", "0"]), "go back to the start");
+    },
+    async seek({ positionMs = 0 } = {}) {
+      checked(await run(["seek", String(Math.max(0, Math.round(positionMs / 1000)))]), "move in the song");
+      last = null;
+    },
+    async stop() {
+      letGo();
+      queue = [];
+      index = -1;
+      last = null;
+      checked(await run(["stop"]), "stop");
+    },
+
+    /**
+     * What is playing: "playing", "paused" (ncm-cli reports a paused song as stopped, with its
+     * title still set) or "stopped", the song, its position, and the songs queued after it.
+     */
+    async nowPlaying() {
+      const now = await state();
+      const title = titleOf(now);
+      if (!title) return { state: "stopped", song: null, position_ms: 0, next: [] };
+      const queued = queue[index];
+      // ncm-cli names the song "title - artist"; a song played from elsewhere is shown by that name.
+      const ours = isSong(now, queued);
+      const song = ours ? queued : { id: null, original_id: null, title: title.replace(/\s+-\s+[^-]+$/u, ""),
+        artists: title.includes(" - ") ? [title.split(" - ").pop()] : [], album: null, duration_ms: null, image: null, playable: true };
+      return {
+        state: now.status === "playing" ? "playing" : "paused",
+        song: { ...song, duration_ms: Number.isFinite(now.duration) ? Math.round(now.duration * 1000) : song.duration_ms },
+        position_ms: Number.isFinite(now.position) ? Math.round(now.position * 1000) : 0,
+        next: ours ? queue.slice(index + 1) : [],
+      };
+    },
+  };
+  return player;
+}

package/src/integrations/open-music-similarity/artist-radio.mjs

@@ -221,7 +221,8 @@ export function createWikidataArtistResolver({
   if (!agent) throw new TypeError("A descriptive Wikidata user agent is required.");
   const cache = new Map();
 
-  async function request(parameters) {
+  async function request(parameters, { signal } = {}) {
+    signal?.throwIfAborted();
     const url = new URL("/w/api.php", wikidataOrigin);
     for (const [key, value] of Object.entries(parameters)) {
       url.searchParams.set(key, String(value));
@@ -232,12 +233,11 @@ export function createWikidataArtistResolver({
           accept: "application/json",
           "user-agent": agent,
         },
-        signal: AbortSignal.timeout(
-          OPEN_MUSIC_SIMILARITY_LIMITS.requestTimeoutMs,
-        ),
+        signal: AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(OPEN_MUSIC_SIMILARITY_LIMITS.requestTimeoutMs)]),
       });
       return await responseJson(response, "Wikidata", "wikidata");
     } catch (error) {
+      signal?.throwIfAborted();
       if (error instanceof OpenMusicSimilarityError) throw error;
       fail(
         "wikidata_request_failed",
@@ -248,7 +248,8 @@ export function createWikidataArtistResolver({
   }
 
   return Object.freeze({
-    async resolveArtist(artistName) {
+    async resolveArtist(artistName, { signal } = {}) {
+      signal?.throwIfAborted();
       const artist = requiredArtistName(artistName);
       const normalized = normalizeForMatch(artist);
       const language = languageForArtist(artist);
@@ -262,7 +263,7 @@ export function createWikidataArtistResolver({
           type: "item",
           limit: OPEN_MUSIC_SIMILARITY_LIMITS.wikidataSearchResultsMax,
           format: "json",
-        });
+        }, { signal });
         const search = Array.isArray(searchPayload?.search)
           ? searchPayload.search
           : [];
@@ -300,7 +301,7 @@ export function createWikidataArtistResolver({
           props: "claims|labels|descriptions",
           languages: language === "en" ? "en" : `${language}|en`,
           format: "json",
-        });
+        }, { signal });
         const entities = isPlainObject(entityPayload?.entities)
           ? entityPayload.entities
           : {};
@@ -449,7 +450,8 @@ export function createListenBrainzArtistRadioClient({
   const cache = new Map();
   let rateLimitedUntil = 0;
 
-  async function request(pathname, parameters) {
+  async function request(pathname, parameters, { signal } = {}) {
+    signal?.throwIfAborted();
     const current = now();
     if (!Number.isFinite(current)) {
       fail(
@@ -476,9 +478,7 @@ export function createListenBrainzArtistRadioClient({
           accept: "application/json",
           "user-agent": agent,
         },
-        signal: AbortSignal.timeout(
-          OPEN_MUSIC_SIMILARITY_LIMITS.requestTimeoutMs,
-        ),
+        signal: AbortSignal.any([...(signal ? [signal] : []), AbortSignal.timeout(OPEN_MUSIC_SIMILARITY_LIMITS.requestTimeoutMs)]),
       });
       const resetIn = headerInteger(response, "x-ratelimit-reset-in");
       const retryAfter = headerInteger(response, "retry-after") ?? resetIn;
@@ -491,6 +491,7 @@ export function createListenBrainzArtistRadioClient({
       }
       return await responseJson(response, "ListenBrainz", "listenbrainz");
     } catch (error) {
+      signal?.throwIfAborted();
       if (error instanceof OpenMusicSimilarityError) {
         if (error.code === "listenbrainz_rate_limited") {
           rateLimitedUntil = Math.max(rateLimitedUntil, current + 1_000);
@@ -513,7 +514,8 @@ export function createListenBrainzArtistRadioClient({
       maxRecordingsPerArtist,
       popBegin,
       popEnd,
-    }) {
+    }, { signal } = {}) {
+      signal?.throwIfAborted();
       const cleanedMbid = safeUuid(artistMbid);
       if (!cleanedMbid) {
         fail(
@@ -538,12 +540,13 @@ export function createListenBrainzArtistRadioClient({
           max_recordings_per_artist: maxRecordingsPerArtist,
           pop_begin: popBegin,
           pop_end: popEnd,
-        });
+        }, { signal });
         return parseRadioPayload(payload);
       });
     },
 
-    async recordingMetadata(recordingMbids) {
+    async recordingMetadata(recordingMbids, { signal } = {}) {
+      signal?.throwIfAborted();
       if (
         !Array.isArray(recordingMbids) ||
         recordingMbids.length < 1 ||
@@ -568,7 +571,7 @@ export function createListenBrainzArtistRadioClient({
         const payload = await request("/1/metadata/recording/", {
           recording_mbids: cleaned.join(","),
           inc: "artist release",
-        });
+        }, { signal });
         return [...parseRecordingMetadata(payload, cleaned).entries()];
       }).then((entries) => new Map(entries));
     },
@@ -664,7 +667,8 @@ export function createOpenMusicSimilarity({
   }
 
   return Object.freeze({
-    async discoverSimilarTracks({ artistName, mode = "medium", limit = 8 } = {}) {
+    async discoverSimilarTracks({ artistName, mode = "medium", limit = 8 } = {}, { signal } = {}) {
+      signal?.throwIfAborted();
       const artist = requiredArtistName(artistName);
       if (!modes.has(mode)) {
         fail(
@@ -686,7 +690,8 @@ export function createOpenMusicSimilarity({
       }
       const range = popularityRanges[mode];
       const source = sourceMetadata(now, mode, range, artist);
-      const identity = await identityResolver.resolveArtist(artist);
+      const identity = await identityResolver.resolveArtist(artist, { signal });
+      signal?.throwIfAborted();
       if (identity.state !== "resolved") {
         return {
           state:
@@ -710,7 +715,8 @@ export function createOpenMusicSimilarity({
         maxRecordingsPerArtist: 5,
         popBegin: range.begin,
         popEnd: range.end,
-      });
+      }, { signal });
+      signal?.throwIfAborted();
       const adjacentGroups = groups.filter(
         (group) => group.artist_mbid !== identity.artist_mbid,
       );
@@ -741,7 +747,9 @@ export function createOpenMusicSimilarity({
         );
         const chunkMetadata = await radioClient.recordingMetadata(
           chunk.map((recording) => recording.recording_mbid),
+          { signal },
         );
+        signal?.throwIfAborted();
         for (const [recordingMbid, details] of chunkMetadata) {
           metadata.set(recordingMbid, details);
         }

package/src/integrations/public-playlists.mjs

@@ -6,7 +6,7 @@ const numericId = /^[1-9][0-9]{0,19}$/u;
 
 function allowedUrl(value) {
   let url;
-  try { url = new URL(value); } catch { throw new Error("Paste a QQ Music or NetEase Cloud Music playlist share link."); }
+  try { url = new URL(value); } catch { throw new Error("Paste a QQ Music or NetEase Music playlist share link."); }
   if (!hosts.has(url.hostname) || !["http:", "https:"].includes(url.protocol) || url.username || url.password || url.port) {
     throw new Error("Use a playlist link from y.qq.com, music.163.com or their official share links.");
   }
@@ -98,6 +98,7 @@ export async function readPublicPlaylist({ input, subjectId, capturedAt, provide
     digest: musicHash(bytes), size: bytes.length, members: ["public-playlist.json"], fileName: name, skipped: songs.length - rows.length,
     scopeNote: `${rows.length} of ${total ?? "an unknown number of"} songs could be read; the service hides some. Only this playlist is added. It shows what you keep, not what you played, and it may not be one you made.`,
   });
+  prepared.preview.source = "public-playlist";
   prepared.preview.availableTracks = rows.length;
   prepared.preview.totalTracks = total;
   return prepared;

package/src/integrations/spotify/account-data-profile.mjs

@@ -91,6 +91,11 @@ function hashParts(...parts) {
   return hash.digest("hex");
 }
 
+/** One key per logical item, so an export and a live library read describe the same save. */
+export function spotifyProfileEvidenceKey(subjectId, kind, logicalKey) {
+  return hashParts("spotify-account-profile-evidence-key-v1", subjectId, kind, logicalKey);
+}
+
 function normalizedText(value) {
   return value.normalize("NFKC").toLocaleLowerCase("und");
 }
@@ -110,6 +115,14 @@ function optionalUri(value) {
   return match ? { type: match[1], id: match[2] } : null;
 }
 
+export function spotifyEntityRefId(type, externalId) {
+  return entityRefId(type, externalId);
+}
+
+export function spotifyResolvedTrackRef(value) {
+  return resolvedTrackRef(value);
+}
+
 function entityRefId(type, externalId) {
   if (type === "track") return uuidV5(externalId, SPOTIFY_TRACK_NAMESPACE);
   return uuidV5(
@@ -184,12 +197,7 @@ function profileBuilder({ subjectId, archiveSha256, capturedAt, profileImportId
     sourceMember,
     attributes = {},
   }) {
-    const evidenceKey = hashParts(
-      "spotify-account-profile-evidence-key-v1",
-      subjectId,
-      kind,
-      logicalKey,
-    );
+    const evidenceKey = spotifyProfileEvidenceKey(subjectId, kind, logicalKey);
     records.push({
       schema_version: 1,
       profile_evidence_id: uuidV5(