trav/lintunes
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

trave cleaned up the readme

Browse Source
This commit is contained in:
trav
2026-10-01 23:57:25 -07:00
parent 5edc3bded2
commit f78330c9ee
1 changed files with 109 additions and 142 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+109 -142
View File
@@ -2,100 +2,24 @@
![LinTunes](screenshot.png)
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.
## trave notes
#### why I did this
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 and vulns?).
I have been a mac user for ~34 years. I gave up daily driving mac os in 2021. After 5 years I got tired of my music being solely on my desktop so I vibe-coded this replacement with all the features I wanted from iTunes.
# docs written by llms and cleaned up by me:
## Features
**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](https://syncthing.net). 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](https://syncthing.net), 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.
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
## Quick start (written by LLM, cleaned up by me) even if you're not a big comp guy
**1. Open a terminal.** Press the Super key (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.
**1. Open a terminal.** Press the Super key (probs the one with the Windows logo),
type `terminal`, press Enter.
**2. Install what LinTunes needs.** Paste the line for your Linux (not sure?
it's probably Ubuntu or Mint):
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.
```sh
# Debian / Ubuntu / Mint
@@ -107,7 +31,7 @@ sudo apt install git python3-pyqt6 python3-pyqt6.qtmultimedia python3-mutagen py
sudo dnf install git python3-pyqt6 qt6-qtmultimedia python3-mutagen python3-numpy python3-requests
```
**3. Download LinTunes** into a `lintunes` folder in your home folder:
**3. Download LinTunes**
```sh
cd ~
@@ -115,30 +39,41 @@ git clone https://git.autonomic.zone/trav/lintunes.git
cd lintunes
```
(That link is the **HTTPS** address from the clone box on the project page —
if you copy it yourself, pick HTTPS, not SSH.)
**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.
```sh
bash packaging/install-desktop.sh
mkdir -p ~/Music/lintunes
python3 -m lintunes.main --data-dir ~/Music/lintunes --save-config
```
It asks once where to keep your music (`~/Music` is fine). Add songs with
**File ▸ Add Files to Library**, or drag folders onto the window. From now on,
open LinTunes from your app menu like any other app.
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).
Coming from iTunes? Replace the last line with the one in
*Importing an existing iTunes library* below.
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.
**Updating:** click the version number at the bottom of the window.
**Window opens but nothing plays?** Your system is missing audio codecs. On
Fedora, enable [RPM Fusion](https://rpmfusion.org/Configuration), 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
# Some LLM docs:
## Mac or Windows?
LinTunes is only built and tested on Linux and
@@ -191,26 +126,6 @@ exactly what the desktop launcher does.
Below, `lintunes` and `python3 -m lintunes.main` are interchangeable — use
whichever your install gave you.
## Starting from scratch (no iTunes needed)
Tell it where to keep the library, once:
```sh
mkdir -p ~/Music/lintunes # the library lives here
lintunes --data-dir ~/Music/lintunes --save-config # remembers it from now on
```
Then just run `lintunes`. The first time it opens, it asks one question — where
to keep your music — and suggests `~/Music`. Pick a folder, or click **Not
Now** and set it later in **Edit ▸ Preferences**.
Now add music: **File ▸ Add Files to Library** (Ctrl+O), or drag files and
folders straight onto the window. Whole folders are fine.
Your songs are **copied** into the folder you chose and filed by artist and
album.
## Importing an existing iTunes library
In iTunes 12.x: **File ▸ Library ▸ Export Library** to get the XML, then:
@@ -229,23 +144,6 @@ case/accent differences. Anything it couldn't find is written to
`import_missing_files.txt` in your data dir. Untested on iTunes versions other
than 12.
## Running it
```sh
lintunes # uses the saved config
```
The desktop launcher runs LinTunes with no arguments, so it always uses whatever
is saved in `~/.config/lintunes/config.json`
## Keys
Space play/pause · ←/→ previous/next · Ctrl+B column browser ·
Ctrl+I get info · 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 ·
double-click sidebar art for a big art window
## Running on a second machine (Syncthing)
@@ -275,7 +173,9 @@ bash packaging/install-desktop.sh
also create that file by hand. After it's saved, every launch, including the
dock icon, uses the synced library automatically.)
## App icon
## App icon (written by LLM, cleaned up by me)
You can change the app icon if you want.
`packaging/install-desktop.sh` installs the launcher entry and icon for your
user (lets you pin LinTunes to the GNOME dash). The icon is just a file —
@@ -286,13 +186,6 @@ Unpinning from the dash does **not** uninstall LinTunes — it's still in the
GNOME app grid (open Activities and search "LinTunes"). Right-click it there →
**Pin to Dash** to get it back.
## Development
```sh
python3 -m pytest tests/
```
`spec.md` is the original design brief; `tasks*.md` track what's built.
## Sharing music with friends (Cassette)
@@ -466,3 +359,77 @@ The common ones:
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](https://syncthing.net). 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](https://syncthing.net), 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.