From 75e05164341e5b2413f53b78fd328364c1619e29 Mon Sep 17 00:00:00 2001 From: Chris Date: Tue, 22 Sep 2026 16:48:55 -0700 Subject: [PATCH] Drop Artist/Album/Title depth assumptions from layout checks Matching has always been by relative path, so any folder layout works as long as both libraries use the same one. Remove the depth and loose-root-file warnings, which flagged valid layouts, and reword the UI and README to say "same folder layout on both sides" with Artist/Album/Title.ext only as an example. The "elsewhere" fallback is now described as same top-level folder, different subfolder. Add a test covering flat and deeply nested layouts. Co-Authored-By: Claude Opus 5.5 --- README.md | 12 ++++++++---- internal/engine/engine.go | 19 +++++++++---------- internal/engine/engine_test.go | 25 +++++++++++++++++++++++++ internal/engine/scan.go | 18 ++++-------------- internal/store/models.go | 2 +- web/dist/.gitkeep | 0 web/src/pages/Build.tsx | 4 ++-- web/src/pages/PairForm.tsx | 3 ++- web/src/pages/Review.tsx | 2 +- 9 files changed, 52 insertions(+), 33 deletions(-) delete mode 100644 web/dist/.gitkeep diff --git a/README.md b/README.md index db0d427..e9c0dda 100644 --- a/README.md +++ b/README.md @@ -9,13 +9,17 @@ It ships as a single Go binary with an embedded React web UI and SQLite state, p ## What it does +Files are matched by their **path relative to each library root**. Any folder layout works (`Artist/Album/Title.ext`, +`Genre/Artist/Title.ext`, flat, …) as long as both libraries use the same one, so that a song sits at the same relative +path on both sides. The fallbacks below catch small differences, and a scan warns when the two layouts don't line up. + | Situation | What playlink does | |---|---| -| Same `Artist/Album/Title.ext` path, **byte-identical** | Status `identical`. Link with one click, in bulk, or automatically after each scan. | +| Same relative path, **byte-identical** | Status `identical`. Link with one click, in bulk, or automatically after each scan. | | Same path, **different bytes** (re-encode, different tags) | Status `different`. Manual review with a codec/bitrate/bit-depth/duration comparison. | | Same title, **different format** (`Song.mp3` vs `Song.flac`) | Status `similar` (other format). Manual review. | | Same title after ignoring track numbers/punctuation (`01 - Song!.flac` vs `Song.mp3`) | Status `similar` (similar title). Manual review. | -| Same artist and title, but in a **different album folder** | Status `similar` (other album folder). Manual review, plus a layout warning. | +| Same top-level folder and title, but a **different subfolder** | Status `similar` (same top folder, other subfolder). Manual review. | | Only exists in the slave library | Status `unmatched`. Never touched. | | Already the same inode | Status `linked`. | @@ -28,8 +32,8 @@ codec-weighted bitrate (Opus and AAC count for more per kbps than MP3). You then libraries share the better file. - **Ignore.** The pair is hidden from review until you un-ignore it. -**Build mode** covers the "start fresh" workflow. Point the slave at an empty folder, browse the host library by artist and album, tick -what you want, and playlink hardlinks it in at the same path. **Remove** deletes slave files, but only ones that are hardlinks of the +**Build mode** covers the "start fresh" workflow. Point the slave at an empty folder, browse the host library, tick the +folders or songs you want, and playlink hardlinks them in at the same relative path. **Remove** deletes slave files, but only ones that are hardlinks of the host file. ## Safety model diff --git a/internal/engine/engine.go b/internal/engine/engine.go index 1787eb0..a9f5266 100644 --- a/internal/engine/engine.go +++ b/internal/engine/engine.go @@ -293,9 +293,11 @@ func (e *Engine) NormalizePair(p *store.Pair) ([]string, error) { } // layoutWarnings does a cheap top-level comparison of the two libraries. +// Any folder layout works; what matters is that both libraries use the same +// one, so matching files sit at the same relative path. func layoutWarnings(l *libs) []string { var warns []string - list := func(root string) (dirs map[string]bool, looseFiles int) { + list := func(root string) (dirs map[string]bool, files int) { dirs = map[string]bool{} ents, _ := os.ReadDir(root) for _, en := range ents { @@ -305,20 +307,17 @@ func layoutWarnings(l *libs) []string { if en.IsDir() { dirs[strings.ToLower(en.Name())] = true } else if l.hasExt(en.Name()) { - looseFiles++ + files++ } } return } - hd, hl := list(l.host.Path) - sd, sl := list(l.slave.Path) - if len(sd) == 0 && sl == 0 { + hd, _ := list(l.host.Path) + sd, sf := list(l.slave.Path) + if len(sd) == 0 && sf == 0 { warns = append(warns, "The slave library is empty. Use Build to pick songs from the host library to hardlink into it.") return warns } - if hl > 0 || sl > 0 { - warns = append(warns, fmt.Sprintf("Found audio files directly in a library root (host: %d, slave: %d). Both libraries should use Artist/Album/Title.ext.", hl, sl)) - } shared := 0 for d := range sd { if hd[d] { @@ -326,8 +325,8 @@ func layoutWarnings(l *libs) []string { } } if len(sd) > 0 && shared*2 < len(sd) { - warns = append(warns, fmt.Sprintf("Only %d of %d artist folders in the slave library also exist in the host library. "+ - "The two libraries should share the same Artist/Album/Title.ext layout, or most files will not match.", shared, len(sd))) + warns = append(warns, fmt.Sprintf("Only %d of %d top-level folders in the slave library also exist in the host library. "+ + "Both libraries should use the same folder layout, or most files will not match.", shared, len(sd))) } return warns } diff --git a/internal/engine/engine_test.go b/internal/engine/engine_test.go index d4b87d1..8eeb658 100644 --- a/internal/engine/engine_test.go +++ b/internal/engine/engine_test.go @@ -9,6 +9,7 @@ import ( "log/slog" "os" "path/filepath" + "strings" "testing" "time" @@ -479,3 +480,27 @@ func TestNormTitle(t *testing.T) { } } } + +func TestAnyLayoutMatchesWithoutWarnings(t *testing.T) { + ev := setup(t, false) + // Flat files, deeper Genre/Artist/Album/Disc nesting: all fine as long as both sides agree. + for _, rel := range []string{"loose.flac", "Rock/Band/Album/Disc 1/01 - Song.flac", "Band/Song.flac"} { + ev.write(ev.host, rel, "same:"+rel) + ev.write(ev.slave, rel, "same:"+rel) + } + ev.scan() + for _, rel := range []string{"loose.flac", "Rock/Band/Album/Disc 1/01 - Song.flac", "Band/Song.flac"} { + if m := ev.match(rel); m.Status != store.StatusIdentical || m.Kind != store.KindPath { + t.Fatalf("%s: want identical/path, got %s/%s", rel, m.Status, m.Kind) + } + } + p, err := ev.st.Pair(ctx, ev.pair.ID) + if err != nil { + t.Fatal(err) + } + for _, w := range p.LastScanWarnings { + if strings.Contains(w, "layout") || strings.Contains(w, "folder") || strings.Contains(w, "depth") { + t.Fatalf("matching layouts must not produce layout warnings, got %q", w) + } + } +} diff --git a/internal/engine/scan.go b/internal/engine/scan.go index 9218bb2..1a3ca66 100644 --- a/internal/engine/scan.go +++ b/internal/engine/scan.go @@ -20,7 +20,6 @@ import ( type walkStats struct { files int symlinks int - offDepth int // files not at Artist/Album/Title depth } // walk lists audio files beneath root. Hidden entries, playlink staging files, @@ -67,9 +66,6 @@ func walk(ctx context.Context, l *libs, root fsops.Root, out map[string]fsops.In } out[rel] = in ws.files++ - if strings.Count(rel, string(filepath.Separator)) != 2 { - ws.offDepth++ - } return nil }) return ws, err @@ -107,7 +103,7 @@ type hostIndex struct { files map[string]fsops.Info lower map[string]string // lower(rel) -> rel byDir map[string][]string // lower(dir) -> rels - byTitle map[string][]string // lower(artist)|normTitle -> rels + byTitle map[string][]string // lower(top folder)|normTitle -> rels } func buildIndex(files map[string]fsops.Info) *hostIndex { @@ -167,8 +163,8 @@ func (ix *hostIndex) find(relSlave string) (string, string) { if len(fuzzyHits) == 1 { return fuzzyHits[0], store.KindFuzzy } - if artist := firstComponent(relSlave); artist != "" && norm != "" { - if hits := ix.byTitle[strings.ToLower(artist)+"|"+norm]; len(hits) == 1 { + if top := firstComponent(relSlave); top != "" && norm != "" { + if hits := ix.byTitle[strings.ToLower(top)+"|"+norm]; len(hits) == 1 { return hits[0], store.KindElsewhere } } @@ -310,14 +306,8 @@ func (e *Engine) scan(ctx context.Context, j *Job, pairID int64, trigger string) if ss.files > 0 { if n := kinds[store.KindElsewhere] + kinds[store.KindNone]; n*4 > ss.files { warns = append(warns, fmt.Sprintf("%d of %d slave files have no counterpart at the same path in the host library. "+ - "Check that both libraries use the same Artist/Album/Title.ext layout.", n, ss.files)) + "Check that both libraries use the same folder layout.", n, ss.files)) } - if ss.offDepth > 0 { - warns = append(warns, fmt.Sprintf("%d slave files are not at Artist/Album/Title.ext depth.", ss.offDepth)) - } - } - if hs.offDepth > 0 { - warns = append(warns, fmt.Sprintf("%d host files are not at Artist/Album/Title.ext depth.", hs.offDepth)) } if hs.symlinks+ss.symlinks > 0 { warns = append(warns, fmt.Sprintf("Ignored %d symlinks (playlink never follows or replaces symlinks).", hs.symlinks+ss.symlinks)) diff --git a/internal/store/models.go b/internal/store/models.go index ffd65c3..7b9a181 100644 --- a/internal/store/models.go +++ b/internal/store/models.go @@ -220,7 +220,7 @@ const ( KindPathCase = "path_case" // relative path differs only by case KindExtension = "extension" // same directory and title, different extension KindFuzzy = "fuzzy" // same directory, normalized title matches - KindElsewhere = "elsewhere" // same artist, different album folder + KindElsewhere = "elsewhere" // same top-level folder and title, different subfolder KindNone = "none" ) diff --git a/web/dist/.gitkeep b/web/dist/.gitkeep deleted file mode 100644 index e69de29..0000000 diff --git a/web/src/pages/Build.tsx b/web/src/pages/Build.tsx index e432a28..838fd9a 100644 --- a/web/src/pages/Build.tsx +++ b/web/src/pages/Build.tsx @@ -39,8 +39,8 @@ export function Build({ pair }: { pair: Pair }) { return (
- Build the slave library from the host. Browse the host library, pick artists, albums or songs, and playlink hardlinks them into the slave - library at the same Artist/Album/Title.ext path. No extra space is used. Existing slave files are never + Build the slave library from the host. Browse the host library, pick folders or songs, and playlink hardlinks them into the slave + library at the same relative path. No extra space is used. Existing slave files are never overwritten, and Remove only deletes slave files that are hardlinks of the host file, so the host copy is always kept. diff --git a/web/src/pages/PairForm.tsx b/web/src/pages/PairForm.tsx index ad22cf3..11165a2 100644 --- a/web/src/pages/PairForm.tsx +++ b/web/src/pages/PairForm.tsx @@ -91,7 +91,8 @@ export function PairForm({ pair, open, onClose }: { pair?: Pair; open: boolean; />
- Both libraries should use the same Artist/Album/Title.ext layout. Files are matched by relative path first. + Both libraries should use the same folder layout (for example Artist/Album/Title.ext), because files are matched by + their relative path first. Any layout works as long as it is the same on both sides. Both must be on the same filesystem. On Unraid, mount one common parent folder into the container instead of two separate volumes. = { path_case: "path differs in case", extension: "other format", fuzzy: "similar title", - elsewhere: "other album folder", + elsewhere: "same top folder, other subfolder", none: "no match", };