taglib-wasm 1.6.0 → 1.7.0

package/dist/src/folder-api/group-albums.js

@@ -0,0 +1,505 @@
+import { basename } from "../utils/path.js";
+function dirname(path) {
+  const i = Math.max(path.lastIndexOf("/"), path.lastIndexOf("\\"));
+  return i === -1 ? path : path.slice(0, i);
+}
+const MARKERS = [
+  "cd",
+  "disc",
+  "disk",
+  "dvd",
+  "sacd",
+  "blu-ray",
+  "bd",
+  "vinyl",
+  "lp",
+  "record",
+  "cassette",
+  "tape",
+  "digital media"
+];
+const WORD_NUMBERS = {
+  one: 1,
+  two: 2,
+  three: 3,
+  four: 4,
+  five: 5,
+  six: 6,
+  seven: 7,
+  eight: 8,
+  nine: 9,
+  ten: 10,
+  eleven: 11,
+  twelve: 12
+};
+function romanToInt(s) {
+  const values = {
+    i: 1,
+    v: 5,
+    x: 10,
+    l: 50,
+    c: 100,
+    d: 500,
+    m: 1e3
+  };
+  let total = 0;
+  let prev = 0;
+  for (let i = s.length - 1; i >= 0; i--) {
+    const v = values[s[i]];
+    if (v === void 0) return NaN;
+    total += v < prev ? -v : v;
+    prev = v;
+  }
+  return total;
+}
+function parseNumberToken(token) {
+  if (/^\d+$/.test(token)) return parseInt(token, 10);
+  const word = WORD_NUMBERS[token.toLowerCase()];
+  if (word) return word;
+  const roman = romanToInt(token.toLowerCase());
+  return Number.isFinite(roman) ? roman : void 0;
+}
+const SEP = String.raw`[\s._#-]*`;
+const NUM = String.raw`(?:\d+|[ivxlcdm]+|one|two|three|four|five|six|seven|eight|nine|ten|eleven|twelve)`;
+function parseDiscName(name) {
+  const trimmed = name.trim();
+  if (/^(?:extras?|bonus)$/i.test(trimmed)) return void 0;
+  for (const marker of MARKERS) {
+    const left = String.raw`(?:^|[^a-z0-9])`;
+    const esc = marker.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const re = new RegExp(left + String.raw`(${esc})${SEP}(${NUM})`, "i");
+    const m = trimmed.match(re);
+    if (!m) continue;
+    const number = parseNumberToken(m[2]);
+    if (number === void 0) continue;
+    const markerStart = m.index + m[1].length - marker.length;
+    const rawPrefix = trimmed.slice(0, markerStart).trim();
+    const title = rawPrefix.replace(/[()[\]]/g, "").replace(/[\s._#-]+$/, "") || void 0;
+    const isExact = title === void 0;
+    const after = trimmed.slice(m.index + m[0].length).trim();
+    const discTitle = after.replace(/^[()[\],:;\-–—\s]+/, "").replace(/[)\]\[,:;\-–—\s]+$/, "").trim() || void 0;
+    const ofMatch = after.trim().match(/^of\s+(\d+)\b/i);
+    const total = ofMatch ? parseInt(ofMatch[1], 10) : void 0;
+    return {
+      kind: isExact ? "exact" : "embedded",
+      number,
+      total,
+      title,
+      discTitle
+    };
+  }
+  const volume = trimmed.match(
+    /^(?:volume|vol\.?|part|pt\.?)\s*(\d+)(?:\s*of\s*(\d+))?$/i
+  );
+  if (volume) {
+    return {
+      kind: "volume",
+      number: parseInt(volume[1], 10),
+      total: volume[2] ? parseInt(volume[2], 10) : void 0,
+      title: void 0,
+      discTitle: void 0
+    };
+  }
+  if (/^bonus\s+disc$/i.test(trimmed)) {
+    return {
+      kind: "bonus",
+      number: void 0,
+      total: void 0,
+      title: void 0,
+      discTitle: void 0
+    };
+  }
+  if (/^(?:\d+|v\d+|p\d+|[ab])$/i.test(trimmed)) {
+    return {
+      kind: "bare",
+      number: /^\d+$/i.test(trimmed) ? parseInt(trimmed, 10) : void 0,
+      total: void 0,
+      title: void 0,
+      discTitle: void 0
+    };
+  }
+  return void 0;
+}
+function baseConfidence(parse) {
+  switch (parse.kind) {
+    case "exact":
+      return typeof parse.number === "number" && /^\d+$/.test(String(parse.number)) ? "high" : "low";
+    case "embedded":
+      return "medium";
+    case "volume":
+      return "medium";
+    case "bonus":
+    case "bare":
+      return "low";
+  }
+}
+function corroborated(parse, siblings) {
+  if (parse.kind === "exact") return true;
+  if (siblings.length === 0) return false;
+  const siblingParses = siblings.map((s) => parseDiscName(basename(s))).filter((p) => p !== void 0);
+  const hasExactSibling = siblingParses.some((p) => p.kind === "exact");
+  const hasNumberedSibling = siblingParses.some(
+    (p) => p.number !== void 0
+  );
+  if (parse.number !== void 0 && hasNumberedSibling) return true;
+  if (parse.kind === "embedded" && hasExactSibling) return true;
+  if (parse.kind === "volume" && hasNumberedSibling) return true;
+  if (parse.kind === "bonus" || parse.kind === "bare") {
+    const numberedCount = siblingParses.filter((p) => p.number !== void 0).length;
+    if (numberedCount >= 2) return true;
+    if (parse.number !== void 0 && hasNumberedSibling) return true;
+  }
+  return false;
+}
+function flatPrefix(filename) {
+  const separated = filename.match(/^(\d{1,2})[\s._-](\d{1,2})/);
+  if (separated) return { disc: parseInt(separated[1], 10), form: "separated" };
+  const compact = filename.match(/^(\d)(\d{2})(?:\D|$)/);
+  if (compact) return { disc: parseInt(compact[1], 10), form: "compact" };
+  return void 0;
+}
+function normalizeKey(s) {
+  return s.trim().toLowerCase().replace(/\s+/g, " ");
+}
+function isGenericAlbumArtist(albumArtist) {
+  if (!albumArtist || albumArtist.trim() === "") return true;
+  const n = normalizeKey(albumArtist);
+  return n === "various artists" || n === "va";
+}
+const CONFIDENCE_RANK = {
+  low: 0,
+  medium: 1,
+  high: 2
+};
+function groupAlbums(result, options = {}) {
+  const minRank = CONFIDENCE_RANK[options.minFolderConfidence ?? "low"];
+  const useFlatPrefixes = options.flatDiscPrefixes ?? true;
+  const useFolderFallback = options.folderFallback ?? true;
+  const okItems = [];
+  const errors = [];
+  for (const item of result.items) {
+    if (item.status === "ok") {
+      okItems.push({ path: item.path, tags: item.tags, metadata: item });
+    } else {
+      errors.push({ path: item.path, error: item.error });
+    }
+  }
+  if (okItems.length === 0) {
+    return { albums: [], singles: [], unmatched: [], errors };
+  }
+  const scanRoot = options.scanRoot;
+  const tree = /* @__PURE__ */ new Map();
+  for (const item of okItems) {
+    const dir = dirname(item.path);
+    let node = tree.get(dir);
+    if (!node) {
+      node = { files: [], parent: dirname(dir) };
+      tree.set(dir, node);
+    }
+    node.files.push(item);
+  }
+  const confirmedDiscs = /* @__PURE__ */ new Map();
+  for (const [dir, node] of tree) {
+    if (node.files.length === 0) continue;
+    const parse = parseDiscName(basename(dir));
+    if (!parse) continue;
+    const siblings = [...tree.keys()].filter(
+      (d) => d !== dir && dirname(d) === dirname(dir)
+    );
+    const corroboratedBySiblings = corroborated(parse, siblings);
+    let confidence = baseConfidence(parse);
+    if (parse.kind === "bonus" || parse.kind === "bare") {
+      if (!corroboratedBySiblings) continue;
+    } else if (corroboratedBySiblings) {
+      confidence = "high";
+    }
+    if (CONFIDENCE_RANK[confidence] < minRank) continue;
+    confirmedDiscs.set(dir, { parse, confidence });
+  }
+  const flatSubdivisions = /* @__PURE__ */ new Map();
+  if (useFlatPrefixes) {
+    for (const [dir, node] of tree) {
+      if (node.files.length === 0 || confirmedDiscs.has(dir)) continue;
+      const byFile = /* @__PURE__ */ new Map();
+      const forms = /* @__PURE__ */ new Set();
+      for (const item of node.files) {
+        const prefix = flatPrefix(basename(item.path));
+        if (prefix) {
+          byFile.set(item.path, prefix.disc);
+          forms.add(prefix.form);
+        }
+      }
+      if (byFile.size < 2) continue;
+      const distinct = [...new Set(byFile.values())].sort((a, b) => a - b);
+      const allCompact = forms.size === 1 && forms.has("compact");
+      const plausible = allCompact ? distinct.every((d) => d >= 1 && d <= distinct.length) : true;
+      if (plausible) flatSubdivisions.set(dir, byFile);
+    }
+  }
+  const albums = /* @__PURE__ */ new Map();
+  const unmatched = [];
+  const evidenceFor = (item) => {
+    const dir = dirname(item.path);
+    const own = confirmedDiscs.get(dir);
+    if (own) {
+      return {
+        folderDiscNumber: own.parse.number,
+        total: own.parse.total,
+        folderDiscTitle: own.parse.discTitle,
+        confidence: own.confidence,
+        albumDir: dirname(dir)
+      };
+    }
+    let cursor = dirname(dir);
+    while (cursor !== void 0) {
+      const entry = confirmedDiscs.get(cursor);
+      if (entry) {
+        return {
+          folderDiscNumber: entry.parse.number,
+          total: entry.parse.total,
+          folderDiscTitle: entry.parse.discTitle,
+          confidence: entry.confidence,
+          albumDir: dirname(cursor)
+        };
+      }
+      const parent = dirname(cursor);
+      if (parent === cursor) break;
+      cursor = parent;
+    }
+    const flat = flatSubdivisions.get(dir)?.get(item.path);
+    if (flat !== void 0) {
+      return {
+        folderDiscNumber: flat,
+        total: void 0,
+        folderDiscTitle: void 0,
+        confidence: "medium",
+        albumDir: dir
+      };
+    }
+    return void 0;
+  };
+  const folderIdentity = (dir) => {
+    const own = confirmedDiscs.get(dir);
+    if (!own) {
+      const title2 = basename(dir);
+      return title2 ? { title: title2, titleSource: dir } : void 0;
+    }
+    if (own.parse.title !== void 0) {
+      return { title: own.parse.title, titleSource: dirname(dir) };
+    }
+    const source = dirname(dir);
+    if (source === scanRoot || source === dir) return void 0;
+    const title = basename(source);
+    return title ? { title, titleSource: source } : void 0;
+  };
+  for (const item of okItems) {
+    const dir = dirname(item.path);
+    const albumTag = item.tags.album?.[0]?.trim();
+    const albumArtistTag = item.tags.albumArtist?.[0]?.trim();
+    if (albumTag) {
+      const artistPart = isGenericAlbumArtist(albumArtistTag) ? "" : normalizeKey(albumArtistTag ?? "");
+      const key2 = `${artistPart}::${normalizeKey(albumTag)}`;
+      let acc2 = albums.get(key2);
+      if (!acc2) {
+        acc2 = {
+          key: key2,
+          album: albumTag,
+          albumArtist: isGenericAlbumArtist(albumArtistTag) ? void 0 : albumArtistTag,
+          source: "tags",
+          directory: void 0,
+          items: [],
+          evidence: /* @__PURE__ */ new Map()
+        };
+        albums.set(key2, acc2);
+      }
+      const evidence2 = evidenceFor(item);
+      acc2.evidence.set(item.path, evidence2);
+      acc2.items.push({
+        ...item.metadata,
+        albumDir: evidence2?.albumDir ?? dir,
+        discNumber: evidence2?.folderDiscNumber
+      });
+      continue;
+    }
+    if (!useFolderFallback) {
+      unmatched.push(item.metadata);
+      continue;
+    }
+    const identity = folderIdentity(dir);
+    if (!identity) {
+      unmatched.push(item.metadata);
+      continue;
+    }
+    const key = `${identity.titleSource}::${normalizeKey(identity.title)}`;
+    let acc = albums.get(key);
+    if (!acc) {
+      acc = {
+        key,
+        album: identity.title,
+        albumArtist: void 0,
+        source: "folder",
+        directory: identity.titleSource,
+        items: [],
+        evidence: /* @__PURE__ */ new Map()
+      };
+      albums.set(key, acc);
+    }
+    const evidence = evidenceFor(item);
+    acc.evidence.set(item.path, evidence);
+    acc.items.push({
+      ...item.metadata,
+      albumDir: evidence?.albumDir ?? dir,
+      discNumber: evidence?.folderDiscNumber
+    });
+  }
+  for (const [key, acc] of [...albums]) {
+    if (acc.source === "tags") continue;
+    for (const other of albums.values()) {
+      if (other === acc || other.source !== "tags") continue;
+      if (normalizeKey(other.album) !== normalizeKey(acc.album)) continue;
+      const albumDir = acc.directory;
+      const sharesChain = albumDir !== void 0 && other.items.some((o) => {
+        const od = dirname(o.path);
+        return od === albumDir || od.startsWith(albumDir + "/");
+      });
+      if (!sharesChain) continue;
+      for (const item of acc.items) {
+        other.items.push(item);
+        other.evidence.set(item.path, acc.evidence.get(item.path));
+      }
+      albums.delete(key);
+      break;
+    }
+  }
+  const groups = [];
+  for (const acc of albums.values()) {
+    const dirTagCommon = /* @__PURE__ */ new Map();
+    const resolvedByFile = /* @__PURE__ */ new Map();
+    for (const item of acc.items) {
+      const dir = dirname(item.path);
+      if (!dirTagCommon.has(dir)) {
+        const tagged = acc.items.filter((i) => dirname(i.path) === dir).map((i) => i.tags.discNumber).filter((d) => d !== void 0 && d > 0);
+        dirTagCommon.set(
+          dir,
+          tagged.length > 0 && tagged.every((d) => d === tagged[0]) ? tagged[0] : void 0
+        );
+      }
+      const evidence = acc.evidence.get(item.path);
+      const tagCommon = dirTagCommon.get(dir);
+      resolvedByFile.set(
+        item.path,
+        tagCommon ?? evidence?.folderDiscNumber
+      );
+    }
+    const discs = /* @__PURE__ */ new Map();
+    const order = [];
+    const noEvidenceItems = [];
+    for (const item of acc.items) {
+      const evidence = acc.evidence.get(item.path);
+      if (evidence === void 0) {
+        noEvidenceItems.push(item);
+        continue;
+      }
+      const resolved = resolvedByFile.get(item.path);
+      const discKey = resolved === void 0 ? `dir:${dirname(item.path)}` : String(resolved);
+      let disc = discs.get(discKey);
+      if (!disc) {
+        disc = {
+          discNumber: resolved,
+          totalDiscs: evidence.total,
+          folderDiscNumber: evidence.folderDiscNumber,
+          folderDiscTitle: evidence.folderDiscTitle,
+          tagDiscNumber: void 0,
+          confidence: evidence.confidence,
+          items: []
+        };
+        discs.set(discKey, disc);
+        order.push(discKey);
+      }
+      disc.items.push(item);
+    }
+    if (noEvidenceItems.length > 0) {
+      const numbered = [...discs.values()].filter((d) => d.folderDiscNumber !== void 0).sort((a, b) => a.folderDiscNumber - b.folderDiscNumber);
+      if (numbered.length > 0) {
+        numbered[0].items.push(...noEvidenceItems);
+      } else {
+        const key = "dir:__none__";
+        let disc = discs.get(key);
+        if (!disc) {
+          disc = {
+            discNumber: void 0,
+            totalDiscs: void 0,
+            folderDiscNumber: void 0,
+            folderDiscTitle: void 0,
+            tagDiscNumber: void 0,
+            confidence: "high",
+            items: []
+          };
+          discs.set(key, disc);
+          order.push(key);
+        }
+        disc.items.push(...noEvidenceItems);
+      }
+    }
+    for (const disc of discs.values()) {
+      const tagged = disc.items.map((i) => i.tags.discNumber).filter((d) => d !== void 0 && d > 0);
+      const common = tagged.length > 0 && tagged.every((d) => d === tagged[0]) ? tagged[0] : void 0;
+      disc.tagDiscNumber = common;
+      disc.discNumber = common ?? disc.folderDiscNumber;
+      for (const item of disc.items) item.discNumber = disc.discNumber;
+    }
+    const albumTaggedTotals = acc.items.map((i) => i.tags.totalDiscs).filter((t) => t !== void 0 && t > 0);
+    const commonTotal = albumTaggedTotals.length > 0 && albumTaggedTotals.every((t) => t === albumTaggedTotals[0]) ? albumTaggedTotals[0] : void 0;
+    const ofN = [...discs.values()].map((d) => d.totalDiscs).find(
+      (t) => t !== void 0
+    );
+    const maxSibling = [...discs.values()].map((d) => d.discNumber).filter((n) => n !== void 0).reduce((a, b) => Math.max(a, b), 0) || void 0;
+    for (const disc of discs.values()) {
+      disc.totalDiscs = commonTotal ?? ofN ?? maxSibling;
+    }
+    const sortedDiscs = [...discs.values()].sort((a, b) => {
+      const an = a.discNumber === void 0 ? -1 : a.discNumber;
+      const bn = b.discNumber === void 0 ? -1 : b.discNumber;
+      if (an !== bn) return an - bn;
+      return (a.folderDiscTitle ?? "").localeCompare(b.folderDiscTitle ?? "");
+    });
+    for (const disc of sortedDiscs) {
+      disc.items.sort((a, b) => {
+        const at = a.tags.track ?? Infinity;
+        const bt = b.tags.track ?? Infinity;
+        if (at !== bt) return at - bt;
+        return a.path.localeCompare(b.path);
+      });
+    }
+    const flags = acc.items.map((i) => i.tags.compilation).filter((c) => c !== void 0);
+    const compilation = flags.length > 0 && flags.every((f) => f === flags[0]) ? flags[0] : void 0;
+    const albumDirs = new Set(acc.items.map((i) => i.albumDir));
+    const directory = albumDirs.size === 1 ? [...albumDirs][0] : acc.directory;
+    groups.push({
+      key: acc.key,
+      albumArtist: acc.albumArtist,
+      album: acc.album,
+      source: acc.source,
+      compilation,
+      directory,
+      discs: sortedDiscs,
+      items: sortedDiscs.flatMap((d) => d.items)
+    });
+  }
+  const albumsOut = [];
+  const singles = [];
+  for (const group of groups) {
+    if (group.items.length === 1) {
+      singles.push(group.items[0]);
+    } else {
+      albumsOut.push(group);
+    }
+  }
+  albumsOut.sort(
+    (a, b) => (a.albumArtist ?? "").localeCompare(b.albumArtist ?? "") || (a.album ?? "").localeCompare(b.album ?? "")
+  );
+  return { albums: albumsOut, singles, unmatched, errors };
+}
+export {
+  groupAlbums
+};

package/dist/src/folder-api/index.d.ts

@@ -5,4 +5,6 @@
 export type { AudioDynamics, AudioFileMetadata, DuplicateGroup, FolderScanItem, FolderScanOptions, FolderScanResult, FolderUpdateItem, FolderUpdateResult, } from "./types.js";
 export { scanFolder } from "./scan-operations.js";
 export { exportFolderMetadata, findDuplicates, updateFolderTags, } from "./folder-operations.js";
+export { type AlbumDisc, type AlbumGroup, type AlbumGroupingResult, type AlbumGroupItem, type AlbumGroupKey, type DiscConfidence, groupAlbums, type GroupAlbumsOptions, } from "./group-albums.js";
+export { scanForAlbums, type ScanForAlbumsOptions } from "./scan-for-albums.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/src/folder-api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/folder-api/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,gBAAgB,GACjB,MAAM,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/folder-api/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,aAAa,EACb,iBAAiB,EACjB,cAAc,EACd,cAAc,EACd,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,YAAY,CAAC;AAEpB,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EACL,oBAAoB,EACpB,cAAc,EACd,gBAAgB,GACjB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,EACL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,WAAW,EACX,KAAK,kBAAkB,GACxB,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/src/folder-api/index.js

@@ -4,9 +4,15 @@ import {
   findDuplicates,
   updateFolderTags
 } from "./folder-operations.js";
+import {
+  groupAlbums
+} from "./group-albums.js";
+import { scanForAlbums } from "./scan-for-albums.js";
 export {
   exportFolderMetadata,
   findDuplicates,
+  groupAlbums,
   scanFolder,
+  scanForAlbums,
   updateFolderTags
 };

package/dist/src/folder-api/scan-for-albums.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Thin async wrapper: scan a folder, then group the scan into
+ * albums. Deno/Node/Bun only, like scanFolder — groupAlbums itself is pure
+ * and runtime-agnostic.
+ */
+import type { FolderScanOptions } from "./types.js";
+import { type AlbumGroupingResult, type GroupAlbumsOptions } from "./group-albums.js";
+export type ScanForAlbumsOptions = FolderScanOptions & GroupAlbumsOptions;
+/**
+ * Scan a folder and group the result into albums with disc subdivisions.
+ *
+ * Forwards every {@link FolderScanOptions} (recursive, extensions, maxFiles,
+ * onProgress, includeProperties, continueOnError, criteria, signal) to the
+ * scan; grouping options (minFolderConfidence, flatDiscPrefixes,
+ * folderFallback) apply to {@link groupAlbums}.
+ *
+ * @throws the same errors scanFolder throws (permission, missing path, abort).
+ */
+export declare function scanForAlbums(folderPath: string, options?: ScanForAlbumsOptions): Promise<AlbumGroupingResult>;
+//# sourceMappingURL=scan-for-albums.d.ts.map

package/dist/src/folder-api/scan-for-albums.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan-for-albums.d.ts","sourceRoot":"","sources":["../../../src/folder-api/scan-for-albums.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAEpD,OAAO,EACL,KAAK,mBAAmB,EAExB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAE3B,MAAM,MAAM,oBAAoB,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAE1E;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CACjC,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAc9B"}

package/dist/src/folder-api/scan-for-albums.js

@@ -0,0 +1,22 @@
+import { scanFolder } from "./scan-operations.js";
+import {
+  groupAlbums
+} from "./group-albums.js";
+async function scanForAlbums(folderPath, options = {}) {
+  const {
+    minFolderConfidence,
+    flatDiscPrefixes,
+    folderFallback,
+    ...scanOptions
+  } = options;
+  const scan = await scanFolder(folderPath, scanOptions);
+  return groupAlbums(scan, {
+    minFolderConfidence,
+    flatDiscPrefixes,
+    folderFallback,
+    scanRoot: folderPath
+  });
+}
+export {
+  scanForAlbums
+};

package/dist/src/runtime/loader-types.d.ts

@@ -32,4 +32,15 @@ export interface LoadTagLibOptions {
      */
     disableOptimizations?: boolean;
 }
+/**
+ * Describe why `wasmBinary` is not a WebAssembly module, or `null` if it is.
+ *
+ * Both loader entry points validate this before handing the buffer to
+ * Emscripten. Left to the glue, a bad buffer surfaces as an asynchronous
+ * `Aborted(CompileError: ...)` written straight to the console AFTER the
+ * returned promise settles — so a caller can neither attach it to their own
+ * failure nor suppress it. The two entry points raise different error types,
+ * hence a shared predicate rather than a shared throw.
+ */
+export declare function describeNonWasmBinary(binary: ArrayBuffer | Uint8Array): string | null;
 //# sourceMappingURL=loader-types.d.ts.map

package/dist/src/runtime/loader-types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader-types.d.ts","sourceRoot":"","sources":["../../../src/runtime/loader-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,WAAW,GAAG,UAAU,CAAC;IAEtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAEtC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC"}
+{"version":3,"file":"loader-types.d.ts","sourceRoot":"","sources":["../../../src/runtime/loader-types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,WAAW,GAAG,UAAU,CAAC;IAEtC;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,GAAG,YAAY,CAAC;IAEtC;;;;OAIG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,WAAW,GAAG,UAAU,GAC/B,MAAM,GAAG,IAAI,CASf"}

package/dist/src/runtime/loader-types.js

@@ -0,0 +1,10 @@
+function describeNonWasmBinary(binary) {
+  const bytes = binary instanceof Uint8Array ? binary : new Uint8Array(binary);
+  const MAGIC = [0, 97, 115, 109];
+  if (bytes.length >= 4 && MAGIC.every((b, i) => bytes[i] === b)) return null;
+  const found = Array.from(bytes.slice(0, 4)).map((b) => b.toString(16).padStart(2, "0")).join(" ");
+  return `wasmBinary is not a WebAssembly module: expected magic bytes 00 61 73 6d, found ${found || "(empty)"}. Size: ${bytes.length} bytes`;
+}
+export {
+  describeNonWasmBinary
+};

package/dist/src/runtime/module-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"module-loader.d.ts","sourceRoot":"","sources":["../../../src/runtime/module-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAS/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,YAAY,CAAC,CAqEvB"}
+{"version":3,"file":"module-loader.d.ts","sourceRoot":"","sources":["../../../src/runtime/module-loader.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAS/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,CAAC,EAAE,iBAAiB,GAC1B,OAAO,CAAC,YAAY,CAAC,CA8EvB"}

package/dist/src/runtime/module-loader.js

@@ -1,3 +1,4 @@
+import { describeNonWasmBinary } from "./loader-types.js";
 import {
   EnvironmentError,
   errorMessage,
@@ -18,6 +19,14 @@ async function loadTagLibModule(options) {
       { forceWasmType: "wasi" }
     );
   }
+  if (options?.wasmBinary) {
+    const problem = describeNonWasmBinary(options.wasmBinary);
+    if (problem) {
+      throw new TagLibInitializationError(problem, {
+        byteLength: options.wasmBinary.byteLength
+      });
+    }
+  }
   if (!options?.wasmBinary && !options?.wasmUrl && !options?.forceWasmType && isDenoCompiled()) {
     const wasmBinary = await tryLoadEmbeddedWasm();
     if (!wasmBinary) {

package/dist/src/runtime/unified-loader/loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../src/runtime/unified-loader/loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAK5E,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CA4C9B"}
+{"version":3,"file":"loader.d.ts","sourceRoot":"","sources":["../../../../src/runtime/unified-loader/loader.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAC;AAM5E,wBAAsB,uBAAuB,CAC3C,OAAO,GAAE,oBAAyB,GACjC,OAAO,CAAC,mBAAmB,CAAC,CAiD9B"}

package/dist/src/runtime/unified-loader/loader.js

@@ -1,5 +1,6 @@
 import { detectRuntime } from "../detector.js";
 import { ModuleLoadError } from "./types.js";
+import { describeNonWasmBinary } from "../loader-types.js";
 import { selectWasmType } from "./module-selection.js";
 import { loadModule } from "./module-loading.js";
 async function loadUnifiedTagLibModule(options = {}) {
@@ -9,6 +10,10 @@ async function loadUnifiedTagLibModule(options = {}) {
       "wasi"
     );
   }
+  if (options.wasmBinary) {
+    const problem = describeNonWasmBinary(options.wasmBinary);
+    if (problem) throw new ModuleLoadError(problem, "emscripten");
+  }
   const startTime = performance.now();
   const runtime = detectRuntime();
   if (options.debug) {

package/dist/src/runtime/wasi-adapter/file-handle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"file-handle.d.ts","sourceRoot":"","sources":["../../../../src/runtime/wasi-adapter/file-handle.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"file-handle.d.ts","sourceRoot":"","sources":["../../../../src/runtime/wasi-adapter/file-handle.ts"],"names":[],"mappings":"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"}