Coverage for downtify/compilation.py: 46%
200 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"""Marking a library album as a various-artists compilation by hand, and
2remembering the mark for the album's later downloads.
4Whether an album is a compilation comes from its source (see
5``album_artist.py``): only an album the source credits to "Various
6Artists" is one. A source can be wrong for a given release - a single
7credited to its first artist though four share it equally - so an admin
8can mark the album from its page, or unmark one the source got wrong the
9other way.
11Marking rewrites every track's album-artist tag to "Various Artists" and
12adds the compilation flag (``TCMP`` / ``COMPILATION`` / ``cpil``); unmarking
13puts the album artist back and removes the flag. Only those two tags
14change. Files stay where they are: "Organize by artist" files a
15compilation's track under its own first artist anyway
16(:func:`downtify.album_artist.filing_artist`), and media servers group
17albums by the tags. Each file is rewritten through a working copy that
18must still read as the same audio before it replaces the original, and
19keeps its modification time - as the library upgrade does.
21The mark is kept in :class:`CompilationMarks`, keyed by the album's title
22and the album artist it was downloaded with, so a track of the same album
23downloaded later gets the same tags (:meth:`CompilationMarks.override_for`,
24applied by the downloader).
25"""
27from __future__ import annotations
29import os
30import shutil
31from collections import Counter
32from dataclasses import dataclass, field
33from datetime import datetime, timezone
34from pathlib import Path
35from typing import Any, Optional
37from loguru import logger
38from mutagen import File as MutagenFile
39from mutagen.flac import FLAC
40from mutagen.id3 import ID3, TCMP, TPE2, ID3NoHeaderError
41from mutagen.mp4 import MP4
42from mutagen.oggopus import OggOpus
43from mutagen.oggvorbis import OggVorbis
45from .album_artist import VARIOUS_ARTISTS, is_various_artists
46from .db.config import Dialect
47from .db.core import Database, as_database
48from .file_naming import file_name_key
49from .library_metadata import read_audio_metadata
50from .library_upgrade import staging_path
52#: A rewritten file must still play for as long as the original did.
53_DURATION_TOLERANCE_SECONDS = 1.0
55#: The formats tagged with Vorbis comments, by extension.
56_VORBIS_READERS = {
57 'flac': FLAC,
58 'ogg': OggVorbis,
59 'oga': OggVorbis,
60 'opus': OggOpus,
61}
64class CompilationError(ValueError):
65 """The request can't be applied (no tracks, several albums, ...)."""
68class AlreadyInStateError(CompilationError):
69 """The files' tags are already what was asked: nothing to rewrite.
71 *result* is the album as the files say it is, so a caller whose own
72 view of them is stale (the Library's listing) can catch up with it.
73 """
75 def __init__(self, message: str, result: CompilationResult) -> None:
76 super().__init__(message)
77 self.result = result
80# ── The remembered marks ──────────────────────────────────────────────
81class CompilationMarks:
82 """Albums whose compilation status an admin set by hand.
84 One row per album, keyed by the album artist its tracks were
85 downloaded with and its title (both compared as
86 :func:`~downtify.file_naming.file_name_key`): ``compilation`` 1 with
87 ``album_artist`` "Various Artists" for a marked album, 0 with the
88 album artist to use instead for one unmarked against its source.
89 """
91 def __init__(self, db_path: str | Path | Database) -> None:
92 self.db = as_database(db_path, 'library')
93 if isinstance(db_path, Database):
94 self._path = str(self.db.path) if self.db.path else None
95 else:
96 self._path = str(db_path)
97 self._init_db()
99 def _connect(self):
100 return self.db.connect()
102 def _init_db(self) -> None:
103 # PostgreSQL gets its schema from the migrations.
104 if self.db.dialect is not Dialect.SQLITE:
105 return
106 with self._connect() as conn:
107 conn.execute("""
108 CREATE TABLE IF NOT EXISTS album_compilation_marks (
109 artist_key TEXT NOT NULL,
110 album_key TEXT NOT NULL,
111 artist TEXT NOT NULL,
112 album TEXT NOT NULL,
113 compilation INTEGER NOT NULL,
114 album_artist TEXT NOT NULL,
115 marked_at TEXT NOT NULL,
116 PRIMARY KEY (artist_key, album_key)
117 )
118 """)
120 def set(
121 self, artist: str, album: str, *, compilation: bool, album_artist: str
122 ) -> None:
123 with self._connect() as conn:
124 conn.execute(
125 """INSERT INTO album_compilation_marks
126 (artist_key, album_key, artist, album, compilation,
127 album_artist, marked_at)
128 VALUES (?, ?, ?, ?, ?, ?, ?)
129 ON CONFLICT(artist_key, album_key) DO UPDATE SET
130 artist = excluded.artist,
131 album = excluded.album,
132 compilation = excluded.compilation,
133 album_artist = excluded.album_artist,
134 marked_at = excluded.marked_at""",
135 (
136 file_name_key(artist),
137 file_name_key(album),
138 artist,
139 album,
140 1 if compilation else 0,
141 album_artist,
142 datetime.now(timezone.utc).isoformat(),
143 ),
144 )
146 def remove(self, artist: str, album: str) -> None:
147 with self._connect() as conn:
148 conn.execute(
149 """DELETE FROM album_compilation_marks
150 WHERE artist_key = ? AND album_key = ?""",
151 (file_name_key(artist), file_name_key(album)),
152 )
154 def marked_albums(self, album: str) -> list[dict[str, Any]]:
155 """The albums titled *album* marked as compilations by hand."""
157 with self._connect() as conn:
158 rows = conn.execute(
159 """SELECT artist, album, album_artist
160 FROM album_compilation_marks
161 WHERE album_key = ? AND compilation = 1
162 ORDER BY marked_at""",
163 (file_name_key(album),),
164 ).fetchall()
165 return [dict(row) for row in rows]
167 def override_for(self, song: dict[str, Any]) -> dict[str, Any]:
168 """``album_artist`` / ``compilation`` for a *song* about to be
169 downloaded, when its album was marked or unmarked by hand - else
170 ``{}``. The song is matched by the album artist its source gave it
171 (else its first artist) and its album title."""
173 album = str(song.get('album_name') or '').strip()
174 if not album:
175 return {}
176 artist = str(song.get('album_artist') or '').strip()
177 if not artist:
178 artists = song.get('artists') or []
179 artist = str(artists[0]).strip() if artists else ''
180 if song.get('compilation'):
181 artist = VARIOUS_ARTISTS
182 if not file_name_key(artist) or not file_name_key(album):
183 return {}
184 with self._connect() as conn:
185 row = conn.execute(
186 """SELECT compilation, album_artist
187 FROM album_compilation_marks
188 WHERE artist_key = ? AND album_key = ?""",
189 (file_name_key(artist), file_name_key(album)),
190 ).fetchone()
191 if row is None:
192 return {}
193 return {
194 'album_artist': str(row['album_artist']),
195 'compilation': bool(row['compilation']),
196 }
199# ── Rewriting the two tags ────────────────────────────────────────────
200def write_album_artist_tags(
201 path: Path, album_artist: str, *, compilation: bool
202) -> None:
203 """Set *path*'s album-artist tag (removed when blank) and add or
204 remove its compilation flag, leaving every other tag as it is - the
205 same frames/keys :func:`downtify.downloader.embed_metadata` writes."""
207 suffix = path.suffix.lower().lstrip('.')
208 if suffix == 'mp3':
209 try:
210 tags = ID3(str(path))
211 except ID3NoHeaderError:
212 tags = ID3()
213 tags.delall('TPE2')
214 tags.delall('TCMP')
215 if album_artist:
216 tags.add(TPE2(encoding=3, text=album_artist))
217 if compilation:
218 tags.add(TCMP(encoding=3, text='1'))
219 # v2.4, as embed_metadata saves (v2.3 corrupts UTF-8 frames).
220 tags.save(str(path), v2_version=4)
221 return
222 if suffix in {'m4a', 'mp4', 'aac'}:
223 audio = MP4(str(path))
224 for key in ('aART', 'cpil'):
225 audio.pop(key, None)
226 if album_artist:
227 audio['aART'] = [album_artist]
228 if compilation:
229 audio['cpil'] = True
230 audio.save()
231 return
232 reader = _VORBIS_READERS.get(suffix)
233 if reader is None:
234 raise CompilationError(f'Unsupported format: {path.suffix}')
235 audio = reader(str(path))
236 for key in ('albumartist', 'compilation'):
237 audio.pop(key, None)
238 if album_artist:
239 audio['albumartist'] = album_artist
240 if compilation:
241 audio['compilation'] = '1'
242 audio.save()
245def _length(path: Path) -> float:
246 try:
247 audio = MutagenFile(str(path))
248 except Exception:
249 return 0.0
250 info = getattr(audio, 'info', None)
251 return float(getattr(info, 'length', 0.0) or 0.0)
254def retag_file(path: Path, album_artist: str, *, compilation: bool) -> None:
255 """:func:`write_album_artist_tags` on a working copy of *path* that
256 must still be readable audio of the same length before it replaces
257 the original; keeps the original modification time. Raises when it
258 fails, leaving the original untouched."""
260 stat = path.stat()
261 expected = _length(path)
262 staged = staging_path(path)
263 shutil.copy2(str(path), str(staged))
264 try:
265 write_album_artist_tags(staged, album_artist, compilation=compilation)
266 length = _length(staged)
267 if length <= 0 or (
268 expected > 0
269 and abs(length - expected) > _DURATION_TOLERANCE_SECONDS
270 ):
271 raise CompilationError('The rewritten file did not verify')
272 os.replace(str(staged), str(path))
273 finally:
274 staged.unlink(missing_ok=True)
275 try:
276 os.utime(str(path), ns=(stat.st_atime_ns, stat.st_mtime_ns))
277 except OSError:
278 pass
281# ── Marking / unmarking an album ──────────────────────────────────────
282@dataclass
283class _Track:
284 stored_path: str
285 full: Path
286 album: str
287 album_artist: str
288 artists: list[str]
289 compilation: bool = False
291 @property
292 def credited_as(self) -> str:
293 """The album artist the Library shows it under: the tag, else its
294 first artist - and "Various Artists" only with the compilation
295 flag (``library_catalog.album_owner_of``)."""
297 first = self.artists[0] if self.artists else ''
298 if is_various_artists(self.album_artist) and not self.compilation:
299 return first
300 return self.album_artist or first
303@dataclass
304class CompilationResult:
305 album: str
306 album_artist: str
307 compilation: bool
308 changed: list[str] = field(default_factory=list)
309 failed: list[dict[str, str]] = field(default_factory=list)
312def _most_common(names: list[str]) -> str:
313 counts = Counter(name for name in names if name)
314 return counts.most_common(1)[0][0] if counts else ''
317def _read_tracks(files: list[tuple[str, Path]]) -> list[_Track]:
318 tracks = []
319 for stored_path, full in files:
320 meta = read_audio_metadata(full)
321 tracks.append(
322 _Track(
323 stored_path=stored_path,
324 full=full,
325 album=str(meta.get('album') or '').strip(),
326 album_artist=str(meta.get('album_artist') or '').strip(),
327 artists=[
328 str(a).strip()
329 for a in meta.get('artists') or []
330 if str(a).strip()
331 ],
332 compilation=bool(meta.get('compilation')),
333 )
334 )
335 return tracks
338def _restored_album_artist(
339 tracks: list[_Track], album: str, marks: CompilationMarks
340) -> tuple[str, Optional[str]]:
341 """``(album artist to put back, marked artist to forget)`` when
342 unmarking: the album artist the album had when it was marked by hand,
343 else - a compilation by its source - the artist most of its tracks
344 list first."""
346 first_artists = [t.artists[0] for t in tracks if t.artists]
347 credited = {file_name_key(a) for t in tracks for a in t.artists}
348 for mark in marks.marked_albums(album):
349 if file_name_key(mark['artist']) in credited:
350 return mark['artist'], mark['artist']
351 return _most_common(first_artists), None
354def set_album_compilation(
355 files: list[tuple[str, Path]],
356 *,
357 compilation: bool,
358 marks: CompilationMarks,
359) -> CompilationResult:
360 """Mark (*compilation* true) or unmark the album whose tracks are
361 *files* (``(stored path, full path)`` pairs), rewrite their tags and
362 remember it. Raises :class:`CompilationError` when *files* is empty,
363 isn't one album, or is already in the asked state."""
365 if not files:
366 raise CompilationError('No tracks given')
367 tracks = _read_tracks(files)
368 albums = {file_name_key(t.album) for t in tracks}
369 if len(albums) != 1 or not next(iter(albums)):
370 raise CompilationError('The tracks must all be from one album')
371 album = _most_common([t.album for t in tracks])
372 current = _most_common([t.credited_as for t in tracks])
373 is_compilation = is_various_artists(current)
374 if compilation == is_compilation:
375 raise AlreadyInStateError(
376 'The album is already a compilation'
377 if compilation
378 else 'The album is not a compilation',
379 CompilationResult(
380 album=album, album_artist=current, compilation=compilation
381 ),
382 )
384 marked_artist: Optional[str] = None
385 if compilation:
386 album_artist = VARIOUS_ARTISTS
387 else:
388 album_artist, marked_artist = _restored_album_artist(
389 tracks, album, marks
390 )
391 if not album_artist:
392 raise CompilationError('No artist to give the album back')
394 result = CompilationResult(
395 album=album, album_artist=album_artist, compilation=compilation
396 )
397 for track in tracks:
398 try:
399 retag_file(track.full, album_artist, compilation=compilation)
400 except Exception as exc:
401 logger.opt(exception=True).warning(
402 'Could not retag {} as a compilation', track.stored_path
403 )
404 result.failed.append({
405 'file': track.stored_path,
406 'error': str(exc)[:200],
407 })
408 continue
409 result.changed.append(track.stored_path)
411 if not result.changed:
412 return result
413 # Remembered only once a file actually changed.
414 if compilation:
415 marks.set(current, album, compilation=True, album_artist=album_artist)
416 elif marked_artist is not None:
417 marks.remove(marked_artist, album)
418 else:
419 # A compilation by its source: the next download of it must not
420 # be marked as one again.
421 marks.set(
422 VARIOUS_ARTISTS,
423 album,
424 compilation=False,
425 album_artist=album_artist,
426 )
427 return result