feat(subtitles): generate Japanese subtitles during Jellyfin playback (#294)

* feat(subtitles): generate Japanese subtitles during Jellyfin playback

- Read the item's original file via toJellyfinOriginalStreamUrl and write output to a temp dir
- Transcoded playback uses Jellyfin's audio index and only external references
- Show Jellyfin media by title and redact URL tokens in subprocess errors
- Update overlay copy, docs, and changelog fragment

* fix(subtitles): redact full stream tokens and reuse one Jellyfin output folder

* test(subtitles): make Jellyfin output path assertions platform-neutral

- Compare dirname/basename via node:path instead of POSIX-only regexes
- Assert the full sub-add command uses the generated output path

src/core/services/index.ts

@@ -130,6 +130,7 @@ export {
   listSubtitleTracks as listJellyfinSubtitleTracksRuntime,
   resolvePlaybackPlan as resolveJellyfinPlaybackPlanRuntime,
   ticksToSeconds as jellyfinTicksToSecondsRuntime,
+  toJellyfinOriginalStreamUrl,
 } from './jellyfin';
 export { JellyfinRemoteSessionService } from './jellyfin-remote';
 export {

src/core/services/jellyfin.test.ts

@@ -7,6 +7,7 @@ import {
   listSubtitleTracks,
   resolvePlaybackPlan,
   ticksToSeconds,
+  toJellyfinOriginalStreamUrl,
 } from './jellyfin';
 
 const clientInfo = {
@@ -862,3 +863,26 @@ test('resolvePlaybackPlan replaces a legacy api_key on the server transcoding ur
     globalThis.fetch = originalFetch;
   }
 });
+
+test('toJellyfinOriginalStreamUrl maps direct and transcoded playback to the original file', () => {
+  assert.equal(
+    toJellyfinOriginalStreamUrl(
+      'https://media.example/jf/videos/item-1/master.m3u8?ApiKey=token&MediaSourceId=src&VideoCodec=h264&StartTimeTicks=9',
+      'item-1',
+    ),
+    'https://media.example/jf/Videos/item-1/stream?static=true&ApiKey=token&MediaSourceId=src',
+  );
+  assert.equal(
+    toJellyfinOriginalStreamUrl(
+      'http://jf.local:8096/Videos/item-1/stream?static=true&api_key=legacy&AudioStreamIndex=2',
+      'item-1',
+    ),
+    'http://jf.local:8096/Videos/item-1/stream?static=true&ApiKey=legacy',
+  );
+  assert.equal(
+    toJellyfinOriginalStreamUrl('https://jf/Videos/other/stream?ApiKey=token', 'item-1'),
+    null,
+  );
+  assert.equal(toJellyfinOriginalStreamUrl('https://jf/Videos/item-1/stream', 'item-1'), null);
+  assert.equal(toJellyfinOriginalStreamUrl('/media/item-1.mkv', 'item-1'), null);
+});

src/core/services/jellyfin.ts

@@ -254,6 +254,29 @@ function createDirectPlayUrl(
   return `${session.serverUrl}/Videos/${itemId}/stream?${query.toString()}`;
 }
 
+/**
+ * Maps a playing stream URL of `itemId`, direct or transcoded, to its original file. Returns null
+ * when the URL is not that item's stream or carries no access token.
+ */
+export function toJellyfinOriginalStreamUrl(playbackUrl: string, itemId: string): string | null {
+  let url: URL;
+  try {
+    url = new URL(playbackUrl);
+  } catch {
+    return null;
+  }
+  const at = url.pathname.toLowerCase().indexOf(`/videos/${itemId.toLowerCase()}/`);
+  if (!/^https?:$/.test(url.protocol) || !itemId || at < 0) return null;
+  const param = (pattern: RegExp) =>
+    [...url.searchParams].find(([key, value]) => pattern.test(key) && value)?.[1];
+  const accessToken = param(/^api_?key$/i);
+  if (!accessToken) return null;
+  const query = new URLSearchParams({ static: 'true', ApiKey: accessToken });
+  const mediaSourceId = param(/^mediasourceid$/i);
+  if (mediaSourceId) query.set('MediaSourceId', mediaSourceId);
+  return `${url.origin}${url.pathname.slice(0, at)}/Videos/${itemId}/stream?${query.toString()}`;
+}
+
 function createTranscodeUrl(
   session: JellyfinAuthSession,
   itemId: string,

src/core/services/subtitle-generation-process.ts

@@ -3,6 +3,11 @@ import { expandSubtitleGenerationPath } from './subtitle-generation-files';
 
 const OUTPUT_LIMIT = 64 * 1024;
 
+// ffmpeg echoes input URLs in its errors; streamed media carries access tokens in the query.
+function redactUrlCredentials(text: string): string {
+  return text.replace(/([?&](?:api_?key|token|access_token)=)[^&#\s'"]+/gi, '$1<redacted>');
+}
+
 // Keep partial lines between chunks: ffmpeg and whisper both report progress on stderr.
 export function runSubtitleGenerationProcess(input: {
   command: string;
@@ -63,7 +68,11 @@ export function runSubtitleGenerationProcess(input: {
       cleanup();
       if (input.signal?.aborted) reject(new Error('Subtitle generation cancelled.'));
       else if (code !== 0) {
-        reject(new Error(`${input.command} exited with status ${code}: ${stderr.trim()}`));
+        reject(
+          new Error(
+            `${input.command} exited with status ${code}: ${redactUrlCredentials(stderr.trim())}`,
+          ),
+        );
       } else resolve(stdout);
     });
   });

src/core/services/subtitle-generation.test.ts

@@ -378,7 +378,22 @@ test('empty executable paths find tools on PATH and explicit overrides take prec
     }
   }));
 
-test('generation rejects remote media, missing models, and missing tools before starting a subprocess', () =>
+test('generation reads an HTTP stream as-is and saves to the requested output', () =>
+  fixture(async (directory) => {
+    const input = await generationFixture(directory);
+    const mediaPath = 'https://jellyfin.example/Videos/item/stream?static=true&ApiKey=secret';
+    const outputPath = path.join(directory, 'out', 'stream.ja.srt');
+    await mkdir(path.dirname(outputPath));
+    assert.equal(await generateJapaneseSubtitles({ ...input, mediaPath, outputPath }), outputPath);
+    const calls: string[][] = (await readFile(input.callsPath, 'utf8'))
+      .trim()
+      .split('\n')
+      .map((line) => JSON.parse(line));
+    assert.equal(calls[0]?.at(-1), mediaPath);
+    assert.equal(calls[1]?.[calls[1].indexOf('-i') + 1], mediaPath);
+  }));
+
+test('generation rejects remote media without an output path, missing models, and missing tools before starting a subprocess', () =>
   fixture(async (directory) => {
     const input = await generationFixture(directory);
     await assert.rejects(
@@ -473,6 +488,17 @@ test('process cancellation terminates work and bounds diagnostic output', () =>
         error.message.length < 66000 &&
         error.message.includes('status 7'),
     );
+    const unauthorized = await executable(
+      directory,
+      'unauthorized',
+      "process.stderr.write('https://host/Videos/1/stream?ApiKey=se+cr/et==&static=true: Server returned 401');process.exitCode=1;",
+    );
+    await assert.rejects(
+      runSubtitleGenerationProcess({ command: unauthorized, args: [] }),
+      (error: unknown) =>
+        error instanceof Error &&
+        error.message.includes('?ApiKey=<redacted>&static=true: Server returned 401'),
+    );
   }));
 
 test('download uses the pinned model revision and removes files that fail integrity', () =>

src/core/services/subtitle-generation.ts

@@ -191,6 +191,7 @@ export async function requireSubtitleGenerationSetup(
 export async function generateJapaneseSubtitles(input: {
   config: SubtitleGenerationConfig;
   modelDirectory: string;
+  /** A local file, or an http(s) stream when `outputPath` is set. */
   mediaPath: string;
   audioStreamIndex?: number;
   references?: readonly SubtitleGenerationReference[];
@@ -201,10 +202,12 @@ export async function generateJapaneseSubtitles(input: {
   signal?: AbortSignal;
 }): Promise<string> {
   input.signal?.throwIfAborted();
-  if (/^[a-z][a-z\d+.-]*:\/\//i.test(input.mediaPath))
+  // HTTP streams are read by ffmpeg directly but have no directory to save beside.
+  const remote = /^https?:\/\//i.test(input.mediaPath);
+  if (remote ? !input.outputPath : /^[a-z][a-z\d+.-]*:\/\//i.test(input.mediaPath))
     throw new Error('Subtitle generation requires a local media file.');
-  const mediaPath = path.resolve(input.mediaPath);
-  if (!(await stat(mediaPath)).isFile())
+  const mediaPath = remote ? input.mediaPath : path.resolve(input.mediaPath);
+  if (!remote && !(await stat(mediaPath)).isFile())
     throw new Error('Subtitle generation requires a local media file.');
   if (input.outputPath) await ensureAvailableOutput(path.resolve(input.outputPath));
   await ensureWritableDirectory(