From d42e6bfe4104b489d2ce69bf83ad062555e1699f Mon Sep 17 00:00:00 2001 From: ByteMe6 Date: Sun, 15 Nov 2026 17:44:34 +0200 Subject: [PATCH 1/8] feat: add configurable free metadata sources --- tests/test_config.py | 16 +- tests/test_inline.py | 7 + tests/test_metadata_sources.py | 1083 +++++++++++++++++ tests/test_pipeline.py | 11 + tests/test_spotify.py | 15 +- trackfetch.py | 2025 ++++++++++++++++++++++++++++---- 6 files changed, 2920 insertions(+), 237 deletions(-) create mode 100644 tests/test_metadata_sources.py diff --git a/tests/test_config.py b/tests/test_config.py index 2f3e023..ab7d7d1 100644 --- a/tests/test_config.py +++ b/tests/test_config.py @@ -30,6 +30,13 @@ def fake_download_audio(url, temp_dir, audio_format="mp3"): def fake_download_cover(url, dest): dest.write_bytes(b"\xff\xd8\xff\xe0jpeg") + def fake_resolve_metadata(artist, title, source_config, runtime): + track = state["track"] + metadata = m.get_track_metadata(track, artist, title) + metadata.update(source="spotify", source_id=track.get("id"), score=1.0) + return metadata + + monkeypatch.setattr(m, "resolve_metadata", fake_resolve_metadata) monkeypatch.setattr(m, "find_spotify_track", lambda sp, a, t: state["track"]) monkeypatch.setattr(m, "find_youtube_video", lambda a, t: state["video"]) monkeypatch.setattr(m, "download_audio", fake_download_audio) @@ -186,15 +193,12 @@ def test_flag_wins_over_config_and_env(self, monkeypatch): assert (client_id, client_secret) == ("flag-id", "flag-secret") - def test_missing_credentials_exit(self, monkeypatch, capsys): + def test_missing_credentials_return_none_quietly(self, monkeypatch, capsys): monkeypatch.delenv("SPOTIFY_CLIENT_ID", raising=False) monkeypatch.delenv("SPOTIFY_CLIENT_SECRET", raising=False) - with pytest.raises(SystemExit) as exc: - m.get_spotify() - - assert exc.value.code == 1 - assert "Spotify credentials not found" in capsys.readouterr().out + assert m.get_spotify() is None + assert capsys.readouterr().out == "" class TestMainWithConfig: diff --git a/tests/test_inline.py b/tests/test_inline.py index b473a1b..8ac244c 100644 --- a/tests/test_inline.py +++ b/tests/test_inline.py @@ -27,6 +27,13 @@ def fake_download_audio(url, temp_dir, audio_format="mp3"): shutil.copy(FIXTURES / f"silence.{audio_format}", path) return path + def fake_resolve_metadata(artist, title, source_config, runtime): + track = fake_find_spotify(None, artist, title) + metadata = m.get_track_metadata(track, artist, title) + metadata.update(source="spotify", source_id=track.get("id"), score=1.0) + return metadata + + monkeypatch.setattr(m, "resolve_metadata", fake_resolve_metadata) monkeypatch.setattr(m, "find_spotify_track", fake_find_spotify) monkeypatch.setattr(m, "find_youtube_video", lambda a, t: state["video"]) monkeypatch.setattr(m, "download_audio", fake_download_audio) diff --git a/tests/test_metadata_sources.py b/tests/test_metadata_sources.py new file mode 100644 index 0000000..89b2c49 --- /dev/null +++ b/tests/test_metadata_sources.py @@ -0,0 +1,1083 @@ +import argparse +import json +import sys + +import pytest +import requests +from conftest import make_track + +import trackfetch as m + + +def make_args(**overrides): + values = { + "metadata_sources": None, + "disable_sources": None, + "provider_opt": None, + "match_threshold": None, + "title_threshold": None, + } + values.update(overrides) + return argparse.Namespace(**values) + + +def make_config( + sources, + youtube=True, + disabled=(), + thresholds=(0.6, 0.8), + none_selected=False, +): + providers = {} + + for name in m.METADATA_PROVIDERS: + entry = dict(m.PROVIDER_DEFAULTS[name]) + entry["enabled"] = name in sources + entry["disabled"] = name in disabled + providers[name] = entry + + return m.SourceConfig( + sources, + youtube, + providers, + thresholds[0], + thresholds[1], + none_selected, + ) + + +class FakeResponse: + def __init__(self, payload=None, status_code=200, json_error=None): + self.payload = payload + self.status_code = status_code + self.json_error = json_error + + def json(self): + if self.json_error: + raise self.json_error + + return self.payload + + +class FakeSession: + def __init__(self, *responses): + self.responses = list(responses) + self.calls = [] + + def get(self, url, **kwargs): + self.calls.append({"url": url, **kwargs}) + response = self.responses.pop(0) + + if isinstance(response, Exception): + raise response + + return response + + +def make_runtime(session=None, cache=None, health=None): + return m.MetadataRuntime( + session=session or FakeSession(), + cache=cache, + health=health, + limiter=m.RateLimiter( + {name: 0.0 for name in m.METADATA_PROVIDERS} + ), + ) + + +def run_cli(monkeypatch, *args): + monkeypatch.setattr(sys, "argv", ["trackfetch", *map(str, args)]) + m.main() + + +class TestSourceResolution: + def test_default_sources_are_itunes_only(self): + config = m.build_source_config(make_args(), {}) + + assert config.metadata_sources == ["itunes"] + assert config.youtube_enabled is True + assert config.is_enabled("itunes") + assert not config.is_enabled("spotify") + assert not config.is_enabled("deezer") + + def test_custom_priority_is_preserved(self): + config = m.build_source_config( + make_args(metadata_sources="deezer, itunes,musicbrainz"), + {}, + ) + + assert config.metadata_sources == ["deezer", "itunes", "musicbrainz"] + + def test_duplicate_sources_are_removed(self): + config = m.build_source_config( + make_args(metadata_sources="deezer,DEEZER,itunes,deezer"), + {}, + ) + + assert config.metadata_sources == ["deezer", "itunes"] + + def test_unknown_source_is_rejected(self): + with pytest.raises(ValueError, match="Unknown metadata source"): + m.build_source_config( + make_args(metadata_sources="deezer,napster"), + {}, + ) + + def test_youtube_is_not_a_metadata_provider(self): + with pytest.raises(ValueError, match="artwork fallback"): + m.build_source_config( + make_args(metadata_sources="itunes,youtube"), + {}, + ) + + def test_explicit_config_enabling_appends_without_reordering(self): + config = m.build_source_config( + make_args(), + {"deezer_enabled": "true"}, + ) + + assert config.metadata_sources == ["itunes", "deezer"] + + def test_explicit_config_disabling_removes_provider(self): + config = m.build_source_config( + make_args(), + { + "metadata_sources": "deezer,itunes", + "deezer_enabled": "false", + }, + ) + + assert config.metadata_sources == ["itunes"] + + def test_disable_sources_removes_provider(self): + config = m.build_source_config( + make_args(metadata_sources="deezer,itunes", disable_sources="itunes"), + {}, + ) + + assert config.metadata_sources == ["deezer"] + + def test_disable_sources_from_config(self): + config = m.build_source_config( + make_args(metadata_sources="deezer,itunes"), + {"disable_sources": "deezer"}, + ) + + assert config.metadata_sources == ["itunes"] + + def test_cli_sources_override_config_sources(self): + config = m.build_source_config( + make_args(metadata_sources="deezer"), + {"metadata_sources": "itunes,musicbrainz"}, + ) + + assert config.metadata_sources == ["deezer"] + + def test_cli_sources_override_config_enabled_flag(self): + config = m.build_source_config( + make_args(metadata_sources="spotify"), + {"spotify_enabled": "false"}, + ) + + assert config.metadata_sources == ["spotify"] + + def test_none_means_no_metadata_but_youtube_stays(self): + config = m.build_source_config( + make_args(metadata_sources="none"), + {}, + ) + + assert config.metadata_sources == [] + assert config.none_selected is True + assert config.youtube_enabled is True + + def test_none_does_not_append_explicitly_enabled_providers(self): + config = m.build_source_config( + make_args(metadata_sources="none"), + {"deezer_enabled": "true"}, + ) + + assert config.metadata_sources == [] + + def test_youtube_can_be_disabled_by_flag(self): + config = m.build_source_config( + make_args(disable_sources="youtube"), + {}, + ) + + assert config.youtube_enabled is False + + def test_youtube_can_be_disabled_in_config(self): + config = m.build_source_config( + make_args(), + {"youtube_enabled": "false"}, + ) + + assert config.youtube_enabled is False + + def test_provider_options_are_applied(self): + config = m.build_source_config( + make_args( + provider_opt=[ + "itunes.country=ua", + "deezer.min_interval=0.5", + "musicbrainz.min_interval=1.5", + ] + ), + {}, + ) + + assert config.providers["itunes"]["country"] == "ua" + assert config.providers["deezer"]["min_interval"] == 0.5 + assert config.providers["musicbrainz"]["min_interval"] == 1.5 + + def test_provider_opt_can_enable_provider(self): + config = m.build_source_config( + make_args(provider_opt=["vocadb.enabled=true"]), + {}, + ) + + assert config.metadata_sources == ["itunes", "vocadb"] + + def test_malformed_provider_option_is_rejected(self): + for value in ("itunes", "itunes.", "itunes.country", "itunes.country="): + with pytest.raises(ValueError): + m.build_source_config( + make_args(provider_opt=[value]), + {}, + ) + + def test_unknown_provider_option_is_rejected(self): + with pytest.raises(ValueError, match="Unknown provider"): + m.build_source_config( + make_args(provider_opt=["napster.enabled=true"]), + {}, + ) + + with pytest.raises(ValueError, match="Unknown option"): + m.build_source_config( + make_args(provider_opt=["itunes.volume=11"]), + {}, + ) + + def test_invalid_country_is_rejected(self): + with pytest.raises(ValueError, match="two-letter"): + m.build_source_config( + make_args(provider_opt=["itunes.country=ukraine"]), + {}, + ) + + def test_thresholds_are_clamped(self): + config = m.build_source_config( + make_args(match_threshold=5, title_threshold=-3), + {}, + ) + + assert config.match_threshold == 1.0 + assert config.title_threshold == 0.0 + + def test_thresholds_from_config(self): + config = m.build_source_config( + make_args(), + {"match_threshold": "0.4", "title_threshold": "0.7"}, + ) + + assert config.match_threshold == 0.4 + assert config.title_threshold == 0.7 + + +class TestVocadbPromotion: + def test_cjk_promotes_vocadb_temporarily(self): + config = make_config(["itunes", "vocadb"]) + + assert m.effective_metadata_sources(config, "初音ミク", "消失") == [ + "vocadb", + "itunes", + ] + assert config.metadata_sources == ["itunes", "vocadb"] + + def test_vocaloid_hint_promotes_vocadb(self): + config = make_config(["itunes", "vocadb"]) + + assert m.effective_metadata_sources( + config, + "Hatsune Miku", + "Song", + )[0] == "vocadb" + + def test_cjk_adds_vocadb_even_when_not_configured(self): + config = make_config(["itunes"]) + + assert m.effective_metadata_sources(config, "初音ミク", "消失") == [ + "vocadb", + "itunes", + ] + + def test_disabled_vocadb_is_not_promoted(self): + config = make_config(["itunes"], disabled=("vocadb",)) + + assert m.effective_metadata_sources(config, "初音ミク", "消失") == [ + "itunes" + ] + + def test_none_is_not_promoted(self): + config = make_config([], none_selected=True) + + assert m.effective_metadata_sources(config, "初音ミク", "消失") == [] + + def test_promoted_vocadb_is_actually_queried(self, monkeypatch): + calls = [] + + def fake_vocadb(runtime, artist, title, config): + calls.append("vocadb") + return [ + { + "title": "初音ミクの消失", + "artist": "初音ミク", + "source": "vocadb", + } + ] + + def fake_itunes(runtime, artist, title, config): + calls.append("itunes") + return [] + + monkeypatch.setitem(m.PROVIDER_FUNCTIONS, "vocadb", fake_vocadb) + monkeypatch.setitem(m.PROVIDER_FUNCTIONS, "itunes", fake_itunes) + config = make_config(["itunes"]) + runtime = make_runtime() + + result = m.resolve_metadata("初音ミク", "初音ミクの消失", config, runtime) + + assert result["source"] == "vocadb" + assert calls == ["vocadb"] + + +class TestMatching: + def test_exact_match(self): + candidate = {"title": "One More Time", "artist": "Daft Punk"} + + scored = m.select_best_metadata( + [candidate], "Daft Punk", "One More Time", 0.6, 0.8 + ) + + assert scored["score"] == pytest.approx(1.0) + + def test_case_and_punctuation_differences(self): + candidate = {"title": "one more time!", "artist": "DAFT PUNK"} + + assert m.select_best_metadata( + [candidate], "Daft Punk", "One More Time", 0.6, 0.8 + ) + + def test_unicode_title(self): + candidate = {"title": "Мёртвый Анархист", "artist": "Король и Шут"} + + assert m.select_best_metadata( + [candidate], "Король и Шут", "мёртвый анархист", 0.6, 0.8 + ) + + def test_cjk_title(self): + candidate = {"title": "初音ミクの消失", "artist": "初音ミク"} + + assert m.select_best_metadata( + [candidate], "初音ミク", "初音ミクの消失", 0.6, 0.8 + ) + + def test_meaningful_unicode_is_preserved(self): + assert m.normalize("がっこう") == "がっこう" + assert m.normalize("がっこう") != m.normalize("かっこう") + assert m.normalize("Beyoncé") == "beyoncé" + + def test_unrelated_title_is_rejected(self): + candidate = { + "title": "Bohemian Rhapsody", + "artist": "Queen", + } + + assert m.select_best_metadata( + [candidate], "Daft Punk", "One More Time", 0.6, 0.8 + ) is None + + def test_title_threshold_rejects_close_but_short_title(self): + candidate = {"title": "One More Tim", "artist": "Daft Punk"} + + assert m.select_best_metadata( + [candidate], "Daft Punk", "One More Time", 0.0, 0.99 + ) is None + + def test_missing_optional_metadata_does_not_invalidate(self): + candidate = {"title": "One More Time", "artist": "Daft Punk"} + + scored = m.select_best_metadata( + [candidate], "Daft Punk", "One More Time", 0.6, 0.8 + ) + + assert scored + assert scored.get("album") is None + + def test_best_candidate_wins(self): + candidates = [ + {"title": "One More Time (Live)", "artist": "Other"}, + {"title": "One More Time", "artist": "Daft Punk"}, + ] + + scored = m.select_best_metadata( + candidates, "Daft Punk", "One More Time", 0.6, 0.8 + ) + + assert scored["artist"] == "Daft Punk" + + +class TestProviders: + def test_itunes_success_and_country(self): + session = FakeSession( + FakeResponse( + { + "results": [ + { + "trackName": "One More Time", + "artistName": "Daft Punk", + "collectionName": "Discovery", + "releaseDate": "2001-03-12T00:00:00Z", + "trackNumber": 1, + "trackId": 123, + "artworkUrl100": "https://img/100x100bb.jpg", + } + ] + } + ) + ) + runtime = make_runtime(session) + config = make_config(["itunes"]) + + candidates = m.itunes_provider( + runtime, "Daft Punk", "One More Time", config + ) + + assert candidates[0]["title"] == "One More Time" + assert candidates[0]["cover_url"] == "https://img/600x600bb.jpg" + assert candidates[0]["source"] == "itunes" + assert session.calls[0]["params"]["country"] == "us" + + def test_itunes_custom_country(self): + session = FakeSession(FakeResponse({"results": []})) + runtime = make_runtime(session) + config = make_config(["itunes"]) + config.providers["itunes"]["country"] = "ua" + + m.itunes_provider(runtime, "a", "b", config) + + assert session.calls[0]["params"]["country"] == "ua" + + def test_itunes_empty_results(self): + runtime = make_runtime(FakeSession(FakeResponse({"results": []}))) + + assert m.itunes_provider( + runtime, "a", "b", make_config(["itunes"]) + ) == [] + + def test_invalid_json_is_a_provider_error(self): + session = FakeSession(FakeResponse(json_error=ValueError("bad"))) + runtime = make_runtime(session) + + with pytest.raises(m.ProviderError, match="invalid JSON"): + m.itunes_provider(runtime, "a", "b", make_config(["itunes"])) + + def test_network_error_is_a_provider_error(self): + session = FakeSession( + requests.ConnectionError("offline") + ) + runtime = make_runtime(session) + + with pytest.raises(m.ProviderError): + m.itunes_provider(runtime, "a", "b", make_config(["itunes"])) + + def test_timeout_is_a_provider_error(self): + session = FakeSession(requests.Timeout("slow")) + runtime = make_runtime(session) + + with pytest.raises(m.ProviderError, match="timed out"): + m.itunes_provider(runtime, "a", "b", make_config(["itunes"])) + + def test_http_error_is_a_provider_error(self): + runtime = make_runtime(FakeSession(FakeResponse(status_code=500))) + + with pytest.raises(m.ProviderError, match="HTTP 500"): + m.itunes_provider(runtime, "a", "b", make_config(["itunes"])) + + def test_401_and_403_are_auth_errors(self): + for status in (401, 403): + runtime = make_runtime(FakeSession(FakeResponse(status_code=status))) + + with pytest.raises(m.ProviderAuthError): + m.deezer_provider(runtime, "a", "b", make_config(["deezer"])) + + def test_invalid_response_shape(self): + runtime = make_runtime(FakeSession(FakeResponse({"unexpected": True}))) + + with pytest.raises(m.ProviderError, match="invalid response"): + m.itunes_provider(runtime, "a", "b", make_config(["itunes"])) + + def test_deezer_success(self): + session = FakeSession( + FakeResponse( + { + "data": [ + { + "id": 7, + "title": "One More Time", + "artist": {"name": "Daft Punk"}, + "album": { + "title": "Discovery", + "artist": {"name": "Daft Punk"}, + "cover_xl": "https://img/xl.jpg", + }, + } + ] + } + ) + ) + candidates = m.deezer_provider( + make_runtime(session), + "Daft Punk", + "One More Time", + make_config(["deezer"]), + ) + + assert candidates[0]["cover_url"] == "https://img/xl.jpg" + assert candidates[0]["album"] == "Discovery" + + def test_deezer_api_error(self): + runtime = make_runtime( + FakeSession(FakeResponse({"error": {"message": "quota"}})) + ) + + with pytest.raises(m.ProviderError, match="Deezer API error"): + m.deezer_provider(runtime, "a", "b", make_config(["deezer"])) + + def test_musicbrainz_with_cover_art_archive(self): + session = FakeSession( + FakeResponse( + { + "recordings": [ + { + "id": "rec-1", + "title": "One More Time", + "artist-credit": [ + {"name": "Daft Punk", "joinphrase": ""} + ], + "releases": [ + { + "id": "rel-1", + "title": "Discovery", + "date": "2001", + } + ], + } + ] + } + ), + FakeResponse( + { + "images": [ + { + "front": True, + "image": "https://caa/front.jpg", + "width": 1200, + "height": 1200, + } + ] + } + ), + ) + runtime = make_runtime(session) + candidates = m.musicbrainz_provider( + runtime, "Daft Punk", "One More Time", make_config(["musicbrainz"]) + ) + + assert candidates[0]["album"] == "Discovery" + assert candidates[0]["release_date"] == "2001" + assert candidates[0]["cover_url"] == "https://caa/front.jpg" + assert len(session.calls) == 2 + + def test_musicbrainz_missing_cover_is_not_a_failure(self): + session = FakeSession( + FakeResponse( + { + "recordings": [ + { + "id": "rec-1", + "title": "One More Time", + "artist-credit": [{"name": "Daft Punk"}], + "releases": [{"id": "rel-1", "title": "Discovery"}], + } + ] + } + ), + FakeResponse(status_code=404), + ) + runtime = make_runtime(session) + candidates = m.musicbrainz_provider( + runtime, "Daft Punk", "One More Time", make_config(["musicbrainz"]) + ) + + assert candidates[0]["title"] == "One More Time" + assert candidates[0]["cover_url"] is None + + def test_cover_art_lookup_is_memoised(self): + session = FakeSession( + FakeResponse( + { + "images": [ + { + "front": True, + "image": "https://caa/front.jpg", + } + ] + } + ) + ) + runtime = make_runtime(session) + config = make_config(["musicbrainz"]) + + first = m.cover_art_archive_url(runtime, "rel-1", config) + second = m.cover_art_archive_url(runtime, "rel-1", config) + + assert first == second == "https://caa/front.jpg" + assert len(session.calls) == 1 + + def test_vocadb_success_with_unicode(self): + session = FakeSession( + FakeResponse( + { + "items": [ + { + "id": 1, + "name": "初音ミクの消失", + "artistString": "初音ミク", + "publishDate": "2008-01-01", + "albums": [ + { + "name": "Album", + "mainPicture": { + "url": "/img/cover.jpg" + }, + } + ], + } + ] + } + ) + ) + candidates = m.vocadb_provider( + make_runtime(session), + "初音ミク", + "初音ミクの消失", + make_config(["vocadb"]), + ) + + assert candidates[0]["title"] == "初音ミクの消失" + assert candidates[0]["artist"] == "初音ミク" + assert candidates[0]["cover_url"] == "https://vocadb.net/img/cover.jpg" + + def test_spotify_missing_credentials_is_quiet(self, monkeypatch, capsys): + monkeypatch.delenv("SPOTIFY_CLIENT_ID", raising=False) + monkeypatch.delenv("SPOTIFY_CLIENT_SECRET", raising=False) + runtime = make_runtime() + + assert m.spotify_provider( + runtime, "a", "b", make_config(["spotify"]) + ) == [] + assert capsys.readouterr().out == "" + + def test_spotify_401_sets_600_second_cooldown(self, monkeypatch): + class Unauthorized(Exception): + http_status = 401 + + class BadSpotify: + def search(self, **kwargs): + raise Unauthorized("unauthorized") + + runtime = make_runtime() + runtime.spotify_client = BadSpotify() + runtime.spotify_initialized = True + config = make_config(["spotify"]) + + result = m.resolve_metadata("a", "b", config, runtime) + + assert result["source"] == "input" + assert runtime.health.in_cooldown("spotify") + assert runtime.health.state("spotify")["cooldown_seconds"] == 600.0 + + +class TestRateLimiting: + def test_independent_provider_intervals(self, monkeypatch): + now = [0.0] + sleeps = [] + + def fake_sleep(seconds): + sleeps.append(seconds) + now[0] += seconds + + monkeypatch.setattr(m.time, "sleep", fake_sleep) + limiter = m.RateLimiter( + {"itunes": 3.0, "deezer": 0.25}, + clock=lambda: now[0], + ) + + limiter.wait("itunes") + now[0] += 1.0 + limiter.wait("deezer") + assert sleeps == [] + + now[0] += 0.5 + limiter.wait("itunes") + assert sleeps == [pytest.approx(1.5)] + + def test_custom_intervals(self, monkeypatch): + now = [0.0] + sleeps = [] + + def fake_sleep(seconds): + sleeps.append(seconds) + now[0] += seconds + + monkeypatch.setattr(m.time, "sleep", fake_sleep) + limiter = m.RateLimiter({"deezer": 2.0}, clock=lambda: now[0]) + + limiter.wait("deezer") + limiter.wait("deezer") + + assert sleeps == [pytest.approx(2.0)] + + def test_zero_interval_never_blocks(self, monkeypatch): + sleeps = [] + monkeypatch.setattr(m.time, "sleep", sleeps.append) + limiter = m.RateLimiter({"vocadb": 0.0}) + + limiter.wait("vocadb") + limiter.wait("vocadb") + + assert sleeps == [] + + +class TestFailureRecovery: + def test_two_failures_start_thirty_second_cooldown(self): + now = [0.0] + health = m.ProviderHealth(clock=lambda: now[0]) + + health.record_failure("deezer") + assert not health.in_cooldown("deezer") + + health.record_failure("deezer") + assert health.in_cooldown("deezer") + assert health.state("deezer")["cooldown_seconds"] == 30.0 + + def test_cooldown_doubles_and_caps(self): + now = [0.0] + health = m.ProviderHealth(clock=lambda: now[0]) + + health.record_failure("deezer") + health.record_failure("deezer") + + expected = [30.0, 60.0, 120.0, 240.0, 480.0, 600.0] + + for cooldown in expected[1:]: + now[0] += health.state("deezer")["cooldown_seconds"] + health.record_failure("deezer") + assert health.state("deezer")["cooldown_seconds"] == cooldown + + def test_retry_after_cooldown(self): + now = [0.0] + health = m.ProviderHealth(clock=lambda: now[0]) + health.record_failure("deezer") + health.record_failure("deezer") + + now[0] += 29.0 + assert health.in_cooldown("deezer") + + now[0] += 2.0 + assert not health.in_cooldown("deezer") + + def test_success_resets_failure_count(self): + health = m.ProviderHealth() + health.record_failure("deezer") + health.record_success("deezer") + + assert health.failures("deezer") == 0 + assert not health.in_cooldown("deezer") + + def test_empty_results_do_not_count_as_failures(self, monkeypatch): + runtime = make_runtime(FakeSession(FakeResponse({"results": []}))) + config = make_config(["itunes"]) + + result = m.resolve_metadata("a", "b", config, runtime) + + assert result["source"] == "input" + assert runtime.health.failures("itunes") == 0 + + def test_priority_is_restored_after_recovery(self, monkeypatch, tmp_path): + now = [0.0] + calls = [] + state = {"deezer_ok": False} + + def fake_deezer(runtime, artist, title, config): + calls.append("deezer") + + if not state["deezer_ok"]: + raise m.ProviderError("offline") + + return [ + { + "title": "One More Time", + "artist": "Daft Punk", + "album": "Discovery", + "source": "deezer", + } + ] + + def fake_itunes(runtime, artist, title, config): + calls.append("itunes") + return [ + { + "title": "One More Time", + "artist": "Daft Punk", + "album": "Discovery", + "source": "itunes", + } + ] + + monkeypatch.setitem(m.PROVIDER_FUNCTIONS, "deezer", fake_deezer) + monkeypatch.setitem(m.PROVIDER_FUNCTIONS, "itunes", fake_itunes) + + health = m.ProviderHealth(clock=lambda: now[0]) + cache = m.MetadataCache(tmp_path / m.CACHE_FILENAME) + runtime = make_runtime(cache=cache, health=health) + config = make_config(["deezer", "itunes"]) + + assert m.resolve_metadata("Daft Punk", "One More Time", config, runtime)["source"] == "itunes" + assert m.resolve_metadata("Daft Punk", "One More Time", config, runtime)["source"] == "itunes" + assert health.in_cooldown("deezer") + + state["deezer_ok"] = True + now[0] += 31.0 + + result = m.resolve_metadata("Daft Punk", "One More Time", config, runtime) + + assert result["source"] == "deezer" + assert calls[-1] == "deezer" + assert health.failures("deezer") == 0 + + +class TestMetadataCache: + def test_cache_is_created_and_read(self, tmp_path): + path = tmp_path / m.CACHE_FILENAME + cache = m.MetadataCache(path) + cache.set( + "Daft Punk", + "One More Time", + "itunes", + { + "title": "One More Time", + "artist": "Daft Punk", + "source": "itunes", + }, + ) + + assert path.is_file() + assert m.MetadataCache(path).get( + "daft punk", "one more time", "itunes" + )["title"] == "One More Time" + + def test_entries_are_independent_per_provider(self, tmp_path): + cache = m.MetadataCache(tmp_path / m.CACHE_FILENAME) + cache.set("A", "B", "itunes", {"title": "B", "source": "itunes"}) + cache.set("A", "B", "deezer", {"title": "B", "source": "deezer"}) + + assert cache.get("A", "B", "itunes")["source"] == "itunes" + assert cache.get("A", "B", "deezer")["source"] == "deezer" + + def test_corrupted_cache_is_handled(self, tmp_path): + path = tmp_path / m.CACHE_FILENAME + path.write_text("not json at all", encoding="utf-8") + + cache = m.MetadataCache(path) + + assert cache.entries == {} + assert cache.get("A", "B", "itunes") is None + + def test_invalid_cache_shape_is_handled(self, tmp_path): + path = tmp_path / m.CACHE_FILENAME + path.write_text(json.dumps({"entries": []}), encoding="utf-8") + + assert m.MetadataCache(path).entries == {} + + def test_cached_priority_result_is_used(self, monkeypatch, tmp_path): + calls = [] + + def fake_itunes(runtime, artist, title, config): + calls.append("itunes") + return [ + { + "title": "One More Time", + "artist": "Daft Punk", + "source": "itunes", + } + ] + + monkeypatch.setitem(m.PROVIDER_FUNCTIONS, "itunes", fake_itunes) + cache = m.MetadataCache(tmp_path / m.CACHE_FILENAME) + runtime = make_runtime(cache=cache) + config = make_config(["itunes"]) + + first = m.resolve_metadata("Daft Punk", "One More Time", config, runtime) + second = m.resolve_metadata("Daft Punk", "One More Time", config, runtime) + + assert first["source"] == "itunes" + assert second["source"] == "itunes" + assert calls == ["itunes"] + + +class TestArtwork: + def test_itunes_artwork_is_upscaled(self): + assert m.upscale_itunes_artwork( + "https://img/100x100bb.jpg" + ) == "https://img/600x600bb.jpg" + + def test_youtube_thumbnail_prefers_largest(self): + video = { + "thumbnails": [ + {"url": "small", "width": 120, "height": 90}, + {"url": "large", "width": 1280, "height": 720}, + ] + } + + assert m.youtube_thumbnail_urls(video)[0] == "large" + + def test_youtube_thumbnail_from_id(self): + urls = m.youtube_thumbnail_urls({"id": "abc"}) + + assert urls[0] == "https://i.ytimg.com/vi/abc/maxresdefault.jpg" + + def test_image_validation(self): + assert m.is_image_bytes(b"\xff\xd8\xff\xe0data") + assert m.is_image_bytes(b"\x89PNG\r\n\x1a\n") + assert not m.is_image_bytes(b"not an image") + assert not m.is_image_bytes(b"") + + +class TestCli: + def test_list_sources_does_not_need_input(self, monkeypatch, capsys): + run_cli(monkeypatch, "--list-sources") + + output = capsys.readouterr().out + assert "itunes" in output + assert "youtube" in output + assert "Metadata priority: itunes" in output + + def test_list_sources_reflects_cli_priority(self, monkeypatch, capsys): + run_cli( + monkeypatch, + "-s", + "deezer,itunes", + "--list-sources", + ) + + assert "Metadata priority: deezer, itunes" in capsys.readouterr().out + + def test_unknown_metadata_source_exits(self, monkeypatch, capsys): + with pytest.raises(SystemExit) as exc: + run_cli(monkeypatch, "-s", "napster", "--list-sources") + + assert exc.value.code == 1 + assert "Unknown metadata source" in capsys.readouterr().out + + def test_malformed_provider_option_exits(self, monkeypatch, capsys): + with pytest.raises(SystemExit) as exc: + run_cli(monkeypatch, "--provider-opt", "itunes.country", "--list-sources") + + assert exc.value.code == 1 + assert "Invalid --provider-opt" in capsys.readouterr().out + + def test_thresholds_are_shown_and_clamped(self, monkeypatch, capsys): + run_cli( + monkeypatch, + "--match-threshold", + "5", + "--title-threshold", + "-1", + "--list-sources", + ) + + output = capsys.readouterr().out + assert "Match threshold: 1.0" in output + assert "Title threshold: 0.0" in output + + def test_invalid_threshold_type_is_rejected_by_argparse( + self, monkeypatch, capsys + ): + with pytest.raises(SystemExit) as exc: + run_cli(monkeypatch, "--match-threshold", "abc", "--list-sources") + + assert exc.value.code == 2 + + +class TestYoutubeFallback: + def test_youtube_disabled_prevents_download(self, monkeypatch, tmp_path): + calls = [] + monkeypatch.setattr( + m, + "find_youtube_video", + lambda artist, title: calls.append((artist, title)), + ) + config = make_config([], youtube=False, none_selected=True) + + ok, reason = m.process_song( + None, + "Daft Punk", + "One More Time", + tmp_path, + False, + "m4a", + source_config=config, + runtime=make_runtime(), + ) + + assert (ok, reason) == (False, "YouTube disabled") + assert calls == [] + + def test_none_metadata_still_uses_youtube(self, monkeypatch, tmp_path): + from conftest import FIXTURES + import shutil + + video = {"title": "A - B", "id": "abc"} + monkeypatch.setattr(m, "find_youtube_video", lambda a, t: video) + monkeypatch.setattr( + m, + "download_audio", + lambda url, temp_dir, fmt: shutil.copy( + FIXTURES / f"silence.{fmt}", + temp_dir / f"audio.{fmt}", + ), + ) + monkeypatch.setattr( + m, + "download_cover", + lambda url, dest: dest.write_bytes(b"\xff\xd8\xff\xe0jpeg"), + ) + config = make_config([], none_selected=True) + + ok, reason = m.process_song( + None, + "A", + "B", + tmp_path, + False, + "m4a", + source_config=config, + runtime=make_runtime(), + ) + + assert (ok, reason) == (True, "downloaded") + assert (tmp_path / "A - B.m4a").exists() diff --git a/tests/test_pipeline.py b/tests/test_pipeline.py index a094fe9..60e66c7 100644 --- a/tests/test_pipeline.py +++ b/tests/test_pipeline.py @@ -44,6 +44,17 @@ def fake_download_cover(url, dest): raise OSError("cover unavailable") dest.write_bytes(b"\xff\xd8\xff\xe0jpeg") + def fake_resolve_metadata(artist, title, source_config, runtime): + track = m.find_spotify_track(None, artist, title) + + if track is None: + return m.fallback_metadata(artist, title) + + metadata = m.get_track_metadata(track, artist, title) + metadata.update(source="spotify", source_id=track.get("id"), score=1.0) + return metadata + + monkeypatch.setattr(m, "resolve_metadata", fake_resolve_metadata) monkeypatch.setattr(m, "find_spotify_track", fake_find_spotify) monkeypatch.setattr(m, "find_youtube_video", lambda artist, title: state["video"]) monkeypatch.setattr(m, "download_audio", fake_download_audio) diff --git a/tests/test_spotify.py b/tests/test_spotify.py index 233e2c9..754b030 100644 --- a/tests/test_spotify.py +++ b/tests/test_spotify.py @@ -5,19 +5,18 @@ class TestGetSpotify: - def test_exits_without_credentials(self, monkeypatch, capsys): + def test_returns_none_without_credentials(self, monkeypatch, capsys): monkeypatch.delenv("SPOTIFY_CLIENT_ID", raising=False) monkeypatch.delenv("SPOTIFY_CLIENT_SECRET", raising=False) - with pytest.raises(SystemExit) as exc: - m.get_spotify() - assert exc.value.code == 1 - assert "credentials not found" in capsys.readouterr().out - def test_exits_with_only_one_credential(self, monkeypatch): + assert m.get_spotify() is None + assert capsys.readouterr().out == "" + + def test_returns_none_with_only_one_credential(self, monkeypatch): monkeypatch.setenv("SPOTIFY_CLIENT_ID", "id") monkeypatch.delenv("SPOTIFY_CLIENT_SECRET", raising=False) - with pytest.raises(SystemExit): - m.get_spotify() + + assert m.get_spotify() is None def test_builds_client(self, monkeypatch): monkeypatch.setenv("SPOTIFY_CLIENT_ID", "id") diff --git a/trackfetch.py b/trackfetch.py index 7bad64e..5c376d6 100755 --- a/trackfetch.py +++ b/trackfetch.py @@ -55,9 +55,91 @@ ], } +VERSION = "2.2.6" +USER_AGENT = ( + f"trackfetch/{VERSION} " + "(https://github.com/ByteMe6/trackfetch)" +) + +METADATA_PROVIDERS = ( + "spotify", + "itunes", + "deezer", + "musicbrainz", + "vocadb", +) +ARTWORK_FALLBACKS = ("youtube",) +DEFAULT_METADATA_SOURCES = ("itunes",) + +PROVIDER_DEFAULTS = { + "spotify": { + "enabled": False, + "min_interval": 0.0, + }, + "itunes": { + "enabled": True, + "min_interval": 3.0, + "country": "us", + }, + "deezer": { + "enabled": False, + "min_interval": 0.25, + }, + "musicbrainz": { + "enabled": False, + "min_interval": 1.1, + }, + "vocadb": { + "enabled": False, + "min_interval": 0.5, + }, +} + +DEFAULT_MATCH_THRESHOLD = 0.6 +DEFAULT_TITLE_THRESHOLD = 0.8 +YOUTUBE_DEFAULT_ENABLED = True + +CACHE_FILENAME = "metadata-cache.json" +CACHE_VERSION = 1 + +PROVIDER_OPTIONS = { + "spotify": {"enabled", "min_interval"}, + "itunes": {"enabled", "min_interval", "country"}, + "deezer": {"enabled", "min_interval"}, + "musicbrainz": {"enabled", "min_interval"}, + "vocadb": {"enabled", "min_interval"}, +} + +CJK_RE = re.compile( + r"[\u3040-\u30ff\u3400-\u4dbf\u4e00-\u9fff" + r"\uf900-\ufaff\uac00-\ud7af]" +) +VOCALOID_HINTS = ( + "vocaloid", + "hatsune miku", + "初音ミク", + "镜音", + "鏡音", + "巡音", + "gumi", + "ia ", + "kaito", + "meiko", + "v flower", +) + + +class ProviderError(Exception): + """A provider request failed for a real, retryable reason.""" + + +class ProviderAuthError(ProviderError): + """A provider rejected the credentials.""" + def normalize(text: str) -> str: - text = unicodedata.normalize("NFKD", text).lower() + # NFC keeps meaningful Unicode characters (CJK, accented letters) intact. + text = unicodedata.normalize("NFC", text).lower() text = re.sub(r"[^\w\s]", " ", text) text = re.sub(r"\s+", " ", text) return text.strip() @@ -71,285 +153,1638 @@ def similarity(a: str, b: str) -> float: ).ratio() -def sanitize_filename(name: str) -> str: - name = re.sub(r'[<>:"/\\|?*\x00-\x1f]', "_", name) - name = re.sub(r"\s+", " ", name).strip() +def artist_similarity(input_artist: str, candidate_artist: str) -> float: + """Compare an artist while allowing providers to list several artists.""" + if not candidate_artist: + return 0.0 - encoded = name.encode("utf-8") + best = similarity(input_artist, candidate_artist) - if len(encoded) > MAX_FILENAME_BYTES: - encoded = encoded[:MAX_FILENAME_BYTES] - name = encoded.decode("utf-8", errors="ignore") + for part in re.split(r"[,;&/]| feat\.? | featuring ", candidate_artist): + part = part.strip() - return name + if part: + best = max(best, similarity(input_artist, part)) + return best -def parse_song(line: str): - if " - " not in line: + +def score_metadata( + input_artist: str, + input_title: str, + candidate: dict, + match_threshold: float, + title_threshold: float, +): + """Return a copy of the candidate with a score, or None if it is too weak.""" + candidate_title = candidate.get("title") or "" + + if not candidate_title: return None - artist, title = line.split(" - ", 1) + title_score = similarity(input_title, candidate_title) - artist = artist.strip() - title = title.strip() + if title_score < title_threshold: + return None - if not artist or not title: + artist_score = artist_similarity( + input_artist, + candidate.get("artist") or "", + ) + overall = title_score * 0.70 + artist_score * 0.30 + + if overall < match_threshold: return None - return artist, title + scored = dict(candidate) + scored["score"] = overall + scored["title_score"] = title_score + scored["artist_score"] = artist_score + return scored -def spotify_credentials(args=None): - """Spotify credentials: flag > config file > environment variable.""" - client_id = None - client_secret = None - if args is not None: - client_id = getattr(args, "spotify_client_id", None) - client_secret = getattr(args, "spotify_client_secret", None) +def select_best_metadata( + candidates, + input_artist: str, + input_title: str, + match_threshold: float, + title_threshold: float, +): + """Pick the highest scoring candidate that passes both thresholds.""" + best = None - client_id = client_id or os.getenv("SPOTIFY_CLIENT_ID") - client_secret = client_secret or os.getenv("SPOTIFY_CLIENT_SECRET") + for candidate in candidates or []: + if not isinstance(candidate, dict): + continue - return client_id, client_secret + scored = score_metadata( + input_artist, + input_title, + candidate, + match_threshold, + title_threshold, + ) + if scored is None: + continue -def get_spotify(args=None): - client_id, client_secret = spotify_credentials(args) + if best is None or scored["score"] > best["score"]: + best = scored - if not client_id or not client_secret: - print("\nERROR: Spotify credentials not found.") - print("Set them in the config file:") - print("[trackfetch]") - print("spotify_client_id = '...'") - print("spotify_client_secret = '...'") - print("or in the environment:") - print("export SPOTIFY_CLIENT_ID='...'") - print("export SPOTIFY_CLIENT_SECRET='...'") - sys.exit(1) + return best - return spotipy.Spotify( - auth_manager=SpotifyClientCredentials( - client_id=client_id, - client_secret=client_secret, - ), - requests_timeout=30, - retries=3, + +def fallback_metadata(artist: str, title: str) -> dict: + return { + "artist": artist, + "title": title, + "album": "", + "album_artist": artist, + "track_number": None, + "release_date": None, + "cover_url": None, + "source": "input", + "source_id": None, + "score": 0.0, + } + + +class SourceConfig: + """The resolved, immutable-in-practice source configuration for one run.""" + + def __init__( + self, + metadata_sources, + youtube_enabled, + providers, + match_threshold, + title_threshold, + none_selected=False, + ): + self.metadata_sources = list(metadata_sources) + self.youtube_enabled = bool(youtube_enabled) + self.providers = providers + self.match_threshold = match_threshold + self.title_threshold = title_threshold + self.none_selected = bool(none_selected) + + def interval(self, name: str) -> float: + return self.providers[name]["min_interval"] + + def is_enabled(self, name: str) -> bool: + return bool(self.providers[name].get("enabled")) + + +def split_source_names(value: str): + return [ + item.strip().lower() + for item in (value or "").split(",") + if item.strip() + ] + + +def normalize_metadata_sources(value: str): + """Validate and de-duplicate a metadata provider list, preserving order.""" + names = [] + + for name in split_source_names(value): + if name in ARTWORK_FALLBACKS: + raise ValueError( + f"'{name}' is an artwork fallback, not a metadata provider" + ) + + if name not in METADATA_PROVIDERS: + raise ValueError( + f"Unknown metadata source '{name}' " + f"(choose from {', '.join(METADATA_PROVIDERS)} or none)" + ) + + if name not in names: + names.append(name) + + return names + + +def normalize_disable_sources(value: str): + names = [] + + for name in split_source_names(value): + if name not in METADATA_PROVIDERS and name not in ARTWORK_FALLBACKS: + raise ValueError( + f"Unknown source '{name}' " + f"(choose from {', '.join(METADATA_PROVIDERS + ARTWORK_FALLBACKS)})" + ) + + if name not in names: + names.append(name) + + return names + + +def parse_bool(value: str, label: str) -> bool: + lowered = (value or "").strip().lower() + + if lowered in ("1", "true", "yes", "on"): + return True + + if lowered in ("0", "false", "no", "off"): + return False + + raise ValueError( + f"Invalid boolean for '{label}': {value!r} " + "(use true or false)" ) -def find_spotify_track(sp, artist: str, title: str): - query = f'artist:"{artist}" track:"{title}"' +def parse_interval(value: str, label: str) -> float: + try: + interval = float(value) + + except (TypeError, ValueError) as error: + raise ValueError( + f"Invalid number for '{label}': {value!r}" + ) from error + + if interval < 0: + raise ValueError(f"'{label}' must not be negative: {value!r}") + + return interval + + +def parse_provider_options(values): + """Parse --provider-opt NAME.KEY=VALUE arguments into typed settings.""" + options = [] + + for raw in values or []: + text = str(raw).strip() + + if "=" not in text: + raise ValueError( + f"Invalid --provider-opt '{raw}': expected NAME.KEY=VALUE" + ) + + target, value = text.split("=", 1) + + if "." not in target: + raise ValueError( + f"Invalid --provider-opt '{raw}': expected NAME.KEY=VALUE" + ) + + name, key = target.split(".", 1) + name = name.strip().lower() + key = key.strip().lower() + value = value.strip() + + if name not in METADATA_PROVIDERS: + raise ValueError( + f"Unknown provider in --provider-opt: '{name}' " + f"(choose from {', '.join(METADATA_PROVIDERS)})" + ) + + if key not in PROVIDER_OPTIONS[name]: + allowed = ", ".join(sorted(PROVIDER_OPTIONS[name])) + raise ValueError( + f"Unknown option '{key}' for provider '{name}' " + f"(choose from {allowed})" + ) + + if value == "": + raise ValueError( + f"Empty value in --provider-opt '{raw}'" + ) + + if key == "enabled": + parsed = parse_bool(value, f"{name}.{key}") + + elif key == "min_interval": + parsed = parse_interval(value, f"{name}.{key}") + + else: + parsed = value.lower() + + options.append((name, key, parsed)) + + return options + + +def threshold_value(value, default: float, label: str) -> float: + if value is None: + return default try: - results = sp.search( - q=query, - type="track", - limit=10, + number = float(value) + + except (TypeError, ValueError) as error: + raise ValueError(f"Invalid value for '{label}': {value!r}") from error + + return min(1.0, max(0.0, number)) + + +def build_source_config(args, settings): + """Resolve CLI flags, config settings and built-in defaults. + + Precedence is CLI > config.ini > built-in defaults. The result does not + permanently change any user configuration. + """ + settings = settings or {} + + providers = {} + config_enabled = set() + config_disabled = set() + + for name in METADATA_PROVIDERS: + defaults = PROVIDER_DEFAULTS[name] + entry = dict(defaults) + entry["disabled"] = False + + enabled_key = f"{name}_enabled" + interval_key = f"{name}_min_interval" + + if enabled_key in settings and str(settings[enabled_key]).strip(): + enabled = parse_bool(settings[enabled_key], enabled_key) + entry["enabled"] = enabled + + if enabled: + config_enabled.add(name) + else: + config_disabled.add(name) + + if interval_key in settings and str(settings[interval_key]).strip(): + entry["min_interval"] = parse_interval( + settings[interval_key], + interval_key, + ) + + if name == "itunes" and settings.get("itunes_country", "").strip(): + country = settings["itunes_country"].strip().lower() + + if not re.fullmatch(r"[a-z]{2}", country): + raise ValueError( + f"Invalid value for 'itunes_country': " + f"{settings['itunes_country']!r} (use a two-letter code)" + ) + + entry["country"] = country + + providers[name] = entry + + cli_enabled = set() + cli_disabled = set() + + for name, key, value in parse_provider_options( + getattr(args, "provider_opt", None) + ): + if key == "enabled": + providers[name]["enabled"] = value + + if value: + cli_enabled.add(name) + cli_disabled.discard(name) + else: + cli_disabled.add(name) + cli_enabled.discard(name) + + elif key == "min_interval": + providers[name]["min_interval"] = value + + elif key == "country": + if not re.fullmatch(r"[a-z]{2}", value): + raise ValueError( + f"Invalid value for '{name}.country': {value!r} " + "(use a two-letter code)" + ) + + providers[name]["country"] = value + + cli_raw = getattr(args, "metadata_sources", None) + cli_sources_given = cli_raw is not None + raw_sources = ( + cli_raw + if cli_sources_given + else config_str_value(settings, "metadata_sources") + ) + + none_selected = False + + if raw_sources is None: + sources = list(DEFAULT_METADATA_SOURCES) + + elif (raw_sources or "").strip().lower() == "none": + sources = [] + none_selected = True + + else: + sources = normalize_metadata_sources(raw_sources) + + disabled_sources = set() + + for raw in ( + config_str_value(settings, "disable_sources"), + getattr(args, "disable_sources", None), + ): + if raw: + disabled_sources.update(normalize_disable_sources(raw)) + + remove = set(disabled_sources) | set(cli_disabled) + + if not cli_sources_given: + remove.update(config_disabled) + + sources = [name for name in sources if name not in remove] + + if not none_selected: + append_enabled = set(cli_enabled) + + if not cli_sources_given: + append_enabled.update(config_enabled) + + for name in METADATA_PROVIDERS: + if name in append_enabled and name not in sources and name not in remove: + sources.append(name) + + for name in METADATA_PROVIDERS: + providers[name]["enabled"] = name in sources + providers[name]["disabled"] = name in remove + + youtube_enabled = YOUTUBE_DEFAULT_ENABLED + + if "youtube_enabled" in settings and str(settings["youtube_enabled"]).strip(): + youtube_enabled = parse_bool( + settings["youtube_enabled"], + "youtube_enabled", ) - except Exception as error: - print(f"WARNING: Spotify search error: {error}") - return None - tracks = results.get("tracks", {}).get("items", []) + if "youtube" in disabled_sources: + youtube_enabled = False + + match_threshold = threshold_value( + getattr(args, "match_threshold", None), + threshold_value( + settings.get("match_threshold"), + DEFAULT_MATCH_THRESHOLD, + "match_threshold", + ), + "match_threshold", + ) + title_threshold = threshold_value( + getattr(args, "title_threshold", None), + threshold_value( + settings.get("title_threshold"), + DEFAULT_TITLE_THRESHOLD, + "title_threshold", + ), + "title_threshold", + ) + + return SourceConfig( + sources, + youtube_enabled, + providers, + match_threshold, + title_threshold, + none_selected, + ) + + +def has_vocadb_hint(artist: str, title: str) -> bool: + text = f"{artist} {title}" + lowered = text.lower() + + if CJK_RE.search(text): + return True + + return any(hint in lowered for hint in VOCALOID_HINTS) + + +def effective_metadata_sources(config: SourceConfig, artist: str, title: str): + """Apply the temporary VocaDB promotion without changing the config.""" + sources = [ + name + for name in config.metadata_sources + if config.is_enabled(name) + ] + vocadb = config.providers["vocadb"] + + if config.none_selected: + # An explicit empty list such as `-s none` stays empty. + return [] + + if not has_vocadb_hint(artist, title) or vocadb.get("disabled"): + return sources + + if "vocadb" in sources: + sources.remove("vocadb") + + return ["vocadb", *sources] + + +def format_source_list(config: SourceConfig) -> str: + lines = ["Available sources:", "", "Metadata providers:"] + + for name in METADATA_PROVIDERS: + entry = config.providers[name] + status = "enabled" if entry.get("enabled") else "disabled" + credentials = "required" if name == "spotify" else "not required" + details = [f"min_interval={entry['min_interval']}s"] + + if name == "itunes": + details.insert(0, f"country={entry.get('country', 'us')}") + + lines.append( + f" {name:<12} {status:<9} credentials: {credentials:<13} " + f"{', '.join(details)}" + ) + + lines.extend(["", "Artwork fallbacks:"]) + + for name in ARTWORK_FALLBACKS: + status = "enabled" if config.youtube_enabled else "disabled" + lines.append( + f" {name:<12} {status:<9} credentials: not required " + f"used when metadata has no artwork" + ) + + lines.extend( + [ + "", + f"Metadata priority: {', '.join(config.metadata_sources) or 'none'}", + f"Match threshold: {config.match_threshold}", + f"Title threshold: {config.title_threshold}", + ] + ) + + return "\n".join(lines) + + +class ProviderHealth: + """Per-provider consecutive-failure and cooldown tracking.""" + + INITIAL_COOLDOWN = 30.0 + MAX_COOLDOWN = 600.0 + + def __init__(self, clock=None): + self.clock = clock or (lambda: time.monotonic()) + self.states = {} + + def state(self, name: str) -> dict: + return self.states.setdefault( + name, + { + "failures": 0, + "cooldown_until": 0.0, + "cooldown_seconds": 0.0, + }, + ) + + def failures(self, name: str) -> int: + return self.state(name)["failures"] + + def in_cooldown(self, name: str) -> bool: + return self.state(name)["cooldown_until"] > self.clock() + + def record_success(self, name: str): + state = self.state(name) + state["failures"] = 0 + state["cooldown_until"] = 0.0 + state["cooldown_seconds"] = 0.0 + + def record_failure(self, name: str): + state = self.state(name) + state["failures"] += 1 + + if state["failures"] < 2: + return + + previous = state["cooldown_seconds"] + + if previous <= 0: + cooldown = self.INITIAL_COOLDOWN + else: + cooldown = min(previous * 2, self.MAX_COOLDOWN) + + state["cooldown_seconds"] = cooldown + state["cooldown_until"] = self.clock() + cooldown + + def force_cooldown(self, name: str, seconds: float): + state = self.state(name) + state["cooldown_seconds"] = seconds + state["cooldown_until"] = self.clock() + seconds + + +class RateLimiter: + """Independent minimum request interval per provider.""" + + def __init__(self, intervals=None, clock=None): + self.intervals = dict(intervals or {}) + self.clock = clock or (lambda: time.monotonic()) + self.last_request = {} + + def wait(self, name: str): + interval = self.intervals.get(name, 0.0) + + if interval <= 0: + self.last_request[name] = self.clock() + return + + last = self.last_request.get(name) + + if last is not None: + remaining = interval - (self.clock() - last) + + if remaining > 0: + time.sleep(remaining) + + self.last_request[name] = self.clock() + + +class MetadataCache: + """Per-provider metadata cache stored next to the downloaded files.""" + + def __init__(self, path: Path): + self.path = Path(path) + self.entries = {} + self.load() + + @staticmethod + def key(artist: str, title: str) -> str: + return f"{normalize(artist)}|{normalize(title)}" + + def load(self): + if not self.path.is_file(): + return - if not tracks: try: - results = sp.search( - q=f"{artist} {title}", - type="track", - limit=10, - ) + data = json.loads(self.path.read_text(encoding="utf-8")) + + except (OSError, ValueError, TypeError): + self.entries = {} + return + + if not isinstance(data, dict): + self.entries = {} + return + + entries = data.get("entries") + + if not isinstance(entries, dict): + self.entries = {} + return + + self.entries = entries + + def save(self): + payload = { + "version": CACHE_VERSION, + "entries": self.entries, + } + + try: + self.path.parent.mkdir(parents=True, exist_ok=True) + self.path.write_text( + json.dumps( + payload, + ensure_ascii=False, + indent=2, + sort_keys=True, + ) + "\n", + encoding="utf-8", + ) + + except OSError: + pass + + def get(self, artist: str, title: str, provider: str): + entry = self.entries.get(self.key(artist, title)) + + if not isinstance(entry, dict): + return None + + result = entry.get(provider) + + if not isinstance(result, dict) or not result.get("title"): + return None + + return dict(result) + + def set(self, artist: str, title: str, provider: str, result: dict): + key = self.key(artist, title) + entry = self.entries.get(key) + + if not isinstance(entry, dict): + entry = {} + + stored = { + field: result.get(field) + for field in ( + "title", + "artist", + "album", + "album_artist", + "track_number", + "release_date", + "cover_url", + "source", + "source_id", + "score", + ) + } + entry[provider] = stored + self.entries[key] = entry + self.save() + + +def sanitize_filename(name: str) -> str: + name = re.sub(r'[<>:"/\\|?*\x00-\x1f]', "_", name) + name = re.sub(r"\s+", " ", name).strip() + + encoded = name.encode("utf-8") + + if len(encoded) > MAX_FILENAME_BYTES: + encoded = encoded[:MAX_FILENAME_BYTES] + name = encoded.decode("utf-8", errors="ignore") + + return name + + +def parse_song(line: str): + if " - " not in line: + return None + + artist, title = line.split(" - ", 1) + + artist = artist.strip() + title = title.strip() + + if not artist or not title: + return None + + return artist, title + + +def spotify_credentials(args=None): + """Spotify credentials: flag > config file > environment variable.""" + client_id = None + client_secret = None + + if args is not None: + client_id = getattr(args, "spotify_client_id", None) + client_secret = getattr(args, "spotify_client_secret", None) + + client_id = client_id or os.getenv("SPOTIFY_CLIENT_ID") + client_secret = client_secret or os.getenv("SPOTIFY_CLIENT_SECRET") + + return client_id, client_secret + + +def get_spotify(args=None): + """Build a Spotify client, or return None quietly without credentials.""" + client_id, client_secret = spotify_credentials(args) + + if not client_id or not client_secret: + return None + + return spotipy.Spotify( + auth_manager=SpotifyClientCredentials( + client_id=client_id, + client_secret=client_secret, + ), + requests_timeout=30, + retries=3, + ) + + +def find_spotify_track( + sp, + artist: str, + title: str, + raise_errors: bool = False, +): + query = f'artist:"{artist}" track:"{title}"' + + try: + results = sp.search( + q=query, + type="track", + limit=10, + ) + except Exception as error: + if raise_errors: + raise + + print(f"WARNING: Spotify search error: {error}") + return None + + tracks = results.get("tracks", {}).get("items", []) + + if not tracks: + try: + results = sp.search( + q=f"{artist} {title}", + type="track", + limit=10, + ) tracks = results.get("tracks", {}).get("items", []) except Exception: + if raise_errors: + raise + return None - if not tracks: - return None + if not tracks: + return None + + best_track = None + best_score = -1.0 + + for track in tracks: + spotify_title = track["name"] + spotify_artists = " ".join( + item["name"] + for item in track["artists"] + ) + + title_score = similarity(title, spotify_title) + artist_score = similarity(artist, spotify_artists) + + score = title_score * 0.70 + artist_score * 0.30 + + if score > best_score: + best_score = score + best_track = track + + print(f"Spotify match score: {best_score:.2f}") + + return best_track + + +def get_track_metadata(track, fallback_artist, fallback_title): + if track is None: + return { + "artist": fallback_artist, + "title": fallback_title, + "album": "", + "album_artist": fallback_artist, + "track_number": None, + "release_date": None, + "cover_url": None, + } + + artist = ", ".join( + item["name"] + for item in track["artists"] + ) + + album = track.get("album", {}) + + album_artist = ", ".join( + item["name"] + for item in album.get("artists", []) + ) + + images = album.get("images", []) + + return { + "artist": artist, + "title": track["name"], + "album": album.get("name", ""), + "album_artist": album_artist or artist, + "track_number": track.get("track_number"), + "release_date": album.get("release_date"), + "cover_url": images[0]["url"] if images else None, + } + + +def is_image_bytes(data: bytes) -> bool: + """Check common image signatures before writing a cover file.""" + if not data: + return False + + signatures = ( + b"\xff\xd8\xff", # JPEG + b"\x89PNG\r\n\x1a\n", # PNG + b"GIF87a", + b"GIF89a", + b"RIFF", # WebP (RIFF....WEBP below) + ) + + if data.startswith(signatures): + return True + + return b"WEBP" in data[:16] + + +def download_cover(url: str, destination: Path): + response = requests.get( + url, + timeout=30, + headers={ + "User-Agent": USER_AGENT + }, + ) + + response.raise_for_status() + + if not is_image_bytes(response.content): + raise ValueError("response is not a valid image") + + destination.write_bytes(response.content) + + +def youtube_thumbnail_urls(video): + """Return thumbnail URLs for a YouTube result, best first.""" + urls = [] + thumbnails = (video or {}).get("thumbnails") + + if isinstance(thumbnails, list): + ordered = sorted( + ( + item for item in thumbnails + if isinstance(item, dict) and item.get("url") + ), + key=lambda item: ( + (item.get("width") or 0) * (item.get("height") or 0) + ), + reverse=True, + ) + + urls.extend(item["url"] for item in ordered) + + thumbnail = (video or {}).get("thumbnail") + + if isinstance(thumbnail, str) and thumbnail: + urls.append(thumbnail) + + video_id = (video or {}).get("id") + + if video_id: + urls.append( + f"https://i.ytimg.com/vi/{video_id}/maxresdefault.jpg" + ) + urls.append( + f"https://i.ytimg.com/vi/{video_id}/hqdefault.jpg" + ) + + result = [] + + for url in urls: + if url not in result: + result.append(url) + + return result + + +def youtube_search(query: str, limit: int = 5): + command = [ + "yt-dlp", + "--remote-components", + YTDLP_REMOTE_COMPONENTS, + "--flat-playlist", + "--dump-json", + f"ytsearch{limit}:{query}", + ] + + result = subprocess.run( + command, + capture_output=True, + text=True, + encoding="utf-8", + errors="replace", + ) + + videos = [] + + for line in result.stdout.splitlines(): + try: + data = json.loads(line) + videos.append(data) + except json.JSONDecodeError: + pass + + return videos + + +def score_youtube_result( + video, + artist: str, + title: str, +): + video_title = video.get("title", "") + + title_score = similarity(title, video_title) + + artist_score = similarity(artist, video_title) + + score = ( + title_score * 0.70 + + artist_score * 0.30 + ) + + normalized_video = normalize(video_title) + + if "official audio" in normalized_video: + score += 0.08 + + if "audio" in normalized_video: + score += 0.03 + + bad_words = [ + "cover", + "караоке", + "karaoke", + "nightcore", + "sped up", + "slowed", + "remix", + "reaction", + ] + + for word in bad_words: + if word in normalized_video: + score -= 0.20 + + return score + + +def find_youtube_video(artist: str, title: str): + query = f"{artist} {title}" + + print(f"Searching YouTube: {query}") + + videos = youtube_search(query, limit=5) + + if not videos: + return None + + best_video = None + best_score = -999.0 + + for video in videos: + score = score_youtube_result( + video, + artist, + title, + ) + + print( + f" YouTube score {score:.2f}: " + f"{video.get('title', 'Unknown')}" + ) + + if score > best_score: + best_score = score + best_video = video + + if best_video: + print( + f"Selected: " + f"{best_video.get('title', 'Unknown')}" + ) + + return best_video + + +class MetadataRuntime: + """Shared state for one TrackFetch run: HTTP, health, rate limits, cache.""" + + def __init__( + self, + session=None, + cache=None, + health=None, + limiter=None, + spotify_args=None, + ): + self.session = session or requests.Session() + headers = getattr(self.session, "headers", None) + + if headers is not None: + headers.setdefault("User-Agent", USER_AGENT) + + self.cache = cache + self.health = health or ProviderHealth() + self.limiter = limiter or RateLimiter() + self.spotify_args = spotify_args + self.spotify_client = None + self.spotify_initialized = False + self.cover_art_cache = {} + + +def request_json( + runtime, + provider: str, + url: str, + params=None, + headers=None, + timeout=20, +): + """Rate-limited JSON request with predictable provider errors.""" + request_headers = {"User-Agent": USER_AGENT} + + if headers: + request_headers.update(headers) + + runtime.limiter.wait(provider) + + try: + response = runtime.session.get( + url, + params=params, + headers=request_headers, + timeout=timeout, + ) + + except requests.Timeout as error: + raise ProviderError(f"{provider} request timed out") from error + + except requests.RequestException as error: + raise ProviderError(f"{provider} request failed: {error}") from error + + status = getattr(response, "status_code", 200) + + if status in (401, 403): + raise ProviderAuthError(f"{provider} returned HTTP {status}") + + if status >= 400: + raise ProviderError(f"{provider} returned HTTP {status}") + + try: + return response.json() + + except (ValueError, TypeError) as error: + raise ProviderError( + f"{provider} returned invalid JSON" + ) from error + + +def is_spotify_auth_error(error) -> bool: + status = getattr(error, "http_status", None) + + if status in (401, 403): + return True + + text = str(error) + + return "401" in text or "403" in text + + +def spotify_provider(runtime, artist: str, title: str, config: SourceConfig): + if not runtime.spotify_initialized: + try: + runtime.spotify_client = get_spotify(runtime.spotify_args) + + except Exception as error: + runtime.spotify_initialized = True + + if is_spotify_auth_error(error): + raise ProviderAuthError(str(error)) from error + + raise ProviderError(f"Spotify authentication error: {error}") from error + + runtime.spotify_initialized = True + + if runtime.spotify_client is None: + # Missing credentials are an optional-provider state, not a failure. + return [] + + try: + track = find_spotify_track( + runtime.spotify_client, + artist, + title, + raise_errors=True, + ) + + except Exception as error: + if is_spotify_auth_error(error): + raise ProviderAuthError(str(error)) from error + + raise ProviderError(f"Spotify search error: {error}") from error + + if track is None: + return [] + + metadata = get_track_metadata(track, artist, title) + + return [ + { + "title": metadata["title"], + "artist": metadata["artist"], + "album": metadata["album"], + "album_artist": metadata["album_artist"], + "track_number": metadata["track_number"], + "release_date": metadata["release_date"], + "cover_url": metadata["cover_url"], + "source": "spotify", + "source_id": track.get("id"), + } + ] + + +def upscale_itunes_artwork(url): + if not url: + return None + + return re.sub(r"\d+x\d+bb\.", "600x600bb.", url) + + +def itunes_provider(runtime, artist: str, title: str, config: SourceConfig): + country = config.providers["itunes"].get("country", "us") + data = request_json( + runtime, + "itunes", + "https://itunes.apple.com/search", + params={ + "term": f"{artist} {title}", + "media": "music", + "entity": "song", + "limit": 25, + "country": country, + }, + ) + + if not isinstance(data, dict) or not isinstance(data.get("results"), list): + raise ProviderError("iTunes returned an invalid response") + + candidates = [] + + for item in data["results"]: + if not isinstance(item, dict) or not item.get("trackName"): + continue + + candidates.append( + { + "title": item.get("trackName"), + "artist": item.get("artistName") or "", + "album": item.get("collectionName") or "", + "album_artist": item.get("artistName") or "", + "track_number": item.get("trackNumber"), + "release_date": item.get("releaseDate"), + "cover_url": upscale_itunes_artwork( + item.get("artworkUrl100") + or item.get("artworkUrl60") + or item.get("artworkUrl30") + ), + "source": "itunes", + "source_id": item.get("trackId"), + } + ) + + return candidates + + +def deezer_provider(runtime, artist: str, title: str, config: SourceConfig): + data = request_json( + runtime, + "deezer", + "https://api.deezer.com/search", + params={ + "q": f'artist:"{artist}" track:"{title}"', + "limit": 25, + }, + ) + + if not isinstance(data, dict): + raise ProviderError("Deezer returned an invalid response") + + if data.get("error"): + raise ProviderError( + f"Deezer API error: {data['error']}" + ) + + items = data.get("data") + + if not isinstance(items, list): + raise ProviderError("Deezer returned an invalid response") + + candidates = [] + + for item in items: + if not isinstance(item, dict) or not item.get("title"): + continue + + album = item.get("album") or {} + album_artist = (album.get("artist") or {}).get("name") + artist_name = (item.get("artist") or {}).get("name") or "" + + candidates.append( + { + "title": item.get("title"), + "artist": artist_name, + "album": album.get("title") or "", + "album_artist": album_artist or artist_name, + "track_number": None, + "release_date": item.get("release_date"), + "cover_url": ( + album.get("cover_xl") + or album.get("cover_big") + or album.get("cover_medium") + or album.get("cover") + ), + "source": "deezer", + "source_id": item.get("id"), + } + ) + + return candidates + + +def musicbrainz_artist(recording) -> str: + parts = [] + + for credit in recording.get("artist-credit") or []: + if not isinstance(credit, dict): + continue + + parts.append(credit.get("name") or "") + parts.append(credit.get("joinphrase") or "") + + return "".join(parts).strip() + + +def cover_art_archive_url(runtime, release_id, config: SourceConfig): + """Look up front cover art for a MusicBrainz release, with memoisation.""" + if not release_id: + return None + + if release_id in runtime.cover_art_cache: + return runtime.cover_art_cache[release_id] + + try: + data = request_json( + runtime, + "musicbrainz", + f"https://coverartarchive.org/release/{release_id}", + ) + + except ProviderAuthError: + runtime.cover_art_cache[release_id] = None + return None + + except ProviderError: + runtime.cover_art_cache[release_id] = None + return None + + images = data.get("images") if isinstance(data, dict) else None + + if not isinstance(images, list): + runtime.cover_art_cache[release_id] = None + return None + + front = [ + image + for image in images + if isinstance(image, dict) and image.get("front") + ] + chosen = None + + for image in front or [item for item in images if isinstance(item, dict)]: + if not image.get("image"): + continue + + if chosen is None: + chosen = image + + elif ( + (image.get("width") or 0) * (image.get("height") or 0) + > (chosen.get("width") or 0) * (chosen.get("height") or 0) + ): + chosen = image + + url = chosen.get("image") if chosen else None + runtime.cover_art_cache[release_id] = url + + return url + + +def musicbrainz_provider(runtime, artist: str, title: str, config: SourceConfig): + data = request_json( + runtime, + "musicbrainz", + "https://musicbrainz.org/ws/2/recording", + params={ + "query": f'artist:"{artist}" AND recording:"{title}"', + "fmt": "json", + "limit": 10, + }, + headers={"User-Agent": USER_AGENT}, + ) + + recordings = data.get("recordings") if isinstance(data, dict) else None + + if not isinstance(recordings, list): + raise ProviderError("MusicBrainz returned an invalid response") - best_track = None - best_score = -1.0 + candidates = [] - for track in tracks: - spotify_title = track["name"] - spotify_artists = " ".join( - item["name"] - for item in track["artists"] + for recording in recordings: + if not isinstance(recording, dict) or not recording.get("title"): + continue + + releases = recording.get("releases") or [] + release = releases[0] if releases and isinstance(releases[0], dict) else {} + release_id = release.get("id") + release_date = release.get("date") + + if not release_date: + for medium in release.get("media") or []: + if isinstance(medium, dict): + for track in medium.get("tracks") or []: + if isinstance(track, dict) and track.get("first-release-date"): + release_date = track["first-release-date"] + break + + candidates.append( + { + "title": recording.get("title"), + "artist": musicbrainz_artist(recording), + "album": release.get("title") or "", + "album_artist": musicbrainz_artist(recording), + "track_number": None, + "release_date": release_date, + "cover_url": cover_art_archive_url( + runtime, + release_id, + config, + ), + "source": "musicbrainz", + "source_id": recording.get("id"), + } ) - title_score = similarity(title, spotify_title) - artist_score = similarity(artist, spotify_artists) + return candidates - score = title_score * 0.70 + artist_score * 0.30 - if score > best_score: - best_score = score - best_track = track +def absolute_vocadb_url(url): + if not url: + return None - print(f"Spotify match score: {best_score:.2f}") + if url.startswith("//"): + return "https:" + url - return best_track + if url.startswith("/"): + return "https://vocadb.net" + url + return url -def get_track_metadata(track, fallback_artist, fallback_title): - if track is None: - return { - "artist": fallback_artist, - "title": fallback_title, - "album": "", - "album_artist": fallback_artist, - "track_number": None, - "release_date": None, - "cover_url": None, - } - artist = ", ".join( - item["name"] - for item in track["artists"] - ) +def vocadb_picture_url(item, album=None): + for source in (item, album or {}): + if not isinstance(source, dict): + continue - album = track.get("album", {}) + picture = source.get("mainPicture") - album_artist = ", ".join( - item["name"] - for item in album.get("artists", []) - ) + if isinstance(picture, dict): + url = ( + picture.get("url") + or picture.get("original") + or picture.get("largeThumbUrl") + ) - images = album.get("images", []) + if url: + return absolute_vocadb_url(url) - return { - "artist": artist, - "title": track["name"], - "album": album.get("name", ""), - "album_artist": album_artist or artist, - "track_number": track.get("track_number"), - "release_date": album.get("release_date"), - "cover_url": images[0]["url"] if images else None, - } + for key in ("coverPicture", "picture", "coverUrl"): + if source.get(key): + return absolute_vocadb_url(source[key]) + return None -def download_cover(url: str, destination: Path): - response = requests.get( - url, - timeout=30, - headers={ - "User-Agent": "trackfetch/2.2.6" + +def vocadb_provider(runtime, artist: str, title: str, config: SourceConfig): + data = request_json( + runtime, + "vocadb", + "https://vocadb.net/api/songs", + params={ + "query": f"{artist} {title}", + "nameMatchMode": "Auto", + "maxResults": 20, + "contentType": "Song", }, ) - response.raise_for_status() + items = data.get("items") if isinstance(data, dict) else None - destination.write_bytes(response.content) + if not isinstance(items, list): + raise ProviderError("VocaDB returned an invalid response") + candidates = [] -def youtube_search(query: str, limit: int = 5): - command = [ - "yt-dlp", - "--remote-components", - YTDLP_REMOTE_COMPONENTS, - "--flat-playlist", - "--dump-json", - f"ytsearch{limit}:{query}", - ] + for item in items: + if not isinstance(item, dict) or not item.get("name"): + continue - result = subprocess.run( - command, - capture_output=True, - text=True, - encoding="utf-8", - errors="replace", - ) + artist_name = item.get("artistString") or "" - videos = [] + if not artist_name: + artist_name = ", ".join( + credit.get("name") or "" + for credit in item.get("artists") or [] + if isinstance(credit, dict) + ).strip(", ") - for line in result.stdout.splitlines(): - try: - data = json.loads(line) - videos.append(data) - except json.JSONDecodeError: - pass + albums = item.get("albums") or [] + album = albums[0] if albums and isinstance(albums[0], dict) else {} - return videos + candidates.append( + { + "title": item.get("name"), + "artist": artist_name, + "album": album.get("name") or "", + "album_artist": artist_name, + "track_number": None, + "release_date": ( + item.get("publishDate") + or item.get("releaseDate") + or album.get("releaseDate") + ), + "cover_url": vocadb_picture_url(item, album), + "source": "vocadb", + "source_id": item.get("id"), + } + ) + return candidates -def score_youtube_result( - video, - artist: str, - title: str, -): - video_title = video.get("title", "") - title_score = similarity(title, video_title) +PROVIDER_FUNCTIONS = { + "spotify": spotify_provider, + "itunes": itunes_provider, + "deezer": deezer_provider, + "musicbrainz": musicbrainz_provider, + "vocadb": vocadb_provider, +} - artist_score = similarity(artist, video_title) - score = ( - title_score * 0.70 - + artist_score * 0.30 +def cached_metadata(runtime, artist, title, provider, config): + if runtime.cache is None: + return None + + cached = runtime.cache.get(artist, title, provider) + + if cached is None: + return None + + return select_best_metadata( + [cached], + artist, + title, + config.match_threshold, + config.title_threshold, ) - normalized_video = normalize(video_title) - if "official audio" in normalized_video: - score += 0.08 +def resolve_metadata(artist: str, title: str, config: SourceConfig, runtime): + """Return the first suitable metadata result in configured priority order.""" + if runtime is None: + runtime = MetadataRuntime() - if "audio" in normalized_video: - score += 0.03 + fallback = fallback_metadata(artist, title) - bad_words = [ - "cover", - "караоке", - "karaoke", - "nightcore", - "sped up", - "slowed", - "remix", - "reaction", - ] + for provider in effective_metadata_sources(config, artist, title): + if runtime.health.in_cooldown(provider): + cached = cached_metadata( + runtime, + artist, + title, + provider, + config, + ) - for word in bad_words: - if word in normalized_video: - score -= 0.20 + if cached is not None: + return cached - return score + continue + state = runtime.health.state(provider) -def find_youtube_video(artist: str, title: str): - query = f"{artist} {title}" + if state["failures"] == 0: + cached = cached_metadata( + runtime, + artist, + title, + provider, + config, + ) - print(f"Searching YouTube: {query}") + if cached is not None: + return cached - videos = youtube_search(query, limit=5) + try: + candidates = PROVIDER_FUNCTIONS[provider]( + runtime, + artist, + title, + config, + ) - if not videos: - return None + except ProviderAuthError: + runtime.health.force_cooldown(provider, 600.0) + cached = cached_metadata( + runtime, + artist, + title, + provider, + config, + ) - best_video = None - best_score = -999.0 + if cached is not None: + return cached - for video in videos: - score = score_youtube_result( - video, + continue + + except ProviderError: + runtime.health.record_failure(provider) + cached = cached_metadata( + runtime, + artist, + title, + provider, + config, + ) + + if cached is not None: + return cached + + continue + + except (KeyError, TypeError, ValueError, AttributeError, IndexError): + # A malformed but successful-looking API response is a failure, + # not a reason to abort the whole run. + runtime.health.record_failure(provider) + cached = cached_metadata( + runtime, + artist, + title, + provider, + config, + ) + + if cached is not None: + return cached + + continue + + best = select_best_metadata( + candidates, artist, title, + config.match_threshold, + config.title_threshold, ) - print( - f" YouTube score {score:.2f}: " - f"{video.get('title', 'Unknown')}" - ) + # A valid response, even with no match, resets the failure counter. + runtime.health.record_success(provider) - if score > best_score: - best_score = score - best_video = video + if best is not None: + if runtime.cache is not None: + runtime.cache.set(artist, title, provider, best) - if best_video: - print( - f"Selected: " - f"{best_video.get('title', 'Unknown')}" - ) + return best - return best_video + return fallback def download_audio( @@ -610,6 +2045,38 @@ def append_line(path: Path, text: str): file.write(text + "\n") +def download_best_cover(metadata, video, cover_path, youtube_enabled): + """Download provider artwork, then fall back to a YouTube thumbnail.""" + candidates = [] + + if metadata.get("cover_url"): + candidates.append( + (metadata["cover_url"], metadata.get("source") or "metadata") + ) + + if youtube_enabled: + for url in youtube_thumbnail_urls(video): + candidates.append((url, "YouTube")) + + last_error = None + + for url, source in candidates: + try: + download_cover(url, cover_path) + + if cover_path.exists() and cover_path.stat().st_size > 0: + print(f"{source} cover downloaded") + return True + + except Exception as error: + last_error = error + + if last_error is not None: + print(f"WARNING: cover download failed: {last_error}") + + return False + + def process_song( sp, input_artist, @@ -617,18 +2084,35 @@ def process_song( output, title_only, audio_format="mp3", + source_config=None, + runtime=None, ): - track = find_spotify_track( - sp, - input_artist, - input_title, - ) + if source_config is None and runtime is None: + track = find_spotify_track( + sp, + input_artist, + input_title, + ) - metadata = get_track_metadata( - track, - input_artist, - input_title, - ) + metadata = get_track_metadata( + track, + input_artist, + input_title, + ) + metadata.setdefault("source", "spotify") + youtube_enabled = True + + else: + if source_config is None: + source_config = build_source_config(None, {}) + + metadata = resolve_metadata( + input_artist, + input_title, + source_config, + runtime, + ) + youtube_enabled = source_config.youtube_enabled print( f"Metadata: " @@ -648,6 +2132,10 @@ def process_song( print(f"SKIP: already exists: {filename}") return True, "exists" + if not youtube_enabled: + print("FAILED: YouTube is disabled") + return False, "YouTube disabled" + video = find_youtube_video( metadata["artist"], metadata["title"], @@ -689,20 +2177,12 @@ def process_song( cover_path = temp_dir / "cover.jpg" - if metadata["cover_url"]: - try: - download_cover( - metadata["cover_url"], - cover_path, - ) - - print("Spotify cover downloaded") - - except Exception as error: - print( - f"WARNING: cover download failed: " - f"{error}" - ) + download_best_cover( + metadata, + video, + cover_path, + youtube_enabled, + ) try: add_metadata( @@ -858,7 +2338,19 @@ def apply_config(args, parser, settings): for action in parser._actions: dest = action.dest - if dest in ("help", "version", "config", "inputs", "track"): + if dest in ( + "help", + "version", + "config", + "inputs", + "track", + "metadata_sources", + "disable_sources", + "provider_opt", + "match_threshold", + "title_threshold", + "list_sources", + ): continue if getattr(args, dest, None) is not None: @@ -977,8 +2469,8 @@ def main(): parser = argparse.ArgumentParser( description=( - "Download music using Spotify metadata " - "and YouTube audio" + "Download music using configurable free metadata " + "sources and YouTube audio" ), epilog=( "A config file with the defaults can be used as well. It is " @@ -1056,6 +2548,62 @@ def main(): help="Delay between songs in seconds (default: 1.0)", ) + parser.add_argument( + "-s", + "--metadata-sources", + default=None, + metavar="SOURCES", + help=( + "Comma-separated metadata priority, for example " + "'deezer,itunes,musicbrainz' or 'none' " + "(default: itunes)" + ), + ) + + parser.add_argument( + "--disable-sources", + default=None, + metavar="SOURCES", + help=( + "Comma-separated sources to disable, " + "for example 'spotify,youtube'" + ), + ) + + parser.add_argument( + "--provider-opt", + action="append", + default=None, + metavar="NAME.KEY=VALUE", + help=( + "Provider-specific setting, for example " + "--provider-opt itunes.country=ua" + ), + ) + + parser.add_argument( + "--match-threshold", + type=float, + default=None, + metavar="SCORE", + help="Minimum overall match score, 0.0-1.0 (default: 0.6)", + ) + + parser.add_argument( + "--title-threshold", + type=float, + default=None, + metavar="SCORE", + help="Minimum title similarity, 0.0-1.0 (default: 0.8)", + ) + + parser.add_argument( + "--list-sources", + action="store_true", + default=None, + help="List available metadata sources and exit", + ) + parser.add_argument( "--spotify-client-id", default=None, @@ -1088,6 +2636,17 @@ def main(): print(f"ERROR: {error}") sys.exit(1) + try: + source_config = build_source_config(args, settings) + + except ValueError as error: + print(f"ERROR: {error}") + sys.exit(1) + + if args.list_sources: + print(format_source_list(source_config)) + return + if args.output is None: args.output = resolve_output(None, settings) @@ -1196,9 +2755,27 @@ def main(): print(f"Output: {args.output}") + print( + "Metadata sources: " + + (", ".join(source_config.metadata_sources) or "none") + ) + print( + "YouTube artwork fallback: " + + ("enabled" if source_config.youtube_enabled else "disabled") + ) + sys.stdout.flush() - sp = get_spotify(args) + runtime = MetadataRuntime( + cache=MetadataCache(args.output / CACHE_FILENAME), + limiter=RateLimiter( + { + name: source_config.interval(name) + for name in METADATA_PROVIDERS + } + ), + spotify_args=args, + ) success = 0 skipped = 0 @@ -1221,12 +2798,14 @@ def main(): continue ok, reason = process_song( - sp, + None, artist, title, args.output, args.title_only, args.format, + source_config=source_config, + runtime=runtime, ) if ok: From b52d491b5a0c80606c4c31c598c63beade1faa17 Mon Sep 17 00:00:00 2001 From: ByteMe6 Date: Sun, 15 Nov 2026 17:44:39 +0200 Subject: [PATCH 2/8] docs: document metadata sources, caching and fallbacks --- CHANGELOG.md | 15 ++++++ README.md | 117 +++++++++++++++++++++++++++++++++++----- README.ru.md | 117 +++++++++++++++++++++++++++++++++++----- README.uk.md | 117 +++++++++++++++++++++++++++++++++++----- docs/tldr/trackfetch.md | 20 ++++++- 5 files changed, 342 insertions(+), 44 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 583c21a..c876c03 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,7 +6,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/). ## [Unreleased] +### Added +- Configurable free metadata providers: iTunes (the new default), Deezer, MusicBrainz with Cover Art Archive, VocaDB and optional Spotify. No API key is needed except for Spotify. +- `-s`/`--metadata-sources` with priority ordering, `none`, duplicate removal and unknown-name validation. YouTube stays a separate artwork fallback and is not part of the metadata ordering. +- `--disable-sources`, `--provider-opt NAME.KEY=VALUE`, `--match-threshold`, `--title-threshold` and `--list-sources`. +- Automatic temporary VocaDB promotion for CJK and Vocaloid-related input. +- Independent per-provider rate limits: iTunes 3.0 s, Deezer 0.25 s, MusicBrainz 1.1 s and VocaDB 0.5 s. +- Provider health tracking: two consecutive real failures start a 30-second cooldown that doubles up to 600 seconds, then the provider is retried and restored to its configured priority. Empty results and missing artwork do not count as failures. +- Per-provider metadata cache in `metadata-cache.json` in the output directory, with graceful handling of corrupted files. +- Artwork fallback from provider artwork to Cover Art Archive to the YouTube thumbnail, without replacing valid high-quality artwork. +- New configuration keys for source priority, per-provider enabling, intervals, storefront country, YouTube fallback and matching thresholds. +- Tests for source resolution, configuration, matching, provider responses, rate limiting, failure recovery, caching, artwork and the new CLI options. + ### Changed +- The default metadata source is now iTunes, so Spotify credentials are optional and Spotify is disabled unless explicitly selected or enabled. +- `get_spotify()` now returns `None` quietly when credentials are missing instead of exiting. +- Metadata results use one normalized structure with source, identifier, artwork and match score. - `brew install trackfetch` no longer compiles `ffmpeg` on macOS: the formula installs a static prebuilt `ffmpeg` next to the prebuilt binary, so the first install takes seconds even where Homebrew has no bottle for it. ### Fixed diff --git a/README.md b/README.md index 0225284..9ec2590 100644 --- a/README.md +++ b/README.md @@ -31,10 +31,10 @@
-trackfetch reads a plain text file with one `Artist - Title` per line. For every song it looks up the official metadata and cover art on Spotify, picks the best-matching audio on YouTube, and saves an MP3 with complete ID3 tags. Runs are resumable, so you can stop a 1,000-song list at any point and pick it up later. +trackfetch reads a plain text file with one `Artist - Title` per line. For every song it looks up metadata and cover art in the configured free sources, picks the best-matching audio on YouTube, and saves an MP3 with complete ID3 tags. Runs are resumable, so you can stop a 1,000-song list at any point and pick it up later. -- **Exact metadata.** The title, every credited artist, album, album artist, track number and release date come from Spotify, not from a YouTube video title. -- **Album art.** The largest Spotify cover is embedded in every file. +- **Configurable metadata.** Use iTunes (the default), Deezer, MusicBrainz, VocaDB and optional Spotify. Put them in any priority order with `-s`, or turn them off one by one. +- **Album art.** Artwork comes from the winning metadata source, then the Cover Art Archive for MusicBrainz, then the YouTube thumbnail. The largest available image is embedded in every file. - **The right upload.** trackfetch scores five YouTube results per song. Official audio wins; covers, karaoke, nightcore, sped-up, slowed, remix and reaction videos lose. - **Your choice of format.** MP3 for any player, or Opus and M4A that keep YouTube's original audio without re-encoding. - **Resumable.** Finished songs are logged in `done.txt` and skipped next time. Failures go to `failed.txt` with the reason. @@ -44,7 +44,7 @@ trackfetch reads a plain text file with one `Artist - Title` per line. For every ## Install -Pick one. Homebrew and Nix also install yt-dlp, FFmpeg and Deno for you; with the other methods, install them yourself ([see below](#dependencies)). Every method needs a free Spotify API key ([set it up below](#spotify-credentials)). +Pick one. Homebrew and Nix also install yt-dlp, FFmpeg and Deno for you; with the other methods, install them yourself ([see below](#dependencies)). The default iTunes source needs no API key. A free Spotify API key is optional and only needed if you select Spotify ([set it up below](#spotify-credentials)). ### Homebrew @@ -182,7 +182,7 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist" ## Usage ```text -trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [--spotify-client-id ID] [--spotify-client-secret SECRET] [INPUT ...] +trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [-s SOURCES] [--disable-sources SOURCES] [--provider-opt NAME.KEY=VALUE] [--match-threshold SCORE] [--title-threshold SCORE] [--list-sources] [--spotify-client-id ID] [--spotify-client-secret SECRET] [INPUT ...] ``` | Option | Default | What it does | @@ -194,6 +194,12 @@ trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f { | `-f`, `--format` | `m4a` | Audio format: `mp3`, `m4a` or `opus`. See [Audio formats](#audio-formats). | | `--title-only` | off | Name files `Title.m4a` instead of `Artist - Title.m4a` | | `--delay` | `1.0` | Seconds to wait between songs. Raise it for long lists. | +| `-s`, `--metadata-sources` | `itunes` | Comma-separated metadata priority, for example `deezer,itunes,musicbrainz`. `none` disables metadata lookups but keeps YouTube. | +| `--disable-sources` | — | Comma-separated sources to disable, for example `spotify,youtube`. | +| `--provider-opt` | — | Provider setting as `NAME.KEY=VALUE`, for example `itunes.country=ua`. Can be repeated. | +| `--match-threshold` | `0.6` | Minimum overall match score, from `0.0` to `1.0`. | +| `--title-threshold` | `0.8` | Minimum title similarity, from `0.0` to `1.0`. | +| `--list-sources` | — | Show available metadata providers and artwork fallbacks, then exit. Makes no network requests. | | `--spotify-client-id` | `$SPOTIFY_CLIENT_ID` | Spotify API client ID. See [Spotify credentials](#spotify-credentials). | | `--spotify-client-secret` | `$SPOTIFY_CLIENT_SECRET` | Spotify API client secret. | @@ -204,8 +210,52 @@ trackfetch big-list.txt --delay 3 # go easy on rate limits trackfetch songs.txt --format opus # original YouTube audio, no re-encode trackfetch "Daft Punk - One More Time" # one track, no file needed trackfetch "A - B" "C - D" --track "E - F" # a few tracks in one go +trackfetch big-list.txt -s deezer,itunes,musicbrainz +trackfetch big-list.txt --disable-sources youtube # metadata only, download will fail +trackfetch --list-sources ``` +### Metadata sources + +The default metadata source is **iTunes**, which needs no API key. YouTube is +always handled separately: it supplies the audio and is the last artwork +fallback. The other providers are off unless you select or enable them: + +| Source | Credentials | Minimum interval | Notes | +| --- | --- | --- | --- | +| `itunes` | none | 3.0 s | Storefront country defaults to `us` | +| `deezer` | none | 0.25 s | Public search | +| `musicbrainz` | none | 1.1 s | Cover art comes from the Cover Art Archive | +| `vocadb` | none | 0.5 s | Japanese, Chinese, Korean and Vocaloid metadata | +| `spotify` | client ID and secret | — | Optional, disabled by default | + +The order in `-s` is the lookup priority. If the first provider has no suitable +match, trackfetch tries the next one. The first result that passes both +matching thresholds wins. + +```bash +trackfetch songs.txt -s deezer,itunes,musicbrainz,vocadb +trackfetch songs.txt -s none # no metadata, YouTube audio only +trackfetch songs.txt --provider-opt itunes.country=ua +trackfetch songs.txt --provider-opt musicbrainz.min_interval=1.5 +trackfetch songs.txt --match-threshold 0.7 --title-threshold 0.85 +``` + +CJK titles and recognizable Vocaloid hints temporarily promote VocaDB for that +lookup. The configured order is not changed. YouTube remains enabled unless it +is explicitly disabled, even with `-s none`. + +Provider failures are handled internally: after two consecutive real failures +(for example a timeout or an HTTP server error) the provider cools down for +30 seconds. The cooldown doubles on each further failure, up to 600 seconds. +A valid empty search, a missing match or missing artwork is not a failure. The +provider is retried after the cooldown and returns to its configured priority +when it recovers. + +Metadata is cached per provider in `metadata-cache.json` in the output +directory. A lower-priority cached result never prevents a higher-priority +provider from being retried after recovery. + ### Inline tracks Skip the file and name the tracks right on the command line: @@ -231,13 +281,43 @@ format = m4a title_only = false delay = 1.0 input = ~/songs.txt + +# Metadata source priority +metadata_sources = deezer,itunes,musicbrainz,vocadb + +# Sources to exclude +disable_sources = spotify + +# Provider settings +spotify_enabled = false spotify_client_id = your-client-id spotify_client_secret = your-client-secret + +itunes_enabled = true +itunes_country = us +itunes_min_interval = 3.0 + +deezer_enabled = true +deezer_min_interval = 0.25 + +musicbrainz_enabled = true +musicbrainz_min_interval = 1.1 + +vocadb_enabled = true +vocadb_min_interval = 0.5 + +# YouTube artwork fallback +youtube_enabled = true + +# Matching thresholds +match_threshold = 0.6 +title_threshold = 0.8 ``` -Every option above can be set there, under the `[trackfetch]` section, except -`--track`, which only makes sense on the command line. The precedence is -always the same: +Most options above can be set there under the `[trackfetch]` section. Source +priority and the provider settings use the keys shown in the example; +`--track` and `--list-sources` only make sense on the command line. The +precedence is always the same: 1. the command-line flag, 2. the config file, @@ -253,8 +333,10 @@ the directory you run trackfetch from. A `[DEFAULT]` section works as well. ### Spotify credentials -trackfetch needs a Spotify client ID and secret to read the metadata. Give -them in whichever way suits you: +Spotify is optional and is not queried unless it is selected with +`-s spotify` or `spotify_enabled = true`. Without credentials trackfetch skips +Spotify quietly and uses the other sources. Give the credentials in whichever +way suits you: ```bash # in the config file @@ -323,7 +405,7 @@ A [tldr](https://tldr.sh/) page is in [`docs/tldr/trackfetch.md`](https://github ## How it works -1. **Find the song on Spotify.** trackfetch searches for `artist:"…" track:"…"` and falls back to a looser search if nothing comes back. Every result is scored by fuzzy similarity, 70% title and 30% artist, and the best one supplies the official spelling, all credited artists, the album details and the cover. +1. **Find the metadata.** trackfetch queries the configured providers in priority order. Every result is scored by fuzzy similarity, 70% title and 30% artist. Both the overall `match_threshold` and the `title_threshold` must pass, so an unrelated result is rejected instead of being used. The winning result supplies the title, artists, album details, release date and artwork. 2. **Find the audio on YouTube.** It searches YouTube for the official artist and title and scores the top five results: | Signal | Effect on the score | @@ -347,14 +429,21 @@ A [tldr](https://tldr.sh/) page is in [`docs/tldr/trackfetch.md`](https://github | `TDRC` | Release date | | `APIC` | Front cover, up to 640×640 | -If Spotify has no match, the song is still downloaded and tagged with the artist and title from your file. +If no metadata source has a suitable match, the song is still downloaded and tagged with the artist and title from your file. If the metadata result has no artwork, trackfetch tries the Cover Art Archive (for MusicBrainz) and then the YouTube thumbnail, so a missing cover never loses otherwise valid metadata. ## Troubleshooting
-ERROR: Spotify credentials not found. +Spotify is selected but no credentials are configured + +trackfetch skips Spotify quietly and continues with the remaining sources. To use Spotify, set `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` in the config file or the environment. See [Spotify credentials](#spotify-credentials). + +
+ +
+A provider is skipped temporarily -`SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET` aren't set in this terminal. See [Spotify credentials](#spotify-credentials). +After two consecutive network, timeout, server or parsing failures a provider is paused: 30 seconds at first, doubling up to 600 seconds. trackfetch keeps using the other sources and retries the provider when the cooldown expires. Empty search results and missing artwork do not trigger a cooldown.
diff --git a/README.ru.md b/README.ru.md index 455b588..c029dea 100644 --- a/README.ru.md +++ b/README.ru.md @@ -31,10 +31,10 @@
-trackfetch читает обычный текстовый файл, где на каждой строке записано `Исполнитель - Название`. Для каждой песни он берёт официальные метаданные и обложку из Spotify, выбирает самое подходящее аудио на YouTube и сохраняет MP3 с полными ID3-тегами. Работу можно прервать в любой момент и продолжить позже, даже если в списке тысяча песен. +trackfetch читает обычный текстовый файл, где на каждой строке записано `Исполнитель - Название`. Для каждой песни он берёт метаданные и обложку из настроенных бесплатных источников, выбирает самое подходящее аудио на YouTube и сохраняет MP3 с полными ID3-тегами. Работу можно прервать в любой момент и продолжить позже, даже если в списке тысяча песен. -- **Точные метаданные.** Название, все исполнители, альбом, исполнитель альбома, номер трека и дата выхода берутся из Spotify, а не из названия ролика на YouTube. -- **Обложка альбома.** В каждый файл встраивается обложка из Spotify в самом большом размере. +- **Настраиваемые метаданные.** iTunes (по умолчанию), Deezer, MusicBrainz, VocaDB и необязательный Spotify. Порядок задаётся через `-s`, а ненужные источники можно отключать. +- **Обложка альбома.** Обложка берётся у победившего источника метаданных, затем из Cover Art Archive для MusicBrainz, затем из превью YouTube. В файл встраивается самый большой доступный вариант. - **Правильная загрузка.** trackfetch оценивает пять результатов YouTube на каждую песню. Официальное аудио выигрывает, а каверы, караоке, nightcore, ускоренные, замедленные версии, ремиксы и реакции проигрывают. - **Формат на выбор.** MP3 для любого плеера или Opus и M4A, которые сохраняют оригинальный звук YouTube без перекодирования. - **Продолжение с места остановки.** Готовые песни записываются в `done.txt` и при следующем запуске пропускаются. Ошибки попадают в `failed.txt` вместе с причиной. @@ -44,7 +44,7 @@ trackfetch читает обычный текстовый файл, где на ## Установка -Выбери любой способ. Homebrew и Nix сами ставят yt-dlp, FFmpeg и Deno; при остальных способах их нужно поставить отдельно ([см. ниже](#зависимости)). Для любого способа нужен бесплатный ключ Spotify API ([как его получить](#ключи-spotify)). +Выбери любой способ. Homebrew и Nix сами ставят yt-dlp, FFmpeg и Deno; при остальных способах их нужно поставить отдельно ([см. ниже](#зависимости)). Источнику iTunes по умолчанию ключ API не нужен. Бесплатный ключ Spotify API необязателен и нужен только если выбрать Spotify ([как его получить](#ключи-spotify)). ### Homebrew @@ -182,7 +182,7 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist" ## Использование ```text -trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [--spotify-client-id ID] [--spotify-client-secret SECRET] [INPUT ...] +trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [-s SOURCES] [--disable-sources SOURCES] [--provider-opt NAME.KEY=VALUE] [--match-threshold SCORE] [--title-threshold SCORE] [--list-sources] [--spotify-client-id ID] [--spotify-client-secret SECRET] [INPUT ...] ``` | Параметр | По умолчанию | Что делает | @@ -194,6 +194,12 @@ trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f { | `-f`, `--format` | `m4a` | Формат звука: `mp3`, `m4a` или `opus`. См. [Форматы звука](#форматы-звука). | | `--title-only` | выключен | Называть файлы `Название.m4a` вместо `Исполнитель - Название.m4a` | | `--delay` | `1.0` | Пауза между песнями в секундах. Для длинных списков её стоит увеличить. | +| `-s`, `--metadata-sources` | `itunes` | Приоритет источников через запятую, например `deezer,itunes,musicbrainz`. `none` отключает метаданные, но оставляет YouTube. | +| `--disable-sources` | — | Источники, которые нужно отключить, например `spotify,youtube`. | +| `--provider-opt` | — | Настройка источника `NAME.KEY=VALUE`, например `itunes.country=ua`. Можно повторять. | +| `--match-threshold` | `0.6` | Минимальная общая оценка совпадения от `0.0` до `1.0`. | +| `--title-threshold` | `0.8` | Минимальное сходство названия от `0.0` до `1.0`. | +| `--list-sources` | — | Показать доступные источники и запасные варианты обложек и выйти. Сеть не используется. | | `--spotify-client-id` | `$SPOTIFY_CLIENT_ID` | Client ID для Spotify API. См. [Данные Spotify](#данные-spotify). | | `--spotify-client-secret` | `$SPOTIFY_CLIENT_SECRET` | Client secret для Spotify API. | @@ -204,6 +210,50 @@ trackfetch big-list.txt --delay 3 # бережнее к лими trackfetch songs.txt --format opus # оригинальный звук YouTube без перекодирования trackfetch "Daft Punk - One More Time" # один трек, файл не нужен trackfetch "A - B" "C - D" --track "E - F" # несколько треков за раз +trackfetch big-list.txt -s deezer,itunes,musicbrainz +trackfetch big-list.txt --disable-sources youtube # без метаданных и без загрузки +trackfetch --list-sources +``` + +### Источники метаданных + +По умолчанию используется **iTunes**, ключ API не нужен. YouTube обрабатывается +отдельно: он даёт звук и служит последним запасным вариантом обложки. Остальные +источники выключены, пока их не выбрать или не включить: + +| Источник | Ключи | Минимальный интервал | Примечания | +| --- | --- | --- | --- | +| `itunes` | не нужны | 3.0 с | Страна магазина по умолчанию `us` | +| `deezer` | не нужны | 0.25 с | Публичный поиск | +| `musicbrainz` | не нужны | 1.1 с | Обложки берутся из Cover Art Archive | +| `vocadb` | не нужны | 0.5 с | Японские, китайские, корейские и Vocaloid-метаданные | +| `spotify` | client ID и secret | — | Необязателен, выключен по умолчанию | + +Порядок в `-s` — это приоритет поиска. Если первый источник не дал подходящего +результата, trackfetch пробует следующий. Побеждает первый результат, который +проходит оба порога совпадения. + +```bash +trackfetch songs.txt -s deezer,itunes,musicbrainz,vocadb +trackfetch songs.txt -s none # без метаданных, только звук YouTube +trackfetch songs.txt --provider-opt itunes.country=ua +trackfetch songs.txt --provider-opt musicbrainz.min_interval=1.5 +trackfetch songs.txt --match-threshold 0.7 --title-threshold 0.85 +``` + +Для CJK-названий и явных подсказок Vocaloid VocaDB временно поднимается в +приоритете только для этого поиска. Настроенный порядок не меняется. YouTube +остаётся включённым, пока его явно не отключить, даже при `-s none`. + +Сбои источников обрабатываются внутри: после двух настоящих ошибок подряд +(таймаут, ошибка сервера и т. п.) источник уходит в паузу на 30 секунд. Каждая +следующая ошибка удваивает паузу до 600 секунд. Пустой поиск, отсутствие +подходящего результата или обложки ошибкой не считаются. После паузы источник +пробуется снова и возвращается на своё место в приоритете. + +Метаданные кешируются отдельно для каждого источника в `metadata-cache.json` в +папке вывода. Результат из кеша источника с низким приоритетом не мешает +повторной попытке источника с высоким приоритетом после восстановления. ``` ### Треки прямо в аргументах @@ -232,13 +282,43 @@ format = m4a title_only = false delay = 1.0 input = ~/songs.txt + +# Приоритет источников метаданных +metadata_sources = deezer,itunes,musicbrainz,vocadb + +# Исключённые источники +disable_sources = spotify + +# Настройки источников +spotify_enabled = false spotify_client_id = твой-client-id spotify_client_secret = твой-client-secret + +itunes_enabled = true +itunes_country = us +itunes_min_interval = 3.0 + +deezer_enabled = true +deezer_min_interval = 0.25 + +musicbrainz_enabled = true +musicbrainz_min_interval = 1.1 + +vocadb_enabled = true +vocadb_min_interval = 0.5 + +# Запасная обложка YouTube +youtube_enabled = true + +# Пороги совпадения +match_threshold = 0.6 +title_threshold = 0.8 ``` -Любой параметр из таблицы выше можно задать там, в секции `[trackfetch]`, -кроме `--track` — он уместен только в командной строке. Приоритет всегда -одинаковый: +Большинство параметров из таблицы выше можно задать там, в секции +`[trackfetch]`. Приоритет источников и настройки провайдеров используют ключи +из примера; `--track` и `--list-sources` уместны только в командной строке. +Приоритет всегда одинаковый: 1. флаг в командной строке, 2. конфиг-файл, @@ -254,8 +334,10 @@ spotify_client_secret = твой-client-secret ### Данные Spotify -trackfetch нужен client ID и client secret Spotify, чтобы читать метаданные. -Их можно задать любым удобным способом: +Spotify необязателен и не используется, пока его не выбрать через +`-s spotify` или `spotify_enabled = true`. Без ключей trackfetch молча +пропускает Spotify и берёт данные из других источников. Ключи можно задать +любым удобным способом: ```bash # в конфиг-файле @@ -322,7 +404,7 @@ trackfetch retry.txt ## Как это работает -1. **Поиск песни в Spotify.** trackfetch ищет `artist:"…" track:"…"`, а если ничего не нашлось, делает менее строгий поиск. Каждый результат оценивается по нечёткому сходству: 70% даёт название, 30% исполнитель. Лучший результат даёт официальное написание, всех исполнителей, данные альбома и обложку. +1. **Поиск метаданных.** trackfetch опрашивает настроенные источники по приоритету. Каждый результат оценивается по нечёткому сходству: 70% даёт название, 30% исполнитель. Нужно пройти и общий `match_threshold`, и `title_threshold`, поэтому неподходящий результат отклоняется. Победитель даёт название, исполнителей, альбом, дату выхода и обложку. 2. **Поиск аудио на YouTube.** trackfetch ищет на YouTube официальные исполнителя и название и оценивает первые пять результатов: | Признак | Влияние на оценку | @@ -346,14 +428,21 @@ trackfetch retry.txt | `TDRC` | Дата выхода | | `APIC` | Обложка, до 640×640 | -Если в Spotify песня не нашлась, она всё равно скачивается и получает теги с исполнителем и названием из твоего файла. +Если ни один источник не дал подходящего результата, песня всё равно скачивается и получает теги с исполнителем и названием из твоего файла. Если у результата нет обложки, trackfetch пробует Cover Art Archive (для MusicBrainz), а затем превью YouTube, поэтому отсутствие обложки не теряет остальные метаданные. ## Решение проблем
-ERROR: Spotify credentials not found. +Spotify выбран, но ключи не заданы + +trackfetch молча пропускает Spotify и продолжает с остальными источниками. Чтобы использовать Spotify, задай `SPOTIFY_CLIENT_ID` и `SPOTIFY_CLIENT_SECRET` в конфиг-файле или переменных окружения. См. [Ключи Spotify](#ключи-spotify). + +
+ +
+Источник временно пропускается -В этом терминале не заданы `SPOTIFY_CLIENT_ID` и `SPOTIFY_CLIENT_SECRET`. См. [Ключи Spotify](#ключи-spotify). +После двух настоящих ошибок подряд (сеть, таймаут, сервер или разбор ответа) источник ставится на паузу: сначала 30 секунд, затем всё дольше, до 600 секунд. trackfetch продолжает использовать другие источники и повторяет попытку после паузы. Пустые результаты и отсутствие обложки паузу не вызывают.
diff --git a/README.uk.md b/README.uk.md index b810b0a..18a2b65 100644 --- a/README.uk.md +++ b/README.uk.md @@ -31,10 +31,10 @@
-trackfetch читає звичайний текстовий файл, де в кожному рядку записано `Виконавець - Назва`. Для кожної пісні він бере офіційні метадані й обкладинку зі Spotify, обирає найвідповідніше аудіо на YouTube і зберігає MP3 з повними ID3-тегами. Роботу можна перервати будь-коли й продовжити пізніше, навіть якщо у списку тисяча пісень. +trackfetch читає звичайний текстовий файл, де в кожному рядку записано `Виконавець - Назва`. Для кожної пісні він бере метадані й обкладинку з налаштованих безкоштовних джерел, обирає найвідповідніше аудіо на YouTube і зберігає MP3 з повними ID3-тегами. Роботу можна перервати будь-коли й продовжити пізніше, навіть якщо у списку тисяча пісень. -- **Точні метадані.** Назва, усі виконавці, альбом, виконавець альбому, номер треку й дата виходу беруться зі Spotify, а не з назви ролика на YouTube. -- **Обкладинка альбому.** У кожен файл вбудовується обкладинка зі Spotify у найбільшому розмірі. +- **Налаштовувані метадані.** iTunes (за замовчуванням), Deezer, MusicBrainz, VocaDB і необов'язковий Spotify. Порядок задається через `-s`, а непотрібні джерела можна вимикати. +- **Обкладинка альбому.** Обкладинка береться з джерела-переможця, потім із Cover Art Archive для MusicBrainz, потім із прев'ю YouTube. У файл вбудовується найбільший доступний варіант. - **Правильне завантаження.** trackfetch оцінює п'ять результатів YouTube для кожної пісні. Офіційне аудіо виграє, а кавери, караоке, nightcore, прискорені, сповільнені версії, ремікси й реакції програють. - **Формат на вибір.** MP3 для будь-якого плеєра або Opus і M4A, які зберігають оригінальний звук YouTube без перекодування. - **Продовження з місця зупинки.** Готові пісні записуються в `done.txt` і під час наступного запуску пропускаються. Помилки потрапляють у `failed.txt` разом із причиною. @@ -44,7 +44,7 @@ trackfetch читає звичайний текстовий файл, де в к ## Встановлення -Обери будь-який спосіб. Homebrew і Nix самі встановлюють yt-dlp, FFmpeg і Deno; для інших способів їх треба встановити окремо ([див. нижче](#залежності)). Для будь-якого способу потрібен безкоштовний ключ Spotify API ([як його отримати](#ключі-spotify)). +Обери будь-який спосіб. Homebrew і Nix самі встановлюють yt-dlp, FFmpeg і Deno; для інших способів їх треба встановити окремо ([див. нижче](#залежності)). Джерелу iTunes за замовчуванням ключ API не потрібен. Безкоштовний ключ Spotify API необов'язковий і потрібен лише якщо вибрати Spotify ([як його отримати](#ключі-spotify)). ### Homebrew @@ -182,7 +182,7 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist" ## Використання ```text -trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [--spotify-client-id ID] [--spotify-client-secret SECRET] [INPUT ...] +trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [-s SOURCES] [--disable-sources SOURCES] [--provider-opt NAME.KEY=VALUE] [--match-threshold SCORE] [--title-threshold SCORE] [--list-sources] [--spotify-client-id ID] [--spotify-client-secret SECRET] [INPUT ...] ``` | Параметр | За замовчуванням | Що робить | @@ -194,6 +194,12 @@ trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f { | `-f`, `--format` | `m4a` | Формат звуку: `mp3`, `m4a` або `opus`. Див. [Формати звуку](#формати-звуку). | | `--title-only` | вимкнено | Називати файли `Назва.m4a` замість `Виконавець - Назва.m4a` | | `--delay` | `1.0` | Пауза між піснями в секундах. Для довгих списків її варто збільшити. | +| `-s`, `--metadata-sources` | `itunes` | Пріоритет джерел через кому, наприклад `deezer,itunes,musicbrainz`. `none` вимикає метадані, але залишає YouTube. | +| `--disable-sources` | — | Джерела, які треба вимкнути, наприклад `spotify,youtube`. | +| `--provider-opt` | — | Налаштування джерела `NAME.KEY=VALUE`, наприклад `itunes.country=ua`. Можна повторювати. | +| `--match-threshold` | `0.6` | Мінімальна загальна оцінка збігу від `0.0` до `1.0`. | +| `--title-threshold` | `0.8` | Мінімальна схожість назви від `0.0` до `1.0`. | +| `--list-sources` | — | Показати доступні джерела й запасні варіанти обкладинок і вийти. Мережа не використовується. | | `--spotify-client-id` | `$SPOTIFY_CLIENT_ID` | Client ID для Spotify API. Див. [Дані Spotify](#дані-spotify). | | `--spotify-client-secret` | `$SPOTIFY_CLIENT_SECRET` | Client secret для Spotify API. | @@ -204,6 +210,50 @@ trackfetch big-list.txt --delay 3 # дбайливіше до л trackfetch songs.txt --format opus # оригінальний звук YouTube без перекодування trackfetch "Daft Punk - One More Time" # один трек, файл не потрібен trackfetch "A - B" "C - D" --track "E - F" # кілька треків за раз +trackfetch big-list.txt -s deezer,itunes,musicbrainz +trackfetch big-list.txt --disable-sources youtube # без метаданих і без завантаження +trackfetch --list-sources +``` + +### Джерела метаданих + +За замовчуванням використовується **iTunes**, ключ API не потрібен. YouTube +обробляється окремо: він дає звук і служить останнім запасним варіантом +обкладинки. Інші джерела вимкнені, доки їх не вибрати або не ввімкнути: + +| Джерело | Ключі | Мінімальний інтервал | Примітки | +| --- | --- | --- | --- | +| `itunes` | не потрібні | 3.0 с | Країна магазину за замовчуванням `us` | +| `deezer` | не потрібні | 0.25 с | Публічний пошук | +| `musicbrainz` | не потрібні | 1.1 с | Обкладинки з Cover Art Archive | +| `vocadb` | не потрібні | 0.5 с | Японські, китайські, корейські та Vocaloid-метадані | +| `spotify` | client ID і secret | — | Необов'язковий, вимкнений за замовчуванням | + +Порядок у `-s` — це пріоритет пошуку. Якщо перше джерело не дало відповідного +результату, trackfetch пробує наступне. Перемагає перший результат, який +проходить обидва пороги збігу. + +```bash +trackfetch songs.txt -s deezer,itunes,musicbrainz,vocadb +trackfetch songs.txt -s none # без метаданих, лише звук YouTube +trackfetch songs.txt --provider-opt itunes.country=ua +trackfetch songs.txt --provider-opt musicbrainz.min_interval=1.5 +trackfetch songs.txt --match-threshold 0.7 --title-threshold 0.85 +``` + +Для CJK-назв і явних підказок Vocaloid VocaDB тимчасово піднімається в +пріоритеті лише для цього пошуку. Налаштований порядок не змінюється. YouTube +залишається ввімкненим, доки його явно не вимкнути, навіть при `-s none`. + +Збої джерел обробляються всередині: після двох справжніх помилок поспіль +(таймаут, помилка сервера тощо) джерело йде на паузу на 30 секунд. Кожна +наступна помилка подвоює паузу до 600 секунд. Порожній пошук, відсутність +відповідного результату або обкладинки помилкою не вважаються. Після паузи +джерело пробується знову й повертається на своє місце в пріоритеті. + +Метадані кешуються окремо для кожного джерела в `metadata-cache.json` у теці +виводу. Результат із кешу джерела з низьким пріоритетом не заважає повторній +спробі джерела з високим пріоритетом після відновлення. ``` ### Треки просто в аргументах @@ -232,13 +282,43 @@ format = m4a title_only = false delay = 1.0 input = ~/songs.txt + +# Пріоритет джерел метаданих +metadata_sources = deezer,itunes,musicbrainz,vocadb + +# Виключені джерела +disable_sources = spotify + +# Налаштування джерел +spotify_enabled = false spotify_client_id = твій-client-id spotify_client_secret = твій-client-secret + +itunes_enabled = true +itunes_country = us +itunes_min_interval = 3.0 + +deezer_enabled = true +deezer_min_interval = 0.25 + +musicbrainz_enabled = true +musicbrainz_min_interval = 1.1 + +vocadb_enabled = true +vocadb_min_interval = 0.5 + +# Запасна обкладинка YouTube +youtube_enabled = true + +# Пороги збігу +match_threshold = 0.6 +title_threshold = 0.8 ``` -Будь-який параметр із таблиці вище можна задати там, у секції `[trackfetch]`, -окрім `--track` — він має сенс лише в командному рядку. Пріоритет завжди -однаковий: +Більшість параметрів із таблиці вище можна задати там, у секції +`[trackfetch]`. Пріоритет джерел і налаштування провайдерів використовують +ключі з прикладу; `--track` і `--list-sources` мають сенс лише в командному +рядку. Пріоритет завжди однаковий: 1. прапорець у командному рядку, 2. конфіг-файл, @@ -254,8 +334,10 @@ spotify_client_secret = твій-client-secret ### Дані Spotify -trackfetch потрібні client ID і client secret Spotify, щоб читати метадані. -Їх можна задати будь-яким зручним способом: +Spotify необов'язковий і не використовується, доки його не вибрати через +`-s spotify` або `spotify_enabled = true`. Без ключів trackfetch мовчки +пропускає Spotify і бере дані з інших джерел. Ключі можна задати будь-яким +зручним способом: ```bash # у конфіг-файлі @@ -322,7 +404,7 @@ trackfetch retry.txt ## Як це працює -1. **Пошук пісні у Spotify.** trackfetch шукає `artist:"…" track:"…"`, а якщо нічого не знайшлося, виконує менш суворий пошук. Кожен результат оцінюється за нечіткою схожістю: 70% дає назва, 30% виконавець. Найкращий результат дає офіційне написання, усіх виконавців, дані альбому й обкладинку. +1. **Пошук метаданих.** trackfetch опитує налаштовані джерела за пріоритетом. Кожен результат оцінюється за нечіткою схожістю: 70% дає назва, 30% виконавець. Потрібно пройти і загальний `match_threshold`, і `title_threshold`, тому невідповідний результат відхиляється. Переможець дає назву, виконавців, альбом, дату виходу й обкладинку. 2. **Пошук аудіо на YouTube.** trackfetch шукає на YouTube офіційних виконавця й назву та оцінює перші п'ять результатів: | Ознака | Вплив на оцінку | @@ -346,14 +428,21 @@ trackfetch retry.txt | `TDRC` | Дата виходу | | `APIC` | Обкладинка, до 640×640 | -Якщо у Spotify пісню не знайдено, вона все одно завантажується й отримує теги з виконавцем і назвою з твого файлу. +Якщо жодне джерело не дало відповідного результату, пісня все одно завантажується й отримує теги з виконавцем і назвою з твого файлу. Якщо в результату немає обкладинки, trackfetch пробує Cover Art Archive (для MusicBrainz), а потім прев'ю YouTube, тож відсутність обкладинки не втрачає інші метадані. ## Усунення несправностей
-ERROR: Spotify credentials not found. +Spotify вибрано, але ключі не задано + +trackfetch мовчки пропускає Spotify і продовжує з іншими джерелами. Щоб використовувати Spotify, задай `SPOTIFY_CLIENT_ID` і `SPOTIFY_CLIENT_SECRET` у конфіг-файлі або змінних оточення. Див. [Ключі Spotify](#ключі-spotify). + +
+ +
+Джерело тимчасово пропускається -У цьому терміналі не задано `SPOTIFY_CLIENT_ID` і `SPOTIFY_CLIENT_SECRET`. Див. [Ключі Spotify](#ключі-spotify). +Після двох справжніх помилок поспіль (мережа, таймаут, сервер або розбір відповіді) джерело ставиться на паузу: спочатку 30 секунд, далі дедалі довше, до 600 секунд. trackfetch продовжує використовувати інші джерела й повторює спробу після паузи. Порожні результати та відсутність обкладинки паузу не викликають.
diff --git a/docs/tldr/trackfetch.md b/docs/tldr/trackfetch.md index 9074011..c9a752b 100644 --- a/docs/tldr/trackfetch.md +++ b/docs/tldr/trackfetch.md @@ -1,7 +1,7 @@ # trackfetch -> Download songs listed in a text file as tagged MP3, M4A or Opus files, using Spotify metadata and YouTube audio. -> Requires `yt-dlp`, `ffmpeg` and the Spotify client ID and secret (config file or `SPOTIFY_CLIENT_ID` and `SPOTIFY_CLIENT_SECRET`). +> Download songs listed in a text file as tagged MP3, M4A or Opus files, using configurable free metadata sources and YouTube audio. +> Requires `yt-dlp` and `ffmpeg`. Spotify is optional and only used when selected. > More information: . - Download every song from a file with one `Artist - Title` per line into the current directory: @@ -24,6 +24,22 @@ `trackfetch {{path/to/songs.txt}} --title-only` +- Use a custom metadata priority: + +`trackfetch {{path/to/songs.txt}} {{[-s|--metadata-sources]}} {{deezer,itunes,musicbrainz,vocadb}}` + +- Disable YouTube artwork fallback or any other source: + +`trackfetch {{path/to/songs.txt}} --disable-sources {{youtube}}` + +- List the available metadata providers and artwork fallbacks: + +`trackfetch --list-sources` + +- Set a provider-specific option: + +`trackfetch {{path/to/songs.txt}} --provider-opt {{itunes.country=ua}}` + - Use a config file for the defaults: `trackfetch {{path/to/songs.txt}} {{[--config]}} {{path/to/config.ini}}` From 0e0ade7e2eb17b0c539f9812094a2406838518b7 Mon Sep 17 00:00:00 2001 From: ByteMe6 Date: Sun, 15 Nov 2026 17:45:29 +0200 Subject: [PATCH 3/8] docs: clarify disabling the YouTube source --- README.md | 5 +++-- README.ru.md | 6 ++++-- README.uk.md | 4 +++- docs/tldr/trackfetch.md | 2 +- 4 files changed, 11 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9ec2590..f3353b6 100644 --- a/README.md +++ b/README.md @@ -211,7 +211,7 @@ trackfetch songs.txt --format opus # original YouTube audio, no r trackfetch "Daft Punk - One More Time" # one track, no file needed trackfetch "A - B" "C - D" --track "E - F" # a few tracks in one go trackfetch big-list.txt -s deezer,itunes,musicbrainz -trackfetch big-list.txt --disable-sources youtube # metadata only, download will fail +trackfetch big-list.txt --disable-sources spotify # skip Spotify explicitly trackfetch --list-sources ``` @@ -243,7 +243,8 @@ trackfetch songs.txt --match-threshold 0.7 --title-threshold 0.85 CJK titles and recognizable Vocaloid hints temporarily promote VocaDB for that lookup. The configured order is not changed. YouTube remains enabled unless it -is explicitly disabled, even with `-s none`. +is explicitly disabled, even with `-s none`. Disabling YouTube also disables +the audio download, because YouTube is the only audio source. Provider failures are handled internally: after two consecutive real failures (for example a timeout or an HTTP server error) the provider cools down for diff --git a/README.ru.md b/README.ru.md index c029dea..a371c49 100644 --- a/README.ru.md +++ b/README.ru.md @@ -211,7 +211,7 @@ trackfetch songs.txt --format opus # оригинальный з trackfetch "Daft Punk - One More Time" # один трек, файл не нужен trackfetch "A - B" "C - D" --track "E - F" # несколько треков за раз trackfetch big-list.txt -s deezer,itunes,musicbrainz -trackfetch big-list.txt --disable-sources youtube # без метаданных и без загрузки +trackfetch big-list.txt --disable-sources spotify # явно пропустить Spotify trackfetch --list-sources ``` @@ -243,7 +243,9 @@ trackfetch songs.txt --match-threshold 0.7 --title-threshold 0.85 Для CJK-названий и явных подсказок Vocaloid VocaDB временно поднимается в приоритете только для этого поиска. Настроенный порядок не меняется. YouTube -остаётся включённым, пока его явно не отключить, даже при `-s none`. +остаётся включённым, пока его явно не отключить, даже при `-s none`. Отключение +YouTube также отключает загрузку звука, потому что YouTube — единственный +источник аудио. Сбои источников обрабатываются внутри: после двух настоящих ошибок подряд (таймаут, ошибка сервера и т. п.) источник уходит в паузу на 30 секунд. Каждая diff --git a/README.uk.md b/README.uk.md index 18a2b65..f3c6329 100644 --- a/README.uk.md +++ b/README.uk.md @@ -211,7 +211,7 @@ trackfetch songs.txt --format opus # оригінальний з trackfetch "Daft Punk - One More Time" # один трек, файл не потрібен trackfetch "A - B" "C - D" --track "E - F" # кілька треків за раз trackfetch big-list.txt -s deezer,itunes,musicbrainz -trackfetch big-list.txt --disable-sources youtube # без метаданих і без завантаження +trackfetch big-list.txt --disable-sources spotify # явно пропустити Spotify trackfetch --list-sources ``` @@ -244,6 +244,8 @@ trackfetch songs.txt --match-threshold 0.7 --title-threshold 0.85 Для CJK-назв і явних підказок Vocaloid VocaDB тимчасово піднімається в пріоритеті лише для цього пошуку. Налаштований порядок не змінюється. YouTube залишається ввімкненим, доки його явно не вимкнути, навіть при `-s none`. +Вимкнення YouTube також вимикає завантаження звуку, бо YouTube — єдине +джерело аудіо. Збої джерел обробляються всередині: після двох справжніх помилок поспіль (таймаут, помилка сервера тощо) джерело йде на паузу на 30 секунд. Кожна diff --git a/docs/tldr/trackfetch.md b/docs/tldr/trackfetch.md index c9a752b..d6ab4c1 100644 --- a/docs/tldr/trackfetch.md +++ b/docs/tldr/trackfetch.md @@ -28,7 +28,7 @@ `trackfetch {{path/to/songs.txt}} {{[-s|--metadata-sources]}} {{deezer,itunes,musicbrainz,vocadb}}` -- Disable YouTube artwork fallback or any other source: +- Disable a source (disabling YouTube also disables audio downloads): `trackfetch {{path/to/songs.txt}} --disable-sources {{youtube}}` From ec84254324ce23a87d4ac898ab90f7625a5662c1 Mon Sep 17 00:00:00 2001 From: ByteMe6 Date: Sun, 15 Nov 2026 18:42:43 +0200 Subject: [PATCH 4/8] fix: correct source precedence, validation and artwork formats CLI metadata selections now override conflicting config disabling, while explicit CLI disables still win. Thresholds and provider intervals reject non-finite and out-of-range values instead of clamping them. Downloaded artwork is detected by signature so extensions and embedded MIME types match JPEG, PNG, GIF or WebP bytes. Incomplete or lower-scored cache results no longer replace better entries. --- tests/test_metadata_sources.py | 600 ++++++++++++++++++++++++++++++++- tests/test_tags_and_files.py | 90 +++++ trackfetch.py | 262 ++++++++++---- 3 files changed, 875 insertions(+), 77 deletions(-) diff --git a/tests/test_metadata_sources.py b/tests/test_metadata_sources.py index 89b2c49..ff15fcf 100644 --- a/tests/test_metadata_sources.py +++ b/tests/test_metadata_sources.py @@ -159,8 +159,11 @@ def test_disable_sources_removes_provider(self): def test_disable_sources_from_config(self): config = m.build_source_config( - make_args(metadata_sources="deezer,itunes"), - {"disable_sources": "deezer"}, + make_args(), + { + "metadata_sources": "deezer,itunes", + "disable_sources": "deezer", + }, ) assert config.metadata_sources == ["itunes"] @@ -267,14 +270,19 @@ def test_invalid_country_is_rejected(self): {}, ) - def test_thresholds_are_clamped(self): - config = m.build_source_config( - make_args(match_threshold=5, title_threshold=-3), - {}, - ) + def test_negative_threshold_is_rejected(self): + with pytest.raises(ValueError, match="between 0.0 and 1.0"): + m.build_source_config( + make_args(match_threshold=-0.1), + {}, + ) - assert config.match_threshold == 1.0 - assert config.title_threshold == 0.0 + def test_threshold_above_one_is_rejected(self): + with pytest.raises(ValueError, match="between 0.0 and 1.0"): + m.build_source_config( + make_args(title_threshold=1.1), + {}, + ) def test_thresholds_from_config(self): config = m.build_source_config( @@ -286,6 +294,267 @@ def test_thresholds_from_config(self): assert config.title_threshold == 0.7 +class TestNumericValidation: + @pytest.mark.parametrize("value", [0.0, 0.5, 1.0, "0.25"]) + def test_valid_thresholds_are_accepted(self, value): + config = m.build_source_config( + make_args(match_threshold=value, title_threshold=value), + {}, + ) + + assert config.match_threshold == float(value) + assert config.title_threshold == float(value) + + @pytest.mark.parametrize( + "value", + [-0.1, 1.1, float("nan"), float("inf"), float("-inf"), "not-a-number"], + ) + def test_invalid_match_threshold_is_rejected(self, value): + with pytest.raises(ValueError, match="match_threshold"): + m.build_source_config(make_args(match_threshold=value), {}) + + @pytest.mark.parametrize( + "value", + [-0.1, 1.1, float("nan"), float("inf"), float("-inf"), "not-a-number"], + ) + def test_invalid_title_threshold_is_rejected(self, value): + with pytest.raises(ValueError, match="title_threshold"): + m.build_source_config(make_args(title_threshold=value), {}) + + @pytest.mark.parametrize( + "value", + ["-0.1", "1.1", "nan", "inf", "-inf", "not-a-number"], + ) + def test_invalid_threshold_from_config_is_rejected(self, value): + with pytest.raises(ValueError, match="match_threshold"): + m.build_source_config( + make_args(), + {"match_threshold": value}, + ) + + @pytest.mark.parametrize("value", ["0", "0.25", "3.0"]) + def test_valid_provider_intervals_are_accepted(self, value): + config = m.build_source_config( + make_args(), + {"deezer_min_interval": value}, + ) + + assert config.providers["deezer"]["min_interval"] == float(value) + + def test_zero_interval_is_preserved(self): + config = m.build_source_config(make_args(), {}) + + assert config.providers["spotify"]["min_interval"] == 0.0 + + @pytest.mark.parametrize( + "value", + ["-1", "nan", "inf", "-inf", "not-a-number"], + ) + def test_invalid_provider_interval_from_config_is_rejected(self, value): + with pytest.raises(ValueError, match="deezer_min_interval"): + m.build_source_config( + make_args(), + {"deezer_min_interval": value}, + ) + + @pytest.mark.parametrize( + "value", + ["-1", "nan", "inf", "-inf", "not-a-number"], + ) + def test_invalid_provider_interval_from_cli_is_rejected(self, value): + with pytest.raises(ValueError, match="deezer.min_interval"): + m.build_source_config( + make_args(provider_opt=[f"deezer.min_interval={value}"]), + {}, + ) + + def test_provider_defaults_are_valid(self): + config = m.build_source_config(make_args(), {}) + + for name, defaults in m.PROVIDER_DEFAULTS.items(): + assert ( + config.providers[name]["min_interval"] + == defaults["min_interval"] + ) + + +class TestCliPrecedence: + def test_cli_selection_overrides_config_disable_sources(self): + settings = { + "metadata_sources": "itunes", + "disable_sources": "deezer", + "deezer_enabled": "false", + } + + config = m.build_source_config( + make_args(metadata_sources="deezer"), + settings, + ) + + assert config.metadata_sources == ["deezer"] + assert config.is_enabled("deezer") + assert not config.providers["deezer"]["disabled"] + + def test_config_enabled_provider_is_disabled_by_cli(self): + config = m.build_source_config( + make_args(disable_sources="deezer"), + {"metadata_sources": "deezer,itunes"}, + ) + + assert config.metadata_sources == ["itunes"] + assert not config.is_enabled("deezer") + + def test_cli_changes_config_source_order(self): + config = m.build_source_config( + make_args(metadata_sources="deezer,itunes"), + {"metadata_sources": "itunes,deezer"}, + ) + + assert config.metadata_sources == ["deezer", "itunes"] + + def test_cli_none_keeps_youtube_enabled(self): + config = m.build_source_config( + make_args(metadata_sources="none"), + { + "metadata_sources": "deezer,itunes", + "deezer_enabled": "true", + }, + ) + + assert config.metadata_sources == [] + assert config.none_selected + assert config.youtube_enabled + + def test_cli_selection_with_youtube_enabled(self): + config = m.build_source_config( + make_args(metadata_sources="deezer"), + {"metadata_sources": "itunes", "youtube_enabled": "true"}, + ) + + assert config.metadata_sources == ["deezer"] + assert config.youtube_enabled + + def test_cli_selection_with_youtube_disabled(self): + config = m.build_source_config( + make_args( + metadata_sources="deezer", + disable_sources="youtube", + ), + {"metadata_sources": "itunes"}, + ) + + assert config.metadata_sources == ["deezer"] + assert not config.youtube_enabled + + def test_config_disabled_youtube_stays_disabled_with_cli_selection(self): + config = m.build_source_config( + make_args(metadata_sources="deezer"), + {"metadata_sources": "itunes", "youtube_enabled": "false"}, + ) + + assert config.metadata_sources == ["deezer"] + assert not config.youtube_enabled + + def test_cli_disable_wins_over_cli_selection(self): + config = m.build_source_config( + make_args( + metadata_sources="deezer,itunes", + disable_sources="deezer", + ), + {}, + ) + + assert config.metadata_sources == ["itunes"] + assert not config.is_enabled("deezer") + + def test_cli_disable_wins_over_cli_provider_enable(self): + config = m.build_source_config( + make_args( + provider_opt=["deezer.enabled=true"], + disable_sources="deezer", + ), + {}, + ) + + assert config.metadata_sources == ["itunes"] + assert not config.is_enabled("deezer") + + def test_cli_provider_enable_overrides_config_disable_sources(self): + config = m.build_source_config( + make_args(provider_opt=["deezer.enabled=true"]), + { + "metadata_sources": "itunes", + "disable_sources": "deezer", + }, + ) + + assert config.metadata_sources == ["itunes", "deezer"] + assert config.is_enabled("deezer") + + def test_disabled_provider_is_never_queried(self, monkeypatch): + calls = [] + + def fake_deezer(runtime, artist, title, config): + calls.append("deezer") + return [{"title": title, "artist": artist}] + + def fake_itunes(runtime, artist, title, config): + calls.append("itunes") + return [{"title": title, "artist": artist, "source": "itunes"}] + + monkeypatch.setitem(m.PROVIDER_FUNCTIONS, "deezer", fake_deezer) + monkeypatch.setitem(m.PROVIDER_FUNCTIONS, "itunes", fake_itunes) + config = m.build_source_config( + make_args(), + { + "metadata_sources": "deezer,itunes", + "disable_sources": "deezer", + }, + ) + + result = m.resolve_metadata( + "Daft Punk", + "One More Time", + config, + make_runtime(), + ) + + assert result["source"] == "itunes" + assert calls == ["itunes"] + + def test_config_remains_unchanged_after_cli_overrides(self): + settings = { + "metadata_sources": "itunes", + "disable_sources": "deezer", + "deezer_enabled": "false", + "youtube_enabled": "true", + } + original = dict(settings) + + m.build_source_config( + make_args( + metadata_sources="deezer", + disable_sources="youtube", + ), + settings, + ) + + assert settings == original + + def test_config_disabled_provider_is_not_promoted_by_cli_selection(self): + config = m.build_source_config( + make_args(metadata_sources="itunes"), + { + "metadata_sources": "itunes", + "disable_sources": "vocadb", + }, + ) + + assert m.effective_metadata_sources( + config, "初音ミク", "消失" + ) == ["itunes"] + + class TestVocadbPromotion: def test_cjk_promotes_vocadb_temporarily(self): config = make_config(["itunes", "vocadb"]) @@ -898,6 +1167,49 @@ def test_entries_are_independent_per_provider(self, tmp_path): assert cache.get("A", "B", "itunes")["source"] == "itunes" assert cache.get("A", "B", "deezer")["source"] == "deezer" + def test_incomplete_result_does_not_overwrite_better_entry(self, tmp_path): + path = tmp_path / m.CACHE_FILENAME + cache = m.MetadataCache(path) + cache.set( + "A", + "B", + "itunes", + {"title": "B", "artist": "A", "source": "itunes"}, + ) + + assert cache.set("A", "B", "itunes", {"title": None}) is False + assert cache.get("A", "B", "itunes")["title"] == "B" + + def test_lower_scored_result_does_not_replace_better_entry(self, tmp_path): + cache = m.MetadataCache(tmp_path / m.CACHE_FILENAME) + cache.set( + "A", + "B", + "itunes", + {"title": "B", "artist": "A", "score": 0.9}, + ) + + assert cache.set( + "A", + "B", + "itunes", + {"title": "B", "artist": "A", "score": 0.5}, + ) is False + assert cache.get("A", "B", "itunes")["score"] == 0.9 + + def test_unrelated_entries_survive_a_new_write(self, tmp_path): + path = tmp_path / m.CACHE_FILENAME + cache = m.MetadataCache(path) + cache.set("A", "B", "itunes", {"title": "B", "source": "itunes"}) + cache.set("C", "D", "deezer", {"title": "D", "source": "deezer"}) + cache.set("A", "B", "deezer", {"title": "B", "source": "deezer"}) + + reloaded = m.MetadataCache(path) + + assert reloaded.get("A", "B", "itunes")["source"] == "itunes" + assert reloaded.get("A", "B", "deezer")["source"] == "deezer" + assert reloaded.get("C", "D", "deezer")["source"] == "deezer" + def test_corrupted_cache_is_handled(self, tmp_path): path = tmp_path / m.CACHE_FILENAME path.write_text("not json at all", encoding="utf-8") @@ -913,6 +1225,47 @@ def test_invalid_cache_shape_is_handled(self, tmp_path): assert m.MetadataCache(path).entries == {} + def test_disabled_provider_cache_is_not_used( + self, monkeypatch, tmp_path + ): + calls = [] + + def fake_itunes(runtime, artist, title, config): + calls.append("itunes") + return [{"title": title, "artist": artist, "source": "itunes"}] + + monkeypatch.setitem(m.PROVIDER_FUNCTIONS, "itunes", fake_itunes) + cache = m.MetadataCache(tmp_path / m.CACHE_FILENAME) + cache.set( + "Daft Punk", + "One More Time", + "deezer", + { + "title": "Wrong cached result", + "artist": "Daft Punk", + "source": "deezer", + "score": 1.0, + }, + ) + runtime = make_runtime(cache=cache) + config = m.build_source_config( + make_args(), + { + "metadata_sources": "deezer,itunes", + "disable_sources": "deezer", + }, + ) + + result = m.resolve_metadata( + "Daft Punk", + "One More Time", + config, + runtime, + ) + + assert result["source"] == "itunes" + assert calls == ["itunes"] + def test_cached_priority_result_is_used(self, monkeypatch, tmp_path): calls = [] @@ -963,8 +1316,159 @@ def test_youtube_thumbnail_from_id(self): def test_image_validation(self): assert m.is_image_bytes(b"\xff\xd8\xff\xe0data") assert m.is_image_bytes(b"\x89PNG\r\n\x1a\n") + assert m.is_image_bytes(b"GIF87a") + assert m.is_image_bytes(b"GIF89a") + assert m.is_image_bytes(b"RIFF\x00\x00\x00\x00WEBP") assert not m.is_image_bytes(b"not an image") assert not m.is_image_bytes(b"") + assert not m.is_image_bytes(b"RIFF\x00\x00\x00\x00WAVE") + assert not m.is_image_bytes(b"WEBP\x00\x00\x00\x00RIFF") + + @pytest.mark.parametrize( + ("data", "expected"), + [ + (b"\xff\xd8\xff\xe0data", "jpeg"), + (b"\x89PNG\r\n\x1a\n", "png"), + (b"GIF87a", "gif"), + (b"GIF89a", "gif"), + (b"RIFF\x00\x00\x00\x00WEBP", "webp"), + ], + ) + def test_image_format_detection(self, data, expected): + assert m.detect_image_format(data) == expected + + def test_image_extensions_and_mime_types_match_signature(self): + assert m.IMAGE_FORMATS["jpeg"] == ("image/jpeg", ".jpg") + assert m.IMAGE_FORMATS["png"] == ("image/png", ".png") + assert m.IMAGE_FORMATS["gif"] == ("image/gif", ".gif") + assert m.IMAGE_FORMATS["webp"] == ("image/webp", ".webp") + + def test_download_cover_uses_signature_not_content_type( + self, monkeypatch, tmp_path + ): + class Response: + content = b"\x89PNG\r\n\x1a\nrest" + headers = {"Content-Type": "image/jpeg"} + + def raise_for_status(self): + pass + + monkeypatch.setattr( + m.requests, + "get", + lambda *a, **k: Response(), + ) + destination = tmp_path / "cover.jpg" + + format_name = m.download_cover("https://img/cover.jpg", destination) + + assert format_name == "png" + assert (tmp_path / "cover.png").read_bytes() == Response.content + assert not destination.exists() + + @pytest.mark.parametrize( + "content", + [b"", b"not an image", b"RIFF\x00\x00\x00\x00WAVE"], + ) + def test_download_cover_rejects_invalid_images( + self, monkeypatch, tmp_path, content + ): + class Response: + def raise_for_status(self): + pass + + response = Response() + response.content = content + monkeypatch.setattr( + m.requests, + "get", + lambda *a, **k: response, + ) + + with pytest.raises(ValueError, match="valid image"): + m.download_cover("https://img/cover.jpg", tmp_path / "cover") + + @pytest.mark.parametrize( + ("content", "extension"), + [ + (b"\xff\xd8\xff\xe0data", ".jpg"), + (b"\x89PNG\r\n\x1a\nrest", ".png"), + (b"GIF89a-rest", ".gif"), + (b"RIFF\x00\x00\x00\x00WEBP-rest", ".webp"), + ], + ) + def test_download_best_cover_uses_actual_extension( + self, monkeypatch, tmp_path, content, extension + ): + class Response: + pass + + response = Response() + response.content = content + + def raise_for_status(): + pass + + response.raise_for_status = raise_for_status + monkeypatch.setattr( + m.requests, + "get", + lambda *a, **k: response, + ) + metadata = { + "cover_url": "https://img/cover.jpg", + "source": "itunes", + } + + path = m.download_best_cover( + metadata, + None, + tmp_path / "cover", + False, + ) + + assert path == tmp_path / f"cover{extension}" + assert path.read_bytes() == content + assert not (tmp_path / "cover").exists() + + def test_download_best_cover_falls_back_after_invalid_image( + self, monkeypatch, tmp_path + ): + class Response: + def __init__(self, content, status=200): + self.content = content + self.status_code = status + + def raise_for_status(self): + if self.status_code >= 400: + raise requests.HTTPError("bad image") + + responses = [ + Response(b"broken"), + Response(b"\x89PNG\r\n\x1a\nrest"), + ] + + def fake_get(url, **kwargs): + return responses.pop(0) + + monkeypatch.setattr(m.requests, "get", fake_get) + metadata = { + "cover_url": "https://img/cover.jpg", + "source": "itunes", + } + video = { + "id": "abc", + "thumbnails": [{"url": "https://yt/thumb.jpg"}], + } + + path = m.download_best_cover( + metadata, + video, + tmp_path / "cover", + True, + ) + + assert path == tmp_path / "cover.png" class TestCli: @@ -1000,19 +1504,31 @@ def test_malformed_provider_option_exits(self, monkeypatch, capsys): assert exc.value.code == 1 assert "Invalid --provider-opt" in capsys.readouterr().out - def test_thresholds_are_shown_and_clamped(self, monkeypatch, capsys): + def test_invalid_thresholds_are_rejected(self, monkeypatch, capsys): + with pytest.raises(SystemExit) as exc: + run_cli( + monkeypatch, + "--match-threshold", + "5", + "--list-sources", + ) + + assert exc.value.code == 1 + assert "must be between 0.0 and 1.0" in capsys.readouterr().out + + def test_valid_thresholds_are_shown(self, monkeypatch, capsys): run_cli( monkeypatch, "--match-threshold", - "5", + "0", "--title-threshold", - "-1", + "1", "--list-sources", ) output = capsys.readouterr().out - assert "Match threshold: 1.0" in output - assert "Title threshold: 0.0" in output + assert "Match threshold: 0.0" in output + assert "Title threshold: 1.0" in output def test_invalid_threshold_type_is_rejected_by_argparse( self, monkeypatch, capsys @@ -1047,6 +1563,62 @@ def test_youtube_disabled_prevents_download(self, monkeypatch, tmp_path): assert (ok, reason) == (False, "YouTube disabled") assert calls == [] + def test_cli_youtube_disable_prevents_network_calls( + self, monkeypatch, tmp_path + ): + calls = [] + monkeypatch.setattr( + m, + "find_youtube_video", + lambda artist, title: calls.append((artist, title)), + ) + config = m.build_source_config( + make_args(disable_sources="youtube"), + {}, + ) + + ok, reason = m.process_song( + None, + "Daft Punk", + "One More Time", + tmp_path, + False, + "m4a", + source_config=config, + runtime=make_runtime(), + ) + + assert (ok, reason) == (False, "YouTube disabled") + assert calls == [] + + def test_config_youtube_disable_prevents_network_calls( + self, monkeypatch, tmp_path + ): + calls = [] + monkeypatch.setattr( + m, + "find_youtube_video", + lambda artist, title: calls.append((artist, title)), + ) + config = m.build_source_config( + make_args(), + {"youtube_enabled": "false"}, + ) + + ok, reason = m.process_song( + None, + "Daft Punk", + "One More Time", + tmp_path, + False, + "m4a", + source_config=config, + runtime=make_runtime(), + ) + + assert (ok, reason) == (False, "YouTube disabled") + assert calls == [] + def test_none_metadata_still_uses_youtube(self, monkeypatch, tmp_path): from conftest import FIXTURES import shutil diff --git a/tests/test_tags_and_files.py b/tests/test_tags_and_files.py index ef13517..9d12990 100644 --- a/tests/test_tags_and_files.py +++ b/tests/test_tags_and_files.py @@ -11,6 +11,10 @@ import trackfetch as m JPEG = b"\xff\xd8\xff\xe0fake-jpeg" +PNG = b"\x89PNG\r\n\x1a\nfake-png" +GIF = b"GIF89afake-gif" +WEBP = b"RIFF\x00\x00\x00\x00WEBPfake-webp" +INVALID_IMAGE = b"not an image" @pytest.fixture @@ -206,3 +210,89 @@ def test_ignores_blank_lines_and_whitespace(self, tmp_path): done = tmp_path / "done.txt" done.write_text(" A - B \n\n\nC - D\n", encoding="utf-8") assert m.read_done(done) == {"A - B", "C - D"} + + +class TestCoverFormatMimeTypes: + @pytest.mark.parametrize( + ("data", "mime"), + [ + (JPEG, "image/jpeg"), + (PNG, "image/png"), + (GIF, "image/gif"), + (WEBP, "image/webp"), + ], + ) + def test_mp3_embeds_matching_mime(self, mp3, tmp_path, metadata, data, mime): + cover = tmp_path / "cover.img" + cover.write_bytes(data) + + m.add_metadata(mp3, cover, metadata) + + apic = ID3(mp3).getall("APIC")[0] + assert apic.data == data + assert apic.mime == mime + + def test_mp3_skips_invalid_cover(self, mp3, tmp_path, metadata): + cover = tmp_path / "cover.img" + cover.write_bytes(INVALID_IMAGE) + + m.add_metadata(mp3, cover, metadata) + + assert not ID3(mp3).getall("APIC") + + @pytest.mark.parametrize( + ("data", "mime"), + [ + (JPEG, "image/jpeg"), + (PNG, "image/png"), + (GIF, "image/gif"), + (WEBP, "image/webp"), + ], + ) + def test_opus_embeds_matching_mime(self, opus, tmp_path, metadata, data, mime): + cover = tmp_path / "cover.img" + cover.write_bytes(data) + + m.add_metadata(opus, cover, metadata) + + picture = opus_picture(OggOpus(opus)) + assert picture.data == data + assert picture.mime == mime + + def test_opus_skips_invalid_cover(self, opus, tmp_path, metadata): + cover = tmp_path / "cover.img" + cover.write_bytes(INVALID_IMAGE) + + m.add_metadata(opus, cover, metadata) + + assert "METADATA_BLOCK_PICTURE" not in OggOpus(opus) + + @pytest.mark.parametrize( + ("data", "image_format"), + [ + (JPEG, MP4Cover.FORMAT_JPEG), + (PNG, MP4Cover.FORMAT_PNG), + ], + ) + def test_m4a_embeds_supported_formats( + self, m4a, tmp_path, metadata, data, image_format + ): + cover = tmp_path / "cover.img" + cover.write_bytes(data) + + m.add_metadata(m4a, cover, metadata) + + covr = MP4(m4a)["covr"][0] + assert bytes(covr) == data + assert covr.imageformat == image_format + + @pytest.mark.parametrize("data", [GIF, WEBP, INVALID_IMAGE]) + def test_m4a_does_not_mislabel_unsupported_formats( + self, m4a, tmp_path, metadata, data + ): + cover = tmp_path / "cover.img" + cover.write_bytes(data) + + m.add_metadata(m4a, cover, metadata) + + assert "covr" not in MP4(m4a) diff --git a/trackfetch.py b/trackfetch.py index 5c376d6..baa7b88 100755 --- a/trackfetch.py +++ b/trackfetch.py @@ -5,6 +5,7 @@ import base64 import configparser import json +import math import os import re import shutil @@ -346,6 +347,11 @@ def parse_interval(value: str, label: str) -> float: f"Invalid number for '{label}': {value!r}" ) from error + if not math.isfinite(interval): + raise ValueError( + f"'{label}' must be a finite number: {value!r}" + ) + if interval < 0: raise ValueError(f"'{label}' must not be negative: {value!r}") @@ -418,7 +424,17 @@ def threshold_value(value, default: float, label: str) -> float: except (TypeError, ValueError) as error: raise ValueError(f"Invalid value for '{label}': {value!r}") from error - return min(1.0, max(0.0, number)) + if not math.isfinite(number): + raise ValueError( + f"'{label}' must be a finite number between 0.0 and 1.0: {value!r}" + ) + + if not 0.0 <= number <= 1.0: + raise ValueError( + f"'{label}' must be between 0.0 and 1.0: {value!r}" + ) + + return number def build_source_config(args, settings): @@ -517,19 +533,40 @@ def build_source_config(args, settings): else: sources = normalize_metadata_sources(raw_sources) - disabled_sources = set() - - for raw in ( - config_str_value(settings, "disable_sources"), - getattr(args, "disable_sources", None), - ): - if raw: - disabled_sources.update(normalize_disable_sources(raw)) - - remove = set(disabled_sources) | set(cli_disabled) - - if not cli_sources_given: - remove.update(config_disabled) + config_disabled_sources = set( + normalize_disable_sources( + config_str_value(settings, "disable_sources") or "" + ) + ) + cli_disabled_sources = set( + normalize_disable_sources( + getattr(args, "disable_sources", None) or "" + ) + ) + all_disabled_sources = config_disabled_sources | cli_disabled_sources + + config_disabled_metadata = config_disabled_sources - set(ARTWORK_FALLBACKS) + cli_disabled_metadata = cli_disabled_sources - set(ARTWORK_FALLBACKS) + + if cli_sources_given: + # A CLI selection is an explicit override of the configured source + # list and of any per-provider configuration that disables it. Only + # CLI disable operations may remove an explicitly selected provider. + remove = cli_disabled_metadata | set(cli_disabled) + disabled_for_promotion = ( + cli_disabled_metadata + | set(cli_disabled) + | (config_disabled | config_disabled_metadata) - set(sources) + - set(cli_enabled) + ) + else: + # An explicit CLI provider enable still wins over config disabling, + # but never over an explicit CLI disable. + remove = ( + config_disabled_metadata | set(config_disabled) + ) - set(cli_enabled) + remove |= cli_disabled_metadata | set(cli_disabled) + disabled_for_promotion = set(remove) sources = [name for name in sources if name not in remove] @@ -545,7 +582,7 @@ def build_source_config(args, settings): for name in METADATA_PROVIDERS: providers[name]["enabled"] = name in sources - providers[name]["disabled"] = name in remove + providers[name]["disabled"] = name in disabled_for_promotion youtube_enabled = YOUTUBE_DEFAULT_ENABLED @@ -555,7 +592,7 @@ def build_source_config(args, settings): "youtube_enabled", ) - if "youtube" in disabled_sources: + if "youtube" in all_disabled_sources: youtube_enabled = False match_threshold = threshold_value( @@ -808,12 +845,30 @@ def get(self, artist: str, title: str, provider: str): return dict(result) def set(self, artist: str, title: str, provider: str, result: dict): + if not isinstance(result, dict) or not result.get("title"): + # An incomplete result must not replace a usable cached entry. + return False + key = self.key(artist, title) entry = self.entries.get(key) if not isinstance(entry, dict): entry = {} + existing = entry.get(provider) + + if isinstance(existing, dict) and existing.get("title"): + old_score = existing.get("score") + new_score = result.get("score") + + try: + if old_score is not None and ( + new_score is None or float(new_score) < float(old_score) + ): + return False + except (TypeError, ValueError): + pass + stored = { field: result.get(field) for field in ( @@ -833,6 +888,8 @@ def set(self, artist: str, title: str, provider: str, result: dict): self.entries[key] = entry self.save() + return True + def sanitize_filename(name: str) -> str: name = re.sub(r'[<>:"/\\|?*\x00-\x1f]', "_", name) @@ -995,23 +1052,50 @@ def get_track_metadata(track, fallback_artist, fallback_title): } -def is_image_bytes(data: bytes) -> bool: - """Check common image signatures before writing a cover file.""" +IMAGE_FORMATS = { + "jpeg": ("image/jpeg", ".jpg"), + "png": ("image/png", ".png"), + "gif": ("image/gif", ".gif"), + "webp": ("image/webp", ".webp"), +} + + +def detect_image_format(data: bytes): + """Return the image format from its signature, or None if unsupported.""" if not data: - return False + return None - signatures = ( - b"\xff\xd8\xff", # JPEG - b"\x89PNG\r\n\x1a\n", # PNG - b"GIF87a", - b"GIF89a", - b"RIFF", # WebP (RIFF....WEBP below) - ) + if data.startswith(b"\xff\xd8\xff"): + return "jpeg" - if data.startswith(signatures): - return True + if data.startswith(b"\x89PNG\r\n\x1a\n"): + return "png" + + if data.startswith((b"GIF87a", b"GIF89a")): + return "gif" - return b"WEBP" in data[:16] + if ( + len(data) >= 12 + and data.startswith(b"RIFF") + and data[8:12] == b"WEBP" + ): + return "webp" + + return None + + +def image_mime_type(data: bytes): + format_name = detect_image_format(data) + + if format_name is None: + return None + + return IMAGE_FORMATS[format_name][0] + + +def is_image_bytes(data: bytes) -> bool: + """Check common image signatures before writing a cover file.""" + return detect_image_format(data) is not None def download_cover(url: str, destination: Path): @@ -1025,10 +1109,19 @@ def download_cover(url: str, destination: Path): response.raise_for_status() - if not is_image_bytes(response.content): + format_name = detect_image_format(response.content) + + if format_name is None: raise ValueError("response is not a valid image") - destination.write_bytes(response.content) + destination = Path(destination) + final_path = destination.with_suffix(IMAGE_FORMATS[format_name][1]) + final_path.write_bytes(response.content) + + if final_path != destination and destination.exists(): + destination.unlink() + + return format_name def youtube_thumbnail_urls(video): @@ -1917,16 +2010,18 @@ def add_mp3_metadata( if cover_path.exists(): image_data = cover_path.read_bytes() - - audio.add( - APIC( - encoding=3, - mime="image/jpeg", - type=3, - desc="Cover", - data=image_data, + mime = image_mime_type(image_data) + + if mime is not None: + audio.add( + APIC( + encoding=3, + mime=mime, + type=3, + desc="Cover", + data=image_data, + ) ) - ) audio.save( mp3_path, @@ -1959,15 +2054,19 @@ def add_opus_metadata( audio[key] = str(value) if cover_path.exists(): - picture = Picture() - picture.type = 3 - picture.mime = "image/jpeg" - picture.desc = "Cover" - picture.data = cover_path.read_bytes() + image_data = cover_path.read_bytes() + mime = image_mime_type(image_data) - audio["METADATA_BLOCK_PICTURE"] = base64.b64encode( - picture.write() - ).decode("ascii") + if mime is not None: + picture = Picture() + picture.type = 3 + picture.mime = mime + picture.desc = "Cover" + picture.data = image_data + + audio["METADATA_BLOCK_PICTURE"] = base64.b64encode( + picture.write() + ).decode("ascii") audio.save() @@ -2001,12 +2100,19 @@ def add_m4a_metadata( ] if cover_path.exists(): - audio["covr"] = [ - MP4Cover( - cover_path.read_bytes(), - imageformat=MP4Cover.FORMAT_JPEG, - ) - ] + image_data = cover_path.read_bytes() + format_name = detect_image_format(image_data) + + # MP4 cover art supports JPEG and PNG. Embedding a GIF or WebP as + # JPEG would mislabel the bytes, so leave it out for this format. + if format_name == "jpeg": + audio["covr"] = [ + MP4Cover(image_data, imageformat=MP4Cover.FORMAT_JPEG) + ] + elif format_name == "png": + audio["covr"] = [ + MP4Cover(image_data, imageformat=MP4Cover.FORMAT_PNG) + ] audio.save() @@ -2046,7 +2152,11 @@ def append_line(path: Path, text: str): def download_best_cover(metadata, video, cover_path, youtube_enabled): - """Download provider artwork, then fall back to a YouTube thumbnail.""" + """Download provider artwork, then fall back to a YouTube thumbnail. + + Returns the path of the saved image with an extension that matches the + actual image signature, or None when no usable image was downloaded. + """ candidates = [] if metadata.get("cover_url"): @@ -2059,14 +2169,39 @@ def download_best_cover(metadata, video, cover_path, youtube_enabled): candidates.append((url, "YouTube")) last_error = None + cover_path = Path(cover_path) for url, source in candidates: try: - download_cover(url, cover_path) + result = download_cover(url, cover_path) + + if isinstance(result, Path): + actual_path = result + elif result in IMAGE_FORMATS: + actual_path = cover_path.with_suffix( + IMAGE_FORMATS[result][1] + ) + else: + actual_path = cover_path - if cover_path.exists() and cover_path.stat().st_size > 0: + if not actual_path.exists(): + actual_path = cover_path + + image_data = actual_path.read_bytes() + format_name = detect_image_format(image_data) + + if format_name is None: + raise ValueError("response is not a valid image") + + extension = IMAGE_FORMATS[format_name][1] + final_path = actual_path.with_suffix(extension) + + if actual_path != final_path: + actual_path.replace(final_path) + + if final_path.stat().st_size > 0: print(f"{source} cover downloaded") - return True + return final_path except Exception as error: last_error = error @@ -2074,7 +2209,7 @@ def download_best_cover(metadata, video, cover_path, youtube_enabled): if last_error is not None: print(f"WARNING: cover download failed: {last_error}") - return False + return None def process_song( @@ -2175,15 +2310,16 @@ def process_song( if not audio_path: return False, "yt-dlp download failed" - cover_path = temp_dir / "cover.jpg" - - download_best_cover( + cover_path = download_best_cover( metadata, video, - cover_path, + temp_dir / "cover", youtube_enabled, ) + if cover_path is None: + cover_path = temp_dir / "cover.jpg" + try: add_metadata( audio_path, From e9bd1659294cafee21797aa125029fcf6805edcf Mon Sep 17 00:00:00 2001 From: ByteMe6 Date: Sun, 15 Nov 2026 18:42:43 +0200 Subject: [PATCH 5/8] docs: describe source precedence, validation and artwork handling --- CHANGELOG.md | 5 +++++ README.md | 26 +++++++++++++++++++++----- README.ru.md | 26 +++++++++++++++++++++----- README.uk.md | 26 +++++++++++++++++++++----- docs/tldr/trackfetch.md | 10 +++++++++- 5 files changed, 77 insertions(+), 16 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index c876c03..4d19f30 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -25,6 +25,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/). - `brew install trackfetch` no longer compiles `ffmpeg` on macOS: the formula installs a static prebuilt `ffmpeg` next to the prebuilt binary, so the first install takes seconds even where Homebrew has no bottle for it. ### Fixed +- A CLI metadata selection now overrides conflicting `disable_sources` and `*_enabled=false` configuration, while an explicit CLI disable still wins over a CLI selection. The config file is never rewritten. +- `match_threshold` and `title_threshold` values outside `0.0`-`1.0`, NaN and infinities are now rejected instead of being silently clamped. +- Provider `min_interval` values that are NaN, infinite or negative are rejected consistently from the CLI, the config file and `--provider-opt`. +- Downloaded artwork is identified by its actual signature, so PNG, GIF and WebP files get the correct extension and MIME type instead of always being labelled JPEG. M4A skips GIF/WebP artwork rather than mislabelling it. +- An incomplete metadata result can no longer overwrite a usable entry in `metadata-cache.json`. - A negative `--delay` now gives a clear error instead of a Python traceback. - A UTF-8 BOM in the input file no longer ends up in the artist, the title and the file name. - Duplicate tracks are removed before downloading, so they are not counted twice and `done.txt` stays clean. diff --git a/README.md b/README.md index f3353b6..5ea0f9b 100644 --- a/README.md +++ b/README.md @@ -194,11 +194,11 @@ trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f { | `-f`, `--format` | `m4a` | Audio format: `mp3`, `m4a` or `opus`. See [Audio formats](#audio-formats). | | `--title-only` | off | Name files `Title.m4a` instead of `Artist - Title.m4a` | | `--delay` | `1.0` | Seconds to wait between songs. Raise it for long lists. | -| `-s`, `--metadata-sources` | `itunes` | Comma-separated metadata priority, for example `deezer,itunes,musicbrainz`. `none` disables metadata lookups but keeps YouTube. | -| `--disable-sources` | — | Comma-separated sources to disable, for example `spotify,youtube`. | +| `-s`, `--metadata-sources` | `itunes` | Comma-separated metadata priority, for example `deezer,itunes,musicbrainz`. `none` disables metadata lookups but keeps YouTube. A CLI selection overrides configured disabling for the selected providers. | +| `--disable-sources` | — | Comma-separated sources to disable, for example `spotify,youtube`. Takes precedence over a CLI metadata selection for the same provider. | | `--provider-opt` | — | Provider setting as `NAME.KEY=VALUE`, for example `itunes.country=ua`. Can be repeated. | -| `--match-threshold` | `0.6` | Minimum overall match score, from `0.0` to `1.0`. | -| `--title-threshold` | `0.8` | Minimum title similarity, from `0.0` to `1.0`. | +| `--match-threshold` | `0.6` | Minimum overall match score, from `0.0` to `1.0`. Values outside that range, NaN and infinities are rejected. | +| `--title-threshold` | `0.8` | Minimum title similarity, from `0.0` to `1.0`. Values outside that range, NaN and infinities are rejected. | | `--list-sources` | — | Show available metadata providers and artwork fallbacks, then exit. Makes no network requests. | | `--spotify-client-id` | `$SPOTIFY_CLIENT_ID` | Spotify API client ID. See [Spotify credentials](#spotify-credentials). | | `--spotify-client-secret` | `$SPOTIFY_CLIENT_SECRET` | Spotify API client secret. | @@ -231,7 +231,11 @@ fallback. The other providers are off unless you select or enable them: The order in `-s` is the lookup priority. If the first provider has no suitable match, trackfetch tries the next one. The first result that passes both -matching thresholds wins. +matching thresholds wins. Command-line choices override the config file for +that run: `-s deezer` enables Deezer even if the config disables it, while +`--disable-sources deezer` still disables it. Both thresholds must be finite +numbers from `0.0` to `1.0`; invalid values stop with an error instead of being +silently clamped. ```bash trackfetch songs.txt -s deezer,itunes,musicbrainz,vocadb @@ -257,6 +261,12 @@ Metadata is cached per provider in `metadata-cache.json` in the output directory. A lower-priority cached result never prevents a higher-priority provider from being retried after recovery. +Artwork is identified by its actual bytes, not by the URL or the HTTP +`Content-Type` header. JPEG, PNG, GIF and WebP keep their real extension and +MIME type. MP3 and Opus can embed all four; M4A supports JPEG and PNG, so GIF or +WebP artwork is skipped for that container instead of being mislabelled as +JPEG. + ### Inline tracks Skip the file and name the tracks right on the command line: @@ -324,6 +334,12 @@ precedence is always the same: 2. the config file, 3. the built-in default (the current directory for the output folder). +For source selection, a CLI `-s` list overrides both `metadata_sources` and +conflicting `disable_sources`/`*_enabled=false` entries for the providers it +names. An explicit CLI disable from `--disable-sources` or +`--provider-opt NAME.enabled=false` wins over a CLI selection. The config file +itself is never rewritten. + trackfetch looks for the config file in this order: the path given with `--config`, the path in `$TRACKFETCH_CONFIG`, `trackfetch.ini` in the current directory, `$XDG_CONFIG_HOME/trackfetch/trackfetch.ini`, diff --git a/README.ru.md b/README.ru.md index a371c49..ef39616 100644 --- a/README.ru.md +++ b/README.ru.md @@ -194,11 +194,11 @@ trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f { | `-f`, `--format` | `m4a` | Формат звука: `mp3`, `m4a` или `opus`. См. [Форматы звука](#форматы-звука). | | `--title-only` | выключен | Называть файлы `Название.m4a` вместо `Исполнитель - Название.m4a` | | `--delay` | `1.0` | Пауза между песнями в секундах. Для длинных списков её стоит увеличить. | -| `-s`, `--metadata-sources` | `itunes` | Приоритет источников через запятую, например `deezer,itunes,musicbrainz`. `none` отключает метаданные, но оставляет YouTube. | -| `--disable-sources` | — | Источники, которые нужно отключить, например `spotify,youtube`. | +| `-s`, `--metadata-sources` | `itunes` | Приоритет источников через запятую, например `deezer,itunes,musicbrainz`. `none` отключает метаданные, но оставляет YouTube. Выбор в командной строке переопределяет отключение этих источников в конфиге. | +| `--disable-sources` | — | Источники, которые нужно отключить, например `spotify,youtube`. Имеет приоритет над выбором источника в `-s`. | | `--provider-opt` | — | Настройка источника `NAME.KEY=VALUE`, например `itunes.country=ua`. Можно повторять. | -| `--match-threshold` | `0.6` | Минимальная общая оценка совпадения от `0.0` до `1.0`. | -| `--title-threshold` | `0.8` | Минимальное сходство названия от `0.0` до `1.0`. | +| `--match-threshold` | `0.6` | Минимальная общая оценка совпадения от `0.0` до `1.0`. Значения вне диапазона, NaN и бесконечности отклоняются. | +| `--title-threshold` | `0.8` | Минимальное сходство названия от `0.0` до `1.0`. Значения вне диапазона, NaN и бесконечности отклоняются. | | `--list-sources` | — | Показать доступные источники и запасные варианты обложек и выйти. Сеть не используется. | | `--spotify-client-id` | `$SPOTIFY_CLIENT_ID` | Client ID для Spotify API. См. [Данные Spotify](#данные-spotify). | | `--spotify-client-secret` | `$SPOTIFY_CLIENT_SECRET` | Client secret для Spotify API. | @@ -231,7 +231,11 @@ trackfetch --list-sources Порядок в `-s` — это приоритет поиска. Если первый источник не дал подходящего результата, trackfetch пробует следующий. Побеждает первый результат, который -проходит оба порога совпадения. +проходит оба порога совпадения. Параметры командной строки переопределяют +конфиг для этого запуска: `-s deezer` включает Deezer, даже если в конфиге он +отключён, а `--disable-sources deezer` по-прежнему его выключает. Оба порога +должны быть конечными числами от `0.0` до `1.0`; недопустимые значения +завершают работу с ошибкой, а не обрезаются молча. ```bash trackfetch songs.txt -s deezer,itunes,musicbrainz,vocadb @@ -256,6 +260,12 @@ YouTube также отключает загрузку звука, потому Метаданные кешируются отдельно для каждого источника в `metadata-cache.json` в папке вывода. Результат из кеша источника с низким приоритетом не мешает повторной попытке источника с высоким приоритетом после восстановления. + +Формат обложки определяется по самим байтам, а не по URL или заголовку HTTP +`Content-Type`. JPEG, PNG, GIF и WebP сохраняют правильное расширение и MIME +тип. MP3 и Opus могут встраивать все четыре формата; M4A поддерживает JPEG и +PNG, поэтому GIF или WebP для этого контейнера пропускается, а не помечается +как JPEG. ``` ### Треки прямо в аргументах @@ -326,6 +336,12 @@ title_threshold = 0.8 2. конфиг-файл, 3. встроенное значение по умолчанию (для папки вывода — текущая директория). +Для источников список `-s` в командной строке переопределяет и +`metadata_sources`, и конфликтующие `disable_sources`/`*_enabled=false` для +названных в нём источников. Явное отключение через `--disable-sources` или +`--provider-opt NAME.enabled=false` имеет приоритет над выбором в `-s`. Сам +конфиг-файл никогда не изменяется. + Конфиг-файл ищется в таком порядке: путь из `--config`, путь из `$TRACKFETCH_CONFIG`, `trackfetch.ini` в текущей директории, `$XDG_CONFIG_HOME/trackfetch/trackfetch.ini`, diff --git a/README.uk.md b/README.uk.md index f3c6329..fdfab92 100644 --- a/README.uk.md +++ b/README.uk.md @@ -194,11 +194,11 @@ trackfetch [-h] [--track ARTIST - TITLE ...] [-o OUTPUT] [--config CONFIG] [-f { | `-f`, `--format` | `m4a` | Формат звуку: `mp3`, `m4a` або `opus`. Див. [Формати звуку](#формати-звуку). | | `--title-only` | вимкнено | Називати файли `Назва.m4a` замість `Виконавець - Назва.m4a` | | `--delay` | `1.0` | Пауза між піснями в секундах. Для довгих списків її варто збільшити. | -| `-s`, `--metadata-sources` | `itunes` | Пріоритет джерел через кому, наприклад `deezer,itunes,musicbrainz`. `none` вимикає метадані, але залишає YouTube. | -| `--disable-sources` | — | Джерела, які треба вимкнути, наприклад `spotify,youtube`. | +| `-s`, `--metadata-sources` | `itunes` | Пріоритет джерел через кому, наприклад `deezer,itunes,musicbrainz`. `none` вимикає метадані, але залишає YouTube. Вибір у командному рядку перевизначає вимкнення цих джерел у конфігу. | +| `--disable-sources` | — | Джерела, які треба вимкнути, наприклад `spotify,youtube`. Має пріоритет над вибором джерела в `-s`. | | `--provider-opt` | — | Налаштування джерела `NAME.KEY=VALUE`, наприклад `itunes.country=ua`. Можна повторювати. | -| `--match-threshold` | `0.6` | Мінімальна загальна оцінка збігу від `0.0` до `1.0`. | -| `--title-threshold` | `0.8` | Мінімальна схожість назви від `0.0` до `1.0`. | +| `--match-threshold` | `0.6` | Мінімальна загальна оцінка збігу від `0.0` до `1.0`. Значення поза діапазоном, NaN і нескінченності відхиляються. | +| `--title-threshold` | `0.8` | Мінімальна схожість назви від `0.0` до `1.0`. Значення поза діапазоном, NaN і нескінченності відхиляються. | | `--list-sources` | — | Показати доступні джерела й запасні варіанти обкладинок і вийти. Мережа не використовується. | | `--spotify-client-id` | `$SPOTIFY_CLIENT_ID` | Client ID для Spotify API. Див. [Дані Spotify](#дані-spotify). | | `--spotify-client-secret` | `$SPOTIFY_CLIENT_SECRET` | Client secret для Spotify API. | @@ -231,7 +231,11 @@ trackfetch --list-sources Порядок у `-s` — це пріоритет пошуку. Якщо перше джерело не дало відповідного результату, trackfetch пробує наступне. Перемагає перший результат, який -проходить обидва пороги збігу. +проходить обидва пороги збігу. Параметри командного рядка перевизначають +конфіг для цього запуску: `-s deezer` вмикає Deezer, навіть якщо в конфігу його +вимкнено, а `--disable-sources deezer` усе одно його вимикає. Обидва пороги +мають бути скінченними числами від `0.0` до `1.0`; неприпустимі значення +завершують роботу з помилкою, а не обрізаються мовчки. ```bash trackfetch songs.txt -s deezer,itunes,musicbrainz,vocadb @@ -256,6 +260,12 @@ trackfetch songs.txt --match-threshold 0.7 --title-threshold 0.85 Метадані кешуються окремо для кожного джерела в `metadata-cache.json` у теці виводу. Результат із кешу джерела з низьким пріоритетом не заважає повторній спробі джерела з високим пріоритетом після відновлення. + +Формат обкладинки визначається за самими байтами, а не за URL або заголовком +HTTP `Content-Type`. JPEG, PNG, GIF і WebP зберігають правильне розширення та +MIME тип. MP3 і Opus можуть вбудовувати всі чотири формати; M4A підтримує JPEG +і PNG, тому GIF або WebP для цього контейнера пропускається, а не позначається +як JPEG. ``` ### Треки просто в аргументах @@ -326,6 +336,12 @@ title_threshold = 0.8 2. конфіг-файл, 3. вбудоване значення за замовчуванням (для теки виводу — поточна директорія). +Для джерел список `-s` у командному рядку перевизначає і `metadata_sources`, і +конфліктні `disable_sources`/`*_enabled=false` для названих у ньому джерел. +Явне вимкнення через `--disable-sources` або +`--provider-opt NAME.enabled=false` має пріоритет над вибором у `-s`. Сам +конфіг-файл ніколи не змінюється. + Конфіг-файл шукається в такому порядку: шлях із `--config`, шлях із `$TRACKFETCH_CONFIG`, `trackfetch.ini` у поточній директорії, `$XDG_CONFIG_HOME/trackfetch/trackfetch.ini`, diff --git a/docs/tldr/trackfetch.md b/docs/tldr/trackfetch.md index d6ab4c1..cfe233b 100644 --- a/docs/tldr/trackfetch.md +++ b/docs/tldr/trackfetch.md @@ -24,14 +24,22 @@ `trackfetch {{path/to/songs.txt}} --title-only` -- Use a custom metadata priority: +- Use a custom metadata priority (a CLI selection overrides configured disabling): `trackfetch {{path/to/songs.txt}} {{[-s|--metadata-sources]}} {{deezer,itunes,musicbrainz,vocadb}}` +- Use no metadata providers but keep YouTube audio: + +`trackfetch {{path/to/songs.txt}} {{[-s|--metadata-sources]}} none` + - Disable a source (disabling YouTube also disables audio downloads): `trackfetch {{path/to/songs.txt}} --disable-sources {{youtube}}` +- Require a stricter match; both thresholds accept only finite values from 0.0 to 1.0: + +`trackfetch {{path/to/songs.txt}} --match-threshold {{0.7}} --title-threshold {{0.85}}` + - List the available metadata providers and artwork fallbacks: `trackfetch --list-sources` From eac0aa2a9844f7ede9e87e88e48c104d1ca07970 Mon Sep 17 00:00:00 2001 From: ByteMe6 Date: Sun, 15 Nov 2026 21:28:11 +0200 Subject: [PATCH 6/8] fix: reject non-finite delay values A NaN or infinite --delay now exits with a clear error instead of reaching time.sleep and triggering a traceback. --- CHANGELOG.md | 2 +- tests/test_inline.py | 19 +++++++++++++++++++ trackfetch.py | 4 ++++ 3 files changed, 24 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4d19f30..1b32de4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,7 +30,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/). - Provider `min_interval` values that are NaN, infinite or negative are rejected consistently from the CLI, the config file and `--provider-opt`. - Downloaded artwork is identified by its actual signature, so PNG, GIF and WebP files get the correct extension and MIME type instead of always being labelled JPEG. M4A skips GIF/WebP artwork rather than mislabelling it. - An incomplete metadata result can no longer overwrite a usable entry in `metadata-cache.json`. -- A negative `--delay` now gives a clear error instead of a Python traceback. +- A negative, NaN or infinite `--delay` now gives a clear error instead of a Python traceback. - A UTF-8 BOM in the input file no longer ends up in the artist, the title and the file name. - Duplicate tracks are removed before downloading, so they are not counted twice and `done.txt` stays clean. - A song that was already downloaded is no longer counted as a success. diff --git a/tests/test_inline.py b/tests/test_inline.py index 8ac244c..7acad33 100644 --- a/tests/test_inline.py +++ b/tests/test_inline.py @@ -232,6 +232,25 @@ def test_negative_delay_exits(self, pipeline, monkeypatch, tmp_path, capsys): assert exc.value.code == 1 assert "must not be negative" in capsys.readouterr().out + @pytest.mark.parametrize("value", ["nan", "inf", "-inf"]) + def test_non_finite_delay_exits( + self, pipeline, monkeypatch, tmp_path, capsys, value + ): + songs = tmp_path / "songs.txt" + songs.write_text("Daft Punk - One More Time\n", encoding="utf-8") + + with pytest.raises(SystemExit) as exc: + run_cli( + monkeypatch, + songs, + "-o", + tmp_path / "o", + f"--delay={value}", + ) + + assert exc.value.code == 1 + assert "must be a finite number" in capsys.readouterr().out + def test_bom_is_stripped(self, pipeline, monkeypatch, tmp_path): songs = tmp_path / "songs.txt" songs.write_text( diff --git a/trackfetch.py b/trackfetch.py index baa7b88..1052057 100755 --- a/trackfetch.py +++ b/trackfetch.py @@ -2795,6 +2795,10 @@ def main(): if args.delay is None: args.delay = DEFAULT_DELAY + if not math.isfinite(args.delay): + print(f"ERROR: Delay must be a finite number: {args.delay}") + sys.exit(1) + if args.delay < 0: print(f"ERROR: Delay must not be negative: {args.delay}") sys.exit(1) From e0e7e43f4adb72a06bca785e432b28db7aab3927 Mon Sep 17 00:00:00 2001 From: ByteMe6 Date: Sun, 15 Nov 2026 21:29:43 +0200 Subject: [PATCH 7/8] refactor: clarify source precedence and cover-extension handling Name the resolved disable sets explicitly and make the config-vs-CLI precedence readable. Keep download_cover writing to the path it is given and let download_best_cover derive the extension from the bytes on disk. --- tests/test_metadata_sources.py | 3 +- trackfetch.py | 61 +++++++++++++--------------------- 2 files changed, 25 insertions(+), 39 deletions(-) diff --git a/tests/test_metadata_sources.py b/tests/test_metadata_sources.py index ff15fcf..64e377d 100644 --- a/tests/test_metadata_sources.py +++ b/tests/test_metadata_sources.py @@ -1363,8 +1363,7 @@ def raise_for_status(self): format_name = m.download_cover("https://img/cover.jpg", destination) assert format_name == "png" - assert (tmp_path / "cover.png").read_bytes() == Response.content - assert not destination.exists() + assert destination.read_bytes() == Response.content @pytest.mark.parametrize( "content", diff --git a/trackfetch.py b/trackfetch.py index 1052057..34a7add 100755 --- a/trackfetch.py +++ b/trackfetch.py @@ -545,27 +545,27 @@ def build_source_config(args, settings): ) all_disabled_sources = config_disabled_sources | cli_disabled_sources - config_disabled_metadata = config_disabled_sources - set(ARTWORK_FALLBACKS) - cli_disabled_metadata = cli_disabled_sources - set(ARTWORK_FALLBACKS) + config_disables = config_disabled | ( + config_disabled_sources - set(ARTWORK_FALLBACKS) + ) + cli_disables = cli_disabled | ( + cli_disabled_sources - set(ARTWORK_FALLBACKS) + ) if cli_sources_given: # A CLI selection is an explicit override of the configured source - # list and of any per-provider configuration that disables it. Only - # CLI disable operations may remove an explicitly selected provider. - remove = cli_disabled_metadata | set(cli_disabled) - disabled_for_promotion = ( - cli_disabled_metadata - | set(cli_disabled) - | (config_disabled | config_disabled_metadata) - set(sources) - - set(cli_enabled) + # list and of any configured disabling of those providers. Only an + # explicit CLI disable may remove a selected provider. + remove = set(cli_disables) + # A config disable still blocks VocaDB promotion unless the provider + # was also explicitly selected or enabled on the CLI. + disabled_for_promotion = set(cli_disables) | ( + config_disables - set(sources) - set(cli_enabled) ) else: # An explicit CLI provider enable still wins over config disabling, # but never over an explicit CLI disable. - remove = ( - config_disabled_metadata | set(config_disabled) - ) - set(cli_enabled) - remove |= cli_disabled_metadata | set(cli_disabled) + remove = (config_disables - set(cli_enabled)) | set(cli_disables) disabled_for_promotion = set(remove) sources = [name for name in sources if name not in remove] @@ -1115,11 +1115,7 @@ def download_cover(url: str, destination: Path): raise ValueError("response is not a valid image") destination = Path(destination) - final_path = destination.with_suffix(IMAGE_FORMATS[format_name][1]) - final_path.write_bytes(response.content) - - if final_path != destination and destination.exists(): - destination.unlink() + destination.write_bytes(response.content) return format_name @@ -2173,31 +2169,22 @@ def download_best_cover(metadata, video, cover_path, youtube_enabled): for url, source in candidates: try: - result = download_cover(url, cover_path) - - if isinstance(result, Path): - actual_path = result - elif result in IMAGE_FORMATS: - actual_path = cover_path.with_suffix( - IMAGE_FORMATS[result][1] - ) - else: - actual_path = cover_path + download_cover(url, cover_path) - if not actual_path.exists(): - actual_path = cover_path - - image_data = actual_path.read_bytes() + # Trust the bytes on disk over the URL or the Content-Type header, + # so the saved extension always matches the actual image format. + image_data = cover_path.read_bytes() format_name = detect_image_format(image_data) if format_name is None: raise ValueError("response is not a valid image") - extension = IMAGE_FORMATS[format_name][1] - final_path = actual_path.with_suffix(extension) + final_path = cover_path.with_suffix( + IMAGE_FORMATS[format_name][1] + ) - if actual_path != final_path: - actual_path.replace(final_path) + if cover_path != final_path: + cover_path.replace(final_path) if final_path.stat().st_size > 0: print(f"{source} cover downloaded") From 9d0e7d843cf8ac0ad06a3c8e49f090aac74a3f5d Mon Sep 17 00:00:00 2001 From: ByteMe6 Date: Sun, 15 Nov 2026 21:49:23 +0200 Subject: [PATCH 8/8] test: fix lint and cover untested provider/config paths Remove dead imports and overlong/sorting issues flagged by ruff, and add tests for real error-handling and validation branches (provider malformed responses, cover-art fallbacks, Spotify auth failures, cache corruption, config path errors). No existing assertion is changed. --- tests/test_metadata_sources.py | 391 ++++++++++++++++++++++++++++++++- tests/test_spotify.py | 1 - 2 files changed, 387 insertions(+), 5 deletions(-) diff --git a/tests/test_metadata_sources.py b/tests/test_metadata_sources.py index 64e377d..10a9e62 100644 --- a/tests/test_metadata_sources.py +++ b/tests/test_metadata_sources.py @@ -4,7 +4,6 @@ import pytest import requests -from conftest import make_track import trackfetch as m @@ -1125,8 +1124,12 @@ def fake_itunes(runtime, artist, title, config): runtime = make_runtime(cache=cache, health=health) config = make_config(["deezer", "itunes"]) - assert m.resolve_metadata("Daft Punk", "One More Time", config, runtime)["source"] == "itunes" - assert m.resolve_metadata("Daft Punk", "One More Time", config, runtime)["source"] == "itunes" + first = m.resolve_metadata("Daft Punk", "One More Time", config, runtime) + second = m.resolve_metadata( + "Daft Punk", "One More Time", config, runtime + ) + assert first["source"] == "itunes" + assert second["source"] == "itunes" assert health.in_cooldown("deezer") state["deezer_ok"] = True @@ -1619,9 +1622,10 @@ def test_config_youtube_disable_prevents_network_calls( assert calls == [] def test_none_metadata_still_uses_youtube(self, monkeypatch, tmp_path): - from conftest import FIXTURES import shutil + from conftest import FIXTURES + video = {"title": "A - B", "id": "abc"} monkeypatch.setattr(m, "find_youtube_video", lambda a, t: video) monkeypatch.setattr( @@ -1652,3 +1656,382 @@ def test_none_metadata_still_uses_youtube(self, monkeypatch, tmp_path): assert (ok, reason) == (True, "downloaded") assert (tmp_path / "A - B.m4a").exists() + + +class TestMatchBranches: + def test_artist_similarity_without_candidate(self): + assert m.artist_similarity("Daft Punk", "") == 0.0 + + def test_candidate_without_title_is_rejected(self): + assert m.select_best_metadata( + [{"artist": "Daft Punk"}], "Daft Punk", "One More Time", 0.6, 0.8 + ) is None + + def test_candidate_below_overall_threshold_is_rejected(self): + candidate = {"title": "One More Time", "artist": "Someone Else"} + + assert m.select_best_metadata( + [candidate], "Daft Punk", "One More Time", 0.99, 0.5 + ) is None + + def test_non_dict_candidate_is_skipped(self): + scored = m.select_best_metadata( + ["not a dict", {"title": "One More Time", "artist": "Daft Punk"}], + "Daft Punk", + "One More Time", + 0.6, + 0.8, + ) + + assert scored["artist"] == "Daft Punk" + + +class TestSourceValidation: + def test_unknown_disable_source_is_rejected(self): + with pytest.raises(ValueError, match="Unknown source"): + m.build_source_config(make_args(disable_sources="napster"), {}) + + def test_invalid_boolean_is_rejected(self): + with pytest.raises(ValueError, match="Invalid boolean"): + m.parse_bool("maybe", "x") + + def test_provider_opt_without_key_is_rejected(self): + with pytest.raises(ValueError, match="Invalid --provider-opt"): + m.build_source_config(make_args(provider_opt=["itunes=1"]), {}) + + def test_invalid_itunes_country_in_config_is_rejected(self): + with pytest.raises(ValueError, match="two-letter"): + m.build_source_config(make_args(), {"itunes_country": "ukraine"}) + + def test_provider_opt_disable_removes_provider(self): + config = m.build_source_config( + make_args( + metadata_sources="deezer,itunes", + provider_opt=["deezer.enabled=false"], + ), + {}, + ) + + assert config.metadata_sources == ["itunes"] + assert not config.is_enabled("deezer") + + +class TestProviderErrorBranches: + def test_itunes_skips_malformed_items(self): + session = FakeSession( + FakeResponse({"results": ["nope", {"trackId": 1}]}) + ) + + candidates = m.itunes_provider( + make_runtime(session), "a", "b", make_config(["itunes"]) + ) + + assert candidates == [] + + def test_deezer_non_dict_response(self): + runtime = make_runtime(FakeSession(FakeResponse(["nope"]))) + + with pytest.raises(m.ProviderError, match="invalid response"): + m.deezer_provider(runtime, "a", "b", make_config(["deezer"])) + + def test_deezer_data_not_a_list(self): + runtime = make_runtime(FakeSession(FakeResponse({"data": {}}))) + + with pytest.raises(m.ProviderError, match="invalid response"): + m.deezer_provider(runtime, "a", "b", make_config(["deezer"])) + + def test_deezer_skips_malformed_items(self): + session = FakeSession( + FakeResponse({"data": ["nope", {"noTitle": 1}]}) + ) + + candidates = m.deezer_provider( + make_runtime(session), "a", "b", make_config(["deezer"]) + ) + + assert candidates == [] + + def test_musicbrainz_invalid_response(self): + runtime = make_runtime(FakeSession(FakeResponse({"unexpected": 1}))) + + with pytest.raises(m.ProviderError, match="invalid response"): + m.musicbrainz_provider( + runtime, "a", "b", make_config(["musicbrainz"]) + ) + + def test_musicbrainz_skips_malformed_items(self): + session = FakeSession( + FakeResponse({"recordings": ["nope", {"id": "x"}]}) + ) + + candidates = m.musicbrainz_provider( + make_runtime(session), "a", "b", make_config(["musicbrainz"]) + ) + + assert candidates == [] + + def test_musicbrainz_release_date_from_media(self): + session = FakeSession( + FakeResponse( + { + "recordings": [ + { + "id": "rec-1", + "title": "One More Time", + "artist-credit": [{"name": "Daft Punk"}], + "releases": [ + { + "id": "rel-1", + "title": "Discovery", + "media": [ + { + "tracks": [ + { + "first-release-date": "2001" + } + ] + } + ], + } + ], + } + ] + } + ), + FakeResponse(status_code=404), + ) + + candidates = m.musicbrainz_provider( + make_runtime(session), "Daft Punk", "One More Time", + make_config(["musicbrainz"]), + ) + + assert candidates[0]["release_date"] == "2001" + + def test_vocadb_invalid_response(self): + runtime = make_runtime(FakeSession(FakeResponse({"unexpected": 1}))) + + with pytest.raises(m.ProviderError, match="invalid response"): + m.vocadb_provider(runtime, "a", "b", make_config(["vocadb"])) + + def test_vocadb_skips_malformed_items(self): + session = FakeSession( + FakeResponse({"items": ["nope", {"id": 1}]}) + ) + + candidates = m.vocadb_provider( + make_runtime(session), "a", "b", make_config(["vocadb"]) + ) + + assert candidates == [] + + def test_vocadb_artist_from_artist_credits(self): + session = FakeSession( + FakeResponse( + { + "items": [ + { + "id": 1, + "name": "Song", + "artists": [{"name": "A"}, {"name": "B"}], + } + ] + } + ) + ) + + candidates = m.vocadb_provider( + make_runtime(session), "a", "b", make_config(["vocadb"]) + ) + + assert candidates[0]["artist"] == "A, B" + + +class TestCoverArtArchiveBranches: + def test_missing_release_id_returns_none(self): + assert m.cover_art_archive_url( + make_runtime(), None, make_config(["musicbrainz"]) + ) is None + + def test_auth_error_is_cached_as_none(self): + runtime = make_runtime(FakeSession(FakeResponse(status_code=401))) + + assert m.cover_art_archive_url( + runtime, "rel-1", make_config(["musicbrainz"]) + ) is None + assert runtime.cover_art_cache["rel-1"] is None + + def test_missing_cover_is_cached_as_none(self): + runtime = make_runtime(FakeSession(FakeResponse(status_code=404))) + + assert m.cover_art_archive_url( + runtime, "rel-2", make_config(["musicbrainz"]) + ) is None + assert runtime.cover_art_cache["rel-2"] is None + + def test_images_not_a_list_returns_none(self): + runtime = make_runtime(FakeSession(FakeResponse({"images": "x"}))) + + assert m.cover_art_archive_url( + runtime, "rel-3", make_config(["musicbrainz"]) + ) is None + + def test_skips_images_without_url_and_picks_largest(self): + session = FakeSession( + FakeResponse( + { + "images": [ + {"front": True}, + {"front": True, "image": "small", "width": 10, "height": 10}, + {"front": True, "image": "big", "width": 100, "height": 100}, + ] + } + ) + ) + runtime = make_runtime(session) + + assert m.cover_art_archive_url( + runtime, "rel-4", make_config(["musicbrainz"]) + ) == "big" + + +class TestVocadbUrlHelpers: + def test_absolute_vocadb_url_variants(self): + assert m.absolute_vocadb_url(None) is None + assert m.absolute_vocadb_url("//x/y") == "https://x/y" + assert ( + m.absolute_vocadb_url("/img/a.jpg") + == "https://vocadb.net/img/a.jpg" + ) + assert m.absolute_vocadb_url("https://x/y") == "https://x/y" + + def test_picture_url_from_cover_key(self): + assert ( + m.vocadb_picture_url({"coverUrl": "/img/c.jpg"}) + == "https://vocadb.net/img/c.jpg" + ) + + def test_picture_url_none_when_absent(self): + assert m.vocadb_picture_url("x", "y") is None + + +class TestSpotifyBranches: + def test_auth_error_detected_from_message(self): + assert m.is_spotify_auth_error(Exception("HTTP 403 Forbidden")) + assert not m.is_spotify_auth_error(Exception("boom")) + + def test_init_auth_error(self, monkeypatch): + def boom(args): + raise RuntimeError("401 unauthorized") + + monkeypatch.setattr(m, "get_spotify", boom) + + with pytest.raises(m.ProviderAuthError): + m.spotify_provider( + make_runtime(), "a", "b", make_config(["spotify"]) + ) + + def test_init_error(self, monkeypatch): + def boom(args): + raise RuntimeError("boom") + + monkeypatch.setattr(m, "get_spotify", boom) + + with pytest.raises(m.ProviderError, match="authentication error"): + m.spotify_provider( + make_runtime(), "a", "b", make_config(["spotify"]) + ) + + def test_search_auth_error(self, monkeypatch): + def boom(*args, **kwargs): + raise RuntimeError("403") + + monkeypatch.setattr(m, "find_spotify_track", boom) + runtime = make_runtime() + runtime.spotify_client = object() + runtime.spotify_initialized = True + + with pytest.raises(m.ProviderAuthError): + m.spotify_provider(runtime, "a", "b", make_config(["spotify"])) + + def test_search_error(self, monkeypatch): + def boom(*args, **kwargs): + raise RuntimeError("boom") + + monkeypatch.setattr(m, "find_spotify_track", boom) + runtime = make_runtime() + runtime.spotify_client = object() + runtime.spotify_initialized = True + + with pytest.raises(m.ProviderError, match="search error"): + m.spotify_provider(runtime, "a", "b", make_config(["spotify"])) + + def test_no_track_returns_empty(self, monkeypatch): + monkeypatch.setattr(m, "find_spotify_track", lambda *a, **k: None) + runtime = make_runtime() + runtime.spotify_client = object() + runtime.spotify_initialized = True + + assert m.spotify_provider( + runtime, "a", "b", make_config(["spotify"]) + ) == [] + + +class TestCacheBranches: + def test_non_dict_json_is_handled(self, tmp_path): + path = tmp_path / m.CACHE_FILENAME + path.write_text("[]", encoding="utf-8") + + assert m.MetadataCache(path).entries == {} + + def test_save_oserror_is_ignored(self, monkeypatch, tmp_path): + cache = m.MetadataCache(tmp_path / m.CACHE_FILENAME) + + def boom(self, *args, **kwargs): + raise OSError("nope") + + monkeypatch.setattr(m.Path, "write_text", boom) + + assert cache.set("A", "B", "itunes", {"title": "B"}) is True + + def test_unparsable_score_does_not_block_update(self, tmp_path): + cache = m.MetadataCache(tmp_path / m.CACHE_FILENAME) + cache.set("A", "B", "itunes", {"title": "B", "score": "n/a"}) + + assert cache.set( + "A", "B", "itunes", {"title": "B", "score": 0.5} + ) is True + assert cache.get("A", "B", "itunes")["score"] == 0.5 + + +class TestProcessSongDefaults: + def test_builds_default_config_when_only_runtime_is_given( + self, monkeypatch, tmp_path + ): + monkeypatch.setattr( + m, + "resolve_metadata", + lambda artist, title, config, runtime: m.fallback_metadata( + artist, title + ), + ) + monkeypatch.setattr(m, "find_youtube_video", lambda a, t: None) + + ok, reason = m.process_song( + None, + "A", + "B", + tmp_path, + False, + "m4a", + source_config=None, + runtime=make_runtime(), + ) + + assert (ok, reason) == (False, "no YouTube result") + + +class TestConfigPathErrors: + def test_config_path_that_is_a_directory_raises(self, tmp_path): + with pytest.raises(FileNotFoundError, match="not a file"): + m.load_config(tmp_path) diff --git a/tests/test_spotify.py b/tests/test_spotify.py index 754b030..a1207dd 100644 --- a/tests/test_spotify.py +++ b/tests/test_spotify.py @@ -1,4 +1,3 @@ -import pytest from conftest import FakeSpotify, make_track import trackfetch as m