playlist-admin 2.6.81 → 2.6.83

package/cli/lib/audio_converter.js

@@ -1,47 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { run } from './util.js';
-import { readMetadata } from './metadata.js';
-
-// Port of lib/services/audio_converter.dart
-export async function convert({ inputPath, outputPath, format = 'mp3', ffmpegPath, meta = null, isCancelled }) {
-  let ffmpeg = ffmpegPath || 'ffmpeg';
-  if (ffmpeg.includes('\\') || ffmpeg.includes('/')) {
-    if (!fs.existsSync(ffmpeg)) ffmpeg = 'ffmpeg';
-  }
-  if (!fs.existsSync(inputPath)) return { ok: false, lufs: null };
-  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
-
-  if (inputPath.toLowerCase().endsWith(`.${format}`)) {
-    fs.copyFileSync(inputPath, outputPath);
-    return { ok: true, lufs: null };
-  }
-
-  if (!meta) meta = await readMetadata(inputPath, { ffmpegPath });
-
-  const args = [
-    '-y', '-i', inputPath,
-    '-map_metadata', '0',
-    '-id3v2_version', '3',
-    '-threads', '0',
-  ];
-  if (format === 'mp3') {
-    args.push('-af', 'loudnorm=I=-14:TP=-1:LRA=7', '-filter_threads', '0');
-  }
-  args.push('-codec:a', format === 'mp3' ? 'libmp3lame' : 'flac', '-q:a', '0', outputPath);
-
-  try {
-    const result = await run(ffmpeg, args, { timeout: 600000 });
-    if (result.code !== 0) {
-      // Remove the partial/empty output so the file isn't treated as done.
-      try { fs.unlinkSync(outputPath); } catch {}
-      return { ok: false, lufs: null };
-    }
-    const m = result.stderr.match(/Input Integrated:\s+([-\d.]+)/);
-    const lufs = m ? parseFloat(m[1]) : null;
-    return { ok: true, lufs };
-  } catch {
-    try { fs.unlinkSync(outputPath); } catch {}
-    return { ok: false, lufs: null };
-  }
-}

package/cli/lib/cleanup.js

@@ -1,61 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import readline from 'node:readline';
-import { stemOf } from './util.js';
-
-// Port of _cleanupMp3 from lib/cli_main.dart
-export async function cleanupMp3(libPath) {
-  const m4aDir = path.join(libPath, 'm4a');
-  const mp3Dir = path.join(libPath, 'mp3');
-  if (!fs.existsSync(m4aDir) || !fs.existsSync(mp3Dir)) {
-    console.log('錯誤：找不到 mp3 或 m4a 目錄');
-    return;
-  }
-
-  const m4aStems = new Set();
-  for (const f of fs.readdirSync(m4aDir)) {
-    if (f.toLowerCase().endsWith('.m4a')) {
-      m4aStems.add(stemOf(f).toLowerCase());
-    }
-  }
-  console.log(`M4A 檔案數: ${m4aStems.size}`);
-
-  const orphans = [];
-  for (const f of fs.readdirSync(mp3Dir)) {
-    if (f.toLowerCase().endsWith('.mp3')) {
-      const stem = stemOf(f).toLowerCase();
-      if (!m4aStems.has(stem)) {
-        orphans.push(path.join(mp3Dir, f));
-      }
-    }
-  }
-
-  if (orphans.length === 0) {
-    console.log('✅ 沒有發現孤兒 MP3');
-    return;
-  }
-
-  console.log(`\n⚠️  找到 ${orphans.length} 個 metadata 更名版的孤兒 MP3：\n`);
-  let totalSize = 0;
-  for (const f of orphans) {
-    const stat = fs.statSync(f);
-    totalSize += stat.size;
-    console.log(`  ${path.basename(f)}  (${(stat.size / 1024 / 1024).toFixed(1)} MB)`);
-  }
-  console.log(`\n  總計: ${(totalSize / 1024 / 1024).toFixed(1)} MB\n`);
-
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-  const answer = await new Promise((resolve) => rl.question('是否刪除？(y/N): ', resolve));
-  rl.close();
-  const input = (answer || '').trim().toLowerCase();
-  if (input === 'y') {
-    let deleted = 0;
-    for (const f of orphans) {
-      fs.unlinkSync(f);
-      deleted++;
-    }
-    console.log(`✅ 已刪除 ${deleted} 個檔案`);
-  } else {
-    console.log('跳過刪除');
-  }
-}

package/cli/lib/config.js

@@ -1,166 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-
-export function appDataDir() {
-  return path.join(
-    process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'),
-    'Playlist Administrator',
-    'data',
-  );
-}
-
-export function loadConfig() {
-  // 1. Pointer file: LOCALAPPDATA\Playlist Administrator\data\config.json
-  const pointerFile = path.join(appDataDir(), 'config.json');
-  let basePath = '';
-  if (fs.existsSync(pointerFile)) {
-    try {
-      const data = JSON.parse(fs.readFileSync(pointerFile, 'utf-8'));
-      basePath = data.base_path || '';
-    } catch {}
-  }
-
-  // 2. Main config: <base_path>\config.json
-  const mainFile = basePath ? path.join(basePath, 'config.json') : '';
-  const cfg = {};
-  if (mainFile && fs.existsSync(mainFile)) {
-    try {
-      Object.assign(cfg, JSON.parse(fs.readFileSync(mainFile, 'utf-8')));
-    } catch {}
-  } else if (fs.existsSync(pointerFile)) {
-    try {
-      Object.assign(cfg, JSON.parse(fs.readFileSync(pointerFile, 'utf-8')));
-    } catch {}
-  }
-
-  cfg.base_path = cfg.base_path || basePath;
-
-  const config = {
-    basePath: cfg.base_path || cfg.basePath || '',
-    language: cfg.language || 'zh-TW',
-    audioFormat: cfg.audio_format || cfg.audioFormat || 'mp3',
-    maxThreads: cfg.max_threads || cfg.maxThreads || 4,
-    debugMode: !!cfg.debug_mode,
-    enableMetadataEnrichment: !!(cfg.enable_metadata_enrichment ?? cfg.enableMetadataEnrichment),
-    spotubeExactMatch: cfg.spotube_exact_match !== false && cfg.spotubeExactMatch !== false,
-    spotubeConvertMatchedOnly: !!(cfg.spotube_convert_matched_only ?? cfg.spotubeConvertMatchedOnly),
-    ffmpegPath: cfg.ffmpeg_path || cfg.ffmpegPath || 'bin/ffmpeg.exe',
-    spotubeExePath: cfg.spotube_exe_path || cfg.spotubeExePath || '',
-    spotubeDownloadPath: cfg.spotube_download_path || cfg.spotubeDownloadPath || '',
-    spotubeFolderName: cfg.spotube_folder_name || cfg.spotubeFolderName || 'spotube',
-    lyricsFolderName: cfg.lyrics_folder_name || cfg.lyricsFolderName || 'Lyrics',
-    autoUpdateCheck: cfg.auto_update_check !== false && cfg.autoUpdateCheck !== false,
-    autoDownloadUpdate: !!(cfg.auto_download_update ?? cfg.autoDownloadUpdate),
-    enableRetroactiveLyrics: !!(cfg.enable_retroactive_lyrics ?? cfg.enableRetroactiveLyrics),
-    theme: cfg.theme || 'dark',
-    skippedVersion: cfg.skipped_version || cfg.skippedVersion || '',
-    setupCompleted: !!(cfg.setup_completed ?? cfg.setupCompleted),
-    groqApiKey: cfg.groq_api_key || cfg.groqApiKey || '',
-    groqConcurrency: cfg.groq_concurrency || cfg.groqConcurrency || 3,
-    podcastSubscriptions: cfg.podcast_subscriptions || cfg.podcastSubscriptions || {},
-    podcastHistory: cfg.podcast_history || cfg.podcastHistory || {},
-    urlNames: cfg.url_names || cfg.urlNames || {},
-    searchNames: cfg.search_names || cfg.searchNames || {},
-    spotubeCoords: cfg.spotube_coords || cfg.spotubeCoords || {},
-    lastUpdated: cfg.last_updated || cfg.lastUpdated || {},
-    lyricsOffsets: cfg.lyrics_offsets || cfg.lyricsOffsets || {},
-  };
-
-  if (config.basePath) derivePaths(config);
-  return config;
-}
-
-export function saveConfig(config) {
-  if (!config.basePath) return;
-  const path_ = path.join(config.basePath, 'config.json');
-  const lock = `${path_}.lock`;
-  // File lock to prevent concurrent writes (wait up to ~10s)
-  for (let i = 0; i < 100 && fs.existsSync(lock); i++) {
-    sleepSync(100);
-  }
-  if (fs.existsSync(lock)) {
-    try { fs.unlinkSync(lock); } catch {}
-  }
-  try {
-    fs.writeFileSync(lock, '');
-    // Write in the Python/Dart-compatible snake_case schema. Writing JS
-    // camelCase here would break the GUI/Flutter app (and this reader).
-    const json = {
-      base_path: config.basePath,
-      language: config.language,
-      audio_format: config.audioFormat,
-      max_threads: config.maxThreads,
-      debug_mode: config.debugMode,
-      enable_metadata_enrichment: config.enableMetadataEnrichment,
-      spotube_exact_match: config.spotubeExactMatch,
-      spotube_convert_matched_only: config.spotubeConvertMatchedOnly,
-      ffmpeg_path: config.ffmpegPath,
-      spotube_exe_path: config.spotubeExePath,
-      spotube_download_path: config.spotubeDownloadPath,
-      spotube_folder_name: config.spotubeFolderName,
-      lyrics_folder_name: config.lyricsFolderName,
-      auto_update_check: config.autoUpdateCheck,
-      auto_download_update: config.autoDownloadUpdate,
-      enable_retroactive_lyrics: config.enableRetroactiveLyrics,
-      theme: config.theme,
-      skipped_version: config.skippedVersion,
-      setup_completed: config.setupCompleted,
-      groq_api_key: config.groqApiKey,
-      groq_concurrency: config.groqConcurrency,
-      podcast_subscriptions: config.podcastSubscriptions,
-      podcast_history: config.podcastHistory,
-      url_names: config.urlNames,
-      search_names: config.searchNames,
-      spotube_coords: config.spotubeCoords,
-      last_updated: config.lastUpdated,
-      lyrics_offsets: config.lyricsOffsets,
-      spotify_urls: Object.keys(config.urlNames),
-    };
-    fs.writeFileSync(path_, JSON.stringify(json, null, 2), 'utf-8');
-  } finally {
-    try { fs.unlinkSync(lock); } catch {}
-  }
-  // Update pointer file
-  const dir = appDataDir();
-  fs.mkdirSync(dir, { recursive: true });
-  fs.writeFileSync(
-    path.join(dir, 'config.json'),
-    JSON.stringify({ base_path: config.basePath, language: config.language }),
-    'utf-8',
-  );
-}
-
-function sleepSync(ms) {
-  const sw = Date.now();
-  while (Date.now() - sw < ms) { /* spin */ }
-}
-
-function derivePaths(config) {
-  const base = path.normalize(config.basePath);
-  const music = path.join(base, 'Music');
-  config.libraryPath = fs.existsSync(music) ? music : base;
-  config.playlistsPath = path.join(base, 'Playlists');
-  config.exportPath = path.join(base, 'USB_Output');
-  config.lyricsPath = path.join(config.libraryPath, config.lyricsFolderName);
-
-  const m4a = path.join(config.libraryPath, 'm4a');
-  if (!fs.existsSync(m4a) && fs.existsSync(path.join(base, 'm4a'))) {
-    config.m4aPath = path.join(base, 'm4a');
-  } else {
-    config.m4aPath = m4a;
-  }
-  const mp3 = path.join(config.libraryPath, 'mp3');
-  if (!fs.existsSync(mp3) && fs.existsSync(path.join(base, 'mp3'))) {
-    config.mp3Path = path.join(base, 'mp3');
-  } else {
-    config.mp3Path = mp3;
-  }
-
-  if (config.spotubeDownloadPath && config.spotubeDownloadPath.trim()) {
-    config.resolvedSpotubeDownloadPath = config.spotubeDownloadPath;
-  } else {
-    const folder = config.spotubeFolderName || 'spotube';
-    config.resolvedSpotubeDownloadPath = path.join(os.homedir(), 'Downloads', folder);
-  }
-}

package/cli/lib/library_index.js

@@ -1,370 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { walkDir, stemOf } from './util.js';
-import { readMetadata } from './metadata.js';
-import { toSimplified, isLoaded, loadDict } from './zhcn.js';
-
-// Port of lib/services/library_index.dart
-const artistAliases = {
-  'claire kuo': '郭靜', 'jolin': '蔡依林', 'jolin tsai': '蔡依林',
-  'crowd lu': '盧廣仲', 'pets tseng': '曾沛慈', 'evangeline wong': '王艷薇',
-  'sabrina': '胡恂舞', 'sabrina hu': '胡恂舞', 'eric chou': '周興哲',
-  'shi shi': '孫盛希', 'boon hui lu': '文慧如', 'vicky chen': '陳忻玥',
-  'feng ze': '邱鋒澤', 'ivy': '艾薇', 'genblue': '幻藍小熊',
-  'lbi': '利比', 'erin': '連穎', 'eleanor': '李芷婷',
-  'ann bai': '白安', 'diana wang': '王詩安', 'ethan': '陳威全',
-  'chih siou': '持修', 'show luo': '羅志祥',
-};
-
-const noisePatterns = [
-  '全新單曲', '單曲', '官方完整版', '官方', '完整版',
-  '高清', '動態歌詞版', '歌詞版', '官方版', '全新',
-  'music video', 'official video', 'official music video',
-  'video', 'loop', 'lyrics',
-];
-
-export class LibraryIndex {
-  constructor() {
-    this._filenameIndex = new Map(); // tokenKey(string) -> [paths]
-    this._metadataIndex = new Map();
-    this._fileInfoMap = new Map(); // path -> {size, mtimeMs}
-    this._mp3Count = 0;
-    this._m4aCount = 0;
-    this._podcastMp3Count = 0;
-    this._podcastOtherCount = 0;
-  }
-
-  static _cacheDir() {
-    return path.join(
-      process.env.LOCALAPPDATA || '',
-      'Playlist Administrator', 'data');
-  }
-  static _fingerprintFile() {
-    return path.join(LibraryIndex._cacheDir(), 'index_fingerprint.json');
-  }
-  static _metaIndexFile() {
-    return path.join(LibraryIndex._cacheDir(), 'index_metadata.json');
-  }
-
-  static _buildFingerprint(files) {
-    const fp = new Set();
-    for (const f of files) {
-      try {
-        const st = fs.statSync(f);
-        fp.add(`${f}|${st.mtimeMs}`);
-      } catch {
-        fp.add(`${f}|0`);
-      }
-    }
-    return fp;
-  }
-
-  async build(libraryPath, log, { basePath } = {}) {
-    loadDict();
-    log('掃描音檔…');
-    const allFiles = await this._walkDir(libraryPath);
-    if (basePath && basePath !== libraryPath) {
-      const baseFiles = await this._walkDir(basePath);
-      for (const f of baseFiles) {
-        if (!allFiles.includes(f)) allFiles.push(f);
-      }
-    }
-    const mp3s = [];
-    const m4as = [];
-    for (const f of allFiles) {
-      const low = f.toLowerCase();
-      if (low.endsWith('.mp3')) mp3s.push(f);
-      else if (low.endsWith('.m4a')) m4as.push(f);
-    }
-    this._mp3Count = mp3s.length;
-    this._m4aCount = m4as.length;
-    this._fileInfoMap = new Map();
-    for (const f of allFiles) {
-      try {
-        const st = fs.statSync(f);
-        this._fileInfoMap.set(f, { size: st.size, mtimeMs: st.mtimeMs });
-      } catch {}
-    }
-    this._filenameIndex = this._buildFilenameIndex(mp3s);
-
-    let cachedFingerprint = null;
-    try {
-      const f = LibraryIndex._fingerprintFile();
-      if (fs.existsSync(f)) {
-        cachedFingerprint = new Set(JSON.parse(fs.readFileSync(f, 'utf-8')).fingerprint || []);
-      }
-    } catch {}
-
-    const currentFp = LibraryIndex._buildFingerprint(allFiles);
-    const changedStems = new Set();
-    if (cachedFingerprint) {
-      for (const entry of currentFp) {
-        if (!cachedFingerprint.has(entry)) {
-          const pipeIdx = entry.indexOf('|');
-          if (pipeIdx > 0) changedStems.add(stemOf(entry.substring(0, pipeIdx)).toLowerCase());
-        }
-      }
-      for (const entry of cachedFingerprint) {
-        if (!currentFp.has(entry)) {
-          const pipeIdx = entry.indexOf('|');
-          if (pipeIdx > 0) changedStems.add(stemOf(entry.substring(0, pipeIdx)).toLowerCase());
-        }
-      }
-    }
-
-    this._metadataIndex = new Map();
-
-    if (changedStems.size === 0 && cachedFingerprint) {
-      log(`MP3: ${this._mp3Count}, M4A: ${this._m4aCount} (無變動，載入快取索引)`);
-      const cached = this._loadMetaIndex();
-      if (cached) {
-        for (const [keyJson, paths] of Object.entries(cached)) {
-          try {
-            const tokens = JSON.parse(keyJson);
-            this._metadataIndex.set(tokens.join('\u0000'), paths);
-          } catch {}
-        }
-        log(`  metadata 索引載入完成: ${this._metadataIndex.size} 首`);
-        this._saveFingerprint(currentFp);
-        return;
-      }
-    }
-
-    log(`MP3: ${this._mp3Count}, M4A: ${this._m4aCount}`);
-    log('建立檔名索引…');
-    if (changedStems.size > 0) {
-      log(`metadata 新增/變更: ${changedStems.size} 個檔案`);
-    }
-
-    // Load cached metadata for unchanged files
-    const cached = this._loadMetaIndex();
-    const cachedPaths = new Set();
-    if (cached) {
-      for (const [keyJson, paths] of Object.entries(cached)) {
-        let skip = false;
-        for (const p of paths) {
-          if (changedStems.has(stemOf(p).toLowerCase())) { skip = true; break; }
-        }
-        if (!skip) {
-          this._metadataIndex.set(keyJson, paths);
-          for (const p of paths) cachedPaths.add(p);
-        }
-      }
-    }
-
-    const toIndex = mp3s.filter((f) => {
-      if (changedStems.size === 0) return true;
-      return changedStems.has(stemOf(f).toLowerCase());
-    });
-
-    log(`讀取 metadata 索引 (${toIndex.length}/${mp3s.length} 個檔案)…`);
-    const newEntries = await this._buildMetadataIndex(toIndex, log);
-    for (const [k, v] of newEntries) this._metadataIndex.set(k, v);
-
-    // Remove entries for deleted files
-    const onDisk = new Set(mp3s);
-    for (const [k, paths] of [...this._metadataIndex]) {
-      const kept = paths.filter((p) => onDisk.has(p));
-      if (kept.length === 0) this._metadataIndex.delete(k);
-      else this._metadataIndex.set(k, kept);
-    }
-
-    if (changedStems.size > 0) {
-      log(`索引完成 (新增 ${newEntries.length}，快取 ${this._metadataIndex.size - newEntries.length})`);
-    } else {
-      log('索引完成');
-    }
-
-    const serializable = {};
-    for (const [k, v] of this._metadataIndex) serializable[k] = v;
-    this._saveMetaIndex(serializable);
-    this._saveFingerprint(currentFp);
-  }
-
-  _saveFingerprint(fp) {
-    try {
-      const dir = LibraryIndex._cacheDir();
-      fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(LibraryIndex._fingerprintFile(), JSON.stringify({ fingerprint: [...fp] }));
-    } catch {}
-  }
-
-  _loadMetaIndex() {
-    try {
-      const f = LibraryIndex._metaIndexFile();
-      if (!fs.existsSync(f)) return null;
-      return JSON.parse(fs.readFileSync(f, 'utf-8'));
-    } catch { return null; }
-  }
-
-  _saveMetaIndex(index) {
-    try {
-      const dir = LibraryIndex._cacheDir();
-      fs.mkdirSync(dir, { recursive: true });
-      fs.writeFileSync(LibraryIndex._metaIndexFile(), JSON.stringify(index));
-    } catch {}
-  }
-
-  async _walkDir(dir) {
-    const result = [];
-    if (!fs.existsSync(dir)) return result;
-    const stack = [dir];
-    while (stack.length) {
-      const cur = stack.pop();
-      let entries;
-      try { entries = fs.readdirSync(cur, { withFileTypes: true }); } catch { continue; }
-      for (const e of entries) {
-        const full = path.join(cur, e.name);
-        if (e.isDirectory()) stack.push(full);
-        else if (e.isFile()) {
-          const low = full.toLowerCase();
-          if (!low.endsWith('.mp3') && !low.endsWith('.m4a') && !low.endsWith('.flac')) continue;
-          if (low.includes('podcast_downloads') || low.includes('podcast_rag')) {
-            if (low.endsWith('.mp3')) this._podcastMp3Count++;
-            else this._podcastOtherCount++;
-            continue;
-          }
-          result.push(full);
-        }
-      }
-    }
-    return result;
-  }
-
-  _buildFilenameIndex(files) {
-    const index = new Map();
-    for (const f of files) {
-      const tokens = this._normalize(stemOf(f));
-      if (tokens.length) {
-        const key = tokens.join('\u0000');
-        if (!index.has(key)) index.set(key, []);
-        index.get(key).push(f);
-      }
-    }
-    return index;
-  }
-
-  async _buildMetadataIndex(files, log) {
-    const index = new Map();
-    const batchSize = 20;
-    for (let i = 0; i < files.length; i += batchSize) {
-      const batch = files.slice(i, i + batchSize);
-      const metas = await Promise.all(batch.map((f) => readMetadata(f, this._config)));
-      for (let j = 0; j < batch.length; j++) {
-        const meta = metas[j];
-        if (meta.title) {
-          const tokens = this._normalize(meta.title);
-          if (tokens.length) {
-            const key = tokens.join('\u0000');
-            if (!index.has(key)) index.set(key, []);
-            index.get(key).push(batch[j]);
-          }
-        }
-      }
-      if ((i + batch.length) % 500 === 0 || i + batch.length >= files.length) {
-        log(`  metadata 索引: ${Math.min(i + batch.length, files.length)}/${files.length}`);
-      }
-    }
-    return index;
-  }
-
-  _normalize(text) {
-    let t = (text || '').toLowerCase().trim();
-    if (!t) return [];
-
-    // Remove spaces between CJK chars
-    t = t.replace(/([\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff])\s+(?=[\u4e00-\u9fff\u3040-\u309f\u30a0-\u30ff])/g, '$1');
-
-    if (isLoaded()) t = toSimplified(t);
-
-    for (const [alias, value] of Object.entries(artistAliases)) {
-      const re = new RegExp(`\\b${alias.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`, 'gi');
-      t = t.replace(re, isLoaded() ? toSimplified(value) : value.toLowerCase());
-    }
-
-    // Remove "E " prefix artifact
-    t = t.replace(/(^|(?<=[^a-z0-9]))e(?=[a-z\u4e00-\u9fff\u3040-\u30ff])/g, '');
-
-    for (const p of noisePatterns) {
-      t = t.replace(new RegExp(p, 'gi'), ' ');
-    }
-
-    t = t.replace(/\s*(feat|ft|vs)\.?\s*|\s*[&,x]\s*/gi, ' ');
-
-    t = t.replace(/[\(\[【（［][^\)\]】）］]*(?:live|remix|mv|official|lyrics?\s*video|music\s*video)[^\)\]】）］]*[\)\]】）］]/gi, ' ');
-
-    t = t.replace(/([a-z])([\u4e00-\u9fff])/g, '$1 $2');
-    t = t.replace(/([\u4e00-\u9fff])([a-z])/g, '$1 $2');
-
-    const parts = t.split(/[\s\-_()\[\]【】,./:：，。、！？（）「」""''《》〈〉\u3000]+/);
-    return parts.filter((p) => p.length > 0);
-  }
-
-  findMp3ForM4a(m4aPath, { useMtime = true, cachedMeta = null } = {}) {
-    const stem = stemOf(m4aPath);
-    const tokens = this._normalize(stem);
-    const m4aInfo = this._fileInfoMap.get(m4aPath);
-
-    const mtimeOk = (mp3Path) => {
-      if (!useMtime) return true;
-      const mp3Info = this._fileInfoMap.get(mp3Path);
-      return mp3Info && m4aInfo && mp3Info.mtimeMs >= m4aInfo.mtimeMs;
-    };
-
-    // 1. exact filename match
-    const exact = this._findInIndex(tokens, this._filenameIndex);
-    if (exact && mtimeOk(exact)) return exact;
-
-    // 2. fuzzy filename match
-    for (const [key, paths] of this._filenameIndex) {
-      const entryTokens = key.split('\u0000');
-      if (this._isSubset(tokens, entryTokens) || this._isSubset(entryTokens, tokens)) {
-        for (const f of paths) {
-          if (f.toLowerCase().endsWith('.mp3') && this._fileInfoMap.has(f) && mtimeOk(f)) return f;
-        }
-      }
-    }
-
-    // 3. metadata-based matching
-    if (cachedMeta && cachedMeta.title) {
-      const titleTokens = this._normalize(cachedMeta.title);
-      for (const [key, paths] of this._metadataIndex) {
-        const entryTokens = key.split('\u0000');
-        if (this._isSubset(titleTokens, entryTokens) || this._isSubset(entryTokens, titleTokens)) {
-          for (const f of paths) {
-            if (f.toLowerCase().endsWith('.mp3') && this._fileInfoMap.has(f)) return f;
-          }
-        }
-      }
-      if (cachedMeta.artist) {
-        const combined = this._normalize(`${cachedMeta.title} - ${cachedMeta.artist}`);
-        for (const [key, paths] of this._filenameIndex) {
-          const entryTokens = key.split('\u0000');
-          if (this._isSubset(combined, entryTokens) || this._isSubset(entryTokens, combined)) {
-            for (const f of paths) {
-              if (f.toLowerCase().endsWith('.mp3') && this._fileInfoMap.has(f)) return f;
-            }
-          }
-        }
-      }
-    }
-
-    return null;
-  }
-
-  _findInIndex(tokens, index) {
-    const key = tokens.join('\u0000');
-    const paths = index.get(key);
-    if (paths) {
-      for (const f of paths) {
-        if (f.toLowerCase().endsWith('.mp3') && this._fileInfoMap.has(f)) return f;
-      }
-    }
-    return null;
-  }
-
-  _isSubset(small, big) {
-    if (small.length > big.length) return false;
-    return small.every((s) => big.some((b) => b.includes(s)));
-  }
-}