trackfetch 2.0.0

English · Українська · Русский

Install · Quick start · Playlists from streaming services · Usage · How it works · Troubleshooting

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.

• 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.
• 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.
• No Python needed. Standalone binaries for Linux, macOS and Windows on x86_64 and ARM64.

Install

trackfetch needs these tools on your PATH, plus a free Spotify API key (set it up below):

Standalone binary

No Python required. Download the file for your system from the latest release:

On Linux and macOS, make it executable and put it on your PATH:

chmod +x trackfetch-linux-x86_64
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

pipx install git+https://github.com/ByteMe6/trackfetch.git

From source

git clone https://github.com/ByteMe6/trackfetch.git
cd trackfetch
python -m venv .venv && source .venv/bin/activate
pip install -e .

Spotify credentials

trackfetch uses Spotify's Client Credentials flow: no Spotify login, no access to your account.

1. Open the Spotify Developer Dashboard and click Create app.
2. Enter any name and description. For the redirect URI, enter http://127.0.0.1:8888/callback. trackfetch never uses it, but the form requires one.
3. Open the app's Settings and copy the Client ID and Client Secret.
4. Set them as environment variables:

export SPOTIFY_CLIENT_ID='your-client-id'
export SPOTIFY_CLIENT_SECRET='your-client-secret'

set -Ux SPOTIFY_CLIENT_ID 'your-client-id'
set -Ux SPOTIFY_CLIENT_SECRET 'your-client-secret'

[Environment]::SetEnvironmentVariable('SPOTIFY_CLIENT_ID', 'your-client-id', 'User')
[Environment]::SetEnvironmentVariable('SPOTIFY_CLIENT_SECRET', 'your-client-secret', 'User')

Quick start

cat > songs.txt <<'EOF'
# My playlist
Daft Punk - One More Time
Radiohead - Paranoid Android
Korol i Shut - Мёртвый Анархист
EOF

trackfetch songs.txt

The files land in ~/Music/trackfetch/.

Playlists from streaming services

You don't have to type the list by hand. TuneMyMusic exports playlists from Spotify, Apple Music, YouTube Music, Deezer, Tidal, SoundCloud and other services to a text file that trackfetch reads as is:

1. On tunemymusic.com, choose the service your playlist is on as the source.
2. Select the playlists you want.
3. Choose Export to file as the destination and save it as TXT.
4. Run trackfetch on the exported file:

trackfetch "My Playlist.txt" -o ~/Music/"My Playlist"

Usage

trackfetch [-h] [-o OUTPUT] [--title-only] [--delay DELAY] input

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

Input file

# Lines starting with "#" are comments. Blank lines are ignored.
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.

Output folder

~/Music/trackfetch/
├── Daft Punk - One More Time.mp3
├── Radiohead - Paranoid Android.mp3
├── done.txt      ← finished songs, skipped on the next run
└── failed.txt    ← "Artist - Title | reason" for each song that failed

Retry failures by stripping the reasons from failed.txt and running it again:

cut -d '|' -f 1 ~/Music/trackfetch/failed.txt > retry.txt
trackfetch retry.txt

Re-download a song by deleting its MP3 and its line in done.txt.

Cheat sheet

A tldr page is in docs/tldr/trackfetch.md. To use it with tealdeer, copy it into your custom pages folder as trackfetch.page.md.

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.

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
   Similarity to the song title	× 0.70
   Similarity to the artist	× 0.30
   official audio in the video title	+0.08
   audio in the video title	+0.03
   cover, karaoke, караоке, nightcore, sped up, slowed, remix, reaction	−0.20 each

3. Download. yt-dlp downloads only the winning video and converts it to MP3.

4. Tag. trackfetch replaces any existing tags with these ID3v2.3 frames:

   Frame	Content
   TIT2	Title
   TPE1	Artists
   TALB	Album
   TPE2	Album artist
   TRCK	Track number
   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.

Troubleshooting

Development

pip install -e ".[test]" ruff
ruff check .
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 before opening a pull request.

Releasing

Every push to master runs the tests on Linux, macOS and Windows. When version in pyproject.toml has no matching vX.Y.Z tag yet, the Build & Release workflow also builds all six binaries and publishes a release, using that version's section of 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.

Disclaimer

trackfetch is for personal use with content you have the right to download. You are responsible for following copyright law where you live and the terms of service of YouTube and Spotify. trackfetch isn't affiliated with or endorsed by Spotify, YouTube or TuneMyMusic. If you can, support the artists you listen to.

License

trackfetch is free software, released under the GNU General Public License v3.0 or later. You can use, study, change and share it. If you distribute a modified version, it must stay under the same license.