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 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.
- 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.txtand skipped next time. Failures go tofailed.txtwith 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.
Pick one. Homebrew and Nix also install yt-dlp, FFmpeg and Deno for you; with the other methods, install them yourself (see below). 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).
macOS and Linux:
brew install ByteMe6/tap/trackfetchOn macOS the formula installs the prebuilt trackfetch binary and a static prebuilt ffmpeg inside the formula, so ffmpeg, the dependency Homebrew used to build for hours on Intel Macs and newer macOS versions, is never compiled. yt-dlp and deno come from Homebrew as usual.
Linux and Apple Silicon Macs, with flakes enabled:
nix run github:ByteMe6/trackfetch -- songs.txt # run without installing
nix profile install github:ByteMe6/trackfetch # installpipx install trackfetchNo Python required. Download the file for your system from the latest release:
| x86_64 | ARM64 | |
|---|---|---|
| Linux | trackfetch-linux-x86_64 |
trackfetch-linux-arm64 |
| macOS | trackfetch-macos-x86_64 (Intel) |
trackfetch-macos-arm64 (Apple Silicon) |
| Windows | trackfetch-windows-x86_64.exe |
trackfetch-windows-arm64.exe |
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/trackfetchOn macOS, if Gatekeeper blocks the unsigned binary, run xattr -d com.apple.quarantine trackfetch-macos-* once. Checksums are in SHA256SUMS.txt on each release.
git clone https://github.com/ByteMe6/trackfetch.git
cd trackfetch
python -m venv .venv && source .venv/bin/activate
pip install -e .With pipx, a standalone binary or a source install, put these on your PATH:
| Tool | Used for | Install |
|---|---|---|
| yt-dlp | Searching and downloading from YouTube | pipx install yt-dlp · brew install yt-dlp · winget install yt-dlp |
| FFmpeg | Converting the audio to MP3 | sudo apt install ffmpeg · brew install ffmpeg · winget install ffmpeg |
| Deno | JavaScript runtime that yt-dlp needs for YouTube | curl -fsSL https://deno.land/install.sh | sh · brew install deno · winget install DenoLand.Deno |
trackfetch uses Spotify's Client Credentials flow: no Spotify login, no access to your account.
- Open the Spotify Developer Dashboard and click Create app.
- 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. - Open the app's Settings and copy the Client ID and Client Secret.
- Set them as environment variables:
bash / zsh
export SPOTIFY_CLIENT_ID='your-client-id'
export SPOTIFY_CLIENT_SECRET='your-client-secret'fish
set -Ux SPOTIFY_CLIENT_ID 'your-client-id'
set -Ux SPOTIFY_CLIENT_SECRET 'your-client-secret'PowerShell
[Environment]::SetEnvironmentVariable('SPOTIFY_CLIENT_ID', 'your-client-id', 'User')
[Environment]::SetEnvironmentVariable('SPOTIFY_CLIENT_SECRET', 'your-client-secret', 'User')Caution
Spotipy caches the access token in a .cache file in the current directory. Don't commit it or share it.
cat > songs.txt <<'EOF'
# My playlist
Daft Punk - One More Time
Radiohead - Paranoid Android
Korol i Shut - Мёртвый Анархист
EOF
trackfetch songs.txtThe files land in the current directory.
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:
- On tunemymusic.com, choose the service your playlist is on as the source.
- Select the playlists you want.
- Choose Export to file as the destination and save it as TXT.
- Run trackfetch on the exported file:
trackfetch "My Playlist.txt" -o ~/Music/"My Playlist"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] [--no-logs] [--lyrics | --no-lyrics] [INPUT ...]
| Option | Default | What it does |
|---|---|---|
INPUT |
optional | Text file with one Artist - Title per line, or an inline Artist - Title track. Can also be set in the config file. |
--track |
— | Track to download inline, Artist - Title. Can be given several times. |
-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. |
-f, --format |
m4a |
Audio format: mp3, m4a or opus. See 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. 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. 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-client-secret |
$SPOTIFY_CLIENT_SECRET |
Spotify API client secret. |
--no-logs |
off | Do not read done.txt and do not write done.txt or failed.txt. Progress from earlier runs is ignored, so finished songs are not skipped. |
--lyrics / --no-lyrics |
on | Embed lyrics fetched from LRCLIB into MP3 tags. Plain text goes to USLT; timed lyrics also go to SYLT. Missing lyrics never fail the download. |
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
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 spotify # skip Spotify explicitly
trackfetch --list-sourcesThe 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.5 s | Storefront country defaults to us. About 20 Search API calls per minute are allowed, so the interval keeps a small margin below that ceiling. |
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. 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.
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.85CJK 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. 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 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.
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.
For MP3 output trackfetch also looks up lyrics on LRCLIB
and embeds them in the ID3 tag, so players can show the words offline without
sidecar .lrc or .txt files.
| Frame | Contents |
|---|---|
USLT |
The full plain text, without timestamps. |
SYLT |
Timed lines, only when the source returns synchronized lyrics. |
When timed lyrics are available, both frames are written: USLT keeps the
full text for players without SYLT support. When only plain lyrics are
available, only USLT is written. Timestamps are never invented.
The source is LRCLIB, which needs no API key. Lyrics embedding is enabled by
default for MP3 and can be turned off with --no-lyrics or
lyrics_enabled = false in the config file. The other formats (m4a, opus)
are not changed by this option.
Missing lyrics, a timeout or an HTTP error never fails the download. The MP3
is still saved with its usual metadata. If an MP3 already contains lyrics and
no new lyrics are found, the existing frames are left untouched. When new
lyrics are found, the old USLT/SYLT frames are replaced instead of
duplicated. Existing tags and cover art, and the audio data itself, are never
rewritten or re-encoded.
trackfetch songs.txt --format mp3 # embed lyrics (default)
trackfetch songs.txt --format mp3 --no-lyrics # keep MP3 tags lyrics-freeSkip the file and name the tracks right on the command line:
trackfetch "Daft Punk - One More Time"
trackfetch "Daft Punk - One More Time" "Radiohead - Paranoid Android"
trackfetch --track "Daft Punk - One More Time" --track "Radiohead - Paranoid Android"A file and inline tracks can be mixed: trackfetch songs.txt --track "Blur - Song 2".
The separator is the same - as in the file, and the first - splits the
artist from the title.
Put your defaults in an INI file and forget the flags:
[trackfetch]
output = ~/Music/trackfetch
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
no_logs = false
itunes_enabled = true
itunes_country = us
itunes_min_interval = 3.5
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
# Lyrics embedding into MP3 tags
lyrics_enabled = true
# Matching thresholds
match_threshold = 0.6
title_threshold = 0.8Most 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:
- the command-line flag,
- the config file,
- 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,
~/.config/trackfetch/trackfetch.ini and ~/.trackfetch.ini.
A relative path in the config file, such as output = songs, is relative to
the directory you run trackfetch from. A [DEFAULT] section works as well.
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:
# in the config file
[trackfetch]
spotify_client_id = your-client-id
spotify_client_secret = your-client-secret# in the environment
export SPOTIFY_CLIENT_ID='your-client-id'
export SPOTIFY_CLIENT_SECRET='your-client-secret'# on the command line
trackfetch songs.txt --spotify-client-id your-id --spotify-client-secret your-secretThe flag wins over the config file, and the config file wins over the environment variable.
| 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 metadata tags and embedded cover art. Embedded lyrics are written to MP3 only. done.txt doesn't track the format, so use a separate -o folder for each format.
# 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,
and trackfetch prints how many lines it skipped and which ones they were. See examples/songs.txt.
./
├── 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
Retry failures by stripping the reasons from failed.txt and running it again:
cut -d '|' -f 1 ./failed.txt > retry.txt
trackfetch retry.txtRe-download a song by deleting its MP3 and its line in done.txt.
With --no-logs, trackfetch does not read done.txt and does not write
done.txt or failed.txt. Progress is therefore not restored between runs:
songs finished in an earlier run are downloaded again, and the failure log is
neither created nor updated. failed.txt is a write-only log in every mode, so
the flag only makes trackfetch stop producing it.
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.
-
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_thresholdand thetitle_thresholdmust pass, so an unrelated result is rejected instead of being used. The winning result supplies the title, artists, album details, release date and artwork. -
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 audioin the video title+0.08 audioin the video title+0.03 cover,karaoke,караоке,nightcore,sped up,slowed,remix,reaction−0.20 each -
Download. yt-dlp downloads only the winning video and converts it to the chosen format.
m4aandopuskeep YouTube's original audio,mp3re-encodes it. -
Tag. trackfetch replaces any existing tags with these ID3v2.3 frames:
Frame Content TIT2Title TPE1Artists TALBAlbum TPE2Album artist TRCKTrack number TDRCRelease date APICFront cover, up to 640×640
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.
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.
A provider is skipped temporarily
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.
Every song fails with no YouTube result or yt-dlp download failed
YouTube changes often. Update yt-dlp first with pipx upgrade yt-dlp or yt-dlp -U. Recent versions of yt-dlp also need Deno: check that deno --version works in the same terminal.
ERROR: Postprocessing: ffprobe and ffmpeg not found
Install FFmpeg and check that ffmpeg -version works in the same terminal.
The wrong version of a song was downloaded
Make the line in your file more specific, for example by using the exact title as Spotify spells it. Then delete the MP3 and its line in done.txt and run trackfetch again. If it keeps picking the wrong upload, open an issue with the YouTube score lines from the output.
HTTP 429 or other rate-limit errors
Raise --delay, for example to 3. Stopped runs continue where they left off.
pip install -e ".[test]" ruff
ruff check .
pytest --cov=trackfetchThe 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.
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.
Important
Bump the version in a commit that doesn't edit .github/workflows/. GitHub doesn't let the workflow token tag a commit that changes workflow files, so the release step would fail with a 403.
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.
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.