feat(tv): persist downloaded opensubtitles across app restarts

utils/atoms/downloadedSubtitles.ts

@@ -0,0 +1,162 @@
+/**
+ * Downloaded Subtitles Storage
+ *
+ * Persists metadata about client-side downloaded subtitles (from OpenSubtitles).
+ * Subtitle files are stored in Paths.cache/streamyfin-subtitles/ directory.
+ * Filenames are prefixed with itemId for organization: {itemId}_{filename}
+ *
+ * While files are in cache, metadata is persisted in MMKV so subtitles survive
+ * app restarts (unless cache is manually cleared by the user).
+ *
+ * TV platform only.
+ */
+
+import { storage } from "../mmkv";
+
+// MMKV storage key
+const DOWNLOADED_SUBTITLES_KEY = "downloadedSubtitles.json";
+
+/**
+ * Metadata for a downloaded subtitle file
+ */
+export interface DownloadedSubtitle {
+  /** Unique identifier (uuid) */
+  id: string;
+  /** Jellyfin item ID */
+  itemId: string;
+  /** Local file path in documents directory */
+  filePath: string;
+  /** Display name */
+  name: string;
+  /** 3-letter language code */
+  language: string;
+  /** File format (srt, ass, etc.) */
+  format: string;
+  /** Source provider */
+  source: "opensubtitles";
+  /** Unix timestamp when downloaded */
+  downloadedAt: number;
+}
+
+/**
+ * Storage structure for downloaded subtitles
+ */
+interface DownloadedSubtitlesStorage {
+  /** Map of itemId to array of downloaded subtitles */
+  byItemId: Record<string, DownloadedSubtitle[]>;
+}
+
+/**
+ * Load the storage from MMKV
+ */
+function loadStorage(): DownloadedSubtitlesStorage {
+  try {
+    const data = storage.getString(DOWNLOADED_SUBTITLES_KEY);
+    if (data) {
+      return JSON.parse(data) as DownloadedSubtitlesStorage;
+    }
+  } catch {
+    // Ignore parse errors, return empty storage
+  }
+  return { byItemId: {} };
+}
+
+/**
+ * Save the storage to MMKV
+ */
+function saveStorage(data: DownloadedSubtitlesStorage): void {
+  try {
+    storage.set(DOWNLOADED_SUBTITLES_KEY, JSON.stringify(data));
+  } catch (error) {
+    console.error("Failed to save downloaded subtitles:", error);
+  }
+}
+
+/**
+ * Get all downloaded subtitles for a specific Jellyfin item
+ */
+export function getSubtitlesForItem(itemId: string): DownloadedSubtitle[] {
+  const data = loadStorage();
+  return data.byItemId[itemId] ?? [];
+}
+
+/**
+ * Add a downloaded subtitle to storage
+ */
+export function addDownloadedSubtitle(subtitle: DownloadedSubtitle): void {
+  const data = loadStorage();
+
+  // Initialize array for item if it doesn't exist
+  if (!data.byItemId[subtitle.itemId]) {
+    data.byItemId[subtitle.itemId] = [];
+  }
+
+  // Check if subtitle with same id already exists and update it
+  const existingIndex = data.byItemId[subtitle.itemId].findIndex(
+    (s) => s.id === subtitle.id,
+  );
+
+  if (existingIndex !== -1) {
+    // Update existing entry
+    data.byItemId[subtitle.itemId][existingIndex] = subtitle;
+  } else {
+    // Add new entry
+    data.byItemId[subtitle.itemId].push(subtitle);
+  }
+
+  saveStorage(data);
+}
+
+/**
+ * Remove a downloaded subtitle from storage
+ */
+export function removeDownloadedSubtitle(
+  itemId: string,
+  subtitleId: string,
+): void {
+  const data = loadStorage();
+
+  if (data.byItemId[itemId]) {
+    data.byItemId[itemId] = data.byItemId[itemId].filter(
+      (s) => s.id !== subtitleId,
+    );
+
+    // Clean up empty arrays
+    if (data.byItemId[itemId].length === 0) {
+      delete data.byItemId[itemId];
+    }
+
+    saveStorage(data);
+  }
+}
+
+/**
+ * Remove all downloaded subtitles for a specific item
+ */
+export function removeAllSubtitlesForItem(itemId: string): void {
+  const data = loadStorage();
+
+  if (data.byItemId[itemId]) {
+    delete data.byItemId[itemId];
+    saveStorage(data);
+  }
+}
+
+/**
+ * Check if a subtitle file already exists for an item by language
+ */
+export function hasSubtitleForLanguage(
+  itemId: string,
+  language: string,
+): boolean {
+  const subtitles = getSubtitlesForItem(itemId);
+  return subtitles.some((s) => s.language === language);
+}
+
+/**
+ * Get all downloaded subtitles across all items
+ */
+export function getAllDownloadedSubtitles(): DownloadedSubtitle[] {
+  const data = loadStorage();
+  return Object.values(data.byItemId).flat();
+}

utils/opensubtitles/api.ts

@@ -87,6 +87,58 @@ export class OpenSubtitlesApiError extends Error {
   }
 }
 
+/**
+ * Mapping between ISO 639-1 (2-letter) and ISO 639-2B (3-letter) language codes
+ */
+const ISO_639_MAPPING: Record<string, string> = {
+  en: "eng",
+  es: "spa",
+  fr: "fre",
+  de: "ger",
+  it: "ita",
+  pt: "por",
+  ru: "rus",
+  ja: "jpn",
+  ko: "kor",
+  zh: "chi",
+  ar: "ara",
+  pl: "pol",
+  nl: "dut",
+  sv: "swe",
+  no: "nor",
+  da: "dan",
+  fi: "fin",
+  tr: "tur",
+  cs: "cze",
+  el: "gre",
+  he: "heb",
+  hu: "hun",
+  ro: "rum",
+  th: "tha",
+  vi: "vie",
+  id: "ind",
+  ms: "may",
+  bg: "bul",
+  hr: "hrv",
+  sk: "slo",
+  sl: "slv",
+  uk: "ukr",
+};
+
+// Reverse mapping: 3-letter to 2-letter
+const ISO_639_REVERSE: Record<string, string> = Object.fromEntries(
+  Object.entries(ISO_639_MAPPING).map(([k, v]) => [v, k]),
+);
+
+/**
+ * Convert ISO 639-2B (3-letter) to ISO 639-1 (2-letter) language code
+ * OpenSubtitles REST API uses 2-letter codes
+ */
+function toIso6391(code: string): string {
+  if (code.length === 2) return code;
+  return ISO_639_REVERSE[code.toLowerCase()] || code;
+}
+
 /**
  * OpenSubtitles API client for direct subtitle fetching
  */
@@ -138,7 +190,7 @@ export class OpenSubtitlesApi {
     const queryParams = new URLSearchParams();
 
     if (params.imdbId) {
-      // Ensure IMDB ID has correct format (with "tt" prefix)
+      // Ensure IMDB ID has "tt" prefix
       const imdbId = params.imdbId.startsWith("tt")
         ? params.imdbId
         : `tt${params.imdbId}`;
@@ -151,7 +203,12 @@ export class OpenSubtitlesApi {
       queryParams.set("year", params.year.toString());
     }
     if (params.languages) {
-      queryParams.set("languages", params.languages);
+      // Convert 3-letter codes to 2-letter codes (API uses ISO 639-1)
+      const lang =
+        params.languages.length === 3
+          ? toIso6391(params.languages)
+          : params.languages;
+      queryParams.set("languages", lang);
     }
     if (params.seasonNumber !== undefined) {
       queryParams.set("season_number", params.seasonNumber.toString());
@@ -179,50 +236,18 @@ export class OpenSubtitlesApi {
   }
 }
 
+/**
+ * Convert ISO 639-2B (3-letter) to ISO 639-1 (2-letter) language code
+ * Exported for external use
+ */
+export { toIso6391 };
+
 /**
  * Convert ISO 639-1 (2-letter) to ISO 639-2B (3-letter) language code
- * OpenSubtitles uses ISO 639-2B codes
  */
 export function toIso6392B(code: string): string {
-  const mapping: Record<string, string> = {
-    en: "eng",
-    es: "spa",
-    fr: "fre",
-    de: "ger",
-    it: "ita",
-    pt: "por",
-    ru: "rus",
-    ja: "jpn",
-    ko: "kor",
-    zh: "chi",
-    ar: "ara",
-    pl: "pol",
-    nl: "dut",
-    sv: "swe",
-    no: "nor",
-    da: "dan",
-    fi: "fin",
-    tr: "tur",
-    cs: "cze",
-    el: "gre",
-    he: "heb",
-    hu: "hun",
-    ro: "rum",
-    th: "tha",
-    vi: "vie",
-    id: "ind",
-    ms: "may",
-    bg: "bul",
-    hr: "hrv",
-    sk: "slo",
-    sl: "slv",
-    uk: "ukr",
-  };
-
-  // If already 3 letters, return as-is
   if (code.length === 3) return code;
-
-  return mapping[code.toLowerCase()] || code;
+  return ISO_639_MAPPING[code.toLowerCase()] || code;
 }
 
 /**