feat: the backup can include the music, sending each library file once to music/ and again only when it changes (#6774)

With "Include the music" on, each night's run sends the library files the
destination doesn't hold yet, after the database file has landed, for up to
six hours; a large library spans several nights the first time. Files keep
their path under the library folders' common root, beside database/ in the
same folder or bucket.

backup_music_files records each file's size and mtime as sent, so a night
sends only new and changed files, and a rescan that touches a track but finds
the same file sends nothing. A changed file goes to its old name; Minstrel
never deletes there. An object the bucket refuses (a locked overwrite) is
kept with its answer and goes again once the file changes or the settings are
saved; three refusals in a row stop the night's music, since that is a key
that may not write under music/. A folder copy is written under a .part name
and renamed, keeping the file's time.

The panel shows how much of the library is in, the refused files, and each
run's music count and note. The verdict still turns on the database file.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

web/src/lib/api/admin.ts

@@ -1104,6 +1104,8 @@ export type BackupConfig = {
   run_hour: number;
   /** KiB a second an upload to the bucket may use; 0 is no limit. */
   upload_limit_kib: number;
+  /** Also send the library's music files, each once, to music/. */
+  include_music: boolean;
 };
 
 export type BackupState = 'off' | 'incomplete' | 'failing' | 'waiting' | 'overdue' | 'ok';
@@ -1118,6 +1120,23 @@ export type BackupRun = {
   location: string;
   bytes: number;
   error: string;
+  /** What the run sent of the music, and why it stopped early, if it did. */
+  music_files: number;
+  music_bytes: number;
+  music_note: string;
+};
+
+/** A library file the destination wouldn't take; tried again once it changes. */
+export type BackupRefusedFile = { path: string; error: string; at: string };
+
+/** How much of the library the backup holds as it is now. */
+export type BackupMusicProgress = {
+  total_files: number;
+  total_bytes: number;
+  sent_files: number;
+  sent_bytes: number;
+  refused_files: number;
+  refused: BackupRefusedFile[];
 };
 
 export type BackupStatus = {
@@ -1132,6 +1151,8 @@ export type BackupStatus = {
   /** The longest a run may take; the panel stops polling a little after. */
   run_limit_seconds: number;
   runs: BackupRun[];
+  /** Present when the backup includes the music. */
+  music: BackupMusicProgress | null;
 };
 
 /** A save or test. An empty secret_key keeps the stored one. */

web/src/lib/components/admin/BackupPanel.svelte

@@ -4,6 +4,7 @@
   import { errMessage } from '#lib/api/errors.js';
   import { pushToast } from '#lib/stores/toast.svelte.js';
   import { formatBytes } from '#lib/utils/bytes.js';
+  import { plural } from '#lib/utils/plural.js';
   import SettingsColumns from '#lib/components/settings/SettingsColumns.svelte';
   import SettingsGroup from '#lib/components/settings/SettingsGroup.svelte';
   import BackupSettings from './BackupSettings.svelte';
@@ -149,6 +150,43 @@
         </div>
       </SettingsGroup>
 
+      {#if status.music}
+        {@const m = status.music}
+        <SettingsGroup title="Music" id="backup-music-progress">
+          <div class="space-y-1 px-4 py-3" data-testid="backup-music">
+            <p class="text-sm text-text-primary">
+              {#if m.total_files === 0}
+                No music in the library yet.
+              {:else if m.sent_files === m.total_files}
+                All {plural(m.total_files, 'file', 'files')} backed up · {formatBytes(m.sent_bytes)}
+              {:else}
+                {m.sent_files} of {plural(m.total_files, 'file', 'files')} backed up · {formatBytes(m.sent_bytes)} of
+                {formatBytes(m.total_bytes)}
+              {/if}
+            </p>
+            {#if m.sent_files + m.refused_files < m.total_files && m.total_files > 0}
+              <p class="text-xs text-text-secondary">The rest goes with the next backups.</p>
+            {/if}
+          </div>
+          {#if m.refused_files > 0}
+            <div class="px-4 pb-3">
+              <p class="text-sm text-warning-fg">
+                The destination refused {plural(m.refused_files, 'file', 'files')}. Each goes again once it changes, or
+                once you save the settings.
+              </p>
+              <ul class="mt-1 space-y-1 text-xs" aria-label="Refused files">
+                {#each m.refused as f (f.path)}
+                  <li>
+                    <span class="block break-all font-mono text-text-primary">{f.path}</span>
+                    <span class="block text-text-secondary">{f.error} · {when(f.at)}</span>
+                  </li>
+                {/each}
+              </ul>
+            </div>
+          {/if}
+        </SettingsGroup>
+      {/if}
+
       {#if status.runs.length > 0}
         <SettingsGroup title="Latest backups" id="backup-runs">
           <ul class="divide-y divide-border text-sm" aria-label="Latest backups">
@@ -161,6 +199,14 @@
                     {#if run.status === 'succeeded'}· {run.location} · {formatBytes(run.bytes)}{/if}
                     {#if run.status === 'failed'}· {run.error}{/if}
                   </span>
+                  {#if run.music_files > 0}
+                    <span class="block text-xs text-text-secondary">
+                      Music: {plural(run.music_files, 'file', 'files')} · {formatBytes(run.music_bytes)}
+                    </span>
+                  {/if}
+                  {#if run.music_note}
+                    <span class="block text-xs text-text-secondary">{run.music_note}</span>
+                  {/if}
                 </span>
                 <span
                   class="shrink-0 text-xs {run.status === 'succeeded'

web/src/lib/components/admin/BackupPanel.test.ts

@@ -25,7 +25,8 @@ const base: BackupStatus = {
     access_key: 'ak',
     has_secret_key: true,
     run_hour: 3,
-    upload_limit_kib: 4096
+    upload_limit_kib: 4096,
+    include_music: false
   },
   state: 'ok',
   problems: [],
@@ -43,9 +44,13 @@ const base: BackupStatus = {
       finished_at: '2026-11-02T03:00:09Z',
       location: 'database/minstrel-20261102T030000Z.tar',
       bytes: 12_000_000,
-      error: ''
+      error: '',
+      music_files: 0,
+      music_bytes: 0,
+      music_note: ''
     }
-  ]
+  ],
+  music: null
 };
 
 function status(over: Partial<BackupStatus> = {}): BackupStatus {
@@ -154,7 +159,8 @@ describe('BackupPanel', () => {
         access_key: 'ak',
         secret_key: '',
         run_hour: 3,
-        upload_limit_kib: 4096
+        upload_limit_kib: 4096,
+        include_music: false
       })
     );
   });
@@ -179,6 +185,61 @@ describe('BackupPanel', () => {
     );
   });
 
+  test('with the music included, says how much of the library the backup holds', async () => {
+    await renderPanel(
+      status({
+        config: { ...base.config, include_music: true },
+        music: { total_files: 10, total_bytes: 300_000_000, sent_files: 4, sent_bytes: 120_000_000, refused_files: 0, refused: [] },
+        runs: [
+          {
+            ...base.runs[0],
+            music_files: 4,
+            music_bytes: 120_000_000,
+            music_note: 'Music stopped for tonight after 6 hours; it carries on with the next backup.'
+          }
+        ]
+      })
+    );
+    const music = screen.getByTestId('backup-music').textContent?.replace(/\s+/g, ' ') ?? '';
+    expect(music).toMatch(/4 of 10 files backed up · 120\.0 MB of 300\.0 MB/);
+    expect(music).toMatch(/The rest goes with the next backups\./);
+    const runs = screen.getByRole('list', { name: /latest backups/i }).textContent?.replace(/\s+/g, ' ') ?? '';
+    expect(runs).toMatch(/Music: 4 files · 120\.0 MB/);
+    expect(runs).toMatch(/carries on with the next backup/);
+  });
+
+  test('a file the destination refused is named with its answer', async () => {
+    await renderPanel(
+      status({
+        config: { ...base.config, include_music: true },
+        music: {
+          total_files: 2,
+          total_bytes: 20,
+          sent_files: 1,
+          sent_bytes: 10,
+          refused_files: 1,
+          refused: [{ path: '/music/A/one.flac', error: 'HTTP 403 AccessDenied: object is locked', at: '2026-11-02T03:00:09Z' }]
+        }
+      })
+    );
+    const refused = screen.getByRole('list', { name: /refused files/i });
+    expect(refused.textContent).toMatch(/\/music\/A\/one\.flac/);
+    expect(refused.textContent).toMatch(/object is locked/);
+    expect(screen.getByTestId('backup-music').textContent).not.toMatch(/The rest goes/);
+  });
+
+  test('the music switch is off by default and, switched on, says how a changed file is kept', async () => {
+    vi.mocked(saveBackups).mockResolvedValue(base);
+    await renderPanel();
+    const music = screen.getByRole('switch', { name: /include the music/i }) as HTMLInputElement;
+    expect(music.checked).toBe(false);
+    expect(screen.queryByTestId('backup-music-retention')).toBeNull();
+    await fireEvent.click(music);
+    expect(screen.getByTestId('backup-music-retention').textContent).toMatch(/retention/);
+    await fireEvent.click(screen.getByRole('button', { name: /^save$/i }));
+    await waitFor(() => expect(saveBackups).toHaveBeenCalledWith(expect.objectContaining({ include_music: true })));
+  });
+
   test('the folder destination asks for a path, not a bucket', async () => {
     await renderPanel(status({ config: { ...base.config, destination: 'folder', folder: '/backups' } }));
     expect(screen.getByRole('textbox', { name: /^folder$/i })).toHaveProperty('value', '/backups');

web/src/lib/components/admin/BackupSettings.svelte

@@ -40,7 +40,8 @@
       bucket: c.bucket,
       access_key: c.access_key,
       run_hour: c.run_hour,
-      upload_limit_kib: c.upload_limit_kib
+      upload_limit_kib: c.upload_limit_kib,
+      include_music: c.include_music
     };
   }
 
@@ -151,6 +152,27 @@
     </SettingRow>
   {/if}
 
+  <SettingRow
+    label="Include the music"
+    for="backup-music"
+    hint="Each file goes once, and again only when it changes. A large library takes several nights the first time."
+  >
+    <input
+      id="backup-music"
+      type="checkbox"
+      role="switch"
+      aria-checked={draft.include_music}
+      bind:checked={draft.include_music}
+      class="h-4 w-4 cursor-pointer accent-accent"
+    />
+  </SettingRow>
+  {#if draft.include_music}
+    <p class="px-4 pb-2 text-xs text-text-secondary" data-testid="backup-music-retention">
+      A changed file goes to the same name. On a bucket that keeps versions or locks objects, set its retention to
+      keep only what you want.
+    </p>
+  {/if}
+
   <SettingRow label="Time of day" for="backup-hour" hint="On your clock.">
     <select id="backup-hour" bind:value={draft.run_hour} class={field}>
       {#each hours as h (h)}