Fix launcher backend parsing and yt-dlp overrides

src/core/services/youtube/metadata-probe.ts

@@ -1,5 +1,6 @@
 import { spawn } from 'node:child_process';
 import type { YoutubeVideoMetadata } from '../immersion-tracker/types';
+import { getYoutubeYtDlpCommand } from './ytdlp-command';
 
 const YOUTUBE_METADATA_PROBE_TIMEOUT_MS = 15_000;
 
@@ -87,7 +88,7 @@ function pickChannelThumbnail(thumbnails: YtDlpThumbnail[] | undefined): string
 export async function probeYoutubeVideoMetadata(
   targetUrl: string,
 ): Promise<YoutubeVideoMetadata | null> {
-  const { stdout } = await runCapture('yt-dlp', [
+  const { stdout } = await runCapture(getYoutubeYtDlpCommand(), [
     '--dump-single-json',
     '--no-warnings',
     '--skip-download',

src/core/services/youtube/playback-resolve.ts

@@ -1,4 +1,5 @@
 import { spawn } from 'node:child_process';
+import { getYoutubeYtDlpCommand } from './ytdlp-command';
 
 const YOUTUBE_PLAYBACK_RESOLVE_TIMEOUT_MS = 15_000;
 const DEFAULT_PLAYBACK_FORMAT = 'b';
@@ -88,8 +89,7 @@ export async function resolveYoutubePlaybackUrl(
   targetUrl: string,
   format = DEFAULT_PLAYBACK_FORMAT,
 ): Promise<string> {
-  const ytDlpCommand = process.env.SUBMINER_YTDLP_BIN?.trim() || 'yt-dlp';
-  const { stdout } = await runCapture(ytDlpCommand, [
+  const { stdout } = await runCapture(getYoutubeYtDlpCommand(), [
     '--get-url',
     '--no-warnings',
     '-f',

src/core/services/youtube/track-download.test.ts

@@ -114,6 +114,39 @@ async function withFakeYtDlp<T>(
   });
 }
 
+async function withFakeYtDlpCommand<T>(
+  mode: 'both' | 'webp-only' | 'multi' | 'multi-primary-only-fail' | 'rolling-auto',
+  fn: (dir: string, binDir: string) => Promise<T>,
+): Promise<T> {
+  return await withTempDir(async (root) => {
+    const binDir = path.join(root, 'bin');
+    fs.mkdirSync(binDir, { recursive: true });
+    makeFakeYtDlpScript(binDir);
+
+    const originalPath = process.env.PATH;
+    const originalCommand = process.env.SUBMINER_YTDLP_BIN;
+    process.env.PATH = '';
+    process.env.YTDLP_FAKE_MODE = mode;
+    process.env.SUBMINER_YTDLP_BIN =
+      process.platform === 'win32' ? path.join(binDir, 'yt-dlp.cmd') : path.join(binDir, 'yt-dlp');
+    try {
+      return await fn(root, binDir);
+    } finally {
+      if (originalPath === undefined) {
+        delete process.env.PATH;
+      } else {
+        process.env.PATH = originalPath;
+      }
+      delete process.env.YTDLP_FAKE_MODE;
+      if (originalCommand === undefined) {
+        delete process.env.SUBMINER_YTDLP_BIN;
+      } else {
+        process.env.SUBMINER_YTDLP_BIN = originalCommand;
+      }
+    }
+  });
+}
+
 async function withFakeYtDlpExpectations<T>(
   expectations: Partial<
     Record<'YTDLP_EXPECT_AUTO_SUBS' | 'YTDLP_EXPECT_MANUAL_SUBS' | 'YTDLP_EXPECT_SUB_LANG', string>
@@ -179,6 +212,29 @@ test('downloadYoutubeSubtitleTrack prefers subtitle files over later webp artifa
   });
 });
 
+test('downloadYoutubeSubtitleTrack honors SUBMINER_YTDLP_BIN when yt-dlp is not on PATH', async () => {
+  if (process.platform === 'win32') {
+    return;
+  }
+
+  await withFakeYtDlpCommand('both', async (root) => {
+    const result = await downloadYoutubeSubtitleTrack({
+      targetUrl: 'https://www.youtube.com/watch?v=abc123',
+      outputDir: path.join(root, 'out'),
+      track: {
+        id: 'auto:ja-orig',
+        language: 'ja',
+        sourceLanguage: 'ja-orig',
+        kind: 'auto',
+        label: 'Japanese (auto)',
+      },
+    });
+
+    assert.equal(path.extname(result.path), '.vtt');
+    assert.match(path.basename(result.path), /^auto-ja-orig\./);
+  });
+});
+
 test('downloadYoutubeSubtitleTrack ignores stale subtitle files from prior runs', async () => {
   if (process.platform === 'win32') {
     return;

src/core/services/youtube/track-download.ts

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
 import type { YoutubeTrackOption } from './track-probe';
+import { getYoutubeYtDlpCommand } from './ytdlp-command';
 import {
   convertYoutubeTimedTextToVtt,
   isYoutubeTimedTextExtension,
@@ -237,7 +238,7 @@ export async function downloadYoutubeSubtitleTrack(input: {
     }),
   ];
 
-  await runCapture('yt-dlp', args);
+  await runCapture(getYoutubeYtDlpCommand(), args);
   const subtitlePath = pickLatestSubtitleFile(input.outputDir, prefix);
   if (!subtitlePath) {
     throw new Error(`No subtitle file was downloaded for ${input.track.sourceLanguage}`);
@@ -281,7 +282,7 @@ export async function downloadYoutubeSubtitleTracks(input: {
   const includeManualSubs = input.tracks.some((track) => track.kind === 'manual');
 
   const result = await runCaptureDetailed(
-    'yt-dlp',
+    getYoutubeYtDlpCommand(),
     buildDownloadArgs({
       targetUrl: input.targetUrl,
       outputTemplate,

src/core/services/youtube/track-probe.test.ts

@@ -48,6 +48,37 @@ async function withFakeYtDlp<T>(
   });
 }
 
+async function withFakeYtDlpCommand<T>(
+  payload: unknown,
+  fn: () => Promise<T>,
+  options: { rawScript?: boolean } = {},
+): Promise<T> {
+  return await withTempDir(async (root) => {
+    const binDir = path.join(root, 'bin');
+    fs.mkdirSync(binDir, { recursive: true });
+    makeFakeYtDlpScript(binDir, payload, options.rawScript === true);
+    const originalPath = process.env.PATH;
+    const originalCommand = process.env.SUBMINER_YTDLP_BIN;
+    process.env.PATH = '';
+    process.env.SUBMINER_YTDLP_BIN =
+      process.platform === 'win32' ? path.join(binDir, 'yt-dlp.cmd') : path.join(binDir, 'yt-dlp');
+    try {
+      return await fn();
+    } finally {
+      if (originalPath === undefined) {
+        delete process.env.PATH;
+      } else {
+        process.env.PATH = originalPath;
+      }
+      if (originalCommand === undefined) {
+        delete process.env.SUBMINER_YTDLP_BIN;
+      } else {
+        process.env.SUBMINER_YTDLP_BIN = originalCommand;
+      }
+    }
+  });
+}
+
 test('probeYoutubeTracks prefers srv3 over vtt for automatic captions', async () => {
   await withFakeYtDlp(
     {
@@ -69,6 +100,28 @@ test('probeYoutubeTracks prefers srv3 over vtt for automatic captions', async ()
   );
 });
 
+test('probeYoutubeTracks honors SUBMINER_YTDLP_BIN when yt-dlp is not on PATH', async () => {
+  if (process.platform === 'win32') {
+    return;
+  }
+
+  await withFakeYtDlpCommand(
+    {
+      id: 'abc123',
+      title: 'Example',
+      subtitles: {
+        ja: [{ ext: 'vtt', url: 'https://example.com/ja.vtt', name: 'Japanese manual' }],
+      },
+    },
+    async () => {
+      const result = await probeYoutubeTracks('https://www.youtube.com/watch?v=abc123');
+      assert.equal(result.videoId, 'abc123');
+      assert.equal(result.tracks[0]?.downloadUrl, 'https://example.com/ja.vtt');
+      assert.equal(result.tracks[0]?.fileExtension, 'vtt');
+    },
+  );
+});
+
 test('probeYoutubeTracks keeps preferring srt for manual captions', async () => {
   await withFakeYtDlp(
     {

src/core/services/youtube/track-probe.ts

@@ -1,6 +1,7 @@
 import { spawn } from 'node:child_process';
 import type { YoutubeTrackOption } from '../../../types';
 import { formatYoutubeTrackLabel, normalizeYoutubeLangCode, type YoutubeTrackKind } from './labels';
+import { getYoutubeYtDlpCommand } from './ytdlp-command';
 
 const YOUTUBE_TRACK_PROBE_TIMEOUT_MS = 15_000;
 
@@ -111,7 +112,11 @@ function toTracks(entries: Record<string, YtDlpSubtitleEntry> | undefined, kind:
 export type { YoutubeTrackOption };
 
 export async function probeYoutubeTracks(targetUrl: string): Promise<YoutubeTrackProbeResult> {
-  const { stdout } = await runCapture('yt-dlp', ['--dump-single-json', '--no-warnings', targetUrl]);
+  const { stdout } = await runCapture(getYoutubeYtDlpCommand(), [
+    '--dump-single-json',
+    '--no-warnings',
+    targetUrl,
+  ]);
   const trimmedStdout = stdout.trim();
   if (!trimmedStdout) {
     throw new Error('yt-dlp returned empty output while probing subtitle tracks');

src/core/services/youtube/ytdlp-command.ts

@@ -0,0 +1,5 @@
+const DEFAULT_YTDLP_COMMAND = 'yt-dlp';
+
+export function getYoutubeYtDlpCommand(): string {
+  return process.env.SUBMINER_YTDLP_BIN?.trim() || DEFAULT_YTDLP_COMMAND;
+}