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
« 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.
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:
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.
22Candidates come from :func:`candidates`; the swap is :func:`replace_audio`.
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.
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"""
36from __future__ import annotations
38import os
39import shutil
40import subprocess
41from pathlib import Path
42from typing import Any, Callable, Optional
44from loguru import logger
45from mutagen import File as MutagenFile
46from mutagen.flac import FLAC
47from mutagen.id3 import ID3, ID3NoHeaderError
49from . import providers
50from .library_catalog import UPGRADE_STAGING_MARKER
52#: File types whose audio can be replaced: the formats Downtify writes.
53REPLACEABLE_FORMATS = ('mp3', 'flac', 'm4a', 'ogg', 'opus')
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')
59#: The biggest file accepted for upload (a 20-minute WAV is ~210 MB).
60MAX_UPLOAD_BYTES = 400 * 1024 * 1024
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}
71#: Candidates asked of each source.
72CANDIDATE_LIMIT = 10
74ProgressCallback = Callable[[float, str, Optional[str]], None]
77class ReplaceError(ValueError):
78 """The audio can't be replaced; the message says why."""
81def replacement_format(path: Path) -> str:
82 """The format new audio for *path* is written in: its own."""
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
92def search_query(entry: dict[str, Any]) -> str:
93 """What to search for a track: ``Artist - Title``."""
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
104# ── Candidates ──────────────────────────────────────────────────────────
107def _thumbnail(video_id: str) -> str:
108 return f'https://i.ytimg.com/vi/{video_id}/mqdefault.jpg'
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 }
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 }
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)."""
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 ]
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."""
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]
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."""
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
227# ── Tags ────────────────────────────────────────────────────────────────
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."""
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
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()
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)
277# ── The swap ────────────────────────────────────────────────────────────
280def staging_basename(path: Path) -> str:
281 """The name new audio is downloaded under, beside *path* (the library
282 scan skips it)."""
284 return f'{path.stem}{UPGRADE_STAGING_MARKER}'
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."""
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 }
358# ── From a file ─────────────────────────────────────────────────────────
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)."""
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
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."""
377 return target.with_name(f'{staging_basename(target)}.upload.{fmt}')
380def _ffmpeg() -> Optional[str]:
381 return shutil.which('ffmpeg')
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)."""
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
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)."""
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
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.
433 ``{duration_before, duration_after, converted}``. Raises
434 :class:`ReplaceError` with nothing changed. *upload* is gone
435 afterwards either way."""
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 }