feat(admin): fingerprinting settings — on/off, length, match threshold, concurrency, sweep interval (M400 #3913)

Rule 25: the fingerprinting knobs move out of source into a DB-backed
singleton (migration 0061), edited from a card on the Duplicates page and
shared live with the scanner, the backfill and the duplicate sweep through
one service instance, so a save needs no restart.

The length is the knob that can silently break the library: prints taken
at two lengths never match. Each track_fingerprints row now records the
length it was taken at, and every reader filters on the current one — the
backfill treats another length as stale, the gauge counts it pending, the
sweep never streams it. Equivalent to a version bump, except that setting
the length back makes rows not yet redone current again. The card warns
before a length change re-fingerprints the library.

Off stops every decode: the scan takes only the stream hash (a demux, and
what recognises a moved file) and stores nothing, dropping a changed file's
stale row; the backfill idles. A save also makes a sweep due, since a new
threshold or length changes what the same prints group into, and the sweep
interval gains slack so an hourly interval on an hourly tick doesn't skip
every other tick.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SQ31KQpYbStyK5y58UmPLH

internal/db/dbq/duplicates.sql.go

@@ -211,16 +211,21 @@ SELECT t.id, t.duration_ms, f.audio_stream_sha256, f.chromaprint
  WHERE t.missing_since IS NULL
    AND f.fingerprint_version >= $1
    AND f.chromaprint IS NOT NULL
-   AND (t.duration_ms, t.id) > ($2::integer, $3::uuid)
+   -- Only chromaprints taken at the current length: prints at two lengths are not
+   -- comparable, and after a length change the backfill is still re-deriving the
+   -- rest (#3913).
+   AND f.chromaprint_length_sec = $2
+   AND (t.duration_ms, t.id) > ($3::integer, $4::uuid)
  ORDER BY t.duration_ms, t.id
- LIMIT $4
+ LIMIT $5
 `
 
 type ListDuplicateCandidatesParams struct {
-	CurrentVersion  int16
-	AfterDurationMs int32
-	AfterID         pgtype.UUID
-	PageLimit       int32
+	CurrentVersion       int16
+	ChromaprintLengthSec int32
+	AfterDurationMs      int32
+	AfterID              pgtype.UUID
+	PageLimit            int32
 }
 
 type ListDuplicateCandidatesRow struct {
@@ -237,6 +242,7 @@ type ListDuplicateCandidatesRow struct {
 func (q *Queries) ListDuplicateCandidates(ctx context.Context, arg ListDuplicateCandidatesParams) ([]ListDuplicateCandidatesRow, error) {
 	rows, err := q.db.Query(ctx, listDuplicateCandidates,
 		arg.CurrentVersion,
+		arg.ChromaprintLengthSec,
 		arg.AfterDurationMs,
 		arg.AfterID,
 		arg.PageLimit,

internal/db/dbq/fingerprint_settings.sql.go

@@ -0,0 +1,72 @@
+// Code generated by sqlc. DO NOT EDIT.
+// versions:
+//   sqlc v1.31.1
+// source: fingerprint_settings.sql
+
+package dbq
+
+import (
+	"context"
+)
+
+const getFingerprintSettings = `-- name: GetFingerprintSettings :one
+SELECT id, enabled, chromaprint_length_sec, acoustic_max_bit_error_rate, backfill_concurrency, sweep_interval_hours, updated_at FROM fingerprint_settings WHERE id = true
+`
+
+func (q *Queries) GetFingerprintSettings(ctx context.Context) (FingerprintSetting, error) {
+	row := q.db.QueryRow(ctx, getFingerprintSettings)
+	var i FingerprintSetting
+	err := row.Scan(
+		&i.ID,
+		&i.Enabled,
+		&i.ChromaprintLengthSec,
+		&i.AcousticMaxBitErrorRate,
+		&i.BackfillConcurrency,
+		&i.SweepIntervalHours,
+		&i.UpdatedAt,
+	)
+	return i, err
+}
+
+const updateFingerprintSettings = `-- name: UpdateFingerprintSettings :one
+UPDATE fingerprint_settings
+   SET enabled                     = $1,
+       chromaprint_length_sec      = $2,
+       acoustic_max_bit_error_rate = $3,
+       backfill_concurrency        = $4,
+       sweep_interval_hours        = $5,
+       updated_at                  = now()
+ WHERE id = true
+RETURNING id, enabled, chromaprint_length_sec, acoustic_max_bit_error_rate, backfill_concurrency, sweep_interval_hours, updated_at
+`
+
+type UpdateFingerprintSettingsParams struct {
+	Enabled                 bool
+	ChromaprintLengthSec    int32
+	AcousticMaxBitErrorRate float64
+	BackfillConcurrency     int32
+	SweepIntervalHours      int32
+}
+
+// Whole-row write from the admin card; migration 0061's CHECKs are the backstop
+// behind the service's own validation.
+func (q *Queries) UpdateFingerprintSettings(ctx context.Context, arg UpdateFingerprintSettingsParams) (FingerprintSetting, error) {
+	row := q.db.QueryRow(ctx, updateFingerprintSettings,
+		arg.Enabled,
+		arg.ChromaprintLengthSec,
+		arg.AcousticMaxBitErrorRate,
+		arg.BackfillConcurrency,
+		arg.SweepIntervalHours,
+	)
+	var i FingerprintSetting
+	err := row.Scan(
+		&i.ID,
+		&i.Enabled,
+		&i.ChromaprintLengthSec,
+		&i.AcousticMaxBitErrorRate,
+		&i.BackfillConcurrency,
+		&i.SweepIntervalHours,
+		&i.UpdatedAt,
+	)
+	return i, err
+}

internal/db/dbq/fingerprints.sql.go

@@ -27,20 +27,29 @@ const getFingerprintCoverage = `-- name: GetFingerprintCoverage :one
 SELECT count(*)::bigint AS total,
        count(*) FILTER (
            WHERE f.fingerprint_version >= $1
+             AND f.chromaprint_length_sec = $2
              AND f.audio_stream_sha256 IS NOT NULL AND f.chromaprint IS NOT NULL
        )::bigint AS fingerprinted,
        count(*) FILTER (
            WHERE f.fingerprint_version >= $1
+             AND f.chromaprint_length_sec = $2
              AND (f.audio_stream_sha256 IS NULL OR f.chromaprint IS NULL)
        )::bigint AS rejected,
        count(*) FILTER (
-           WHERE f.track_id IS NULL OR f.fingerprint_version < $1
+           WHERE f.track_id IS NULL
+              OR f.fingerprint_version < $1
+              OR f.chromaprint_length_sec <> $2
        )::bigint AS pending
   FROM tracks t
   LEFT JOIN track_fingerprints f ON f.track_id = t.id
  WHERE t.missing_since IS NULL
 `
 
+type GetFingerprintCoverageParams struct {
+	CurrentVersion       int16
+	ChromaprintLengthSec int32
+}
+
 type GetFingerprintCoverageRow struct {
 	Total         int64
 	Fingerprinted int64
@@ -49,11 +58,13 @@ type GetFingerprintCoverageRow struct {
 }
 
 // The admin gauge for the backfill. fingerprinted + rejected + pending = total.
-// rejected is a row at the current version with a NULL half: a tool ran and
-// refused the file, which is settled rather than waiting. Missing tracks are
-// excluded, or the gauge could never reach the end.
-func (q *Queries) GetFingerprintCoverage(ctx context.Context, currentVersion int16) (GetFingerprintCoverageRow, error) {
-	row := q.db.QueryRow(ctx, getFingerprintCoverage, currentVersion)
+// "Current" means derived by the current method AT the current length: a row at
+// another length is pending, because the backfill will re-derive it. rejected is
+// a current row with a NULL half: a tool ran and refused the file, which is
+// settled rather than waiting. Missing tracks are excluded, or the gauge could
+// never reach the end.
+func (q *Queries) GetFingerprintCoverage(ctx context.Context, arg GetFingerprintCoverageParams) (GetFingerprintCoverageRow, error) {
+	row := q.db.QueryRow(ctx, getFingerprintCoverage, arg.CurrentVersion, arg.ChromaprintLengthSec)
 	var i GetFingerprintCoverageRow
 	err := row.Scan(
 		&i.Total,
@@ -69,16 +80,21 @@ SELECT t.id, t.file_path
   FROM tracks t
   LEFT JOIN track_fingerprints f ON f.track_id = t.id
  WHERE t.missing_since IS NULL
-   AND (f.track_id IS NULL OR f.fingerprint_version < $1)
-   AND t.id > $2
+   -- A row taken at another length is as stale as one from an older method:
+   -- chromaprints at two lengths cannot be compared (#3913).
+   AND (f.track_id IS NULL
+        OR f.fingerprint_version < $1
+        OR f.chromaprint_length_sec <> $2)
+   AND t.id > $3
  ORDER BY t.id
- LIMIT $3
+ LIMIT $4
 `
 
 type ListTracksNeedingFingerprintParams struct {
-	CurrentVersion int16
-	AfterID        pgtype.UUID
-	BatchLimit     int32
+	CurrentVersion       int16
+	ChromaprintLengthSec int32
+	AfterID              pgtype.UUID
+	BatchLimit           int32
 }
 
 type ListTracksNeedingFingerprintRow struct {
@@ -93,7 +109,12 @@ type ListTracksNeedingFingerprintRow struct {
 // and retried in a tight loop. Missing tracks are skipped — there is no file to
 // read.
 func (q *Queries) ListTracksNeedingFingerprint(ctx context.Context, arg ListTracksNeedingFingerprintParams) ([]ListTracksNeedingFingerprintRow, error) {
-	rows, err := q.db.Query(ctx, listTracksNeedingFingerprint, arg.CurrentVersion, arg.AfterID, arg.BatchLimit)
+	rows, err := q.db.Query(ctx, listTracksNeedingFingerprint,
+		arg.CurrentVersion,
+		arg.ChromaprintLengthSec,
+		arg.AfterID,
+		arg.BatchLimit,
+	)
 	if err != nil {
 		return nil, err
 	}
@@ -114,23 +135,25 @@ func (q *Queries) ListTracksNeedingFingerprint(ctx context.Context, arg ListTrac
 
 const upsertTrackFingerprint = `-- name: UpsertTrackFingerprint :exec
 INSERT INTO track_fingerprints (
-    track_id, audio_stream_sha256, chromaprint, fingerprint_version
+    track_id, audio_stream_sha256, chromaprint, fingerprint_version, chromaprint_length_sec
 ) VALUES (
     $1, $2, $3,
-    $4
+    $4, $5
 )
 ON CONFLICT (track_id) DO UPDATE SET
-    audio_stream_sha256 = EXCLUDED.audio_stream_sha256,
-    chromaprint         = EXCLUDED.chromaprint,
-    fingerprint_version = EXCLUDED.fingerprint_version,
-    computed_at         = now()
+    audio_stream_sha256    = EXCLUDED.audio_stream_sha256,
+    chromaprint            = EXCLUDED.chromaprint,
+    fingerprint_version    = EXCLUDED.fingerprint_version,
+    chromaprint_length_sec = EXCLUDED.chromaprint_length_sec,
+    computed_at            = now()
 `
 
 type UpsertTrackFingerprintParams struct {
-	TrackID            pgtype.UUID
-	AudioStreamSha256  []byte
-	Chromaprint        []int32
-	FingerprintVersion int16
+	TrackID              pgtype.UUID
+	AudioStreamSha256    []byte
+	Chromaprint          []int32
+	FingerprintVersion   int16
+	ChromaprintLengthSec int32
 }
 
 // Written whenever a track's fingerprint is derived: by the scan when a file is
@@ -143,6 +166,7 @@ func (q *Queries) UpsertTrackFingerprint(ctx context.Context, arg UpsertTrackFin
 		arg.AudioStreamSha256,
 		arg.Chromaprint,
 		arg.FingerprintVersion,
+		arg.ChromaprintLengthSec,
 	)
 	return err
 }

internal/db/dbq/models.go

@@ -323,6 +323,16 @@ type DuplicateSweep struct {
 	ErrorMessage     *string
 }
 
+type FingerprintSetting struct {
+	ID                      bool
+	Enabled                 bool
+	ChromaprintLengthSec    int32
+	AcousticMaxBitErrorRate float64
+	BackfillConcurrency     int32
+	SweepIntervalHours      int32
+	UpdatedAt               pgtype.Timestamptz
+}
+
 type GeneralLike struct {
 	UserID  pgtype.UUID
 	TrackID pgtype.UUID
@@ -694,11 +704,12 @@ type Track struct {
 }
 
 type TrackFingerprint struct {
-	TrackID            pgtype.UUID
-	AudioStreamSha256  []byte
-	Chromaprint        []int32
-	FingerprintVersion int16
-	ComputedAt         pgtype.Timestamptz
+	TrackID              pgtype.UUID
+	AudioStreamSha256    []byte
+	Chromaprint          []int32
+	FingerprintVersion   int16
+	ComputedAt           pgtype.Timestamptz
+	ChromaprintLengthSec int32
 }
 
 type TrackSimilarity struct {

internal/db/migrations/0061_fingerprint_settings.down.sql

@@ -0,0 +1,2 @@
+ALTER TABLE track_fingerprints DROP COLUMN chromaprint_length_sec;
+DROP TABLE fingerprint_settings;

internal/db/migrations/0061_fingerprint_settings.up.sql

@@ -0,0 +1,50 @@
+-- 0061_fingerprint_settings.up.sql — fingerprinting's knobs, in admin Settings
+-- (Scribe #3913, milestone #400). Rule 25: anything an operator might tune is a
+-- database row, changed without a restart. Singleton in the style of
+-- reacquisition_settings (0056).
+CREATE TABLE fingerprint_settings (
+    id                          boolean PRIMARY KEY DEFAULT true,
+
+    -- Fingerprinting new files, the backfill, and the duplicate sweep. Off stops
+    -- the decode work entirely — the reason to turn it off is a slow NAS, and
+    -- that is the operator's call. On by default: a library that cannot tell its
+    -- duplicates apart is what milestone #400 exists to end.
+    enabled                     boolean NOT NULL DEFAULT true,
+
+    -- Seconds of audio fpcalc fingerprints. Chromaprints taken at different
+    -- lengths cannot be compared, which is why track_fingerprints records the
+    -- length each row was taken at (below): change this and every chromaprint is
+    -- re-derived, and until then only rows at the new length are compared.
+    chromaprint_length_sec      integer NOT NULL DEFAULT 120,
+
+    -- The most disagreement two aligned fingerprints may show and still be
+    -- proposed as one recording. Unrelated audio sits near 0.5, so the ceiling
+    -- stays well clear of it.
+    acoustic_max_bit_error_rate double precision NOT NULL DEFAULT 0.15,
+
+    -- Files the backfill decodes at once. Decoding competes with playback
+    -- transcoding for CPU and with streaming for the mount.
+    backfill_concurrency        integer NOT NULL DEFAULT 2,
+
+    -- The least time between duplicate sweeps. A sweep still runs only when
+    -- fingerprints have changed since the last one.
+    sweep_interval_hours        integer NOT NULL DEFAULT 1,
+
+    -- When the settings were last saved. A new threshold or length can change
+    -- what a sweep finds, so a save makes a sweep due.
+    updated_at                  timestamptz NOT NULL DEFAULT now(),
+
+    CONSTRAINT fingerprint_settings_singleton CHECK (id = true),
+    CONSTRAINT fingerprint_settings_length_range
+        CHECK (chromaprint_length_sec >= 30 AND chromaprint_length_sec <= 600),
+    CONSTRAINT fingerprint_settings_threshold_range
+        CHECK (acoustic_max_bit_error_rate >= 0.01 AND acoustic_max_bit_error_rate <= 0.35),
+    CONSTRAINT fingerprint_settings_concurrency_range
+        CHECK (backfill_concurrency >= 1 AND backfill_concurrency <= 8),
+    CONSTRAINT fingerprint_settings_sweep_interval_range
+        CHECK (sweep_interval_hours >= 1 AND sweep_interval_hours <= 168)
+);
+INSERT INTO fingerprint_settings (id) VALUES (true) ON CONFLICT (id) DO NOTHING;
+
+-- Every row written so far was taken at fpcalc's default length.
+ALTER TABLE track_fingerprints ADD COLUMN chromaprint_length_sec integer NOT NULL DEFAULT 120;

internal/db/queries/duplicates.sql

@@ -53,6 +53,10 @@ SELECT t.id, t.duration_ms, f.audio_stream_sha256, f.chromaprint
  WHERE t.missing_since IS NULL
    AND f.fingerprint_version >= sqlc.arg(current_version)
    AND f.chromaprint IS NOT NULL
+   -- Only chromaprints taken at the current length: prints at two lengths are not
+   -- comparable, and after a length change the backfill is still re-deriving the
+   -- rest (#3913).
+   AND f.chromaprint_length_sec = sqlc.arg(chromaprint_length_sec)
    AND (t.duration_ms, t.id) > (sqlc.arg(after_duration_ms)::integer, sqlc.arg(after_id)::uuid)
  ORDER BY t.duration_ms, t.id
  LIMIT sqlc.arg(page_limit);

internal/db/queries/fingerprint_settings.sql

@@ -0,0 +1,15 @@
+-- name: GetFingerprintSettings :one
+SELECT * FROM fingerprint_settings WHERE id = true;
+
+-- name: UpdateFingerprintSettings :one
+-- Whole-row write from the admin card; migration 0061's CHECKs are the backstop
+-- behind the service's own validation.
+UPDATE fingerprint_settings
+   SET enabled                     = sqlc.arg(enabled),
+       chromaprint_length_sec      = sqlc.arg(chromaprint_length_sec),
+       acoustic_max_bit_error_rate = sqlc.arg(acoustic_max_bit_error_rate),
+       backfill_concurrency        = sqlc.arg(backfill_concurrency),
+       sweep_interval_hours        = sqlc.arg(sweep_interval_hours),
+       updated_at                  = now()
+ WHERE id = true
+RETURNING *;

internal/db/queries/fingerprints.sql

@@ -4,16 +4,17 @@
 -- older method. Replaces the row wholesale — a fingerprint of the old bytes has
 -- no standing once the file has changed.
 INSERT INTO track_fingerprints (
-    track_id, audio_stream_sha256, chromaprint, fingerprint_version
+    track_id, audio_stream_sha256, chromaprint, fingerprint_version, chromaprint_length_sec
 ) VALUES (
     sqlc.arg(track_id), sqlc.narg(audio_stream_sha256), sqlc.narg(chromaprint),
-    sqlc.arg(fingerprint_version)
+    sqlc.arg(fingerprint_version), sqlc.arg(chromaprint_length_sec)
 )
 ON CONFLICT (track_id) DO UPDATE SET
-    audio_stream_sha256 = EXCLUDED.audio_stream_sha256,
-    chromaprint         = EXCLUDED.chromaprint,
-    fingerprint_version = EXCLUDED.fingerprint_version,
-    computed_at         = now();
+    audio_stream_sha256    = EXCLUDED.audio_stream_sha256,
+    chromaprint            = EXCLUDED.chromaprint,
+    fingerprint_version    = EXCLUDED.fingerprint_version,
+    chromaprint_length_sec = EXCLUDED.chromaprint_length_sec,
+    computed_at            = now();
 
 -- name: DeleteTrackFingerprint :exec
 -- A file changed but could not be fingerprinted, for a reason unrelated to the
@@ -32,27 +33,37 @@ SELECT t.id, t.file_path
   FROM tracks t
   LEFT JOIN track_fingerprints f ON f.track_id = t.id
  WHERE t.missing_since IS NULL
-   AND (f.track_id IS NULL OR f.fingerprint_version < sqlc.arg(current_version))
+   -- A row taken at another length is as stale as one from an older method:
+   -- chromaprints at two lengths cannot be compared (#3913).
+   AND (f.track_id IS NULL
+        OR f.fingerprint_version < sqlc.arg(current_version)
+        OR f.chromaprint_length_sec <> sqlc.arg(chromaprint_length_sec))
    AND t.id > sqlc.arg(after_id)
  ORDER BY t.id
  LIMIT sqlc.arg(batch_limit);
 
 -- name: GetFingerprintCoverage :one
 -- The admin gauge for the backfill. fingerprinted + rejected + pending = total.
--- rejected is a row at the current version with a NULL half: a tool ran and
--- refused the file, which is settled rather than waiting. Missing tracks are
--- excluded, or the gauge could never reach the end.
+-- "Current" means derived by the current method AT the current length: a row at
+-- another length is pending, because the backfill will re-derive it. rejected is
+-- a current row with a NULL half: a tool ran and refused the file, which is
+-- settled rather than waiting. Missing tracks are excluded, or the gauge could
+-- never reach the end.
 SELECT count(*)::bigint AS total,
        count(*) FILTER (
            WHERE f.fingerprint_version >= sqlc.arg(current_version)
+             AND f.chromaprint_length_sec = sqlc.arg(chromaprint_length_sec)
              AND f.audio_stream_sha256 IS NOT NULL AND f.chromaprint IS NOT NULL
        )::bigint AS fingerprinted,
        count(*) FILTER (
            WHERE f.fingerprint_version >= sqlc.arg(current_version)
+             AND f.chromaprint_length_sec = sqlc.arg(chromaprint_length_sec)
              AND (f.audio_stream_sha256 IS NULL OR f.chromaprint IS NULL)
        )::bigint AS rejected,
        count(*) FILTER (
-           WHERE f.track_id IS NULL OR f.fingerprint_version < sqlc.arg(current_version)
+           WHERE f.track_id IS NULL
+              OR f.fingerprint_version < sqlc.arg(current_version)
+              OR f.chromaprint_length_sec <> sqlc.arg(chromaprint_length_sec)
        )::bigint AS pending
   FROM tracks t
   LEFT JOIN track_fingerprints f ON f.track_id = t.id