Return or a double-click on a song started the regular player behind the decks, with its controls greyed out and no way to stop it. DJ mode now suspends the player. Sync to other track was only re-enabled when its own deck changed, so loading the other deck afterwards left it grey; it's now enabled whenever its deck has a song and explains what it can't do.
1066 lines
73 KiB
Markdown
1066 lines
73 KiB
Markdown
# 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 live on the kanban board at
|
||
`~/Documents/projtracker/projects/lintunes/` (use the `tasks` skill); the old
|
||
`TASKS.md`/`tasks-done.md` are archived there — don't recreate them.
|
||
|
||
## Commands
|
||
|
||
```sh
|
||
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:
|
||
|
||
```sh
|
||
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/storage/listen_history.py`** — the yearly Wrapped's raw data
|
||
(Round 74). The journals keep *totals*, which can't say "top songs of
|
||
2026", minutes listened, month or time of day; this keeps **one line per
|
||
listen** in `<data_dir>/history/<machine id>/<YYYY-MM>.jsonl` — the
|
||
journals' owner-only-writer rule, append-only, a finished month never
|
||
changes. `t` is *local* time with its offset (time-of-day is the listener's
|
||
clock); `ms` is time actually **heard** — `Player._account_heard` adds
|
||
position steps of 0–1.5 s, so seeks and pauses don't count; `end` is
|
||
finish/skip/stop/quit; the artist/album snapshot outlives a delete or
|
||
retag. Under 5 s is noise and never written. Only while the synced pref
|
||
`wrapped.track_history` is on: `Player.listen_ended` → `MainWindow` (adds
|
||
`src` desktop/cast/airplay and `ctx`, which it latches at `track_changed` because
|
||
`_now_playing_context` moves before the old listen closes) →
|
||
`LibraryManager.record_listen`, flushed with the journal. The Rabbit writes
|
||
the same lines (`History.java`) only when sync put `"history": true` in its
|
||
`library.json`; `andtunes/plays.bring_back_history` copies a month home when
|
||
the device's copy is longer (two desktops can both do that, hence the
|
||
union merge in `conflict_resolver._merge_listen_history`).
|
||
`cassette/wrapped.py` puts this year's **trimmed** log
|
||
(`trim_for_sharing`: no id/ctx/src/shuf) in every friend's `out/` as
|
||
`wrapped-<year>.json` when `wrapped.share_with_friends` is also on —
|
||
checked hourly by `CassetteUi`, written daily in Nov–Dec and monthly
|
||
otherwise, never rewritten when the plays didn't change. No Wrapped page
|
||
yet: that's built after Spotify's 2026 one drops, plus a Last.fm backfill
|
||
for Jan–Sep (scrobbling is on; the R1 never scrobbled).
|
||
|
||
- **`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`).
|
||
|
||
- **Per-track volume** (Round 79): `Track.volume_adjustment` is iTunes'
|
||
"Volume Adjustment", imported as-is (±255 = ±100%) and edited in Get Info.
|
||
`player.volume_with_adjustment` scales the slider's *perceptual* level by
|
||
it: −100% is silence, and a boost can't pass full. `Player` applies it
|
||
through `_output_volume()` everywhere it pushes volume to a sink, before
|
||
each load, and on `refresh_volume()` (MainWindow calls that when the
|
||
playing track is edited). `Player.volume()` stays the bare slider value.
|
||
|
||
- **Volume normalization** (Round 83, `loudness.py`, Controls → Normalize
|
||
Volume / Preferences → General): each file's EBU R128 integrated loudness
|
||
from the `ffmpeg` CLI's `ebur128` (~0.4 s a song), cached by path + size +
|
||
mtime in `$XDG_CACHE_HOME/lintunes/loudness.json` (machine-local, never
|
||
the synced dir). `Player` turns `TARGET_LUFS − measured` into a dB gain in
|
||
`_output_volume` (`volume_with_gain`, linear amplitude through Qt's own
|
||
volume curve, capped at full). The playing song is measured urgently and
|
||
the next `LOOKAHEAD` ahead; an unmeasured one starts at the cache's median
|
||
and **glides** (never jumps) to its own gain. No DSP, no tags: Qt's
|
||
pipeline has no insert point, and none is needed.
|
||
|
||
- **`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).
|
||
**Repeat** (Round 88, the transport's button, off → all → one) lives in
|
||
`Player`: repeat-all wraps `_step_index` both ways (a shuffled walk is
|
||
reshuffled for each lap, never starting with the song that ended the last),
|
||
repeat-one replays only a song that *finished* (`_after_finish`) — Next and
|
||
Previous still move — and `_load_current`'s unplayable-skip loop gives up
|
||
after one lap, since a wrapping walk would otherwise never end.
|
||
Player is also deliberately **context-agnostic**: playback *context*
|
||
("library" / "playlist:<pid>") is tracked in `MainWindow`, not the player.
|
||
|
||
- **`lintunes/gui/`** — `main_window.py` assembles a top `TransportBar` over a
|
||
horizontal `QSplitter` (`SidebarPanel` | stacked `LibraryView`/`PlaylistView`).
|
||
The bar's second row (`transport.HeaderRow`, placed by hand) holds three
|
||
things owned elsewhere: the sidebar's Library button (`SidebarPanel.header`,
|
||
kept edge to edge with the playlist list — `list_area`, scrollbar included —
|
||
via `track_split`), the shown view's `header` (search box, playlist name —
|
||
mounted on the content stack's `currentChanged`, returned to its view when
|
||
it goes), and the seek row, exactly under the now-playing panel. Everything
|
||
in it stands on one floor (`HeaderRow.BOTTOM` above the lists): boxes by
|
||
their bottom edge, text by its baseline. The row of boxes above floats —
|
||
equal space before, between and after the controls, with the panel a fixed
|
||
share of the width. Since the Library button left the
|
||
sidebar, `MainWindow` must hand it the first focus, or the playlist tree
|
||
takes it and opens its first playlist at startup.
|
||
The transport-bar visualizer tile (`gui/visualizer.py`, Round 86): a
|
||
click opens it big, and while big the tile stays blank; hovering paints
|
||
two controls over it — a colour wheel (left: colour / gray / off) and ▲/▼
|
||
(right: previous/next style, wrapping) — hit-tested on release. No
|
||
double-click. Both big windows (visualizer, album art) close on a click
|
||
or Esc.
|
||
**Buttons** (Round 92): every one darkens on hover (`HOVER_DARKER`)
|
||
and clearly more while held (`PRESSED_DARKER` 125, sunk) — between
|
||
Material 3's 8 %→10 % and GNOME's 15 %→30 %; a checked toggle uses
|
||
`CHECKED_DARKER`. A transport box draws nothing itself: its buttons
|
||
carry the face (QFrame has no `:pressed`, so a face on the box could
|
||
never sink), and the play box's three are separate touching buttons
|
||
(`tile` property: square where they meet, one shared line). The seek
|
||
slider has the `tall` property, which `ClickToJumpScrollStyle` reads to
|
||
draw its groove and knob twice Fusion's height. With art, the sidebar
|
||
panel draws the cover to the outline's centre and the 1 px line over it
|
||
in the lists' grey (`frame_color`); inset by half a pixel, the clip
|
||
left a pale blend that read as a 2 px border on vivid covers.
|
||
The playlist list's frame is a `sidebar.RoundedFrame` (Round 91): the
|
||
panels' 8 px corners, painted *over* the list by a mouse-transparent
|
||
overlay (window color outside the curve, then Fusion's own frame line,
|
||
`frame_color`), since a mask would be jagged. The empty art panel is a
|
||
button (click = download art) that only looks like one under the
|
||
cursor: embossed in the Library button's face on hover, sunk and darker
|
||
while held. The big art window has **no background**: it is snapped
|
||
back to the art's shape after a resize (`art_window.reshaped`, the
|
||
dimension the user dragged leads) and paints the art to *cover*, so a
|
||
shape it can't take (maximized) crops a sliver instead of showing a bar.
|
||
The library search box filters the sidebar too (Round 89):
|
||
`LibraryView.search_changed` → `PlaylistTree.set_filter`, same rule as
|
||
the songs (every word, case-folded, in the name); a folder shows when its
|
||
name matches (with all it holds) or something inside does, opened while
|
||
filtering, and clearing restores the folders the user had open — so
|
||
`rebuild` reads the pre-filter expansion while a filter is up.
|
||
`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/gui/visualizer.py`** + **`visualizer_styles.py`** — the
|
||
transport-bar visualizer (Round 78). The widget owns PCM intake, the timer,
|
||
on/dim/off and the color; a *renderer* (`visualizer_style` pref: `bars`,
|
||
`radial`, `laser`) owns the animation state and paints it into any rect, so
|
||
the double-click `VisualizerWindow` paints the **same** renderer bigger
|
||
rather than a copy. Since the first press of a double-click already cycled
|
||
the brightness, `mouseDoubleClickEvent` puts it back. Every tunable is a
|
||
`visualizer_*` pref, read through `visualizer_styles.settings()` (clamped to
|
||
`LIMITS`, which the Preferences sliders share) and applied live through
|
||
`configure()`. **Radial** is the EQ as polar dots (angle = log bands,
|
||
radius = level in rings; both counts are settings). A moving dot leaves
|
||
ghosts in its own color fading into the background, kept as a birth time
|
||
per (spoke, ring) so a spoke never holds more than its ring count. It reads
|
||
a **4096**-point FFT and interpolates bands narrower than a bin: with 2048
|
||
points, every degree under ~1.3 kHz shared a bin with its neighbours and
|
||
drew as a flat arc. "Even out bass and treble" removes a *straight*,
|
||
loudness-weighted dB-vs-log-f tilt, clipped to ±24 dB, and never lifts a
|
||
band that isn't sounding (a curve fitted to a lone tone lit up silent
|
||
treble). **Laser** simulates a mirror on a speaker membrane: the
|
||
circular-membrane modes run as complex one-pole resonators, vectorized in
|
||
`CHUNK`s. Loops come from the split degenerate pairs, between whose
|
||
resonances x and y answer up to 90° apart, hence the slack 50 Hz membrane
|
||
with a wide split. The beam ray is intersected with a screen at
|
||
`distance`, turned by pitch/yaw/roll; the auto-gain holds the beam
|
||
*angle*, so distance is real, and `scale()` shrinks the drawing only when a
|
||
steep screen would push the loudest swing out of view. The path is drawn
|
||
brighter where it moves slower (dwell). The afterimage is a **phosphor**
|
||
(`_Phosphor`, one per painted size, half resolution past 400 px wide):
|
||
each sweep is burned in once and the buffer is dimmed per frame, so cost
|
||
doesn't grow with the fade time. The dimming is a numpy LUT that rounds
|
||
*down*, because Qt's own fade rounds to nearest and stalls faint pixels
|
||
forever. The numpy array must be a **view of the QImage's `bits()`**, since
|
||
building a QImage *from* an array copies it. A **speaker range** (low/high
|
||
Hz, `gui/range_slider.py`) filters what drives the membrane, with
|
||
`one_pole` stages done exactly via the cumsum trick, 36 dB/octave. That is
|
||
steeper than a real speaker on purpose: the membrane answers bass ~80 dB
|
||
more than treble, so a gentler slope lets bass drown a treble-only
|
||
setting. For the same reason the auto-gain floor is *measured* per range
|
||
(reference hiss through that speaker and membrane), and the membrane is
|
||
simulated at full rate only once the bass is cut. Treble alone draws a
|
||
shimmer along one line: far above every resonance, all modes move in
|
||
phase. Every style's fade is one seconds slider,
|
||
0 = off. **Sync** (Round 78): decoding runs ahead of the speakers, by a
|
||
buffer or two normally but by up to ~0.8 s when the GUI thread stalls and
|
||
buffers arrive in a burst. So the widget keeps 1.5 s of *timestamped*
|
||
history (`QAudioBuffer.startTime()`) and each frame draws the stretch
|
||
ending at `Player.position_ms()`, carried forward by the clock between
|
||
Qt's buffer-sized steps, minus `visualizer_sync_delay_ms`. That delay is
|
||
output latency Qt can't see (Bluetooth), this machine's hardware, so it
|
||
lives in **`config.json`**; the dialog emits `prefs.changed` after writing
|
||
it so the widget re-reads. The laser takes every heard sample exactly once
|
||
(`_drawn` index), never the newest-decoded ones.
|
||
**Presets** (`gui/visualizer_presets.py`): per style, `STYLE_KEYS` under a
|
||
name, in `visualizer_presets` (synced; never the sync delay). `Default` is
|
||
built in and reserved. Applying one moves the dialog's *controls* (each
|
||
registers a setter in `_viz_setters`), and their own handlers save the
|
||
values, so controls and prefs can't disagree. The drop-down reads
|
||
"Custom" whenever the settings match no preset. A setting added later
|
||
must join `STYLE_KEYS` and register a setter, or presets silently skip it
|
||
(`test_every_style_key_has_a_control` pins that).
|
||
The laser page draws the rig (`gui/laser_diagram.py`, textbook line art
|
||
through the renderer's own `_rotation`); it labels distance, angles and
|
||
dot size, so those sliders show no number.
|
||
The highlight swatches can be repainted with a color picker:
|
||
`highlight_palette` overrides a slot, and `theme.highlight_color` reads
|
||
through `theme.highlight_palette`, so nothing else needs to know.
|
||
|
||
- **`lintunes/kaleidostrobe/`** + **`gui/visualizer_kaleido.py`** — the
|
||
fourth visualizer style (Round 84): Kaleidostrobe, the 2002 iTunes plugin
|
||
by Shehryar Lasi, **reverse-engineered from its PowerPC Mach-O** (symbols
|
||
intact) to be identical, not "inspired by". Method: capstone listings, and
|
||
the original running under a **Unicorn PPC emulator** through its own
|
||
VisualPluginHandler (imports answered in Python, GL calls recorded) as the
|
||
oracle. `engine.py` is the Qt-free port, routine by routine, with `f32` /
|
||
`math.fma` wherever the PPC rounded to single or fused a multiply-add
|
||
(a palette index on `x.5` depends on it), `ParkMiller` = Darwin 6's
|
||
`rand()` (RAND_MAX 2³¹−1). `tables.npz` holds what the original computes
|
||
deterministically, extracted by running *its* code: 22 colour maps and 23
|
||
base wave images (before their random `transform()`, which is ported, as
|
||
are the 16 live `calcDelta` warps — each with its **own** static counters
|
||
per layer). Quirks kept on purpose: `flipDiag`'s off-by-one. Facts that
|
||
shape the port: the plugin renders only after 39,999 µs, so it ran at
|
||
**25 fps** and counts frames for rotation and switching — the renderer
|
||
steps the engine on its own 25 Hz clock, never the widget's 60 Hz timer;
|
||
beat timing is in TickCount (1/60 s). The original's Color/Flash settings
|
||
were Apple SDK leftovers its code never read, so the style has none. It
|
||
reads only iTunes' **spectrum** bytes (never the waveform); iTunes' byte
|
||
scale was never published, so `itunes_spectrum` (√magnitude, 43 Hz bins)
|
||
is the one calibrated stand-in. **On screen it is 60 fps anyway**
|
||
(Round 85): between the 25 Hz frames `_compose` turns the cones by a
|
||
fraction of a frame and crossfades the textures — smoothing only. The
|
||
cones' height/depth change **only on the plugin's frames**: Round 85 also
|
||
drove them from the newest audio every refresh (snappier beats), and on
|
||
bass-heavy songs it twitched — a jump on 84% of refreshes against 41% —
|
||
so Round 86 took it out. The 25 fps cap was hiding that jitter; don't
|
||
reintroduce fresh-audio geometry between frames. Painting: the panel uses QPainter — each GL triangle is
|
||
planar, drawn in texture space through a projective **world** transform
|
||
(Qt mis-draws a strongly projective *brush* transform). The **big window
|
||
replays the original's GL calls** (`paint_gl` in a `gui/kaleido_gl.py`
|
||
QOpenGLWidget, GL 2.1 fixed-function via QOpenGLVersionFunctionsFactory):
|
||
QPainter cost ~40 ms a frame at 1920×1080, which is what stuttered. No GL
|
||
→ `unavailable` → the window paints with QPainter again. Gray mode is
|
||
strictly two-tone (gray-mode colour on the panel background, by HSV
|
||
value — luma calls the saturated palettes dark). The sync slider now goes
|
||
below 0 ("sooner"), borrowing audio decoded but not yet heard — only
|
||
~0–30 ms of it exists, hence the −50 ms floor. The top cone is always
|
||
nearer, so painter's order is the depth test.
|
||
`tests/kaleidostrobe_golden.npz` was recorded from the emulated original
|
||
and `test_round84` holds the port to it byte for byte.
|
||
|
||
- **`lintunes/dj/`** + **`gui/dj_shelf.py`** — DJ mode (Round 93; View ›
|
||
DJ Mode or the turntable button under BPM). The window parts **under the
|
||
row of transport boxes** (`TransportBar.insert_shelf`: the Library button's
|
||
header row slides down with the lists) and a dark shelf shows in the gap,
|
||
animated open and closed (`MainWindow.set_dj_mode`). Default height leaves
|
||
~15 songs below (at least the full 320 px layout), the grip resizes it
|
||
between ~28 and ~5 songs below (`height_bounds`), saved as config.json's
|
||
`dj_shelf_height`; under 200 px it's one compact strip. **Manual, like DJ
|
||
software**: a deck loads only by dragging a song onto its record (the
|
||
record darkens and gets the deck's rim; replacing a deck that's playing
|
||
above 50 % gain asks first), and a song that ends just stops — no queue,
|
||
so the main transport, seek bar, space and arrows are greyed/ignored, and
|
||
the main player is **suspended** while DJ mode is open
|
||
(`Player.set_suspended`: paused, and nothing — double-click, Return, a
|
||
media key — can start it; it played behind the decks, unstoppable, in
|
||
v0.63.0). "Sync to other track" is enabled whenever its own deck has a
|
||
song; what it can't do yet it says in the status bar. Deck A is blue and Deck B
|
||
orange, every control included; loaded songs get a DECK A/B tag in every
|
||
track list (`track_table.deck_tag`). **Its own engine**, because Qt's
|
||
player can't change tempo without pitch or play backwards: `dj/loader.py`
|
||
decodes the whole song (ffmpeg CLI, int16 stereo 44.1 kHz, ~50 MB per 5
|
||
min) and analyses it — `bpm_detect`'s tempo, refined to 0.01 BPM by which
|
||
tempo folds the onsets sharpest (`analysis.beat_grid`; 0.1 BPM off smears
|
||
two minutes of beats by a fifth of a beat), and the first beat from a
|
||
~3 ms energy-rise onset (`onset_times`; bpm_detect's 1024-sample flux
|
||
smears *when* by tens of ms). Both measured exact on synthetic kicks. A
|
||
file with no BPM gets it saved (`set_tracks_bpm`). `dj/audio.py` is pure
|
||
numpy: keep pitch = WSOLA (1024/512, ±256 search), Keep pitch off =
|
||
varispeed, scratching = varispeed at the hand's angular rate (one turn =
|
||
1.8 s, a 33⅓ record; letting go is normal speed at once). The mixer is
|
||
constant-power crossfade × master (the volume slider through Qt's curve).
|
||
`dj/output.py` feeds a QAudioSink from **its own QThread** (100 ms
|
||
buffered), so GUI painting can't starve it; it must stop before Qt quits
|
||
(`aboutToQuit`, `closeEvent`), and **tests stub it** (conftest
|
||
`_no_dj_sound`) — the decks would otherwise play out loud. Sync ("Sync to
|
||
other track", per deck): tempo to the other deck's (the nearest octave);
|
||
if both are playing, then the shortest beat nudge (`phase_shift`, never
|
||
more than half a beat). The waveforms are drawn in *heard* time around one
|
||
shared playhead, so synced beats sit exactly above each other. **Vocals**:
|
||
Demucs (htdemucs, two stems) splits each loaded song once in the
|
||
background into `$XDG_CACHE_HOME/lintunes/stems/<key>/` (path+size+mtime);
|
||
the slider blends vocals/instrumental live. Demucs + CPU PyTorch (~1 GB)
|
||
live in their own venv, `$XDG_DATA_HOME/lintunes/demucs`
|
||
(`stems.setup_command()`; it needs numpy installed explicitly), never a
|
||
pip dependency of LinTunes — without it the slider is disabled with that
|
||
command in its tooltip.
|
||
|
||
- **`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/art_search.py`** — Download Album Art. Queries **both** the
|
||
iTunes Search API and Deezer's public album search (neither needs a key)
|
||
and merges them through `rank_candidates`: album match beats artist match,
|
||
so a right-artist, wrong-album hit never wins. Two sources because neither
|
||
catalog is complete: iTunes has **no copy at all** of Digable Planets'
|
||
*Reachin'*, which Deezer finds on the first query (Round 60). One source
|
||
failing is not an error while the other answers. Embedding, whether from
|
||
there or from Get Info, goes through `gui/art_ops.embed_artwork`: write,
|
||
`mpris.invalidate_artwork`, size refresh. Get Info's `ArtSquare` **never
|
||
stages bytes that don't decode** (`clipboard_image` checks every candidate
|
||
with `QImage.loadFromData`), because a clipboard can advertise `image/png`
|
||
and hand over nothing. Every paste attempt is logged at INFO
|
||
(`lintunes.gui.info_dialog`), so it shows up in the journal.
|
||
|
||
- **`lintunes/fingerprint.py`** — "Identify Track…": Chromaprint's `fpcalc`
|
||
CLI (detected with `shutil.which`, the `ffmpeg_available()` pattern — a
|
||
runtime tool, never a pip dep) fingerprints the file, and AcoustID's web API
|
||
says what it is. Shaped like `art_search.py`: pure parse/rank helpers first
|
||
(tested offline against canned JSON), then subprocess/network, then
|
||
`TrackIdentifier(QObject)` on a daemon thread emitting a dict carrying either
|
||
`candidates` or `error`. **The year rule is the point of the feature**: every
|
||
candidate carries the recording's *original* year — the earliest release
|
||
across **all** its release groups — even the candidate proposing a later
|
||
compilation as the album, because a 60s song must not sort by the year its CD
|
||
reissue came out. `_releasegroup_sort_key` separately ranks a plain studio
|
||
Album above EP/Single above anything with a Compilation/Live secondary type,
|
||
so the default proposal is the real album. **An AcoustID result's score
|
||
belongs to the *audio*, not to any one recording**: every recording linked to
|
||
it carries that score, mis-tags included, and a song whose title another
|
||
artist also used collects them (Round 52: trav's Dionne Farris "I Know" is
|
||
linked to Jay-Z's, Marisela's, David Essex's and New Atlantic's). What tells
|
||
a real link from a stray is `sources`, the submission count — 475 against 6
|
||
and three 1s — so the lookup asks for it and `_link_tier` sinks anything
|
||
under a tenth of the strongest link in that result. Hence the key order
|
||
*who*, then *which take*, then *which release*: stray tier, agreement with
|
||
the artist the file's own tags name (`artist_hint_for`), duration bucket,
|
||
hint overlap, release rank. Artist before duration is the point — Jay-Z's
|
||
take was 1.5 s closer to the file than Dionne's own, and that used to decide
|
||
it. `gui/identify_dialog.py` is passive
|
||
(the `AlbumArtDialog` contract — nothing written until accepted); the caller
|
||
applies `result_fields()` through `LibraryManager.edit_track_fields`, which is
|
||
what buys tag writes, undo and artist/album file relocation for free. A row is
|
||
pre-checked only where the proposal *differs* from the current value, so an
|
||
unchecked field can never quietly blank a tag. The API key is the user's own,
|
||
in `preferences.acoustid` (the Last.fm precedent — preferences.json syncs, so
|
||
it never belongs in git). Audio under ~3 s has no fingerprint at all
|
||
("Empty fingerprint"), which is a reported failure, not a crash.
|
||
|
||
- **`lintunes/bpm_detect.py`** — right-click → Calculate BPM (Round 73).
|
||
Spectral-flux onset envelope → autocorrelation → every tempo 60–200 scored
|
||
over four beat multiples, times a log-Gaussian prior at 120 BPM (the
|
||
half/double-tempo tiebreak), then `fold_bpm` into 70–180. Plain numpy plus
|
||
the `ffmpeg` CLI (decodes the first 120 s to mono 11 kHz) — **no librosa**,
|
||
which would drag numba/scipy/scikit-learn in for one function. `BpmWorker`
|
||
is ExportWorker's shape on the shared status-bar widgets (`_busy_worker`),
|
||
reports each result as it lands so a cancel keeps them, and the batch is
|
||
applied by `LibraryManager.set_tracks_bpm` as **one** undoable command,
|
||
overwriting existing BPMs (trav's call). The transport's tap button stays
|
||
for the songs it gets wrong.
|
||
|
||
- **`lintunes/filename_tags.py`** — the offline half of Identify Track, and the
|
||
answer to its biggest limitation: **AcoustID only knows music somebody
|
||
submitted**, so an underground/SoundCloud rip fingerprints perfectly and
|
||
matches *nothing* (verified: "B. Clem — Zuuso" returns zero results from
|
||
AcoustID, zero from a MusicBrainz text search, zero from iTunes). Its
|
||
filename, though, says exactly what it is. Pure string work, no network, no
|
||
Qt: strips yt-dlp's trailing id (`[1025657891]`, `-WC7gK2kgyTQ` — an 11-char
|
||
token is only treated as a YouTube id if it carries a digit, an underscore,
|
||
or repeatedly flipping case, or "Underground" would be eaten), drops
|
||
`(Official Video)`-style noise, splits `Artist - Title` on a *spaced* hyphen
|
||
only (so "Jay-Z" and "350-440-DialTone" survive), collapses a doubled
|
||
uploader, reads a leading `1-04`, restores `_s`→`'s`, and falls back to the
|
||
iTunes tree (`<root>/Artist/Album/NN Title.ext`), ignoring placeholder dirs
|
||
like "Unknown Artist". `fingerprint.candidate_from_filename` wraps it as a
|
||
candidate with `source="filename"`, appended to every lookup and standing
|
||
alone when there are no matches — the dialog then says where the guess came
|
||
from instead of quoting a fabricated confidence. The same filename also
|
||
feeds `hint_for(track)`, which ranks real lookup results: token overlap
|
||
(words worth double, bare numbers single — "alhambra" identifies a release,
|
||
"1961" appears in every compilation spanning it), a coarse **duration**
|
||
bucket off the recording lengths AcoustID returns (which is what separates a
|
||
150 s studio take from a 155 s live one), and a year named in the filename
|
||
that predates anything the database knows. That last one is not a nicety:
|
||
MusicBrainz's own `first-release-date` for "Ahmad Jamal's Alhambra" is
|
||
**2002**, because its three original 1961 pressings are in the database
|
||
undated — so a second MusicBrainz call would return the same wrong year, and
|
||
the file's own name is the only place 1961 exists.
|
||
|
||
- **`lintunes/url_import.py`** — `File → Import from URL…` (Round 49): trav's
|
||
`song` shell helper (`yt-dlp --extract-audio --audio-format mp3 "$@"`) run
|
||
from inside the app. Those flags are passed **verbatim**; everything else on
|
||
the command line is plumbing: `-P <tempdir>`, `--print before_dl:LTSTART …`,
|
||
`--print after_move:LTFILE %(filepath)s` and an `LTPROG` progress template,
|
||
so output is read from markers rather than scraped. yt-dlp is a *runtime
|
||
CLI tool* (`shutil.which`, the fpcalc pattern), never a pip dep, and needs
|
||
ffmpeg for the mp3. **No `-o`**: yt-dlp's default `Title [id].mp3` is what
|
||
`filename_tags` parses. `UrlImportWorker` (daemon thread, `ExportWorker`'s
|
||
shape, shares the status-bar progress widgets and so `_busy_worker()`)
|
||
downloads into a private `mkdtemp`, emits `downloaded(path)` per song, and
|
||
the GUI imports each one *as it lands*, through the normal `import_files`
|
||
(a copy into the organized tree) and straight into the Identify queue, so
|
||
song 1's dialog can be up while song 5 downloads. The GUI deletes the temp
|
||
dir only on `finished`/`failed`, which are queued after every `downloaded`.
|
||
`resolve_target` is the rule for "and add to current playlist?": above the
|
||
selected song in the shown playlist, else the end of the *playing*
|
||
playlist, else the end of the shown one, else the checkbox is grayed.
|
||
Smart/folder/system playlists are never targets. A batch keeps the link's
|
||
order (`position + songs already inserted`). With no AcoustID key,
|
||
`TrackIdentifier` proposes from the filename alone and never touches fpcalc
|
||
or the network. Only a URL import reaches that path, since the menu route
|
||
still insists on setup first. YouTube's "Sign in to confirm you're not a
|
||
bot" is about the *network* (`song` hits it too), and yt-dlp's cure is the
|
||
browser's cookies: a run that downloads **nothing** for that reason is
|
||
retried once with `--cookies-from-browser` (`default_cookies_browser`,
|
||
Firefox first), and a browser that worked is saved as
|
||
`ytdlp_cookies_browser` in **`config.json`**, not preferences — which
|
||
browser holds a YouTube login is this machine's business (Round 59).
|
||
**A link is listed before it downloads** (Round 75): trav pasted a song
|
||
from a YouTube Mix (`watch?v=…&list=RD…`), yt-dlp took the whole list,
|
||
and songs kept arriving with no word why. `link_kind` (URL alone) lets
|
||
only a plain song link skip the listing; everything else goes through
|
||
`PlaylistProbe` (`--flat-playlist`, one `LTENTRY` line per song, streamed
|
||
into the dialog's checklist). A song-in-a-list ticks only its song (plus a
|
||
**Just This Song** button that doesn't wait), a playlist link ticks all.
|
||
Measured on the real Mix: ~36 s to the first row, 2,967 rows, the linked
|
||
song **8 times** (a Mix loops), so rows are de-duplicated by id. Chosen
|
||
songs download by **their own page URLs**, never the list link or
|
||
`--playlist-items`, since a Mix reshuffles on every listing. Several songs
|
||
get `gui/url_import_progress.py`, a non-modal per-song list (Hide keeps
|
||
downloading; clicking the status-bar line reopens it). `LTSTART` carries
|
||
the id, and `ERROR: [site] <id>: …` lines become `item_failed`.
|
||
**A Spotify link** (Round 76, `spotify_link.py`, ported from trav's
|
||
`spotify-youtube` script) can't be downloaded, but Spotify's public
|
||
embed page (`open.spotify.com/embed/<kind>/<id>`, a `__NEXT_DATA__`
|
||
JSON block, no key) names every song with its **length**. `SpotifyProbe`
|
||
feeds those to the same checklist; `SpotifyImportWorker` (a
|
||
`UrlImportWorker` with the same signals, rows keyed by Spotify id) runs a
|
||
`ytsearch5:` listing per song, takes the result closest to Spotify's
|
||
length (`rank_candidates`: within 10 s, then no "live"/"cover" the
|
||
Spotify title doesn't have — the shazam-import lesson), falls back to the
|
||
next result if a download fails, and writes Spotify's title/artist/album/
|
||
track number into the mp3 **before** emitting `downloaded`, so the
|
||
import files it under the right artist and Identify ranks by that artist.
|
||
If the embed page changes shape, `parse_embed` raises `SpotifyError`.
|
||
**Several songs are identified as one batch** (Round 77,
|
||
`identify_batch.py` + `gui/identify_batch_dialog.py`): an import of more
|
||
than one song never pops a dialog mid-download. `IdentifyCollector` looks
|
||
each up quietly as it lands, and only after `finished`/`failed` *and* the
|
||
last lookup does one review window open, with all the songs as rows in the
|
||
app's columns. `find_common_album` makes it "one album" when every song
|
||
naming an album can be on the same one (its own tags vote too, which is
|
||
what carries a Spotify album through AcoustID's compilations). Then the
|
||
album-wide fields are unified to the most common value, shown once above
|
||
the table, and the cover comes from the same `AlbumArtFetcher` search.
|
||
Ticked rows go through `LibraryManager.edit_many_track_fields` as **one**
|
||
undo step. Unticked rows get the ordinary `IdentifyDialog` afterwards,
|
||
from the lookups already made. **No popup may land on top of another
|
||
app**: `MainWindow._when_app_active` shows it at once only while LinTunes
|
||
is the active application, and otherwise asks for attention
|
||
(`QApplication.alert`) and waits for `applicationStateChanged`. A window
|
||
test that downloads several songs must stub `_show_batch_review` and
|
||
cancel `_url_batch` on teardown, or a late lookup opens a modal dialog
|
||
in the next test.
|
||
|
||
- **`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`, which **ignores
|
||
auto-repeat**: on Wayland repeats are generated client-side until the
|
||
compositor delivers the release, and a busy gnome-shell turned one held
|
||
arrow into 1,676 track skips (Round 56). Every list sent over D-Bus must be
|
||
a typed `QDBusArgument` (`mpris.string_array`) — a plain Python list goes
|
||
out as `av`, which GDBus rejects. That was `xesam:artist`, and the error
|
||
flood it caused is what kept gnome-shell busy.
|
||
|
||
- **`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. Its menu item ("Sync Playlist to
|
||
Rabbit (Auxio)") was **retired in Round 51**, once andTunes could play what
|
||
it syncs; the module stays because `find_device` and its `sanitize_name` /
|
||
`track_display` / `track_filename` / `build_m3u` / `CHUNK` are imported by
|
||
both `export/exporter.py` and `andtunes/`, so their signatures are
|
||
load-bearing.
|
||
|
||
- **`lintunes/andtunes/`** — the desktop half of andTunes, a music player for
|
||
the Rabbit R1 (Round 47; the app itself lives in `andtunes/` at the repo
|
||
root, R1 measurements in `andtunes/DEVICE.md`, tasks tagged `andtunes` on the board). The premise: **the app never scans
|
||
anything.** Auxio re-reads Android's MediaStore on every launch, which is
|
||
the "your songs will show up here" hang — but LinTunes already knows the
|
||
artist, album and year of every file it just copied, so it writes them into
|
||
`Music/andTunes/library.json` and the app parses one file instead of
|
||
indexing a filesystem. `layout.py` is the on-device shape (`Media/<Artist>/
|
||
<Album>/04 Song.mp3` — one copy per song however many playlists hold it —
|
||
plus `Art/`, `Playlists/`, `library.json`); `manifest.py` is pure and
|
||
Qt-free; `art.py` renders one 480 px JPEG **per album** (not per track) via
|
||
QImage — safe off the GUI thread, unlike QPixmap — cached under
|
||
`$XDG_CACHE_HOME/lintunes/andtunes-art` and invalidated by the audio file
|
||
being newer, which is exactly what embedding new art does. `sync.py` is a
|
||
third sibling of `plan_export`/`ExportWorker`: pure planner, then a daemon
|
||
thread with KiB progress. Three rules that bite: **planning must not render
|
||
art** (a mutagen open per album, and planning runs on the GUI thread — the
|
||
worker does it, and those bytes are absent from the progress total); the
|
||
index (m3us then `library.json`) is written **last** and after a cancel is
|
||
rewritten to list only tracks whose files actually landed, so the app never
|
||
opens a manifest with holes in it; and every delete goes through
|
||
`layout.assert_inside`, which refuses anything not strictly inside the
|
||
andTunes root. That guard is why the old `Music/<Playlist>/` folders are
|
||
structurally unreachable rather than merely un-referenced, and `Buttons/`
|
||
(the user's own menu artwork) and `plays/` (written by the app) are skipped
|
||
by the device scan entirely — sync reads those, it doesn't own them.
|
||
Which playlists go on the device lives in `preferences.json` under
|
||
`device_sync` (so it rides the Syncthing share and both machines agree);
|
||
keeping it off the `Playlist` keeps it out of the conflict-merge machinery,
|
||
and **unticking is the only way a playlist comes off the device**.
|
||
A fully ticked *folder* is stored as `device_sync.folder_ids` and follows
|
||
the folder — playlists added to it later sync too
|
||
(`device_sync_dialog.resolve_sync_playlists` is what both the dialog and
|
||
the sync read).
|
||
**The device's filesystem is case-insensitive**, so "RJD2" and "Rjd2" are one
|
||
folder there and one artist here: since Round 54 the app's `Library.group()`
|
||
keys *both* `albumsByKey` and `artistsByName` case-folded (and fetches the
|
||
artist before the album block, holding it — the raw-case lookup afterwards is
|
||
what NPE'd on the second track of a two-spelling album and blanked the whole
|
||
library), and `plan_andtunes_sync` folds both the collision rule and the
|
||
device diff, which had been re-copying every such file over MTP every sync.
|
||
`plan.stale` still carries the device's own spelling — that is what
|
||
`_delete_stale` unlinks by.
|
||
**A gvfs-MTP mount can hold a *phantom* directory** — one it lists happily
|
||
while the device has no such folder — and every write into it fails `EIO`
|
||
forever, because `mkdir(exist_ok=True)` sees the phantom and does nothing.
|
||
Only remounting clears it (`gio mount -u mtp://…` then `gio mount`). Two
|
||
rules came out of it (Round 55): a copy that raises `OSError` costs **that
|
||
song**, not the sync (it lands in the `unwritable` summary list), and the
|
||
song is then **left out of the m3u and `library.json`** — a manifest naming
|
||
a file that isn't there is worse than a short one, because the app skips to
|
||
the next track and the user sees the wrong song play. **Planning is a worker**
|
||
too (`AndTunesPlanWorker`): `plan_andtunes_sync` is pure, but it walks every
|
||
file on the device, and over MTP that froze the window long enough for GNOME
|
||
to offer to kill LinTunes mid-sync. Anything after the last album
|
||
(`_write_index`, buttons, pruning) must keep emitting progress — it was
|
||
minutes of silence with the line stuck on `Album art 501/501`, and
|
||
`_write_index` reads `Art/` in **one listing**, never a stat per album.
|
||
The art pass is held to the same rule (Round 70): it compares each cover
|
||
against `plan.art_sizes`, the sizes the planner's scan already read, never a
|
||
stat per album, and `art.album_art_jpeg` caches "this album has no art" as a
|
||
`<key>.none` marker, so an unchanged library costs the art pass no device
|
||
I/O and no mutagen opens.
|
||
Since Round 50 the app exists: `andtunes/app/` is plain Java against the
|
||
Android framework, built by `andtunes/build.py` (aapt2 → javac → R8 →
|
||
zipalign → apksigner) — **no Gradle, no Kotlin**, because platform 33 +
|
||
build-tools 34 were already on disk and trav didn't want a 1 GB download
|
||
over cell for tools that make the same APK. `--ship` copies it to
|
||
`lintunes/android/andTunes.apk` with its version in `andTunes.json`;
|
||
**re-run `--ship` whenever the app changes**, since the committed APK is
|
||
what the self-updater carries and what `install.py` installs.
|
||
**App v0.4.0** (Round 92): the menu is a list, Now Playing has icon
|
||
pills and a full-screen art / album link, and a speakers pill plays the
|
||
queue on AirPlay (`AirPlayRemote`, raop.py in Java) or Chromecast
|
||
(`CastRemote`, the Cast protocol by hand) — see andtunes/README.md.
|
||
Test speakers only against shairport-sync in Docker published on this
|
||
machine's LAN address (its avahi stays on the Docker bridge, so it is
|
||
never advertised), listed in the device's `Music/andTunes/speakers.txt`
|
||
— **never** connect the Rabbit to a speaker that isn't trav's, and read
|
||
a screencap before every `input tap`: the picker lists the neighbours'.
|
||
`andtunes/andtunes.keystore` is committed on purpose (both machines must
|
||
sign identically or `adb install -r` refuses the update). `install.py` is
|
||
Connections → Install andTunes on Rabbit…: adb as a runtime tool, then the
|
||
all-files + notification grants (a refused grant is not a failed install —
|
||
the app's first-run screen covers it), or an MTP copy to `Download/` with
|
||
no adb. Sync copies `buttons/*.png` (rendered by
|
||
`andtunes/tools/make_buttons.py`) into the device's `Buttons/` **only
|
||
where the file is missing** — those names are a contract with the app's
|
||
`Ui.button()`, which prefers the device copy. `proguard.pro` keeps no
|
||
debug attributes because R8 8.2 NPEs on javac 21's.
|
||
Round 51 closed the loop. The planner runs every track through
|
||
`export/web_support.conversion_for` (Android decodes the browser set), so
|
||
FairPlay is refused and ALAC/AIFF land as `.flac` — converted once into
|
||
`$XDG_CACHE_HOME/lintunes/andtunes-flac/<track id>.flac` and size-diffed
|
||
from there on, so a converted song isn't re-copied every sync. And the app
|
||
keeps `plays/andtunes-<install id>.json` in the play-journal shape, counted
|
||
on a natural finish like `Player`; `plays.bring_back` folds it into
|
||
`<data_dir>/plays/` with `play_journal.merge_totals` (per-track max — that
|
||
file has two homes and both desktops may bring it back) **before** anything
|
||
is copied, writing nothing when nothing moved. `PlayJournal.load` then
|
||
treats the R1 as one more machine.
|
||
**A wedged gvfs-MTP mount blocks in uninterruptible FUSE waits**: `timeout`
|
||
can't kill a process stuck on it. USB re-enumeration (lock/unlock with
|
||
`mtp,adb`, an `adb install`) is what wedged it in Round 51. Recovery:
|
||
`kill` the `gvfsd-mtp` process, then `gio mount mtp://<device>/` —
|
||
`device_sync.reset_mtp_connection`, offered as **Reset Connection** when
|
||
the menu item reads "Rabbit isn't responding…". Since Round 71 **the GUI
|
||
thread never calls `find_device()`**: it froze the window every time the
|
||
Connections menu opened on a wedged mount. `MainWindow._devices`
|
||
(`device_sync.DeviceWatcher`) probes on a daemon thread, one at a time,
|
||
and declares `STUCK` after 3 s; click handlers go through
|
||
`when_ready(callback)`. A stuck probe thread can't be killed, so quitting
|
||
then may still hang until the reset. `tests/conftest.py` patches
|
||
`find_device` to `None` for every test, and nothing — test or tool call —
|
||
may list `/run/user/*/gvfs`; ask `gio mount -l` instead, which goes over
|
||
D-Bus.
|
||
|
||
- **`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.
|
||
**Upload to web server** (Round 81, `export/upload.py`): a ticked box in
|
||
the web-mix dialog builds the mix in `$XDG_CACHE_HOME/lintunes/webmix/
|
||
<slug>/` (no folder picker) and mirrors it with `rsync -a --checksum
|
||
--delete` over ssh to `<host>:<path>/<slug>/`. rsync, not scp: scp re-sends
|
||
everything and never deletes, so a song taken out of the playlist would
|
||
stay online forever. Host and path live in **`config.json`** only (the
|
||
host is usually this machine's `~/.ssh/config` alias, and trav's server
|
||
must never appear in the repo or the synced share — tests use
|
||
`example-host`). `--delete` only ever reaches the slug folder
|
||
(`remote_dir` validates the slug), staging is wiped first
|
||
(`reset_staging`, guarded to stay inside the staging root) so a removed
|
||
song can't survive the mirror, and ssh runs with `BatchMode=yes`, since
|
||
nobody can answer a prompt. Steps: `ServerCheckWorker` (`ssh test -d`; an
|
||
existing folder asks before replacing it), `ExportWorker`, then
|
||
`UploadWorker`, all shown in `gui/web_upload_progress.py`. The web
|
||
player has **previous/next** buttons (the arrow keys, wrapping at either
|
||
end, through the shuffle order when on) and a **shuffle** button (and the S key): a shuffled walk that starts at
|
||
the current song and plays every song once. A mix can carry several
|
||
images (`plan.images`): the dialog always keeps one empty row to add
|
||
another, and the page shows them in order under the description, a blank
|
||
line apart; none at all ships `placeholder.png`.
|
||
|
||
- **`lintunes/cassette/`** — friend library sharing (Round 63+; the spec is
|
||
`Cassette friend library.md`). LinTunes never talks to a friend: it drives
|
||
the **local** Syncthing's REST API (`syncthing_api.py`, key/address from
|
||
Syncthing's `config.xml`, overridable in `config.json`) and Syncthing moves
|
||
the bytes. Every failure is a `SyncthingError(step, detail, kind)`, because
|
||
the UI promises never to fail silently. One of trav's machines is the
|
||
**host** (`host.py`: `config.json` flag + a synced `preferences.json` record
|
||
naming it); everything lives in the machine-local
|
||
`~/.local/share/lintunes/cassette/` (`state.json` + `friends/<token>/
|
||
{out,in,cache}`), never the synced data dir — Syncthing folders must not
|
||
nest. A friendship is two folders, `lintunes-cassette-<token>-a` (inviter →
|
||
invitee) and `-b`, each send-only for its writer and receive-only for the
|
||
reader. **Syncthing hides an unknown device's folders** (verified on 1.30: a
|
||
stranger is only a pending *device*), so while an invite is open the
|
||
inviter's `CassetteService` *probes* a new knock — adds it with nothing
|
||
shared, reads which folder it offers, completes on the right `-b` token or
|
||
removes and remembers it (`state.rejected`). With no open invite nothing is
|
||
probed and knocks stay pending, untouched. The paste side can't tell "their
|
||
computer is off" from "their LinTunes is closed" (Syncthing briefly reports a
|
||
stranger's connection as up), so it shows one combined status.
|
||
`scripts/cassette_pair.py` starts throwaway Syncthings on loopback (no
|
||
discovery there, hence `CassetteService(addresses_for=…)`); tests marked
|
||
`syncthing` run a real handshake with `pytest --syncthing`. The service
|
||
starts from `run_gui`, never from constructing `MainWindow` — tests build
|
||
windows by the dozen and must not reach a real Syncthing.
|
||
**Friend mode** (`gui/friend_mode.py`, entered from the ▾ beside Library)
|
||
shows a friend's `library.json` through a second `LibraryView` over
|
||
`cassette/friend_library.FriendSource` — the slice of `LibraryManager` that
|
||
view reads, read-only. Their track ids are *theirs*: the table is
|
||
`set_read_only(True)` (no play, no drag, no copy into my playlists, only
|
||
"lookup on youtube"), and the cassette column is `track_table.CASSETTE_FIELD`
|
||
(registered in `COLUMN_MAP`, deliberately not `ALL_COLUMNS`), live only
|
||
where `cassette_hooks` is set. Nothing is written until Save and Close
|
||
(`service.save_requests` → `requests.json`); any other exit with changes
|
||
asks "Save changes?". `cassette/matching.py` is best effort (exact vs
|
||
fuzzy); `cassette/space.py` judges the music disk (red) and Syncthing's
|
||
`minDiskFree` floor on the cassette disk (orange) separately.
|
||
**Delivery** (`cassette/delivery.py` + `gui/cassette_delivery.py`) is
|
||
rebuilt from the folders on every pass, both directions: sender = their
|
||
`requests.json` ∩ what I offer *now* → `outbox/<id> ~ <name>` (copied to a
|
||
`.part` the `.stignore` hides, then renamed), and anything no longer
|
||
requested is deleted — a request vanishing *is* the delivery receipt.
|
||
Receiver: planning on the GUI thread (it reads the library), copying on
|
||
`DeliveryWorker`'s thread (`file_importer.stage_file` — the import split so
|
||
the copy is off the GUI thread), `manager.add_track` back on the GUI thread
|
||
(`track_from_file`: date added now, no listening history). An exact match
|
||
already in my library is never imported twice, which is what makes a crash
|
||
between import and requests-rewrite harmless; a missing `library.json`
|
||
prunes nothing.
|
||
**Followed playlists** (a UFO in friend mode) are never `Playlist`s of mine:
|
||
`PlaylistTree.followed_provider` injects them (mixed alphabetically or in a
|
||
friend folder, per `Friend.layout`), and `gui/followed_view.py` plays them
|
||
from `friends/<token>/cache/`. Player queue entries may be **string keys**
|
||
(`cassette:<token>:<their id>`) resolved by `Player.track_resolver`; a key
|
||
scrobbles (`track_finished`) but never calls `record_play`. Requests are
|
||
always computed by `service._write_requests` (cassetted ∪ followed songs not
|
||
yet cached), so a save never re-asks for what's already in the cache, and a
|
||
pass prunes cache files no followed playlist uses.
|
||
|
||
- **`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).
|
||
|
||
- **`lintunes/airplay/`** — AirPlay playback (Connections → Connect to
|
||
AirPlay…, Round 87), via **pyatv**'s RAOP streaming and the opposite model
|
||
to `cast/`: an AirPlay speaker is *sent* PCM in real time, so every song is
|
||
decoded by the `ffmpeg` CLI (`stream.py`) and pyatv packetizes it — ALAC and
|
||
AIFF play here, only FairPlay is refused. pyatv's own sources don't fit
|
||
(its file path is miniaudio, no AAC/ALAC; its pipe path reports duration 0
|
||
and guesses the WAV header), so `stream.install_shim` patches the
|
||
`open_source` name in `pyatv.protocols.raop` to answer a `PcmRequest` with
|
||
an `FfmpegSource` at the negotiated rate. ffmpeg emits **big-endian**
|
||
(`s16be`): pyatv byteswaps its own little-endian samples, and the shim's
|
||
output is byte-identical to pyatv's `FileSource`. pyatv has **no pause or
|
||
seek** for RAOP (its pause *is* stop), so `AirPlaySink` runs one
|
||
`stream_file` per stretch of playback and pause/seek/resume start a new one
|
||
at `-ss`; each start bumps a generation, so a replaced stream can't report
|
||
"finished" and advance the queue. **A closed connection makes pyatv
|
||
*return*, not raise** — "the song ended" is only ffmpeg's EOF
|
||
(`outcome_of`), anything else is a lost speaker. Position is what's
|
||
*heard*: frames read minus the receiver's `22050 + rate` frames of latency
|
||
(~1.5 s, `support.heard_ms`). Volume: the slider's level through Qt's
|
||
log→linear curve, then that dB on pyatv's −30..0 scale
|
||
(`level_to_percent`), applied before each stream starts. Everything pyatv
|
||
runs on one `AsyncLoop` thread; results come back as Qt signals.
|
||
Discovery repeats `pyatv.scan` while the picker is open and lists *every*
|
||
AirPlay device, greyed with the reason when it can't be used (video-only
|
||
TVs/projectors have no RAOP; PIN pairing and passwords aren't built), in
|
||
`gui/cast_dialog.DevicePickerDialog`, which `ChromecastDialog` shares.
|
||
Connects go **RAOP-only** (`controller.raop_only`). Casting and AirPlay are
|
||
mutually exclusive (MainWindow disconnects the other first); the visualizer
|
||
tile shows the sink's `glyph`. Testing streams against **pyatv's own fake
|
||
receiver** (`tests/fake_device/raop.py` in its sdist, bound to 127.0.0.1) —
|
||
never a real speaker unless trav says so.
|
||
**pyatv's own handshakes play nothing on a WiiM** (Round 88): its AirPlay 2
|
||
session (picked for any receiver advertising AirPlay 2 features) gets 200
|
||
OK for everything, timing included, and stays silent; its AirPlay 1 runs a
|
||
transient pairing and then sends the ANNOUNCE unencrypted, and the WiiM
|
||
hangs up. Music Assistant's `cliairplay` plays on it through libraop's
|
||
RAOP client (its "RAOP-compat" route), so since Round 90 **`raop.py` is
|
||
LinTunes' own RAOP sender** reproducing that client's behaviour, and
|
||
pyatv only discovers those speakers: one RTSP session per connection
|
||
(auth-setup when `et` lists 4, ANNOUNCE AppleLossless, SETUP, RECORD with
|
||
`RTP-Info`, no FLUSH before audio; OPTIONS keepalive every 25 s; FLUSH +
|
||
restart for pause/seek/next), the iTunes User-Agent, a **2 s** buffer
|
||
(pyatv's is 1.5 s; cliairplay's notes say LinkPlay starves on shallow
|
||
ones), RTP timestamps on the NTP clock, a start 200 ms out so the first
|
||
~2 s go out at once, the timing responder, resends from a 512-packet
|
||
backlog. `NativeDevice` is the slice of a pyatv device `AirPlaySink`
|
||
drives, so the sink is shared. Audio is **uncompressed** ALAC
|
||
(`support.alac_verbatim`) where libraop compresses: ffmpeg's encoder only
|
||
writes 4096-sample frames (RAOP needs 352), and Rice coding in Python
|
||
would cost the GUI's interpreter a share of a core. Not yet confirmed on
|
||
the WiiM. `use_compat`: config.json's `airplay_protocol` "auto" = the
|
||
native sender for everything but Apple's own hardware (a HomePod is
|
||
AirPlay 2 only), "1" = native everywhere, "2" = pyatv's AirPlay 2;
|
||
`airplay_latency_ms` overrides the 2 s. **cliairplay is the fallback**
|
||
(Round 91, trav's go-ahead): when the native sender can't connect, or
|
||
config.json's `airplay_backend` is `"cli"` (`"native"` = never fall
|
||
back), `cli.ensure_binary` downloads Music Assistant's pinned release
|
||
into `$XDG_DATA_HOME/lintunes/bin/` once and **refuses it unless its
|
||
SHA-256 matches** the one pinned in `cli.py` — then `CliAirPlaySink`
|
||
runs ffmpeg → cliairplay per stretch of playback (commands on a fifo,
|
||
`[STATUS]` lines back on stderr; `started at_unix_ms` / `playing
|
||
elapsed_ms` give the position). Bumping its version means new pinned
|
||
hashes from that release's SHA256SUMS. `airplay_debug` puts pyatv's and
|
||
`lintunes.airplay.raop`'s loggers at DEBUG (every RTSP request); every
|
||
stream's start, first audio and outcome are logged at INFO under
|
||
`lintunes.airplay`, and the chosen sender in the control log.
|
||
**Testing without a speaker** (Round 89): shairport-sync in Docker
|
||
(`mikebrady/shairport-sync:5.5.2-classic`, its own dbus + avahi inside,
|
||
on the default bridge so nothing is advertised on the LAN, `-o stdout`
|
||
to a file) is a real third-party receiver whose decoded PCM can be
|
||
compared with what was sent — silent and bit-checkable (its output file
|
||
also holds the silence it writes while idle). pyatv also died on
|
||
shairport's `/info` (not a plist), so the shim treats an unreadable
|
||
`/info` as none.
|
||
|
||
## Conventions & gotchas
|
||
|
||
- **The Rabbit R1's screen is not what the internet says.** Measured:
|
||
**480 × 640 px**, physical density 320, **override density 160** — so an app
|
||
sees a 480 × 640 *dp* canvas on a 2.88" panel (~278 real ppi). One dp is
|
||
about half its usual physical size, so andTunes doubles every stock value
|
||
(rows ≥ 88 dp, text 28–32 sp). Don't "fix" it by changing the device
|
||
density; trav has it where he wants it. Android 13 / API 33, arm64-v8a.
|
||
The scroll wheel emits KEY_UP/KEY_DOWN (`KEYCODE_DPAD_UP`/`DOWN`).
|
||
|
||
- **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. **Title bars are ours** (Round 72): Mutter draws none for
|
||
Wayland clients, and Qt's `adwaita` decoration plugin paints them pure white
|
||
from hardcoded constants, deaf to the palette. So on Wayland
|
||
`gui/titlebar.install` (an app event filter) makes every `Window`/`Dialog`
|
||
frameless at `Polish` and adds a `TitleBar` at its first `Show`, in the
|
||
palette's `Window` color, room made through the window's top contents
|
||
margin and the window grown by that much so its contents keep their size.
|
||
Buttons follow GNOME's `button-layout`; move/resize go through
|
||
`startSystemMove`/`startSystemResize`. A window with no layout must paint
|
||
into `contentsRect()` (`art_window.py`); one that needs the system frame
|
||
sets the `titlebar.OPT_OUT` property. The bar must never be an event filter
|
||
on its own window — that is called during the window's teardown and aborts.
|
||
- **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.
|
||
- **Never develop or verify against trav's real library.** It is 21,531 tracks
|
||
of irreplaceable music and no amount of read-only care makes it the right
|
||
thing to point a half-finished feature at. `scripts/make_dev_library.py`
|
||
builds a synthetic one that has the same *shapes* — every playlist type
|
||
(regular, folder, live/non-live/unsupported smart, system, empty,
|
||
duplicates), six container formats, art on some albums and not others, a
|
||
play journal, a tombstone, and a deliberate pile of naming edge cases (a
|
||
collision pair differing only by id, an emoji album, a 208-character title,
|
||
forbidden characters, a dangling location). Build it with
|
||
`python3 scripts/make_dev_library.py --out dev-library` and run against it
|
||
with `--data-dir dev-library/data`; it's gitignored, the generator isn't.
|
||
When a feature needs a shape the fixture lacks, **add it to the generator**
|
||
rather than reaching for the real library.
|
||
|
||
- `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).
|