Coverage for downtify/library_catalog.py: 91%

523 statements  

« prev     ^ index     » next       coverage.py v7.17.4, created at 2026-11-21 22:18 +0000

1"""Unified library listing and safe path resolution for player + UI.""" 

2 

3from __future__ import annotations 

4 

5import os 

6import re 

7import unicodedata 

8from collections.abc import Collection, Iterable, Sequence 

9from dataclasses import dataclass 

10from pathlib import Path 

11from typing import TYPE_CHECKING, Any, Callable, Optional 

12 

13from .catalog_worker import fold_library_entries 

14from .library_cache_keys import file_content_key_from_name_and_size 

15from .library_metadata import library_entry_for_file 

16from .library_metadata_cache import LibraryMetadataCache 

17from .library_paths import ( 

18 ResolvedLibraryRoots, 

19 extra_dir_id, 

20 library_stored_path, 

21 locate_library_file, 

22) 

23from .library_paths_cache import ( 

24 get_cached_path_pairs, 

25 get_cached_track_entries, 

26 listing_lock, 

27 peek_cached_path_pairs, 

28 peek_cached_track_entries, 

29 set_listing_refresh_fn, 

30 store_cached_track_entries, 

31) 

32from .playlist_catalog import PlaylistCatalog 

33from .track_index import TrackIndex 

34 

35if TYPE_CHECKING: 

36 from .library_visibility import HiddenRules 

37 

38AUDIO_EXTENSIONS = frozenset({ 

39 '.mp3', 

40 '.m4a', 

41 '.flac', 

42 '.ogg', 

43 '.wav', 

44 '.aac', 

45 '.opus', 

46}) 

47 

48 

49@dataclass(frozen=True) 

50class LibraryContext: 

51 download_dir: Path 

52 slskd_dir: Optional[Path] = None 

53 extra_dirs: tuple[Path, ...] = () 

54 track_index: Optional[TrackIndex] = None 

55 metadata_cache: Optional[LibraryMetadataCache] = None 

56 playlist_catalog: Optional[PlaylistCatalog] = None 

57 primary_extra_id: str = '' 

58 hidden_files: frozenset[str] = frozenset() 

59 hidden_resolved: frozenset[str] = frozenset() 

60 

61 

62def library_context_from_state( 

63 download_dir: Path, 

64 settings: dict[str, Any], 

65 track_index: Optional[TrackIndex] = None, 

66 metadata_cache: Optional[LibraryMetadataCache] = None, 

67 playlist_catalog: Optional[PlaylistCatalog] = None, 

68 hidden_files: frozenset[str] = frozenset(), 

69 hidden_resolved: frozenset[str] = frozenset(), 

70) -> LibraryContext: 

71 slskd_raw = settings.get('slskd') 

72 slskd_dir: Optional[Path] = None 

73 if isinstance(slskd_raw, dict): 

74 source = str(slskd_raw.get('source_dir') or '').strip() 

75 if source: 

76 slskd_dir = Path(source) 

77 from .external_library import extra_dirs_from_settings # noqa: PLC0415 # import cycle 

78 

79 extra_dirs = extra_dirs_from_settings( 

80 settings, Path(download_dir), slskd_dir 

81 ) 

82 external = settings.get('external_library') 

83 primary = ( 

84 str(external.get('primary_folder') or '') 

85 if isinstance(external, dict) 

86 else '' 

87 ) 

88 primary_id = next( 

89 (extra_dir_id(root) for root in extra_dirs if str(root) == primary), '' 

90 ) 

91 return LibraryContext( 

92 hidden_files=hidden_files, 

93 hidden_resolved=hidden_resolved, 

94 primary_extra_id=primary_id, 

95 download_dir=Path(download_dir), 

96 slskd_dir=slskd_dir, 

97 extra_dirs=extra_dirs, 

98 track_index=track_index, 

99 metadata_cache=metadata_cache, 

100 playlist_catalog=playlist_catalog, 

101 ) 

102 

103 

104#: Marker in the name of the working copy a library upgrade writes 

105#: before swapping it in (see ``downtify.library_upgrade``). It lives in 

106#: the library folder for the few seconds a rewrite takes, and must 

107#: never show up as a track of its own. 

108UPGRADE_STAGING_MARKER = '.downtify-upgrade' 

109 

110#: Cap on ``GET /tracks?limit=`` and ``POST /api/library/lookup``. 

111TRACK_QUERY_LIMIT_MAX = 200 

112LOOKUP_SONG_MAX = 200 

113 

114# Same rules as ``frontend/src/lib/library.js`` ``songKey``. 

115_SAME_SONG_TAG = re.compile( 

116 r'[([](?:(?:feat|ft|with)\b|[^)\]]*remaster)[^)\]]*[)\]]', 

117 re.IGNORECASE, 

118) 

119_FEAT_TAIL = re.compile(r'\s(feat|ft)\.?\s.*$') 

120_REMASTER_TAIL = re.compile(r'\s-\s[^-]*remaster[^-]*$') 

121_ARTIST_SPLIT = re.compile(r',|;| & ') 

122 

123#: Top-level folder podcast episodes live under (see 

124#: ``downtify.podcasts``). Excluded from the library scan below, so 

125#: episodes never show up as tracks, albums or artists, and never reach 

126#: an Upgrade library run — they have no Spotify track id and no lyrics 

127#: to look for, and neither module needs to know podcasts exist. 

128PODCASTS_DIRNAME = 'Podcasts' 

129 

130 

131#: Sidecar artwork Downtify writes (playlist covers) or that already 

132#: sits beside downloaded tracks. 

133IMAGE_EXTENSIONS = frozenset({'.jpg', '.jpeg', '.png', '.webp'}) 

134 

135 

136def _is_audio(path: Path) -> bool: 

137 if UPGRADE_STAGING_MARKER in path.name: 

138 return False 

139 return path.is_file() and path.suffix.lower() in AUDIO_EXTENSIONS 

140 

141 

142def _is_image(path: Path) -> bool: 

143 return path.is_file() and path.suffix.lower() in IMAGE_EXTENSIONS 

144 

145 

146def _resolve_within_library( 

147 stored: str, 

148 ctx: LibraryContext, 

149 accept: Callable[[Path], bool], 

150) -> Optional[Path]: 

151 """A library-relative path, confined to the library's own folders.""" 

152 

153 text = str(stored or '').strip().replace('\\', '/') 

154 if text in getattr(ctx, 'hidden_files', frozenset()): 

155 return None 

156 if not text or text.startswith('/'): 

157 return None 

158 if '\0' in text: 

159 return None 

160 # Files in the library trash must not be served as normal media. 

161 if '.downtify-trash' in text.split('/'): 

162 return None 

163 

164 candidate = locate_library_file( 

165 text, ctx.download_dir, ctx.slskd_dir, ctx.extra_dirs 

166 ) 

167 if candidate is None or not accept(candidate): 

168 return None 

169 if '.downtify-trash' in candidate.parts or str( 

170 candidate.resolve() 

171 ) in getattr(ctx, 'hidden_resolved', frozenset()): 

172 return None 

173 

174 allowed_roots = [ctx.download_dir.resolve()] 

175 if ctx.slskd_dir is not None: 

176 slskd_resolved = ctx.slskd_dir.resolve() 

177 if slskd_resolved not in allowed_roots: 

178 allowed_roots.append(slskd_resolved) 

179 for extra in ctx.extra_dirs: 

180 try: 

181 extra_resolved = extra.resolve() 

182 except OSError: 

183 extra_resolved = extra 

184 if extra_resolved not in allowed_roots: 

185 allowed_roots.append(extra_resolved) 

186 

187 for root in allowed_roots: 

188 try: 

189 candidate.relative_to(root) 

190 return candidate 

191 except ValueError: 

192 continue 

193 return None 

194 

195 

196def resolve_library_file(stored: str, ctx: LibraryContext) -> Optional[Path]: 

197 """Resolve a library-relative path if it points to an allowed audio file.""" 

198 

199 return _resolve_within_library(stored, ctx, _is_audio) 

200 

201 

202def resolve_library_image(stored: str, ctx: LibraryContext) -> Optional[Path]: 

203 """Resolve a library-relative path to a cover image sitting in the library. 

204 

205 Same path-traversal confinement as :func:`resolve_library_file`, for 

206 the sidecar artwork saved next to a playlist's M3U (see 

207 ``downtify.downloader.save_playlist_cover``). 

208 """ 

209 

210 return _resolve_within_library(stored, ctx, _is_image) 

211 

212 

213def _under_podcasts(file_path: Path, download_dir: Path) -> bool: 

214 try: 

215 file_path.relative_to(download_dir / PODCASTS_DIRNAME) 

216 except ValueError: 

217 return False 

218 return True 

219 

220 

221def _register_path( 

222 file_path: Path, 

223 ctx: LibraryContext, 

224 by_resolved: dict[str, str], 

225 roots: ResolvedLibraryRoots, 

226) -> None: 

227 if UPGRADE_STAGING_MARKER in file_path.name: 

228 return 

229 if '.downtify-trash' in file_path.parts: 

230 return 

231 if file_path.suffix.lower() not in AUDIO_EXTENSIONS: 

232 return 

233 try: 

234 resolved = file_path.resolve() 

235 except OSError: 

236 return 

237 if _under_podcasts(resolved, ctx.download_dir): 

238 return 

239 resolved_key = str(resolved) 

240 if resolved_key in getattr( 

241 ctx, 'hidden_resolved', frozenset() 

242 ) or roots.stored_for(resolved) in getattr( 

243 ctx, 'hidden_files', frozenset() 

244 ): 

245 return 

246 if resolved_key in by_resolved: 

247 return 

248 by_resolved[resolved_key] = roots.stored_for(resolved) 

249 

250 

251def _walk_audio_files(root: Path, *, prune_podcasts: bool = False): 

252 """Yield audio files under *root* without visiting every other file.""" 

253 

254 try: 

255 if not root.is_dir(): 

256 return 

257 except OSError: 

258 return 

259 for dirpath, dirnames, filenames in os.walk(root, followlinks=False): 

260 dirnames[:] = [name for name in dirnames if name != '.downtify-trash'] 

261 current = Path(dirpath) 

262 if prune_podcasts and current == root: 

263 dirnames[:] = [ 

264 name for name in dirnames if name != PODCASTS_DIRNAME 

265 ] 

266 for name in filenames: 

267 if UPGRADE_STAGING_MARKER in name: 

268 continue 

269 suffix = Path(name).suffix.lower() 

270 if suffix not in AUDIO_EXTENSIONS: 

271 continue 

272 yield current / name 

273 

274 

275def _scan_library_path_pairs(ctx: LibraryContext) -> list[tuple[str, str]]: 

276 """Scan disk for playable ``(stored, resolved)`` pairs (uncached).""" 

277 

278 by_resolved: dict[str, str] = {} 

279 roots = ResolvedLibraryRoots.from_dirs( 

280 ctx.download_dir, ctx.slskd_dir, ctx.extra_dirs 

281 ) 

282 

283 for path in _walk_audio_files(ctx.download_dir, prune_podcasts=True): 

284 _register_path(path, ctx, by_resolved, roots) 

285 

286 if ctx.slskd_dir is not None and roots.slskd != roots.download: 

287 for path in _walk_audio_files(ctx.slskd_dir): 

288 _register_path(path, ctx, by_resolved, roots) 

289 

290 for extra_resolved, _folder_id in roots.extras: 

291 if extra_resolved == roots.download: 

292 continue 

293 if roots.slskd is not None and extra_resolved == roots.slskd: 

294 continue 

295 for path in _walk_audio_files(extra_resolved): 

296 _register_path(path, ctx, by_resolved, roots) 

297 

298 if ctx.track_index is not None: 

299 for stored in ctx.track_index.list_filenames(): 

300 full = resolve_library_file(stored, ctx) 

301 if full is not None: 

302 by_resolved[str(full.resolve())] = library_stored_path( 

303 full, ctx.download_dir, ctx.slskd_dir, ctx.extra_dirs 

304 ) 

305 

306 return sorted( 

307 ((stored, resolved) for resolved, stored in by_resolved.items()), 

308 key=lambda item: item[0], 

309 ) 

310 

311 

312def list_library_path_pairs(ctx: LibraryContext) -> list[tuple[str, str]]: 

313 """Playable library entries as ``(stored key, resolved path)``.""" 

314 

315 return get_cached_path_pairs(ctx, _scan_library_path_pairs) 

316 

317 

318def list_library_paths(ctx: LibraryContext) -> list[str]: 

319 """All playable library entries (downloads, slskd, extra folders).""" 

320 

321 return [stored for stored, _resolved in list_library_path_pairs(ctx)] 

322 

323 

324def _attach_playlists_to_entries( 

325 entries: list[dict[str, Any]], 

326 pairs: list[tuple[str, Path]], 

327 catalog: PlaylistCatalog, 

328) -> None: 

329 content_keys: list[str] = [] 

330 filenames: list[str] = [] 

331 ck_by_file: dict[str, str] = {} 

332 size_by_file = { 

333 str(entry.get('file') or '').replace('\\', '/'): int( 

334 entry.get('size') or 0 

335 ) 

336 for entry in entries 

337 } 

338 for stored, full in pairs: 

339 name = str(stored or '').strip().replace('\\', '/') 

340 if name: 

341 filenames.append(name) 

342 ck = file_content_key_from_name_and_size( 

343 full.name, size_by_file.get(name, 0) 

344 ) 

345 if ck: 

346 content_keys.append(ck) 

347 if name: 

348 ck_by_file[name] = ck 

349 by_ck = catalog.playlists_by_content_keys(content_keys) 

350 by_fn = catalog.playlists_by_filenames(filenames) 

351 for entry in entries: 

352 fn = str(entry.get('file') or '').replace('\\', '/') 

353 names: set[str] = set() 

354 ck = ck_by_file.get(fn) 

355 if ck: 

356 names.update(by_ck.get(ck, [])) 

357 names.update(by_fn.get(fn, [])) 

358 if names: 

359 entry['playlists'] = sorted(names) 

360 

361 

362def _attach_m3u_playlists_to_entries( 

363 entries: list[dict[str, Any]], ctx: LibraryContext 

364) -> None: 

365 from .playlist_listing import list_library_playlists # noqa: PLC0415 # import cycle 

366 

367 by_file: dict[str, set[str]] = {} 

368 for playlist in list_library_playlists( 

369 ctx.download_dir, ctx.slskd_dir, ctx.extra_dirs 

370 ): 

371 name = str(playlist.get('name') or '') 

372 if not name: 

373 continue 

374 for stored in playlist.get('files') or []: 

375 by_file.setdefault(str(stored), set()).add(name) 

376 if not by_file: 

377 return 

378 for entry in entries: 

379 extra = by_file.get(str(entry.get('file') or '')) 

380 if not extra: 

381 continue 

382 names = set(entry.get('playlists') or []) 

383 names.update(extra) 

384 entry['playlists'] = sorted(names) 

385 

386 

387def listing_for_request( 

388 ctx: LibraryContext, 

389 *, 

390 allowed_keys: Optional[Collection[str]] = None, 

391) -> list[dict[str, Any]]: 

392 """Last snapshot for UI routes; never walks the library on a hit. 

393 

394 ``allowed_keys`` keeps only a non-admin's own rows (the snapshot 

395 itself is never narrowed). 

396 """ 

397 

398 set_listing_refresh_fn(lambda: list_library_entries(ctx)) 

399 peeked = peek_cached_track_entries(ctx) 

400 if peeked is not None: 

401 return _filter_entries(peeked, allowed_keys) 

402 return list_library_entries(ctx, allowed_keys=allowed_keys) 

403 

404 

405def merge_library_listing_file(ctx: LibraryContext, stored: str) -> None: 

406 """Add one downloaded file to the RAM snapshot without a tree walk. 

407 

408 UI artist/album lists read that snapshot; a full rescan still runs 

409 later, after the download queue is idle. 

410 """ 

411 

412 with listing_lock(): 

413 _merge_library_listing_file(ctx, stored) 

414 

415 

416def _merge_library_listing_file(ctx: LibraryContext, stored: str) -> None: 

417 """Read/modify/publish under the writer lock, never the UI read lock.""" 

418 

419 name = str(stored or '').strip().replace('\\', '/') 

420 if not name: 

421 return 

422 peeked = peek_cached_track_entries(ctx) 

423 if peeked is None: 

424 return 

425 already = any( 

426 str(row.get('file') or '').replace('\\', '/') == name for row in peeked 

427 ) 

428 if already: 

429 return 

430 full = resolve_library_file(name, ctx) 

431 if full is None: 

432 return 

433 cache = ctx.metadata_cache 

434 if cache is not None: 

435 rows = cache.get_entries_batch([(name, full)]) 

436 else: 

437 rows = [library_entry_for_file(name, full)] 

438 if not rows: 

439 return 

440 merged = fold_library_entries([*peeked, *rows]) 

441 paths = peek_cached_path_pairs(ctx) or [] 

442 if not any(str(item[0]) == name for item in paths): 

443 paths = [*paths, (name, str(full))] 

444 store_cached_track_entries(ctx, merged, paths=paths, provisional=True) 

445 

446 

447def refresh_library_listing_files( 

448 ctx: LibraryContext, stored_paths: Sequence[str] 

449) -> None: 

450 """Re-read files whose tags were rewritten in place (the same path: 

451 an album marked as a compilation, replaced audio) into the RAM 

452 snapshot without a tree walk. 

453 

454 Not left to the background rescan: a download finishing first would 

455 store the snapshot with these files' old rows under the tree's new 

456 fingerprint (:func:`merge_library_listing_file`), and the old rows 

457 would then never be read again. 

458 """ 

459 

460 names = { 

461 str(item or '').strip().replace('\\', '/') for item in stored_paths 

462 } 

463 names.discard('') 

464 if not names: 

465 return 

466 peeked = peek_cached_track_entries(ctx) 

467 if peeked is None: 

468 return 

469 fresh: dict[str, dict[str, Any]] = {} 

470 for name in names: 

471 full = resolve_library_file(name, ctx) 

472 if full is None: 

473 continue 

474 cache = ctx.metadata_cache 

475 rows = ( 

476 cache.get_entries_batch([(name, full)]) 

477 if cache is not None 

478 else [library_entry_for_file(name, full)] 

479 ) 

480 if rows: 

481 fresh[name] = rows[0] 

482 if not fresh: 

483 return 

484 # A fresh row wins over the old one, which keeps what only the listing 

485 # adds on top of the tags (the playlists a file is in). 

486 rows = [ 

487 {**row, **fresh[key]} 

488 if (key := str(row.get('file') or '').replace('\\', '/')) in fresh 

489 else row 

490 for row in peeked 

491 ] 

492 store_cached_track_entries(ctx, rows, paths=peek_cached_path_pairs(ctx)) 

493 

494 

495def drop_library_listing_files( 

496 ctx: LibraryContext, stored_paths: Sequence[str] 

497) -> None: 

498 """Remove deleted files from the RAM snapshot without a tree walk. 

499 

500 Album/artist grids read that snapshot; a full rescan still runs 

501 later, after the download queue is idle. 

502 """ 

503 

504 with listing_lock(): 

505 _drop_library_listing_files(ctx, stored_paths) 

506 

507 

508def _drop_library_listing_files( 

509 ctx: LibraryContext, stored_paths: Sequence[str] 

510) -> None: 

511 names = { 

512 str(item or '').strip().replace('\\', '/') for item in stored_paths 

513 } 

514 names.discard('') 

515 if not names: 

516 return 

517 peeked = peek_cached_track_entries(ctx) 

518 if peeked is None: 

519 return 

520 kept = [ 

521 row 

522 for row in peeked 

523 if str(row.get('file') or '').replace('\\', '/') not in names 

524 ] 

525 if len(kept) == len(peeked): 

526 return 

527 paths = [ 

528 item 

529 for item in (peek_cached_path_pairs(ctx) or []) 

530 if str(item[0]).replace('\\', '/') not in names 

531 ] 

532 store_cached_track_entries(ctx, kept, paths=paths, provisional=True) 

533 

534 

535def entry_content_key(entry: dict[str, Any]) -> str: 

536 """The ownership key of a listing row (no disk access needed).""" 

537 

538 try: 

539 size = int(entry.get('size') or 0) 

540 except (TypeError, ValueError): 

541 return '' 

542 return ( 

543 file_content_key_from_name_and_size(str(entry.get('file') or ''), size) 

544 or '' 

545 ) 

546 

547 

548def list_library_entries( 

549 ctx: LibraryContext, 

550 *, 

551 fold_extra: bool = True, 

552 allowed_keys: Optional[Collection[str]] = None, 

553) -> list[dict[str, Any]]: 

554 """Playable library rows with title/artist from embedded tags. 

555 

556 ``fold_extra`` (default) drops extra-folder duplicates and remaps 

557 artist names. Sync passes ``False`` so it can log those skips itself. 

558 ``allowed_keys`` keeps only rows whose content key is in it (a 

559 non-admin's library); the shared snapshot itself is never narrowed. 

560 """ 

561 

562 if fold_extra: 

563 cached = get_cached_track_entries(ctx) 

564 if cached is not None: 

565 return _filter_entries( 

566 cached, 

567 allowed_keys, 

568 hidden_files=getattr(ctx, 'hidden_files', frozenset()), 

569 ) 

570 

571 with listing_lock(): 

572 if fold_extra: 

573 cached = get_cached_track_entries(ctx) 

574 if cached is not None: 

575 return _filter_entries( 

576 cached, 

577 allowed_keys, 

578 hidden_files=getattr(ctx, 'hidden_files', frozenset()), 

579 ) 

580 

581 path_rows = list_library_path_pairs(ctx) 

582 pairs: list[tuple[str, Path]] = [ 

583 (stored, Path(resolved)) for stored, resolved in path_rows 

584 ] 

585 cache = ctx.metadata_cache 

586 if cache is not None: 

587 entries = cache.get_entries_batch(pairs) 

588 else: 

589 entries = [ 

590 library_entry_for_file(stored, full) for stored, full in pairs 

591 ] 

592 if ctx.playlist_catalog is not None and entries: 

593 _attach_playlists_to_entries(entries, pairs, ctx.playlist_catalog) 

594 if entries: 

595 _attach_m3u_playlists_to_entries(entries, ctx) 

596 if not fold_extra: 

597 return entries 

598 entries = ( 

599 fold_library_entries(entries, ctx.primary_extra_id) 

600 if ctx.primary_extra_id 

601 else fold_library_entries(entries) 

602 ) 

603 store_cached_track_entries(ctx, entries, paths=path_rows) 

604 return _filter_entries( 

605 entries, 

606 allowed_keys, 

607 hidden_files=getattr(ctx, 'hidden_files', frozenset()), 

608 ) 

609 

610 

611def _filter_entries( 

612 entries: list[dict[str, Any]], 

613 allowed_keys: Optional[Collection[str]], 

614 hidden_files: frozenset[str] = frozenset(), 

615) -> list[dict[str, Any]]: 

616 if hidden_files: 

617 entries = [ 

618 e for e in entries if str(e.get('file') or '') not in hidden_files 

619 ] 

620 if allowed_keys is None: 

621 return entries 

622 allowed = set(allowed_keys) 

623 return [e for e in entries if entry_content_key(e) in allowed] 

624 

625 

626def list_entries_for_stored_paths( 

627 ctx: LibraryContext, 

628 stored_paths: list[str], 

629) -> list[dict[str, Any]]: 

630 """``GET /tracks`` rows for an explicit list of library keys. 

631 

632 Used when a playlist page only needs its own songs, not the whole 

633 library. Order follows *stored_paths*. 

634 """ 

635 

636 pairs: list[tuple[str, Path]] = [] 

637 seen: set[str] = set() 

638 for stored in stored_paths: 

639 name = str(stored or '').strip().replace('\\', '/') 

640 if not name or name in seen: 

641 continue 

642 seen.add(name) 

643 full = resolve_library_file(name, ctx) 

644 if full is not None: 

645 pairs.append((name, full)) 

646 cache = ctx.metadata_cache 

647 if cache is not None: 

648 by_file = { 

649 str(row.get('file') or ''): row 

650 for row in cache.get_entries_batch(pairs) 

651 } 

652 return [by_file[name] for name, _full in pairs if name in by_file] 

653 return [library_entry_for_file(stored, full) for stored, full in pairs] 

654 

655 

656def list_entries_for_playlist( 

657 ctx: LibraryContext, 

658 stored_paths: list[str], 

659) -> list[dict[str, Any]]: 

660 """``GET /tracks?playlist=`` rows, in playlist order. 

661 

662 Read from the listing snapshot, like ``GET /tracks``: asking the disk 

663 about each file twice took over a second for a playlist of 4000 songs 

664 on a NAS. Only files the snapshot doesn't have go to the disk (a 

665 folded extra-folder copy, or a file too new for it). 

666 """ 

667 

668 snapshot = peek_cached_track_entries(ctx) 

669 if not snapshot: 

670 return list_entries_for_stored_paths(ctx, stored_paths) 

671 by_file = {str(row.get('file') or ''): row for row in snapshot} 

672 names = dict.fromkeys( 

673 name 

674 for name in ( 

675 str(stored or '').strip().replace('\\', '/') 

676 for stored in stored_paths 

677 ) 

678 if name 

679 ) 

680 missing = [name for name in names if name not in by_file] 

681 for row in list_entries_for_stored_paths(ctx, missing): 

682 by_file[str(row.get('file') or '')] = row 

683 return [by_file[name] for name in names if name in by_file] 

684 

685 

686def fold_text(text: str) -> str: 

687 """Case- and accent-fold, matching the Library page's filter.""" 

688 

689 nfkd = unicodedata.normalize('NFD', str(text or '')) 

690 stripped = ''.join( 

691 char for char in nfkd if unicodedata.category(char) != 'Mn' 

692 ) 

693 return stripped.casefold() 

694 

695 

696def song_key(artist: str, title: str) -> str: 

697 """Loose already-downloaded key; keep in sync with ``songKey`` in JS.""" 

698 

699 def clean(text: str) -> str: 

700 folded = fold_text(text) 

701 folded = _SAME_SONG_TAG.sub(' ', folded) 

702 folded = _FEAT_TAIL.sub(' ', folded) 

703 folded = _REMASTER_TAIL.sub(' ', folded) 

704 folded = ''.join(ch if ch.isalnum() else ' ' for ch in folded) 

705 return ' '.join(folded.split()) 

706 

707 first = _ARTIST_SPLIT.split(str(artist or ''), maxsplit=1)[0].strip() 

708 return f'{clean(first)}|{clean(title)}' 

709 

710 

711_VARIOUS_ARTISTS = frozenset({'various artists', 'various'}) 

712 

713 

714def _first_artist(entry: dict[str, Any]) -> str: 

715 artists = entry.get('artists') 

716 if isinstance(artists, list): 

717 for name in artists: 

718 if str(name).strip(): 

719 return str(name).strip() 

720 return str(entry.get('artist') or '').split(';')[0].strip() 

721 

722 

723def album_artist_of(entry: dict[str, Any]) -> str: 

724 """The artist a track belongs to (album artist, else first artist). 

725 

726 ``Various Artists`` is treated as missing so a compilation's track - or 

727 a duo tagged that way (``Zé Neto & Cristiano`` in the artist tag) - 

728 belongs to its own first artist. Matches ``groupingArtistName`` in 

729 ``frontend/src/lib/library.js``. 

730 """ 

731 

732 album_artist = str(entry.get('album_artist') or '').strip() 

733 if album_artist and album_artist.casefold() not in _VARIOUS_ARTISTS: 

734 return album_artist 

735 return _first_artist(entry) 

736 

737 

738def album_owner_of(entry: dict[str, Any]) -> str: 

739 """The artist an album is listed under: its album-artist tag as it is 

740 - so a ``Various Artists`` compilation stays one album - else the 

741 track's first artist. ``Various Artists`` only counts on a track with 

742 the compilation flag (``TCMP`` / ``COMPILATION`` / ``cpil``), which 

743 Downtify writes on a real compilation: older versions tagged any song 

744 with several artists ``Various Artists`` without it, and such a track 

745 stays with its first artist's album (:func:`album_artist_of`). 

746 Matches ``albumOwnerName`` in the web app.""" 

747 

748 album_artist = str(entry.get('album_artist') or '').strip() 

749 if album_artist.casefold() in _VARIOUS_ARTISTS and not entry.get( 

750 'compilation' 

751 ): 

752 return album_artist_of(entry) 

753 return album_artist or _first_artist(entry) 

754 

755 

756def credited_artists_of(entry: dict[str, Any]) -> list[str]: 

757 """Every artist credited on this track: the one it belongs to 

758 (:func:`album_artist_of`), then every other credited artist. Never 

759 ``Various Artists``. A guest's credit only counts on a page they 

760 already have (see :func:`artists_with_pages`).""" 

761 

762 names: list[str] = [] 

763 seen: set[str] = set() 

764 artists = entry.get('artists') 

765 for name in [ 

766 album_artist_of(entry), 

767 *(artists if isinstance(artists, list) else []), 

768 ]: 

769 text = str(name or '').strip() 

770 key = text.casefold() 

771 if not text or key in _VARIOUS_ARTISTS or key in seen: 

772 continue 

773 seen.add(key) 

774 names.append(text) 

775 return names 

776 

777 

778def artists_with_pages(entries: Iterable[dict[str, Any]]) -> set[str]: 

779 """The casefolded names with a Library page: every artist some track 

780 belongs to (:func:`album_artist_of`). A guest credit alone makes none: 

781 tags can name a duo's members one by one (``Henrique; Juliano``, as 

782 YouTube Music credits some duos), and a page per member would be an 

783 artist that doesn't exist. Matches ``groupArtists`` in the web app.""" 

784 

785 names: set[str] = set() 

786 for entry in entries: 

787 key = album_artist_of(entry).casefold() 

788 if key and key not in _VARIOUS_ARTISTS: 

789 names.add(key) 

790 return names 

791 

792 

793def _group_albums( 

794 entries: list[dict[str, Any]], 

795) -> dict[tuple[str, str], dict[str, Any]]: 

796 albums: dict[tuple[str, str], dict[str, Any]] = {} 

797 for entry in entries: 

798 album = str(entry.get('album') or '').strip() 

799 if not album: 

800 continue 

801 artist = album_owner_of(entry) 

802 key = (artist.casefold(), album.casefold()) 

803 bucket = albums.get(key) 

804 if bucket is None: 

805 bucket = { 

806 'title': album, 

807 'artist': artist, 

808 'year': str(entry.get('year') or ''), 

809 'added': int(entry.get('added') or 0), 

810 'tracks': [], 

811 } 

812 albums[key] = bucket 

813 bucket['tracks'].append(entry) 

814 bucket['added'] = max(bucket['added'], int(entry.get('added') or 0)) 

815 if not bucket['year'] and entry.get('year'): 

816 bucket['year'] = str(entry.get('year') or '') 

817 return albums 

818 

819 

820def filter_library_entries( 

821 entries: list[dict[str, Any]], 

822 *, 

823 artist: str = '', 

824 album: str = '', 

825 q: str = '', 

826 limit: int = 0, 

827) -> list[dict[str, Any]]: 

828 """Subset of listing rows for ``GET /tracks`` query filters.""" 

829 

830 want_artist = str(artist or '').strip().casefold() 

831 want_album = str(album or '').strip().casefold() 

832 words = [word for word in fold_text(q).split() if word] 

833 cap = min(max(int(limit or 0), 0), TRACK_QUERY_LIMIT_MAX) 

834 out: list[dict[str, Any]] = [] 

835 for entry in entries: 

836 # An artist's page wants every track they're credited on; an 

837 # album's page (artist = its album artist, "Various Artists" 

838 # included) every track of that album. 

839 if ( 

840 want_artist 

841 and album_owner_of(entry).casefold() != want_artist 

842 and want_artist 

843 not in {name.casefold() for name in credited_artists_of(entry)} 

844 ): 

845 continue 

846 if want_album: 

847 tagged = str(entry.get('album') or '').strip().casefold() 

848 if tagged != want_album: 

849 continue 

850 if words: 

851 haystack = fold_text( 

852 ' '.join(( 

853 str(entry.get('title') or ''), 

854 str(entry.get('artist') or ''), 

855 str(entry.get('album') or ''), 

856 str(entry.get('file') or ''), 

857 )) 

858 ) 

859 if not all(word in haystack for word in words): 

860 continue 

861 out.append(entry) 

862 if cap and len(out) >= cap: 

863 break 

864 return out 

865 

866 

867def lookup_library_songs( 

868 ctx: LibraryContext, 

869 songs: Sequence[Any], 

870 *, 

871 allowed_keys: Optional[Collection[str]] = None, 

872) -> list[dict[str, Any]]: 

873 """``GET /tracks`` rows that match search/link songs already downloaded. 

874 

875 ``allowed_keys`` keeps only a non-admin's own matches, so the search 

876 page doesn't offer someone else's file as "already downloaded". 

877 """ 

878 

879 wanted: list[str] = [] 

880 seen_keys: set[str] = set() 

881 for raw in songs[:LOOKUP_SONG_MAX]: 

882 if not isinstance(raw, dict): 

883 continue 

884 artist = str(raw.get('artist') or '').strip() 

885 artists = raw.get('artists') 

886 if not artist and isinstance(artists, list) and artists: 

887 artist = str(artists[0] or '').strip() 

888 title = str(raw.get('title') or raw.get('name') or '').strip() 

889 key = song_key(artist, title) 

890 if key == '|' or key in seen_keys: 

891 continue 

892 seen_keys.add(key) 

893 wanted.append(key) 

894 if not wanted: 

895 return [] 

896 pending = set(wanted) 

897 found: list[dict[str, Any]] = [] 

898 found_keys: set[str] = set() 

899 for entry in listing_for_request(ctx, allowed_keys=allowed_keys): 

900 key = song_key( 

901 str(entry.get('artist') or ''), 

902 str(entry.get('title') or ''), 

903 ) 

904 if key not in pending or key in found_keys: 

905 continue 

906 found_keys.add(key) 

907 found.append(entry) 

908 if len(found_keys) == len(pending): 

909 break 

910 return found 

911 

912 

913def library_album_index( 

914 ctx: LibraryContext, 

915 *, 

916 allowed_keys: Optional[Collection[str]] = None, 

917 hidden: Optional[HiddenRules] = None, 

918) -> list[dict[str, Any]]: 

919 """Albums for the Library grid: counts and a cover file, not every track. 

920 

921 ``hidden`` (an admin's view, see :mod:`downtify.library_visibility`) 

922 marks albums hidden from other users with ``hidden_by`` (``album`` or 

923 ``artist``); they stay in the list. 

924 """ 

925 

926 grouped = _group_albums( 

927 listing_for_request(ctx, allowed_keys=allowed_keys) 

928 ) 

929 rows: list[dict[str, Any]] = [] 

930 for bucket in grouped.values(): 

931 tracks = bucket['tracks'] 

932 cover_file = '' 

933 duration = 0.0 

934 size = 0 

935 for track in tracks: 

936 duration += float(track.get('duration') or 0) 

937 size += int(track.get('size') or 0) 

938 if not cover_file and track.get('has_cover'): 

939 cover_file = str(track.get('file') or '') 

940 row = { 

941 'title': bucket['title'], 

942 'artist': bucket['artist'], 

943 'year': bucket['year'], 

944 'added': int(bucket['added'] or 0), 

945 'duration': duration, 

946 'size': size, 

947 'track_count': len(tracks), 

948 'cover_file': cover_file, 

949 } 

950 if hidden: 

951 reason = hidden.album_reason(bucket['artist'], bucket['title']) 

952 if reason: 

953 row['hidden_by'] = reason 

954 rows.append(row) 

955 rows.sort( 

956 key=lambda row: (-int(row['added']), str(row['title']).casefold()) 

957 ) 

958 return rows 

959 

960 

961def library_artist_index( 

962 ctx: LibraryContext, 

963 liked_paths: Optional[set[str]] = None, 

964 *, 

965 allowed_keys: Optional[Collection[str]] = None, 

966 hidden: Optional[HiddenRules] = None, 

967) -> list[dict[str, Any]]: 

968 """Artists for the Library grid and Discover, without every track row. 

969 

970 ``hidden`` (an admin's view) marks artists hidden from other users 

971 with ``hidden_by: 'artist'``; they stay in the list. 

972 """ 

973 

974 liked = liked_paths or set() 

975 artists: dict[str, dict[str, Any]] = {} 

976 entries = listing_for_request(ctx, allowed_keys=allowed_keys) 

977 with_pages = artists_with_pages(entries) 

978 for entry in entries: 

979 stored = str(entry.get('file') or '').replace('\\', '/') 

980 album = str(entry.get('album') or '').strip() 

981 owner = album_owner_of(entry).casefold() 

982 # Every credited artist with a page gets the track (a guest too); 

983 # an album only counts for its own album artist. 

984 for name in credited_artists_of(entry): 

985 key = name.casefold() 

986 if key not in with_pages: 

987 continue 

988 bucket = artists.get(key) 

989 if bucket is None: 

990 bucket = { 

991 'name': name, 

992 'added': 0, 

993 'duration': 0.0, 

994 'track_count': 0, 

995 'liked_count': 0, 

996 'album_count': 0, 

997 'cover_file': '', 

998 '_albums': set(), 

999 } 

1000 artists[key] = bucket 

1001 bucket['track_count'] += 1 

1002 bucket['duration'] += float(entry.get('duration') or 0) 

1003 bucket['added'] = max( 

1004 int(bucket['added'] or 0), int(entry.get('added') or 0) 

1005 ) 

1006 if stored in liked: 

1007 bucket['liked_count'] += 1 

1008 if not bucket['cover_file'] and entry.get('has_cover'): 

1009 bucket['cover_file'] = stored 

1010 if album and key == owner: 

1011 bucket['_albums'].add(album.casefold()) 

1012 rows: list[dict[str, Any]] = [] 

1013 for bucket in artists.values(): 

1014 album_keys = bucket.pop('_albums') 

1015 bucket['album_count'] = len(album_keys) 

1016 if hidden and hidden.artist_hidden(bucket['name']): 

1017 bucket['hidden_by'] = 'artist' 

1018 rows.append(bucket) 

1019 rows.sort(key=lambda row: str(row['name']).casefold()) 

1020 return rows 

1021 

1022 

1023def library_home_summary( 

1024 ctx: LibraryContext, 

1025 *, 

1026 recent_albums: int = 12, 

1027 allowed_keys: Optional[Collection[str]] = None, 

1028) -> dict[str, Any]: 

1029 """Counts and a short recent-album shelf for the Home page.""" 

1030 

1031 entries = listing_for_request(ctx, allowed_keys=allowed_keys) 

1032 albums = _group_albums(entries) 

1033 artists = artists_with_pages(entries) 

1034 total_size = 0 

1035 for entry in entries: 

1036 total_size += int(entry.get('size') or 0) 

1037 recent = sorted(albums.values(), key=lambda row: -int(row['added']))[ 

1038 :recent_albums 

1039 ] 

1040 return { 

1041 'track_count': len(entries), 

1042 'album_count': len(albums), 

1043 'artist_count': len(artists), 

1044 'size': total_size, 

1045 'recent_albums': recent, 

1046 }