From e6741f959da7455f24e1d8ddd05124965356dccf Mon Sep 17 00:00:00 2001 From: ghostdanser <5584730+sjbrownrigg@users.noreply.github.com> Date: Thu, 13 Aug 2026 11:54:54 +0100 Subject: [PATCH 1/4] Don't mark failed downloads as downloaded Track.download() retried once and, on a second failure, logged the track to the failed-downloads database but then returned normally. Media.rip() runs preprocess -> download -> postprocess unconditionally, so postprocess() went on to call db.set_downloaded(), permanently marking a track that had never downloaded. Every later run's resolve() then saw it in the downloads database and skipped it, so the track could never be recovered -- including across restarts. Raise TrackDownloadFailedError instead, so Media.rip() stops before postprocess() and set_downloaded() is never reached for a track that actually failed. Also delete the partial file. Downloads always restart from byte 0 (BasicDownloadable opens the path "wb" and sends no Range header), so a partial is never resumed -- it just sits in the library as a truncated file that has valid tags and the right size, plays in any client, and fails to decode partway through. Album.download() and Playlist.download() already wrap each track.rip() in its own try/except and continue, so raising cannot abort a whole album or playlist. Co-Authored-By: Claude Opus 5 (cherry picked from commit 78d76bea26bf27311a444df4a9dba98432b34bbd) --- streamrip/exceptions.py | 8 ++++++++ streamrip/media/track.py | 12 +++++++++++- 2 files changed, 19 insertions(+), 1 deletion(-) diff --git a/streamrip/exceptions.py b/streamrip/exceptions.py index 687b1a14..cfd84e33 100644 --- a/streamrip/exceptions.py +++ b/streamrip/exceptions.py @@ -68,3 +68,11 @@ def print_msg(self, item) -> str: class ConversionError(Exception): """ConversionError.""" + + +class TrackDownloadFailedError(Exception): + """Raised when a track fails to download after retrying. + + Signals to Media.rip() that postprocess (tagging, marking downloaded) + must not run for this track. + """ diff --git a/streamrip/media/track.py b/streamrip/media/track.py index bc3207d5..281833ae 100644 --- a/streamrip/media/track.py +++ b/streamrip/media/track.py @@ -7,7 +7,7 @@ from ..client import Client, Downloadable from ..config import Config from ..db import Database -from ..exceptions import NonStreamableError +from ..exceptions import NonStreamableError, TrackDownloadFailedError from ..filepath_utils import clean_filename from ..metadata import AlbumMetadata, Covers, TrackMetadata, tag_file from ..progress import add_title, get_progress_callback, remove_title @@ -71,6 +71,16 @@ async def download(self): self.db.set_failed( self.downloadable.source, "track", self.meta.info.id ) + if os.path.isfile(self.download_path): + os.remove(self.download_path) + # postprocess() normally does this, but raising below + # skips it, which would leave a phantom title in the + # progress display for the rest of the run. + if self.is_single: + remove_title(self.meta.title) + raise TrackDownloadFailedError( + f"{self.meta.title} ({self.meta.info.id})" + ) from e async def postprocess(self): if self.is_single: From 29de6fbb2a0189e604464dd58c547497c1bbac11 Mon Sep 17 00:00:00 2001 From: ghostdanser <5584730+sjbrownrigg@users.noreply.github.com> Date: Thu, 13 Aug 2026 11:55:26 +0100 Subject: [PATCH 2/4] Record tracks that fail while resolving PendingTrack.resolve() had four failure paths and only one of them recorded anything. If the metadata request failed, if building the metadata raised, or if fetching the downloadable URL failed, it logged a line and returned None. Nothing else happened: no file was written, no downloads-database row was added, and nothing went into the failed database. The track simply went missing from the album, and because it was never recorded as failed, `rip repair` could not find it either. PendingSingle.resolve() had the same gap on three of its paths. Call db.set_failed() on all of them so a resolve-time failure is retryable rather than invisible. Co-Authored-By: Claude Opus 5 (cherry picked from commit bcebf576183b2a7c291186c9701f20928ec1b139) --- streamrip/media/track.py | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/streamrip/media/track.py b/streamrip/media/track.py index 281833ae..7c335b73 100644 --- a/streamrip/media/track.py +++ b/streamrip/media/track.py @@ -139,16 +139,22 @@ async def resolve(self) -> Track | None: return None source = self.client.source + # Every failure below has to be recorded, not just logged. An unlogged + # failure leaves no trace anywhere: no file, no downloads.db row, and + # nothing in the failed db for `rip repair` to retry -- the track just + # silently goes missing from the album. try: resp = await self.client.get_metadata(self.id, "track") except NonStreamableError as e: logger.error(f"Track {self.id} not available for stream on {source}: {e}") + self.db.set_failed(source, "track", self.id) return None try: meta = TrackMetadata.from_resp(self.album, source, resp) except Exception as e: logger.error(f"Error building track metadata for {self.id}: {e}") + self.db.set_failed(source, "track", self.id) return None if meta is None: @@ -163,6 +169,7 @@ async def resolve(self) -> Track | None: logger.error( f"Error getting downloadable data for track {meta.tracknumber} [{self.id}]: {e}" ) + self.db.set_failed(source, "track", self.id) return None downloads_config = self.config.session.downloads @@ -201,16 +208,20 @@ async def resolve(self) -> Track | None: ) return None + # As in PendingTrack.resolve: record every failure, so a track that + # dies here is retryable by `rip repair` instead of vanishing. try: resp = await self.client.get_metadata(self.id, "track") except NonStreamableError as e: logger.error(f"Error fetching track {self.id}: {e}") + self.db.set_failed(self.client.source, "track", self.id) return None # Patch for soundcloud try: album = AlbumMetadata.from_track_resp(resp, self.client.source) except Exception as e: logger.error(f"Error building album metadata for track {id=}: {e}") + self.db.set_failed(self.client.source, "track", self.id) return None if album is None: @@ -224,6 +235,7 @@ async def resolve(self) -> Track | None: meta = TrackMetadata.from_resp(album, self.client.source, resp) except Exception as e: logger.error(f"Error building track metadata for track {id=}: {e}") + self.db.set_failed(self.client.source, "track", self.id) return None if meta is None: From 061e46e9e6f5fbe977df30ed0aca49d423a305c1 Mon Sep 17 00:00:00 2001 From: ghostdanser <5584730+sjbrownrigg@users.noreply.github.com> Date: Thu, 13 Aug 2026 11:55:42 +0100 Subject: [PATCH 3/4] Add `rip repair` to retry failed downloads The failed-downloads database was write-only: entries went in and nothing ever read them back. config.toml has always told users that "`rip repair` can be called to retry the downloads", but no such command existed. Add it. It reads the failed database, retries each item through the normal resolve/rip pipeline, and clears the ones that succeed, leaving the rest logged for a future run. Success is determined by membership in the downloads database rather than by diffing the failed database before and after, because nothing in the pipeline removes rows from the failed database -- a before/after diff would always report zero repaired. Checking the downloads database is sound because set_downloaded() is only reached from postprocess(), which a failed track no longer gets to. Failed items are cleared from the downloads database before retrying, so a repair still works on a database left inconsistent by an older version. Repaired tracks are placed in their album's folder, since a failed item is usually one track missing from an otherwise complete album, and retrying resolves it as a single. --flat restores the old behaviour of downloading it to the root. Co-Authored-By: Claude Opus 5 (cherry picked from commit 6c54ab0139f3e889241ad375bbb4c39dced9a408) --- streamrip/rip/cli.py | 81 ++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 81 insertions(+) diff --git a/streamrip/rip/cli.py b/streamrip/rip/cli.py index 2b3f532e..e5cee9dd 100644 --- a/streamrip/rip/cli.py +++ b/streamrip/rip/cli.py @@ -361,6 +361,87 @@ def database_browse(ctx, table): ) +@rip.command() +@click.option("-y", "--yes", help="Don't ask for confirmation.", is_flag=True) +@click.option( + "--flat", + help="Put repaired tracks straight in the download folder instead of " + "their album folder.", + is_flag=True, +) +@click.pass_context +@coro +async def repair(ctx, yes, flat): + """Retry downloads that previously failed. + + Reads the failed downloads database, retries each item, and clears it + from the failed database on success. Items that fail again stay logged + so they can be retried later. + + Failed tracks are retried individually, but are placed in their album's + folder so they rejoin the album they were originally missing from. Pass + --flat to put them in the download folder instead. + """ + if ctx.obj["config"] is None: + return + + with ctx.obj["config"] as cfg: + cfg: Config + # A repaired track is nearly always a track missing from an album that + # was otherwise downloaded, so it needs to land in that album's folder + # rather than loose in the download root. This only touches the + # in-memory session copy, so config.toml is left alone. + if not flat: + cfg.session.filepaths.add_singles_to_folder = True + failed_db = db.Failed(cfg.session.database.failed_downloads_path) + downloads_db = db.Downloads(cfg.session.database.downloads_path) + failed_items = failed_db.all() + + if not failed_items: + console.print("[green]No failed downloads to repair!") + return + + console.print( + f"Found [yellow]{len(failed_items)}[/yellow] failed download(s)." + ) + if not yes and not Confirm.ask("Retry them now?"): + console.print("[green]Repair aborted") + return + + # A failed item should never also be logged as downloaded, but older + # versions of streamrip could mark one downloaded even after it + # failed. Clear that stale state so the retry below isn't skipped. + for _source, _media_type, item_id in failed_items: + downloads_db.remove(id=item_id) + + async with Main(cfg) as main: + await main.add_all_by_id(failed_items) + await main.resolve() + await main.rip() + + # Nothing in the download pipeline removes rows from the failed db, so + # success can't be detected by diffing it. Instead rely on the + # invariant this patch establishes: set_downloaded() is only reached + # via postprocess(), which a failed download never gets to. So an item + # present in the downloads db now is one that just succeeded. + repaired = [ + item_id + for _, _, item_id in failed_items + if downloads_db.contains(id=item_id) + ] + for item_id in repaired: + failed_db.remove(id=item_id) + + console.print( + f"[green]Repaired {len(repaired)}/{len(failed_items)} item(s).[/green]" + ) + if len(repaired) < len(failed_items): + console.print( + f"[yellow]{len(failed_items) - len(repaired)} item(s) failed again " + "and are still logged. Run [bold]rip repair[/bold] to try again." + ) + + @rip.command() @click.option( "-f", From a75065e86321b711969d4a840784b83a5fff1f78 Mon Sep 17 00:00:00 2001 From: ghostdanser <5584730+sjbrownrigg@users.noreply.github.com> Date: Wed, 19 Aug 2026 08:57:35 +0100 Subject: [PATCH 4/4] Repair through the album, not track by track Repair re-added each failed track by id, which resolves as a single. That builds album metadata from the track response -- and on Tidal a track response carries only the album's id, title and cover: album object keys: ['cover', 'id', 'title', 'vibrantColor', 'videoCover'] No track count, so tracktotal falls back to 1, and the artist is the track's artists rather than the album artist. Where folder_format uses {albumartist} or {tracktotal}, repaired tracks therefore land in a different folder from the album they belong to. One repair of a real library produced 18 such folders holding 107 files. Look up each failed track's album and retry through that instead. The metadata is then the album's own, so the folder, disc subfolders and cover art are right, and nothing extra is downloaded: tracks already in the downloads database are skipped. Albums are de-duplicated, so several failures from one album cost one retry rather than several. Anything whose album cannot be determined is still retried on its own. --- streamrip/rip/cli.py | 52 +++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 51 insertions(+), 1 deletion(-) diff --git a/streamrip/rip/cli.py b/streamrip/rip/cli.py index e5cee9dd..e2f758d4 100644 --- a/streamrip/rip/cli.py +++ b/streamrip/rip/cli.py @@ -361,6 +361,38 @@ def database_browse(ctx, table): ) +async def _albums_for(main, failed_items): + """Map failed tracks onto the albums that contain them. + + Returns (album targets, items to retry as they are). Anything whose album + cannot be determined is passed through untouched rather than dropped. + """ + targets: list[tuple[str, str, str]] = [] + unresolved: list[tuple[str, str, str]] = [] + seen: set[tuple[str, str]] = set() + + for source, media_type, item_id in failed_items: + if media_type != "track": + targets.append((source, media_type, item_id)) + continue + try: + client = await main.get_logged_in_client(source) + resp = await client.get_metadata(item_id, "track") + album_id = str((resp.get("album") or {}).get("id") or "") + except Exception as e: + logger.debug("Could not find the album for %s: %s", item_id, e) + album_id = "" + + if not album_id: + unresolved.append((source, media_type, item_id)) + continue + if (source, album_id) not in seen: + seen.add((source, album_id)) + targets.append((source, "album", album_id)) + + return targets, unresolved + + @rip.command() @click.option("-y", "--yes", help="Don't ask for confirmation.", is_flag=True) @click.option( @@ -415,7 +447,25 @@ async def repair(ctx, yes, flat): downloads_db.remove(id=item_id) async with Main(cfg) as main: - await main.add_all_by_id(failed_items) + # Retry through the album rather than track by track. Resolving a + # single track builds its album metadata from the track response, + # which on Tidal carries only an id, title and cover -- no track + # count, and the track's artists in place of the album artist. The + # folder that produces differs from the album's own in both, so + # repaired tracks land in a separate folder instead of rejoining + # the album. + # + # Going through the album gets the real metadata, the right + # folder, disc subfolders and cover art, and costs nothing extra: + # tracks already in the downloads db are skipped, so only what is + # missing gets fetched. + targets, unresolved = await _albums_for(main, failed_items) + if unresolved: + console.print( + f"[yellow]{len(unresolved)} item(s) had no album to retry " + "through; fetching them individually." + ) + await main.add_all_by_id(targets + unresolved) await main.resolve() await main.rip()