Coverage for downtify/external_library.py: 81%
522 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"""Import audio that already lives outside Downtify's download folder.
3Folders listed in Settings (``external_library.folders``) are scanned in
4place — files are not copied. Tracks that already exist in the download
5or slskd trees (same song, by tags) are skipped. Artist names are folded
6onto names already in the library when they clearly match.
7"""
9from __future__ import annotations
11import re
12import time
13import unicodedata
14from collections.abc import Callable
15from concurrent.futures import Future, ThreadPoolExecutor, as_completed
16from difflib import SequenceMatcher
17from pathlib import Path
18from typing import Any, Optional
20from loguru import logger
22from . import lyrics as lyrics_mod
23from .artist_profile import profile_seed_enqueue
24from .cover_sources import PREFERENCE_HIGHEST
25from .image_size import image_short_side
26from .itunes import fetch_genre
27from .library_catalog import (
28 AUDIO_EXTENSIONS,
29 list_library_entries,
30 resolve_library_file,
31)
32from .library_metadata import library_entry_for_file
33from .library_paths import EXTERNAL_LIBRARY_PREFIX
34from .library_paths_cache import invalidate_library_paths_cache
35from .library_preference import prefer_entries
36from .library_upgrade import (
37 CATEGORY_ARTWORK,
38 UpgradeOptions,
39 _Artwork,
40 _pick_artwork,
41 _write_upgrade,
42)
43from .lyrics import read_track_lyrics, write_to_file
45MAX_EXTERNAL_FOLDERS = 20
46MAX_FOLDER_PATH_LEN = 1024
47# Same ceiling as ``downloader.MAX_PARALLEL_DOWNLOADS``.
48_MAX_ENRICH_WORKERS = 30
49_DURATION_TOLERANCE = 5.0
50_NAME_RATIO = 0.92
51_LEADING_THE = re.compile(r'^the\s+', re.IGNORECASE)
52_NON_ALNUM = re.compile(r'[^\w\s]', re.UNICODE)
53_FEAT_TAIL = re.compile(r'\s(?:feat|ft)\.?\s.*$', re.IGNORECASE)
54_REMASTER_TAIL = re.compile(r'\s-\s[^-]*remaster[^-]*$', re.IGNORECASE)
55_SAME_SONG_TAG = re.compile(
56 r'[([](?:(?:feat|ft|with)\b|[^)\]]*remaster)[^)\]]*[)\]]',
57 re.IGNORECASE,
58)
61def is_external_stored(stored: str) -> bool:
62 text = str(stored or '').strip().replace('\\', '/')
63 return text.startswith(EXTERNAL_LIBRARY_PREFIX)
66def _clean_folder_path(raw: Any) -> str:
67 text = str(raw or '').strip()
68 if not text or '\0' in text:
69 return ''
70 if len(text) > MAX_FOLDER_PATH_LEN:
71 return ''
72 path = Path(text)
73 if not path.is_absolute():
74 return ''
75 return text.replace('\\', '/')
78def sanitize_external_folders(raw: Any) -> list[str]:
79 """Absolute paths, unique, capped — empty / relative entries dropped."""
81 if isinstance(raw, str):
82 items = [raw]
83 elif isinstance(raw, list):
84 items = raw
85 else:
86 items = []
87 folders: list[str] = []
88 seen: set[str] = set()
89 for item in items:
90 cleaned = _clean_folder_path(item)
91 if not cleaned:
92 continue
93 try:
94 key = str(Path(cleaned).resolve())
95 except OSError:
96 key = cleaned
97 if key in seen:
98 continue
99 seen.add(key)
100 folders.append(cleaned)
101 if len(folders) >= MAX_EXTERNAL_FOLDERS:
102 break
103 return folders
106def effective_external_library(settings: dict[str, Any]) -> dict[str, Any]:
107 raw = settings.get('external_library')
108 if not isinstance(raw, dict):
109 raw = {}
110 folders = sanitize_external_folders(raw.get('folders'))
111 result: dict[str, Any] = {'folders': folders}
112 primary = str(raw.get('primary_folder') or '')
113 if primary in folders:
114 result['primary_folder'] = primary
115 return result
118def extra_dirs_from_settings(
119 settings: dict[str, Any],
120 download_dir: Path,
121 slskd_dir: Optional[Path] = None,
122) -> tuple[Path, ...]:
123 """Folders to scan, skipping ones already covered by downloads/slskd."""
125 download_resolved = download_dir.resolve()
126 slskd_resolved: Optional[Path] = None
127 if slskd_dir is not None:
128 try:
129 slskd_resolved = slskd_dir.resolve()
130 except OSError:
131 slskd_resolved = slskd_dir
132 roots: list[Path] = []
133 seen: set[str] = set()
134 for text in effective_external_library(settings)['folders']:
135 root = Path(text)
136 try:
137 resolved = root.resolve()
138 except OSError:
139 resolved = root
140 key = str(resolved)
141 if key in seen:
142 continue
143 if _is_same_or_inside(resolved, download_resolved):
144 continue
145 if slskd_resolved is not None and _is_same_or_inside(
146 resolved, slskd_resolved
147 ):
148 continue
149 seen.add(key)
150 roots.append(root)
151 return tuple(roots)
154def _is_same_or_inside(path: Path, root: Path) -> bool:
155 try:
156 path.relative_to(root)
157 except ValueError:
158 return False
159 return True
162def fold_text(value: str) -> str:
163 text = unicodedata.normalize('NFKD', str(value or ''))
164 text = ''.join(char for char in text if not unicodedata.combining(char))
165 return text.casefold()
168def artist_match_key(name: str) -> str:
169 text = fold_text(name)
170 text = _LEADING_THE.sub('', text)
171 text = _NON_ALNUM.sub(' ', text)
172 return ' '.join(text.split())
175def _compact_key(name: str) -> str:
176 return artist_match_key(name).replace(' ', '')
179def _title_key(title: str) -> str:
180 text = fold_text(title)
181 text = _SAME_SONG_TAG.sub(' ', text)
182 text = _FEAT_TAIL.sub(' ', text)
183 text = _REMASTER_TAIL.sub(' ', text)
184 text = _NON_ALNUM.sub(' ', text)
185 return ' '.join(text.split())
188def _primary_artist(entry: dict[str, Any]) -> str:
189 album_artist = str(entry.get('album_artist') or '').strip()
190 if album_artist:
191 return album_artist
192 artist = str(entry.get('artist') or '').strip()
193 if not artist:
194 return ''
195 for sep in (';', '/', ',', '\\'):
196 if sep in artist:
197 return artist.split(sep, 1)[0].strip()
198 return artist
201def song_identity(entry: dict[str, Any]) -> str:
202 title = str(entry.get('title') or '').strip()
203 if not title:
204 stored = str(entry.get('file') or '').replace('\\', '/')
205 title = Path(stored).stem
206 return f'{artist_match_key(_primary_artist(entry))}|{_title_key(title)}'
209def _durations_compatible(left: dict[str, Any], right: dict[str, Any]) -> bool:
210 try:
211 da = float(left.get('duration') or 0.0)
212 db = float(right.get('duration') or 0.0)
213 except (TypeError, ValueError):
214 return True
215 if da <= 0 or db <= 0:
216 return True
217 return abs(da - db) <= _DURATION_TOLERANCE
220def match_artist(name: str, catalog: list[str]) -> Optional[str]:
221 """Return a catalog name when *name* is the same artist, else ``None``."""
223 return _ArtistMatcher(catalog).match(name)
226class _ArtistMatcher:
227 """Prepared names and per-fold results, including unmatched artists.
229 The cache belongs to one catalog snapshot: a newly downloaded artist
230 must be considered by the next fold. Candidate order is significant
231 for exact/compact matches, substring matches, and fuzzy-score ties.
232 """
234 def __init__(self, catalog: list[str]) -> None:
235 self._catalog = [
236 (candidate, artist_match_key(candidate)) for candidate in catalog
237 ]
238 self._results: dict[str, Optional[str]] = {}
240 def match(self, name: str) -> Optional[str]:
241 if name not in self._results:
242 self._results[name] = self._match(name)
243 return self._results[name]
245 def _match(self, name: str) -> Optional[str]:
246 wanted = artist_match_key(name)
247 compact = wanted.replace(' ', '')
248 if not wanted:
249 return None
250 for candidate, other in self._catalog:
251 if other == wanted or (
252 compact and other.replace(' ', '') == compact
253 ):
254 return candidate
255 if len(wanted) < 4:
256 return None
257 best_name = ''
258 best_ratio = 0.0
259 for candidate, other in self._catalog:
260 if not other:
261 continue
262 if wanted in other or other in wanted:
263 return candidate
264 ratio = SequenceMatcher(None, wanted, other).ratio()
265 if ratio > best_ratio:
266 best_ratio = ratio
267 best_name = candidate
268 return best_name if best_ratio >= _NAME_RATIO else None
271def _catalog_from_owned(owned: list[dict[str, Any]]) -> list[str]:
272 names: list[str] = []
273 seen: set[str] = set()
274 for entry in owned:
275 name = _primary_artist(entry)
276 if not name:
277 continue
278 key = artist_match_key(name)
279 if not key or key in seen:
280 continue
281 seen.add(key)
282 names.append(name)
283 return names
286def _replace_primary_artist(artist: str, canonical: str) -> str:
287 text = str(artist or '').strip()
288 if not text:
289 return canonical
290 for sep in ('; ', ' / ', ', ', ';', '/', ',', '\\'):
291 if sep in text:
292 rest = text.split(sep, 1)[1]
293 joiner = sep if sep in {'; ', ' / ', ', '} else f'{sep} '
294 return f'{canonical}{joiner}{rest}'
295 return canonical
298def _remap_entry(
299 entry: dict[str, Any], matcher: _ArtistMatcher
300) -> dict[str, Any]:
301 primary = _primary_artist(entry)
302 if not primary:
303 return entry
304 canonical = matcher.match(primary)
305 if not canonical or canonical == primary:
306 return entry
307 out = dict(entry)
308 out['album_artist'] = canonical
309 out['artist'] = _replace_primary_artist(
310 str(entry.get('artist') or ''), canonical
311 )
312 return out
315def partition_extra_entries(
316 entries: list[dict[str, Any]],
317) -> tuple[
318 list[dict[str, Any]],
319 list[dict[str, Any]],
320 list[tuple[dict[str, Any], str]],
321]:
322 """Split library rows into owned, imported extra, and skipped extra.
324 Skip reasons: ``duplicate`` (already in downloads/slskd or another
325 extra file of the same song) or ``duplicate_folder`` (same song
326 twice in the extra folders).
327 """
329 owned: list[dict[str, Any]] = []
330 extra: list[dict[str, Any]] = []
331 for entry in entries:
332 if is_external_stored(str(entry.get('file') or '')):
333 extra.append(entry)
334 else:
335 owned.append(entry)
336 if not extra:
337 return owned, [], []
339 matcher = _ArtistMatcher(_catalog_from_owned(owned))
340 owned_by_id: dict[str, list[dict[str, Any]]] = {}
341 for item in owned:
342 owned_by_id.setdefault(song_identity(item), []).append(item)
344 kept: list[dict[str, Any]] = []
345 skipped: list[tuple[dict[str, Any], str]] = []
346 seen_extra: set[str] = set()
347 for entry in extra:
348 remapped = _remap_entry(entry, matcher)
349 ident = song_identity(remapped)
350 if ident in seen_extra:
351 skipped.append((remapped, 'duplicate_folder'))
352 continue
353 duplicates = owned_by_id.get(ident, [])
354 if any(_durations_compatible(remapped, other) for other in duplicates):
355 skipped.append((remapped, 'duplicate'))
356 continue
357 seen_extra.add(ident)
358 kept.append(remapped)
359 return owned, kept, skipped
362def finish_library_entries(
363 entries: list[dict[str, Any]],
364 primary_extra_id: str = '',
365) -> list[dict[str, Any]]:
366 """Fold extra-folder tracks onto the rest of the library.
368 Extra files that duplicate a download/slskd track (same song) are
369 dropped. Artist spellings are rewritten to a name already in the
370 library when the match is confident.
371 """
373 if not any(
374 is_external_stored(str(entry.get('file') or '')) for entry in entries
375 ):
376 return entries
377 if primary_extra_id:
378 return prefer_entries(
379 entries, primary_extra_id, finish_library_entries
380 )
381 owned, kept, _skipped = partition_extra_entries(entries)
382 return owned + kept
385def missing_external_folders(settings: dict[str, Any]) -> list[str]:
386 missing: list[str] = []
387 for text in effective_external_library(settings)['folders']:
388 path = Path(text)
389 try:
390 ok = path.is_dir()
391 except OSError:
392 ok = False
393 if not ok:
394 missing.append(text)
395 return missing
398def _song_for_import(entry: dict[str, Any]) -> dict[str, Any]:
399 artist = str(entry.get('artist') or '')
400 artists = [part.strip() for part in artist.split(';') if part.strip()]
401 if len(artists) == 1:
402 text = artists[0]
403 for sep in ('/', ',', ';'):
404 if sep in text:
405 artists = [
406 part.strip() for part in text.split(sep) if part.strip()
407 ]
408 break
409 elif not artists and artist:
410 artists = [artist]
411 return {
412 'name': str(entry.get('title') or ''),
413 'artists': artists,
414 'artist': artist,
415 'album_name': str(entry.get('album') or ''),
416 'album_artist': str(entry.get('album_artist') or ''),
417 'year': str(entry.get('year') or ''),
418 'genre': str(entry.get('genre') or ''),
419 'track_number': int(entry.get('track_number') or 0),
420 'duration': float(entry.get('duration') or 0.0),
421 'explicit': bool(entry.get('explicit')),
422 }
425def _row_for_import(
426 stored: str, ctx: Any, full: Path
427) -> tuple[dict[str, Any], Any]:
428 cache = getattr(ctx, 'metadata_cache', None)
429 if cache is None:
430 return library_entry_for_file(stored, full), None
431 rows = cache.get_entries_batch([(stored, full)])
432 return (rows[0] if rows else {'file': stored}), cache
435def _lyrics_for_import(
436 full: Path,
437 song: dict[str, Any],
438 settings: dict[str, Any],
439 lyrics_cache: Optional[Any],
440) -> tuple[Any, bool]:
441 """Return ``(lyrics, looked_up_and_missed)``.
443 A sidecar already at the configured location is enough. Embedded
444 tags alone are not: Sync must still write a ``.lrc`` when the user
445 chose a lyrics folder (or beside the file) and that file is missing.
446 """
448 providers = lyrics_mod.providers_from_settings(settings)
449 if not providers:
450 return None, False
451 dest = lyrics_mod.lrc_path_for(full)
452 try:
453 if dest.is_file() and dest.stat().st_size:
454 return None, False
455 except OSError:
456 pass
457 existing = read_track_lyrics(full, raw=True)
458 tagged = existing.get('plain') or existing.get('synced') or ''
459 if lyrics_mod.looks_like_lrc(tagged):
460 plain = lyrics_mod._strip_lrc_timestamps(tagged) or tagged
461 return lyrics_mod.Lyrics(synced=tagged, plain=plain), False
462 try:
463 found = lyrics_mod.fetch(song, providers, lyrics_cache)
464 except Exception:
465 logger.opt(exception=True).debug(
466 'External sync: lyrics fetch failed for {!r}',
467 song.get('name'),
468 )
469 return None, True
470 if found is not None and found.has_any():
471 return found, False
472 return None, True
475def _cover_for_import(
476 song: dict[str, Any],
477 full: Path,
478 entry: dict[str, Any],
479 settings: dict[str, Any],
480) -> Any:
481 if not settings.get('download_cover_art', True) or entry.get('has_cover'):
482 return None
483 options = UpgradeOptions(
484 categories=(CATEGORY_ARTWORK,),
485 artwork_min_px=1,
486 artwork_source=PREFERENCE_HIGHEST,
487 )
488 try:
489 artwork = _pick_artwork(song, full, entry, options=options)
490 except Exception:
491 logger.opt(exception=True).debug(
492 'External sync: cover lookup failed for {!r}',
493 song.get('name'),
494 )
495 return None
496 if artwork is not None and artwork.data:
497 return artwork
498 return None
501def _genre_for_import(song: dict[str, Any]) -> str:
502 if str(song.get('genre') or '').strip():
503 return ''
504 try:
505 return fetch_genre(song) or ''
506 except Exception:
507 logger.opt(exception=True).debug(
508 'External sync: genre lookup failed for {!r}',
509 song.get('name'),
510 )
511 return ''
514def _write_import_tags(
515 full: Path, song: dict[str, Any], artwork: Any, genre: str
516) -> tuple[bool, bool, str]:
517 if artwork is None and not genre:
518 return False, False, ''
519 error = _write_upgrade(
520 full,
521 song,
522 artwork=artwork if artwork is not None else _Artwork(),
523 new_lyrics=None,
524 write_tags=True,
525 )
526 if error:
527 logger.warning('External sync: could not tag {}: {}', full.name, error)
528 return False, False, 'tags'
529 return artwork is not None, bool(genre), ''
532def _write_import_lyrics(full: Path, new_lyrics: Any) -> bool:
533 try:
534 write_to_file(full, new_lyrics)
535 except Exception:
536 logger.opt(exception=True).warning(
537 'External sync: could not embed lyrics in {}', full.name
538 )
539 return False
540 return True
543def enrich_imported_track(
544 stored: str,
545 ctx: Any,
546 *,
547 settings: dict[str, Any],
548 lyrics_cache: Optional[Any] = None,
549 cover_cache: Optional[Any] = None,
550) -> dict[str, Any]:
551 """Lyrics, cover and genre the same way a finished download would.
553 Files stay in place. When the tree is writable, cover and genre go
554 through the library-upgrade staging copy. When it is read-only, the
555 cover is stored under ``/data/cover_cache`` and genre in the library
556 metadata cache. Lyrics are written afterwards (sidecar always; tags
557 only when the audio is writable).
558 """
560 done: dict[str, Any] = {
561 'lyrics': False,
562 'artwork': False,
563 'genre': False,
564 'error': '',
565 'lyrics_missing': False,
566 }
567 full = resolve_library_file(stored, ctx)
568 if full is None:
569 done['error'] = 'missing_file'
570 return done
572 entry, cache = _row_for_import(stored, ctx, full)
573 song = _song_for_import(entry)
574 if not str(song.get('name') or '').strip():
575 done['error'] = 'no_title'
576 return done
578 sidecar_state = lyrics_mod.relocate_lrc_sidecar(full)
579 new_lyrics, lyrics_missing = _lyrics_for_import(
580 full, song, settings, lyrics_cache
581 )
582 done['lyrics_missing'] = lyrics_missing
583 if sidecar_state == 'copied' and new_lyrics is None:
584 done['lyrics'] = True
585 writable = lyrics_mod.can_mutate_audio(full)
586 artwork = _cover_for_import(song, full, entry, settings)
587 genre = _genre_for_import(song)
588 if genre:
589 song = {**song, 'genre': genre}
590 if new_lyrics is None and artwork is None and not genre:
591 return done
593 overlay: dict[str, Any] = {}
594 if writable:
595 tagged_art, tagged_genre, tag_error = _write_import_tags(
596 full, song, artwork, genre
597 )
598 done['artwork'] = tagged_art
599 done['genre'] = tagged_genre
600 if tag_error:
601 done['error'] = tag_error
602 else:
603 if artwork is not None and artwork.data and cover_cache is not None:
604 cover_cache.store(stored, full, artwork.data, 'image/jpeg')
605 done['artwork'] = True
606 overlay['has_cover'] = True
607 overlay['cover_px'] = artwork.px or image_short_side(artwork.data)
608 if genre:
609 done['genre'] = True
610 overlay['genre'] = genre
611 if new_lyrics is not None:
612 if _write_import_lyrics(full, new_lyrics):
613 done['lyrics'] = True
614 done['lyrics_missing'] = False
615 else:
616 done['error'] = 'lyrics'
617 if cache is not None:
618 try:
619 cache.refresh(stored, full)
620 if overlay:
621 cache.merge_fields(stored, full, overlay)
622 except Exception:
623 logger.debug('External sync: metadata cache refresh failed')
624 return done
627def _enrich_imported_tracks(
628 extra_entries: list[dict[str, Any]],
629 ctx: Any,
630 *,
631 settings: dict[str, Any],
632 lyrics_cache: Optional[Any] = None,
633 cover_cache: Optional[Any] = None,
634 delay_seconds: float = 0.0,
635 on_progress: Optional[Callable[[int, int, str], None]] = None,
636) -> tuple[dict[str, int], dict[str, dict[str, Any]]]:
637 totals = {'lyrics': 0, 'artwork': 0, 'genre': 0}
638 by_file: dict[str, dict[str, Any]] = {}
639 if not extra_entries:
640 return totals, by_file
642 def _one(entry: dict[str, Any]) -> tuple[str, dict[str, Any]]:
643 stored = str(entry.get('file') or '')
644 try:
645 return stored, enrich_imported_track(
646 stored,
647 ctx,
648 settings=settings,
649 lyrics_cache=lyrics_cache,
650 cover_cache=cover_cache,
651 )
652 except Exception:
653 logger.opt(exception=True).debug(
654 'External sync: enrich worker failed'
655 )
656 return stored, {
657 'lyrics': False,
658 'artwork': False,
659 'genre': False,
660 'error': 'enrich',
661 'lyrics_missing': False,
662 }
664 def _record(stored: str, result: dict[str, Any], done: int) -> None:
665 by_file[stored] = result
666 for key in totals:
667 if result.get(key):
668 totals[key] += 1
669 if on_progress is not None:
670 on_progress(done, len(extra_entries), stored)
672 delay = max(0.0, float(delay_seconds or 0))
673 workers = _enrich_workers(settings)
674 done = 0
675 if delay <= 0:
676 with ThreadPoolExecutor(max_workers=workers) as pool:
677 futures = [pool.submit(_one, item) for item in extra_entries]
678 for future in as_completed(futures):
679 stored, result = _enrich_future_result(future)
680 done += 1
681 _record(stored, result, done)
682 return totals, by_file
684 with ThreadPoolExecutor(max_workers=workers) as pool:
685 for start in range(0, len(extra_entries), workers):
686 if start:
687 time.sleep(delay)
688 batch = extra_entries[start : start + workers]
689 futures = [pool.submit(_one, item) for item in batch]
690 for future in as_completed(futures):
691 stored, result = _enrich_future_result(future)
692 done += 1
693 _record(stored, result, done)
694 return totals, by_file
697def _enrich_workers(settings: dict[str, Any]) -> int:
698 try:
699 workers = int(settings.get('max_parallel_downloads') or 3)
700 except (TypeError, ValueError):
701 workers = 3
702 return max(1, min(workers, _MAX_ENRICH_WORKERS))
705def _enrich_future_result(
706 future: Future[tuple[str, dict[str, Any]]],
707) -> tuple[str, dict[str, Any]]:
708 try:
709 return future.result()
710 except Exception:
711 logger.opt(exception=True).debug('External sync: enrich worker failed')
712 return '', {
713 'lyrics': False,
714 'artwork': False,
715 'genre': False,
716 'error': 'enrich',
717 'lyrics_missing': False,
718 }
721def count_audio_files(root: Path, extensions: frozenset[str]) -> int:
722 if not root.is_dir():
723 return 0
724 total = 0
725 for path in root.rglob('*'):
726 try:
727 if path.is_file() and path.suffix.lower() in extensions:
728 total += 1
729 except OSError:
730 continue
731 return total
734def _match_extra_artists(
735 extra_entries: list[dict[str, Any]],
736 owned_entries: list[dict[str, Any]],
737) -> tuple[int, list[str]]:
738 catalog = _catalog_from_owned(owned_entries)
739 matched = 0
740 new_names: list[str] = []
741 seen_new: set[str] = set()
742 for item in extra_entries:
743 primary = _primary_artist(item)
744 if not primary:
745 continue
746 if match_artist(primary, catalog) is not None:
747 matched += 1
748 continue
749 key = artist_match_key(primary)
750 if key and key not in seen_new:
751 seen_new.add(key)
752 new_names.append(primary)
753 return matched, new_names
756def _queue_new_artist_profiles(
757 download_dir: Path,
758 new_names: list[str],
759 lang: str,
760 image_kinds: tuple[str, ...],
761) -> int:
762 queued = 0
763 for name in new_names:
764 song = {'album_artist': name, 'artists': [name]}
765 try:
766 if profile_seed_enqueue(download_dir, song, lang, image_kinds):
767 queued += 1
768 except Exception:
769 logger.opt(exception=True).debug(
770 'Could not queue artist profile for {!r}', name
771 )
772 return queued
775def _log_track(
776 status: str, entry: dict[str, Any], **fields: Any
777) -> dict[str, Any]:
778 artist = str(
779 entry.get('album_artist') or entry.get('artist') or ''
780 ).strip()
781 row = {
782 'status': status,
783 'title': str(entry.get('title') or '').strip(),
784 'artist': artist,
785 'file': str(entry.get('file') or ''),
786 }
787 row.update(fields)
788 return row
791def _build_sync_log(
792 missing: list[str],
793 skipped: list[tuple[dict[str, Any], str]],
794 kept: list[dict[str, Any]],
795 by_file: dict[str, dict[str, Any]],
796) -> list[dict[str, Any]]:
797 log: list[dict[str, Any]] = []
798 for path in missing:
799 log.append({
800 'status': 'missing_folder',
801 'title': '',
802 'artist': '',
803 'file': path,
804 })
805 for entry, reason in skipped:
806 log.append(_log_track(reason, entry))
807 for entry in kept:
808 stored = str(entry.get('file') or '')
809 info = by_file.get(stored) or {}
810 error = str(info.get('error') or '')
811 log.append(
812 _log_track(
813 'error' if error else 'imported',
814 entry,
815 error=error,
816 lyrics=bool(info.get('lyrics')),
817 cover=bool(info.get('artwork')),
818 genre=bool(info.get('genre')),
819 lyrics_missing=bool(info.get('lyrics_missing')),
820 )
821 )
822 return log
825def sync_external_library(
826 ctx: Any,
827 *,
828 download_dir: Path,
829 settings: dict[str, Any],
830 lang: str = 'en',
831 image_kinds: tuple[str, ...] = (),
832 lyrics_cache: Optional[Any] = None,
833 cover_cache: Optional[Any] = None,
834 on_progress: Optional[Callable[[int, int, str], None]] = None,
835) -> dict[str, Any]:
836 """Rescan extra folders, tag like a download, seed artist profiles."""
838 invalidate_library_paths_cache()
839 cfg = effective_external_library(settings)
840 missing = missing_external_folders(settings)
841 scanned = sum(
842 count_audio_files(root, AUDIO_EXTENSIONS) for root in ctx.extra_dirs
843 )
844 raw = list_library_entries(ctx, fold_extra=False)
845 owned_entries, extra_entries, skipped = partition_extra_entries(raw)
846 matched, new_names = _match_extra_artists(extra_entries, owned_entries)
847 try:
848 delay = float(settings.get('external_sync_delay_seconds') or 0)
849 except (TypeError, ValueError):
850 delay = 0.0
851 if on_progress is not None:
852 on_progress(0, len(extra_entries), '')
853 enriched, by_file = _enrich_imported_tracks(
854 extra_entries,
855 ctx,
856 settings=settings,
857 lyrics_cache=lyrics_cache,
858 cover_cache=cover_cache,
859 delay_seconds=delay,
860 on_progress=on_progress,
861 )
862 queued = _queue_new_artist_profiles(
863 download_dir, new_names, lang, image_kinds
864 )
865 log = _build_sync_log(missing, skipped, extra_entries, by_file)
866 errors = sum(1 for item in log if item.get('status') == 'error')
867 logger.info(
868 'External library sync: scanned={} added={} lyrics={} missing={}',
869 scanned,
870 len(extra_entries),
871 enriched['lyrics'],
872 len(missing),
873 )
874 return {
875 'folders': list(cfg['folders']),
876 'folder_count': len(cfg['folders']),
877 'missing': missing,
878 'scanned': scanned,
879 'added': len(extra_entries),
880 'skipped_duplicates': len(skipped),
881 'matched_artists': matched,
882 'new_artists': len(new_names),
883 'profiles_queued': queued,
884 'lyrics_embedded': enriched['lyrics'],
885 'covers_fetched': enriched['artwork'],
886 'genre_tagged': enriched['genre'],
887 'errors': errors,
888 'log': log,
889 }