trackfetch 2.0.0__tar.gz → 2.2.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: trackfetch
-Version: 2.0.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
@@ -30,20 +30,21 @@ Requires-Dist: pytest-cov>=5; extra == "test"
 Dynamic: license-file
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/banner-dark.svg">
-  <img alt="trackfetch: a text file of songs in, tagged MP3s with cover art out" src=".github/assets/banner-light.svg" width="100%">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ByteMe6/trackfetch/master/.github/assets/banner-dark.svg">
+  <img alt="trackfetch: a text file of songs in, tagged MP3s with cover art out" src="https://raw.githubusercontent.com/ByteMe6/trackfetch/master/.github/assets/banner-light.svg" width="100%">
 </picture>
 
 <p align="center">
   <a href="https://github.com/ByteMe6/trackfetch/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/ByteMe6/trackfetch?style=flat-square&label=release&labelColor=15122B&color=FFB547"></a>
+  <a href="https://pypi.org/project/trackfetch/"><img alt="PyPI" src="https://img.shields.io/pypi/v/trackfetch?style=flat-square&label=pypi&labelColor=15122B&color=FFB547"></a>
   <a href="https://github.com/ByteMe6/trackfetch/actions/workflows/release.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/ByteMe6/trackfetch/release.yml?branch=master&style=flat-square&label=build&labelColor=15122B"></a>
   <a href="#install"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-FFB547?style=flat-square&labelColor=15122B"></a>
   <a href="#standalone-binary"><img alt="Linux, macOS and Windows on x86_64 and ARM64" src="https://img.shields.io/badge/linux%20%C2%B7%20macos%20%C2%B7%20windows-x86__64%20%2B%20arm64-FFB547?style=flat-square&labelColor=15122B"></a>
-  <a href="LICENSE"><img alt="License: GPL-3.0-or-later" src="https://img.shields.io/badge/license-GPL--3.0--or--later-FFB547?style=flat-square&labelColor=15122B"></a>
+  <a href="https://github.com/ByteMe6/trackfetch/blob/master/LICENSE"><img alt="License: GPL-3.0-or-later" src="https://img.shields.io/badge/license-GPL--3.0--or--later-FFB547?style=flat-square&labelColor=15122B"></a>
 </p>
 
 <p align="center">
-  <b>English</b> · <a href="README.uk.md">Українська</a> · <a href="README.ru.md">Русский</a>
+  <b>English</b> · <a href="https://github.com/ByteMe6/trackfetch/blob/master/README.uk.md">Українська</a> · <a href="https://github.com/ByteMe6/trackfetch/blob/master/README.ru.md">Русский</a>
 </p>
 
 <p align="center">
@@ -57,7 +58,7 @@ Dynamic: license-file
 
 <br>
 
-<img alt="Terminal recording: trackfetch skips two songs that are already downloaded, finds Daft Punk - One More Time on Spotify, scores five YouTube results, downloads the best one and saves a tagged MP3" src=".github/assets/demo.svg" width="100%">
+<img alt="Terminal recording: trackfetch skips two songs that are already downloaded, finds Daft Punk - One More Time on Spotify, scores five YouTube results, downloads the best one and saves a tagged MP3" src="https://raw.githubusercontent.com/ByteMe6/trackfetch/master/.github/assets/demo.svg" width="100%">
 
 <br>
 
@@ -66,7 +67,7 @@ trackfetch reads a plain text file with one `Artist - Title` per line. For every
 - **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.
 - **The right upload.** trackfetch scores five YouTube results per song. Official audio wins; covers, karaoke, nightcore, sped-up, slowed, remix and reaction videos lose.
-- **Best quality.** yt-dlp extracts the audio as the highest-quality VBR MP3.
+- **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.
 - **Plays everywhere.** Tags are written as ID3v2.3, which Windows Explorer, Apple Music, Android, car stereos and most other players read.
 - **Any alphabet.** Cyrillic and other non-Latin titles are matched correctly and kept in filenames. Characters that are illegal in filenames are replaced.
@@ -74,13 +75,32 @@ trackfetch reads a plain text file with one `Artist - Title` per line. For every
 
 ## Install
 
-trackfetch needs these tools on your `PATH`, plus 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)). Every method needs a free Spotify API key ([set it up below](#spotify-credentials)).
 
-| Tool | Used for | Install |
-| --- | --- | --- |
-| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | Searching and downloading from YouTube | `pipx install yt-dlp` · `brew install yt-dlp` · `winget install yt-dlp` |
-| [FFmpeg](https://ffmpeg.org/) | Converting the audio to MP3 | `sudo apt install ffmpeg` · `brew install ffmpeg` · `winget install ffmpeg` |
-| [Deno](https://deno.com/) | JavaScript runtime that yt-dlp needs for YouTube | `curl -fsSL https://deno.land/install.sh \| sh` · `brew install deno` · `winget install DenoLand.Deno` |
+### Homebrew
+
+macOS and Linux:
+
+```bash
+brew install ByteMe6/tap/trackfetch
+```
+
+On Intel Macs, Homebrew builds the dependencies from source, so the first install takes a while.
+
+### Nix
+
+Linux and Apple Silicon Macs, with flakes enabled:
+
+```bash
+nix run github:ByteMe6/trackfetch -- songs.txt   # run without installing
+nix profile install github:ByteMe6/trackfetch    # install
+```
+
+### pipx
+
+```bash
+pipx install trackfetch
+```
 
 ### Standalone binary
 
@@ -101,12 +121,6 @@ sudo mv trackfetch-linux-x86_64 /usr/local/bin/trackfetch
 
 On macOS, if Gatekeeper blocks the unsigned binary, run `xattr -d com.apple.quarantine trackfetch-macos-*` once. Checksums are in `SHA256SUMS.txt` on each release.
 
-### pipx
-
-```bash
-pipx install git+https://github.com/ByteMe6/trackfetch.git
-```
-
 ### From source
 
 ```bash
@@ -116,6 +130,16 @@ python -m venv .venv && source .venv/bin/activate
 pip install -e .
 ```
 
+### Dependencies
+
+With pipx, a standalone binary or a source install, put these on your `PATH`:
+
+| Tool | Used for | Install |
+| --- | --- | --- |
+| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | Searching and downloading from YouTube | `pipx install yt-dlp` · `brew install yt-dlp` · `winget install yt-dlp` |
+| [FFmpeg](https://ffmpeg.org/) | Converting the audio to MP3 | `sudo apt install ffmpeg` · `brew install ffmpeg` · `winget install ffmpeg` |
+| [Deno](https://deno.com/) | JavaScript runtime that yt-dlp needs for YouTube | `curl -fsSL https://deno.land/install.sh \| sh` · `brew install deno` · `winget install DenoLand.Deno` |
+
 ## Spotify credentials
 
 trackfetch uses Spotify's Client Credentials flow: no Spotify login, no access to your account.
@@ -171,7 +195,7 @@ EOF
 trackfetch songs.txt
 ```
 
-The files land in `~/Music/trackfetch/`.
+The files land in the current directory.
 
 ## Playlists from streaming services
 
@@ -189,22 +213,90 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist"
 ## Usage
 
 ```text
-trackfetch [-h] [-o OUTPUT] [--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 MP3s in. It's created if it doesn't exist. |
-| `--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
 trackfetch songs.txt -o /media/usb --title-only   # short names for a car stereo
 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 |
+| --- | --- | --- |
+| `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 |
+| `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.
+
 ### Input file
 
 ```text
@@ -213,14 +305,14 @@ Daft Punk - One More Time
 Sufjan Stevens - Mystery of Love - Remastered   ← only the first " - " separates artist and title
 ```
 
-The separator is space, hyphen, space (` - `). Lines without it are skipped. See [`examples/songs.txt`](examples/songs.txt).
+The separator is space, hyphen, space (` - `). Lines without it are skipped. See [`examples/songs.txt`](https://github.com/ByteMe6/trackfetch/blob/master/examples/songs.txt).
 
 ### 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
 ```
@@ -228,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
 ```
 
@@ -236,7 +328,7 @@ trackfetch retry.txt
 
 ### Cheat sheet
 
-A [tldr](https://tldr.sh/) page is in [`docs/tldr/trackfetch.md`](docs/tldr/trackfetch.md). To use it with [tealdeer](https://github.com/tealdeer-rs/tealdeer), copy it into your custom pages folder as `trackfetch.page.md`.
+A [tldr](https://tldr.sh/) page is in [`docs/tldr/trackfetch.md`](https://github.com/ByteMe6/trackfetch/blob/master/docs/tldr/trackfetch.md). To use it with [tealdeer](https://github.com/tealdeer-rs/tealdeer), copy it into your custom pages folder as `trackfetch.page.md`.
 
 ## How it works
 
@@ -313,11 +405,11 @@ pytest --cov=trackfetch
 
 The tests stub every network and subprocess call, so they run offline in under a second. To build a standalone binary yourself, run `pip install pyinstaller && pyinstaller trackfetch.spec`; it ends up in `dist/`.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+See [CONTRIBUTING.md](https://github.com/ByteMe6/trackfetch/blob/master/CONTRIBUTING.md) before opening a pull request.
 
 ### Releasing
 
-Every push to `master` runs the tests on Linux, macOS and Windows. When `version` in [`pyproject.toml`](pyproject.toml) has no matching `vX.Y.Z` tag yet, the [Build & Release](.github/workflows/release.yml) workflow also builds all six binaries and publishes a release, using that version's section of [`CHANGELOG.md`](CHANGELOG.md) as the notes.
+Every push to `master` runs the tests on Linux, macOS and Windows. When `version` in [`pyproject.toml`](https://github.com/ByteMe6/trackfetch/blob/master/pyproject.toml) has no matching `vX.Y.Z` tag yet, the [Build & Release](https://github.com/ByteMe6/trackfetch/blob/master/.github/workflows/release.yml) workflow also builds all six binaries and publishes a release, using that version's section of [`CHANGELOG.md`](https://github.com/ByteMe6/trackfetch/blob/master/CHANGELOG.md) as the notes.
 
 To release, move the changes under `[Unreleased]` in the changelog to a new `## [X.Y.Z] - YYYY-MM-DD` section, bump `version`, and push.
 
@@ -330,4 +422,4 @@ trackfetch is for personal use with content you have the right to download. You
 
 ## License
 
-trackfetch is free software, released under the [GNU General Public License v3.0 or later](LICENSE). You can use, study, change and share it. If you distribute a modified version, it must stay under the same license.
+trackfetch is free software, released under the [GNU General Public License v3.0 or later](https://github.com/ByteMe6/trackfetch/blob/master/LICENSE). You can use, study, change and share it. If you distribute a modified version, it must stay under the same license.

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

@@ -1,18 +1,19 @@
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset=".github/assets/banner-dark.svg">
-  <img alt="trackfetch: a text file of songs in, tagged MP3s with cover art out" src=".github/assets/banner-light.svg" width="100%">
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ByteMe6/trackfetch/master/.github/assets/banner-dark.svg">
+  <img alt="trackfetch: a text file of songs in, tagged MP3s with cover art out" src="https://raw.githubusercontent.com/ByteMe6/trackfetch/master/.github/assets/banner-light.svg" width="100%">
 </picture>
 
 <p align="center">
   <a href="https://github.com/ByteMe6/trackfetch/releases/latest"><img alt="Latest release" src="https://img.shields.io/github/v/release/ByteMe6/trackfetch?style=flat-square&label=release&labelColor=15122B&color=FFB547"></a>
+  <a href="https://pypi.org/project/trackfetch/"><img alt="PyPI" src="https://img.shields.io/pypi/v/trackfetch?style=flat-square&label=pypi&labelColor=15122B&color=FFB547"></a>
   <a href="https://github.com/ByteMe6/trackfetch/actions/workflows/release.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/ByteMe6/trackfetch/release.yml?branch=master&style=flat-square&label=build&labelColor=15122B"></a>
   <a href="#install"><img alt="Python 3.10+" src="https://img.shields.io/badge/python-3.10%2B-FFB547?style=flat-square&labelColor=15122B"></a>
   <a href="#standalone-binary"><img alt="Linux, macOS and Windows on x86_64 and ARM64" src="https://img.shields.io/badge/linux%20%C2%B7%20macos%20%C2%B7%20windows-x86__64%20%2B%20arm64-FFB547?style=flat-square&labelColor=15122B"></a>
-  <a href="LICENSE"><img alt="License: GPL-3.0-or-later" src="https://img.shields.io/badge/license-GPL--3.0--or--later-FFB547?style=flat-square&labelColor=15122B"></a>
+  <a href="https://github.com/ByteMe6/trackfetch/blob/master/LICENSE"><img alt="License: GPL-3.0-or-later" src="https://img.shields.io/badge/license-GPL--3.0--or--later-FFB547?style=flat-square&labelColor=15122B"></a>
 </p>
 
 <p align="center">
-  <b>English</b> · <a href="README.uk.md">Українська</a> · <a href="README.ru.md">Русский</a>
+  <b>English</b> · <a href="https://github.com/ByteMe6/trackfetch/blob/master/README.uk.md">Українська</a> · <a href="https://github.com/ByteMe6/trackfetch/blob/master/README.ru.md">Русский</a>
 </p>
 
 <p align="center">
@@ -26,7 +27,7 @@
 
 <br>
 
-<img alt="Terminal recording: trackfetch skips two songs that are already downloaded, finds Daft Punk - One More Time on Spotify, scores five YouTube results, downloads the best one and saves a tagged MP3" src=".github/assets/demo.svg" width="100%">
+<img alt="Terminal recording: trackfetch skips two songs that are already downloaded, finds Daft Punk - One More Time on Spotify, scores five YouTube results, downloads the best one and saves a tagged MP3" src="https://raw.githubusercontent.com/ByteMe6/trackfetch/master/.github/assets/demo.svg" width="100%">
 
 <br>
 
@@ -35,7 +36,7 @@ trackfetch reads a plain text file with one `Artist - Title` per line. For every
 - **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.
 - **The right upload.** trackfetch scores five YouTube results per song. Official audio wins; covers, karaoke, nightcore, sped-up, slowed, remix and reaction videos lose.
-- **Best quality.** yt-dlp extracts the audio as the highest-quality VBR MP3.
+- **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.
 - **Plays everywhere.** Tags are written as ID3v2.3, which Windows Explorer, Apple Music, Android, car stereos and most other players read.
 - **Any alphabet.** Cyrillic and other non-Latin titles are matched correctly and kept in filenames. Characters that are illegal in filenames are replaced.
@@ -43,13 +44,32 @@ trackfetch reads a plain text file with one `Artist - Title` per line. For every
 
 ## Install
 
-trackfetch needs these tools on your `PATH`, plus 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)). Every method needs a free Spotify API key ([set it up below](#spotify-credentials)).
 
-| Tool | Used for | Install |
-| --- | --- | --- |
-| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | Searching and downloading from YouTube | `pipx install yt-dlp` · `brew install yt-dlp` · `winget install yt-dlp` |
-| [FFmpeg](https://ffmpeg.org/) | Converting the audio to MP3 | `sudo apt install ffmpeg` · `brew install ffmpeg` · `winget install ffmpeg` |
-| [Deno](https://deno.com/) | JavaScript runtime that yt-dlp needs for YouTube | `curl -fsSL https://deno.land/install.sh \| sh` · `brew install deno` · `winget install DenoLand.Deno` |
+### Homebrew
+
+macOS and Linux:
+
+```bash
+brew install ByteMe6/tap/trackfetch
+```
+
+On Intel Macs, Homebrew builds the dependencies from source, so the first install takes a while.
+
+### Nix
+
+Linux and Apple Silicon Macs, with flakes enabled:
+
+```bash
+nix run github:ByteMe6/trackfetch -- songs.txt   # run without installing
+nix profile install github:ByteMe6/trackfetch    # install
+```
+
+### pipx
+
+```bash
+pipx install trackfetch
+```
 
 ### Standalone binary
 
@@ -70,12 +90,6 @@ sudo mv trackfetch-linux-x86_64 /usr/local/bin/trackfetch
 
 On macOS, if Gatekeeper blocks the unsigned binary, run `xattr -d com.apple.quarantine trackfetch-macos-*` once. Checksums are in `SHA256SUMS.txt` on each release.
 
-### pipx
-
-```bash
-pipx install git+https://github.com/ByteMe6/trackfetch.git
-```
-
 ### From source
 
 ```bash
@@ -85,6 +99,16 @@ python -m venv .venv && source .venv/bin/activate
 pip install -e .
 ```
 
+### Dependencies
+
+With pipx, a standalone binary or a source install, put these on your `PATH`:
+
+| Tool | Used for | Install |
+| --- | --- | --- |
+| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | Searching and downloading from YouTube | `pipx install yt-dlp` · `brew install yt-dlp` · `winget install yt-dlp` |
+| [FFmpeg](https://ffmpeg.org/) | Converting the audio to MP3 | `sudo apt install ffmpeg` · `brew install ffmpeg` · `winget install ffmpeg` |
+| [Deno](https://deno.com/) | JavaScript runtime that yt-dlp needs for YouTube | `curl -fsSL https://deno.land/install.sh \| sh` · `brew install deno` · `winget install DenoLand.Deno` |
+
 ## Spotify credentials
 
 trackfetch uses Spotify's Client Credentials flow: no Spotify login, no access to your account.
@@ -140,7 +164,7 @@ EOF
 trackfetch songs.txt
 ```
 
-The files land in `~/Music/trackfetch/`.
+The files land in the current directory.
 
 ## Playlists from streaming services
 
@@ -158,22 +182,90 @@ trackfetch "My Playlist.txt" -o ~/Music/"My Playlist"
 ## Usage
 
 ```text
-trackfetch [-h] [-o OUTPUT] [--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 MP3s in. It's created if it doesn't exist. |
-| `--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
 trackfetch songs.txt -o /media/usb --title-only   # short names for a car stereo
 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 |
+| --- | --- | --- |
+| `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 |
+| `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.
+
 ### Input file
 
 ```text
@@ -182,14 +274,14 @@ Daft Punk - One More Time
 Sufjan Stevens - Mystery of Love - Remastered   ← only the first " - " separates artist and title
 ```
 
-The separator is space, hyphen, space (` - `). Lines without it are skipped. See [`examples/songs.txt`](examples/songs.txt).
+The separator is space, hyphen, space (` - `). Lines without it are skipped. See [`examples/songs.txt`](https://github.com/ByteMe6/trackfetch/blob/master/examples/songs.txt).
 
 ### 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
 ```
@@ -197,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
 ```
 
@@ -205,7 +297,7 @@ trackfetch retry.txt
 
 ### Cheat sheet
 
-A [tldr](https://tldr.sh/) page is in [`docs/tldr/trackfetch.md`](docs/tldr/trackfetch.md). To use it with [tealdeer](https://github.com/tealdeer-rs/tealdeer), copy it into your custom pages folder as `trackfetch.page.md`.
+A [tldr](https://tldr.sh/) page is in [`docs/tldr/trackfetch.md`](https://github.com/ByteMe6/trackfetch/blob/master/docs/tldr/trackfetch.md). To use it with [tealdeer](https://github.com/tealdeer-rs/tealdeer), copy it into your custom pages folder as `trackfetch.page.md`.
 
 ## How it works
 
@@ -282,11 +374,11 @@ pytest --cov=trackfetch
 
 The tests stub every network and subprocess call, so they run offline in under a second. To build a standalone binary yourself, run `pip install pyinstaller && pyinstaller trackfetch.spec`; it ends up in `dist/`.
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) before opening a pull request.
+See [CONTRIBUTING.md](https://github.com/ByteMe6/trackfetch/blob/master/CONTRIBUTING.md) before opening a pull request.
 
 ### Releasing
 
-Every push to `master` runs the tests on Linux, macOS and Windows. When `version` in [`pyproject.toml`](pyproject.toml) has no matching `vX.Y.Z` tag yet, the [Build & Release](.github/workflows/release.yml) workflow also builds all six binaries and publishes a release, using that version's section of [`CHANGELOG.md`](CHANGELOG.md) as the notes.
+Every push to `master` runs the tests on Linux, macOS and Windows. When `version` in [`pyproject.toml`](https://github.com/ByteMe6/trackfetch/blob/master/pyproject.toml) has no matching `vX.Y.Z` tag yet, the [Build & Release](https://github.com/ByteMe6/trackfetch/blob/master/.github/workflows/release.yml) workflow also builds all six binaries and publishes a release, using that version's section of [`CHANGELOG.md`](https://github.com/ByteMe6/trackfetch/blob/master/CHANGELOG.md) as the notes.
 
 To release, move the changes under `[Unreleased]` in the changelog to a new `## [X.Y.Z] - YYYY-MM-DD` section, bump `version`, and push.
 
@@ -299,4 +391,4 @@ trackfetch is for personal use with content you have the right to download. You
 
 ## License
 
-trackfetch is free software, released under the [GNU General Public License v3.0 or later](LICENSE). You can use, study, change and share it. If you distribute a modified version, it must stay under the same license.
+trackfetch is free software, released under the [GNU General Public License v3.0 or later](https://github.com/ByteMe6/trackfetch/blob/master/LICENSE). You can use, study, change and share it. If you distribute a modified version, it must stay under the same license.

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "trackfetch"
-version = "2.0.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"