Coverage for downtify/library_songs.py: 89%
65 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"""The library's files by song, so an artist watch never downloads a
2song the library already holds under another name.
4An artist watch lists its releases on YouTube Music, while a playlist
5download is named from Spotify's metadata - and the two spell the same
6song differently: ``Way 2 Sexy (with Future & Young Thug)`` on Spotify
7is ``Way 2 Sexy (feat. Future & Young Thug)`` on YouTube Music, with
8``Future & Young Thug`` instead of ``Future, Young Thug`` in the
9artists. The file name the output template renders differs, so the
10name-based "already downloaded" check misses it and the song is fetched
11a second time. The same happens inside one artist's catalogue: a single
12that is also on the album, an album and its deluxe edition.
14A song here is :func:`downtify.library_catalog.song_key` - the first
15artist and the title, with ``(feat. …)`` / ``(with …)`` / remaster tags
16folded away - plus its length: two files of one key whose lengths
17differ by more than :data:`SAME_SONG_SECONDS` are different recordings
18(a live version, an extended mix) and are never taken for each other.
19A file or a track whose length is unknown never matches.
21Deezer adds a few more spellings of the very same recording: ``(Album
22Version)``, ``(Explicit Version)``, ``(Explicit)``, ``- Original Mix``
23and the like are folded away too (:data:`_SAME_RECORDING_TAG`). So is
24the film a soundtrack song comes from, which Indian labels add on one
25catalogue and not another: ``Tum Hi Ho (From "Aashiqui 2")`` is the
26``Tum Hi Ho`` MusicBrainz and Spotify list. Words that name another
27recording - ``Clean``, ``Radio Edit``, ``Live``, ``Remix`` - are kept,
28and the length must agree as well.
29"""
31from __future__ import annotations
33import re
34from collections import defaultdict
35from collections.abc import Iterable
36from pathlib import Path
37from typing import Any, Optional
39from .isrc import normalize as normalize_isrc
40from .library_catalog import song_key
41from .library_metadata import read_audio_metadata
42from .library_paths import SLSKD_LIBRARY_PREFIX
44#: Lengths (seconds) of one song in two sources differ by a second or
45#: two (encoder padding, rounding); a different recording by far more.
46SAME_SONG_SECONDS = 3.0
48#: Two files with one ISRC are the same recording; a length further off
49#: than this is a mislabelled one (an extended mix tagged with the
50#: single's code).
51ISRC_SECONDS = 10.0
53#: Title tags that name no other recording: the album's (explicit)
54#: version, or the film a song is from, as one catalogue spells it and
55#: another leaves out.
56_SAME_RECORDING_TAG = re.compile(
57 r'\s*(?:[([]\s*(?:album|explicit|original|lp)(?:\s+(?:version|mix))?\s*'
58 r'[)\]]|\s-\s(?:album|explicit|original|lp)\s+(?:version|mix)\s*$'
59 r'|[([]\s*from\s[^)\]]*[)\]])',
60 re.IGNORECASE,
61)
64def _length(value: Any) -> float:
65 try:
66 return max(0.0, float(value or 0))
67 except (TypeError, ValueError):
68 return 0.0
71def _key(artists: Any, title: Any) -> str:
72 if isinstance(artists, (list, tuple)):
73 first = str(artists[0]) if artists else ''
74 else:
75 first = str(artists or '')
76 key = song_key(first, _SAME_RECORDING_TAG.sub('', str(title or '')))
77 # Both halves are needed: a title alone matches too much.
78 return '' if key.startswith('|') or key.endswith('|') else key
81def same_recording(path: Path, song: dict[str, Any]) -> bool:
82 """Whether the file at *path* holds *song*: the same ISRC (a length
83 within :data:`ISRC_SECONDS`), else the same song key and a length
84 within :data:`SAME_SONG_SECONDS`, from the file's own tags."""
86 key = _key(song.get('artists'), song.get('name'))
87 length = _length(song.get('duration'))
88 code = normalize_isrc(song.get('isrc'))
89 if not code and (not key or length <= 0):
90 return False
91 try:
92 tags = read_audio_metadata(path)
93 except Exception:
94 return False
95 found = _length(tags.get('duration'))
96 if code and normalize_isrc(tags.get('isrc')) == code:
97 return not (found and length) or abs(found - length) <= ISRC_SECONDS
98 if not key or length <= 0:
99 return False
100 return (
101 found > 0
102 and abs(found - length) <= SAME_SONG_SECONDS
103 and _key(tags.get('artists') or tags.get('artist'), tags.get('title'))
104 == key
105 )
108class LibrarySongs:
109 """Library files by song (see the module docstring).
111 Built from library listing rows (``file``, ``artist``, ``title``,
112 ``duration``). :meth:`add` records a file downloaded meanwhile, so a
113 later release of the same sweep finds it too.
114 """
116 def __init__(self, rows: Iterable[dict[str, Any]] = ()) -> None:
117 self._songs: dict[str, list[tuple[str, float]]] = defaultdict(list)
118 self._isrcs: dict[str, list[tuple[str, float]]] = defaultdict(list)
119 for row in rows:
120 self._put(
121 str(row.get('file') or ''),
122 _key(row.get('artist'), row.get('title')),
123 _length(row.get('duration')),
124 row.get('isrc'),
125 )
127 def _put(self, name: str, key: str, length: float, isrc: Any = '') -> None:
128 name = name.strip().replace('\\', '/')
129 if name and key and length > 0:
130 self._songs[key].append((name, length))
131 code = normalize_isrc(isrc)
132 if name and code:
133 self._isrcs[code].append((name, length))
135 def add(self, filename: str, song: dict[str, Any]) -> None:
136 """Remember *filename* as holding *song*."""
138 self._put(
139 filename,
140 _key(song.get('artists'), song.get('name')),
141 _length(song.get('duration')),
142 song.get('isrc'),
143 )
145 def find(self, song: dict[str, Any]) -> Optional[str]:
146 """The library file already holding *song*, else ``None``.
148 The closest length wins; a file outside slskd's folder is
149 preferred over one in it.
150 """
152 length = _length(song.get('duration'))
153 # The recording's own code first: the same recording whatever the
154 # titles say (a length far off is another edit sharing a code).
155 by_code = [
156 (name.startswith(SLSKD_LIBRARY_PREFIX), abs(other - length), name)
157 for name, other in self._isrcs.get(
158 normalize_isrc(song.get('isrc')), ()
159 )
160 if not (length and other) or abs(other - length) <= ISRC_SECONDS
161 ]
162 if by_code:
163 return min(by_code)[2]
164 key = _key(song.get('artists'), song.get('name'))
165 if not key or length <= 0:
166 return None
167 close = [
168 (name.startswith(SLSKD_LIBRARY_PREFIX), abs(other - length), name)
169 for name, other in self._songs.get(key, ())
170 if abs(other - length) <= SAME_SONG_SECONDS
171 ]
172 return min(close)[2] if close else None