trackfetch

trackfetch [-h] [-o output] [-f mp3|m4a|opus] [--title-only] [--delay seconds] input

trackfetch reads a plain text file with one `Artist - Title` per line, looks up official metadata and cover art on Spotify, picks matching audio on YouTube with yt-dlp, and writes tagged files. Runs are resumable: finished songs are recorded in `done.txt` in the output directory and skipped next time; failures go to `failed.txt` as `Artist - Title | reason`.The default output directory is `~/Music/trackfetch`. Tags are written as ID3v2.3 (title, artists, album, album artist, track number, release date, and front cover up to 640×640). Cyrillic and other non-Latin titles are kept in filenames; characters that are illegal in filenames are replaced.For each song it searches Spotify with `artist:"…" track:"…"` (then a looser query if needed), scores results by fuzzy similarity (70% title, 30% artist), and uses the best match for spelling, credits, album details, and cover. It then searches YouTube for that artist and title and scores the top five results, boosting titles that say official audio and penalizing cover, karaoke, nightcore, sped-up, slowed, remix, and reaction videos. If Spotify has no match, the song is still downloaded and tagged with the artist and title from the input file.mp3 (default) re-encodes YouTube audio to VBR MP3. opus and m4a copy YouTube's original Opus or AAC when available, without a second lossy encode. All three formats get the same tags and cover. `done.txt` does not record the format, so use a separate --output directory per format.The input separator is space, hyphen, space (` - `). Only the first occurrence splits artist from title. Lines starting with `#` are comments; blank lines and lines without the separator are skipped.Python 3.10 or later is required for the PyPI install. yt-dlp, ffmpeg, and deno must be on `PATH` unless Homebrew or Nix installed them as dependencies. Spotify access uses the Client Credentials flow: a free app on the Spotify Developer Dashboard, with SPOTIFY_CLIENT_ID and SPOTIFY_CLIENT_SECRET in the environment. trackfetch does not log into a Spotify user account.

input

Text file with one `Artist - Title` per line.

Directory to write audio, `done.txt`, and `failed.txt`. Created if missing. Default: `~/Music/trackfetch`.

Audio format: mp3 (default), m4a, or opus.

Name files `Title.ext` instead of `Artist - Title.ext`.

Pause between songs. Default: 1.0. Raise it for long lists.

Show argparse help and exit.

SPOTIFY_CLIENT_ID, SPOTIFY_CLIENT_SECRET

Spotify app Client ID and Client Secret. Required. Create an app at https://developer.spotify.com/dashboard (the form requires a redirect URI; `http://127.0.0.1:8888/callback` is accepted and unused).

Audio comes from YouTube, not from Spotify's own files. Availability, matching, and quality vary. mp3 is a second lossy encode. opus does not play in iTunes or many older devices. Rate limits and YouTube/Spotify API changes can cause failures; raise --delay on long lists. To re-download a song, delete its audio file and its line in `done.txt`. Respect copyright and the terms of the services you query.

trackfetch is GPL-3.0-or-later software by ByteMe6. The PyPI package and command are both trackfetch (2.1 series at the time of writing). Standalone binaries are published for Linux, macOS, and Windows on x86_64 and ARM64.

yt-dlp(1), ffmpeg(1), spotdl(1), ytmdl(1), deno(1)

Source code · Homepage · Documentation