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
« 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."""
3from __future__ import annotations
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
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
35if TYPE_CHECKING:
36 from .library_visibility import HiddenRules
38AUDIO_EXTENSIONS = frozenset({
39 '.mp3',
40 '.m4a',
41 '.flac',
42 '.ogg',
43 '.wav',
44 '.aac',
45 '.opus',
46})
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()
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
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 )
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'
110#: Cap on ``GET /tracks?limit=`` and ``POST /api/library/lookup``.
111TRACK_QUERY_LIMIT_MAX = 200
112LOOKUP_SONG_MAX = 200
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',|;| & ')
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'
131#: Sidecar artwork Downtify writes (playlist covers) or that already
132#: sits beside downloaded tracks.
133IMAGE_EXTENSIONS = frozenset({'.jpg', '.jpeg', '.png', '.webp'})
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
142def _is_image(path: Path) -> bool:
143 return path.is_file() and path.suffix.lower() in IMAGE_EXTENSIONS
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."""
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
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
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)
187 for root in allowed_roots:
188 try:
189 candidate.relative_to(root)
190 return candidate
191 except ValueError:
192 continue
193 return None
196def resolve_library_file(stored: str, ctx: LibraryContext) -> Optional[Path]:
197 """Resolve a library-relative path if it points to an allowed audio file."""
199 return _resolve_within_library(stored, ctx, _is_audio)
202def resolve_library_image(stored: str, ctx: LibraryContext) -> Optional[Path]:
203 """Resolve a library-relative path to a cover image sitting in the library.
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 """
210 return _resolve_within_library(stored, ctx, _is_image)
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
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)
251def _walk_audio_files(root: Path, *, prune_podcasts: bool = False):
252 """Yield audio files under *root* without visiting every other file."""
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
275def _scan_library_path_pairs(ctx: LibraryContext) -> list[tuple[str, str]]:
276 """Scan disk for playable ``(stored, resolved)`` pairs (uncached)."""
278 by_resolved: dict[str, str] = {}
279 roots = ResolvedLibraryRoots.from_dirs(
280 ctx.download_dir, ctx.slskd_dir, ctx.extra_dirs
281 )
283 for path in _walk_audio_files(ctx.download_dir, prune_podcasts=True):
284 _register_path(path, ctx, by_resolved, roots)
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)
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)
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 )
306 return sorted(
307 ((stored, resolved) for resolved, stored in by_resolved.items()),
308 key=lambda item: item[0],
309 )
312def list_library_path_pairs(ctx: LibraryContext) -> list[tuple[str, str]]:
313 """Playable library entries as ``(stored key, resolved path)``."""
315 return get_cached_path_pairs(ctx, _scan_library_path_pairs)
318def list_library_paths(ctx: LibraryContext) -> list[str]:
319 """All playable library entries (downloads, slskd, extra folders)."""
321 return [stored for stored, _resolved in list_library_path_pairs(ctx)]
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)
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
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)
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.
394 ``allowed_keys`` keeps only a non-admin's own rows (the snapshot
395 itself is never narrowed).
396 """
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)
405def merge_library_listing_file(ctx: LibraryContext, stored: str) -> None:
406 """Add one downloaded file to the RAM snapshot without a tree walk.
408 UI artist/album lists read that snapshot; a full rescan still runs
409 later, after the download queue is idle.
410 """
412 with listing_lock():
413 _merge_library_listing_file(ctx, stored)
416def _merge_library_listing_file(ctx: LibraryContext, stored: str) -> None:
417 """Read/modify/publish under the writer lock, never the UI read lock."""
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)
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.
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 """
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))
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.
500 Album/artist grids read that snapshot; a full rescan still runs
501 later, after the download queue is idle.
502 """
504 with listing_lock():
505 _drop_library_listing_files(ctx, stored_paths)
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)
535def entry_content_key(entry: dict[str, Any]) -> str:
536 """The ownership key of a listing row (no disk access needed)."""
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 )
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.
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 """
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 )
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 )
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 )
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]
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.
632 Used when a playlist page only needs its own songs, not the whole
633 library. Order follows *stored_paths*.
634 """
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]
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.
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 """
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]
686def fold_text(text: str) -> str:
687 """Case- and accent-fold, matching the Library page's filter."""
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()
696def song_key(artist: str, title: str) -> str:
697 """Loose already-downloaded key; keep in sync with ``songKey`` in JS."""
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())
707 first = _ARTIST_SPLIT.split(str(artist or ''), maxsplit=1)[0].strip()
708 return f'{clean(first)}|{clean(title)}'
711_VARIOUS_ARTISTS = frozenset({'various artists', 'various'})
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()
723def album_artist_of(entry: dict[str, Any]) -> str:
724 """The artist a track belongs to (album artist, else first artist).
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 """
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)
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."""
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)
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`)."""
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
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."""
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
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
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."""
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
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.
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 """
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
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.
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 """
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
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.
970 ``hidden`` (an admin's view) marks artists hidden from other users
971 with ``hidden_by: 'artist'``; they stay in the list.
972 """
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
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."""
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 }