minstrel/web/src/lib/components/FingerprintSettingsCard.svelte

<script lang="ts">
  import { onMount } from 'svelte';
  import { TriangleAlert } from 'lucide-svelte';
  import {
    getFingerprintSettings,
    updateFingerprintSettings,
    type FingerprintSettings
  } from '#lib/api/admin.js';
  import { errMessage } from '#lib/api/errors.js';
  import { pushToast } from '#lib/stores/toast.svelte.js';

  // How Minstrel fingerprints tracks and when it looks for duplicates (#3913).
  // Lives on the Duplicates page, beside the results these settings shape.

  let { libraryTotal = 0, onSaved }: { libraryTotal?: number; onSaved?: () => void } =
    $props();

  let saved = $state<FingerprintSettings | null>(null);
  let form = $state<FingerprintSettings | null>(null);
  let saving = $state(false);
  let loadError = $state(false);

  const dirty = $derived(!!saved && !!form && JSON.stringify(saved) !== JSON.stringify(form));

  // Stored as the share of bits two fingerprints may disagree on; the report
  // speaks in match percentages, so the card does too.
  const matchPercent = $derived(
    form ? Math.round((1 - form.acoustic_max_bit_error_rate) * 100) : 0
  );
  function onMatchInput(value: string) {
    if (!form) return;
    form.acoustic_max_bit_error_rate = value === '' ? NaN : Math.round(100 - Number(value)) / 100;
  }

  // The one setting with a cost the operator can't see from here: fingerprints
  // taken at two lengths can't be compared, so a new length redoes the library.
  const lengthChanged = $derived(
    !!saved && !!form && form.chromaprint_length_sec !== saved.chromaprint_length_sec
  );

  // Mirrors the server's ranges, so a bad value is named in the card's own terms
  // (a percentage, not a bit-error rate) before anything is sent.
  const between = (v: number, lo: number, hi: number) => Number.isInteger(v) && v >= lo && v <= hi;
  const problems = $derived.by(() => {
    if (!form) return [] as string[];
    const out: string[] = [];
    if (!between(form.chromaprint_length_sec, 30, 600))
      out.push('Seconds of audio must be a whole number from 30 to 600.');
    if (!between(matchPercent, 65, 99)) out.push('Minimum match must be from 65% to 99%.');
    if (!between(form.backfill_concurrency, 1, 8))
      out.push('Files fingerprinted at once must be from 1 to 8.');
    if (!between(form.sweep_interval_hours, 1, 168))
      out.push('Hours between sweeps must be from 1 to 168.');
    return out;
  });

  async function load() {
    try {
      saved = await getFingerprintSettings();
      form = { ...saved };
      loadError = false;
    } catch {
      loadError = true;
    }
  }

  onMount(load);

  async function save() {
    if (!form || problems.length > 0) return;
    saving = true;
    try {
      saved = await updateFingerprintSettings(form);
      form = { ...saved };
      pushToast('Fingerprinting settings saved.');
      onSaved?.();
    } catch (e) {
      pushToast(errMessage(e), 'error');
    } finally {
      saving = false;
    }
  }

  const inputClass =
    'mt-1 w-28 rounded border border-border bg-background px-2 py-1 text-sm text-text-primary ' +
    'focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-accent';
</script>

<section class="space-y-4 rounded-xl border border-border bg-surface p-5">
  <div>
    <h3 class="font-display text-lg font-medium text-text-primary">Fingerprinting</h3>
    <p class="mt-1 text-sm text-text-secondary">
      How tracks are fingerprinted, and how alike two must sound to be proposed as the same
      recording. Identical files are always found, whatever these say.
    </p>
  </div>

  {#if loadError}
    <p class="text-sm text-action-destructive">
      Couldn't load fingerprinting settings.
      <button type="button" class="underline hover:no-underline" onclick={load}>Try again</button>
    </p>
  {:else if form === null}
    <p class="text-sm text-text-secondary">Loading…</p>
  {:else}
    <label class="flex items-start gap-3">
      <input type="checkbox" bind:checked={form.enabled} class="mt-1" />
      <span>
        <span class="text-sm text-text-primary">Fingerprint tracks</span>
        <span class="block text-xs text-text-secondary">
          Off stops all audio decoding: new files aren't fingerprinted and the library isn't
          worked through in the background. Moved files are still recognised, because that only
          reads the file. Tracks without a fingerprint aren't compared.
        </span>
      </span>
    </label>

    <div class="grid gap-4 sm:grid-cols-2">
      <label class="block">
        <span class="text-sm text-text-primary">Seconds of audio to fingerprint</span>
        <span class="block text-xs text-text-secondary">
          More tells apart recordings that only differ later in the track, and takes longer for
          each file.
        </span>
        <input
          type="number"
          min="30"
          max="600"
          bind:value={form.chromaprint_length_sec}
          class={inputClass}
        />
      </label>

      <label class="block">
        <span class="text-sm text-text-primary">Minimum match (%)</span>
        <span class="block text-xs text-text-secondary">
          How alike two recordings must sound to be proposed as one. Higher proposes fewer, surer
          groups. Unrelated songs score around 50%.
        </span>
        <input
          type="number"
          min="65"
          max="99"
          value={matchPercent}
          oninput={(e) => onMatchInput(e.currentTarget.value)}
          class={inputClass}
        />
      </label>

      <label class="block">
        <span class="text-sm text-text-primary">Files fingerprinted at once</span>
        <span class="block text-xs text-text-secondary">
          The background pass competes with playback for CPU and with streaming for the disk.
          Lower it if playback stutters while it runs.
        </span>
        <input
          type="number"
          min="1"
          max="8"
          bind:value={form.backfill_concurrency}
          class={inputClass}
        />
      </label>

      <label class="block">
        <span class="text-sm text-text-primary">Hours between sweeps</span>
        <span class="block text-xs text-text-secondary">
          The least time between automatic duplicate sweeps. A sweep only runs when something has
          changed, and Sweep now doesn't wait.
        </span>
        <input
          type="number"
          min="1"
          max="168"
          bind:value={form.sweep_interval_hours}
          class={inputClass}
        />
      </label>
    </div>

    {#if lengthChanged}
      <p
        class="flex items-start gap-2 rounded-md bg-surface-hover px-3 py-2 text-xs text-text-secondary"
        data-testid="length-warning"
      >
        <TriangleAlert size={14} class="mt-0.5 shrink-0 text-action-destructive" aria-hidden="true" />
        <span>
          Saving re-fingerprints {libraryTotal > 0
            ? `all ${libraryTotal.toLocaleString()} tracks`
            : 'every track'} at the new length. Fingerprints taken at different lengths can't be
          compared, so a track is left out of the duplicate search until it's redone, and groups
          of similar recordings come back as that work finishes.
        </span>
      </p>
    {/if}

    {#if problems.length > 0}
      <ul class="space-y-1 text-xs text-action-destructive" data-testid="settings-problems">
        {#each problems as problem (problem)}
          <li>{problem}</li>
        {/each}
      </ul>
    {/if}

    <div class="flex justify-end">
      <button
        type="button"
        class="rounded-md bg-action-secondary px-4 py-2 text-sm text-action-fg hover:opacity-90
               focus-visible:outline-solid focus-visible:outline-2 focus-visible:outline-accent
               disabled:cursor-not-allowed disabled:opacity-50"
        disabled={!dirty || saving || problems.length > 0}
        onclick={save}
      >
        {saving ? 'Saving…' : 'Save'}
      </button>
    </div>
  {/if}
</section>