trackfetch 2.1.0__tar.gz → 2.2.0__tar.gz

{trackfetch-2.1.0 → trackfetch-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trackfetch
-Version: 2.1.0
+Version: 2.2.0
 Summary: Turn a text file of songs into tagged MP3s: Spotify metadata and cover art, best-match YouTube audio via yt-dlp.
 Author: ByteMe6
 License-Expression: GPL-3.0-or-later
@@ -195,7 +195,7 @@ EOF
 trackfetch songs.txt
 ```
 
-The files land in `~/Music/trackfetch/`.
+The files land in the current directory.
 
 ## Playlists from streaming services
 
@@ -213,16 +213,19 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist"
 ## Usage
 
 ```text
-trackfetch [-h] [-o OUTPUT] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] input
+trackfetch [-h] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [--spotify-client-id ID] [--spotify-client-secret SECRET] [input]
 ```
 
 | Option | Default | What it does |
 | --- | --- | --- |
-| `input` | required | Text file with one `Artist - Title` per line |
-| `-o`, `--output` | `~/Music/trackfetch` | Folder to save the files in. It's created if it doesn't exist. |
-| `-f`, `--format` | `mp3` | Audio format: `mp3`, `m4a` or `opus`. See [Audio formats](#audio-formats). |
-| `--title-only` | off | Name files `Title.mp3` instead of `Artist - Title.mp3` |
+| `input` | required | Text file with one `Artist - Title` per line. Can also be set in the [config file](#configuration-file). |
+| `-o`, `--output` | current directory | Folder to save the files in. It's created if it doesn't exist. |
+| `--config` | auto-detected | Path to a [config file](#configuration-file). |
+| `-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. |
+| `--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. |
 
 ```bash
 trackfetch songs.txt -o ~/Music/RoadTrip          # save to a specific folder
@@ -231,13 +234,66 @@ trackfetch big-list.txt --delay 3                 # go easy on rate limits
 trackfetch songs.txt --format opus                # original YouTube audio, no re-encode
 ```
 
+### Configuration file
+
+Put your defaults in an INI file and forget the flags:
+
+```ini
+[trackfetch]
+output = ~/Music/trackfetch
+format = m4a
+title_only = false
+delay = 1.0
+input = ~/songs.txt
+spotify_client_id = your-client-id
+spotify_client_secret = your-client-secret
+```
+
+Every option above can be set there, under the `[trackfetch]` section. The
+precedence is always the same:
+
+1. the command-line flag,
+2. the config file,
+3. the built-in default (the current directory for the output folder).
+
+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` (usually
+`~/.config/trackfetch/trackfetch.ini`) and `~/.trackfetch.ini`.
+
+### Spotify credentials
+
+trackfetch needs a Spotify client ID and secret to read the metadata. Give
+them in whichever way suits you:
+
+```bash
+# in the config file
+[trackfetch]
+spotify_client_id = your-client-id
+spotify_client_secret = your-client-secret
+```
+
+```bash
+# in the environment
+export SPOTIFY_CLIENT_ID='your-client-id'
+export SPOTIFY_CLIENT_SECRET='your-client-secret'
+```
+
+```bash
+# on the command line
+trackfetch songs.txt --spotify-client-id your-id --spotify-client-secret your-secret
+```
+
+The flag wins over the config file, and the config file wins over the
+environment variable.
+
 ### Audio formats
 
 | Format | What you get | Plays on |
 | --- | --- | --- |
-| `mp3` (default) | YouTube's audio **re-encoded** to the best VBR MP3. A second lossy encode, so slightly below the source | everything, including old players and car stereos |
+| `m4a` (default) | YouTube's **original** AAC audio when available, copied without re-encoding | Apple devices, iTunes, most players |
 | `opus` | YouTube's **original** Opus audio, copied without re-encoding. The best quality you can get | most modern players, Android, browsers; not iTunes or older devices |
-| `m4a` | YouTube's **original** AAC audio when available, copied without re-encoding | Apple devices, iTunes, most players |
+| `mp3` | YouTube's audio **re-encoded** to the best VBR MP3. A second lossy encode, so slightly below the source | everything, including old players and car stereos |
 
 All three get the same tags and embedded cover art. `done.txt` doesn't track the format, so use a separate `-o` folder for each format.
 
@@ -254,9 +310,9 @@ The separator is space, hyphen, space (` - `). Lines without it are skipped. See
 ### Output folder
 
 ```text
-~/Music/trackfetch/
-├── Daft Punk - One More Time.mp3
-├── Radiohead - Paranoid Android.mp3
+./
+├── Daft Punk - One More Time.m4a
+├── Radiohead - Paranoid Android.m4a
 ├── done.txt      ← finished songs, skipped on the next run
 └── failed.txt    ← "Artist - Title | reason" for each song that failed
 ```
@@ -264,7 +320,7 @@ The separator is space, hyphen, space (` - `). Lines without it are skipped. See
 **Retry failures** by stripping the reasons from `failed.txt` and running it again:
 
 ```bash
-cut -d '|' -f 1 ~/Music/trackfetch/failed.txt > retry.txt
+cut -d '|' -f 1 ./failed.txt > retry.txt
 trackfetch retry.txt
 ```
 

{trackfetch-2.1.0 → trackfetch-2.2.0}/README.md

@@ -164,7 +164,7 @@ EOF
 trackfetch songs.txt
 ```
 
-The files land in `~/Music/trackfetch/`.
+The files land in the current directory.
 
 ## Playlists from streaming services
 
@@ -182,16 +182,19 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist"
 ## Usage
 
 ```text
-trackfetch [-h] [-o OUTPUT] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] input
+trackfetch [-h] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [--spotify-client-id ID] [--spotify-client-secret SECRET] [input]
 ```
 
 | Option | Default | What it does |
 | --- | --- | --- |
-| `input` | required | Text file with one `Artist - Title` per line |
-| `-o`, `--output` | `~/Music/trackfetch` | Folder to save the files in. It's created if it doesn't exist. |
-| `-f`, `--format` | `mp3` | Audio format: `mp3`, `m4a` or `opus`. See [Audio formats](#audio-formats). |
-| `--title-only` | off | Name files `Title.mp3` instead of `Artist - Title.mp3` |
+| `input` | required | Text file with one `Artist - Title` per line. Can also be set in the [config file](#configuration-file). |
+| `-o`, `--output` | current directory | Folder to save the files in. It's created if it doesn't exist. |
+| `--config` | auto-detected | Path to a [config file](#configuration-file). |
+| `-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. |
+| `--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. |
 
 ```bash
 trackfetch songs.txt -o ~/Music/RoadTrip          # save to a specific folder
@@ -200,13 +203,66 @@ trackfetch big-list.txt --delay 3                 # go easy on rate limits
 trackfetch songs.txt --format opus                # original YouTube audio, no re-encode
 ```
 
+### Configuration file
+
+Put your defaults in an INI file and forget the flags:
+
+```ini
+[trackfetch]
+output = ~/Music/trackfetch
+format = m4a
+title_only = false
+delay = 1.0
+input = ~/songs.txt
+spotify_client_id = your-client-id
+spotify_client_secret = your-client-secret
+```
+
+Every option above can be set there, under the `[trackfetch]` section. The
+precedence is always the same:
+
+1. the command-line flag,
+2. the config file,
+3. the built-in default (the current directory for the output folder).
+
+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` (usually
+`~/.config/trackfetch/trackfetch.ini`) and `~/.trackfetch.ini`.
+
+### Spotify credentials
+
+trackfetch needs a Spotify client ID and secret to read the metadata. Give
+them in whichever way suits you:
+
+```bash
+# in the config file
+[trackfetch]
+spotify_client_id = your-client-id
+spotify_client_secret = your-client-secret
+```
+
+```bash
+# in the environment
+export SPOTIFY_CLIENT_ID='your-client-id'
+export SPOTIFY_CLIENT_SECRET='your-client-secret'
+```
+
+```bash
+# on the command line
+trackfetch songs.txt --spotify-client-id your-id --spotify-client-secret your-secret
+```
+
+The flag wins over the config file, and the config file wins over the
+environment variable.
+
 ### Audio formats
 
 | Format | What you get | Plays on |
 | --- | --- | --- |
-| `mp3` (default) | YouTube's audio **re-encoded** to the best VBR MP3. A second lossy encode, so slightly below the source | everything, including old players and car stereos |
+| `m4a` (default) | YouTube's **original** AAC audio when available, copied without re-encoding | Apple devices, iTunes, most players |
 | `opus` | YouTube's **original** Opus audio, copied without re-encoding. The best quality you can get | most modern players, Android, browsers; not iTunes or older devices |
-| `m4a` | YouTube's **original** AAC audio when available, copied without re-encoding | Apple devices, iTunes, most players |
+| `mp3` | YouTube's audio **re-encoded** to the best VBR MP3. A second lossy encode, so slightly below the source | everything, including old players and car stereos |
 
 All three get the same tags and embedded cover art. `done.txt` doesn't track the format, so use a separate `-o` folder for each format.
 
@@ -223,9 +279,9 @@ The separator is space, hyphen, space (` - `). Lines without it are skipped. See
 ### Output folder
 
 ```text
-~/Music/trackfetch/
-├── Daft Punk - One More Time.mp3
-├── Radiohead - Paranoid Android.mp3
+./
+├── Daft Punk - One More Time.m4a
+├── Radiohead - Paranoid Android.m4a
 ├── done.txt      ← finished songs, skipped on the next run
 └── failed.txt    ← "Artist - Title | reason" for each song that failed
 ```
@@ -233,7 +289,7 @@ The separator is space, hyphen, space (` - `). Lines without it are skipped. See
 **Retry failures** by stripping the reasons from `failed.txt` and running it again:
 
 ```bash
-cut -d '|' -f 1 ~/Music/trackfetch/failed.txt > retry.txt
+cut -d '|' -f 1 ./failed.txt > retry.txt
 trackfetch retry.txt
 ```
 

{trackfetch-2.1.0 → trackfetch-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trackfetch"
-version = "2.1.0"
+version = "2.2.0"
 description = "Turn a text file of songs into tagged MP3s: Spotify metadata and cover art, best-match YouTube audio via yt-dlp."
 readme = "README.md"
 license = "GPL-3.0-or-later"

trackfetch-2.2.0/tests/test_config.py

@@ -0,0 +1,346 @@
+import argparse
+import configparser
+import shutil
+import sys
+from pathlib import Path
+
+import pytest
+from conftest import FIXTURES, make_track
+
+import trackfetch as m
+
+
+@pytest.fixture
+def pipeline(monkeypatch):
+    state = {
+        "track": make_track("One More Time", ["Daft Punk"], album="Discovery", track_number=1),
+        "video": {"title": "Daft Punk - One More Time (Official Audio)", "id": "abc"},
+        "formats": [],
+    }
+
+    def fake_download_audio(url, temp_dir, audio_format="mp3"):
+        state["formats"].append(audio_format)
+        path = temp_dir / f"audio.{audio_format}"
+        if audio_format == "mp3":
+            path.write_bytes(b"\x00" * 64)
+        else:
+            shutil.copy(FIXTURES / f"silence.{audio_format}", path)
+        return path
+
+    def fake_download_cover(url, dest):
+        dest.write_bytes(b"\xff\xd8\xff\xe0jpeg")
+
+    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)
+    monkeypatch.setattr(m, "download_cover", fake_download_cover)
+    monkeypatch.setattr(m, "get_spotify", lambda *a, **k: object())
+    monkeypatch.setattr(m.time, "sleep", lambda s: None)
+    return state
+
+
+def run_cli(monkeypatch, *args):
+    monkeypatch.setattr(sys, "argv", ["trackfetch", *map(str, args)])
+    m.main()
+
+
+def write_config(path: Path, body: str) -> Path:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(body, encoding="utf-8")
+    return path
+
+
+class TestConfigLookup:
+    def test_no_config_file_returns_empty_settings(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "empty"))
+        monkeypatch.delenv("TRACKFETCH_CONFIG", raising=False)
+        monkeypatch.setattr(m.Path, "home", classmethod(lambda cls: tmp_path / "home"))
+
+        settings, path = m.load_config()
+
+        assert settings == {}
+        assert path is None
+
+    def test_explicit_config_file_is_used(self, tmp_path):
+        config = write_config(tmp_path / "custom.ini", "[trackfetch]\noutput = /tmp/x\n")
+
+        settings, path = m.load_config(config)
+
+        assert settings["output"] == "/tmp/x"
+        assert path == config
+
+    def test_missing_explicit_config_file_raises(self, tmp_path):
+        with pytest.raises(FileNotFoundError):
+            m.load_config(tmp_path / "nope.ini")
+
+    def test_config_in_current_directory(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
+        monkeypatch.delenv("TRACKFETCH_CONFIG", raising=False)
+        monkeypatch.setattr(m.Path, "home", classmethod(lambda cls: tmp_path / "home"))
+        write_config(tmp_path / m.CONFIG_FILENAME, "[trackfetch]\noutput = /tmp/from-cwd\n")
+
+        settings, path = m.load_config()
+
+        assert settings["output"] == "/tmp/from-cwd"
+        assert path == tmp_path / m.CONFIG_FILENAME
+
+    def test_config_in_xdg_directory(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+        monkeypatch.delenv("TRACKFETCH_CONFIG", raising=False)
+        monkeypatch.setattr(m.Path, "home", classmethod(lambda cls: tmp_path / "home"))
+        xdg = tmp_path / "xdg"
+        write_config(xdg / "trackfetch" / m.CONFIG_FILENAME, "[trackfetch]\noutput = /tmp/xdg\n")
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(xdg))
+
+        settings, path = m.load_config()
+
+        assert settings["output"] == "/tmp/xdg"
+
+    def test_env_var_points_to_config(self, tmp_path, monkeypatch):
+        config = write_config(tmp_path / "env.ini", "[trackfetch]\noutput = /tmp/env\n")
+        monkeypatch.setenv("TRACKFETCH_CONFIG", str(config))
+
+        settings, path = m.load_config()
+
+        assert settings["output"] == "/tmp/env"
+
+    def test_invalid_config_file_raises(self, tmp_path):
+        config = write_config(tmp_path / "bad.ini", "not an ini file at all\n")
+
+        with pytest.raises(configparser.Error):
+            m.load_config(config)
+
+
+class TestResolveOutput:
+    def test_flag_wins_over_config(self, tmp_path):
+        settings = {"output": str(tmp_path / "from-config")}
+
+        result = m.resolve_output(tmp_path / "from-flag", settings)
+
+        assert result == tmp_path / "from-flag"
+
+    def test_config_used_when_no_flag(self, tmp_path):
+        settings = {"output": str(tmp_path / "from-config")}
+
+        result = m.resolve_output(None, settings)
+
+        assert result == tmp_path / "from-config"
+
+    def test_current_directory_is_the_last_resort(self, tmp_path, monkeypatch):
+        monkeypatch.chdir(tmp_path)
+
+        assert m.resolve_output(None, {}) == tmp_path
+        assert m.resolve_output(None, {"output": "  "}) == tmp_path
+
+    def test_tilde_is_expanded(self):
+        result = m.resolve_output(None, {"output": "~/Music/x"})
+
+        assert result == Path.home() / "Music" / "x"
+
+
+class TestSpotifyCredentials:
+    def test_env_is_used_when_config_is_silent(self, monkeypatch):
+        monkeypatch.setenv("SPOTIFY_CLIENT_ID", "env-id")
+        monkeypatch.setenv("SPOTIFY_CLIENT_SECRET", "env-secret")
+
+        client_id, client_secret = m.spotify_credentials()
+
+        assert (client_id, client_secret) == ("env-id", "env-secret")
+
+    def test_config_wins_over_env(self, monkeypatch):
+        monkeypatch.setenv("SPOTIFY_CLIENT_ID", "env-id")
+        monkeypatch.setenv("SPOTIFY_CLIENT_SECRET", "env-secret")
+        settings = {
+            "spotify_client_id": "config-id",
+            "spotify_client_secret": "config-secret",
+        }
+
+        parser = argparse.ArgumentParser()
+        parser.add_argument("--spotify-client-id", default=None)
+        parser.add_argument("--spotify-client-secret", default=None)
+        args = parser.parse_args([])
+        m.apply_config(args, parser, settings)
+        client_id, client_secret = m.spotify_credentials(args)
+
+        assert (client_id, client_secret) == ("config-id", "config-secret")
+
+    def test_flag_wins_over_config_and_env(self, monkeypatch):
+        monkeypatch.setenv("SPOTIFY_CLIENT_ID", "env-id")
+        monkeypatch.setenv("SPOTIFY_CLIENT_SECRET", "env-secret")
+        parser = argparse.ArgumentParser()
+        parser.add_argument("--spotify-client-id", default=None)
+        parser.add_argument("--spotify-client-secret", default=None)
+        args = parser.parse_args(
+            ["--spotify-client-id", "flag-id", "--spotify-client-secret", "flag-secret"]
+        )
+        settings = {
+            "spotify_client_id": "config-id",
+            "spotify_client_secret": "config-secret",
+        }
+
+        m.apply_config(args, parser, settings)
+
+        client_id, client_secret = m.spotify_credentials(args)
+
+        assert (client_id, client_secret) == ("flag-id", "flag-secret")
+
+    def test_missing_credentials_exit(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
+
+
+class TestMainWithConfig:
+    def test_config_output_is_used(self, pipeline, monkeypatch, tmp_path):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("Daft Punk - One More Time\n", encoding="utf-8")
+        out = tmp_path / "from-config"
+        config = write_config(tmp_path / "cfg.ini", f"[trackfetch]\noutput = {out}\n")
+
+        run_cli(monkeypatch, songs, "--config", config)
+
+        assert (out / "Daft Punk - One More Time.m4a").exists()
+
+    def test_flag_overrides_config(self, pipeline, monkeypatch, tmp_path):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("Daft Punk - One More Time\n", encoding="utf-8")
+        config_out = tmp_path / "from-config"
+        flag_out = tmp_path / "from-flag"
+        config = write_config(tmp_path / "cfg.ini", f"[trackfetch]\noutput = {config_out}\n")
+
+        run_cli(monkeypatch, songs, "--config", config, "-o", flag_out)
+
+        assert (flag_out / "Daft Punk - One More Time.m4a").exists()
+        assert not config_out.exists()
+
+    def test_current_directory_is_used_without_config(self, pipeline, monkeypatch, tmp_path):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("Daft Punk - One More Time\n", encoding="utf-8")
+        workdir = tmp_path / "work"
+        workdir.mkdir()
+        monkeypatch.chdir(workdir)
+        monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / "xdg"))
+        monkeypatch.delenv("TRACKFETCH_CONFIG", raising=False)
+        monkeypatch.setattr(m.Path, "home", classmethod(lambda cls: tmp_path / "home"))
+
+        run_cli(monkeypatch, songs)
+
+        assert (workdir / "Daft Punk - One More Time.m4a").exists()
+
+    def test_invalid_config_file_exits(self, monkeypatch, tmp_path, capsys):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("A - B\n", encoding="utf-8")
+        config = write_config(tmp_path / "bad.ini", "not an ini file at all\n")
+
+        with pytest.raises(SystemExit) as exc:
+            run_cli(monkeypatch, songs, "--config", config)
+
+        assert exc.value.code == 1
+        assert "Invalid config file" in capsys.readouterr().out
+
+    def test_invalid_value_in_config_exits(self, monkeypatch, tmp_path, capsys):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("A - B\n", encoding="utf-8")
+        config = write_config(tmp_path / "cfg.ini", "[trackfetch]\ndelay = abc\n")
+
+        with pytest.raises(SystemExit) as exc:
+            run_cli(monkeypatch, songs, "--config", config)
+
+        assert exc.value.code == 1
+        assert "Invalid value for 'delay' in config file" in capsys.readouterr().out
+
+    def test_missing_input_file_exits(self, monkeypatch, tmp_path, capsys):
+        with pytest.raises(SystemExit) as exc:
+            run_cli(monkeypatch)
+
+        assert exc.value.code == 1
+        assert "No input file" in capsys.readouterr().out
+
+    def test_input_can_come_from_the_config(self, pipeline, monkeypatch, tmp_path):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("Daft Punk - One More Time\n", encoding="utf-8")
+        out = tmp_path / "o"
+        config = write_config(
+            tmp_path / "cfg.ini", f"[trackfetch]\ninput = {songs}\noutput = {out}\n"
+        )
+
+        run_cli(monkeypatch, "--config", config)
+
+        assert (out / "Daft Punk - One More Time.m4a").exists()
+
+    def test_missing_explicit_config_exits(self, monkeypatch, tmp_path, capsys):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("A - B\n", encoding="utf-8")
+
+        with pytest.raises(SystemExit) as exc:
+            run_cli(monkeypatch, songs, "--config", tmp_path / "nope.ini")
+
+        assert exc.value.code == 1
+        assert "Config file not found" in capsys.readouterr().out
+
+    def test_format_from_config(self, pipeline, monkeypatch, tmp_path):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("Daft Punk - One More Time\n", encoding="utf-8")
+        out = tmp_path / "o"
+        config = write_config(
+            tmp_path / "cfg.ini", f"[trackfetch]\noutput = {out}\nformat = opus\n"
+        )
+
+        run_cli(monkeypatch, songs, "--config", config)
+
+        assert (out / "Daft Punk - One More Time.opus").exists()
+        assert pipeline["formats"] == ["opus"]
+
+    def test_unknown_format_in_config_exits(self, monkeypatch, tmp_path, capsys):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("A - B\n", encoding="utf-8")
+        config = write_config(tmp_path / "cfg.ini", "[trackfetch]\nformat = flac\n")
+
+        with pytest.raises(SystemExit) as exc:
+            run_cli(monkeypatch, songs, "--config", config)
+
+        assert exc.value.code == 1
+        assert "Unknown value for 'format' in config file" in capsys.readouterr().out
+
+    def test_title_only_from_config(self, pipeline, monkeypatch, tmp_path):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("Daft Punk - One More Time\n", encoding="utf-8")
+        out = tmp_path / "o"
+        config = write_config(
+            tmp_path / "cfg.ini", f"[trackfetch]\noutput = {out}\ntitle_only = true\n"
+        )
+
+        run_cli(monkeypatch, songs, "--config", config)
+
+        assert (out / "One More Time.m4a").exists()
+
+    def test_delay_from_config(self, pipeline, monkeypatch, tmp_path):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("A - 1\nA - 2\n", encoding="utf-8")
+        out = tmp_path / "o"
+        config = write_config(tmp_path / "cfg.ini", f"[trackfetch]\noutput = {out}\ndelay = 2.5\n")
+        sleeps = []
+        monkeypatch.setattr(m.time, "sleep", sleeps.append)
+
+        run_cli(monkeypatch, songs, "--config", config)
+
+        assert sleeps == [2.5]
+
+    def test_config_path_is_reported(self, pipeline, monkeypatch, tmp_path, capsys):
+        songs = tmp_path / "songs.txt"
+        songs.write_text("Daft Punk - One More Time\n", encoding="utf-8")
+        out = tmp_path / "o"
+        config = write_config(tmp_path / "cfg.ini", f"[trackfetch]\noutput = {out}\n")
+
+        run_cli(monkeypatch, songs, "--config", config)
+        log = capsys.readouterr().out
+
+        assert f"Config: {config}" in log
+        assert f"Output: {out}" in log

{trackfetch-2.1.0 → trackfetch-2.2.0}/tests/test_pipeline.py

@@ -48,7 +48,7 @@ def pipeline(monkeypatch):
     monkeypatch.setattr(m, "find_youtube_video", lambda artist, title: state["video"])
     monkeypatch.setattr(m, "download_audio", fake_download_audio)
     monkeypatch.setattr(m, "download_cover", fake_download_cover)
-    monkeypatch.setattr(m, "get_spotify", lambda: object())
+    monkeypatch.setattr(m, "get_spotify", lambda *a, **k: object())
     monkeypatch.setattr(m.time, "sleep", lambda s: None)
     return state
 
@@ -173,7 +173,7 @@ class TestMain:
         assert "Found 2 songs" in log
         assert "SUCCESS: 1" in log
         assert "FAILED: 1" in log
-        assert (out / "Daft Punk - One More Time.mp3").exists()
+        assert (out / "Daft Punk - One More Time.m4a").exists()
         assert (out / "done.txt").read_text(encoding="utf-8") == "Daft Punk - One More Time\n"
         assert (out / "failed.txt").read_text(
             encoding="utf-8"
@@ -204,7 +204,7 @@ class TestMain:
         songs.write_text("Daft Punk - One More Time\n", encoding="utf-8")
         out = tmp_path / "o"
         out.mkdir()
-        (out / "Daft Punk - One More Time.mp3").write_bytes(b"")
+        (out / "Daft Punk - One More Time.m4a").write_bytes(b"")
 
         run_cli(monkeypatch, songs, "-o", out)
         log = capsys.readouterr().out
@@ -220,12 +220,12 @@ class TestMain:
         assert (out / "Daft Punk - One More Time.opus").exists()
         assert pipeline["formats"] == ["opus"]
 
-    def test_default_format_is_mp3(self, pipeline, monkeypatch, tmp_path):
+    def test_default_format_is_m4a(self, pipeline, monkeypatch, tmp_path):
         songs = tmp_path / "songs.txt"
         songs.write_text("Daft Punk - One More Time\n", encoding="utf-8")
 
         run_cli(monkeypatch, songs, "-o", tmp_path / "o")
-        assert pipeline["formats"] == ["mp3"]
+        assert pipeline["formats"] == ["m4a"]
 
     def test_rejects_unknown_format(self, monkeypatch, tmp_path, capsys):
         songs = tmp_path / "songs.txt"

{trackfetch-2.1.0 → trackfetch-2.2.0}/trackfetch.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trackfetch
-Version: 2.1.0
+Version: 2.2.0
 Summary: Turn a text file of songs into tagged MP3s: Spotify metadata and cover art, best-match YouTube audio via yt-dlp.
 Author: ByteMe6
 License-Expression: GPL-3.0-or-later
@@ -195,7 +195,7 @@ EOF
 trackfetch songs.txt
 ```
 
-The files land in `~/Music/trackfetch/`.
+The files land in the current directory.
 
 ## Playlists from streaming services
 
@@ -213,16 +213,19 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist"
 ## Usage
 
 ```text
-trackfetch [-h] [-o OUTPUT] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] input
+trackfetch [-h] [-o OUTPUT] [--config CONFIG] [-f {mp3,m4a,opus}] [--title-only] [--delay DELAY] [--spotify-client-id ID] [--spotify-client-secret SECRET] [input]
 ```
 
 | Option | Default | What it does |
 | --- | --- | --- |
-| `input` | required | Text file with one `Artist - Title` per line |
-| `-o`, `--output` | `~/Music/trackfetch` | Folder to save the files in. It's created if it doesn't exist. |
-| `-f`, `--format` | `mp3` | Audio format: `mp3`, `m4a` or `opus`. See [Audio formats](#audio-formats). |
-| `--title-only` | off | Name files `Title.mp3` instead of `Artist - Title.mp3` |
+| `input` | required | Text file with one `Artist - Title` per line. Can also be set in the [config file](#configuration-file). |
+| `-o`, `--output` | current directory | Folder to save the files in. It's created if it doesn't exist. |
+| `--config` | auto-detected | Path to a [config file](#configuration-file). |
+| `-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. |
+| `--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. |
 
 ```bash
 trackfetch songs.txt -o ~/Music/RoadTrip          # save to a specific folder
@@ -231,13 +234,66 @@ trackfetch big-list.txt --delay 3                 # go easy on rate limits
 trackfetch songs.txt --format opus                # original YouTube audio, no re-encode
 ```
 
+### Configuration file
+
+Put your defaults in an INI file and forget the flags:
+
+```ini
+[trackfetch]
+output = ~/Music/trackfetch
+format = m4a
+title_only = false
+delay = 1.0
+input = ~/songs.txt
+spotify_client_id = your-client-id
+spotify_client_secret = your-client-secret
+```
+
+Every option above can be set there, under the `[trackfetch]` section. The
+precedence is always the same:
+
+1. the command-line flag,
+2. the config file,
+3. the built-in default (the current directory for the output folder).
+
+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` (usually
+`~/.config/trackfetch/trackfetch.ini`) and `~/.trackfetch.ini`.
+
+### Spotify credentials
+
+trackfetch needs a Spotify client ID and secret to read the metadata. Give
+them in whichever way suits you:
+
+```bash
+# in the config file
+[trackfetch]
+spotify_client_id = your-client-id
+spotify_client_secret = your-client-secret
+```
+
+```bash
+# in the environment
+export SPOTIFY_CLIENT_ID='your-client-id'
+export SPOTIFY_CLIENT_SECRET='your-client-secret'
+```
+
+```bash
+# on the command line
+trackfetch songs.txt --spotify-client-id your-id --spotify-client-secret your-secret
+```
+
+The flag wins over the config file, and the config file wins over the
+environment variable.
+
 ### Audio formats
 
 | Format | What you get | Plays on |
 | --- | --- | --- |
-| `mp3` (default) | YouTube's audio **re-encoded** to the best VBR MP3. A second lossy encode, so slightly below the source | everything, including old players and car stereos |
+| `m4a` (default) | YouTube's **original** AAC audio when available, copied without re-encoding | Apple devices, iTunes, most players |
 | `opus` | YouTube's **original** Opus audio, copied without re-encoding. The best quality you can get | most modern players, Android, browsers; not iTunes or older devices |
-| `m4a` | YouTube's **original** AAC audio when available, copied without re-encoding | Apple devices, iTunes, most players |
+| `mp3` | YouTube's audio **re-encoded** to the best VBR MP3. A second lossy encode, so slightly below the source | everything, including old players and car stereos |
 
 All three get the same tags and embedded cover art. `done.txt` doesn't track the format, so use a separate `-o` folder for each format.
 
@@ -254,9 +310,9 @@ The separator is space, hyphen, space (` - `). Lines without it are skipped. See
 ### Output folder
 
 ```text
-~/Music/trackfetch/
-├── Daft Punk - One More Time.mp3
-├── Radiohead - Paranoid Android.mp3
+./
+├── Daft Punk - One More Time.m4a
+├── Radiohead - Paranoid Android.m4a
 ├── done.txt      ← finished songs, skipped on the next run
 └── failed.txt    ← "Artist - Title | reason" for each song that failed
 ```
@@ -264,7 +320,7 @@ The separator is space, hyphen, space (` - `). Lines without it are skipped. See
 **Retry failures** by stripping the reasons from `failed.txt` and running it again:
 
 ```bash
-cut -d '|' -f 1 ~/Music/trackfetch/failed.txt > retry.txt
+cut -d '|' -f 1 ./failed.txt > retry.txt
 trackfetch retry.txt
 ```
 

{trackfetch-2.1.0 → trackfetch-2.2.0}/trackfetch.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 trackfetch.py
+tests/test_config.py
 tests/test_pipeline.py
 tests/test_spotify.py
 tests/test_tags_and_files.py

{trackfetch-2.1.0 → trackfetch-2.2.0}/trackfetch.py

@@ -3,6 +3,7 @@
 
 import argparse
 import base64
+import configparser
 import json
 import os
 import re
@@ -34,6 +35,13 @@ from spotipy.oauth2 import SpotifyClientCredentials
 
 YTDLP_REMOTE_COMPONENTS = "ejs:github"
 
+CONFIG_SECTION = "trackfetch"
+CONFIG_FILENAME = "trackfetch.ini"
+CONFIG_ENV = "TRACKFETCH_CONFIG"
+
+DEFAULT_FORMAT = "m4a"
+DEFAULT_DELAY = 1.0
+
 AUDIO_FORMATS = {
     "mp3": [],
     "m4a": [
@@ -84,13 +92,31 @@ def parse_song(line: str):
     return artist, title
 
 
-def get_spotify():
-    client_id = os.getenv("SPOTIFY_CLIENT_ID")
-    client_secret = os.getenv("SPOTIFY_CLIENT_SECRET")
+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):
+    client_id, client_secret = spotify_credentials(args)
 
     if not client_id or not client_secret:
         print("\nERROR: Spotify credentials not found.")
-        print("Set:")
+        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)
@@ -200,7 +226,7 @@ def download_cover(url: str, destination: Path):
         url,
         timeout=30,
         headers={
-            "User-Agent": "trackfetch/2.1"
+            "User-Agent": "trackfetch/2.2"
         },
     )
 
@@ -695,6 +721,159 @@ def process_song(
     return True, "downloaded"
 
 
+def config_candidates():
+    """Config file locations, in the order they are looked up."""
+    candidates = []
+
+    env = os.getenv(CONFIG_ENV)
+
+    if env:
+        candidates.append(Path(env).expanduser())
+
+    candidates.append(Path.cwd() / CONFIG_FILENAME)
+
+    xdg = os.getenv("XDG_CONFIG_HOME")
+
+    if xdg:
+        candidates.append(
+            Path(xdg).expanduser() / "trackfetch" / CONFIG_FILENAME
+        )
+
+    candidates.append(
+        Path.home() / ".config" / "trackfetch" / CONFIG_FILENAME
+    )
+    candidates.append(Path.home() / CONFIG_FILENAME)
+
+    return candidates
+
+
+def find_config_file(explicit=None):
+    """Return the config file to use, or None if there is none."""
+    if explicit is not None:
+        return Path(explicit).expanduser()
+
+    for candidate in config_candidates():
+        if candidate.is_file():
+            return candidate
+
+    return None
+
+
+def load_config(explicit=None):
+    """Read settings from a config file.
+
+    Returns a (settings, path) tuple. Settings is empty when no config file
+    exists. Raises FileNotFoundError when an explicitly requested file is
+    missing, and configparser.Error when the file cannot be parsed.
+    """
+    config_path = find_config_file(explicit)
+
+    if config_path is None:
+        return {}, None
+
+    if not config_path.is_file():
+        raise FileNotFoundError(f"Config file not found: {config_path}")
+
+    parser = configparser.ConfigParser()
+
+    with config_path.open(encoding="utf-8") as file:
+        parser.read_file(file)
+
+    settings = dict(parser.defaults())
+
+    if parser.has_section(CONFIG_SECTION):
+        settings.update(dict(parser[CONFIG_SECTION]))
+
+    return settings, config_path
+
+
+def config_str_value(settings, key):
+    """Read a plain string setting, or None when it is missing or blank."""
+    value = (settings.get(key) or "").strip()
+
+    if not value:
+        return None
+
+    return value
+
+
+def config_path_value(settings, key):
+    """Read a path-like setting, or None when it is missing or blank."""
+    value = config_str_value(settings, key)
+
+    if value is None:
+        return None
+
+    return Path(value).expanduser()
+
+
+def resolve_output(cli_output, settings):
+    """Pick the output directory: flag > config file > current directory."""
+    if cli_output is not None:
+        return Path(cli_output).expanduser()
+
+    from_config = config_path_value(settings, "output")
+
+    if from_config is not None:
+        return from_config
+
+    return Path.cwd()
+
+
+def coerce_config_value(action, raw):
+    """Convert a raw config value into the type the CLI option expects."""
+    if action.type is Path:
+        return Path(raw).expanduser()
+
+    if action.type is float:
+        return float(raw)
+
+    if action.type is int:
+        return int(raw)
+
+    if isinstance(action, argparse._StoreTrueAction):
+        return raw.lower() in ("1", "true", "yes", "on")
+
+    return raw
+
+
+def apply_config(args, parser, settings):
+    """Fill options that were not given on the command line from the config.
+
+    The flag always wins, the config file is the second source, and the
+    built-in default is the last one.
+    """
+    for action in parser._actions:
+        dest = action.dest
+
+        if dest in ("help", "version", "config"):
+            continue
+
+        if getattr(args, dest, None) is not None:
+            continue
+
+        raw = config_str_value(settings, dest)
+
+        if raw is None:
+            continue
+
+        try:
+            value = coerce_config_value(action, raw)
+
+        except (TypeError, ValueError) as error:
+            raise ValueError(
+                f"Invalid value for '{dest}' in config file: {raw} ({error})"
+            ) from error
+
+        if action.choices and value not in action.choices:
+            raise ValueError(
+                f"Unknown value for '{dest}' in config file: {raw} "
+                f"(choose from {', '.join(action.choices)})"
+            )
+
+        setattr(args, dest, value)
+
+
 def main():
     parser = argparse.ArgumentParser(
         description=(
@@ -706,6 +885,7 @@ def main():
     parser.add_argument(
         "input",
         type=Path,
+        nargs="?",
         help="Text file with Artist - Title",
     )
 
@@ -713,33 +893,94 @@ def main():
         "-o",
         "--output",
         type=Path,
-        default=Path.home() / "Music" / "trackfetch",
-        help="Output directory",
+        default=None,
+        help=(
+            "Output directory "
+            "(overrides the config file, "
+            "defaults to the current directory)"
+        ),
+    )
+
+    parser.add_argument(
+        "--config",
+        type=Path,
+        default=None,
+        help="Path to a config file",
     )
 
     parser.add_argument(
         "-f",
         "--format",
         choices=list(AUDIO_FORMATS),
-        default="mp3",
+        default=None,
         help="Audio format",
     )
 
     parser.add_argument(
         "--title-only",
         action="store_true",
+        default=None,
         help="Use only title in filename",
     )
 
     parser.add_argument(
         "--delay",
         type=float,
-        default=1.0,
+        default=None,
         help="Delay between songs in seconds",
     )
 
+    parser.add_argument(
+        "--spotify-client-id",
+        default=None,
+        help="Spotify client ID (overrides the config file and the env)",
+    )
+
+    parser.add_argument(
+        "--spotify-client-secret",
+        default=None,
+        help="Spotify client secret (overrides the config file and the env)",
+    )
+
     args = parser.parse_args()
 
+    try:
+        settings, config_path = load_config(args.config)
+
+    except FileNotFoundError as error:
+        print(f"ERROR: {error}")
+        sys.exit(1)
+
+    except configparser.Error as error:
+        print(f"ERROR: Invalid config file: {error}")
+        sys.exit(1)
+
+    try:
+        apply_config(args, parser, settings)
+
+    except ValueError as error:
+        print(f"ERROR: {error}")
+        sys.exit(1)
+
+    if args.output is None:
+        args.output = resolve_output(None, settings)
+
+    if args.format is None:
+        args.format = DEFAULT_FORMAT
+
+    if args.title_only is None:
+        args.title_only = False
+
+    if args.delay is None:
+        args.delay = DEFAULT_DELAY
+
+    if args.input is None:
+        print(
+            "ERROR: No input file. "
+            "Pass it as an argument or set 'input' in the config file."
+        )
+        sys.exit(1)
+
     if not args.input.exists():
         print(f"ERROR: Input file not found: {args.input}")
         sys.exit(1)
@@ -773,9 +1014,13 @@ def main():
 
     print(f"Found {len(songs)} songs")
     print(f"Already completed: {len(done)}")
+
+    if config_path:
+        print(f"Config: {config_path}")
+
     print(f"Output: {args.output}")
 
-    sp = get_spotify()
+    sp = get_spotify(args)
 
     success = 0
     skipped = 0