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

1"""Opt-in catalog-verified Deemix replacements, with durable receipts.""" 

2 

3from __future__ import annotations 

4 

5import json 

6import os 

7import subprocess 

8import tempfile 

9from pathlib import Path 

10from typing import Any, Callable 

11 

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 

32 

33 

34class DeemixLibraryUpgrade: 

35 """Prepare individually, then publish references once per batch. 

36 

37 The Deemix collection is only read. The sole deletable files are 

38 individually verified originals inside Downtify's download root. 

39 """ 

40 

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 

58 

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

68 

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 

80 

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 

90 

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 ) 

267 

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) 

312 

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 

324 

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

385 

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) 

415 

416 

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