Coverage for downtify/compilation.py: 46%

200 statements  

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

3 

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. 

10 

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. 

20 

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

26 

27from __future__ import annotations 

28 

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 

36 

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 

44 

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 

51 

52#: A rewritten file must still play for as long as the original did. 

53_DURATION_TOLERANCE_SECONDS = 1.0 

54 

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} 

62 

63 

64class CompilationError(ValueError): 

65 """The request can't be applied (no tracks, several albums, ...).""" 

66 

67 

68class AlreadyInStateError(CompilationError): 

69 """The files' tags are already what was asked: nothing to rewrite. 

70 

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

74 

75 def __init__(self, message: str, result: CompilationResult) -> None: 

76 super().__init__(message) 

77 self.result = result 

78 

79 

80# ── The remembered marks ────────────────────────────────────────────── 

81class CompilationMarks: 

82 """Albums whose compilation status an admin set by hand. 

83 

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

90 

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

98 

99 def _connect(self): 

100 return self.db.connect() 

101 

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

119 

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 ) 

145 

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 ) 

153 

154 def marked_albums(self, album: str) -> list[dict[str, Any]]: 

155 """The albums titled *album* marked as compilations by hand.""" 

156 

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] 

166 

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

172 

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 } 

197 

198 

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

206 

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

243 

244 

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) 

252 

253 

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

259 

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 

279 

280 

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 

290 

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

296 

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 

301 

302 

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) 

310 

311 

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

315 

316 

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 

336 

337 

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

345 

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 

352 

353 

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

364 

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 ) 

383 

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

393 

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) 

410 

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