Coverage for downtify/deemix_upgrade.py: 84%
215 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"""Opt-in catalog-verified Deemix replacements, with durable receipts."""
3from __future__ import annotations
5import json
6import os
7import subprocess
8import tempfile
9from pathlib import Path
10from typing import Any, Callable
12from . import lyrics as lyrics_mod
13from .deemix_provider import (
14 DeemixClient,
15 _catalog_track,
16 candidate_matches,
17 download_from_deemix,
18 normalize_settings,
19 verified_audio,
20)
21from .deemix_upgrade_playlists import digest, rewrite_playlists
22from .deemix_upgrade_store import AudioReplacementStore
23from .library_cache_keys import file_content_key
24from .library_catalog import (
25 LibraryContext,
26 library_entry_for_file,
27 resolve_library_file,
28)
29from .library_paths import library_stored_path
30from .library_upgrade import UpgradeOptions, UpgradeOutcome
31from .library_upgrade_db import JOB_DONE, JOB_SKIPPED
34class DeemixLibraryUpgrade:
35 """Prepare individually, then publish references once per batch.
37 The Deemix collection is only read. The sole deletable files are
38 individually verified originals inside Downtify's download root.
39 """
41 def __init__(
42 self,
43 store: AudioReplacementStore,
44 context: Callable[[], LibraryContext],
45 settings: Callable[[], dict[str, Any]],
46 playing: Callable[[], set[str]],
47 publish_catalog: Callable[[], None],
48 rekey_owners: Callable[[str, str, str], None] | None = None,
49 lyrics_cache: Any = None,
50 ) -> None:
51 self.store = store
52 self.context = context
53 self.settings = settings
54 self.playing = playing
55 self.publish_catalog = publish_catalog
56 self.rekey_owners = rekey_owners
57 self.lyrics_cache = lyrics_cache
59 @staticmethod
60 def _guard() -> None:
61 """Optional host mount markers, checked again before destructive work."""
62 markers = json.loads(
63 os.environ.get('DOWNTIFY_LIBRARY_READY_MARKERS', '{}')
64 )
65 for name, expected in markers.items():
66 if Path(name).read_text(encoding='utf-8').strip() != expected:
67 raise ValueError('A required library mount is unavailable')
69 def _source(self, stored: str) -> Path:
70 ctx = self.context()
71 if stored.startswith(('ext/', 'slskd/')):
72 raise ValueError('External originals are never removed')
73 full = (ctx.download_dir / stored).resolve(strict=True)
74 if (
75 not full.is_relative_to(ctx.download_dir.resolve())
76 or not full.is_file()
77 ):
78 raise ValueError('Original is outside the download collection')
79 return full
81 def _config(self) -> dict[str, Any]:
82 self._guard()
83 cfg = normalize_settings(self.settings().get('deemix') or {})
84 if not cfg['enabled']:
85 raise ValueError('Enable and test Deemix before replacing audio')
86 source = Path(cfg['source_dir']).resolve(strict=True)
87 if source not in [p.resolve() for p in self.context().extra_dirs]:
88 raise ValueError('Register the Deemix collection first')
89 return cfg
91 def prepare(
92 self,
93 stored: str,
94 options: UpgradeOptions,
95 run_id: int,
96 on_stage: Callable[[str], None],
97 ) -> UpgradeOutcome:
98 cfg = self._config()
99 old = self._source(stored)
100 if old.is_relative_to(Path(cfg['source_dir']).resolve()):
101 return UpgradeOutcome(
102 JOB_SKIPPED, 'Already in the Deemix collection', checked=False
103 )
104 receipt = self.store.get(stored)
105 chosen_id = options.deemix_recordings.get(stored)
106 old_sha = digest(old)
107 if receipt:
108 if chosen_id and str(receipt['catalog'].get('id')) != chosen_id:
109 raise ValueError(
110 'A different replacement was already prepared; review that operation first'
111 )
112 if receipt['old_sha'] != old_sha:
113 raise ValueError(
114 'Original changed since preparation; kept for review'
115 )
116 self._verified_target(receipt)
117 self.store.reuse(stored, run_id, options.delete_replaced_audio)
118 return UpgradeOutcome(
119 JOB_DONE,
120 'Verified replacement reused; publication pending',
121 checked=False,
122 )
123 entry = library_entry_for_file(stored, old)
124 required = (
125 ('title', 'artist') if chosen_id else ('title', 'artist', 'album')
126 )
127 if not all(entry.get(key) for key in required):
128 return UpgradeOutcome(
129 JOB_SKIPPED,
130 'Artist, title and album are required for safe matching',
131 checked=False,
132 )
133 if (
134 entry.get('codec') in {'flac', 'alac', 'wav'}
135 and cfg['bitrate'] != '9'
136 ):
137 return UpgradeOutcome(
138 JOB_SKIPPED,
139 'Kept lossless original; select FLAC in Deemix first',
140 checked=False,
141 )
142 if cfg['bitrate'] == '1' and int(entry.get('bitrate') or 0) > 150000:
143 return UpgradeOutcome(
144 JOB_SKIPPED, 'Kept higher-bitrate original', checked=False
145 )
146 song = {
147 'name': entry['title'],
148 'artist': entry['artist'],
149 'album_name': entry['album'],
150 }
151 if entry.get('explicit'):
152 song['explicit'] = True
153 on_stage('matching')
154 client = DeemixClient(cfg)
155 try:
156 client.connect()
157 row = _catalog_track(
158 client,
159 {'song_id': 'deezer-' + chosen_id} if chosen_id else song,
160 )
161 finally:
162 client.close()
163 if chosen_id and row is not None:
164 # An explicitly reviewed catalog link can correct an old
165 # album label. It must still be the same artist/title/version.
166 if str(row.get('id')) != chosen_id or not candidate_matches(
167 {**song, 'album_name': ''}, row
168 ):
169 return UpgradeOutcome(
170 JOB_SKIPPED,
171 'Selected recording does not match the artist and title; original retained',
172 checked=False,
173 )
174 song = {
175 **song,
176 'album_name': (row.get('album') or {}).get('title'),
177 }
178 if row is None or not candidate_matches(song, row):
179 return UpgradeOutcome(
180 JOB_SKIPPED,
181 'No unambiguous matching album recording; original retained',
182 checked=False,
183 )
184 on_stage('downloading')
185 target = download_from_deemix({'song_id': f'deezer-{row["id"]}'}, cfg)
186 if target is None:
187 raise ValueError('Deemix did not return a verified recording')
188 target = target.resolve(strict=True)
189 if target == old or not target.is_relative_to(
190 Path(cfg['source_dir']).resolve()
191 ):
192 raise ValueError(
193 'Replacement must remain inside the separate Deemix collection'
194 )
195 target_sha = digest(target)
196 if not verified_audio(target, row, cfg['bitrate']):
197 raise ValueError('Replacement metadata or duration did not verify')
198 on_stage('verifying')
199 subprocess.run(
200 [
201 'ffmpeg',
202 '-nostdin',
203 '-v',
204 'error',
205 '-xerror',
206 '-i',
207 str(target),
208 '-f',
209 'null',
210 '-',
211 ],
212 check=True,
213 capture_output=True,
214 timeout=180,
215 )
216 if digest(old) != old_sha:
217 raise ValueError(
218 'Original changed during download; kept for review'
219 )
220 ctx = self.context()
221 new_file = library_stored_path(
222 target, ctx.download_dir, ctx.slskd_dir, ctx.extra_dirs
223 )
224 metadata = library_entry_for_file(new_file, target)
225 if not candidate_matches(
226 song,
227 {
228 'title': metadata.get('title'),
229 'artist': {'name': metadata.get('artist')},
230 'album': {'title': metadata.get('album')},
231 'explicit_lyrics': bool(metadata.get('explicit')),
232 },
233 ):
234 raise ValueError(
235 'Downloaded album tags do not match the requested release'
236 )
237 if entry.get('has_cover') and not metadata.get('has_cover'):
238 raise ValueError('Replacement is missing the original artwork')
239 if (
240 ctx.metadata_cache is not None
241 and ctx.metadata_cache.refresh(new_file, target) is None
242 ):
243 raise ValueError('Replacement could not be registered')
244 self._missing_lyrics(target, row)
245 if digest(target) != target_sha:
246 raise ValueError(
247 'Replacement changed during verification; original retained'
248 )
249 self.store.save_prepared({
250 'old_file': stored,
251 'run_id': run_id,
252 'new_file': new_file,
253 'old_key': file_content_key(old),
254 'new_key': file_content_key(target),
255 'old_sha': old_sha,
256 'new_sha': target_sha,
257 'new_metadata': metadata,
258 'catalog': row,
259 'delete_original': int(options.delete_replaced_audio),
260 })
261 return UpgradeOutcome(
262 JOB_DONE,
263 'Deemix recording verified; publication pending',
264 changed=['audio'],
265 checked=False,
266 )
268 def _missing_lyrics(self, target: Path, row: dict[str, Any]) -> None:
269 """Supplement absent lyrics only; never retag or overwrite Deemix."""
270 existing = lyrics_mod.read_track_lyrics(target)
271 if existing.get('synced') or existing.get('plain'):
272 return
273 providers = self.settings().get('lyrics_providers') or []
274 if not providers:
275 return
276 song = {
277 'name': row.get('title'),
278 'artists': [row.get('artist') or {}],
279 'album_name': (row.get('album') or {}).get('title'),
280 'duration': row.get('duration'),
281 }
282 found = lyrics_mod.fetch(song, providers, self.lyrics_cache)
283 if found is None or not found.has_any():
284 return
285 dest = lyrics_mod.lrc_path_for(target)
286 if (
287 dest.resolve().is_relative_to(
288 Path(self._config()['source_dir']).resolve()
289 )
290 or dest.exists()
291 ):
292 return
293 dest.parent.mkdir(parents=True, exist_ok=True)
294 staged = None
295 try:
296 with tempfile.NamedTemporaryFile(
297 dir=dest.parent, prefix='.deemix-lyrics-', delete=False
298 ) as output:
299 staged = Path(output.name)
300 output.write(
301 (found.synced or found.plain or '').encode('utf-8')
302 )
303 output.flush()
304 os.fsync(output.fileno())
305 try:
306 os.link(staged, dest)
307 except FileExistsError:
308 pass
309 finally:
310 if staged:
311 staged.unlink(missing_ok=True)
313 def _verified_target(self, receipt: dict[str, Any]) -> Path:
314 ctx = self.context()
315 cfg = self._config()
316 target = resolve_library_file(receipt['new_file'], ctx)
317 if target is None or not target.resolve().is_relative_to(
318 Path(cfg['source_dir']).resolve()
319 ):
320 raise ValueError('Replacement collection is unavailable')
321 if digest(target) != receipt['new_sha']:
322 raise ValueError('Replacement changed; original retained')
323 return target
325 def finalize(
326 self, run_id: int, stopped: Callable[[], bool]
327 ) -> list[dict[str, Any]]:
328 receipts = self.store.for_run(run_id)
329 ctx = self.context()
330 mapping: dict[Path, tuple[Path, float]] = {}
331 eligible = []
332 playing = self.playing()
333 for receipt in receipts:
334 if stopped():
335 raise InterruptedError('Replacement paused')
336 if receipt['old_file'] in playing:
337 raise ValueError(
338 'An original is playing; pause playback and resume this run'
339 )
340 target = self._verified_target(receipt)
341 old = (ctx.download_dir / receipt['old_file']).resolve()
342 if not old.exists() and receipt['state'] in {'linked', 'removed'}:
343 self.store.mark(
344 receipt['old_file'],
345 'removed',
346 'Cleanup already completed',
347 deleted=True,
348 )
349 continue
350 old = self._source(receipt['old_file'])
351 if digest(old) != receipt['old_sha']:
352 raise ValueError(
353 'Original changed before publication; retained'
354 )
355 alias = os.environ.get('DOWNTIFY_DEEMIX_M3U_ROOT', '')
356 playlist_target = target
357 if alias:
358 root = Path(self._config()['source_dir']).resolve()
359 if Path(alias).resolve() != root:
360 raise ValueError(
361 'M3U alias does not resolve to the Deemix collection'
362 )
363 playlist_target = Path(alias) / target.relative_to(root)
364 mapping[old] = (
365 playlist_target,
366 receipt['new_metadata']['duration'],
367 )
368 eligible.append(receipt)
369 roots = [ctx.download_dir, *ctx.extra_dirs]
370 if ctx.slskd_dir:
371 roots.append(ctx.slskd_dir)
372 rewrite_playlists(roots, ctx.download_dir, mapping, stopped=stopped)
373 if stopped():
374 raise InterruptedError(
375 'Replacement paused before reference publication'
376 )
377 self.store.relink(eligible)
378 self.store.assert_relinked(eligible)
379 if self.rekey_owners:
380 for receipt in eligible:
381 self.rekey_owners(
382 receipt['old_key'], receipt['new_key'], receipt['new_file']
383 )
384 self.publish_catalog()
386 for receipt in eligible:
387 if stopped():
388 raise InterruptedError('Replacement paused before cleanup')
389 old_file = receipt['old_file']
390 if not receipt['delete_original']:
391 self.store.mark(
392 old_file, 'retained', 'Original kept by request'
393 )
394 continue
395 if old_file in self.playing():
396 raise ValueError('Original is playing; cleanup deferred')
397 old = self._source(old_file)
398 self._verified_target(receipt)
399 if digest(old) != receipt['old_sha']:
400 raise ValueError('Original changed before cleanup; retained')
401 self._guard()
402 # The database transaction and M3U publication have succeeded;
403 # remove only this verified original, never folders or sidecars.
404 old.unlink()
405 self.store.mark(
406 old_file,
407 'removed',
408 'Original removed after verified import',
409 deleted=True,
410 )
411 if ctx.metadata_cache is not None:
412 ctx.metadata_cache.forget(old_file)
413 self.publish_catalog()
414 return self.store.for_run(run_id)
417def alias_file(
418 stored: str, store: AudioReplacementStore, ctx: LibraryContext
419) -> Path | None:
420 """Read-only compatibility for old player URLs; not used by mutations."""
421 alias = store.path_alias(stored)
422 return resolve_library_file(alias, ctx) if alias else None