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

1"""Import audio that already lives outside Downtify's download folder. 

2 

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""" 

8 

9from __future__ import annotations 

10 

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 

19 

20from loguru import logger 

21 

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 

44 

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) 

59 

60 

61def is_external_stored(stored: str) -> bool: 

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

63 return text.startswith(EXTERNAL_LIBRARY_PREFIX) 

64 

65 

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('\\', '/') 

76 

77 

78def sanitize_external_folders(raw: Any) -> list[str]: 

79 """Absolute paths, unique, capped — empty / relative entries dropped.""" 

80 

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 

104 

105 

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 

116 

117 

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.""" 

124 

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) 

152 

153 

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 

160 

161 

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() 

166 

167 

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()) 

173 

174 

175def _compact_key(name: str) -> str: 

176 return artist_match_key(name).replace(' ', '') 

177 

178 

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()) 

186 

187 

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 

199 

200 

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)}' 

207 

208 

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 

218 

219 

220def match_artist(name: str, catalog: list[str]) -> Optional[str]: 

221 """Return a catalog name when *name* is the same artist, else ``None``.""" 

222 

223 return _ArtistMatcher(catalog).match(name) 

224 

225 

226class _ArtistMatcher: 

227 """Prepared names and per-fold results, including unmatched artists. 

228 

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 """ 

233 

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]] = {} 

239 

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] 

244 

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 

269 

270 

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 

284 

285 

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 

296 

297 

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 

313 

314 

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. 

323 

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 """ 

328 

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, [], [] 

338 

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) 

343 

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 

360 

361 

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. 

367 

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 """ 

372 

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 

383 

384 

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 

396 

397 

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 } 

423 

424 

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 

433 

434 

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)``. 

442 

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 """ 

447 

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 

473 

474 

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 

499 

500 

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 '' 

512 

513 

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), '' 

530 

531 

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 

541 

542 

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. 

552 

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 """ 

559 

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 

571 

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 

577 

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 

592 

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 

625 

626 

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 

641 

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 } 

663 

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) 

671 

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 

683 

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 

695 

696 

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)) 

703 

704 

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 } 

719 

720 

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 

732 

733 

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 

754 

755 

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 

773 

774 

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 

789 

790 

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 

823 

824 

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.""" 

837 

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 }