lintunes/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this is

LinTunes is an iTunes-replacement music library manager and player for Linux, built with PyQt6 / Qt Multimedia. It imports an iTunes 12 library, stores the library as plain JSON (syncable via Syncthing), and reproduces the iTunes UI (left sidebar + right playlist view, column browser, customizable per-playlist columns). spec.md is the original design brief; TASKS.md is the live backlog and tasks-done.md records completed work.

Commands

pip install -e .                 # install deps (PyQt6, mutagen, numpy, requests)
python3 -m lintunes.main         # run the app straight from the checkout
python3 -m pytest                # run the whole test suite
python3 -m pytest tests/test_round9.py            # one test file
python3 -m pytest tests/test_round9.py::test_name # one test

The app needs a --data-dir; config persists to ~/.config/lintunes/config.json. One-time iTunes import:

lintunes --import-xml "iTunes Library.xml" \
         --music-root "/path/to/iTunes Media" \
         --data-dir /path/to/library-data --save-config

Runtime needs FFmpeg codecs for Qt Multimedia (qt6-qtmultimedia w/ ffmpeg). Tests run headless via the qapp fixture in tests/conftest.py (QT_QPA_PLATFORM=offscreen).

Architecture

Data flows in one direction through three layers: storage (JSON on disk) → model (Library/Track/Playlist dataclasses) → LibraryManager (mutations + persistence) → GUI (Qt widgets that read the manager and connect to its signals).

• lintunes/main.py — CLI entry. --import-xml runs a headless import and exits; otherwise run_gui() resolves Syncthing conflicts, loads the library, builds Preferences/LibraryManager/LastFm/MainWindow, wires MPRIS, and installs the window as a global event filter (for media keys).

• lintunes/models/ — pure dataclasses (track.py, playlist.py, library.py) with to_dict/from_dict round-tripping. PlaylistType is REGULAR | FOLDER | SMART | SYSTEM. Per-playlist PlaylistSettings holds visible columns / sort column / widths. Playlists are identified by an 8-char hex persistent_id (folder containment via parent_persistent_id).

• lintunes/storage/json_storage.py — the library is multiple files in the data dir: library.json (all tracks), library_metadata.json, one playlists/<persistent_id>.json per playlist, and one plays/<machine-id>.json per machine. Writes are atomic (*.json.tmp → rename). storage/conflict_resolver.py merges Syncthing *.sync-conflict-* files on startup: play counts take the max, edited fields take the newest, playlist membership takes the union except where a removal was recorded (Round 44, see tombstones.py). Since Round 39 that union is anchor-based (merge_track_order): a track only one copy has is re-inserted after the nearest track both share, not appended at the tail, so a middle insert stays in the middle. Whose order wins is decided by Playlist.date_modified, not by the file's mtime, which moves for cosmetic reasons. Since Round 43 a stamped copy also beats an unstamped one (a stamp exists only once LinTunes recorded an edit, so that is real evidence); mtime is the fallback only when neither side has ever been edited. Two rules follow: a merge that changes nothing writes nothing (an unconditional write reset the kept file's mtime and biased that fallback a little more every round), and a merge whose result is a union neither copy had stamps date_modified — that content is newer than both, and saying so is what stops two machines trading the same tracks back and forth. library_manager._reconcile_playlist is the same decision on the live-reload path and must read the stamps too; it is reached only for playlists in _dirty_playlist_content (real content edits), never for one that is merely cosmetically dirty from a column drag. Since Round 42 every ConflictSummary carries a level (WARNING / CHANGE / INFO): a merge that only reconciled column widths, or a smart playlist whose rules are byte-identical on both sides, is INFO and must never read as an edit the user made. The dialog (gui/conflict_dialog.py) shows one level and above and opens at the highest level in the batch, so a routine merge never steals focus but a blank window is impossible either. Round 43 made the summaries say something actionable: which copy won and when it was edited, who wrote the copy Syncthing set aside (the 7-char device token in the conflict filename, named via sync_identity.py), and every re-inserted track by Artist — Title and position — six in the window, all of them in what-changed.txt at the top of the backup snapshot. Never label a copy "this machine" from which file holds the plain name: that is Syncthing's choice, and it sets the local copy aside as readily as a remote one.

• lintunes/storage/play_journal.py — why play counts can't conflict. Since Round 38 library.json holds only a base count and each machine owns plays/<machine-id>.json with its own per-track totals; effective count = base + the sum of every journal. Only the owner ever writes its journal, so two machines never touch the same file — and finishing a track no longer rewrites 15 MB, which is what handed Syncthing a conflict once per song. Totals, not an append log, so there is no compaction step to double-count in. PlayJournal.load() must be handed a library whose tracks still carry base counts (the fresh load at startup, the disk copy inside reload_from_disk) — folding an already-folded library promotes the effective count to base. Mirror-image rule in json_storage.save_tracks(): it writes journal.base_fields(tid), never the Track's effective count. Those two places are the whole hazard; tests/test_round38.py pins both.

• lintunes/library_manager.py — LibraryManager(QObject) owns the Library, is the single funnel for all mutations, and persists them debounced (3 s) with per-area dirty tracking (a play-count bump rewrites only library.json; a playlist edit rewrites only that playlist file). User edits go through undo_stack (Ctrl+Z); the internal _apply_*/_set_* helpers do the real mutation + dirty-mark + signal and are reused by undo/redo without recursing. Widgets react to its signals (playlists_changed, playlist_content_changed(pid), track_updated(id), track_fields_edited).

• lintunes/player.py — Player(QObject) walks a queue through a swappable PlaybackSink. Player owns the queue, shuffle walk, per-track start/stop times and the play-count/scrobble bookkeeping; a sink owns only "make this file come out of something, and report where it's up to". LocalSink (the QMediaPlayer/QAudioOutput pipeline, with the QAudioBufferOutput PCM tee that feeds the visualizer) stays in player.py — the Player tests stub Qt Multimedia with patch.multiple(player_module, QMediaPlayer=..., …), so those names must resolve in this module. cast/sink.py::CastSink is the other implementation. set_sink() carries the current track, position and playing-state across a swap and deliberately does not re-emit track_changed (that would double-scrobble the same song). Player is also deliberately context-agnostic: playback context ("library" / "playlist:") is tracked in MainWindow, not the player.

• lintunes/gui/ — main_window.py assembles a top TransportBar over a horizontal QSplitter (SidebarPanel | stacked LibraryView/PlaylistView). track_table.py is the shared track grid (drag/drop, copy/paste, drop indicator). playlist_ops.py::add_tracks_with_dup_check is the single funnel for every add-to-playlist path. theme.py applies the palette (highlight colors, UI scales) from prefs.

• lintunes/importers/itunes_importer.py — parses the iTunes XML plist. Remaps Mac file:///Volumes/... paths to the local --music-root with case/Unicode-normalization fuzzy matching (macOS is case-insensitive + NFD vs ext4). Imports user playlists, folders and smart playlists (criteria parsed by smart.parse_itunes_smart; criteria it can't model are kept as a static snapshot — report.smart_unsupported). System playlists are skipped (report.skipped_system). Album art is read live from embedded ID3 tags (tagging.py), never stored in the library JSON.

• lintunes/preferences.py — app settings in <data_dir>/preferences.json (rides the same Syncthing share). Preferences.set(key, value) saves and emits changed; MainWindow._on_prefs_changed re-applies theme/metrics live. Because it is synced, anything machine-specific belongs in config.py's config.json instead (see music_folder.py). now_playing_font has three states — None automatic (best available from theme.NOW_PLAYING_FALLBACKS), "" the app font, or an explicit family. Startup never prompts for it; the row in Preferences is the only place it's chosen.

• lintunes/music_folder.py — where the organized tree lives on this machine. The library stores it three ways (models/library.py): music_folder absolute (what pre-0.10 code reads — kept forever as the shared floor between versions), music_folder_rel relative to the data dir (the portable one, same trick as Track.location), and music_folder_set_at, a stamp so a merge prefers the newest setting rather than the newest file. resolve() tries rel → legacy → the per-machine override in config.json (both music_folder_override and the older music_root that --music-root … --save-config writes — an imported library already knows where its music is on this machine, so don't ask), and every candidate must exist — the override is consulted last so a machine that once needed one isn't pinned to it forever. Two rules that bite: LibraryManager.set_music_folder must call mark_library_settings_dirty() (without it reload_from_disk reverts the change on the next sync tick), and organize_root() can return None, which every caller must handle rather than inventing a relative path — MainWindow._music_import_dir used to fall back to Path("Music"), which resolved against a working directory GNOME's dash doesn't set predictably.

• lintunes/tombstones.py — why a deletion sticks. Two copies with no common ancestor cannot tell "A added this" from "B removed it", which is why every merge was a union — and why a song removed on one machine came back from the other forever. So removals are recorded: Playlist.track_events ({track id: [when, "add"|"remove"]}) and Library.deleted_tracks ({track id: when}, in library_metadata.json). A merge takes the newest event per track across both copies and applies it, so a removal beats a copy that merely still had the song and a later re-add beats the removal; a track with no event still merges as a union. Events are recorded in the same single funnels as everything else — _set_track_ids for playlists, _remove_tracks for the library — and pruned after RETENTION_DAYS (30) at the save boundary, so a machine offline longer than that can resurrect something. Three rules: track ids are never reused (_highest_track_id counts deletions, or a new track would be dropped on sight by the dead id's own tombstone), library_metadata.json is merged before library.json (it carries the record the library merge is filtered against — resolve_conflicts sorts for it), and a merge applying a deletion never touches a music file; it only drops the library entry, and reports at WARNING.

• lintunes/sync_identity.py — turns a conflict filename's 7-char device token into a device name, by reading Syncthing's config.xml and deriving our own device ID from cert.pem (base32 of the SHA-256 of the DER cert). Stdlib only, cached, and every failure path returns None — a machine with no Syncthing must still merge, just without naming anyone.

• lintunes/mpris.py — registers org.mpris.MediaPlayer2.lintunes over D-Bus so the desktop's media keys / now-playing popup control playback. Spacebar and arrow keys are handled locally via MainWindow.eventFilter.

• lintunes/trash.py — freedesktop.org Trash spec 1.0, hand-rolled (no new dep). The trash is per-filesystem: music usually lives on a mounted volume, so the file belongs in <topdir>/.Trash-<uid> with a topdir-relative, percent-encoded Path=, not in ~/.local/share/Trash (which would be a cross-device copy the file manager can't "Restore"). The .trashinfo is created with O_EXCL first to claim the name atomically, then the file is renamed in; a failed rename unlinks the info file so there's never a half-trashed pair. Raises TrashError without touching the file, so a caller can treat failure as "not deleted". Only LibraryManager calls it.

• lintunes/device_sync.py — one-way playlist sync to the Rabbit R1 (Device menu). The Rabbit mounts via MTP/gvfs (a FUSE path under /run/user/<uid>/gvfs), not mass storage — so plain file I/O, but never copystat and never trust mtimes (diff by name+size). Sync owns exactly Music/<Playlist Name>/ on the device (creates/overwrites/deletes there, plus an Auxio-importable .m3u); it never deletes outside that folder and only ever reads local library files.

• lintunes/export/ — File → Export Playlist… (also on a playlist's right-click menu). A sibling of device_sync, reusing its filename helpers and build_m3u: pure plan_export() first, then ExportWorker on a daemon thread. Two destinations — a folder (files as Artist - Title.ext plus an .m3u) or a web mix (index.html + audios/ + hero image, from templates/; no m3u — it's a folder you upload, not one you open in a player, so plan.m3u_name is "" there). The manifest is written last, so an interrupted export never leaves a page or m3u naming files that aren't there. web_support.py is the format gate, shaped like cast/support.py: deny-by-default on the suffix with the iTunes kind breaking the .m4a tie. Bitrate never triggers a conversion — only unplayability does — and every conversion targets FLAC, so it can't cost a bit; DRM'd tracks are reported, never attempted. ffmpeg is the CLI binary here (not Qt's ffmpeg backend), so it's detected at runtime and its absence is offered as "export without them". The templates ship a ~180-line dependency-free player.js/player.css that replaced audio.js + jQuery (abandoned since 2012; jQuery was only ever glue — audio.js never used it). player-graphics.gif must ship byte-identical: it's an animated GIF whose loading frame is a spinner, not a flat sprite sheet — which is why Round 41 recolors its pale glyphs to black with filter: brightness(0) in CSS rather than editing the file. The one user-chosen color (link/row hover backgrounds + the progress fill) travels as a :root { --accent } custom property declared in index.html, so player.css can read it while staying a verbatim shutil.copyfile — the page is still the only rendered template. exporter.normalize_accent is a hard gate, not politeness: the value lands raw inside a <style> block and string.Template escapes nothing. The accent is not persisted, so an untouched export still renders the original #8c764a. Templates are registered in setup.py via package_data; loaded with importlib.resources so an installed copy finds them.

• lintunes/cast/ — Chromecast playback (Connections menu), using the media-receiver model: server.py runs a ThreadingHTTPServer on an ephemeral port for the life of a session and the device fetches the original file itself (bit-exact, no transcode). URLs carry an opaque random token, never a path, so traversal is structurally impossible; Range + HEAD are mandatory (the device seeks by re-requesting ranges and won't report a duration without them). A token resolves to an _Asset that is either a file on disk (audio) or an in-memory blob (album art, which lives in tags rather than as its own file); the two have separate eviction rings so a cover can't push out the previous track's audio. Art is passed as play_media(thumb=…), which pychromecast folds into metadata["images"] — that's what a TV paints full-screen. support.py is the format gate — ALAC, AIFF and protected AAC are refused and Player skips them with a status-bar message. discovery.py wraps CastBrowser; sink.py is the PlaybackSink; controller.py owns the session and its own SleepInhibitor. pychromecast is imported lazily, never at module scope, so the app still launches where the dep isn't installed yet. While casting there is no local PCM, so the visualizer panel doubles as the cast indicator: it shows the cast glyph instead of bars and a click there stops casting (the brightness cycle is suppressed — it means nothing with no bars). That is the only cast control in the transport bar. Position comes from a 500 ms poll of adjusted_current_time (only trusted while PLAYING — it creeps while paused).

Conventions & gotchas

• Tests are organized as tests/test_roundN.py — each development round adds a new test_roundN.py alongside the topical files (test_models.py, test_itunes_importer.py, etc.). New feature work follows the same pattern.

• Keep Player and track_table manager-free where they already are — cross-cutting data is injected via callbacks/signals (e.g. track_table takes a playlists_for_track callback rather than importing the manager).

• Cosmetic table settings must not look like edits. The last column is stretch-sized, so Qt re-fires sectionResized for it on every viewport width change; track_table._on_section_resized ignores that section, or resizing the window would rewrite the open playlist's JSON (and hand Syncthing a conflict) purely for a width apply_settings overrides on load anyway. Round 42 is the same rule one level down: a live smart playlist's membership is never persisted (Playlist.has_derived_membership gates it in json_storage.save_playlist, which writes track_ids: [] + derived_membership: true) and recompute_smart_playlist passes touch=False to _set_track_ids so it marks nothing dirty and moves no timestamp. Membership is rebuilt from the criteria on every load (recompute_all_smart), so storing it only bought a conflict per song — one per finished track, on the same file, from both machines. The exceptions are live_update=False and unsupported criteria: their track_ids are the content (a snapshot), so they still persist and still count as edits.

• Qt/Wayland gotchas (GNOME/Mutter): QDrag.setPixmap / setDragCursor / QCursor.pos() are unreliable during a drag — gui/drag_ghost.py paints its own child-widget overlay instead. QAudioOutput must not be constructed before a QMainWindow exists (Qt 6.10 deadlock). Some PyQt signal relays need explicit types/lambdas.

• Music files are only touched deliberately: tag edits via tagging.py, and — since Round 18 — artist/album_artist/album edits relocate the file inside LibraryManager.organize_root() (<music_folder>/Music) to keep the tree organized iTunes-style (_maybe_move_file; undoable; files outside the root are never moved; the new path syncs cross-machine via the location newest-wins merge in conflict_resolver). Since Round 33 the only other path is an explicit user delete (LibraryManager.delete_tracks), which moves the file to the desktop trash via trash.py — never unlink, so it stays recoverable. Nothing else may move, rewrite or remove music files. The library JSON is the source of truth for everything else.

• Versioning & self-update: __version__ in lintunes/__init__.py is the single source of truth (setup.py regex-reads it, never imports the package). Claude bumps minor for feature rounds and patch for fix-only rounds as part of each round's final commit; trav decides major bumps. The status-bar version button (gui/version_button.py + lintunes/updater.py) checks origin shortly after launch and every 4 h, and a click runs git pull --ff-only then re-execs the app — pushing master is effectively releasing to the other machines (a new pip dependency still needs a manual pip install -e . there). Every round ends with commit AND push (trav's standing request, 2026-07-03: both machines ride the bleeding edge, sync as often as possible) — so never leave master in a half-working state between commits you push.

• scripts/ holds one-off maintenance tools (audit_artwork.py, recover_artwork.py, clear_computed_ratings.py) run manually against a data dir; most default to dry-run and need --write to mutate files.

• Not under version control until recently — the *~ files are editor backups (gitignored). data/ and itunes-test-library/ are gitignored (the user's real library + large import fixture).