osu-play 1.3.2 → 1.4.0

package/dist/cli.js

@@ -29,8 +29,33 @@ var __esm = (fn, res) => () => (fn && (res = fn(fn = 0)), res);
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 
 // src/core/utils/mod.ts
-import path from "node:path";
+var exports_mod = {};
+__export(exports_mod, {
+  revealFile: () => revealFile,
+  hashedFilePath: () => hashedFilePath,
+  getRealmDBPath: () => getRealmDBPath,
+  getDefaultOsuDataDir: () => getDefaultOsuDataDir,
+  getDefaultConfigPath: () => getDefaultConfigPath,
+  getDataDir: () => getDataDir,
+  getConfigDir: () => getConfigDir
+});
+import path2 from "node:path";
 import { existsSync } from "node:fs";
+import { spawn } from "node:child_process";
+function revealFile(filePath) {
+  const command = process.platform === "darwin" ? { args: ["-R", filePath], executable: "open" } : process.platform === "win32" ? { args: ["/select,", filePath], executable: "explorer.exe" } : { args: [path2.dirname(filePath)], executable: "xdg-open" };
+  return new Promise((resolve, reject) => {
+    const child = spawn(command.executable, command.args, {
+      detached: true,
+      stdio: "ignore"
+    });
+    child.once("error", reject);
+    child.once("spawn", () => {
+      child.unref();
+      resolve();
+    });
+  });
+}
 function getDataDir() {
   switch (process.platform) {
     case "linux":
@@ -41,13 +66,13 @@ function getDataDir() {
         return xdg;
       const home = process.env.HOME;
       if (home)
-        return path.join(home, ".local", "share");
+        return path2.join(home, ".local", "share");
       break;
     }
     case "darwin": {
       const home = process.env.HOME;
       if (home)
-        return path.join(home, "Library", "Application Support");
+        return path2.join(home, "Library", "Application Support");
       break;
     }
     case "win32":
@@ -65,13 +90,13 @@ function getConfigDir() {
         return xdg;
       const home = process.env.HOME;
       if (home)
-        return path.join(home, ".config");
+        return path2.join(home, ".config");
       break;
     }
     case "darwin": {
       const home = process.env.HOME;
       if (home)
-        return path.join(home, "Library", "Preferences");
+        return path2.join(home, "Library", "Preferences");
       break;
     }
     case "win32":
@@ -80,18 +105,18 @@ function getConfigDir() {
   return;
 }
 function getDefaultOsuDataDir() {
-  return path.join(getDataDir() ?? ".", "osu");
+  return path2.join(getDataDir() ?? ".", "osu");
 }
 function getDefaultConfigPath(appName = "osu-play") {
-  return path.join(getConfigDir() ?? ".", appName);
+  return path2.join(getConfigDir() ?? ".", appName);
 }
 function hashedFilePath(hash, osuDataDir = getDefaultOsuDataDir()) {
-  return path.join(osuDataDir, "files", hash.slice(0, 1), hash.slice(0, 2), hash);
+  return path2.join(osuDataDir, "files", hash.slice(0, 1), hash.slice(0, 2), hash);
 }
 function getRealmDBPath(legacyAppConfigDirOrOptions = {}, maybeOptions = {}) {
   const options = typeof legacyAppConfigDirOrOptions === "string" ? maybeOptions : legacyAppConfigDirOrOptions;
   const osuDataDir = options.osuDataDir ?? getDefaultOsuDataDir();
-  const osuDBPath = path.join(osuDataDir, "client.realm");
+  const osuDBPath = path2.join(osuDataDir, "client.realm");
   if (!existsSync(osuDBPath)) {
     console.log(`[getRealmDBPath]: ${osuDBPath} not found`);
     return null;
@@ -400,8 +425,8 @@ var init_mod2 = __esm(() => {
 });
 
 // src/core/lazer/mod.ts
-var exports_mod = {};
-__export(exports_mod, {
+var exports_mod2 = {};
+__export(exports_mod2, {
   inspectLazerSchemaEntries: () => inspectLazerSchemaEntries,
   inspectLazerSchema: () => inspectLazerSchema,
   hashedFilePath: () => hashedFilePath,
@@ -489,12 +514,615 @@ var init_mod3 = __esm(() => {
 });
 
 // src/core/cli/main.ts
-import path3 from "node:path";
+import path4 from "node:path";
 import { writeFileSync } from "node:fs";
 import { ProcessTerminal, TUI } from "@earendil-works/pi-tui";
 import yargs from "yargs/yargs";
 import { hideBin } from "yargs/helpers";
 
+// src/core/api/server.ts
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import path from "node:path";
+var API_VERSION = "1.16.1";
+var SERVER_VERSION = "1.4.0";
+var DEFAULT_HOST = "127.0.0.1";
+var DEFAULT_PORT = 4533;
+function responseBase(status) {
+  return {
+    openSubsonic: true,
+    serverVersion: SERVER_VERSION,
+    status,
+    type: "osu-play",
+    version: API_VERSION
+  };
+}
+function sendJson(response, body, statusCode = 200) {
+  const encoded = JSON.stringify(body);
+  response.writeHead(statusCode, {
+    "Cache-Control": "no-store",
+    "Content-Length": Buffer.byteLength(encoded),
+    "Content-Type": "application/json; charset=utf-8"
+  });
+  response.end(encoded);
+}
+function sendSuccess(response, data = {}) {
+  sendJson(response, {
+    "subsonic-response": {
+      ...responseBase("ok"),
+      ...data
+    }
+  });
+}
+function sendFailure(response, error, statusCode = 200) {
+  sendJson(response, {
+    "subsonic-response": {
+      ...responseBase("failed"),
+      error
+    }
+  }, statusCode);
+}
+function requiredParameter(response, params, name) {
+  const value = params.get(name)?.trim();
+  if (!value) {
+    sendFailure(response, {
+      code: 10,
+      message: `Required parameter '${name}' is missing.`
+    });
+    return null;
+  }
+  return value;
+}
+function hasValidCredentials(params) {
+  const username = params.get("u")?.trim();
+  const token = params.get("t")?.trim();
+  const salt = params.get("s")?.trim();
+  return Boolean(username && token && salt && /^[a-f0-9]{32}$/i.test(token) && params.get("f") === "json" && params.get("c")?.trim() && params.get("v")?.trim());
+}
+function parseNonNegativeInteger(value, fallback, maximum) {
+  if (value === null) {
+    return fallback;
+  }
+  if (!/^\d+$/.test(value)) {
+    return null;
+  }
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 0) {
+    return null;
+  }
+  return maximum === undefined ? parsed : Math.min(parsed, maximum);
+}
+function albumPayload(album) {
+  return {
+    artist: album.artist,
+    ...album.coverArt ? { coverArt: album.coverArt } : {},
+    id: album.id,
+    name: album.name
+  };
+}
+function songPayload(song) {
+  return {
+    album: song.album,
+    albumId: song.albumId,
+    artist: song.artist,
+    ...song.coverArt ? { coverArt: song.coverArt } : {},
+    ...song.duration ? { duration: song.duration } : {},
+    id: song.id,
+    title: song.title,
+    track: song.track
+  };
+}
+function artistIndex(catalog) {
+  const groups = new Map;
+  for (const artist of catalog.artists) {
+    const firstCharacter = artist.name.trim().charAt(0).toUpperCase();
+    const name = /^[A-Z]$/.test(firstCharacter) ? firstCharacter : "#";
+    const group = groups.get(name) ?? [];
+    group.push({
+      ...artist.coverArt ? { coverArt: artist.coverArt } : {},
+      id: artist.id,
+      name: artist.name
+    });
+    groups.set(name, group);
+  }
+  return [...groups.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([name, artist]) => ({ artist, name }));
+}
+function contentType(fileName) {
+  switch (path.extname(fileName).toLowerCase()) {
+    case ".aac":
+      return "audio/aac";
+    case ".flac":
+      return "audio/flac";
+    case ".jpeg":
+    case ".jpg":
+      return "image/jpeg";
+    case ".m4a":
+    case ".mp4":
+      return "audio/mp4";
+    case ".mp3":
+      return "audio/mpeg";
+    case ".ogg":
+    case ".oga":
+    case ".opus":
+      return "audio/ogg";
+    case ".png":
+      return "image/png";
+    case ".wav":
+      return "audio/wav";
+    case ".webm":
+      return "audio/webm";
+    case ".webp":
+      return "image/webp";
+    default:
+      return "application/octet-stream";
+  }
+}
+function parseRange(rangeHeader, size) {
+  const match = /^bytes=(\d*)-(\d*)$/.exec(rangeHeader.trim());
+  if (!match || !match[1] && !match[2]) {
+    return null;
+  }
+  if (!match[1]) {
+    const suffixLength = Number(match[2]);
+    if (!Number.isSafeInteger(suffixLength) || suffixLength <= 0) {
+      return null;
+    }
+    return {
+      end: size - 1,
+      start: Math.max(0, size - suffixLength)
+    };
+  }
+  const start = Number(match[1]);
+  const requestedEnd = match[2] ? Number(match[2]) : size - 1;
+  if (!Number.isSafeInteger(start) || !Number.isSafeInteger(requestedEnd) || start < 0 || requestedEnd < start || start >= size) {
+    return null;
+  }
+  return {
+    end: Math.min(requestedEnd, size - 1),
+    start
+  };
+}
+async function serveMedia(request, response, media, etag) {
+  let file;
+  try {
+    file = await stat(media.path);
+  } catch {
+    sendFailure(response, {
+      code: 70,
+      message: "Requested media is no longer available."
+    }, 404);
+    return;
+  }
+  if (!file.isFile()) {
+    sendFailure(response, {
+      code: 70,
+      message: "Requested media is not a file."
+    }, 404);
+    return;
+  }
+  const commonHeaders = {
+    "Accept-Ranges": "bytes",
+    "Cache-Control": "public, max-age=31536000, immutable",
+    "Content-Type": contentType(media.fileName),
+    ETag: `"${etag}"`
+  };
+  const rangeHeader = request.headers.range;
+  const range = rangeHeader ? parseRange(rangeHeader, file.size) : undefined;
+  if (rangeHeader && !range) {
+    response.writeHead(416, {
+      ...commonHeaders,
+      "Content-Range": `bytes */${file.size}`
+    });
+    response.end();
+    return;
+  }
+  const start = range?.start ?? 0;
+  const end = range?.end ?? file.size - 1;
+  const contentLength = Math.max(0, end - start + 1);
+  response.writeHead(range ? 206 : 200, {
+    ...commonHeaders,
+    "Content-Length": contentLength,
+    ...range ? { "Content-Range": `bytes ${start}-${end}/${file.size}` } : {}
+  });
+  if (request.method === "HEAD" || file.size === 0) {
+    response.end();
+    return;
+  }
+  const stream = createReadStream(media.path, { end, start });
+  const destroyStream = () => stream.destroy();
+  response.once("close", destroyStream);
+  stream.once("error", (error) => {
+    response.destroy(error);
+  });
+  stream.once("close", () => {
+    response.off("close", destroyStream);
+  });
+  stream.pipe(response);
+}
+async function routeRequest(request, response, catalogStore) {
+  const requestUrl = new URL(request.url ?? "/", `http://${DEFAULT_HOST}`);
+  const match = /^\/rest\/([A-Za-z0-9]+)\.view$/.exec(requestUrl.pathname);
+  if (!match) {
+    sendFailure(response, {
+      code: 0,
+      message: "Unsupported API endpoint."
+    }, 404);
+    return;
+  }
+  const endpoint = match[1];
+  const isMedia = endpoint === "stream" || endpoint === "getCoverArt";
+  const allowedMethod = request.method === "GET" || isMedia && request.method === "HEAD";
+  if (!allowedMethod) {
+    response.setHeader("Allow", isMedia ? "GET, HEAD" : "GET");
+    sendFailure(response, {
+      code: 0,
+      message: "Unsupported HTTP method."
+    }, 405);
+    return;
+  }
+  if (!hasValidCredentials(requestUrl.searchParams)) {
+    sendFailure(response, {
+      code: 40,
+      message: "Wrong username or password."
+    });
+    return;
+  }
+  if (endpoint === "getArtists" || endpoint === "getAlbumList2") {
+    const offset = endpoint === "getAlbumList2" ? parseNonNegativeInteger(requestUrl.searchParams.get("offset"), 0) : 0;
+    if (offset === 0) {
+      await catalogStore.refreshIfChanged();
+    }
+  }
+  const catalog = catalogStore.getCatalog();
+  switch (endpoint) {
+    case "ping":
+      sendSuccess(response);
+      return;
+    case "getArtists":
+      sendSuccess(response, {
+        artists: {
+          index: artistIndex(catalog)
+        }
+      });
+      return;
+    case "getAlbumList2": {
+      if (requestUrl.searchParams.get("type") !== "alphabeticalByName") {
+        sendFailure(response, {
+          code: 10,
+          message: "Only type=alphabeticalByName is supported."
+        });
+        return;
+      }
+      const offset = parseNonNegativeInteger(requestUrl.searchParams.get("offset"), 0);
+      const size = parseNonNegativeInteger(requestUrl.searchParams.get("size"), 10, 500);
+      if (offset === null || size === null) {
+        sendFailure(response, {
+          code: 10,
+          message: "Album offset and size must be non-negative integers."
+        });
+        return;
+      }
+      sendSuccess(response, {
+        albumList2: {
+          album: catalog.albums.slice(offset, offset + size).map(albumPayload)
+        }
+      });
+      return;
+    }
+    case "getAlbum": {
+      const id = requiredParameter(response, requestUrl.searchParams, "id");
+      if (!id)
+        return;
+      const album = catalog.albumsById.get(id);
+      if (!album) {
+        sendFailure(response, {
+          code: 70,
+          message: "Album not found."
+        });
+        return;
+      }
+      sendSuccess(response, {
+        album: {
+          ...albumPayload(album),
+          song: album.songs.map(songPayload)
+        }
+      });
+      return;
+    }
+    case "stream": {
+      const id = requiredParameter(response, requestUrl.searchParams, "id");
+      if (!id)
+        return;
+      const song = catalog.songsById.get(id);
+      if (!song) {
+        sendFailure(response, {
+          code: 70,
+          message: "Song not found."
+        }, 404);
+        return;
+      }
+      await serveMedia(request, response, {
+        fileName: song.fileName,
+        path: song.path
+      }, song.id);
+      return;
+    }
+    case "getCoverArt": {
+      const id = requiredParameter(response, requestUrl.searchParams, "id");
+      if (!id)
+        return;
+      const cover = catalog.coversById.get(id);
+      if (!cover) {
+        sendFailure(response, {
+          code: 70,
+          message: "Cover art not found."
+        }, 404);
+        return;
+      }
+      await serveMedia(request, response, cover, id);
+      return;
+    }
+    case "getPlaylists":
+      sendSuccess(response, {
+        playlists: {
+          playlist: []
+        }
+      });
+      return;
+    case "getStarred2":
+      sendSuccess(response, {
+        starred2: {
+          song: []
+        }
+      });
+      return;
+    case "scrobble": {
+      const id = requiredParameter(response, requestUrl.searchParams, "id");
+      if (!id)
+        return;
+      if (!catalog.songsById.has(id)) {
+        sendFailure(response, {
+          code: 70,
+          message: "Song not found."
+        });
+        return;
+      }
+      sendSuccess(response);
+      return;
+    }
+    case "getLyricsBySongId":
+      sendSuccess(response, {
+        lyricsList: {
+          structuredLyrics: []
+        }
+      });
+      return;
+    case "getLyrics":
+      sendSuccess(response, {
+        lyrics: {
+          value: ""
+        }
+      });
+      return;
+    case "getPlaylist":
+      sendFailure(response, {
+        code: 70,
+        message: "Playlist not found; osu-play API mode is read-only."
+      });
+      return;
+    case "createPlaylist":
+    case "updatePlaylist":
+    case "star":
+    case "unstar":
+      sendFailure(response, {
+        code: 0,
+        message: "This operation is not supported by read-only osu-play API mode."
+      });
+      return;
+    default:
+      sendFailure(response, {
+        code: 0,
+        message: `Endpoint '${endpoint}.view' is not supported.`
+      });
+  }
+}
+async function startApiServer(options) {
+  const host = options.host ?? DEFAULT_HOST;
+  const requestedPort = options.port ?? DEFAULT_PORT;
+  const server = createServer((request, response) => {
+    routeRequest(request, response, options.catalogStore).catch((error) => {
+      if (!response.headersSent) {
+        sendFailure(response, {
+          code: 0,
+          message: "Internal server error."
+        }, 500);
+      } else {
+        response.destroy(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  });
+  server.requestTimeout = 30000;
+  server.headersTimeout = 1e4;
+  await new Promise((resolve, reject) => {
+    const handleError = (error) => {
+      server.off("listening", handleListening);
+      reject(error);
+    };
+    const handleListening = () => {
+      server.off("error", handleError);
+      resolve();
+    };
+    server.once("error", handleError);
+    server.once("listening", handleListening);
+    server.listen(requestedPort, host);
+  });
+  const address = server.address();
+  if (!address || typeof address === "string") {
+    await new Promise((resolve) => server.close(() => resolve()));
+    throw new Error("Could not determine the API server address.");
+  }
+  const port = address.port;
+  return {
+    async close() {
+      if (!server.listening) {
+        return;
+      }
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error)
+            reject(error);
+          else
+            resolve();
+        });
+        server.closeIdleConnections();
+      });
+    },
+    host,
+    port,
+    url: `http://${host}:${port}`
+  };
+}
+
+// src/core/lazer/library.ts
+import { stat as stat2 } from "node:fs/promises";
+
+// src/core/api/catalog.ts
+init_mod();
+import { createHash } from "node:crypto";
+function stableId(kind, value) {
+  return createHash("sha256").update(`${kind}\x00${value}`).digest("hex");
+}
+function normalizedParts(parts) {
+  return [...new Set(parts.map((part) => part?.trim()).filter(Boolean))];
+}
+function formatMetadataText(primary, unicode, fallback) {
+  return normalizedParts([primary, unicode]).join(" / ") || fallback;
+}
+function getNamedFile(fileName, beatmapSet) {
+  if (!fileName) {
+    return null;
+  }
+  for (const file of beatmapSet.Files) {
+    if (file.Filename === fileName && file.File?.Hash) {
+      return {
+        fileName,
+        hash: file.File.Hash
+      };
+    }
+  }
+  return null;
+}
+function beatmapSetKey(beatmapSet) {
+  return String(beatmapSet.ID ?? beatmapSet.Hash ?? "");
+}
+function compareText(left, right) {
+  return left.localeCompare(right, undefined, {
+    sensitivity: "base",
+    usage: "sort"
+  });
+}
+function buildMusicCatalog(beatmapSets, osuDataDir) {
+  const albums = [];
+  const coversById = new Map;
+  const seenAudioHashes = new Set;
+  const sortedSets = [...beatmapSets].filter((beatmapSet) => !beatmapSet.DeletePending).sort((left, right) => compareText(beatmapSetKey(left), beatmapSetKey(right)));
+  for (const beatmapSet of sortedSets) {
+    const pendingByHash = new Map;
+    let albumCoverArt;
+    for (const beatmap of beatmapSet.Beatmaps) {
+      const metadata = beatmap.Metadata;
+      const audio = getNamedFile(metadata.AudioFile, beatmapSet);
+      if (!audio) {
+        continue;
+      }
+      const background = getNamedFile(metadata.BackgroundFile, beatmapSet);
+      if (background) {
+        coversById.set(background.hash, {
+          fileName: background.fileName,
+          path: hashedFilePath(background.hash, osuDataDir)
+        });
+        albumCoverArt ??= background.hash;
+      }
+      const durationMs = Math.max(0, beatmap.Length ?? 0);
+      const existing = pendingByHash.get(audio.hash);
+      if (existing) {
+        existing.durationMs = Math.max(existing.durationMs, durationMs);
+        existing.coverArt ??= background?.hash;
+        continue;
+      }
+      pendingByHash.set(audio.hash, {
+        artist: formatMetadataText(metadata.Artist, metadata.ArtistUnicode, "Unknown Artist"),
+        coverArt: background?.hash,
+        durationMs,
+        fileName: audio.fileName,
+        hash: audio.hash,
+        title: formatMetadataText(metadata.Title, metadata.TitleUnicode, "Unknown Title")
+      });
+    }
+    const retained = [...pendingByHash.values()].filter((song) => !seenAudioHashes.has(song.hash));
+    if (retained.length === 0) {
+      continue;
+    }
+    for (const song of retained) {
+      seenAudioHashes.add(song.hash);
+    }
+    const firstSong = retained[0];
+    const setKey = beatmapSetKey(beatmapSet) || firstSong.hash;
+    const albumId = stableId("album", setKey);
+    const albumName = firstSong.title;
+    const albumArtist = firstSong.artist;
+    const coverArt = albumCoverArt ?? firstSong.coverArt;
+    const songs = retained.map((song, index) => {
+      const duration = Math.round(song.durationMs / 1000);
+      return {
+        album: albumName,
+        albumId,
+        artist: song.artist,
+        ...coverArt ? { coverArt } : {},
+        ...duration > 0 ? { duration } : {},
+        fileName: song.fileName,
+        id: song.hash,
+        path: hashedFilePath(song.hash, osuDataDir),
+        title: song.title,
+        track: index + 1
+      };
+    });
+    albums.push({
+      artist: albumArtist,
+      ...coverArt ? { coverArt } : {},
+      id: albumId,
+      name: albumName,
+      songs
+    });
+  }
+  albums.sort((left, right) => compareText(left.name, right.name) || left.id.localeCompare(right.id));
+  const albumsById = new Map(albums.map((album) => [album.id, album]));
+  const songsById = new Map(albums.flatMap((album) => album.songs.map((song) => [song.id, song])));
+  const artistsByName = new Map;
+  for (const album of albums) {
+    const normalizedName = album.artist.trim().toLocaleLowerCase();
+    const existing = artistsByName.get(normalizedName);
+    if (existing) {
+      existing.coverArt ??= album.coverArt;
+      continue;
+    }
+    artistsByName.set(normalizedName, {
+      ...album.coverArt ? { coverArt: album.coverArt } : {},
+      id: stableId("artist", normalizedName),
+      name: album.artist
+    });
+  }
+  const artists = [...artistsByName.values()].sort((left, right) => compareText(left.name, right.name) || left.id.localeCompare(right.id));
+  return {
+    albums,
+    albumsById,
+    artists,
+    coversById,
+    songsById
+  };
+}
+
 // src/core/playlist/mod.ts
 init_mod();
 function uniqueParts(parts) {
@@ -539,12 +1167,123 @@ function buildPlaylist(beatmapSets, osuDataDir) {
   return playlist;
 }
 
+// src/core/lazer/library.ts
+init_mod();
+function formatRealmLoadError(error) {
+  return [
+    "Realm native bindings could not be loaded.",
+    `Current Node runtime: ${process.version}.`,
+    "To repair Realm bindings in this project, run `bun run repair:realm` (or `bun run setup` to reinstall dependencies).",
+    "If you installed dependencies on Node 22, switch to Node 20 LTS and rerun the repair command.",
+    `Original error: ${error instanceof Error ? error.message : String(error)}`
+  ].join(`
+`);
+}
+async function loadRealmDependencies() {
+  try {
+    const [{ default: Realm8 }, lazerModule] = await Promise.all([
+      import("realm"),
+      Promise.resolve().then(() => (init_mod3(), exports_mod2))
+    ]);
+    return {
+      Realm: Realm8,
+      ...lazerModule
+    };
+  } catch (error) {
+    throw new Error(formatRealmLoadError(error), { cause: error });
+  }
+}
+async function projectLazerLibrary(osuDataDir, projector) {
+  const realmDBPath = getRealmDBPath({ osuDataDir });
+  if (!realmDBPath) {
+    throw new Error("Realm DB not found");
+  }
+  const {
+    Realm: Realm8,
+    formatLazerSchemaCompatibilityError: formatLazerSchemaCompatibilityError2,
+    getBeatmapSets: getBeatmapSets2,
+    getLazerDB: getLazerDB2,
+    inspectLazerSchema: inspectLazerSchema2
+  } = await loadRealmDependencies();
+  Realm8.flags.ALLOW_CLEAR_TEST_STATE = true;
+  const realm = await getLazerDB2(realmDBPath);
+  try {
+    const schemaReport = inspectLazerSchema2(realm);
+    if (!schemaReport.compatible) {
+      throw new Error(formatLazerSchemaCompatibilityError2(schemaReport));
+    }
+    return projector(getBeatmapSets2(realm));
+  } finally {
+    realm.close();
+  }
+}
+function loadPlaylistFromLazer(osuDataDir) {
+  return projectLazerLibrary(osuDataDir, (beatmapSets) => buildPlaylist(beatmapSets, osuDataDir));
+}
+function loadMusicCatalogFromLazer(osuDataDir) {
+  return projectLazerLibrary(osuDataDir, (beatmapSets) => buildMusicCatalog(beatmapSets, osuDataDir));
+}
+async function deleteBeatmapSetFromLazer(track, osuDataDir) {
+  const { deleteBeatmapSet: deleteBeatmapSet2 } = await loadRealmDependencies();
+  await deleteBeatmapSet2(track, osuDataDir);
+}
+async function createRefreshingCatalogStore(options) {
+  let catalog = await options.loadCatalog();
+  let signature = await options.getSignature();
+  let refreshPromise = null;
+  return {
+    getCatalog() {
+      return catalog;
+    },
+    async refreshIfChanged() {
+      if (refreshPromise) {
+        return refreshPromise;
+      }
+      refreshPromise = (async () => {
+        try {
+          const nextSignature = await options.getSignature();
+          if (nextSignature === signature) {
+            return catalog;
+          }
+          const nextCatalog = await options.loadCatalog();
+          catalog = nextCatalog;
+          signature = nextSignature;
+        } catch (error) {
+          options.onRefreshError?.(error);
+        }
+        return catalog;
+      })();
+      try {
+        return await refreshPromise;
+      } finally {
+        refreshPromise = null;
+      }
+    }
+  };
+}
+async function createLazerCatalogStore(osuDataDir, onRefreshError = (error) => {
+  console.warn(`[WARN] Could not refresh the osu!lazer catalog; continuing with the last good snapshot: ${error instanceof Error ? error.message : String(error)}`);
+}) {
+  const realmDBPath = getRealmDBPath({ osuDataDir });
+  if (!realmDBPath) {
+    throw new Error("Realm DB not found");
+  }
+  return createRefreshingCatalogStore({
+    async getSignature() {
+      const file = await stat2(realmDBPath);
+      return `${file.mtimeMs}:${file.size}`;
+    },
+    loadCatalog: () => loadMusicCatalogFromLazer(osuDataDir),
+    onRefreshError
+  });
+}
+
 // src/core/player/mpv.ts
-import { spawn } from "node:child_process";
+import { spawn as spawn2 } from "node:child_process";
 import { existsSync as existsSync2, rmSync } from "node:fs";
 import net from "node:net";
 import os from "node:os";
-import path2 from "node:path";
+import path3 from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
 function getErrorCode(error) {
   if (error && typeof error === "object" && "code" in error) {
@@ -566,7 +1305,7 @@ function createSocketPath() {
   if (process.platform === "win32") {
     return `\\\\.\\pipe\\${id}`;
   }
-  return path2.join(os.tmpdir(), `${id}.sock`);
+  return path3.join(os.tmpdir(), `${id}.sock`);
 }
 function isControlText(value) {
   return [...value].some((character) => {
@@ -695,7 +1434,7 @@ class MpvPlayerBackend {
     this.cleanupSocketPath();
     this.disposing = false;
     this.stderrBuffer = "";
-    const processHandle = spawn("mpv", [
+    const processHandle = spawn2("mpv", [
       "--no-config",
       "--no-terminal",
       "--idle=yes",
@@ -974,6 +1713,13 @@ function findTrackIndexByQuery(playlist, query) {
   }
   return playlist.findIndex((track) => normalizeSearchText(track.title).includes(normalizedQuery));
 }
+function findTrackIndicesByQuery(playlist, query) {
+  const normalizedQuery = normalizeSearchText(query);
+  if (!normalizedQuery) {
+    return playlist.map((_, index) => index);
+  }
+  return playlist.flatMap((track, index) => normalizeSearchText(track.title).includes(normalizedQuery) ? [index] : []);
+}
 
 class PlaylistPlayerSession {
   backend;
@@ -983,9 +1729,13 @@ class PlaylistPlayerSession {
   loop;
   deleteTrack;
   playlist;
+  random;
   reloadPlaylist;
+  revealTrack;
   searchQuery = "";
   selectedIndex = 0;
+  shuffle;
+  shuffleOrder = [];
   operationQueue = Promise.resolve();
   unsubscribeBackend;
   constructor(playlist, backend, options = {}) {
@@ -993,7 +1743,13 @@ class PlaylistPlayerSession {
     this.playlist = playlist;
     this.deleteTrack = options.deleteTrack;
     this.loop = options.loop ?? false;
+    this.random = options.random ?? Math.random;
     this.reloadPlaylist = options.reloadPlaylist;
+    this.revealTrack = options.revealTrack;
+    this.shuffle = options.shuffle ?? false;
+    if (this.shuffle) {
+      this.resetShuffleOrder(this.selectedIndex);
+    }
     this.unsubscribeBackend = backend.subscribe((event) => {
       this.handleBackendEvent(event);
     });
@@ -1011,6 +1767,7 @@ class PlaylistPlayerSession {
       playlist: this.playlist,
       searchQuery: this.searchQuery,
       selectedIndex: this.selectedIndex,
+      shuffle: this.shuffle,
       status: backendSnapshot.status,
       timePositionSeconds: backendSnapshot.timePositionSeconds
     };
@@ -1034,24 +1791,44 @@ class PlaylistPlayerSession {
     if (this.playlist.length === 0) {
       return;
     }
+    if (this.searchQuery) {
+      this.moveSearchSelection(delta);
+      return;
+    }
     this.selectedIndex = wrapIndex(this.selectedIndex + delta, this.playlist.length);
     this.emit();
   }
   moveSelectionPage(delta, pageSize) {
+    if (this.searchQuery) {
+      this.moveSearchSelection(delta * Math.max(1, pageSize));
+      return;
+    }
     this.moveSelection(delta * Math.max(1, pageSize));
   }
+  moveSearchSelection(delta) {
+    const matches = findTrackIndicesByQuery(this.playlist, this.searchQuery);
+    if (matches.length === 0) {
+      return;
+    }
+    const currentMatchIndex = matches.indexOf(this.selectedIndex);
+    const nextMatchIndex = wrapIndex(currentMatchIndex + delta, matches.length);
+    this.selectedIndex = matches[nextMatchIndex] ?? this.selectedIndex;
+    this.emit();
+  }
   selectHome() {
     if (this.playlist.length === 0) {
       return;
     }
-    this.selectedIndex = 0;
+    const matches = findTrackIndicesByQuery(this.playlist, this.searchQuery);
+    this.selectedIndex = matches[0] ?? 0;
     this.emit();
   }
   selectEnd() {
     if (this.playlist.length === 0) {
       return;
     }
-    this.selectedIndex = this.playlist.length - 1;
+    const matches = findTrackIndicesByQuery(this.playlist, this.searchQuery);
+    this.selectedIndex = matches.at(-1) ?? this.playlist.length - 1;
     this.emit();
   }
   setSelectionIndex(index) {
@@ -1065,30 +1842,43 @@ class PlaylistPlayerSession {
     this.loop = !this.loop;
     this.emit();
   }
+  toggleShuffle() {
+    this.shuffle = !this.shuffle;
+    if (this.shuffle) {
+      this.resetShuffleOrder(this.currentIndex ?? this.selectedIndex);
+    }
+    this.emit();
+  }
   appendSearchQuery(text) {
-    if (!text) {
+    if (!text)
       return;
-    }
     this.searchQuery += text;
     this.syncSelectionToSearch();
   }
   deleteSearchCharacter() {
-    if (!this.searchQuery) {
+    if (!this.searchQuery)
       return;
-    }
     this.searchQuery = this.searchQuery.slice(0, -1);
     this.syncSelectionToSearch();
   }
+  deleteSearchWord() {
+    if (!this.searchQuery)
+      return;
+    this.searchQuery = this.searchQuery.replace(/\s*\S+\s*$/, "");
+    this.syncSelectionToSearch();
+  }
   clearSearch() {
-    if (!this.searchQuery) {
+    if (!this.searchQuery)
       return;
-    }
     this.searchQuery = "";
     this.emit();
   }
   async playSelected() {
     const selectedIndex = this.selectedIndex;
     await this.enqueueOperation(async () => {
+      if (this.shuffle) {
+        this.resetShuffleOrder(selectedIndex);
+      }
       await this.playIndex(selectedIndex);
     });
   }
@@ -1157,6 +1947,22 @@ class PlaylistPlayerSession {
       }
     });
   }
+  async revealSelectedTrack() {
+    const track = this.playlist[this.selectedIndex];
+    if (!track) {
+      return;
+    }
+    if (!this.revealTrack) {
+      this.reportError(new Error("Opening the containing folder is unavailable."));
+      return;
+    }
+    try {
+      this.clearError();
+      await this.revealTrack(track);
+    } catch (error) {
+      this.reportError(error);
+    }
+  }
   async deleteSelectedTrack() {
     const selectedIndex = this.selectedIndex;
     await this.enqueueOperation(async () => {
@@ -1189,6 +1995,9 @@ class PlaylistPlayerSession {
           const nextCurrentIndex = this.playlist.findIndex((playlistTrack) => playlistTrack.hash === currentTrack.hash);
           this.currentIndex = nextCurrentIndex === -1 ? null : nextCurrentIndex;
         }
+        if (this.shuffle) {
+          this.resetShuffleOrder(this.currentIndex ?? this.selectedIndex);
+        }
         this.emit();
       } catch (error) {
         this.reportError(error);
@@ -1234,6 +2043,19 @@ class PlaylistPlayerSession {
       return null;
     }
     const baseIndex = this.currentIndex ?? this.selectedIndex;
+    if (this.shuffle) {
+      let orderIndex = this.shuffleOrder.indexOf(baseIndex);
+      if (orderIndex === -1) {
+        this.resetShuffleOrder(baseIndex);
+        orderIndex = 0;
+      }
+      const nextOrderIndex = orderIndex + delta;
+      const shouldWrap2 = wrap || this.loop;
+      if (nextOrderIndex < 0 || nextOrderIndex >= this.shuffleOrder.length) {
+        return shouldWrap2 ? this.shuffleOrder[wrapIndex(nextOrderIndex, this.shuffleOrder.length)] ?? null : null;
+      }
+      return this.shuffleOrder[nextOrderIndex] ?? null;
+    }
     const nextIndex = baseIndex + delta;
     const shouldWrap = wrap || this.loop;
     if (nextIndex < 0) {
@@ -1244,6 +2066,17 @@ class PlaylistPlayerSession {
     }
     return nextIndex;
   }
+  resetShuffleOrder(firstIndex) {
+    const remainingIndices = this.playlist.map((_, index) => index).filter((index) => index !== firstIndex);
+    for (let index = remainingIndices.length - 1;index > 0; index -= 1) {
+      const swapIndex = Math.floor(this.random() * (index + 1));
+      [remainingIndices[index], remainingIndices[swapIndex]] = [
+        remainingIndices[swapIndex],
+        remainingIndices[index]
+      ];
+    }
+    this.shuffleOrder = this.playlist[firstIndex] ? [firstIndex, ...remainingIndices] : remainingIndices;
+  }
   handleBackendEvent(event) {
     switch (event.type) {
       case "state":
@@ -1463,6 +2296,14 @@ class PlaylistPlayerScreen {
       this.session.toggleLoop();
       return;
     }
+    if (matchesKey(data, "x")) {
+      this.session.toggleShuffle();
+      return;
+    }
+    if (matchesKey(data, "o")) {
+      this.session.revealSelectedTrack();
+      return;
+    }
     if (matchesKey(data, Key.backspace)) {
       this.session.deleteSearchCharacter();
       return;
@@ -1474,9 +2315,11 @@ class PlaylistPlayerScreen {
   }
   render(width) {
     const { playlist } = this.snapshot;
+    const visibleIndices = this.snapshot.searchQuery ? findTrackIndicesByQuery(playlist, this.snapshot.searchQuery) : playlist.map((_, index) => index);
+    const selectedVisibleIndex = Math.max(0, visibleIndices.indexOf(this.snapshot.selectedIndex));
     const viewportHeight = Math.max(this.getViewportHeight(), RESERVED_ROWS);
     const listHeight = this.getListHeight(viewportHeight);
-    const { start, end } = getVisibleTrackRange(this.snapshot.selectedIndex, playlist.length, listHeight);
+    const { start, end } = getVisibleTrackRange(selectedVisibleIndex, visibleIndices.length, listHeight);
     const position = formatSeconds(this.snapshot.timePositionSeconds);
     const duration = formatSeconds(this.snapshot.durationSeconds);
     const glyph = STATUS_GLYPH[this.snapshot.status] ?? "·";
@@ -1494,12 +2337,18 @@ class PlaylistPlayerScreen {
     } else if (this.searchMode || this.snapshot.searchQuery) {
       lines.push(truncateToWidth(style(`/ ${this.snapshot.searchQuery}${this.searchMode ? "▏" : ""}`, CYAN), width));
     } else {
-      lines.push(truncateToWidth(style(`${this.snapshot.selectedIndex + 1}/${Math.max(playlist.length, 1)} · loop ${this.snapshot.loop ? "on" : "off"} · ${this.snapshot.backendName}`, DIM), width));
+      lines.push(truncateToWidth(style(`${this.snapshot.selectedIndex + 1}/${Math.max(playlist.length, 1)} · loop ${this.snapshot.loop ? "on" : "off"} · shuffle ${this.snapshot.shuffle ? "on" : "off"} · ${this.snapshot.backendName}`, DIM), width));
     }
     if (playlist.length === 0) {
       lines.push(truncateToWidth("No tracks were found in your osu!lazer library.", width));
+    } else if (visibleIndices.length === 0) {
+      lines.push(truncateToWidth("No tracks match the current search.", width));
     } else {
-      for (let index = start;index < end; index += 1) {
+      for (let visibleIndex = start;visibleIndex < end; visibleIndex += 1) {
+        const index = visibleIndices[visibleIndex];
+        if (index === undefined) {
+          continue;
+        }
         const track = playlist[index];
         if (!track) {
           continue;
@@ -1514,7 +2363,7 @@ class PlaylistPlayerScreen {
     while (lines.length < viewportHeight - 1) {
       lines.push("");
     }
-    lines.push(truncateToWidth(style(this.searchMode ? "type to jump · backspace edit · enter keep · esc leave" : "j/k move · ⏎ play · space pause · n/p track · h/l seek · r loop · d delete · / search · q quit", DIM), width));
+    lines.push(truncateToWidth(style(this.searchMode ? "type to filter · ↑/↓ results · enter play · ctrl-w word · esc leave" : "j/k move · ⏎ play · space pause · n/p track · h/l seek · x shuffle · r loop · o reveal · d delete · / search · q quit", DIM), width));
     return lines;
   }
   armPendingGoToTop() {
@@ -1556,6 +2405,7 @@ class PlaylistPlayerScreen {
     }
     if (matchesKey(data, Key.enter)) {
       this.searchMode = false;
+      this.session.playSelected();
       return;
     }
     if (matchesKey(data, Key.escape)) {
@@ -1566,10 +2416,22 @@ class PlaylistPlayerScreen {
       this.session.deleteSearchCharacter();
       return;
     }
+    if (matchesKey(data, Key.ctrl("w"))) {
+      this.session.deleteSearchWord();
+      return;
+    }
     if (matchesKey(data, Key.ctrl("u"))) {
       this.session.clearSearch();
       return;
     }
+    if (matchesKey(data, Key.up) || matchesKey(data, Key.ctrl("p"))) {
+      this.session.moveSearchSelection(-1);
+      return;
+    }
+    if (matchesKey(data, Key.down) || matchesKey(data, Key.ctrl("n"))) {
+      this.session.moveSearchSelection(1);
+      return;
+    }
     const printable = decodePrintableText(data);
     if (!printable) {
       return;
@@ -1600,33 +2462,17 @@ class PlaylistPlayerScreen {
 
 // src/core/cli/main.ts
 init_mod();
-function formatRealmLoadError(error) {
-  return [
-    "Realm native bindings could not be loaded.",
-    `Current Node runtime: ${process.version}.`,
-    "To repair Realm bindings in this project, run `bun run repair:realm` (or `bun run setup` to reinstall dependencies).",
-    "If you installed dependencies on Node 22, switch to Node 20 LTS and rerun the repair command.",
-    `Original error: ${error instanceof Error ? error.message : String(error)}`
-  ].join(`
-`);
-}
-async function loadRealmDependencies() {
-  try {
-    const [{ default: Realm8 }, lazerModule] = await Promise.all([
-      import("realm"),
-      Promise.resolve().then(() => (init_mod3(), exports_mod))
-    ]);
-    return {
-      Realm: Realm8,
-      ...lazerModule
-    };
-  } catch (error) {
-    throw new Error(formatRealmLoadError(error), { cause: error });
-  }
-}
 function getArgs() {
-  return yargs(hideBin(process.argv)).scriptName("osu-play").usage(`Play music from your osu!lazer beatmaps in a minimal terminal player
-Usage: $0 [options]`).option("reload", {
+  return yargs(hideBin(process.argv)).scriptName("osu-play").usage(`Play or serve music from your osu!lazer beatmaps
+Usage: $0 [options]`).option("api", {
+    type: "boolean",
+    default: false,
+    describe: "Run a localhost Subsonic API for music clients such as Kopuz"
+  }).option("apiPort", {
+    type: "number",
+    default: 4533,
+    describe: "Port for --api mode (binds to 127.0.0.1)"
+  }).option("reload", {
     type: "boolean",
     default: false,
     alias: "r",
@@ -1648,42 +2494,38 @@ Usage: $0 [options]`).option("reload", {
     default: false,
     alias: "l",
     describe: "Loop the playlist when playback reaches the end"
+  }).option("shuffle", {
+    type: "boolean",
+    default: false,
+    alias: "s",
+    describe: "Play the playlist in shuffled order"
+  }).check((argv) => {
+    if (!Number.isInteger(argv.apiPort) || argv.apiPort < 1 || argv.apiPort > 65535) {
+      throw new Error("--apiPort must be an integer between 1 and 65535");
+    }
+    const conflictingMode = [
+      argv.exportPlaylist ? "exportPlaylist" : null,
+      argv.loop ? "loop" : null,
+      argv.shuffle ? "shuffle" : null
+    ].find(Boolean);
+    if (argv.api && conflictingMode) {
+      throw new Error(`--api cannot be combined with --${conflictingMode}`);
+    }
+    return true;
   }).alias("help", "h").help().parse();
 }
-async function createPlaylist(osuDataDir) {
-  const realmDBPath = getRealmDBPath({ osuDataDir });
-  if (!realmDBPath) {
-    throw new Error("Realm DB not found");
-  }
-  const {
-    Realm: Realm8,
-    formatLazerSchemaCompatibilityError: formatLazerSchemaCompatibilityError2,
-    getBeatmapSets: getBeatmapSets2,
-    getLazerDB: getLazerDB2,
-    inspectLazerSchema: inspectLazerSchema2
-  } = await loadRealmDependencies();
-  Realm8.flags.ALLOW_CLEAR_TEST_STATE = true;
-  const realm = await getLazerDB2(realmDBPath);
-  try {
-    const schemaReport = inspectLazerSchema2(realm);
-    if (!schemaReport.compatible) {
-      throw new Error(formatLazerSchemaCompatibilityError2(schemaReport));
-    }
-    return buildPlaylist(getBeatmapSets2(realm), osuDataDir);
-  } finally {
-    realm.close();
-  }
-}
 async function deleteTrackFromCollection(track, osuDataDir) {
-  const { deleteBeatmapSet: deleteBeatmapSet2 } = await loadRealmDependencies();
-  await deleteBeatmapSet2(track, osuDataDir);
+  await deleteBeatmapSetFromLazer(track, osuDataDir);
 }
-async function runTuiPlayer(playlist, osuDataDir, loop) {
+async function runTuiPlayer(playlist, osuDataDir, loop, shuffle) {
+  const { revealFile: revealFile2 } = await Promise.resolve().then(() => (init_mod(), exports_mod));
   const backend = new MpvPlayerBackend;
   const session = new PlaylistPlayerSession(playlist, backend, {
     deleteTrack: (track) => deleteTrackFromCollection(track, osuDataDir),
     loop,
-    reloadPlaylist: () => createPlaylist(osuDataDir)
+    reloadPlaylist: () => loadPlaylistFromLazer(osuDataDir),
+    revealTrack: (track) => revealFile2(track.path),
+    shuffle
   });
   const terminal = new ProcessTerminal;
   const tui = new TUI(terminal);
@@ -1714,6 +2556,30 @@ async function runTuiPlayer(playlist, osuDataDir, loop) {
     await session.dispose();
   }
 }
+async function runApiMode(osuDataDir, port) {
+  const catalogStore = await createLazerCatalogStore(osuDataDir);
+  const server = await startApiServer({
+    catalogStore,
+    port
+  });
+  console.log(`[INFO] osu-play API listening at ${server.url}`);
+  console.log("[INFO] In Kopuz, add a Custom server with this URL and any non-empty username/password.");
+  console.log("[INFO] Press Ctrl+C to stop.");
+  let resolveShutdown;
+  const shutdown = new Promise((resolve) => {
+    resolveShutdown = resolve;
+  });
+  const handleSignal = () => resolveShutdown?.();
+  process.once("SIGINT", handleSignal);
+  process.once("SIGTERM", handleSignal);
+  try {
+    await shutdown;
+  } finally {
+    process.off("SIGINT", handleSignal);
+    process.off("SIGTERM", handleSignal);
+    await server.close();
+  }
+}
 async function main() {
   const argv = await getArgs();
   if (argv.reload) {
@@ -1722,16 +2588,20 @@ async function main() {
   if (argv.configDir) {
     console.log("[INFO] `--configDir` is deprecated and ignored because osu-play no longer copies the Realm DB.");
   }
-  const playlist = await createPlaylist(argv.osuDataDir);
+  if (argv.api) {
+    await runApiMode(argv.osuDataDir, argv.apiPort);
+    return;
+  }
+  const playlist = await loadPlaylistFromLazer(argv.osuDataDir);
   if (argv.exportPlaylist) {
     const playlistContents = playlist.map((track) => track.path).join(`
 `);
     writeFileSync(argv.exportPlaylist, playlistContents);
     console.log(`[INFO] Exported ${playlist.length} tracks to ${argv.exportPlaylist}.`);
-    console.log(`[INFO] Use something like \`mpv --playlist=${path3.resolve(argv.exportPlaylist)}\` to play the playlist.`);
+    console.log(`[INFO] Use something like \`mpv --playlist=${path4.resolve(argv.exportPlaylist)}\` to play the playlist.`);
     return;
   }
-  await runTuiPlayer(playlist, argv.osuDataDir, argv.loop);
+  await runTuiPlayer(playlist, argv.osuDataDir, argv.loop, argv.shuffle);
 }
 
 // src/cli.ts
@@ -1742,4 +2612,4 @@ main().then(() => {
   process.exit(1);
 });
 
-//# debugId=434A8694113114A064756E2164756E21
+//# debugId=7C34DADA116CE55564756E2164756E21