LinTunes

Lintunes is an mp3 library manager and player for linux. Absolutely no guarantees, if it wrecks your itunes library or wipes your harddrive that's on you (maybe just have your LLM of choice review the software for bugs if you're worried). FWIW I've been using it for months without major issues.

A lot of these docs were written by LLM but I've tried to clean them up a bit!!

why I did this

I've been a mac user for ~34 years. I gave up daily driving a mac in 2021 but kept my music library in itunes. After 5 years I got tired of my music being solely on my desktop. But I couldn't find anything with all the features of itunes I wanted and also with the ability to import my 26 year old mp3 library. So.

Quick start even if you're not a big comp guy

(written by LLM, cleaned up by me)

1. Open a terminal. Press the Super key (probs the one with the Windows logo), type terminal, press Enter.

Paste each command below with Ctrl+Shift+V (plain Ctrl+V doesn't work in a terminal), then press Enter. If it asks for your password, type it — nothing shows while you type, that's normal.

2. Install what LinTunes needs.

If you're not sure which distro you're on try the Debian one. If it balks like sudo: apt: command not found, try the Fedora one.

# Debian / Ubuntu / Mint
sudo apt install git python3-pyqt6 python3-pyqt6.qtmultimedia python3-mutagen python3-numpy python3-requests

# Fedora
sudo dnf install git python3-pyqt6 qt6-qtmultimedia python3-mutagen python3-numpy python3-requests

3. Download LinTunes

cd ~
git clone https://git.autonomic.zone/trav/lintunes.git
cd lintunes

4. Add it to your app menu and start it:

This will setup LinTunes to create a folder inside your Music folder where it'll keep your music organized.

bash packaging/install-desktop.sh
mkdir -p ~/Music/lintunes
python3 -m lintunes.main --data-dir ~/Music/lintunes --save-config

Now you can open LinTunes from your app menu like any other app. Now you're running LinTunes! You can drag music in and it'll copy it into the ~/Music/lintunes folder and keep it organize (make sure you have enough ssd space to store your music).

If you see a little asterix in the bottom-left next to the version number it means there's a software update. Click that number and it'll do the update.

Window opens but nothing plays? Your system is missing audio codecs. On Fedora, enable RPM Fusion, then run sudo dnf swap ffmpeg-free ffmpeg --allowerasing.

Keys

(written by LLM, cleaned up by me)

• Space play/pause · ←/→ previous/next
• Ctrl+B column browser
• Ctrl+I get info for currently selected track
• Ctrl+L go to current song
• Ctrl+O add files
• Ctrl+N new playlist (Ctrl+Alt+N smart, Ctrl+Shift+N folder)
• Ctrl+Z undo
• Ctrl+, preferences
• Ctrl+C/Ctrl+X/Ctrl+V copy/cut/paste tracks
• click sidebar art for a big art window

Sharing music with friends (Cassette)

Cassette lets you subscribe to friends' playlists, peek at their libraries and download their songs via a program called Syncthing.

1. Install and start Syncthing (once)

Open a terminal and paste the line for your distro:

sudo apt install syncthing        # Debian / Ubuntu / Mint
sudo dnf install syncthing        # Fedora

Then start it, and have it start by itself every time you log in:

systemctl --user enable --now syncthing

To check it's running, open http://127.0.0.1:8384 in your web browser — you should see Syncthing's page. You don't have to do anything there; the default settings (including "global discovery" and "relaying", which let two computers find each other across the internet) are exactly right.

Already using Syncthing to keep your library on two of your own computers? Great — nothing changes. Only one of your computers handles friends; LinTunes asks which the first time (see below), and songs it brings in reach your other computers the usual way.

2. Connect with a friend

One of you invites, the other pastes. It doesn't matter who.

If you're inviting: in LinTunes choose Connections ▸ Share Library with a Friend…. The very first time, LinTunes asks "Use this computer for sharing with friends?" — say Yes. You'll get an invite code: a long line starting with LTC1. Press Copy Code and send it to your friend however you like (text, email, chat). Each code works for one friend, once.

If you were sent a code: choose Connections ▸ Add Friend Library…, paste the whole code into the box, and press Connect.

That's it. When the two computers have found each other, you'll see "Name is now connected." at the bottom of the window. This can take a minute — or, if the other computer is off, however long until it's back on.

You can see how it's going any time in Connections ▸ Sync Settings…: pick your friend in the list on the left. Invites nobody has used yet are listed on the General page, with a Cancel Invite button each.

3. Choose what your friend can see

Nothing is shared until you say so. In Connections ▸ Sync Settings…, click your friend's name on the left. Below their connection status are two sections:

• Library — tick the artists, albums or songs your friend may ask for, or tick Share whole library for everything (including songs you add later).
• Playlists — tick the playlists to share, or Share all playlists. A shared playlist brings its songs along: they show up ticked and greyed in the Library section (hover one to see which playlist is holding it there).

Select All and Select None do what they say — and if you click one by accident, just press Cancel: nothing is saved until you press OK.

Want everyone to see the same thing? On the General page, tick Share the same selection with all friends and choose there instead.

Sharing something doesn't send it. Your friend only receives what they ask for.

4. Browse a friend's library and ask for songs

Once you have a friend, a small ▾ appears on the right end of the Library button:

Click the ▾ and pick your friend. The button turns light purple and shows their library's name — you're now looking at what they've shared with you:

It works just like your own library, except nothing plays (the songs aren't on your computer yet). Instead, every artist, album and song has a little cassette button:

Button	What it means
	Not asked for. Click it to ask your friend for this.
	Asked for — this song is on its way to you. Click again to change your mind.
	Some of this artist's or album's songs are asked for. Click to ask for all of them.

Pressing the button on an artist or album asks for every song under it.

Along the bottom of the window:

• Hide tracks I have hides songs you already own. Songs that are probably the same as one of yours (same artist and title, different album or length) stay visible in light grey so you can decide.
• The size of what you've asked for, next to your free space. It turns orange if it would leave so little space that Syncthing pauses, and red if it won't fit at all.
• Save and Close sends your list to your friend and takes you back to your own library. Cancel forgets the changes. (Leaving any other way with changes asks "Save changes?" first.)

The songs you asked for arrive in your library by themselves, filed by artist and album like anything you'd add yourself, with "3 songs arrived from Sam." at the bottom of the window. They come with their names, album info and artwork — but not your friend's play counts or ratings.

5. Follow a friend's playlist

In a friend's library, their shared playlists are listed on the left, each with a UFO. Click a playlist's UFO to follow it:

Icon	What it means
	Not following. Click the UFO to follow this playlist.
	Following. Click again to stop.

Press Save and Close, and the playlist appears in your sidebar with a purple UFO, and plays like any other playlist:

• Songs that are still on their way show in grey; they become playable as they arrive. The bottom of the window says when your friend's folder last synced.
• A followed playlist's songs are kept separate from your library — you get to listen without them filling up your collection. Like one? Right-click the column headings, turn on Cassette, and press its cassette button to add it to your library.
• Right-click a followed playlist in the sidebar and choose Unfollow to let it go (its songs are cleaned up afterwards).

Two choices per friend, in Sync Settings on their page:

• Show followed playlists mixed in with yours, or grouped in a folder with their name.
• Keep their songs separate (the default), or add them to your library automatically.

If something isn't working

Sync Settings always says what's going on in plain words and what to do next. The common ones:

• "Syncthing isn't running" — run systemctl --user start syncthing, then press Retry on the General page.
• "Can't reach Syncthing's API" — press Read from Syncthing on the General page. (Or copy the key from Syncthing's page at http://127.0.0.1:8384: Actions ▸ Settings ▸ General ▸ API Key.)
• "Waiting for Name's computer" for a long time — both computers need to be on with Syncthing running, and your friend needs to have opened LinTunes once since you pasted the code. If it never connects, the code may already have been used: ask for a new one.
• "That code isn't valid" — part of the code got lost when it was copied. It's one long line starting with LTC1.; ask your friend to send it again.
• "This invite has already been used" — codes work once. Ask for a new one.

To stop sharing with someone, open their page in Sync Settings and press Remove Friend…. Songs you already brought into your library stay.

Full Features list

(written by LLM and cleaned up a bit by me)

Library

• Sortable track list with 24 optional columns (plays, skips, rating, BPM, bit rate, date added…) — column choice, sort and widths are remembered per playlist.
• Keeps track of date song was last played
• Column browser (Ctrl+B) — filter by genre / artist / album.
• Instant search over name, artist, album, composer and more.
• Get Info (Ctrl+I) edits tags on one track or a whole selection at once, writing them back to the file. Artwork can be pasted, dragged in, or fetched automatically (Download Album Art…, via the iTunes Search API).
• Rename an artist or album and the files move themselves into a tidy Artist/Album/ tree.
• Undo/redo everything (Ctrl+Z / Ctrl+Shift+Z) — edits, deletes, reorders.
• Deleting a track sends the file to your desktop Trash, never rm.
• Identify Track… listens to a song (Chromaprint + AcoustID) and proposes its real title, artist, album and original release year — and when the internet has never heard of it, reads the answer out of the filename.
• Import from URL… (File menu) — paste a link and the song is downloaded (yt-dlp), filed, and handed straight to Identify Track.
• Album art is searched on both iTunes and Deezer, can be pasted onto a whole album's worth of tracks at once, and clicking the blank cover in the sidebar goes looking for it.
• Right-click any song to look it up on YouTube.
• Every song you add is stamped with the day you added it.

Playlists

• Regular playlists, folders, and smart playlists (auto-updating, with a full rule editor).
• Drag and drop to reorder or insert at a spot; duplicate-aware adds; copy/cut/paste tracks between playlists.
• Click a selected playlist's name to rename it.
• New libraries start with a New Tracks smart playlist (everything added in the last 3 months).

Playing

• mp3, m4a, flac, aac, wav, aiff.
• Shuffle, per-track start/stop times, play counts, skip counts and ratings.
• Media keys work, plus Space and ←/→ anywhere in the app.
• Live spectrum visualizer — click it to cycle bright / dim / off.
• last.fm scrobbling
• Theming: highlight color, UI scale, and custom colors
• A soft emboss on every button that follows your custom colors.

Sending music elsewhere

• Chromecast
• Export a playlist (File ▸ Export Playlist…) — either a folder of Artist - Title.mp3 files plus an .m3u, or a self-contained index.html you can upload anywhere.
• Sync a playlist to a Rabbit R1 over MTP, .m3u included.
• andTunes, a small music player for the Rabbit R1 that LinTunes installs and fills from the Connections menu — and the plays you rack up on the Rabbit come back into your library.

Living on more than one machine

• The whole library is plain JSON, designed to be synced with Syncthing. Sync conflicts merge themselves on startup.
• The version number in the status bar checks for updates (via git) and you can click it to update to the latest version.
• Play counts can never conflict (each machine keeps its own tally), a song you remove on one machine stays removed, and the merge report only speaks up when something you'd care about happened.

Sharing with friends (Cassette)

• Share parts of your library with a friend — one pasted code connects you, over Syncthing, with no server anywhere.
• You choose exactly what each friend can see: the whole library, or just certain artists, albums, songs and playlists.
• Browse a friend's library and press the little cassette buttons on anything you'd like; those songs arrive in your library by themselves.
• Follow a friend's playlist and play it right from your own sidebar.

\

BUT WAIT, THERE'S MORE

there's a file extra-docs.md with more documentation that might be handy if you have more questions