Coverage for downtify/audio_replace.py: 45%

229 statements  

« prev     ^ index     » next       coverage.py v7.17.4, created at 2026-11-21 22:18 +0000

1"""Replace a library track's audio with a version the user picks. 

2 

3Automatic matching sometimes lands on the wrong song or the wrong version 

4(a live cut, a remix, a lyric video with an intro). From a track's menu, 

5an admin searches YouTube Music and YouTube (or pastes a YouTube or 

6SoundCloud track link), picks the right upload, and the file's audio is 

7swapped for it: 

8 

9* **Same file.** The new audio is written to the same path, in the same 

10 format (an ``.flac`` stays FLAC, an ``.mp3`` MP3 at the chosen bitrate), 

11 so every M3U, playlist, like, Navidrome entry and app track id that 

12 points at the file keeps pointing at it. 

13* **Same tags.** Every tag of the old file - title, artists, album, 

14 numbers, cover, lyrics, whatever else - is copied onto the new audio as 

15 it is; the ``.lrc`` sidecar is left alone. The file's modification time 

16 is kept, so it doesn't jump to the top of "recently added". 

17* **Safe.** The new audio is downloaded beside the file under a staging 

18 name the library scan skips (``<name>.downtify-upgrade.<ext>``), checked 

19 to be readable audio, and only then moved over the old file. A failed 

20 download or check leaves the old file untouched. 

21 

22Candidates come from :func:`candidates`; the swap is :func:`replace_audio`. 

23 

24**From a file.** The admin can also upload the right audio from their 

25own computer (a CD rip, a Soulseek download, a file a friend sent): 

26:func:`replace_from_file`. A file in the same format as the library file 

27is used as it is, bit for bit; another format is converted to the file's 

28own (an ``.mp3`` at the chosen bitrate), so the path still doesn't 

29change. Same tags, same date, same staging and checks as above. 

30 

31Either way the file is then remembered as replaced by hand 

32(:mod:`downtify.hand_replaced`), so a later download of the same song 

33doesn't write over it. 

34""" 

35 

36from __future__ import annotations 

37 

38import os 

39import shutil 

40import subprocess 

41from pathlib import Path 

42from typing import Any, Callable, Optional 

43 

44from loguru import logger 

45from mutagen import File as MutagenFile 

46from mutagen.flac import FLAC 

47from mutagen.id3 import ID3, ID3NoHeaderError 

48 

49from . import providers 

50from .library_catalog import UPGRADE_STAGING_MARKER 

51 

52#: File types whose audio can be replaced: the formats Downtify writes. 

53REPLACEABLE_FORMATS = ('mp3', 'flac', 'm4a', 'ogg', 'opus') 

54 

55#: What an uploaded replacement may be: the formats above, plus the 

56#: usual lossless and lossy files people have (converted on the way in). 

57UPLOAD_FORMATS = (*REPLACEABLE_FORMATS, 'wav', 'aiff', 'aif', 'aac', 'webm') 

58 

59#: The biggest file accepted for upload (a 20-minute WAV is ~210 MB). 

60MAX_UPLOAD_BYTES = 400 * 1024 * 1024 

61 

62#: ffmpeg's encoder for each format Downtify writes. 

63_ENCODERS = { 

64 'mp3': 'libmp3lame', 

65 'm4a': 'aac', 

66 'ogg': 'libvorbis', 

67 'opus': 'libopus', 

68 'flac': 'flac', 

69} 

70 

71#: Candidates asked of each source. 

72CANDIDATE_LIMIT = 10 

73 

74ProgressCallback = Callable[[float, str, Optional[str]], None] 

75 

76 

77class ReplaceError(ValueError): 

78 """The audio can't be replaced; the message says why.""" 

79 

80 

81def replacement_format(path: Path) -> str: 

82 """The format new audio for *path* is written in: its own.""" 

83 

84 fmt = path.suffix.lower().lstrip('.') 

85 if fmt not in REPLACEABLE_FORMATS: 

86 raise ReplaceError( 

87 f'Only {", ".join(REPLACEABLE_FORMATS)} files can be replaced' 

88 ) 

89 return fmt 

90 

91 

92def search_query(entry: dict[str, Any]) -> str: 

93 """What to search for a track: ``Artist - Title``.""" 

94 

95 title = str(entry.get('title') or '').strip() 

96 artist = ', '.join( 

97 part.strip() 

98 for part in str(entry.get('artist') or '').split(';') 

99 if part.strip() 

100 ) 

101 return f'{artist} - {title}' if artist and title else title or artist 

102 

103 

104# ── Candidates ────────────────────────────────────────────────────────── 

105 

106 

107def _thumbnail(video_id: str) -> str: 

108 return f'https://i.ytimg.com/vi/{video_id}/mqdefault.jpg' 

109 

110 

111def _from_youtube_music(song: dict[str, Any]) -> dict[str, Any]: 

112 video_id = str(song.get('song_id') or '') 

113 return { 

114 'video_id': video_id, 

115 'title': str(song.get('name') or ''), 

116 'artist': ', '.join(song.get('artists') or []), 

117 'album': str(song.get('album_name') or ''), 

118 'duration': int(song.get('duration') or 0), 

119 'thumbnail': str(song.get('cover_url') or '') or _thumbnail(video_id), 

120 'source': 'youtube-music', 

121 'url': f'https://music.youtube.com/watch?v={video_id}', 

122 } 

123 

124 

125def _from_youtube(entry: dict[str, Any]) -> Optional[dict[str, Any]]: 

126 video_id = entry.get('id') 

127 if not isinstance(video_id, str) or not video_id: 

128 return None 

129 if entry.get('live_status') in {'is_live', 'is_upcoming', 'post_live'}: 

130 return None 

131 try: 

132 duration = int(entry.get('duration') or 0) 

133 except (TypeError, ValueError): 

134 duration = 0 

135 return { 

136 'video_id': video_id, 

137 'title': str(entry.get('title') or ''), 

138 'artist': str(entry.get('channel') or entry.get('uploader') or ''), 

139 'album': '', 

140 'duration': duration, 

141 'thumbnail': _thumbnail(video_id), 

142 'source': 'youtube', 

143 'url': f'https://www.youtube.com/watch?v={video_id}', 

144 } 

145 

146 

147def _from_soundcloud_link(url: str) -> list[dict[str, Any]]: 

148 """The one track a pasted SoundCloud link names; its ``video_id`` is 

149 the track URL (what :func:`replace_audio` fetches).""" 

150 

151 try: 

152 song = providers.soundcloud_track_from_url(url) 

153 except Exception as exc: 

154 logger.opt(exception=True).debug('SoundCloud lookup failed') 

155 raise ReplaceError('Could not read that SoundCloud track') from exc 

156 return [ 

157 { 

158 'video_id': song['url'], 

159 'title': song['name'], 

160 'artist': song['artist'], 

161 'album': '', 

162 'duration': int(song.get('duration') or 0), 

163 'thumbnail': song['cover_url'], 

164 'source': 'link', 

165 'url': song['url'], 

166 } 

167 ] 

168 

169 

170def _from_link(query: str) -> Optional[list[dict[str, Any]]]: 

171 """The one video (or SoundCloud track) a pasted link names, or 

172 ``None`` when *query* isn't such a link.""" 

173 

174 soundcloud = providers.parse_soundcloud_url(query.strip()) 

175 if soundcloud is not None: 

176 return _from_soundcloud_link(soundcloud[1]) 

177 parsed = providers.parse_youtube_url(query.strip()) 

178 if parsed is None: 

179 return None 

180 kind, video_id = parsed 

181 if kind != 'track': 

182 raise ReplaceError('Paste a link to one video or song') 

183 try: 

184 song = providers.song_from_video_id(video_id) 

185 except Exception: 

186 logger.opt(exception=True).debug('Video lookup failed') 

187 song = {} 

188 found = _from_youtube_music({**song, 'song_id': video_id}) 

189 found['source'] = 'link' 

190 return [found] 

191 

192 

193def candidates( 

194 query: str, limit: int = CANDIDATE_LIMIT 

195) -> list[dict[str, Any]]: 

196 """Versions of a song to pick from: YouTube Music songs first, then 

197 standard YouTube uploads (covers, live cuts, fan uploads), without 

198 repeats. A pasted link is that one video.""" 

199 

200 text = str(query or '').strip() 

201 if not text: 

202 return [] 

203 linked = _from_link(text) 

204 if linked is not None: 

205 return linked 

206 found: list[dict[str, Any]] = [] 

207 seen: set[str] = set() 

208 # ytmusicapi can hand back more than it was asked for. 

209 for song in providers.search_songs(text, limit=limit)[:limit]: 

210 row = _from_youtube_music(song) 

211 if row['video_id'] and row['video_id'] not in seen: 

212 seen.add(row['video_id']) 

213 found.append(row) 

214 try: 

215 uploads = providers.youtube_search(text, limit) 

216 except Exception: 

217 logger.opt(exception=True).warning('YouTube search failed') 

218 uploads = [] 

219 for entry in uploads: 

220 row = _from_youtube(entry) 

221 if row and row['video_id'] not in seen: 

222 seen.add(row['video_id']) 

223 found.append(row) 

224 return found 

225 

226 

227# ── Tags ──────────────────────────────────────────────────────────────── 

228 

229 

230def copy_tags(source: Path, target: Path) -> None: 

231 """Put every tag of *source* (cover and lyrics included) on *target*, 

232 replacing whatever *target* had. Both are the same format.""" 

233 

234 if source.suffix.lower() == '.mp3': 

235 try: 

236 tags = ID3(str(source)) 

237 except ID3NoHeaderError: 

238 return 

239 try: 

240 ID3(str(target)).delete(str(target)) 

241 except ID3NoHeaderError: 

242 pass 

243 # Written in the ID3 version the file had (2.3 or 2.4). 

244 version = tags.version[1] if tags.version[1] in {3, 4} else 4 

245 if version == 3: 

246 tags.update_to_v23() 

247 tags.save(str(target), v2_version=version) 

248 return 

249 

250 old = MutagenFile(str(source)) 

251 new = MutagenFile(str(target)) 

252 if old is None or new is None: 

253 raise ReplaceError('Could not read the tags') 

254 new.delete() 

255 if new.tags is None: 

256 new.add_tags() 

257 if old.tags is not None: 

258 for key in list(old.tags.keys()): 

259 new.tags[key] = old.tags[key] 

260 # FLAC keeps pictures outside the Vorbis comments. 

261 if isinstance(new, FLAC): 

262 new.clear_pictures() 

263 for picture in getattr(old, 'pictures', None) or []: 

264 new.add_picture(picture) 

265 new.save() 

266 

267 

268def _length(path: Path) -> float: 

269 try: 

270 audio = MutagenFile(str(path)) 

271 except Exception: 

272 return 0.0 

273 info = getattr(audio, 'info', None) 

274 return float(getattr(info, 'length', 0.0) or 0.0) 

275 

276 

277# ── The swap ──────────────────────────────────────────────────────────── 

278 

279 

280def staging_basename(path: Path) -> str: 

281 """The name new audio is downloaded under, beside *path* (the library 

282 scan skips it).""" 

283 

284 return f'{path.stem}{UPGRADE_STAGING_MARKER}' 

285 

286 

287def replace_audio( 

288 downloader: Any, 

289 target: Path, 

290 video_id: str, 

291 *, 

292 song: dict[str, Any], 

293 progress_cb: Optional[ProgressCallback] = None, 

294) -> dict[str, Any]: 

295 """Replace *target*'s audio with YouTube video *video_id* (or the 

296 SoundCloud track it is the URL of), keeping its path, format, tags and 

297 modification time. ``{duration_before, 

298 duration_after}``. Raises :class:`ReplaceError` (nothing changed) or 

299 the download's own error.""" 

300 

301 fmt = replacement_format(target) 

302 if not target.is_file(): 

303 raise ReplaceError('The file is no longer in the library') 

304 before = _length(target) 

305 stat = target.stat() 

306 basename = staging_basename(target) 

307 provider = ( 

308 'soundcloud' 

309 if providers.parse_soundcloud_url(video_id) is not None 

310 else 'youtube' 

311 ) 

312 staged: Optional[Path] = None 

313 try: 

314 staged = downloader.fetch_audio( 

315 video_id, 

316 target.parent, 

317 basename, 

318 song=song, 

319 progress_cb=progress_cb, 

320 provider=provider, 

321 audio_format=fmt, 

322 ) 

323 if staged.suffix.lower() != target.suffix.lower(): 

324 raise ReplaceError( 

325 f'The download came out as {staged.suffix}, not {target.suffix}' 

326 ) 

327 after = _length(staged) 

328 if after <= 0: 

329 raise ReplaceError('The downloaded audio could not be read') 

330 if progress_cb is not None: 

331 progress_cb(98.0, 'Copying tags', provider) 

332 copy_tags(target, staged) 

333 os.replace(str(staged), str(target)) 

334 staged = None 

335 finally: 

336 # Whatever is left of the staging download (a failed conversion 

337 # leaves the upstream file) goes. 

338 for leftover in target.parent.glob(f'{basename}.*'): 

339 if leftover.is_file(): 

340 leftover.unlink(missing_ok=True) 

341 try: 

342 os.utime(str(target), ns=(stat.st_atime_ns, stat.st_mtime_ns)) 

343 except OSError: 

344 pass 

345 logger.info( 

346 'Replaced the audio of {} with video {} ({:.0f}s -> {:.0f}s)', 

347 target.name, 

348 video_id, 

349 before, 

350 after, 

351 ) 

352 return { 

353 'duration_before': round(before, 1), 

354 'duration_after': round(after, 1), 

355 } 

356 

357 

358# ── From a file ───────────────────────────────────────────────────────── 

359 

360 

361def upload_format(name: str) -> str: 

362 """The format of an uploaded file, from its name (``ReplaceError`` 

363 for anything that isn't an audio file Downtify takes).""" 

364 

365 fmt = Path(str(name or '')).suffix.lower().lstrip('.') 

366 if fmt not in UPLOAD_FORMATS: 

367 raise ReplaceError( 

368 f'Upload an audio file: {", ".join(UPLOAD_FORMATS)}' 

369 ) 

370 return fmt 

371 

372 

373def upload_staging_path(target: Path, fmt: str) -> Path: 

374 """Where an upload for *target* is written while it arrives: beside 

375 it, under a name the library scan skips.""" 

376 

377 return target.with_name(f'{staging_basename(target)}.upload.{fmt}') 

378 

379 

380def _ffmpeg() -> Optional[str]: 

381 return shutil.which('ffmpeg') 

382 

383 

384def _decodes(path: Path, ffmpeg: str) -> bool: 

385 """Whether ffmpeg reads *path* through to the end without an error 

386 (a truncated or renamed non-audio file doesn't).""" 

387 

388 try: 

389 subprocess.run( 

390 [ffmpeg, '-nostdin', '-v', 'error', '-xerror', '-i', str(path)] 

391 + ['-map', '0:a:0', '-f', 'null', '-'], 

392 check=True, 

393 capture_output=True, 

394 timeout=300, 

395 ) 

396 except (subprocess.SubprocessError, OSError): 

397 return False 

398 return True 

399 

400 

401def _convert( 

402 source: Path, output: Path, fmt: str, bitrate: str, ffmpeg: str 

403) -> None: 

404 """Re-encode *source*'s audio as *fmt* into *output* (no tags, no 

405 cover: those come from the library file).""" 

406 

407 args = [ffmpeg, '-nostdin', '-v', 'error', '-y', '-i', str(source)] 

408 args += ['-map', '0:a:0', '-map_metadata', '-1', '-vn'] 

409 args += ['-c:a', _ENCODERS[fmt]] 

410 if fmt != 'flac' and str(bitrate).isdigit(): 

411 args += ['-b:a', f'{bitrate}k'] 

412 if fmt == 'm4a': 

413 args += ['-f', 'mp4'] 

414 args.append(str(output)) 

415 try: 

416 subprocess.run(args, check=True, capture_output=True, timeout=900) 

417 except subprocess.CalledProcessError as exc: 

418 detail = (exc.stderr or b'').decode('utf-8', 'replace').strip() 

419 logger.warning('Converting {} failed: {}', source.name, detail) 

420 raise ReplaceError('Could not convert the uploaded file') from exc 

421 except (subprocess.SubprocessError, OSError) as exc: 

422 raise ReplaceError('Could not convert the uploaded file') from exc 

423 

424 

425def replace_from_file( 

426 target: Path, upload: Path, *, bitrate: str = '320' 

427) -> dict[str, Any]: 

428 """Replace *target*'s audio with the uploaded file *upload* (already 

429 on disk, beside it - :func:`upload_staging_path`), keeping its path, 

430 format, tags and modification time. The upload is used as it is when 

431 it is already in *target*'s format, converted otherwise. 

432 

433 ``{duration_before, duration_after, converted}``. Raises 

434 :class:`ReplaceError` with nothing changed. *upload* is gone 

435 afterwards either way.""" 

436 

437 converted: Optional[Path] = None 

438 try: 

439 fmt = replacement_format(target) 

440 if not target.is_file(): 

441 raise ReplaceError('The file is no longer in the library') 

442 upload_fmt = upload_format(upload.name) 

443 ffmpeg = _ffmpeg() 

444 if _length(upload) <= 0 or (ffmpeg and not _decodes(upload, ffmpeg)): 

445 raise ReplaceError('The uploaded file is not readable audio') 

446 before = _length(target) 

447 stat = target.stat() 

448 if upload_fmt == fmt: 

449 staged = upload 

450 else: 

451 if not ffmpeg: 

452 raise ReplaceError( 

453 f'Converting to .{fmt} needs ffmpeg: upload a .{fmt} file' 

454 ) 

455 converted = target.with_name(f'{staging_basename(target)}.{fmt}') 

456 _convert(upload, converted, fmt, bitrate, ffmpeg) 

457 staged = converted 

458 after = _length(staged) 

459 if after <= 0: 

460 raise ReplaceError('The new audio could not be read') 

461 copy_tags(target, staged) 

462 os.replace(str(staged), str(target)) 

463 converted = None 

464 finally: 

465 upload.unlink(missing_ok=True) 

466 if converted is not None: 

467 converted.unlink(missing_ok=True) 

468 try: 

469 os.utime(str(target), ns=(stat.st_atime_ns, stat.st_mtime_ns)) 

470 except OSError: 

471 pass 

472 logger.info( 

473 'Replaced the audio of {} with an uploaded .{} file ' 

474 '({:.0f}s -> {:.0f}s{})', 

475 target.name, 

476 upload_fmt, 

477 before, 

478 after, 

479 ', converted' if upload_fmt != fmt else '', 

480 ) 

481 return { 

482 'duration_before': round(before, 1), 

483 'duration_after': round(after, 1), 

484 'converted': upload_fmt != fmt, 

485 }