Skip to content

Library foundation: per-track quality data + sorted-folder scan

jedmund requested to merge jedmund/quality-scanner-foundation into main

First of four PRs adding a unified Library view (replacing List + Artists) with at-a-glance audio quality. This one is server-only — no UI changes — and lays the data groundwork the next three PRs build on.

What changes

  • album_files: new codec, bit_depth, lossless columns. parseAudioMetadata was already getting these from music-metadata and dropping them; now they're persisted.
  • albums: new aggregated codec, bitrate, sample_rate, bit_depth columns. updateAlbumDuplicateInfo now writes the most-common track values alongside quality_score/quality_label so the upcoming list view renders without joining to album_files.
  • sorted_albums: new quality_score, quality_label, codec, bitrate, sample_rate, bit_depth columns. Previously sorted albums had no track metadata at all.
  • sorted_album_files (new table): mirrors album_files for the sorted side.
  • The sorted-folder scanner now walks each album's audio files, parses metadata, persists into sorted_album_files, and aggregates quality back onto sorted_albums. First scan after deploy is heavy (one-time per album); subsequent scans benefit from the cascade-delete reset that already happens at the top of scanSortedDirectory.
  • parseAudioMetadata no longer takes an albumId argument — the parsed result is now FK-agnostic so the same parser feeds both file tables.
  • The duplicate detector now respects qualityScore/qualityLabel on sorted albums (was hard-coded to 0/'Unknown (sorted)' before).

Why now

PR 2 introduces a <QualityBadge> and threshold settings; PR 3 rebuilds / as Library with a list view that shows codec/bitrate/sample-rate columns; PR 4 adds /artist/[key] with quality-tinted rows. None of that works without quality data on the sorted side, which today simply isn't captured.

Verification

  • pnpm run build passes.
  • After deploy, trigger a scan from Settings. New columns populate; sorted_album_files gets rows.
  • Spot-check: a known FLAC 24/96 sorted album should land with quality_label = 'FLAC 24/96kHz' and the matching aggregates.
  • Existing duplicate detection still works; quality label now reflects sorted-side files instead of being hard-coded.

Risk

Mostly additive. The parseAudioMetadata signature change touched the sort-quality probe in sorter.ts (now passes one arg instead of two). The first sorted scan after deploy will be slower than usual due to per-file metadata parsing — concurrency-bounded by the existing metadataQueue (10 in flight).

Merge request reports