earworm

Playlist in, library out.

A terminal app that turns a YouTube playlist into audio files with verified tags, cover art and an .m3u8.

brew install yt-dlp ffmpeg chromaprint
cargo install --git https://github.com/madebygrant/earworm --tag v0.4.0
# To open the TUI
earworm
# Or without using the TUI
earworm 'https://youtube.com/playlist?list=...'

Features

yt-dlp downloads the audio. earworm does the rest, which is what separates a download from a music library:

• Tagging that checks itself. Artist and title are parsed out of the video title, then confirmed against AcoustID fingerprints, Deezer and Apple Music. A track that survives none of that is marked guessed, and earworm asks about it rather than writing a tag it can't back up.
• Cover art embedded at a sane size. YouTube serves 2048² thumbnails for its auto-generated albums. earworm keeps them out of your files: what gets embedded is capped at 1000×1000.
• Albums get one sleeve, playlists get twelve. An official album release is recognised on sight, and anything else you settle by putting [album] or [playlist] in the folder's name. earworm reads that marker and never writes one.
• Re-runs skip work you already did. Each playlist folder keeps an .earworm manifest with its URL and current filenames. Sync it again and earworm fetches only the new tracks, reports the ones that left the playlist, and reads the tags it already wrote instead of looking them up.
• Fix anything weeks later. Every folder opens from disk, offline. Edit tags, swap artist and title, search / across every folder you own, rename a playlist and have the rename survive the next sync.
• Music earworm didn't download is welcome too. Copy a folder of audio into your library and it appears with the rest, opens from its tags, and takes every editing key. Give it a URL later and earworm works out which files it already has before it fetches anything.
• Change format without throwing away what you have. Tracks already on disk convert on their next sync in whatever way costs the least re-encoding. Why some never re-encode at all is documented, because the answer surprised me too.
• Plays through cliamp. p hands over the playlist in the right order, tags as track titles.
• Four themes, measured rather than eyeballed, plus your own. ^t walks them with the screen in front of you and remembers the one you stop on. Every shipped colour clears WCAG 4.5:1 on its own background, including the light theme for terminals the other three are unreadable on, and a palette of your own gets the same numbers run over it.
• Icons for the library. ● marks an album, ▤ a playlist and ◆ a folder earworm did not download. icons = "nerd" draws larger Nerd Font glyphs, and icons = "text" goes back to words.
• Custom playlists. Build a list from tracks in any of your folders with N (which opens a fuzzy track picker) and P, reorder it, and play it in cliamp. It follows a track when you edit it, and deleting a list never touches audio.
• Export to a device. E copies a folder or a custom playlist to a stick, card or synced folder, with names every filesystem accepts and a playlist file beside the audio. A second export copies only what changed, and nothing on the device is deleted unless you ask, and then every file is named first. It can re-encode for players that cannot read opus. Details.
• A song on two playlists downloads once. A video another folder already holds is copied across instead of fetched again, and the pick screen marks a likely duplicate with ≈.
• Artists, and what you're missing of them. b lists every artist your tags name. Star the ones you follow, open an artist to see their discography marked owned, partial or missing, their top tracks and who's related, and hear about their new releases each time earworm starts. Details.
• Retries and undos. r re-downloads whatever failed. u puts back the last tag edit.

How a run goes

Give it a URL and earworm does the whole job: read the playlist, download, identify, tag, add art, name files, write the .m3u8. One step waits for you. Before downloading, the run shows the list and asks which tracks you want.

Enter takes all of them. Esc takes none. space and the / filter are there for everything in between, which you will need the first time a playlist turns out to be 361 tracks of seminar recordings.

Where to go next

docs/install.md	tools, the AcoustID key, --check
docs/configuration.md	the config file, every flag
docs/workflow.md	picks, filters, fixing tags, retry
docs/formats.md	m4a, opus, mp3, flac, and what converts
docs/chapters.md	cutting an album upload into tracks by its chapters
docs/loudness.md	ReplayGain and R128 tags, so tracks play at one volume
docs/lyrics.md	embedded lyrics from LRCLIB, and what is sent to it
docs/library.md	the library screen, search, --resync
docs/discovery.md	artists, stars, discographies, new releases
docs/playback.md	playing through cliamp
docs/themes.md	the four palettes, ^t, and defining your own
docs/keys.md	every key, both screens, the status words
docs/internals.md	how tagging decides, what gets written

Who it's for

People who download playlists and then rename the files by hand. earworm doesn't delete anything you didn't ask it to, shows you when it isn't sure about a tag, and answers --list and --check in plain text so scripts can use them too.

Licence

MIT or Apache-2.0, at your option.