Coverage for downtify/track_tag_match.py: 83%
303 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"""Compare Spotify playlist metadata to on-disk audio tags (mutagen)."""
3from __future__ import annotations
5import re
6import unicodedata
7from functools import lru_cache
8from pathlib import Path
9from typing import Any, Optional
11from loguru import logger
12from mutagen import File as MutagenFile
14from .library_metadata import read_audio_metadata
16_DEFAULT_DURATION_TOLERANCE_SECONDS = 10
17_DEFAULT_DURATION_TOLERANCE_PERCENT = 15
18_DEFAULT_MIX_DURATION_TOLERANCE_PERCENT = 50
19_MAX_WHEN_SPOTIFY_DURATION_UNKNOWN = 600
20_WRONG_MATCH_TITLE_KEYWORDS = (
21 'audiobook',
22 'audio book',
23 'audiolibro',
24 'unabridged',
25 'abridged',
26 'narrated by',
27 'read by',
28 'full book',
29 'ebook',
30 'e-book',
31 'chapter 1',
32 'chapter 2',
33 'chapitre',
34 'podcast',
35 'spoken word',
36 'complete book',
37 ' hour ',
38 ' hours ',
39 ' hrs ',
40 ' part 1 of',
41 ' part 2 of',
42 '1 hour',
43 '2 hour',
44)
46# Variant modifiers (live, remix, karaoke, …) shared by YouTube and slskd.
47# Use word-boundary-ish patterns for short tokens (live, remix) to avoid
48# false positives inside unrelated words (e.g. "Oliver", "deliver").
49_UNWANTED_REMOTE_VARIANT_KEYWORDS = (
50 'karaoke',
51 'instrumental',
52 'acapella',
53 'a cappella',
54 'cover ',
55 'cover)',
56 'tribute',
57 'guitar lesson',
58 'sped up',
59 'slowed',
60 'reverb',
61 'nightcore',
62 '8d audio',
63 'bass boosted',
64 ' remix',
65 '(remix',
66 'remix)',
67 'extended',
68 ' clean',
69 'clean version',
70 ' live',
71 '- live',
72 '(live',
73 'live)',
74 'live version',
75 'live at',
76 'live from',
77)
80_NON_WORD = re.compile(r'[\W_]+')
83def _spaced_words(text: str) -> str:
84 """*text* as its words between single spaces, padded (`` a b ``)."""
86 words = ' '.join(part for part in _NON_WORD.split(text) if part)
87 return f' {words} '
90# Each modifier as its words, worked out once (`` remix ``, `` live at ``).
91_VARIANT_KEYWORD_WORDS = {
92 kw: _spaced_words(kw) for kw in _UNWANTED_REMOTE_VARIANT_KEYWORDS
93}
96def remote_adds_unwanted_variant(
97 spotify_title: str,
98 remote_text: str,
99 *,
100 spotify_artists: Optional[list[str]] = None,
101 skip_keywords: Optional[frozenset[str]] = None,
102) -> bool:
103 """True when *remote_text* adds a variant modifier absent from Spotify."""
105 artists = ' '.join(
106 str(a).strip() for a in (spotify_artists or []) if str(a).strip()
107 )
108 spotify_blob = f'{spotify_title or ""} {artists}'.casefold()
109 remote_l = str(remote_text or '').casefold()
110 skip = skip_keywords or frozenset()
111 spotify_words = ''
112 for kw in _UNWANTED_REMOTE_VARIANT_KEYWORDS:
113 if kw in skip or kw not in remote_l or kw in spotify_blob:
114 continue
115 # Spotify's own words, so "Song - Remix" allows a "Song (Remix)"
116 # file: a modifier counts as Spotify's when its words are, whatever
117 # the punctuation around them. Only worked out when needed.
118 spotify_words = spotify_words or _spaced_words(spotify_blob)
119 if _VARIANT_KEYWORD_WORDS[kw] not in spotify_words:
120 return True
121 return False
124def _remote_adds_spam_keyword(spotify_title: str, remote_text: str) -> bool:
125 remote_l = str(remote_text or '').casefold()
126 if not remote_l:
127 return False
128 title_l = str(spotify_title or '').casefold()
129 return any(
130 kw in remote_l and kw not in title_l
131 for kw in _WRONG_MATCH_TITLE_KEYWORDS
132 )
135def remote_text_unacceptable(
136 spotify_title: str,
137 remote_text: str,
138 *,
139 spotify_artists: Optional[list[str]] = None,
140 skip_variant_keywords: Optional[frozenset[str]] = None,
141) -> bool:
142 """True when *remote_text* adds spam or variant modifiers absent from Spotify."""
144 if _remote_adds_spam_keyword(spotify_title, remote_text):
145 return True
146 return remote_adds_unwanted_variant(
147 spotify_title,
148 remote_text,
149 spotify_artists=spotify_artists,
150 skip_keywords=skip_variant_keywords,
151 )
154def youtube_title_has_negative_keyword(
155 spotify_title: str, candidate_title: str
156) -> bool:
157 """Variant-only check (audiobook/spam uses :func:`remote_text_unacceptable`)."""
159 return remote_adds_unwanted_variant(spotify_title, candidate_title)
162_MIX_SUFFIX_RE = re.compile(
163 r'\s*[-–—]\s*(?:radio\s+(?:mix|edit)|extended\s+mix|club\s+mix|'
164 r'original\s+mix|clean\s+version|explicit\s+version|remix)\s*$',
165 re.IGNORECASE,
166)
169_MIX_VARIANT_MARKERS = (
170 'extended mix',
171 'radio mix',
172 'radio edit',
173 'club mix',
174 'original mix',
175)
177MIX_VARIANT_REMOTE_SKIP_KEYWORDS = frozenset({'extended'})
180def strip_mix_suffix(title: str) -> str:
181 """Drop trailing mix/edit suffixes for broader audio search queries."""
183 return _MIX_SUFFIX_RE.sub('', str(title or '').strip()).strip()
186def candidate_adds_mix_variant(
187 spotify_title: str, candidate_title: str
188) -> bool:
189 """True when *candidate_title* adds a mix/edit label absent from Spotify."""
191 spotify_l = str(spotify_title or '').casefold()
192 cand_l = str(candidate_title or '').casefold()
193 return any(
194 marker in cand_l and marker not in spotify_l
195 for marker in _MIX_VARIANT_MARKERS
196 )
199def mix_variant_remote_skip_keywords(
200 spotify_title: str,
201 remote_text: str,
202) -> Optional[frozenset[str]]:
203 """Allow ``extended`` in remote titles when probing mix-variant uploads."""
205 if candidate_adds_mix_variant(spotify_title, remote_text):
206 return MIX_VARIANT_REMOTE_SKIP_KEYWORDS
207 return None
210def youtube_probe_title_matches(
211 song: dict[str, Any], probe_title: str
212) -> bool:
213 """Loose title check for YouTube downloads (probe metadata, not file tags)."""
215 text = str(probe_title or '').strip()
216 if not text:
217 return True
218 if remote_title_unacceptable(song, text):
219 return False
220 spotify_title = str(song.get('name') or '').strip()
221 if not spotify_title:
222 return True
223 if _titles_align(spotify_title, text):
224 return True
225 if _titles_align(strip_mix_suffix(spotify_title), text):
226 return True
227 probe_n = _normalize_tag_loose(text)
228 title_tokens = [
229 token
230 for token in _normalize_tag_loose(spotify_title).split()
231 if len(token) >= 3
232 ]
233 if not title_tokens:
234 return False
235 hits = sum(1 for token in title_tokens if token in probe_n)
236 if hits < max(1, len(title_tokens) // 2):
237 return False
238 artists = song.get('artists') or []
239 if not artists:
240 return True
241 return any(
242 _normalize_tag_loose(str(artist)) in probe_n for artist in artists
243 )
246def fold_accents(text: str) -> str:
247 """*text* without accents: ``Tití Me Preguntó`` -> ``Titi Me Pregunto``
248 (a file name often drops them)."""
250 if text.isascii():
251 return text
252 decomposed = unicodedata.normalize('NFKD', text)
253 return ''.join(ch for ch in decomposed if not unicodedata.combining(ch))
256def plain_name(text: str) -> str:
257 """*text* spelled the way file names usually spell it: symbols inside a
258 word read as the letter they stand for and the rest dropped - ``P!nk``
259 -> ``Pink``, ``A$AP Rocky`` -> ``ASAP Rocky``, ``$uicideboy$`` ->
260 ``Suicideboys``, ``AC/DC`` -> ``ACDC``, ``N.W.A.`` -> ``NWA``,
261 ``JAŸ-Z`` -> ``JAY Z`` (no accents; a hyphen splits words)."""
263 words = []
264 for raw in fold_accents(str(text or '')).replace('-', ' ').split():
265 word = re.sub(r'(?<=[^\W\d_])!(?=[^\W\d_])', 'i', raw)
266 word = re.sub(r'(?<=[^\W\d_])@(?=[^\W\d_])', 'a', word)
267 word = re.sub(r'\$(?=[^\W\d_])|(?<=[^\W\d_])\$', 's', word)
268 word = re.sub(r'[^\w]+', '', word)
269 if word:
270 words.append(word)
271 return ' '.join(words)
274def _normalize_tag(text: str) -> str:
275 return unicodedata.normalize('NFC', str(text or '').strip()).casefold()
278def _normalize_tag_loose(text: str) -> str:
279 text = _normalize_tag(text)
280 text = text.replace("'", '').replace('’', '').replace('‛', '')
281 text = re.sub(r'[^\w\s]', ' ', text)
282 return re.sub(r'\s+', ' ', text).strip()
285def _titles_align(expected: str, from_file: str) -> bool:
286 title_n = _normalize_tag_loose(expected)
287 file_title_n = _normalize_tag_loose(from_file)
288 if not title_n or not file_title_n:
289 return True
290 if (
291 title_n == file_title_n
292 or title_n in file_title_n
293 or file_title_n in title_n
294 ):
295 return True
296 # The song's own name in both, word for word, however each spells the
297 # rest: "Despacito - Remix" / "Despacito (Official Remix)", "Shook Ones,
298 # Pt. II" / "Shook Ones Part 2", "Tití Me Preguntó" / "Titi Me Pregunto".
299 expected_words = _title_words(expected, core=True)
300 file_words = _title_words(from_file, core=True)
301 if not expected_words or not file_words:
302 return False
303 return _words_within(expected_words, _title_words(from_file)) or (
304 _words_within(file_words, _title_words(expected))
305 )
308def _words_within(words: list[str], others: list[str]) -> bool:
309 """Whether every word of *words* is among *others*; a censored word
310 (``f*kin``) stands for any word it could be (``fuckin``, or ``fkin``
311 when the stars were just dropped)."""
313 pool = set(others)
314 for word in words:
315 if '*' in word:
316 pattern = re.compile(
317 r'\w{0,4}'.join(re.escape(p) for p in word.split('*')) + '$'
318 )
319 if not any(pattern.match(other) for other in pool):
320 return False
321 elif word not in pool:
322 return False
323 return True
326_TAG_CREDIT = re.compile(
327 r'\s*[\(\[]\s*(?:feat\.?|ft\.?|featuring|with|from|official)\b[^\)\]]*[\)\]]'
328 r'|\s+(?:feat\.?|ft\.?|featuring)\s.*$',
329 re.IGNORECASE,
330)
331_TAG_PART = re.compile(
332 r'\b(?:pt|part|vol|volume)\b\.?\s*([ivx]+|\d+)\b', re.IGNORECASE
333)
334_TAG_ROMAN = {
335 'i': '1',
336 'ii': '2',
337 'iii': '3',
338 'iv': '4',
339 'v': '5',
340 'vi': '6',
341 'vii': '7',
342 'viii': '8',
343 'ix': '9',
344 'x': '10',
345}
348_CENSORED_RUN = re.compile(r'(?<=[^\W\d_])\*+')
349_TITLE_SPLIT = re.compile(r'(?:[^\w\x00]|_)+')
352@lru_cache(maxsize=4096)
353def _title_words(text: str, *, core: bool = False) -> tuple[str, ...]:
354 """*text*'s words for comparing titles: no accents, case, apostrophes,
355 ``&``/``and``, censored words (``F**kin'``), and ``Part II`` as
356 ``pt 2``. With *core*, only the song's own name: no ``(feat. …)``,
357 ``(from …)`` or `` - …`` part. Remembered per title: a playlist
358 compares the same titles over and over."""
360 value = fold_accents(str(text or ''))
361 if core:
362 head = value.split(' - ', 1)[0]
363 value = _TAG_CREDIT.sub('', head) or head
364 value = value.casefold().replace("'", '').replace('\u2019', '')
365 # A censored word ("F**kin'") stays one word, its hidden letters one
366 # "*", matched against the spelled-out word (_words_within).
367 value = _CENSORED_RUN.sub('\x00', value)
368 value = _TAG_PART.sub(
369 lambda m: f' pt {_TAG_ROMAN.get(m.group(1).casefold(), m.group(1))} ',
370 value,
371 )
372 words = _TITLE_SPLIT.split(value)
373 return tuple(w.replace('\x00', '*') for w in words if w and w != 'and')
376def _artist_key(text: str) -> str:
377 """An artist as tags are compared: letters only, no accents, symbols
378 spelled out (``P!nk`` -> ``pink``), no leading "The" or ``&``/``and``."""
380 value = plain_name(text).casefold()
381 value = re.sub(r'^the\s+', '', value)
382 return ''.join(w for w in re.split(r'[\W_]+', value) if w and w != 'and')
385def _artist_lists_align(expected: list[str], actual: list[str]) -> bool:
386 if not expected:
387 return True
388 if not actual:
389 return True
390 for exp in expected:
391 exp_n = _normalize_tag_loose(exp)
392 if not exp_n:
393 continue
394 for act in actual:
395 act_n = _normalize_tag_loose(act)
396 if exp_n in act_n or act_n in exp_n:
397 return True
398 # Spelled differently: "P!nk" / "Pink", "Mötley Crüe" / "Motley Crue",
399 # "The Weeknd" / "Weeknd", "Daryl Hall & John Oates" / "Hall & Oates".
400 for exp in expected:
401 exp_k = _artist_key(exp)
402 exp_words = {
403 w
404 for w in re.split(r'[\W_]+', fold_accents(exp).casefold())
405 if len(w) >= 4
406 }
407 for act in actual:
408 act_k = _artist_key(act)
409 if exp_k and act_k and (exp_k in act_k or act_k in exp_k):
410 return True
411 act_words = {
412 w
413 for w in re.split(r'[\W_]+', fold_accents(act).casefold())
414 if len(w) >= 4
415 }
416 # Every name word of one in the other ("Hall & Oates").
417 if (
418 act_words
419 and exp_words
420 and (act_words <= exp_words or exp_words <= act_words)
421 ):
422 return True
423 return False
426def song_duration_seconds(song: dict[str, Any]) -> int:
427 target_duration = int(song.get('duration') or 0)
428 if target_duration > 1000:
429 return target_duration // 1000
430 return target_duration
433def _clamp_int(value: Any, default: int, *, minimum: int, maximum: int) -> int:
434 try:
435 parsed = int(value)
436 except (TypeError, ValueError):
437 parsed = default
438 return min(maximum, max(minimum, parsed))
441def duration_tolerances_from_settings(
442 settings: Optional[dict[str, Any]] = None,
443) -> dict[str, int]:
444 """Read slskd duration tolerance knobs (defaults: 10s, 15%%, 50%% mix)."""
446 raw = settings if isinstance(settings, dict) else {}
447 return {
448 'seconds': _clamp_int(
449 raw.get('duration_tolerance_seconds'),
450 _DEFAULT_DURATION_TOLERANCE_SECONDS,
451 minimum=1,
452 maximum=120,
453 ),
454 'percent': _clamp_int(
455 raw.get('duration_tolerance_percent'),
456 _DEFAULT_DURATION_TOLERANCE_PERCENT,
457 minimum=1,
458 maximum=100,
459 ),
460 'mix_percent': _clamp_int(
461 raw.get('mix_duration_tolerance_percent'),
462 _DEFAULT_MIX_DURATION_TOLERANCE_PERCENT,
463 minimum=1,
464 maximum=200,
465 ),
466 }
469def media_duration_matches_song(
470 song: dict[str, Any],
471 media_seconds: int,
472 *,
473 tolerance_seconds: int = _DEFAULT_DURATION_TOLERANCE_SECONDS,
474 tolerance_percent: int = _DEFAULT_DURATION_TOLERANCE_PERCENT,
475) -> bool:
476 """Align with slskd: reject audiobooks and hour-long wrong matches."""
478 if media_seconds <= 0:
479 return True
480 target = song_duration_seconds(song)
481 if not target:
482 return media_seconds <= _MAX_WHEN_SPOTIFY_DURATION_UNKNOWN
483 delta = abs(media_seconds - target)
484 if delta <= tolerance_seconds:
485 return True
486 cap = max(45, int(target * tolerance_percent / 100))
487 if media_seconds > target + cap:
488 return False
489 if media_seconds < max(20, int(target * 0.5)) and target >= 60:
490 return False
491 return delta <= cap
494def media_duration_matches_mix_variant(
495 song: dict[str, Any],
496 media_seconds: int,
497 *,
498 tolerance_percent: int = _DEFAULT_MIX_DURATION_TOLERANCE_PERCENT,
499 normal_tolerance_seconds: int = _DEFAULT_DURATION_TOLERANCE_SECONDS,
500 normal_tolerance_percent: int = _DEFAULT_DURATION_TOLERANCE_PERCENT,
501) -> bool:
502 """Looser runtime bounds for extended/radio/club mix last-resort matches."""
504 if media_duration_matches_song(
505 song,
506 media_seconds,
507 tolerance_seconds=normal_tolerance_seconds,
508 tolerance_percent=normal_tolerance_percent,
509 ):
510 return True
511 if media_seconds <= 0:
512 return True
513 target = song_duration_seconds(song)
514 if not target:
515 return media_seconds <= _MAX_WHEN_SPOTIFY_DURATION_UNKNOWN
516 if media_seconds > max(720, int(target * 2.5)):
517 return False
518 if media_seconds > int(target * 1.85) + 30:
519 return False
520 if media_seconds < max(20, int(target * 0.35)) and target >= 60:
521 return False
522 return abs(media_seconds - target) <= max(
523 90, int(target * tolerance_percent / 100)
524 )
527def duration_matches_song(song: dict[str, Any], media_seconds: int) -> bool:
528 """Alias used by YouTube pre-download checks."""
530 return media_duration_matches_song(song, media_seconds)
533def remote_title_unacceptable(song: dict[str, Any], remote_title: str) -> bool:
534 """True when a YouTube/Soulseek title looks like audiobook/podcast spam."""
536 spotify_title = str(song.get('name') or '')
537 return remote_text_unacceptable(
538 spotify_title,
539 remote_title,
540 spotify_artists=[
541 str(a).strip()
542 for a in (song.get('artists') or [])
543 if str(a).strip()
544 ],
545 skip_variant_keywords=mix_variant_remote_skip_keywords(
546 spotify_title,
547 remote_title,
548 ),
549 )
552def audio_file_length_seconds(path: Path) -> int:
553 try:
554 audio = MutagenFile(str(path))
555 except Exception:
556 return 0
557 if audio is None or not getattr(audio, 'info', None):
558 return 0
559 try:
560 return int(getattr(audio.info, 'length', 0) or 0)
561 except (TypeError, ValueError):
562 return 0
565def snapshot_spotify_metadata(song: dict[str, Any]) -> dict[str, Any]:
566 """Preserve the Spotify row before mutagen or slskd paths overwrite fields."""
568 row = dict(song)
569 if not row.get('spotify_name'):
570 row['spotify_name'] = str(row.get('name') or '').strip()
571 if not row.get('spotify_artists'):
572 row['spotify_artists'] = [
573 str(a).strip()
574 for a in (row.get('artists') or [])
575 if str(a).strip()
576 ]
577 return row
580def spotify_expected(song: dict[str, Any]) -> tuple[str, list[str]]:
581 title = str(song.get('spotify_name') or '').strip()
582 artists = [
583 str(a).strip()
584 for a in (song.get('spotify_artists') or [])
585 if str(a).strip()
586 ]
587 return title, artists
590def spotify_aligns_with_file_tags(song: dict[str, Any]) -> bool:
591 """False when embedded tags clearly disagree with the Spotify playlist row."""
593 if not song.get('library_from_tags'):
594 return True
596 spotify_title, spotify_artists = spotify_expected(song)
597 if not spotify_title:
598 return True
600 file_title = str(song.get('name') or '').strip()
601 file_artists = [
602 str(a).strip() for a in (song.get('artists') or []) if str(a).strip()
603 ]
604 if not file_title:
605 return True
606 if not _titles_align(spotify_title, file_title):
607 return False
608 return _artist_lists_align(spotify_artists, file_artists)
611def spotify_file_tag_mismatch_label(song: dict[str, Any]) -> str:
612 spotify_title, spotify_artists = spotify_expected(song)
613 file_title = str(song.get('name') or 'unknown')
614 file_artists = song.get('artists') or []
615 exp = spotify_title or 'unknown'
616 if spotify_artists:
617 exp = f'{", ".join(spotify_artists)} - {exp}'
618 file = file_title
619 if file_artists:
620 file = f'{", ".join(str(a) for a in file_artists)} - {file}'
621 return f'spotify={exp!r} tags={file!r}'
624def verify_downloaded_file_matches_spotify(
625 path: Path, song: dict[str, Any]
626) -> bool:
627 """Read mutagen tags on *path* and compare to snapshot Spotify metadata."""
629 meta = read_audio_metadata(path)
630 if not meta.get('title') and not meta.get('artists'):
631 logger.info(
632 'slskd: skip tag verify (no embedded tags) file={!r}',
633 path.name,
634 )
635 return True
637 row = snapshot_spotify_metadata(song)
638 if meta.get('title'):
639 row['name'] = meta['title']
640 if meta.get('artists'):
641 row['artists'] = meta['artists']
642 row['library_from_tags'] = True
643 return spotify_aligns_with_file_tags(row)
646def verify_downloaded_audio_file(path: Path, song: dict[str, Any]) -> bool:
647 """Tags and runtime must match the Spotify row (post-download guard)."""
649 length = audio_file_length_seconds(path)
650 if length > 0:
651 meta = read_audio_metadata(path)
652 file_title = str(meta.get('title') or path.stem)
653 spotify_title = str(song.get('spotify_name') or song.get('name') or '')
654 duration_ok = (
655 media_duration_matches_mix_variant(song, length)
656 if candidate_adds_mix_variant(spotify_title, file_title)
657 else media_duration_matches_song(song, length)
658 )
659 if not duration_ok:
660 logger.info(
661 'download verify: duration mismatch file={}s spotify~{}s file={!r}',
662 length,
663 song_duration_seconds(song),
664 path.name,
665 )
666 return False
667 return verify_downloaded_file_matches_spotify(path, song)
670def verify_youtube_download_file(
671 path: Path,
672 song: dict[str, Any],
673 *,
674 probe: Optional[dict[str, Any]] = None,
675) -> bool:
676 """Pre-tagging guard for yt-dlp files (duration + YouTube title, not mutagen)."""
678 length = audio_file_length_seconds(path)
679 probe_title = str((probe or {}).get('title') or '')
680 spotify_title = str(song.get('spotify_name') or song.get('name') or '')
681 if length > 0:
682 duration_ok = (
683 media_duration_matches_mix_variant(song, length)
684 if probe_title
685 and candidate_adds_mix_variant(spotify_title, probe_title)
686 else media_duration_matches_song(song, length)
687 )
688 if not duration_ok:
689 logger.info(
690 'download verify: duration mismatch file={}s spotify~{}s file={!r}',
691 length,
692 song_duration_seconds(song),
693 path.name,
694 )
695 return False
696 if probe is None:
697 return True
698 if youtube_probe_title_matches(song, probe_title):
699 return True
700 logger.info(
701 'download verify: YouTube title mismatch probe={!r} spotify={!r}',
702 probe_title[:120],
703 spotify_title[:120],
704 )
705 return False