feat(subsync): add reference and target subtitle track picker (#181)

src/core/services/subsync.test.ts

@@ -8,6 +8,7 @@ import {
   runSubsyncManual,
   triggerSubsyncFromConfig,
 } from './subsync';
+import type { SubsyncManualPayload } from '../../types';
 
 function makeDeps(
   overrides: Partial<TriggerSubsyncFromConfigDeps> = {},
@@ -76,7 +77,7 @@ test('triggerSubsyncFromConfig opens manual picker', async () => {
   await triggerSubsyncFromConfig(
     makeDeps({
       openManualPicker: (payload) => {
-        payloadTrackCount = payload.sourceTracks.length;
+        payloadTrackCount = payload.subtitleTracks.length;
         ffsubsyncAvailable = payload.ffsubsyncAvailable;
       },
       showMpvOsd: (text) => {
@@ -88,9 +89,9 @@ test('triggerSubsyncFromConfig opens manual picker', async () => {
     }),
   );
 
-  assert.equal(payloadTrackCount, 1);
+  assert.equal(payloadTrackCount, 2);
   assert.equal(ffsubsyncAvailable, true);
-  assert.ok(osd.includes('Subsync: choose engine and source'));
+  assert.ok(osd.includes('Subsync: choose engine and subtitles'));
   assert.equal(inProgressState, false);
 });
 
@@ -140,7 +141,7 @@ test('triggerSubsyncFromConfig does not run automatic sync', async () => {
   await triggerSubsyncFromConfig(
     makeDeps({
       openManualPicker: (payload) => {
-        payloadTrackCount = payload.sourceTracks.length;
+        payloadTrackCount = payload.subtitleTracks.length;
       },
       showMpvOsd: (text) => {
         osd.push(text);
@@ -152,9 +153,9 @@ test('triggerSubsyncFromConfig does not run automatic sync', async () => {
     }),
   );
 
-  assert.equal(payloadTrackCount, 1);
+  assert.equal(payloadTrackCount, 2);
   assert.equal(spinnerRan, false);
-  assert.deepEqual(osd, ['Subsync: choose engine and source']);
+  assert.deepEqual(osd, ['Subsync: choose engine and subtitles']);
 });
 
 test('triggerSubsyncFromConfig dedupes repeated subtitle source tracks', async () => {
@@ -195,12 +196,71 @@ test('triggerSubsyncFromConfig dedupes repeated subtitle source tracks', async (
         },
       }),
       openManualPicker: (payload) => {
-        payloadTrackCount = payload.sourceTracks.length;
+        payloadTrackCount = payload.subtitleTracks.length;
       },
     }),
   );
 
-  assert.equal(payloadTrackCount, 1);
+  assert.equal(payloadTrackCount, 2);
+});
+
+test('triggerSubsyncFromConfig keeps both active tracks when they share a file', async () => {
+  let payload: SubsyncManualPayload | null = null;
+
+  await triggerSubsyncFromConfig(
+    makeDeps({
+      getMpvClient: () => ({
+        connected: true,
+        currentAudioStreamIndex: null,
+        send: () => {},
+        requestProperty: async (name: string) => {
+          if (name === 'path') return '/tmp/video.mkv';
+          if (name === 'sid') return 1;
+          if (name === 'secondary-sid') return 2;
+          if (name === 'track-list') {
+            // mpv appends a duplicate entry when the same file is re-added, so
+            // the primary and secondary slots can point at one path.
+            return [
+              {
+                id: 1,
+                type: 'sub',
+                selected: true,
+                external: true,
+                'external-filename': '/tmp/ref.srt',
+              },
+              {
+                id: 2,
+                type: 'sub',
+                selected: true,
+                external: true,
+                'external-filename': '/tmp/ref.srt',
+              },
+              {
+                id: 3,
+                type: 'sub',
+                selected: false,
+                external: true,
+                'external-filename': '/tmp/ref.srt',
+              },
+            ];
+          }
+          return null;
+        },
+      }),
+      openManualPicker: (nextPayload) => {
+        payload = nextPayload;
+      },
+    }),
+  );
+
+  assert.ok(payload);
+  const resolved = payload as SubsyncManualPayload;
+  assert.deepEqual(
+    resolved.subtitleTracks.map((track) => track.id),
+    [1, 2],
+  );
+  assert.equal(resolved.defaultReferenceTrackId, 2);
+  assert.equal(resolved.defaultTargetTrackId, 1);
 });
 
 test('triggerSubsyncFromConfig reports failures to OSD', async () => {
@@ -217,15 +277,157 @@ test('triggerSubsyncFromConfig reports failures to OSD', async () => {
   assert.ok(osd.some((line) => line.startsWith('Subsync failed: MPV not connected')));
 });
 
-test('runSubsyncManual requires a source track for alass', async () => {
-  const result = await runSubsyncManual({ engine: 'alass', sourceTrackId: null }, makeDeps());
+test('runSubsyncManual requires a reference track for alass', async () => {
+  const result = await runSubsyncManual({ engine: 'alass', referenceTrackId: null }, makeDeps());
 
   assert.deepEqual(result, {
     ok: false,
-    message: 'Select a subtitle source track for alass',
+    message: 'Select a reference subtitle track for alass',
   });
 });
 
+test('runSubsyncManual rejects alass when reference and target are the same track', async () => {
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceTrackId: 2, targetTrackId: 2 },
+    makeDeps(),
+  );
+
+  assert.deepEqual(result, {
+    ok: false,
+    message: 'Reference and out-of-sync subtitles must be different tracks',
+  });
+});
+
+test('runSubsyncManual rejects an unknown target track', async () => {
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceTrackId: 2, targetTrackId: 99 },
+    makeDeps(),
+  );
+
+  assert.deepEqual(result, {
+    ok: false,
+    message: 'Select the out-of-sync subtitle track to retime',
+  });
+});
+
+test('runSubsyncManual rejects the video reference for remote media', async () => {
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceMode: 'video' },
+    makeDeps({
+      getMpvClient: () => ({
+        connected: true,
+        currentAudioStreamIndex: null,
+        send: () => {},
+        requestProperty: async (name: string) => {
+          if (name === 'path') return 'https://jellyfin.example/Videos/movie/stream.mkv';
+          if (name === 'sid') return 1;
+          if (name === 'secondary-sid') return null;
+          if (name === 'track-list') {
+            return [{ id: 1, type: 'sub', selected: true, lang: 'jpn' }];
+          }
+          return null;
+        },
+      }),
+    }),
+  );
+
+  assert.equal(result.ok, false);
+  assert.match(result.message, /cannot use a stream URL as reference/);
+});
+
+test('openSubsyncManualPicker defaults the reference to the secondary subtitle track', async () => {
+  let payload: SubsyncManualPayload | null = null;
+
+  await triggerSubsyncFromConfig(
+    makeDeps({
+      getMpvClient: () => ({
+        connected: true,
+        currentAudioStreamIndex: null,
+        send: () => {},
+        requestProperty: async (name: string) => {
+          if (name === 'path') return '/tmp/video.mkv';
+          if (name === 'sid') return 1;
+          if (name === 'secondary-sid') return 3;
+          if (name === 'track-list') {
+            return [
+              { id: 1, type: 'sub', selected: true, lang: 'jpn' },
+              {
+                id: 2,
+                type: 'sub',
+                selected: false,
+                external: true,
+                lang: 'eng',
+                'external-filename': '/tmp/other.srt',
+              },
+              {
+                id: 3,
+                type: 'sub',
+                selected: true,
+                external: true,
+                lang: 'eng',
+                'external-filename': '/tmp/secondary.srt',
+              },
+            ];
+          }
+          return null;
+        },
+      }),
+      openManualPicker: (nextPayload) => {
+        payload = nextPayload;
+      },
+    }),
+  );
+
+  assert.ok(payload);
+  const resolved = payload as SubsyncManualPayload;
+  assert.deepEqual(
+    resolved.subtitleTracks.map((track) => track.id),
+    [1, 2, 3],
+  );
+  assert.equal(resolved.defaultReferenceTrackId, 3);
+  assert.equal(resolved.defaultTargetTrackId, 1);
+  assert.equal(resolved.videoReferenceAvailable, true);
+});
+
+test('openSubsyncManualPicker never defaults to a reference missing from the track list', async () => {
+  let payload: SubsyncManualPayload | null = null;
+
+  await triggerSubsyncFromConfig(
+    makeDeps({
+      getMpvClient: () => ({
+        connected: true,
+        currentAudioStreamIndex: null,
+        send: () => {},
+        requestProperty: async (name: string) => {
+          if (name === 'path') return '/tmp/video.mkv';
+          if (name === 'sid') return 1;
+          if (name === 'secondary-sid') return 2;
+          if (name === 'track-list') {
+            return [
+              { id: 1, type: 'sub', selected: true, lang: 'jpn' },
+              // Secondary track with no usable file path: filtered out of the picker.
+              { id: 2, type: 'sub', selected: true, external: true, 'external-filename': '' },
+              { id: 3, type: 'sub', selected: false, lang: 'eng' },
+            ];
+          }
+          return null;
+        },
+      }),
+      openManualPicker: (nextPayload) => {
+        payload = nextPayload;
+      },
+    }),
+  );
+
+  assert.ok(payload);
+  const resolved = payload as SubsyncManualPayload;
+  assert.deepEqual(
+    resolved.subtitleTracks.map((track) => track.id),
+    [1, 3],
+  );
+  assert.equal(resolved.defaultReferenceTrackId, 3);
+});
+
 test('triggerSubsyncFromConfig does not validate sync tool paths before manual selection', async () => {
   const osd: string[] = [];
   const inProgress: boolean[] = [];
@@ -242,7 +444,7 @@ test('triggerSubsyncFromConfig does not validate sync tool paths before manual s
         inProgress.push(value);
       },
       openManualPicker: (payload) => {
-        payloadTrackCount = payload.sourceTracks.length;
+        payloadTrackCount = payload.subtitleTracks.length;
       },
       showMpvOsd: (text) => {
         osd.push(text);
@@ -251,8 +453,8 @@ test('triggerSubsyncFromConfig does not validate sync tool paths before manual s
   );
 
   assert.deepEqual(inProgress, [false]);
-  assert.equal(payloadTrackCount, 1);
-  assert.deepEqual(osd, ['Subsync: choose engine and source']);
+  assert.equal(payloadTrackCount, 2);
+  assert.deepEqual(osd, ['Subsync: choose engine and subtitles']);
 });
 
 function writeExecutableScript(filePath: string, content: string): void {
@@ -333,7 +535,7 @@ test('runSubsyncManual constructs ffsubsync command and returns success', async
     }),
   });
 
-  const result = await runSubsyncManual({ engine: 'ffsubsync', sourceTrackId: null }, deps);
+  const result = await runSubsyncManual({ engine: 'ffsubsync' }, deps);
 
   assert.equal(result.ok, true);
   assert.equal(result.message, 'Subtitle synchronized with ffsubsync');
@@ -346,7 +548,7 @@ test('runSubsyncManual constructs ffsubsync command and returns success', async
   const ffOutputFlagIndex = ffArgs.indexOf('-o');
   assert.equal(ffOutputFlagIndex >= 0, true);
   assert.equal(ffArgs[ffOutputFlagIndex + 1], toShellPath(primaryPath));
-  assert.equal(sentCommands[0]?.[0], 'sub_add');
+  assert.equal(sentCommands[0]?.[0], 'sub-add');
   assert.deepEqual(sentCommands[1], ['set_property', 'sub-delay', 0]);
 });
 
@@ -399,7 +601,7 @@ test('runSubsyncManual writes deterministic _retimed filename when replace is fa
     }),
   });
 
-  const result = await runSubsyncManual({ engine: 'ffsubsync', sourceTrackId: null }, deps);
+  const result = await runSubsyncManual({ engine: 'ffsubsync' }, deps);
 
   assert.equal(result.ok, true);
   const ffArgs = fs.readFileSync(ffsubsyncLogPath, 'utf8').trim().split('\n');
@@ -453,7 +655,7 @@ test('runSubsyncManual reports ffsubsync command failures with details', async (
     }),
   });
 
-  const result = await runSubsyncManual({ engine: 'ffsubsync', sourceTrackId: null }, deps);
+  const result = await runSubsyncManual({ engine: 'ffsubsync' }, deps);
 
   assert.equal(result.ok, false);
   assert.equal(result.message.startsWith('ffsubsync synchronization failed'), true);
@@ -518,7 +720,7 @@ test('runSubsyncManual constructs alass command and returns failure on non-zero
     }),
   });
 
-  const result = await runSubsyncManual({ engine: 'alass', sourceTrackId: 2 }, deps);
+  const result = await runSubsyncManual({ engine: 'alass', referenceTrackId: 2 }, deps);
 
   assert.equal(result.ok, false);
   assert.equal(typeof result.message, 'string');
@@ -528,6 +730,179 @@ test('runSubsyncManual constructs alass command and returns failure on non-zero
   assert.equal(alassArgs[1], toShellPath(primaryPath));
 });
 
+function makeAlassSelectionDeps(tmpDir: string): {
+  deps: TriggerSubsyncFromConfigDeps;
+  alassLogPath: string;
+  videoPath: string;
+  primaryPath: string;
+  sourcePath: string;
+  sentCommands: Array<Array<string | number>>;
+} {
+  const alassLogPath = path.join(tmpDir, 'alass-args.log');
+  const alassPath = path.join(tmpDir, 'alass.sh');
+  const ffmpegPath = path.join(tmpDir, 'ffmpeg.sh');
+  const ffsubsyncPath = path.join(tmpDir, 'ffsubsync.sh');
+  const videoPath = path.join(tmpDir, 'video.mkv');
+  const primaryPath = path.join(tmpDir, 'primary.srt');
+  const sourcePath = path.join(tmpDir, 'source.srt');
+
+  fs.writeFileSync(videoPath, 'video');
+  fs.writeFileSync(primaryPath, 'sub');
+  fs.writeFileSync(sourcePath, 'sub2');
+  writeExecutableScript(ffmpegPath, '#!/bin/sh\nexit 0\n');
+  writeExecutableScript(ffsubsyncPath, '#!/bin/sh\nexit 0\n');
+  writeExecutableScript(
+    alassPath,
+    `#!/bin/sh\n: > "${toShellPath(alassLogPath)}"\nfor arg in "$@"; do printf '%s\\n' "$arg" >> "${toShellPath(alassLogPath)}"; done\n: > "$3"\nexit 0\n`,
+  );
+
+  const trackList: Array<Record<string, unknown>> = [
+    { id: 1, type: 'sub', selected: true, external: true, 'external-filename': primaryPath },
+    { id: 2, type: 'sub', selected: true, external: true, 'external-filename': sourcePath },
+  ];
+  const sentCommands: Array<Array<string | number>> = [];
+  const deps = makeDeps({
+    getMpvClient: () => ({
+      connected: true,
+      currentAudioStreamIndex: null,
+      send: (payload) => {
+        sentCommands.push(payload.command);
+        if (payload.command[0] === 'sub-add' || payload.command[0] === 'sub_add') {
+          trackList.push({
+            id: trackList.length + 1,
+            type: 'sub',
+            selected: false,
+            external: true,
+            'external-filename': payload.command[1],
+          });
+        }
+      },
+      requestProperty: async (name: string) => {
+        if (name === 'path') return videoPath;
+        if (name === 'sid') return 1;
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return trackList;
+        return null;
+      },
+    }),
+    getResolvedConfig: () => ({
+      alassPath,
+      ffsubsyncPath,
+      ffmpegPath,
+      replace: false,
+    }),
+  });
+
+  return { deps, alassLogPath, videoPath, primaryPath, sourcePath, sentCommands };
+}
+
+test('runSubsyncManual uses the video file as alass reference when requested', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subsync-alass-video-ref-'));
+  const { deps, alassLogPath, videoPath, primaryPath } = makeAlassSelectionDeps(tmpDir);
+
+  const result = await runSubsyncManual({ engine: 'alass', referenceMode: 'video' }, deps);
+
+  assert.equal(result.ok, true);
+  const alassArgs = fs.readFileSync(alassLogPath, 'utf8').trim().split('\n');
+  assert.equal(alassArgs[0], toShellPath(videoPath));
+  assert.equal(alassArgs[1], toShellPath(primaryPath));
+});
+
+test('runSubsyncManual retimes the selected target track instead of the primary', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subsync-alass-target-'));
+  const { deps, alassLogPath, primaryPath, sourcePath, sentCommands } =
+    makeAlassSelectionDeps(tmpDir);
+
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceTrackId: 1, targetTrackId: 2 },
+    deps,
+  );
+
+  assert.equal(result.ok, true);
+  const alassArgs = fs.readFileSync(alassLogPath, 'utf8').trim().split('\n');
+  assert.equal(alassArgs[0], toShellPath(primaryPath));
+  assert.equal(alassArgs[1], toShellPath(sourcePath));
+  assert.equal(sentCommands[0]?.[0], 'sub-add');
+  assert.equal(sentCommands[0]?.[2], 'auto');
+});
+
+test('runSubsyncManual keeps a retimed secondary track in the secondary slot', async () => {
+  const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subsync-alass-secondary-slot-'));
+  const alassPath = path.join(tmpDir, 'alass.sh');
+  const ffmpegPath = path.join(tmpDir, 'ffmpeg.sh');
+  const ffsubsyncPath = path.join(tmpDir, 'ffsubsync.sh');
+  const videoPath = path.join(tmpDir, 'video.mkv');
+  const primaryPath = path.join(tmpDir, 'ja.srt');
+  const secondaryPath = path.join(tmpDir, 'en.srt');
+  const retimedPath = path.join(tmpDir, 'en_retimed.srt');
+
+  fs.writeFileSync(videoPath, 'video');
+  fs.writeFileSync(primaryPath, 'ja');
+  fs.writeFileSync(secondaryPath, 'en');
+  writeExecutableScript(ffmpegPath, '#!/bin/sh\nexit 0\n');
+  writeExecutableScript(ffsubsyncPath, '#!/bin/sh\nexit 0\n');
+  writeExecutableScript(alassPath, '#!/bin/sh\n: > "$3"\nexit 0\n');
+
+  const trackList: Array<Record<string, unknown>> = [
+    { id: 1, type: 'sub', selected: true, external: true, 'external-filename': primaryPath },
+    { id: 2, type: 'sub', selected: true, external: true, 'external-filename': secondaryPath },
+  ];
+  const sentCommands: Array<Array<string | number>> = [];
+  const deps = makeDeps({
+    getMpvClient: () => ({
+      connected: true,
+      currentAudioStreamIndex: null,
+      send: (payload) => {
+        sentCommands.push(payload.command);
+        if (payload.command[0] === 'sub-add') {
+          trackList.push({
+            id: 3,
+            type: 'sub',
+            selected: false,
+            external: true,
+            'external-filename': payload.command[1],
+          });
+        }
+      },
+      requestProperty: async (name: string) => {
+        if (name === 'path') return videoPath;
+        if (name === 'sid') return 1;
+        if (name === 'secondary-sid') return 2;
+        if (name === 'track-list') return trackList;
+        return null;
+      },
+    }),
+    getResolvedConfig: () => ({
+      alassPath,
+      ffsubsyncPath,
+      ffmpegPath,
+      replace: false,
+    }),
+  });
+
+  const result = await runSubsyncManual(
+    { engine: 'alass', referenceTrackId: 1, targetTrackId: 2 },
+    deps,
+  );
+
+  assert.equal(result.ok, true);
+  assert.deepEqual(sentCommands[0], ['sub-add', retimedPath, 'auto']);
+  assert.deepEqual(sentCommands[1], ['set_property', 'secondary-sub-delay', 0]);
+  assert.deepEqual(sentCommands[2], ['set_property', 'secondary-sid', 3]);
+  assert.equal(
+    sentCommands.some((command) => command[1] === 'sub-delay'),
+    false,
+  );
+  assert.equal(
+    sentCommands.some((command) => command[1] === 'sid'),
+    false,
+  );
+  assert.equal(
+    sentCommands.some((command) => command[1] === 'sid'),
+    false,
+  );
+});
+
 test('runSubsyncManual keeps internal alass source file alive until sync finishes', async () => {
   const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'subsync-alass-internal-source-'));
   const alassPath = path.join(tmpDir, 'alass.sh');
@@ -589,11 +964,11 @@ test('runSubsyncManual keeps internal alass source file alive until sync finishe
     }),
   });
 
-  const result = await runSubsyncManual({ engine: 'alass', sourceTrackId: 2 }, deps);
+  const result = await runSubsyncManual({ engine: 'alass', referenceTrackId: 2 }, deps);
 
   assert.equal(result.ok, true);
   assert.equal(result.message, 'Subtitle synchronized with alass');
-  assert.equal(sentCommands[0]?.[0], 'sub_add');
+  assert.equal(sentCommands[0]?.[0], 'sub-add');
   assert.deepEqual(sentCommands[1], ['set_property', 'sub-delay', 0]);
 });
 
@@ -645,7 +1020,7 @@ test('runSubsyncManual resolves string sid values from mpv stream properties', a
     }),
   });
 
-  const result = await runSubsyncManual({ engine: 'ffsubsync', sourceTrackId: null }, deps);
+  const result = await runSubsyncManual({ engine: 'ffsubsync' }, deps);
 
   assert.equal(result.ok, true);
   assert.equal(result.message, 'Subtitle synchronized with ffsubsync');

src/core/services/subsync.ts

@@ -21,6 +21,11 @@ interface FileExtractionResult {
   temporary: boolean;
 }
 
+type SubtitleSlot = 'primary' | 'secondary';
+
+const SYNCED_TRACK_LOOKUP_ATTEMPTS = 5;
+const SYNCED_TRACK_LOOKUP_RETRY_MS = 100;
+
 function summarizeCommandFailure(command: string, result: CommandResult): string {
   const parts = [
     `code=${result.code ?? 'n/a'}`,
@@ -90,16 +95,28 @@ function getSourceTrackIdentity(track: MpvTrack): string {
   return 'unknown';
 }
 
-function dedupeSourceTracks(tracks: MpvTrack[]): MpvTrack[] {
-  const deduped = new Map<string, MpvTrack>();
+function isPinned(track: MpvTrack, pinnedIds: Set<number>): boolean {
+  return typeof track.id === 'number' && pinnedIds.has(track.id);
+}
+
+// Pinned tracks (the active primary/secondary) always survive, even when two of
+// them point at the same file; only unpinned duplicates are collapsed.
+function dedupeSubtitleTracks(tracks: MpvTrack[], pinnedIds: Set<number>): MpvTrack[] {
+  const pinnedIdentities = new Set(
+    tracks.filter((track) => isPinned(track, pinnedIds)).map(getSourceTrackIdentity),
+  );
+  const winners = new Map<string, MpvTrack>();
   for (const track of tracks) {
+    if (isPinned(track, pinnedIds)) continue;
     const identity = getSourceTrackIdentity(track);
-    const existing = deduped.get(identity);
+    if (pinnedIdentities.has(identity)) continue;
+    const existing = winners.get(identity);
     if (!existing || (track.selected && !existing.selected)) {
-      deduped.set(identity, track);
+      winners.set(identity, track);
     }
   }
-  return [...deduped.values()];
+  const kept = new Set(winners.values());
+  return tracks.filter((track) => isPinned(track, pinnedIds) || kept.has(track));
 }
 
 export interface TriggerSubsyncFromConfigDeps extends SubsyncCoreDeps {
@@ -142,20 +159,21 @@ async function gatherSubsyncContext(client: MpvClientLike): Promise<SubsyncConte
   }
 
   const secondaryTrack = subtitleTracks.find((track) => track.id === secondarySid) ?? null;
-  const sourceTracks = subtitleTracks
-    .filter((track) => track.id !== sid)
-    .filter((track) => {
-      if (!track.external) return true;
-      const filename = track['external-filename'];
-      return typeof filename === 'string' && filename.length > 0;
-    });
-  const uniqueSourceTracks = dedupeSourceTracks(sourceTracks);
+  const usableTracks = subtitleTracks.filter((track) => {
+    if (typeof track.id !== 'number') return false;
+    if (!track.external) return true;
+    const filename = track['external-filename'];
+    return typeof filename === 'string' && filename.length > 0;
+  });
 
   return {
     videoPath,
     primaryTrack,
     secondaryTrack,
-    sourceTracks: uniqueSourceTracks,
+    subtitleTracks: dedupeSubtitleTracks(
+      usableTracks,
+      new Set([sid, secondarySid].filter((id): id is number => typeof id === 'number')),
+    ),
     audioStreamIndex: client.currentAudioStreamIndex,
   };
 }
@@ -271,41 +289,104 @@ async function runFfsubsyncSync(
   return runCommand(ffsubsyncPath, args);
 }
 
-function loadSyncedSubtitle(client: MpvClientLike, pathToLoad: string): void {
+function delay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// mpv may echo the path back with different separators, and Windows paths are
+// case-insensitive, so compare normalized forms instead of raw strings.
+function normalizeSubtitlePathForCompare(value: string): string {
+  const normalized = value.replace(/\\/g, '/');
+  return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+
+async function findAddedSubtitleTrackId(
+  client: MpvClientLike,
+  pathToLoad: string,
+): Promise<number | null> {
+  const wanted = normalizeSubtitlePathForCompare(pathToLoad);
+  // sub-add is queued, so the track may not appear in the first track-list reply.
+  for (let attempt = 0; attempt < SYNCED_TRACK_LOOKUP_ATTEMPTS; attempt += 1) {
+    let tracks: MpvTrack[] = [];
+    try {
+      const trackListRaw = await client.requestProperty('track-list');
+      tracks = Array.isArray(trackListRaw) ? normalizeTrackIds(trackListRaw as MpvTrack[]) : [];
+    } catch {
+      return null;
+    }
+    // Re-adding a file mpv already knows appends a duplicate entry; the newest
+    // one holds the retimed content, so prefer the last match.
+    const matches = tracks.filter((track) => {
+      if (track.type !== 'sub') return false;
+      const filename = track['external-filename'];
+      return typeof filename === 'string' && normalizeSubtitlePathForCompare(filename) === wanted;
+    });
+    const added = matches[matches.length - 1];
+    if (added && typeof added.id === 'number') {
+      return added.id;
+    }
+    if (attempt < SYNCED_TRACK_LOOKUP_ATTEMPTS - 1) {
+      await delay(SYNCED_TRACK_LOOKUP_RETRY_MS);
+    }
+  }
+  return null;
+}
+
+async function loadSyncedSubtitle(
+  client: MpvClientLike,
+  pathToLoad: string,
+  slot: SubtitleSlot,
+): Promise<void> {
   if (!client.connected) {
     throw new Error('MPV disconnected while loading subtitle');
   }
-  client.send({ command: ['sub_add', pathToLoad] });
+
+  if (slot === 'secondary') {
+    // Keep the primary track untouched: load without selecting, then point
+    // secondary-sid at the freshly added track.
+    client.send({ command: ['sub-add', pathToLoad, 'auto'] });
+    client.send({ command: ['set_property', 'secondary-sub-delay', 0] });
+    const addedTrackId = await findAddedSubtitleTrackId(client, pathToLoad);
+    if (addedTrackId === null) {
+      throw new Error('Synchronized subtitle did not appear in the mpv track list');
+    }
+    client.send({ command: ['set_property', 'secondary-sid', addedTrackId] });
+    return;
+  }
+
+  client.send({ command: ['sub-add', pathToLoad] });
   client.send({ command: ['set_property', 'sub-delay', 0] });
 }
 
 async function subsyncToReference(
   engine: 'alass' | 'ffsubsync',
   referenceFilePath: string,
+  targetTrack: MpvTrack,
   context: SubsyncContext,
   resolved: SubsyncResolvedConfig,
   client: MpvClientLike,
+  slot: SubtitleSlot,
 ): Promise<SubsyncResult> {
   const ffmpegPath = ensureExecutablePath(resolved.ffmpegPath, 'ffmpeg');
-  const primaryExtraction = await extractSubtitleTrackToFile(
+  const targetExtraction = await extractSubtitleTrackToFile(
     ffmpegPath,
     context.videoPath,
-    context.primaryTrack,
+    targetTrack,
   );
-  const replacePrimary = resolved.replace !== false && !primaryExtraction.temporary;
-  const outputPath = buildRetimedPath(primaryExtraction.path, replacePrimary);
+  const replaceTarget = resolved.replace !== false && !targetExtraction.temporary;
+  const outputPath = buildRetimedPath(targetExtraction.path, replaceTarget);
 
   try {
     let result: CommandResult;
     if (engine === 'alass') {
       const alassPath = ensureExecutablePath(resolved.alassPath, 'alass');
-      result = await runAlassSync(alassPath, referenceFilePath, primaryExtraction.path, outputPath);
+      result = await runAlassSync(alassPath, referenceFilePath, targetExtraction.path, outputPath);
     } else {
       const ffsubsyncPath = ensureExecutablePath(resolved.ffsubsyncPath, 'ffsubsync');
       result = await runFfsubsyncSync(
         ffsubsyncPath,
         context.videoPath,
-        primaryExtraction.path,
+        targetExtraction.path,
         outputPath,
         context.audioStreamIndex,
       );
@@ -319,13 +400,13 @@ async function subsyncToReference(
       };
     }
 
-    loadSyncedSubtitle(client, outputPath);
+    await loadSyncedSubtitle(client, outputPath, slot);
     return {
       ok: true,
       message: `Subtitle synchronized with ${engine}`,
     };
   } finally {
-    cleanupTemporaryFile(primaryExtraction);
+    cleanupTemporaryFile(targetExtraction);
   }
 }
 
@@ -337,6 +418,25 @@ function validateFfsubsyncReference(videoPath: string): void {
   }
 }
 
+function resolveTargetTrack(
+  request: SubsyncManualRunRequest,
+  context: SubsyncContext,
+): MpvTrack | null {
+  if (request.targetTrackId === undefined || request.targetTrackId === null) {
+    return context.primaryTrack;
+  }
+  return getTrackById(context.subtitleTracks, request.targetTrackId);
+}
+
+// Retiming the secondary track must not steal the primary slot: the synced file
+// goes back where the out-of-sync one was.
+function resolveTargetSlot(targetTrack: MpvTrack, context: SubsyncContext): SubtitleSlot {
+  if (typeof targetTrack.id !== 'number') return 'primary';
+  if (targetTrack.id === context.primaryTrack.id) return 'primary';
+  if (context.secondaryTrack && targetTrack.id === context.secondaryTrack.id) return 'secondary';
+  return 'primary';
+}
+
 export async function runSubsyncManual(
   request: SubsyncManualRunRequest,
   deps: SubsyncCoreDeps,
@@ -345,6 +445,12 @@ export async function runSubsyncManual(
   const context = await gatherSubsyncContext(client);
   const resolved = deps.getResolvedConfig();
 
+  const targetTrack = resolveTargetTrack(request, context);
+  if (!targetTrack) {
+    return { ok: false, message: 'Select the out-of-sync subtitle track to retime' };
+  }
+  const targetSlot = resolveTargetSlot(targetTrack, context);
+
   if (request.engine === 'ffsubsync') {
     try {
       validateFfsubsyncReference(context.videoPath);
@@ -354,22 +460,64 @@ export async function runSubsyncManual(
         message: `ffsubsync synchronization failed: ${(error as Error).message}`,
       };
     }
-    return subsyncToReference('ffsubsync', context.videoPath, context, resolved, client);
+    return subsyncToReference(
+      'ffsubsync',
+      context.videoPath,
+      targetTrack,
+      context,
+      resolved,
+      client,
+      targetSlot,
+    );
   }
 
-  const sourceTrack = getTrackById(context.sourceTracks, request.sourceTrackId ?? null);
-  if (!sourceTrack) {
-    return { ok: false, message: 'Select a subtitle source track for alass' };
+  if (request.referenceMode === 'video') {
+    if (isRemoteMediaPath(context.videoPath)) {
+      return {
+        ok: false,
+        message:
+          'alass cannot use a stream URL as reference. Pick a reference subtitle track instead.',
+      };
+    }
+    return subsyncToReference(
+      'alass',
+      context.videoPath,
+      targetTrack,
+      context,
+      resolved,
+      client,
+      targetSlot,
+    );
+  }
+
+  const referenceTrack = getTrackById(context.subtitleTracks, request.referenceTrackId ?? null);
+  if (!referenceTrack) {
+    return { ok: false, message: 'Select a reference subtitle track for alass' };
+  }
+  if (referenceTrack.id === targetTrack.id) {
+    return { ok: false, message: 'Reference and out-of-sync subtitles must be different tracks' };
   }
 
   const ffmpegPath = ensureExecutablePath(resolved.ffmpegPath, 'ffmpeg');
-  let sourceExtraction: FileExtractionResult | null = null;
+  let referenceExtraction: FileExtractionResult | null = null;
   try {
-    sourceExtraction = await extractSubtitleTrackToFile(ffmpegPath, context.videoPath, sourceTrack);
-    return await subsyncToReference('alass', sourceExtraction.path, context, resolved, client);
+    referenceExtraction = await extractSubtitleTrackToFile(
+      ffmpegPath,
+      context.videoPath,
+      referenceTrack,
+    );
+    return await subsyncToReference(
+      'alass',
+      referenceExtraction.path,
+      targetTrack,
+      context,
+      resolved,
+      client,
+      targetSlot,
+    );
   } finally {
-    if (sourceExtraction) {
-      cleanupTemporaryFile(sourceExtraction);
+    if (referenceExtraction) {
+      cleanupTemporaryFile(referenceExtraction);
     }
   }
 }
@@ -377,14 +525,27 @@ export async function runSubsyncManual(
 export async function openSubsyncManualPicker(deps: TriggerSubsyncFromConfigDeps): Promise<void> {
   const client = getMpvClientForSubsync(deps);
   const context = await gatherSubsyncContext(client);
+  const subtitleTracks = context.subtitleTracks
+    .filter((track) => typeof track.id === 'number')
+    .map((track) => ({
+      id: track.id as number,
+      label: formatTrackLabel(track),
+    }));
+  const primaryTrackId =
+    typeof context.primaryTrack.id === 'number' ? context.primaryTrack.id : null;
+  const secondaryTrackId =
+    typeof context.secondaryTrack?.id === 'number' ? context.secondaryTrack.id : null;
   const payload: SubsyncManualPayload = {
+    subtitleTracks,
+    // The secondary track can be filtered or deduped out of the emitted list,
+    // so only default to it when the picker actually offers it.
+    defaultReferenceTrackId:
+      subtitleTracks.find((track) => track.id === secondaryTrackId)?.id ??
+      subtitleTracks.find((track) => track.id !== primaryTrackId)?.id ??
+      null,
+    defaultTargetTrackId: primaryTrackId,
+    videoReferenceAvailable: !isRemoteMediaPath(context.videoPath),
     ffsubsyncAvailable: !isRemoteMediaPath(context.videoPath),
-    sourceTracks: context.sourceTracks
-      .filter((track) => typeof track.id === 'number')
-      .map((track) => ({
-        id: track.id as number,
-        label: formatTrackLabel(track),
-      })),
   };
   deps.openManualPicker(payload);
 }
@@ -397,7 +558,7 @@ export async function triggerSubsyncFromConfig(deps: TriggerSubsyncFromConfigDep
 
   try {
     await openSubsyncManualPicker(deps);
-    deps.showMpvOsd('Subsync: choose engine and source');
+    deps.showMpvOsd('Subsync: choose engine and subtitles');
   } catch (error) {
     deps.showMpvOsd(`Subsync failed: ${(error as Error).message}`);
   } finally {

src/main/overlay-runtime.test.ts

@@ -326,7 +326,13 @@ test('handleOverlayModalClosed hides modal window only after all pending modals
   });
   runtime.sendToActiveOverlayWindow(
     'subsync:open-manual',
-    { ffsubsyncAvailable: true, sourceTracks: [] },
+    {
+      ffsubsyncAvailable: true,
+      videoReferenceAvailable: true,
+      subtitleTracks: [],
+      defaultReferenceTrackId: null,
+      defaultTargetTrackId: null,
+    },
     {
       restoreOnModalClose: 'subsync',
     },
@@ -560,7 +566,13 @@ test('modal runtime notifies callers when modal input state becomes active/inact
   });
   runtime.sendToActiveOverlayWindow(
     'subsync:open-manual',
-    { ffsubsyncAvailable: true, sourceTracks: [] },
+    {
+      ffsubsyncAvailable: true,
+      videoReferenceAvailable: true,
+      subtitleTracks: [],
+      defaultReferenceTrackId: null,
+      defaultTargetTrackId: null,
+    },
     {
       restoreOnModalClose: 'subsync',
     },

src/main/runtime/composers/ipc-runtime-composer.test.ts

@@ -4,7 +4,7 @@ import { composeIpcRuntimeHandlers } from './ipc-runtime-composer';
 
 test('composeIpcRuntimeHandlers returns callable IPC handlers and registration bridge', async () => {
   let registered = false;
-  let receivedSourceTrackId: number | null | undefined;
+  let receivedReferenceTrackId: number | null | undefined;
 
   const composed = composeIpcRuntimeHandlers({
     mpvCommandMainDeps: {
@@ -25,7 +25,7 @@ test('composeIpcRuntimeHandlers returns callable IPC handlers and registration b
     },
     handleMpvCommandFromIpcRuntime: () => {},
     runSubsyncManualFromIpc: async (request) => {
-      receivedSourceTrackId = request.sourceTrackId;
+      receivedReferenceTrackId = request.referenceTrackId;
       return {
         ok: true,
         message: 'ok',
@@ -124,10 +124,10 @@ test('composeIpcRuntimeHandlers returns callable IPC handlers and registration b
 
   const result = await composed.runSubsyncManualFromIpc({
     engine: 'alass',
-    sourceTrackId: 7,
+    referenceTrackId: 7,
   });
   assert.deepEqual(result, { ok: true, message: 'ok' });
-  assert.equal(receivedSourceTrackId, 7);
+  assert.equal(receivedReferenceTrackId, 7);
 
   composed.registerIpcRuntimeHandlers();
   assert.equal(registered, true);

src/main/runtime/configured-status-notification.test.ts

@@ -11,7 +11,7 @@ import { createOverlayNotificationDelivery } from './overlay-notification-delive
 test('notifyConfiguredStatus routes both to overlay and system without osd', () => {
   const calls: string[] = [];
 
-  notifyConfiguredStatus('Subsync: choose engine and source', {
+  notifyConfiguredStatus('Subsync: choose engine and subtitles', {
     getNotificationType: () => 'both',
     showOsd: (message) => {
       calls.push(`osd:${message}`);
@@ -25,8 +25,8 @@ test('notifyConfiguredStatus routes both to overlay and system without osd', ()
   });
 
   assert.deepEqual(calls, [
-    'overlay::SubMiner:Subsync: choose engine and source:info:auto',
-    'desktop:SubMiner:Subsync: choose engine and source',
+    'overlay::SubMiner:Subsync: choose engine and subtitles:info:auto',
+    'desktop:SubMiner:Subsync: choose engine and subtitles',
   ]);
 });
 

src/main/runtime/subsync-open.test.ts

@@ -5,7 +5,13 @@ import type { SubsyncManualPayload } from '../../types';
 
 const payload: SubsyncManualPayload = {
   ffsubsyncAvailable: true,
-  sourceTracks: [{ id: 2, label: 'External #2 - eng' }],
+  videoReferenceAvailable: true,
+  subtitleTracks: [
+    { id: 1, label: 'Internal #1 - jpn (active)' },
+    { id: 2, label: 'External #2 - eng' },
+  ],
+  defaultReferenceTrackId: 2,
+  defaultTargetTrackId: 1,
 };
 
 test('subsync manual open prefers dedicated modal window on first attempt', async () => {

src/renderer/index.html

@@ -359,9 +359,13 @@
                   ffsubsync
                 </label>
               </div>
-              <label id="subsyncSourceLabel" class="subsync-field">
-                <span>Source Subtitle (for alass)</span>
-                <select id="subsyncSourceSelect"></select>
+              <label id="subsyncReferenceLabel" class="subsync-field">
+                <span>Reference (correct timing, for alass)</span>
+                <select id="subsyncReferenceSelect"></select>
+              </label>
+              <label id="subsyncTargetLabel" class="subsync-field">
+                <span>Out-of-sync Subtitle (gets retimed)</span>
+                <select id="subsyncTargetSelect"></select>
               </label>
             </div>
             <div id="subsyncStatus" class="runtime-options-status"></div>

src/renderer/modals/subsync.test.ts

@@ -2,6 +2,7 @@ import test from 'node:test';
 import assert from 'node:assert/strict';
 
 import { createSubsyncModal } from './subsync.js';
+import type { SubsyncManualPayload, SubsyncManualRunRequest } from '../../types';
 
 type Listener = () => void;
 
@@ -52,18 +53,54 @@ function createDeferred<T>() {
   return { promise, resolve };
 }
 
-function createTestHarness(runSubsyncManual: () => Promise<{ ok: boolean; message: string }>) {
+function createSelectStub() {
+  const options: Array<{ value: string; textContent: string }> = [];
+  const events = createEventTarget();
+  let innerHTML = '';
+  let value = '';
+
+  return {
+    options,
+    disabled: false,
+    addEventListener: events.addEventListener,
+    dispatch: events.dispatch,
+    get innerHTML(): string {
+      return innerHTML;
+    },
+    set innerHTML(next: string) {
+      innerHTML = next;
+      if (next === '') {
+        options.length = 0;
+        value = '';
+      }
+    },
+    get value(): string {
+      return value;
+    },
+    set value(next: string) {
+      value = next;
+    },
+    appendChild(option: { value: string; textContent: string }) {
+      options.push(option);
+      if (!value) value = option.value;
+      return option;
+    },
+  };
+}
+
+function createTestHarness(
+  runSubsyncManual: (request: SubsyncManualRunRequest) => Promise<{ ok: boolean; message: string }>,
+) {
   const overlayClassList = createClassList();
   const modalClassList = createClassList();
   const statusClassList = createClassList();
-  const sourceLabelClassList = createClassList();
+  const referenceLabelClassList = createClassList();
+  const targetLabelClassList = createClassList();
   const runButtonEvents = createEventTarget();
   const closeButtonEvents = createEventTarget();
   const engineAlassEvents = createEventTarget();
   const engineFfsubsyncEvents = createEventTarget();
 
-  const sourceOptions: Array<{ value: string; textContent: string }> = [];
-
   const runButton = {
     disabled: false,
     addEventListener: runButtonEvents.addEventListener,
@@ -77,6 +114,7 @@ function createTestHarness(runSubsyncManual: () => Promise<{ ok: boolean; messag
 
   const subsyncEngineAlass = {
     checked: false,
+    disabled: false,
     addEventListener: engineAlassEvents.addEventListener,
     dispatch: engineAlassEvents.dispatch,
   };
@@ -88,18 +126,8 @@ function createTestHarness(runSubsyncManual: () => Promise<{ ok: boolean; messag
     dispatch: engineFfsubsyncEvents.dispatch,
   };
 
-  const sourceSelect = {
-    innerHTML: '',
-    value: '',
-    disabled: false,
-    appendChild: (option: { value: string; textContent: string }) => {
-      sourceOptions.push(option);
-      if (!sourceSelect.value) {
-        sourceSelect.value = option.value;
-      }
-      return option;
-    },
-  };
+  const referenceSelect = createSelectStub();
+  const targetSelect = createSelectStub();
 
   let notifyClosedCalls = 0;
   let notifyOpenedCalls = 0;
@@ -139,8 +167,10 @@ function createTestHarness(runSubsyncManual: () => Promise<{ ok: boolean; messag
       subsyncCloseButton: closeButton,
       subsyncEngineAlass,
       subsyncEngineFfsubsync,
-      subsyncSourceLabel: { classList: sourceLabelClassList },
-      subsyncSourceSelect: sourceSelect,
+      subsyncReferenceLabel: { classList: referenceLabelClassList },
+      subsyncReferenceSelect: referenceSelect,
+      subsyncTargetLabel: { classList: targetLabelClassList },
+      subsyncTargetSelect: targetSelect,
       subsyncRunButton: runButton,
       subsyncStatus: {
         textContent: '',
@@ -149,7 +179,7 @@ function createTestHarness(runSubsyncManual: () => Promise<{ ok: boolean; messag
     },
     state: {
       subsyncModalOpen: false,
-      subsyncSourceTracks: [],
+      subsyncSubtitleTracks: [],
       subsyncSubmitting: false,
       isOverSubtitle: false,
     },
@@ -166,6 +196,9 @@ function createTestHarness(runSubsyncManual: () => Promise<{ ok: boolean; messag
     ctx,
     modal,
     runButton,
+    referenceSelect,
+    targetSelect,
+    referenceLabelClassList,
     statusClassList,
     getNotifyClosedCalls: () => notifyClosedCalls,
     getNotifyOpenedCalls: () => notifyOpenedCalls,
@@ -187,16 +220,28 @@ async function flushMicrotasks(): Promise<void> {
   await Promise.resolve();
 }
 
+const BASE_PAYLOAD: SubsyncManualPayload = {
+  subtitleTracks: [
+    { id: 1, label: 'External #1 - jpn (active)' },
+    { id: 2, label: 'External #2 - eng' },
+  ],
+  defaultReferenceTrackId: 2,
+  defaultTargetTrackId: 1,
+  videoReferenceAvailable: true,
+  ffsubsyncAvailable: true,
+};
+
+function payloadWith(overrides: Partial<SubsyncManualPayload>): SubsyncManualPayload {
+  return { ...BASE_PAYLOAD, ...overrides };
+}
+
 test('manual subsync failure closes during run, then reopens modal with error', async () => {
   const deferred = createDeferred<{ ok: boolean; message: string }>();
   const harness = createTestHarness(async () => deferred.promise);
 
   try {
     harness.modal.wireDomEvents();
-    harness.modal.openSubsyncModal({
-      sourceTracks: [{ id: 2, label: 'External #2 - eng' }],
-      ffsubsyncAvailable: true,
-    });
+    harness.modal.openSubsyncModal(BASE_PAYLOAD);
 
     harness.runButton.dispatch('click');
     await Promise.resolve();
@@ -219,7 +264,8 @@ test('manual subsync failure closes during run, then reopens modal with error',
     assert.equal(harness.statusClassList.contains('error'), true);
     assert.equal(harness.ctx.dom.subsyncRunButton.disabled, false);
     assert.equal(harness.ctx.dom.subsyncEngineAlass.checked, true);
-    assert.equal(harness.ctx.dom.subsyncSourceSelect.value, '2');
+    assert.equal(harness.referenceSelect.value, '2');
+    assert.equal(harness.targetSelect.value, '1');
     assert.equal(harness.getNotifyClosedCalls(), 1);
     assert.equal(harness.getNotifyOpenedCalls(), 1);
   } finally {
@@ -231,15 +277,17 @@ test('subsync modal disables ffsubsync when payload marks it unavailable', () =>
   const harness = createTestHarness(async () => ({ ok: true, message: 'ok' }));
 
   try {
-    harness.modal.openSubsyncModal({
-      sourceTracks: [{ id: 2, label: 'External #2 - eng' }],
-      ffsubsyncAvailable: false,
-    });
+    harness.modal.openSubsyncModal(
+      payloadWith({ ffsubsyncAvailable: false, videoReferenceAvailable: false }),
+    );
 
     assert.equal(harness.ctx.dom.subsyncEngineAlass.checked, true);
     assert.equal(harness.ctx.dom.subsyncEngineFfsubsync.checked, false);
     assert.equal(harness.ctx.dom.subsyncEngineFfsubsync.disabled, true);
-    assert.equal(harness.ctx.dom.subsyncStatus.textContent, 'Choose alass source, then run.');
+    assert.equal(
+      harness.ctx.dom.subsyncStatus.textContent,
+      'Choose the alass reference and out-of-sync subtitle, then run.',
+    );
   } finally {
     harness.restoreGlobals();
   }
@@ -253,10 +301,14 @@ test('subsync modal ignores enter submission when no sync engine is available',
   });
 
   try {
-    harness.modal.openSubsyncModal({
-      sourceTracks: [],
-      ffsubsyncAvailable: false,
-    });
+    harness.modal.openSubsyncModal(
+      payloadWith({
+        subtitleTracks: [{ id: 1, label: 'External #1 - jpn (active)' }],
+        defaultReferenceTrackId: null,
+        videoReferenceAvailable: false,
+        ffsubsyncAvailable: false,
+      }),
+    );
 
     harness.modal.handleSubsyncKeydown({
       key: 'Enter',
@@ -270,3 +322,102 @@ test('subsync modal ignores enter submission when no sync engine is available',
     harness.restoreGlobals();
   }
 });
+
+test('subsync modal defaults reference to the secondary track and target to the primary', async () => {
+  let request: SubsyncManualRunRequest | null = null;
+  const harness = createTestHarness(async (nextRequest) => {
+    request = nextRequest;
+    return { ok: true, message: 'ok' };
+  });
+
+  try {
+    harness.modal.wireDomEvents();
+    harness.modal.openSubsyncModal(BASE_PAYLOAD);
+
+    assert.equal(harness.referenceSelect.value, '2');
+    assert.equal(harness.targetSelect.value, '1');
+
+    harness.runButton.dispatch('click');
+    await flushMicrotasks();
+
+    assert.deepEqual(request, {
+      engine: 'alass',
+      targetTrackId: 1,
+      referenceMode: 'track',
+      referenceTrackId: 2,
+    });
+  } finally {
+    harness.restoreGlobals();
+  }
+});
+
+test('subsync modal offers the video file as an alass reference and excludes the target track', () => {
+  const harness = createTestHarness(async () => ({ ok: true, message: 'ok' }));
+
+  try {
+    harness.modal.wireDomEvents();
+    harness.modal.openSubsyncModal(BASE_PAYLOAD);
+
+    assert.deepEqual(
+      harness.referenceSelect.options.map((option) => option.value),
+      ['2', 'video'],
+    );
+
+    harness.targetSelect.value = '2';
+    harness.targetSelect.dispatch('change');
+
+    assert.deepEqual(
+      harness.referenceSelect.options.map((option) => option.value),
+      ['1', 'video'],
+    );
+    assert.equal(harness.referenceSelect.value, '1');
+  } finally {
+    harness.restoreGlobals();
+  }
+});
+
+test('subsync modal sends the video reference mode when the video file is selected', async () => {
+  let request: SubsyncManualRunRequest | null = null;
+  const harness = createTestHarness(async (nextRequest) => {
+    request = nextRequest;
+    return { ok: true, message: 'ok' };
+  });
+
+  try {
+    harness.modal.wireDomEvents();
+    harness.modal.openSubsyncModal(BASE_PAYLOAD);
+
+    harness.referenceSelect.value = 'video';
+    harness.runButton.dispatch('click');
+    await flushMicrotasks();
+
+    assert.deepEqual(request, {
+      engine: 'alass',
+      targetTrackId: 1,
+      referenceMode: 'video',
+      referenceTrackId: null,
+    });
+  } finally {
+    harness.restoreGlobals();
+  }
+});
+
+test('subsync modal hides the reference picker for ffsubsync but keeps the target picker', () => {
+  const harness = createTestHarness(async () => ({ ok: true, message: 'ok' }));
+
+  try {
+    harness.modal.wireDomEvents();
+    harness.modal.openSubsyncModal(BASE_PAYLOAD);
+
+    assert.equal(harness.referenceLabelClassList.contains('hidden'), false);
+
+    harness.ctx.dom.subsyncEngineAlass.checked = false;
+    harness.ctx.dom.subsyncEngineFfsubsync.checked = true;
+    harness.ctx.dom.subsyncEngineFfsubsync.dispatch('change');
+
+    assert.equal(harness.referenceLabelClassList.contains('hidden'), true);
+    assert.equal(harness.targetSelect.value, '1');
+  } finally {
+    harness.restoreGlobals();
+  }
+});

src/renderer/modals/subsync.ts

@@ -1,6 +1,14 @@
-import type { SubsyncManualPayload } from '../../types';
+import type { SubsyncManualPayload, SubsyncManualRunRequest } from '../../types';
 import type { ModalStateReader, RendererContext } from '../context';
 
+const VIDEO_REFERENCE_VALUE = 'video';
+
+interface SubsyncSelection {
+  engine: 'alass' | 'ffsubsync';
+  referenceValue: string;
+  targetTrackId: number | null;
+}
+
 export function createSubsyncModal(
   ctx: RendererContext,
   options: {
@@ -8,27 +16,103 @@ export function createSubsyncModal(
     syncSettingsModalSubtitleSuppression: () => void;
   },
 ) {
-  let ffsubsyncAvailable = true;
+  let currentPayload: SubsyncManualPayload | null = null;
 
   function setSubsyncStatus(message: string, isError = false): void {
     ctx.dom.subsyncStatus.textContent = message;
     ctx.dom.subsyncStatus.classList.toggle('error', isError);
   }
 
-  function updateSubsyncSourceVisibility(): void {
-    const useAlass = ctx.dom.subsyncEngineAlass.checked;
-    ctx.dom.subsyncSourceLabel.classList.toggle('hidden', !useAlass);
+  function hasAlassReference(): boolean {
+    if (!currentPayload) return false;
+    return currentPayload.videoReferenceAvailable || currentPayload.subtitleTracks.length > 1;
   }
 
-  function renderSubsyncSourceTracks(): void {
-    ctx.dom.subsyncSourceSelect.innerHTML = '';
-    for (const track of ctx.state.subsyncSourceTracks) {
-      const option = document.createElement('option');
-      option.value = String(track.id);
-      option.textContent = track.label;
-      ctx.dom.subsyncSourceSelect.appendChild(option);
+  function updateSubsyncFieldVisibility(): void {
+    const useAlass = ctx.dom.subsyncEngineAlass.checked;
+    ctx.dom.subsyncReferenceLabel.classList.toggle('hidden', !useAlass);
+    ctx.dom.subsyncTargetLabel.classList.toggle(
+      'hidden',
+      ctx.state.subsyncSubtitleTracks.length === 0,
+    );
+  }
+
+  function appendOption(select: HTMLSelectElement, value: string, label: string): void {
+    const option = document.createElement('option');
+    option.value = value;
+    option.textContent = label;
+    select.appendChild(option);
+  }
+
+  function getSelectedTargetTrackId(): number | null {
+    const raw = Number.parseInt(ctx.dom.subsyncTargetSelect.value, 10);
+    return Number.isFinite(raw) ? raw : null;
+  }
+
+  function renderTargetTracks(preferredTrackId: number | null): void {
+    const select = ctx.dom.subsyncTargetSelect;
+    select.innerHTML = '';
+    select.value = '';
+    for (const track of ctx.state.subsyncSubtitleTracks) {
+      appendOption(select, String(track.id), track.label);
     }
-    ctx.dom.subsyncSourceSelect.disabled = ctx.state.subsyncSourceTracks.length === 0;
+    select.disabled = ctx.state.subsyncSubtitleTracks.length === 0;
+
+    const preferred = ctx.state.subsyncSubtitleTracks.find(
+      (track) => track.id === preferredTrackId,
+    );
+    const fallback = ctx.state.subsyncSubtitleTracks[0];
+    const selected = preferred ?? fallback;
+    if (selected) {
+      select.value = String(selected.id);
+    }
+  }
+
+  function renderReferenceTracks(preferredValue: string | null): void {
+    const select = ctx.dom.subsyncReferenceSelect;
+    const targetTrackId = getSelectedTargetTrackId();
+    const values: string[] = [];
+
+    select.innerHTML = '';
+    select.value = '';
+    for (const track of ctx.state.subsyncSubtitleTracks) {
+      if (track.id === targetTrackId) continue;
+      appendOption(select, String(track.id), track.label);
+      values.push(String(track.id));
+    }
+    if (currentPayload?.videoReferenceAvailable) {
+      appendOption(select, VIDEO_REFERENCE_VALUE, 'Video file (audio reference)');
+      values.push(VIDEO_REFERENCE_VALUE);
+    }
+    select.disabled = values.length === 0;
+
+    const preferred = preferredValue && values.includes(preferredValue) ? preferredValue : null;
+    const defaultTrackValue =
+      currentPayload?.defaultReferenceTrackId !== null &&
+      currentPayload?.defaultReferenceTrackId !== undefined
+        ? String(currentPayload.defaultReferenceTrackId)
+        : null;
+    const fallback =
+      defaultTrackValue && values.includes(defaultTrackValue) ? defaultTrackValue : values[0];
+    const selected = preferred ?? fallback;
+    if (selected) {
+      select.value = selected;
+    }
+  }
+
+  function describeSubsyncState(): string {
+    if (!currentPayload) return '';
+    const alassReady = hasAlassReference();
+    if (alassReady && currentPayload.ffsubsyncAvailable) {
+      return 'Choose engine, reference and out-of-sync subtitle, then run.';
+    }
+    if (alassReady) {
+      return 'Choose the alass reference and out-of-sync subtitle, then run.';
+    }
+    if (currentPayload.ffsubsyncAvailable) {
+      return 'No reference available for alass. Use ffsubsync.';
+    }
+    return 'No sync engine available for current media.';
   }
 
   function closeSubsyncModal(): void {
@@ -46,30 +130,27 @@ export function createSubsyncModal(
     }
   }
 
-  function openSubsyncModal(payload: SubsyncManualPayload): void {
+  function openSubsyncModal(payload: SubsyncManualPayload, selection?: SubsyncSelection): void {
     ctx.state.subsyncSubmitting = false;
-    ctx.state.subsyncSourceTracks = payload.sourceTracks;
-    ffsubsyncAvailable = payload.ffsubsyncAvailable;
+    ctx.state.subsyncSubtitleTracks = payload.subtitleTracks;
+    currentPayload = payload;
 
-    const hasSources = ctx.state.subsyncSourceTracks.length > 0;
-    ctx.dom.subsyncEngineAlass.checked = hasSources;
-    ctx.dom.subsyncEngineFfsubsync.checked = !hasSources && ffsubsyncAvailable;
-    ctx.dom.subsyncEngineFfsubsync.disabled = !ffsubsyncAvailable;
-    ctx.dom.subsyncRunButton.disabled = !hasSources && !ffsubsyncAvailable;
+    const alassReady = hasAlassReference();
+    const useAlass = selection ? selection.engine === 'alass' && alassReady : alassReady;
+    ctx.dom.subsyncEngineAlass.checked = useAlass;
+    ctx.dom.subsyncEngineFfsubsync.checked = !useAlass && payload.ffsubsyncAvailable;
+    ctx.dom.subsyncEngineAlass.disabled = !alassReady;
+    ctx.dom.subsyncEngineFfsubsync.disabled = !payload.ffsubsyncAvailable;
+    ctx.dom.subsyncRunButton.disabled = !alassReady && !payload.ffsubsyncAvailable;
 
-    renderSubsyncSourceTracks();
-    updateSubsyncSourceVisibility();
-
-    setSubsyncStatus(
-      !ffsubsyncAvailable && hasSources
-        ? 'Choose alass source, then run.'
-        : !ffsubsyncAvailable
-          ? 'No source subtitles available for alass.'
-          : hasSources
-            ? 'Choose engine and source, then run.'
-            : 'No source subtitles available for alass. Use ffsubsync.',
-      false,
+    renderTargetTracks(
+      selection
+        ? (selection.targetTrackId ?? payload.defaultTargetTrackId)
+        : payload.defaultTargetTrackId,
     );
+    renderReferenceTracks(selection?.referenceValue ?? null);
+    updateSubsyncFieldVisibility();
+    setSubsyncStatus(describeSubsyncState(), false);
 
     ctx.state.subsyncModalOpen = true;
     options.syncSettingsModalSubtitleSuppression();
@@ -80,25 +161,11 @@ export function createSubsyncModal(
   }
 
   function reopenSubsyncModalWithError(
-    sourceTracks: SubsyncManualPayload['sourceTracks'],
-    engine: 'alass' | 'ffsubsync',
-    sourceTrackId: number | null,
+    payload: SubsyncManualPayload,
+    selection: SubsyncSelection,
     message: string,
   ): void {
-    openSubsyncModal({ sourceTracks, ffsubsyncAvailable });
-
-    if (engine === 'alass' && sourceTracks.length > 0) {
-      ctx.dom.subsyncEngineAlass.checked = true;
-      ctx.dom.subsyncEngineFfsubsync.checked = false;
-      if (Number.isFinite(sourceTrackId)) {
-        ctx.dom.subsyncSourceSelect.value = String(sourceTrackId);
-      }
-    } else if (ffsubsyncAvailable) {
-      ctx.dom.subsyncEngineAlass.checked = false;
-      ctx.dom.subsyncEngineFfsubsync.checked = true;
-    }
-
-    updateSubsyncSourceVisibility();
+    openSubsyncModal(payload, selection);
     setSubsyncStatus(message, true);
     window.electronAPI.notifyOverlayModalOpened('subsync');
   }
@@ -106,6 +173,7 @@ export function createSubsyncModal(
   async function runSubsyncManualFromModal(): Promise<void> {
     if (ctx.state.subsyncSubmitting) return;
     if (ctx.dom.subsyncRunButton.disabled) return;
+    if (!currentPayload) return;
 
     const useAlass = ctx.dom.subsyncEngineAlass.checked;
     const useFfsubsync = ctx.dom.subsyncEngineFfsubsync.checked;
@@ -115,33 +183,46 @@ export function createSubsyncModal(
     }
 
     const engine = useAlass ? 'alass' : 'ffsubsync';
-    const sourceTrackId =
-      engine === 'alass' && ctx.dom.subsyncSourceSelect.value
-        ? Number.parseInt(ctx.dom.subsyncSourceSelect.value, 10)
-        : null;
+    const referenceValue = ctx.dom.subsyncReferenceSelect.value;
+    const targetTrackId = getSelectedTargetTrackId();
 
-    if (engine === 'alass' && !Number.isFinite(sourceTrackId)) {
-      setSubsyncStatus('Select a source subtitle track for alass.', true);
+    if (targetTrackId === null) {
+      setSubsyncStatus('Select the out-of-sync subtitle track to retime.', true);
+      return;
+    }
+    if (engine === 'alass' && !referenceValue) {
+      setSubsyncStatus('Select a reference for alass.', true);
       return;
     }
 
-    const sourceTracksSnapshot = ctx.state.subsyncSourceTracks.map((track) => ({ ...track }));
+    const useVideoReference = referenceValue === VIDEO_REFERENCE_VALUE;
+    const request: SubsyncManualRunRequest = {
+      engine,
+      targetTrackId,
+    };
+    if (engine === 'alass') {
+      request.referenceMode = useVideoReference ? 'video' : 'track';
+      request.referenceTrackId = useVideoReference ? null : Number.parseInt(referenceValue, 10);
+    }
+
+    const payloadSnapshot: SubsyncManualPayload = {
+      ...currentPayload,
+      subtitleTracks: currentPayload.subtitleTracks.map((track) => ({ ...track })),
+    };
+    const selection: SubsyncSelection = { engine, referenceValue, targetTrackId };
+
     ctx.state.subsyncSubmitting = true;
     ctx.dom.subsyncRunButton.disabled = true;
     closeSubsyncModal();
 
     try {
-      const result = await window.electronAPI.runSubsyncManual({
-        engine,
-        sourceTrackId,
-      });
+      const result = await window.electronAPI.runSubsyncManual(request);
       if (result.ok) return;
-      reopenSubsyncModalWithError(sourceTracksSnapshot, engine, sourceTrackId, result.message);
+      reopenSubsyncModalWithError(payloadSnapshot, selection, result.message);
     } catch (error) {
       reopenSubsyncModalWithError(
-        sourceTracksSnapshot,
-        engine,
-        sourceTrackId,
+        payloadSnapshot,
+        selection,
         `Subsync failed: ${(error as Error).message}`,
       );
     } finally {
@@ -171,10 +252,13 @@ export function createSubsyncModal(
       closeSubsyncModal();
     });
     ctx.dom.subsyncEngineAlass.addEventListener('change', () => {
-      updateSubsyncSourceVisibility();
+      updateSubsyncFieldVisibility();
     });
     ctx.dom.subsyncEngineFfsubsync.addEventListener('change', () => {
-      updateSubsyncSourceVisibility();
+      updateSubsyncFieldVisibility();
+    });
+    ctx.dom.subsyncTargetSelect.addEventListener('change', () => {
+      renderReferenceTracks(ctx.dom.subsyncReferenceSelect.value || null);
     });
     ctx.dom.subsyncRunButton.addEventListener('click', () => {
       void runSubsyncManualFromModal();

src/renderer/state.ts

@@ -18,7 +18,7 @@ import type {
   SubtitlePosition,
   SubtitleSidebarSnapshotConfig,
   SubtitleCue,
-  SubsyncSourceTrack,
+  SubsyncSubtitleTrack,
   YoutubePickerOpenPayload,
 } from '../types';
 
@@ -85,7 +85,7 @@ export type RendererState = {
   characterDictionaryStatus: string;
 
   subsyncModalOpen: boolean;
-  subsyncSourceTracks: SubsyncSourceTrack[];
+  subsyncSubtitleTracks: SubsyncSubtitleTrack[];
   subsyncSubmitting: boolean;
 
   controllerSelectModalOpen: boolean;
@@ -213,7 +213,7 @@ export function createRendererState(): RendererState {
     characterDictionaryStatus: '',
 
     subsyncModalOpen: false,
-    subsyncSourceTracks: [],
+    subsyncSubtitleTracks: [],
     subsyncSubmitting: false,
 
     controllerSelectModalOpen: false,

src/renderer/utils/dom.ts

@@ -90,8 +90,10 @@ export type RendererDom = {
   subsyncCloseButton: HTMLButtonElement;
   subsyncEngineAlass: HTMLInputElement;
   subsyncEngineFfsubsync: HTMLInputElement;
-  subsyncSourceLabel: HTMLLabelElement;
-  subsyncSourceSelect: HTMLSelectElement;
+  subsyncReferenceLabel: HTMLLabelElement;
+  subsyncReferenceSelect: HTMLSelectElement;
+  subsyncTargetLabel: HTMLLabelElement;
+  subsyncTargetSelect: HTMLSelectElement;
   subsyncRunButton: HTMLButtonElement;
   subsyncStatus: HTMLDivElement;
 
@@ -255,8 +257,10 @@ export function resolveRendererDom(): RendererDom {
     subsyncCloseButton: getRequiredElement<HTMLButtonElement>('subsyncClose'),
     subsyncEngineAlass: getRequiredElement<HTMLInputElement>('subsyncEngineAlass'),
     subsyncEngineFfsubsync: getRequiredElement<HTMLInputElement>('subsyncEngineFfsubsync'),
-    subsyncSourceLabel: getRequiredElement<HTMLLabelElement>('subsyncSourceLabel'),
-    subsyncSourceSelect: getRequiredElement<HTMLSelectElement>('subsyncSourceSelect'),
+    subsyncReferenceLabel: getRequiredElement<HTMLLabelElement>('subsyncReferenceLabel'),
+    subsyncReferenceSelect: getRequiredElement<HTMLSelectElement>('subsyncReferenceSelect'),
+    subsyncTargetLabel: getRequiredElement<HTMLLabelElement>('subsyncTargetLabel'),
+    subsyncTargetSelect: getRequiredElement<HTMLSelectElement>('subsyncTargetSelect'),
     subsyncRunButton: getRequiredElement<HTMLButtonElement>('subsyncRun'),
     subsyncStatus: getRequiredElement<HTMLDivElement>('subsyncStatus'),
 

src/shared/ipc/validators.ts

@@ -295,14 +295,27 @@ export function parseControllerConfigUpdate(value: unknown): ControllerConfigUpd
 
 export function parseSubsyncManualRunRequest(value: unknown): SubsyncManualRunRequest | null {
   if (!isObject(value)) return null;
-  const { engine, sourceTrackId } = value;
+  const { engine, referenceMode, referenceTrackId, targetTrackId } = value;
   if (engine !== 'alass' && engine !== 'ffsubsync') return null;
-  if (sourceTrackId !== undefined && sourceTrackId !== null && !isInteger(sourceTrackId)) {
+  if (referenceMode !== undefined && referenceMode !== 'track' && referenceMode !== 'video') {
     return null;
   }
+
+  const parseOptionalTrackId = (raw: unknown): number | null | undefined | false => {
+    if (raw === undefined) return undefined;
+    if (raw === null) return null;
+    return isInteger(raw) ? raw : false;
+  };
+
+  const parsedReferenceTrackId = parseOptionalTrackId(referenceTrackId);
+  const parsedTargetTrackId = parseOptionalTrackId(targetTrackId);
+  if (parsedReferenceTrackId === false || parsedTargetTrackId === false) return null;
+
   return {
     engine,
-    sourceTrackId: sourceTrackId === undefined ? undefined : (sourceTrackId as number | null),
+    referenceMode,
+    referenceTrackId: parsedReferenceTrackId,
+    targetTrackId: parsedTargetTrackId,
   };
 }
 

src/subsync/utils.ts

@@ -33,7 +33,8 @@ export interface SubsyncContext {
   videoPath: string;
   primaryTrack: MpvTrack;
   secondaryTrack: MpvTrack | null;
-  sourceTracks: MpvTrack[];
+  /** Every usable subtitle track, including the primary one. */
+  subtitleTracks: MpvTrack[];
   audioStreamIndex: number | null;
 }
 

src/types/runtime.ts

@@ -78,19 +78,28 @@ export interface MpvClient {
   send(command: { command: unknown[]; request_id?: number }): boolean;
 }
 
-export interface SubsyncSourceTrack {
+export interface SubsyncSubtitleTrack {
   id: number;
   label: string;
 }
 
 export interface SubsyncManualPayload {
-  sourceTracks: SubsyncSourceTrack[];
+  subtitleTracks: SubsyncSubtitleTrack[];
+  defaultReferenceTrackId: number | null;
+  defaultTargetTrackId: number | null;
+  videoReferenceAvailable: boolean;
   ffsubsyncAvailable: boolean;
 }
 
+export type SubsyncReferenceMode = 'track' | 'video';
+
 export interface SubsyncManualRunRequest {
   engine: 'alass' | 'ffsubsync';
-  sourceTrackId?: number | null;
+  /** alass reference source: another subtitle track, or the loaded media file itself. */
+  referenceMode?: SubsyncReferenceMode;
+  referenceTrackId?: number | null;
+  /** Subtitle track to retime. Defaults to the active primary track. */
+  targetTrackId?: number | null;
 }
 
 export interface SubsyncResult {