Merge remote-tracking branch 'origin/develop' into feat/android/choose-download-location

Signed-off-by: Lance Chant <13349722+lancechant@users.noreply.github.com>

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/atoms/filters.ts

@@ -1,6 +1,7 @@
 import { atom } from "jotai";
 import { atomWithStorage } from "jotai/utils";
 import { storage } from "../mmkv";
+import { useSettings } from "./settings";
 
 export enum SortByOption {
   Default = "Default",
@@ -15,13 +16,18 @@ export enum SortByOption {
   OfficialRating = "OfficialRating",
   PremiereDate = "PremiereDate",
   StartDate = "StartDate",
-  IsUnplayed = "IsUnplayed",
-  IsPlayed = "IsPlayed",
   AirTime = "AirTime",
   Studio = "Studio",
-  IsFavoriteOrLiked = "IsFavoriteOrLiked",
   Random = "Random",
 }
+export enum FilterByOption {
+  IsFavoriteOrLiked = "IsFavoriteOrLiked",
+  IsUnplayed = "IsUnplayed",
+  IsPlayed = "IsPlayed",
+  Likes = "Likes",
+  IsFavorite = "IsFavorite",
+  IsResumable = "IsResumable",
+}
 
 export enum SortOrderOption {
   Ascending = "Ascending",
@@ -44,14 +50,43 @@ export const sortOptions: {
   { key: SortByOption.OfficialRating, value: "Official Rating" },
   { key: SortByOption.PremiereDate, value: "Premiere Date" },
   { key: SortByOption.StartDate, value: "Start Date" },
-  { key: SortByOption.IsUnplayed, value: "Is Unplayed" },
-  { key: SortByOption.IsPlayed, value: "Is Played" },
+
   { key: SortByOption.AirTime, value: "Air Time" },
   { key: SortByOption.Studio, value: "Studio" },
-  { key: SortByOption.IsFavoriteOrLiked, value: "Is Favorite Or Liked" },
+
   { key: SortByOption.Random, value: "Random" },
 ];
 
+export const useFilterOptions = () => {
+  const { settings } = useSettings();
+  // We want to only show the watchlist option if someone has ticked that setting.
+  const filterOptions = settings?.useKefinTweaks
+    ? [
+        {
+          key: FilterByOption.IsFavoriteOrLiked,
+          value: "Is Favorite Or Liked",
+        },
+        { key: FilterByOption.IsUnplayed, value: "Is Unplayed" },
+        { key: FilterByOption.IsPlayed, value: "Is Played" },
+        { key: FilterByOption.IsFavorite, value: "Is Favorite" },
+        { key: FilterByOption.IsResumable, value: "Is Resumable" },
+        { key: FilterByOption.Likes, value: "Watchlist" },
+      ]
+    : [
+        {
+          key: FilterByOption.IsFavoriteOrLiked,
+          value: "Is Favorite Or Liked",
+        },
+        { key: FilterByOption.IsUnplayed, value: "Is Unplayed" },
+        { key: FilterByOption.IsPlayed, value: "Is Played" },
+        { key: FilterByOption.IsFavorite, value: "Is Favorite" },
+        { key: FilterByOption.IsResumable, value: "Is Resumable" },
+      ];
+  console.log("filterOptions");
+  console.log(filterOptions);
+  return filterOptions;
+};
+
 export const sortOrderOptions: {
   key: SortOrderOption;
   value: string;
@@ -67,6 +102,7 @@ export const sortByAtom = atom<SortByOption[]>([SortByOption.Default]);
 export const sortOrderAtom = atom<SortOrderOption[]>([
   SortOrderOption.Ascending,
 ]);
+export const filterByAtom = atom<FilterByOption[]>([]);
 
 export interface SortPreference {
   [libraryId: string]: SortByOption;
@@ -76,8 +112,13 @@ export interface SortOrderPreference {
   [libraryId: string]: SortOrderOption;
 }
 
+export interface FilterPreference {
+  [libraryId: string]: FilterByOption;
+}
+
 const defaultSortPreference: SortPreference = {};
 const defaultSortOrderPreference: SortOrderPreference = {};
+const defaultFilterPreference: FilterPreference = {};
 
 export const sortByPreferenceAtom = atomWithStorage<SortPreference>(
   "sortByPreference",
@@ -96,6 +137,23 @@ export const sortByPreferenceAtom = atomWithStorage<SortPreference>(
   },
 );
 
+export const FilterByPreferenceAtom = atomWithStorage<FilterPreference>(
+  "filterByPreference",
+  defaultFilterPreference,
+  {
+    getItem: (key) => {
+      const value = storage.getString(key);
+      return value ? JSON.parse(value) : null;
+    },
+    setItem: (key, value) => {
+      storage.set(key, JSON.stringify(value));
+    },
+    removeItem: (key) => {
+      storage.remove(key);
+    },
+  },
+);
+
 export const sortOrderPreferenceAtom = atomWithStorage<SortOrderPreference>(
   "sortOrderPreference",
   defaultSortOrderPreference,
@@ -126,3 +184,10 @@ export const getSortOrderPreference = (
 ) => {
   return preferences?.[libraryId] || null;
 };
+
+export const getFilterByPreference = (
+  libraryId: string,
+  preferences: FilterPreference,
+) => {
+  return preferences?.[libraryId] || null;
+};

utils/atoms/selectedTVServer.ts

@@ -0,0 +1,60 @@
+import { atom } from "jotai";
+import { storage } from "../mmkv";
+
+const STORAGE_KEY = "selectedTVServer";
+
+export interface SelectedTVServerState {
+  address: string;
+  name?: string;
+}
+
+/**
+ * Load the selected TV server from MMKV storage.
+ */
+function loadSelectedTVServer(): SelectedTVServerState | null {
+  const stored = storage.getString(STORAGE_KEY);
+  if (stored) {
+    try {
+      return JSON.parse(stored) as SelectedTVServerState;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Save the selected TV server to MMKV storage.
+ */
+function saveSelectedTVServer(server: SelectedTVServerState | null): void {
+  if (server) {
+    storage.set(STORAGE_KEY, JSON.stringify(server));
+  } else {
+    storage.remove(STORAGE_KEY);
+  }
+}
+
+/**
+ * Base atom holding the selected TV server state.
+ */
+const baseSelectedTVServerAtom = atom<SelectedTVServerState | null>(
+  loadSelectedTVServer(),
+);
+
+/**
+ * Derived atom that persists changes to MMKV storage.
+ */
+export const selectedTVServerAtom = atom(
+  (get) => get(baseSelectedTVServerAtom),
+  (_get, set, newValue: SelectedTVServerState | null) => {
+    saveSelectedTVServer(newValue);
+    set(baseSelectedTVServerAtom, newValue);
+  },
+);
+
+/**
+ * Clear the selected TV server (used when changing servers).
+ */
+export function clearSelectedTVServer(): void {
+  storage.remove(STORAGE_KEY);
+}

utils/atoms/settings.ts

@@ -6,6 +6,7 @@ import {
   type SortOrder,
   SubtitlePlaybackMode,
 } from "@jellyfin/sdk/lib/generated-client";
+import { t } from "i18next";
 import { atom, useAtom, useAtomValue } from "jotai";
 import { useCallback, useEffect, useMemo } from "react";
 import { Platform } from "react-native";
@@ -122,6 +123,46 @@ export interface MaxAutoPlayEpisodeCount {
   value: number;
 }
 
+/**
+ * The plugin may send object-typed settings as plain primitives.
+ * Resolve to the proper option object from the available choices.
+ */
+const normalizePluginValue = (
+  settingsKey: keyof Settings,
+  value: unknown,
+): unknown => {
+  if (typeof value !== "object" || value === null) {
+    const defaultVal = defaultValues[settingsKey];
+    if (
+      typeof defaultVal === "object" &&
+      defaultVal !== null &&
+      "key" in defaultVal &&
+      "value" in defaultVal
+    ) {
+      // defaultBitrate needs a lookup because its keys are human-readable
+      // (e.g. "8 Mb/s") that can't be derived from the raw value (e.g. 8000000).
+      // Other { key, value } settings like maxAutoPlayEpisodeCount work with
+      // the fallback because their keys are just String(value) (e.g. "5").
+      if (settingsKey === "defaultBitrate") {
+        const match = BITRATES.find(
+          (b) => b.key === value || b.value === value,
+        );
+        if (match) return match;
+      }
+      // maxAutoPlayEpisodeCount: 0 is invalid (breaks autoplay), clamp to -1
+      // -1 key must match the translated dropdown label so the UI shows "Disabled"
+      if (
+        settingsKey === "maxAutoPlayEpisodeCount" &&
+        (value === 0 || value === -1)
+      ) {
+        return { key: t("home.settings.other.disabled"), value: -1 };
+      }
+      return { key: String(value), value };
+    }
+  }
+  return value;
+};
+
 export type HomeSectionLatestResolver = {
   parentId?: string;
   limit?: number;
@@ -130,20 +171,58 @@ export type HomeSectionLatestResolver = {
   includeItemTypes?: Array<BaseItemKind>;
 };
 
+// Video player enum - currently only MPV is supported
 export enum VideoPlayer {
-  // NATIVE, //todo: changes will make this a lot more easier to implement if we want. delete if not wanted
-  VLC_3 = 0,
-  VLC_4 = 1,
+  MPV = 0,
 }
 
+// TV Typography scale presets
+export enum TVTypographyScale {
+  Small = "small",
+  Default = "default",
+  Large = "large",
+  ExtraLarge = "extraLarge",
+}
+
+// Audio transcoding mode - controls how surround audio is handled
+// This controls server-side transcoding behavior for audio streams.
+// MPV decodes via FFmpeg and supports most formats, but mobile devices
+// can't passthrough to external receivers, so this primarily affects
+// bandwidth usage and server load.
+export enum AudioTranscodeMode {
+  Auto = "auto", // Platform defaults (recommended)
+  ForceStereo = "stereo", // Always transcode to stereo
+  Allow51 = "5.1", // Allow up to 5.1, transcode 7.1+
+  AllowAll = "passthrough", // Direct play all audio formats
+}
+
+// Inactivity timeout for TV - auto logout after period of no activity
+export enum InactivityTimeout {
+  Disabled = 0,
+  OneMinute = 60000,
+  FiveMinutes = 300000,
+  FifteenMinutes = 900000,
+  ThirtyMinutes = 1800000,
+  OneHour = 3600000,
+  FourHours = 14400000,
+  TwentyFourHours = 86400000,
+}
+
+// MPV cache mode - controls how caching is enabled
+export type MpvCacheMode = "auto" | "yes" | "no";
+export type MpvVoDriver = "gpu-next" | "gpu";
+
 export type Settings = {
   home?: Home | null;
   deviceProfile?: "Expo" | "Native" | "Old";
   mediaListCollectionIds?: string[];
   preferedLanguage?: string;
-  searchEngine: "Marlin" | "Jellyfin";
+  searchEngine: "Marlin" | "Jellyfin" | "Streamystats";
   marlinServerUrl?: string;
-  openInVLC?: boolean;
+  streamyStatsServerUrl?: string;
+  streamyStatsMovieRecommendations?: boolean;
+  streamyStatsSeriesRecommendations?: boolean;
+  streamyStatsPromotedWatchlists?: boolean;
   downloadQuality?: DownloadOption;
   downloadStorageLocation?: string;
   defaultBitrate?: Bitrate;
@@ -163,24 +242,60 @@ export type Settings = {
   subtitleSize: number;
   safeAreaInControlsEnabled: boolean;
   jellyseerrServerUrl?: string;
+  useKefinTweaks: boolean;
   hiddenLibraries?: string[];
   enableH265ForChromecast: boolean;
-  defaultPlayer: VideoPlayer;
   maxAutoPlayEpisodeCount: MaxAutoPlayEpisodeCount;
   autoPlayEpisodeCount: number;
-  vlcTextColor?: string;
-  vlcBackgroundColor?: string;
-  vlcOutlineColor?: string;
-  vlcOutlineThickness?: string;
-  vlcBackgroundOpacity?: number;
-  vlcOutlineOpacity?: number;
-  vlcIsBold?: boolean;
+  autoPlayNextEpisode: boolean;
+  // Playback speed settings
+  defaultPlaybackSpeed: number;
+  playbackSpeedPerMedia: Record<string, number>;
+  playbackSpeedPerShow: Record<string, number>;
+  // MPV subtitle settings
+  mpvSubtitleScale?: number;
+  mpvSubtitleMarginY?: number;
+  mpvSubtitleAlignX?: "left" | "center" | "right";
+  mpvSubtitleAlignY?: "top" | "center" | "bottom";
+  mpvSubtitleFontSize?: number;
+  mpvSubtitleBackgroundEnabled?: boolean;
+  mpvSubtitleBackgroundOpacity?: number; // 0-100
+  // MPV buffer/cache settings
+  mpvCacheEnabled?: MpvCacheMode;
+  mpvCacheSeconds?: number;
+  mpvDemuxerMaxBytes?: number; // MB
+  mpvDemuxerMaxBackBytes?: number; // MB
+  // MPV video output driver (Android only)
+  mpvVoDriver?: MpvVoDriver;
   // Gesture controls
   enableHorizontalSwipeSkip: boolean;
   enableLeftSideBrightnessSwipe: boolean;
   enableRightSideVolumeSwipe: boolean;
+  hideVolumeSlider: boolean;
+  hideBrightnessSlider: boolean;
   usePopularPlugin: boolean;
-  showLargeHomeCarousel: boolean;
+  mergeNextUpAndContinueWatching: boolean;
+  // TV-specific settings
+  showHomeBackdrop: boolean;
+  showTVHeroCarousel: boolean;
+  tvTypographyScale: TVTypographyScale;
+  showSeriesPosterOnEpisode: boolean;
+  tvThemeMusicEnabled: boolean;
+  // Appearance
+  hideRemoteSessionButton: boolean;
+  hideWatchlistsTab: boolean;
+  // Audio look-ahead caching
+  audioLookaheadEnabled: boolean;
+  audioLookaheadCount: number;
+  audioMaxCacheSizeMB: number;
+  // Music playback
+  preferLocalAudio: boolean;
+  // Audio transcoding mode
+  audioTranscodeMode: AudioTranscodeMode;
+  // OpenSubtitles API key for client-side subtitle fetching
+  openSubtitlesApiKey?: string;
+  // TV-only: Inactivity timeout for auto-logout
+  inactivityTimeout: InactivityTimeout;
 };
 
 export interface Lockable<T> {
@@ -202,7 +317,10 @@ export const defaultValues: Settings = {
   preferedLanguage: undefined,
   searchEngine: "Jellyfin",
   marlinServerUrl: "",
-  openInVLC: false,
+  streamyStatsServerUrl: "",
+  streamyStatsMovieRecommendations: false,
+  streamyStatsSeriesRecommendations: false,
+  streamyStatsPromotedWatchlists: false,
   downloadQuality: DownloadOptions[0],
   downloadStorageLocation: undefined,
   defaultBitrate: BITRATES[0],
@@ -225,27 +343,66 @@ export const defaultValues: Settings = {
   rewindSkipTime: 10,
   showCustomMenuLinks: false,
   disableHapticFeedback: false,
-  subtitleSize: Platform.OS === "ios" ? 60 : 100,
+  subtitleSize: 100, // Scale value * 100, so 100 = 1.0x
   safeAreaInControlsEnabled: true,
   jellyseerrServerUrl: undefined,
+  useKefinTweaks: false,
   hiddenLibraries: [],
   enableH265ForChromecast: false,
-  defaultPlayer: VideoPlayer.VLC_3, // ios-only setting. does not matter what this is for android
   maxAutoPlayEpisodeCount: { key: "3", value: 3 },
   autoPlayEpisodeCount: 0,
-  vlcTextColor: undefined,
-  vlcBackgroundColor: undefined,
-  vlcOutlineColor: undefined,
-  vlcOutlineThickness: undefined,
-  vlcBackgroundOpacity: undefined,
-  vlcOutlineOpacity: undefined,
-  vlcIsBold: undefined,
+  autoPlayNextEpisode: true,
+  // Playback speed defaults
+  defaultPlaybackSpeed: 1.0,
+  playbackSpeedPerMedia: {},
+  playbackSpeedPerShow: {},
+  // MPV subtitle defaults
+  mpvSubtitleScale: undefined,
+  mpvSubtitleMarginY: undefined,
+  mpvSubtitleAlignX: undefined,
+  mpvSubtitleAlignY: undefined,
+  mpvSubtitleFontSize: undefined,
+  mpvSubtitleBackgroundEnabled: false,
+  mpvSubtitleBackgroundOpacity: 75,
+  // MPV buffer/cache defaults.
+  // Android TV gets tighter caps — combined with libmpv 1.0's larger
+  // baseline (fontconfig + libxml2 + libplacebo HDR path + scudo
+  // retention) the larger mobile budget pushes 2 GB Android TV boxes
+  // into swap death during 4K HDR playback. Apple TV has more RAM and
+  // keeps the full budget. Users can override via the settings screen.
+  mpvCacheEnabled: "auto",
+  mpvCacheSeconds: 10,
+  mpvDemuxerMaxBytes: Platform.isTV && Platform.OS === "android" ? 75 : 150, // MB
+  mpvDemuxerMaxBackBytes: Platform.isTV && Platform.OS === "android" ? 30 : 50, // MB
+  // MPV video output driver defaults (Android only)
+  mpvVoDriver: "gpu-next",
   // Gesture controls
   enableHorizontalSwipeSkip: true,
   enableLeftSideBrightnessSwipe: true,
   enableRightSideVolumeSwipe: true,
+  hideVolumeSlider: false,
+  hideBrightnessSlider: false,
   usePopularPlugin: true,
-  showLargeHomeCarousel: false,
+  mergeNextUpAndContinueWatching: false,
+  // TV-specific settings
+  showHomeBackdrop: true,
+  showTVHeroCarousel: true,
+  tvTypographyScale: TVTypographyScale.Default,
+  showSeriesPosterOnEpisode: false,
+  tvThemeMusicEnabled: true,
+  // Appearance
+  hideRemoteSessionButton: false,
+  hideWatchlistsTab: false,
+  // Audio look-ahead caching defaults
+  audioLookaheadEnabled: true,
+  audioLookaheadCount: 1,
+  audioMaxCacheSizeMB: 500,
+  // Music playback
+  preferLocalAudio: true,
+  // Audio transcoding mode
+  audioTranscodeMode: AudioTranscodeMode.Auto,
+  // TV-only: Inactivity timeout (disabled by default)
+  inactivityTimeout: InactivityTimeout.Disabled,
 };
 
 const loadSettings = (): Partial<Settings> => {
@@ -291,6 +448,14 @@ export const pluginSettingsAtom = atom<PluginLockableSettings | undefined>(
   loadPluginSettings(),
 );
 
+const hasMeaningfulSettingValue = (value: unknown) =>
+  value !== undefined && value !== null && value !== "";
+
+const getEffectiveSettingValue = <K extends keyof Settings>(
+  settings: Partial<Settings> | null | undefined,
+  settingsKey: K,
+) => settings?.[settingsKey] ?? defaultValues[settingsKey];
+
 export const useSettings = () => {
   const api = useAtomValue(apiAtom);
   const [_settings, setSettings] = useAtom(settingsAtom);
@@ -315,16 +480,33 @@ export const useSettings = () => {
     if (!api) {
       return;
     }
-    const settings = await api.getStreamyfinPluginConfig().then(
+    const newPluginSettings = await api.getStreamyfinPluginConfig().then(
       ({ data }) => {
         writeInfoLog("Got plugin settings", data?.settings);
         return data?.settings;
       },
       (_err) => undefined,
     );
-    setPluginSettings(settings);
-    return settings;
-  }, [api]);
+    setPluginSettings(newPluginSettings);
+
+    // Locked/unlocked values are handled by the settings memo, which
+    // applies locked values at runtime without overwriting user storage.
+    // We only handle auto-enabling Streamystats here.
+    if (newPluginSettings && _settings) {
+      const streamyStatsUrl = newPluginSettings.streamyStatsServerUrl;
+      if (streamyStatsUrl?.value && _settings.searchEngine !== "Streamystats") {
+        const newSettings = {
+          ...defaultValues,
+          ..._settings,
+          searchEngine: "Streamystats",
+        } as Settings;
+        setSettings(newSettings);
+        saveSettings(newSettings);
+      }
+    }
+
+    return newPluginSettings;
+  }, [api, _settings]);
 
   const updateSettings = (update: Partial<Settings>) => {
     if (!_settings) {
@@ -348,28 +530,27 @@ export const useSettings = () => {
 
   // We do not want to save over users pre-existing settings in case admin ever removes/unlocks a setting.
   // If admin sets locked to false but provides a value,
-  // use user settings first and fallback on admin setting if required.
+  // use persisted settings first, then app defaults, and only fallback on the
+  // plugin value when neither provides a meaningful value.
   const settings: Settings = useMemo(() => {
-    const unlockedPluginDefaults: Partial<Settings> = {};
     const overrideSettings = Object.entries(pluginSettings ?? {}).reduce<
       Partial<Settings>
     >((acc, [key, setting]) => {
       if (setting) {
-        const { value, locked } = setting;
+        let { value } = setting;
+        const { locked } = setting;
         const settingsKey = key as keyof Settings;
 
-        // Make sure we override default settings with plugin settings when they are not locked.
-        if (
-          !locked &&
-          value !== undefined &&
-          _settings?.[settingsKey] !== value
-        ) {
-          (unlockedPluginDefaults as any)[settingsKey] = value;
-        }
+        // Normalize object-typed settings from plugin (plain primitive → { key, value })
+        value = normalizePluginValue(settingsKey, value);
+
+        const effectiveValue = getEffectiveSettingValue(_settings, settingsKey);
 
         (acc as any)[settingsKey] = locked
           ? value
-          : (_settings?.[settingsKey] ?? value);
+          : hasMeaningfulSettingValue(effectiveValue)
+            ? effectiveValue
+            : value;
       }
       return acc;
     }, {});

utils/atoms/tvAccountActionModal.ts

@@ -0,0 +1,14 @@
+import { atom } from "jotai";
+import type {
+  SavedServer,
+  SavedServerAccount,
+} from "@/utils/secureCredentials";
+
+export type TVAccountActionModalState = {
+  server: SavedServer;
+  account: SavedServerAccount;
+  onLogin: () => void;
+  onDelete: () => void;
+} | null;
+
+export const tvAccountActionModalAtom = atom<TVAccountActionModalState>(null);

utils/atoms/tvAccountSelectModal.ts

@@ -0,0 +1,14 @@
+import { atom } from "jotai";
+import type {
+  SavedServer,
+  SavedServerAccount,
+} from "@/utils/secureCredentials";
+
+export type TVAccountSelectModalState = {
+  server: SavedServer;
+  onAccountAction: (account: SavedServerAccount) => void;
+  onAddAccount: () => void;
+  onDeleteServer: () => void;
+} | null;
+
+export const tvAccountSelectModalAtom = atom<TVAccountSelectModalState>(null);

utils/atoms/tvOptionModal.ts

@@ -0,0 +1,27 @@
+import { atom } from "jotai";
+
+export type TVOptionItem<T = any> = {
+  label: string;
+  sublabel?: string;
+  value: T;
+  selected: boolean;
+};
+
+export type TVOptionModalState = {
+  title: string;
+  options: TVOptionItem[];
+  onSelect: (value: any) => void;
+  cardWidth?: number;
+  cardHeight?: number;
+  /**
+   * Run onSelect AFTER the modal route is dismissed. Needed only when onSelect
+   * navigates (the in-player audio switch replacing the player while
+   * transcoding), which the still-active modal route would otherwise swallow.
+   * Default (false) runs onSelect before closing, so state-only callers (detail
+   * page, library filters, settings) don't re-render after focus returns and
+   * lose TV focus.
+   */
+  deferApplyUntilDismissed?: boolean;
+} | null;
+
+export const tvOptionModalAtom = atom<TVOptionModalState>(null);

utils/atoms/tvRequestModal.ts

@@ -0,0 +1,13 @@
+import { atom } from "jotai";
+import type { MediaType } from "@/utils/jellyseerr/server/constants/media";
+import type { MediaRequestBody } from "@/utils/jellyseerr/server/interfaces/api/requestInterfaces";
+
+export type TVRequestModalState = {
+  requestBody: MediaRequestBody;
+  title: string;
+  id: number;
+  mediaType: MediaType;
+  onRequested: () => void;
+} | null;
+
+export const tvRequestModalAtom = atom<TVRequestModalState>(null);

utils/atoms/tvSeasonSelectModal.ts

@@ -0,0 +1,18 @@
+import { atom } from "jotai";
+import type { MediaStatus } from "@/utils/jellyseerr/server/constants/media";
+
+export type TVSeasonSelectModalState = {
+  seasons: Array<{
+    id: number;
+    seasonNumber: number;
+    episodeCount: number;
+    status: MediaStatus;
+  }>;
+  title: string;
+  mediaId: number;
+  tvdbId?: number;
+  hasAdvancedRequestPermission: boolean;
+  onRequested: () => void;
+} | null;
+
+export const tvSeasonSelectModalAtom = atom<TVSeasonSelectModalState>(null);

utils/atoms/tvSeriesSeasonModal.ts

@@ -0,0 +1,14 @@
+import { atom } from "jotai";
+
+export type TVSeriesSeasonModalState = {
+  seasons: Array<{
+    label: string;
+    value: number;
+    selected: boolean;
+  }>;
+  selectedSeasonIndex: number | string;
+  itemId: string;
+  onSeasonSelect: (seasonIndex: number) => void;
+} | null;
+
+export const tvSeriesSeasonModalAtom = atom<TVSeriesSeasonModalState>(null);

utils/atoms/tvSubtitleModal.ts

@@ -0,0 +1,16 @@
+import type { BaseItemDto } from "@jellyfin/sdk/lib/generated-client";
+import { atom } from "jotai";
+import type { Track } from "@/components/video-player/controls/types";
+
+export type TVSubtitleModalState = {
+  item: BaseItemDto;
+  mediaSourceId?: string | null;
+  subtitleTracks: Track[];
+  currentSubtitleIndex: number;
+  onDisableSubtitles?: () => void;
+  onServerSubtitleDownloaded?: () => void;
+  onLocalSubtitleDownloaded?: (path: string) => void;
+  refreshSubtitleTracks?: () => Promise<Track[]>;
+} | null;
+
+export const tvSubtitleModalAtom = atom<TVSubtitleModalState>(null);

utils/atoms/tvUserSwitchModal.ts

@@ -0,0 +1,12 @@
+import { atom } from "jotai";
+import type { SavedServerAccount } from "@/utils/secureCredentials";
+
+export type TVUserSwitchModalState = {
+  serverUrl: string;
+  serverName: string;
+  accounts: SavedServerAccount[];
+  currentUserId: string;
+  onAccountSelect: (account: SavedServerAccount) => void;
+} | null;
+
+export const tvUserSwitchModalAtom = atom<TVUserSwitchModalState>(null);