Merge branch 'develop' into fix/skip-button-rework

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

.eas/build/android-production-apk.yml

@@ -13,7 +13,7 @@ build:
 
     - run:
         name: Prebuild (Android, bun)
-        command: bunx expo prebuild --platform android --no-install
+        command: bun x expo prebuild --platform android --no-install
 
     - eas/configure_android_version
     - eas/inject_android_credentials

.eas/build/android-production-tv.yml

@@ -15,7 +15,7 @@ build:
     # EXPO_TV=1 comes from the profile env, so prebuild targets Android TV.
     - run:
         name: Prebuild (Android TV, bun)
-        command: bunx expo prebuild --platform android --no-install
+        command: bun x expo prebuild --platform android --no-install
 
     - eas/configure_android_version
     - eas/inject_android_credentials

.eas/build/android-production.yml

@@ -18,10 +18,10 @@ build:
         command: bun install --frozen-lockfile
 
     # android/ is gitignored, so generate native code fresh. --no-install
-    # because deps are already installed above; bunx keeps it on bun.
+    # because deps are already installed above; bun x keeps it on bun.
     - run:
         name: Prebuild (Android, bun)
-        command: bunx expo prebuild --platform android --no-install
+        command: bun x expo prebuild --platform android --no-install
 
     # Applies the EAS-resolved remote versionCode/versionName (autoIncrement
     # in eas.json) into the freshly prebuilt android/ project.

.eas/build/ios-production.yml

@@ -26,7 +26,7 @@ build:
     # skips JS + pod install; we install pods explicitly below with bun deps.
     - run:
         name: Prebuild (iOS/tvOS, bun)
-        command: bunx expo prebuild --platform ios --no-install
+        command: bun x expo prebuild --platform ios --no-install
 
     - run:
         name: Install CocoaPods

app.json

@@ -2,7 +2,7 @@
   "expo": {
     "name": "Streamyfin",
     "slug": "streamyfin",
-    "version": "0.54.1",
+    "version": "0.55.0",
     "orientation": "default",
     "icon": "./assets/images/icon.png",
     "scheme": "streamyfin",

app/(auth)/(tabs)/(home)/settings/logs/page.tsx

@@ -127,7 +127,6 @@ export default function Page() {
           values={[order]}
           title={t("library.filters.sort_order")}
           renderItemLabel={(order) => t(`library.filters.${order}`)}
-          disableSearch={true}
         />
         <FilterButton
           id={levelsFilterId}
@@ -137,7 +136,6 @@ export default function Page() {
           values={levels}
           title={t("home.settings.logs.level")}
           renderItemLabel={(level) => level}
-          disableSearch={true}
           multiple={true}
         />
       </View>

app/(auth)/(tabs)/(home,libraries,search,favorites,watchlists)/collections/[collectionId].tsx

@@ -349,9 +349,6 @@ const page: React.FC = () => {
                 values={selectedGenres}
                 title={t("library.filters.genres")}
                 renderItemLabel={(item) => item.toString()}
-                searchFilter={(item, search) =>
-                  item.toLowerCase().includes(search.toLowerCase())
-                }
               />
             ),
           },
@@ -376,7 +373,6 @@ const page: React.FC = () => {
                 values={selectedYears}
                 title={t("library.filters.years")}
                 renderItemLabel={(item) => item.toString()}
-                searchFilter={(item, search) => item.includes(search)}
               />
             ),
           },
@@ -401,9 +397,6 @@ const page: React.FC = () => {
                 values={selectedTags}
                 title={t("library.filters.tags")}
                 renderItemLabel={(item) => item.toString()}
-                searchFilter={(item, search) =>
-                  item.toLowerCase().includes(search.toLowerCase())
-                }
               />
             ),
           },
@@ -421,9 +414,6 @@ const page: React.FC = () => {
                 renderItemLabel={(item) =>
                   sortOptions.find((i) => i.key === item)?.value || ""
                 }
-                searchFilter={(item, search) =>
-                  item.toLowerCase().includes(search.toLowerCase())
-                }
               />
             ),
           },
@@ -441,9 +431,6 @@ const page: React.FC = () => {
                 renderItemLabel={(item) =>
                   sortOrderOptions.find((i) => i.key === item)?.value || ""
                 }
-                searchFilter={(item, search) =>
-                  item.toLowerCase().includes(search.toLowerCase())
-                }
               />
             ),
           },

app/(auth)/(tabs)/(libraries)/[libraryId].tsx

@@ -568,9 +568,6 @@ const Page = () => {
                 values={selectedGenres}
                 title={t("library.filters.genres")}
                 renderItemLabel={(item) => item.toString()}
-                searchFilter={(item, search) =>
-                  item.toLowerCase().includes(search.toLowerCase())
-                }
               />
             ),
           },
@@ -595,7 +592,6 @@ const Page = () => {
                 values={selectedYears}
                 title={t("library.filters.years")}
                 renderItemLabel={(item) => item.toString()}
-                searchFilter={(item, search) => item.includes(search)}
               />
             ),
           },
@@ -620,9 +616,6 @@ const Page = () => {
                 values={selectedTags}
                 title={t("library.filters.tags")}
                 renderItemLabel={(item) => item.toString()}
-                searchFilter={(item, search) =>
-                  item.toLowerCase().includes(search.toLowerCase())
-                }
               />
             ),
           },
@@ -640,9 +633,6 @@ const Page = () => {
                 renderItemLabel={(item) =>
                   sortOptions.find((i) => i.key === item)?.value || ""
                 }
-                searchFilter={(item, search) =>
-                  item.toLowerCase().includes(search.toLowerCase())
-                }
               />
             ),
           },
@@ -660,9 +650,6 @@ const Page = () => {
                 renderItemLabel={(item) =>
                   sortOrderOptions.find((i) => i.key === item)?.value || ""
                 }
-                searchFilter={(item, search) =>
-                  item.toLowerCase().includes(search.toLowerCase())
-                }
               />
             ),
           },
@@ -680,9 +667,6 @@ const Page = () => {
                 renderItemLabel={(item) =>
                   generalFilters.find((i) => i.key === item)?.value || ""
                 }
-                searchFilter={(item, search) =>
-                  item.toLowerCase().includes(search.toLowerCase())
-                }
               />
             ),
           },

app/(auth)/player/direct-player.tsx

@@ -26,6 +26,10 @@ import { Controls } from "@/components/video-player/controls/Controls";
 import { Controls as TVControls } from "@/components/video-player/controls/Controls.tv";
 import { PlayerProvider } from "@/components/video-player/controls/contexts/PlayerContext";
 import { VideoProvider } from "@/components/video-player/controls/contexts/VideoContext";
+import {
+  LOCAL_SUBTITLE_INDEX_START,
+  toServerSubtitleIndex,
+} from "@/components/video-player/controls/types";
 import {
   PlaybackSpeedScope,
   updatePlaybackSpeedSettings,
@@ -50,15 +54,16 @@ import { DownloadedItem } from "@/providers/Downloads/types";
 import { useInactivity } from "@/providers/InactivityProvider";
 import { apiAtom, userAtom } from "@/providers/JellyfinProvider";
 import { OfflineModeProvider } from "@/providers/OfflineModeProvider";
-
 import { getSubtitlesForItem } from "@/utils/atoms/downloadedSubtitles";
 import { useSettings } from "@/utils/atoms/settings";
 import { getDefaultPlaySettings } from "@/utils/jellyfin/getDefaultPlaySettings";
 import { getPrimaryImageUrl } from "@/utils/jellyfin/image/getPrimaryImageUrl";
 import { getStreamUrl } from "@/utils/jellyfin/media/getStreamUrl";
 import {
+  applyMpvSubtitleSelection,
+  getExternalSubtitleUrl,
   getMpvAudioId,
-  getMpvSubtitleId,
+  isImageBasedSubtitle,
 } from "@/utils/jellyfin/subtitleUtils";
 import { writeToLog } from "@/utils/log";
 import { msToTicks, ticksToSeconds } from "@/utils/time";
@@ -657,32 +662,20 @@ export default function DirectPlayerPage() {
     const mediaSource = stream.mediaSource;
     const isTranscoding = Boolean(mediaSource?.TranscodingUrl);
 
-    // Get external subtitle URLs
+    // Get external subtitle URLs — getExternalSubtitleUrl is the shared source
-    // - Online: prepend API base path to server URLs
+    // of truth with identity matching (online: basePath + DeliveryUrl unless
-    // - Offline: use local file paths (stored in DeliveryUrl during download)
+    // IsExternalUrl; offline: local file path stored in DeliveryUrl).
-    let externalSubs: string[] | undefined;
+    const externalSubs = mediaSource?.MediaStreams?.filter(
-    if (!offline && api?.basePath) {
+      (s) => s.Type === "Subtitle" && s.DeliveryMethod === "External",
-      externalSubs = mediaSource?.MediaStreams?.filter(
+    )
-        (s) =>
+      .map((s) =>
-          s.Type === "Subtitle" &&
+        getExternalSubtitleUrl(s, { offline, basePath: api?.basePath }),
-          s.DeliveryMethod === "External" &&
+      )
-          s.DeliveryUrl,
+      .filter((u): u is string => !!u);
-      ).map((s) => `${api.basePath}${s.DeliveryUrl}`);
-    } else if (offline) {
-      externalSubs = mediaSource?.MediaStreams?.filter(
-        (s) =>
-          s.Type === "Subtitle" &&
-          s.DeliveryMethod === "External" &&
-          s.DeliveryUrl,
-      ).map((s) => s.DeliveryUrl!);
-    }
 
-    // Calculate track IDs for initial selection
+    // Audio maps positionally (audio tracks aren't reordered or hidden like
-    const initialSubtitleId = getMpvSubtitleId(
+    // subtitles). The subtitle selection is applied later, once MPV's real track
-      mediaSource,
+    // list is known — see applySubtitleSelection / onTracksReady.
-      subtitleIndex,
-      isTranscoding,
-    );
     const initialAudioId = getMpvAudioId(
       mediaSource,
       audioIndex,
@@ -700,7 +693,6 @@ export default function DirectPlayerPage() {
       url: stream.url,
       startPosition: startPos,
       autoplay: true,
-      initialSubtitleId,
       initialAudioId,
       // Pass cache/buffer settings from user preferences
       cacheConfig: {
@@ -748,7 +740,6 @@ export default function DirectPlayerPage() {
     playbackPositionFromUrl,
     api?.basePath,
     api?.accessToken,
-    subtitleIndex,
     audioIndex,
     offline,
     settings.mpvCacheEnabled,
@@ -938,7 +929,9 @@ export default function DirectPlayerPage() {
         const queryParams = new URLSearchParams({
           itemId: item?.Id ?? "",
           audioIndex: String(index),
-          subtitleIndex: String(currentSubtitleIndex),
+          // A local (client-downloaded) sub only exists in the dying mpv
+          // instance — the server must be asked for "none" (-1) instead.
+          subtitleIndex: String(toServerSubtitleIndex(currentSubtitleIndex)),
           mediaSourceId: stream?.mediaSource?.Id ?? "",
           bitrateValue: bitrateValue?.toString() ?? "",
           playbackPosition: msToTicks(progress.get()).toString(),
@@ -974,30 +967,103 @@ export default function DirectPlayerPage() {
   );
 
   // TV subtitle track change handler
+  /**
+   * Resolve a Jellyfin subtitle index against MPV's *real* track list and apply
+   * it. Identity-based (external by filename, embedded by language/title) so it
+   * stays correct across external/embedded reordering and server-hidden embedded
+   * subs — unlike positional mapping. Reused for initial selection (onTracksReady,
+   * fired again after each external sub-add) and runtime changes.
+   */
+  const applySubtitleSelection = useCallback(
+    async (jellyfinSubtitleIndex: number) => {
+      const subtitleStreams = stream?.mediaSource?.MediaStreams?.filter(
+        (s) => s.Type === "Subtitle",
+      );
+      return applyMpvSubtitleSelection(videoRef.current, {
+        subtitleStreams,
+        jellyfinSubtitleIndex,
+        getExpectedExternalUrl: (s) =>
+          getExternalSubtitleUrl(s, { offline, basePath: api?.basePath }),
+      });
+    },
+    [stream?.mediaSource, offline, api?.basePath],
+  );
+
+  // Re-negotiate the stream with new track params (server re-processes it,
+  // e.g. to burn an image sub in or out). Same-item mirror of VideoContext's
+  // replacePlayer, resuming at the live position.
+  const replaceWithTrackSelection = useCallback(
+    (params: { subtitleIndex?: string; audioIndex?: string }) => {
+      const queryParams = new URLSearchParams({
+        itemId: item?.Id ?? "",
+        audioIndex: params.audioIndex ?? String(currentAudioIndex ?? ""),
+        subtitleIndex:
+          params.subtitleIndex ??
+          String(toServerSubtitleIndex(currentSubtitleIndex)),
+        mediaSourceId: stream?.mediaSource?.Id ?? "",
+        bitrateValue: bitrateValue?.toString() ?? "",
+        playbackPosition: msToTicks(progress.get()).toString(),
+      }).toString();
+      // Destroy the current mpv instance before re-navigating, same rationale as
+      // goToNextItem: Expo Router briefly holds two players during the
+      // transition and two decoders/surfaces OOM-kill low-RAM devices.
+      videoRef.current?.destroy().catch(() => {});
+      router.replace(`player/direct-player?${queryParams}` as any);
+    },
+    [
+      item?.Id,
+      currentAudioIndex,
+      currentSubtitleIndex,
+      stream?.mediaSource?.Id,
+      bitrateValue,
+      router,
+      progress,
+    ],
+  );
+
+  // TV/mobile subtitle track change handler
   const handleSubtitleIndexChange = useCallback(
     async (index: number) => {
-      setCurrentSubtitleIndex(index);
+      // Local (client-downloaded) subs are loaded via addSubtitleFile, not
+      // resolvable against server streams — just track the live index.
+      if (index <= LOCAL_SUBTITLE_INDEX_START) {
+        setCurrentSubtitleIndex(index);
+        return;
+      }
 
-      // Check if we're transcoding
+      const subs = stream?.mediaSource?.MediaStreams?.filter(
+        (s) => s.Type === "Subtitle",
+      );
       const isTranscoding = Boolean(stream?.mediaSource?.TranscodingUrl);
+      const target = subs?.find((s) => s.Index === index);
+      const current = subs?.find((s) => s.Index === currentSubtitleIndex);
+      // Burned-in subs are pixels, not tracks: switching TO one and switching
+      // AWAY from an active one both need a server re-process (same guard as
+      // VideoContext's needsReplace on the mobile menu path).
+      const needsReplace =
+        isTranscoding &&
+        ((target && isImageBasedSubtitle(target)) ||
+          (current && isImageBasedSubtitle(current)));
+      if (needsReplace) {
+        replaceWithTrackSelection({ subtitleIndex: String(index) });
+        return;
+      }
 
-      if (index === -1) {
+      setCurrentSubtitleIndex(index);
-        // Disable subtitles
+      const result = await applySubtitleSelection(index);
-        await videoRef.current?.disableSubtitles?.();
+      // Safety net: a menu-listed sub the player can't select (server-burned
-      } else {
+      // Encode, sidecar never sub-added) needs the server to re-process the
-        // Convert Jellyfin index to MPV track ID
+      // stream with it.
-        const mpvTrackId = getMpvSubtitleId(
+      if (result.kind === "notFound" || result.kind === "burnedIn") {
-          stream?.mediaSource,
+        replaceWithTrackSelection({ subtitleIndex: String(index) });
-          index,
-          isTranscoding,
-        );
-
-        if (mpvTrackId !== undefined && mpvTrackId !== -1) {
-          await videoRef.current?.setSubtitleTrack?.(mpvTrackId);
-        }
       }
     },
-    [stream?.mediaSource],
+    [
+      applySubtitleSelection,
+      replaceWithTrackSelection,
+      stream?.mediaSource,
+      currentSubtitleIndex,
+    ],
   );
 
   // Technical info toggle handler
@@ -1116,6 +1182,10 @@ export default function DirectPlayerPage() {
         previousItem.UserData?.PlaybackPositionTicks?.toString() ?? "",
     }).toString();
 
+    // Free the current mpv instance before navigating, matching goToNextItem —
+    // otherwise two decoders/surfaces overlap during the transition and can
+    // OOM-kill low-RAM devices.
+    videoRef.current?.destroy().catch(() => {});
     router.replace(`player/direct-player?${queryParams}` as any);
   }, [
     previousItem,
@@ -1128,9 +1198,24 @@ export default function DirectPlayerPage() {
   ]);
 
   // TV: Add subtitle file to player (for client-side downloaded subtitles)
-  const addSubtitleFile = useCallback(async (path: string) => {
+  const addSubtitleFile = useCallback(
-    await videoRef.current?.addSubtitleFile?.(path, true);
+    async (path: string) => {
-  }, []);
+      // Set the live index to the new local sub's REAL index BEFORE the add.
+      // Local subs are keyed LOCAL_SUBTITLE_INDEX_START - position, so use the
+      // downloaded path's position (not a blanket sentinel, which would collide
+      // with the first local sub at -100 and mis-record the selection). Any
+      // local index resolves to notFound on the onTracksReady re-apply, so it
+      // still doesn't clobber the freshly selected track; carry-over now keeps
+      // the correct local sub.
+      const locals = itemId ? getSubtitlesForItem(itemId) : [];
+      const pos = locals.findIndex((s) => s.filePath === path);
+      setCurrentSubtitleIndex(
+        LOCAL_SUBTITLE_INDEX_START - (pos >= 0 ? pos : 0),
+      );
+      await videoRef.current?.addSubtitleFile?.(path, true);
+    },
+    [itemId],
+  );
 
   // TV: Refresh subtitle tracks after server-side subtitle download
   // Re-fetches the media source to pick up newly downloaded subtitles
@@ -1362,6 +1447,10 @@ export default function DirectPlayerPage() {
                 }}
                 onTracksReady={() => {
                   setTracksReady(true);
+                  // Fired after embedded tracks enumerate and again after each
+                  // external sub-add; re-resolve so the final fire (full track
+                  // list) selects the right track by identity.
+                  void applySubtitleSelection(currentSubtitleIndex);
                 }}
               />
               {!hasPlaybackStarted && (

app/(auth)/tv-subtitle-modal.tsx

@@ -13,6 +13,7 @@ import {
   ActivityIndicator,
   Animated,
   Easing,
+  InteractionManager,
   Pressable,
   ScrollView,
   StyleSheet,
@@ -646,10 +647,23 @@ export default function TVSubtitleModal() {
 
   const handleTrackSelect = useCallback(
     (option: { setTrack?: () => void }) => {
+      if (modalState?.deferApplyUntilDismissed) {
+        // Player: setTrack can navigate (replacePlayer for a burn-in switch
+        // while transcoding); a router.replace fired while this modal is the
+        // active route targets the MODAL and is swallowed. Close FIRST, apply
+        // after dismissal.
+        handleClose();
+        InteractionManager.runAfterInteractions(() => option.setTrack?.());
+        return;
+      }
+      // Detail page: setTrack only updates state. Run it BEFORE closing so the
+      // re-render happens while the modal is up; deferring it until after
+      // dismissal re-renders the detail page after focus returns and yanks TV
+      // focus, leaving navigation stuck.
       option.setTrack?.();
       handleClose();
     },
-    [handleClose],
+    [handleClose, modalState?.deferApplyUntilDismissed],
   );
 
   const handleDownload = useCallback(

components/BitRateSheet.tsx

@@ -1,122 +0,0 @@
-import { useMemo, useState } from "react";
-import { useTranslation } from "react-i18next";
-import { Platform, TouchableOpacity, View } from "react-native";
-import { Text } from "./common/Text";
-import { FilterSheet } from "./filters/FilterSheet";
-
-export type Bitrate = {
-  key: string;
-  value: number | undefined;
-};
-
-export const BITRATES: Bitrate[] = [
-  {
-    key: "Max",
-    value: undefined,
-  },
-  {
-    key: "8 Mb/s",
-    value: 8000000,
-    height: 1080,
-  },
-  {
-    key: "4 Mb/s",
-    value: 4000000,
-    height: 1080,
-  },
-  {
-    key: "2 Mb/s",
-    value: 2000000,
-  },
-  {
-    key: "1 Mb/s",
-    value: 1000000,
-  },
-  {
-    key: "500 Kb/s",
-    value: 500000,
-  },
-  {
-    key: "250 Kb/s",
-    value: 250000,
-  },
-].sort(
-  (a, b) =>
-    (b.value || Number.POSITIVE_INFINITY) -
-    (a.value || Number.POSITIVE_INFINITY),
-);
-
-interface Props extends React.ComponentProps<typeof View> {
-  onChange: (value: Bitrate) => void;
-  selected?: Bitrate | null;
-  inverted?: boolean | null;
-}
-
-export const BitrateSheet: React.FC<Props> = ({
-  onChange,
-  selected,
-  inverted,
-  ...props
-}) => {
-  const isTv = Platform.isTV;
-  const { t } = useTranslation();
-  const [open, setOpen] = useState(false);
-
-  const sorted = useMemo(() => {
-    if (inverted)
-      return BITRATES.slice().sort(
-        (a, b) =>
-          (a.value || Number.POSITIVE_INFINITY) -
-          (b.value || Number.POSITIVE_INFINITY),
-      );
-    return BITRATES.slice().sort(
-      (a, b) =>
-        (b.value || Number.POSITIVE_INFINITY) -
-        (a.value || Number.POSITIVE_INFINITY),
-    );
-  }, [inverted]);
-
-  if (isTv) return null;
-
-  return (
-    <View
-      className='flex shrink'
-      style={{
-        minWidth: 60,
-        maxWidth: 200,
-      }}
-    >
-      <View className='flex flex-col' {...props}>
-        <Text className='opacity-50 mb-1 text-xs'>
-          {t("item_card.quality")}
-        </Text>
-        <TouchableOpacity
-          className='bg-neutral-900 h-10 rounded-xl border-neutral-800 border px-3 py-2 flex flex-row items-center justify-between'
-          onPress={() => setOpen(true)}
-        >
-          <Text numberOfLines={1}>
-            {BITRATES.find((b) => b.value === selected?.value)?.key}
-          </Text>
-        </TouchableOpacity>
-      </View>
-
-      <FilterSheet
-        open={open}
-        setOpen={setOpen}
-        title={t("item_card.quality")}
-        data={sorted}
-        values={selected ? [selected] : []}
-        multiple={false}
-        searchFilter={(item, query) => {
-          const label = (item as any).key || "";
-          return label.toLowerCase().includes(query.toLowerCase());
-        }}
-        renderItemLabel={(item) => <Text>{(item as any).key || ""}</Text>}
-        set={(vals) => {
-          const chosen = vals[0] as Bitrate | undefined;
-          if (chosen) onChange(chosen);
-        }}
-      />
-    </View>
-  );
-};

components/ItemContent.tv.tsx

@@ -40,7 +40,10 @@ import {
   TVSeriesNavigation,
   TVTechnicalDetails,
 } from "@/components/tv";
-import type { Track } from "@/components/video-player/controls/types";
+import {
+  LOCAL_SUBTITLE_INDEX_START,
+  type Track,
+} from "@/components/video-player/controls/types";
 import { useScaledTVTypography } from "@/constants/TVTypography";
 import useRouter from "@/hooks/useAppRouter";
 import useDefaultPlaySettings from "@/hooks/useDefaultPlaySettings";
@@ -56,6 +59,7 @@ import { useSettings } from "@/utils/atoms/settings";
 import type { TVOptionItem } from "@/utils/atoms/tvOptionModal";
 import { getLogoImageUrlById } from "@/utils/jellyfin/image/getLogoImageUrlById";
 import { getPrimaryImageUrlById } from "@/utils/jellyfin/image/getPrimaryImageUrlById";
+import { compareTracksForMenu } from "@/utils/jellyfin/subtitleUtils";
 import { formatDuration, runtimeTicksToMinutes } from "@/utils/time";
 
 const { width: SCREEN_WIDTH, height: SCREEN_HEIGHT } = Dimensions.get("window");
@@ -232,12 +236,13 @@ export const ItemContentTV: React.FC<ItemContentTVProps> = React.memo(
       return streams ?? [];
     }, [selectedOptions?.mediaSource]);
 
-    // Get available subtitle tracks (raw MediaStream[] for label lookup)
+    // Get available subtitle tracks (raw MediaStream[] for label lookup),
+    // ordered like jellyfin-web (embedded first, externals last, forced/default up).
     const subtitleStreams = useMemo(() => {
       const streams = selectedOptions?.mediaSource?.MediaStreams?.filter(
         (s) => s.Type === "Subtitle",
       );
-      return streams ?? [];
+      return streams ? [...streams].sort(compareTracksForMenu) : [];
     }, [selectedOptions?.mediaSource]);
 
     // Store handleSubtitleChange in a ref for stable callback reference
@@ -248,9 +253,6 @@ export const ItemContentTV: React.FC<ItemContentTVProps> = React.memo(
     // State to trigger refresh of local subtitles list
     const [localSubtitlesRefreshKey, setLocalSubtitlesRefreshKey] = useState(0);
 
-    // Starting index for local (client-downloaded) subtitles
-    const LOCAL_SUBTITLE_INDEX_START = -100;
-
     // Convert MediaStream[] to Track[] for the modal (with setTrack callbacks)
     // Also includes locally downloaded subtitles from OpenSubtitles
     const subtitleTracksForModal = useMemo((): Track[] => {
@@ -411,11 +413,13 @@ export const ItemContentTV: React.FC<ItemContentTVProps> = React.memo(
             )
           : freshItem.MediaSources?.[0];
 
-        // Get subtitle streams from the fresh data
+        // Get subtitle streams from the fresh data, ordered like jellyfin-web
-        const streams =
+        // (embedded first, externals last) — same as the initial list.
-          mediaSource?.MediaStreams?.filter(
+        const streams = [
+          ...(mediaSource?.MediaStreams?.filter(
             (s: MediaStream) => s.Type === "Subtitle",
-          ) ?? [];
+          ) ?? []),
+        ].sort(compareTracksForMenu);
 
         // Convert to Track[] with setTrack callbacks
         const tracks: Track[] = streams.map((stream) => ({

components/MediaSourceButton.tsx

@@ -7,7 +7,8 @@ import { useCallback, useEffect, useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { ActivityIndicator, TouchableOpacity, View } from "react-native";
 import type { ThemeColors } from "@/hooks/useImageColorsReturn";
-import { BITRATES } from "./BitRateSheet";
+import { compareTracksForMenu } from "@/utils/jellyfin/subtitleUtils";
+import { BITRATES } from "./BitrateSelector";
 import type { SelectedOptions } from "./ItemContent";
 import { type OptionGroup, PlatformDropdown } from "./PlatformDropdown";
 
@@ -63,9 +64,12 @@ export const MediaSourceButton: React.FC<Props> = ({
 
   const subtitleStreams = useMemo(
     () =>
-      selectedOptions.mediaSource?.MediaStreams?.filter(
+      // Order like jellyfin-web (embedded first, externals last, forced/default up).
-        (x) => x.Type === "Subtitle",
+      [
-      ) || [],
+        ...(selectedOptions.mediaSource?.MediaStreams?.filter(
+          (x) => x.Type === "Subtitle",
+        ) || []),
+      ].sort(compareTracksForMenu),
     [selectedOptions.mediaSource],
   );
 

components/MediaSourceSheet.tsx

@@ -1,75 +0,0 @@
-import type {
-  BaseItemDto,
-  MediaSourceInfo,
-} from "@jellyfin/sdk/lib/generated-client/models";
-import { useCallback, useMemo, useState } from "react";
-import { useTranslation } from "react-i18next";
-import { Platform, TouchableOpacity, View } from "react-native";
-import { Text } from "./common/Text";
-import { FilterSheet } from "./filters/FilterSheet";
-
-interface Props extends React.ComponentProps<typeof View> {
-  item: BaseItemDto;
-  onChange: (value: MediaSourceInfo) => void;
-  selected?: MediaSourceInfo | null;
-}
-
-export const MediaSourceSheet: React.FC<Props> = ({
-  item,
-  onChange,
-  selected,
-  ...props
-}) => {
-  const isTv = Platform.isTV;
-  const { t } = useTranslation();
-  const [open, setOpen] = useState(false);
-
-  const getDisplayName = useCallback((source: MediaSourceInfo) => {
-    const videoStream = source.MediaStreams?.find((x) => x.Type === "Video");
-    if (source.Name) return source.Name;
-    if (videoStream?.DisplayTitle) return videoStream.DisplayTitle;
-    return `Source ${source.Id}`;
-  }, []);
-
-  const selectedName = useMemo(() => {
-    if (!selected) return "";
-    return getDisplayName(selected);
-  }, [selected, getDisplayName]);
-
-  if (isTv || (item.MediaSources && item.MediaSources.length <= 1)) return null;
-
-  return (
-    <View className='flex shrink' style={{ minWidth: 75 }}>
-      <View className='flex flex-col' {...props}>
-        <Text className='opacity-50 mb-1 text-xs'>{t("item_card.video")}</Text>
-        <TouchableOpacity
-          className='bg-neutral-900 h-10 rounded-xl border-neutral-800 border px-3 py-2 flex flex-row items-center'
-          onPress={() => setOpen(true)}
-        >
-          <Text numberOfLines={1}>{selectedName}</Text>
-        </TouchableOpacity>
-      </View>
-
-      <FilterSheet
-        open={open}
-        setOpen={setOpen}
-        title={t("item_card.video")}
-        data={item.MediaSources || []}
-        values={selected ? [selected] : []}
-        multiple={false}
-        searchFilter={(src, query) =>
-          getDisplayName(src as MediaSourceInfo)
-            .toLowerCase()
-            .includes(query.toLowerCase())
-        }
-        renderItemLabel={(src) => (
-          <Text>{getDisplayName(src as MediaSourceInfo)}</Text>
-        )}
-        set={(vals) => {
-          const chosen = vals[0] as MediaSourceInfo | undefined;
-          if (chosen) onChange(chosen);
-        }}
-      />
-    </View>
-  );
-};

components/SubtitleTrackSelector.tsx

@@ -2,6 +2,7 @@ import type { MediaSourceInfo } from "@jellyfin/sdk/lib/generated-client/models"
 import { useMemo, useState } from "react";
 import { useTranslation } from "react-i18next";
 import { Platform, TouchableOpacity, View } from "react-native";
+import { compareTracksForMenu } from "@/utils/jellyfin/subtitleUtils";
 import { tc } from "@/utils/textTools";
 import { Text } from "./common/Text";
 import { type OptionGroup, PlatformDropdown } from "./PlatformDropdown";
@@ -22,7 +23,9 @@ export const SubtitleTrackSelector: React.FC<Props> = ({
   const [open, setOpen] = useState(false);
 
   const subtitleStreams = useMemo(() => {
-    return source?.MediaStreams?.filter((x) => x.Type === "Subtitle");
+    const subs = source?.MediaStreams?.filter((x) => x.Type === "Subtitle");
+    // Order like jellyfin-web (embedded first, externals last, forced/default up).
+    return subs ? [...subs].sort(compareTracksForMenu) : subs;
   }, [source]);
 
   const selectedSubtitleSteam = useMemo(

components/filters/FilterButton.tsx

@@ -1,20 +1,18 @@
 import { FontAwesome, Ionicons } from "@expo/vector-icons";
 import { useQuery } from "@tanstack/react-query";
-import { useState } from "react";
 import { TouchableOpacity, View, type ViewProps } from "react-native";
 import { Text } from "@/components/common/Text";
-import { FilterSheet } from "./FilterSheet";
+import { useGlobalModal } from "@/providers/GlobalModalProvider";
+import { FilterSheetContent } from "./FilterSheetContent";
 
 interface FilterButtonProps<T> extends ViewProps {
   id: string;
-  disableSearch?: boolean;
   queryKey: string;
   values: T[];
   title: string;
   set: (value: T[]) => void;
   queryFn: (params: any) => Promise<any>;
-  searchFilter?: (item: T, query: string) => boolean;
+  renderItemLabel: (item: T) => string;
-  renderItemLabel: (item: T) => React.ReactNode;
   multiple?: boolean;
   icon?: "filter" | "sort";
 }
@@ -27,13 +25,11 @@ export const FilterButton = <T,>({
   values, // selected values
   title,
   renderItemLabel,
-  searchFilter,
-  disableSearch = false,
   multiple = false,
   icon = "filter",
   ...props
 }: FilterButtonProps<T>) => {
-  const [open, setOpen] = useState(false);
+  const { showModal, hideModal } = useGlobalModal();
 
   const { data: filters } = useQuery<T[]>({
     queryKey: ["filters", title, queryKey, id],
@@ -42,61 +38,59 @@ export const FilterButton = <T,>({
     enabled: !!id && !!queryFn && !!queryKey,
   });
 
-  return (
+  const openSheet = () => {
-    <>
+    if (!filters?.length) return;
-      <TouchableOpacity
+    showModal(
-        onPress={() => {
+      <FilterSheetContent<T>
-          filters?.length && setOpen(true);
-        }}
-      >
-        <View
-          className={`
-            px-3 py-1.5 rounded-full flex flex-row items-center space-x-1
-            ${
-              values.length > 0
-                ? "bg-purple-600  border border-purple-700"
-                : "bg-neutral-900 border border-neutral-900"
-            }
-          ${filters?.length === 0 && "opacity-50"}
-            `}
-          {...props}
-        >
-          <Text
-            className={`
-            ${values.length > 0 ? "text-purple-100" : "text-neutral-100"}
-            text-xs font-semibold`}
-          >
-            {title}
-          </Text>
-          {icon === "filter" ? (
-            <Ionicons
-              name='filter'
-              size={14}
-              color='white'
-              style={{ opacity: 0.5 }}
-            />
-          ) : (
-            <FontAwesome
-              name='sort'
-              size={14}
-              color='white'
-              style={{ opacity: 0.5 }}
-            />
-          )}
-        </View>
-      </TouchableOpacity>
-      <FilterSheet<T>
         title={title}
-        open={open}
-        setOpen={setOpen}
         data={filters}
-        values={values}
+        initialValues={values}
         set={set}
         renderItemLabel={renderItemLabel}
-        searchFilter={searchFilter}
-        disableSearch={disableSearch}
         multiple={multiple}
-      />
+        onClose={hideModal}
-    </>
+      />,
+      { snapPoints: ["85%"] },
+    );
+  };
+
+  return (
+    <TouchableOpacity onPress={openSheet}>
+      <View
+        className={`
+          px-3 py-1.5 rounded-full flex flex-row items-center space-x-1
+          ${
+            values.length > 0
+              ? "bg-purple-600  border border-purple-700"
+              : "bg-neutral-900 border border-neutral-900"
+          }
+          ${filters?.length === 0 ? "opacity-50" : ""}
+        `}
+        {...props}
+      >
+        <Text
+          className={`
+            ${values.length > 0 ? "text-purple-100" : "text-neutral-100"}
+            text-xs font-semibold`}
+        >
+          {title}
+        </Text>
+        {icon === "filter" ? (
+          <Ionicons
+            name='filter'
+            size={14}
+            color='white'
+            style={{ opacity: 0.5 }}
+          />
+        ) : (
+          <FontAwesome
+            name='sort'
+            size={14}
+            color='white'
+            style={{ opacity: 0.5 }}
+          />
+        )}
+      </View>
+    </TouchableOpacity>
   );
 };

components/filters/FilterSheet.tsx

@@ -1,257 +0,0 @@
-import { Ionicons } from "@expo/vector-icons";
-import {
-  BottomSheetBackdrop,
-  type BottomSheetBackdropProps,
-  BottomSheetModal,
-  BottomSheetScrollView,
-} from "@gorhom/bottom-sheet";
-import { isEqual } from "lodash";
-import type React from "react";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
-import { useTranslation } from "react-i18next";
-import {
-  StyleSheet,
-  TouchableOpacity,
-  View,
-  type ViewProps,
-} from "react-native";
-import { useSafeAreaInsets } from "react-native-safe-area-context";
-import { Text } from "@/components/common/Text";
-import { Button } from "../Button";
-import { Input } from "../common/Input";
-
-interface Props<T> extends ViewProps {
-  open: boolean;
-  setOpen: (open: boolean) => void;
-  data?: T[] | null;
-  values: T[];
-  set: (value: T[]) => void;
-  title: string;
-  searchFilter?: (item: T, query: string) => boolean;
-  renderItemLabel: (item: T) => React.ReactNode;
-  disableSearch?: boolean;
-  multiple?: boolean;
-}
-
-const LIMIT = 100;
-
-/**
- * FilterSheet Component
- *
- * This component creates a bottom sheet modal for filtering and selecting items from a list.
- *
- * @template T - The type of items in the list
- *
- * @param {Object} props - The component props
- * @param {boolean} props.open - Whether the bottom sheet is open
- * @param {function} props.setOpen - Function to set the open state
- * @param {T[] | null} [props.data] - The full list of items to filter from
- * @param {T[]} props.values - The currently selected items
- * @param {function} props.set - Function to update the selected items
- * @param {string} props.title - The title of the bottom sheet
- * @param {function} props.searchFilter - Function to filter items based on search query
- * @param {function} props.renderItemLabel - Function to render the label for each item
- * @param {boolean} [props.disableSearch=false] - Whether to disable the search input
- *
- * @returns {React.ReactElement} The FilterSheet component
- *
- * Features:
- * - Displays a list of items in a bottom sheet
- * - Allows searching and filtering of items
- * - Supports single selection of items
- * - Loads items in batches for performance optimization
- * - Customizable item rendering
- */
-
-export const FilterSheet = <T,>({
-  values,
-  data: _data,
-  open,
-  set,
-  setOpen,
-  title,
-  searchFilter,
-  renderItemLabel,
-  disableSearch = false,
-  multiple = false,
-}: Props<T>) => {
-  const bottomSheetModalRef = useRef<BottomSheetModal>(null);
-  const snapPoints = useMemo(() => ["85%"], []);
-  const { t } = useTranslation();
-  const insets = useSafeAreaInsets();
-
-  const [data, setData] = useState<T[]>([]);
-  const [offset, setOffset] = useState<number>(0);
-
-  const [search, setSearch] = useState<string>("");
-
-  const [showSearch, setShowSearch] = useState<boolean>(false);
-
-  const filteredData = useMemo(() => {
-    if (!search) return _data;
-    const results = [];
-    for (let i = 0; i < (_data?.length || 0); i++) {
-      if (_data && searchFilter?.(_data[i], search)) {
-        results.push(_data[i]);
-      }
-    }
-    return results.slice(0, 100);
-  }, [search, _data, searchFilter]);
-
-  useEffect(() => {
-    if (!data || data.length === 0 || disableSearch) return;
-    if (data.length > 15) {
-      setShowSearch(true);
-    }
-  }, [data]);
-
-  // Loads data in batches of LIMIT size, starting from offset,
-  // to implement efficient "load more" functionality
-  useEffect(() => {
-    if (!_data || _data.length === 0) return;
-
-    const newData = [...data];
-
-    for (let i = offset; i < Math.min(_data.length, offset + LIMIT); i++) {
-      const item = _data[i];
-      // Check if this item already exists in our data array
-      // some dups happened with re-renders during testing
-      const exists = newData.some((existingItem) =>
-        isEqual(existingItem, item),
-      );
-      if (!exists) {
-        newData.push(item);
-      }
-    }
-
-    setData(newData);
-  }, [offset, _data]);
-
-  useEffect(() => {
-    if (open) bottomSheetModalRef.current?.present();
-    else bottomSheetModalRef.current?.dismiss();
-  }, [open]);
-
-  const handleSheetChanges = useCallback((index: number) => {
-    if (index === -1) {
-      setOpen(false);
-    }
-  }, []);
-
-  const renderData = useMemo(() => {
-    if (search.length > 0 && showSearch) return filteredData;
-    return data;
-  }, [search, filteredData, data]);
-
-  const renderBackdrop = useCallback(
-    (props: BottomSheetBackdropProps) => (
-      <BottomSheetBackdrop
-        {...props}
-        disappearsOnIndex={-1}
-        appearsOnIndex={0}
-      />
-    ),
-    [],
-  );
-
-  return (
-    <BottomSheetModal
-      ref={bottomSheetModalRef}
-      index={0}
-      snapPoints={snapPoints}
-      onChange={handleSheetChanges}
-      backdropComponent={renderBackdrop}
-      handleIndicatorStyle={{
-        backgroundColor: "white",
-      }}
-      backgroundStyle={{
-        backgroundColor: "#171717",
-      }}
-      style={{}}
-    >
-      <BottomSheetScrollView
-        style={{
-          flex: 1,
-        }}
-      >
-        <View
-          className='mt-2 mb-8'
-          style={{
-            paddingLeft: Math.max(16, insets.left),
-            paddingRight: Math.max(16, insets.right),
-          }}
-        >
-          <Text className='font-bold text-2xl'>{title}</Text>
-          <Text className='mb-2 text-neutral-500'>
-            {t("search.x_items", { count: _data?.length })}
-          </Text>
-          {showSearch && (
-            <Input
-              placeholder={t("search.search")}
-              className='my-2 border-neutral-800 border'
-              value={search}
-              onChangeText={(text) => {
-                setSearch(text);
-              }}
-              returnKeyType='done'
-            />
-          )}
-          <View
-            style={{
-              borderRadius: 20,
-              overflow: "hidden",
-            }}
-            className='mb-4 flex flex-col rounded-xl overflow-hidden'
-          >
-            {renderData?.map((item, index) => (
-              <View key={index}>
-                <TouchableOpacity
-                  onPress={() => {
-                    if (multiple) {
-                      if (!values.includes(item)) set(values.concat(item));
-                      else set(values.filter((v) => v !== item));
-
-                      setTimeout(() => {
-                        setOpen(false);
-                      }, 250);
-                    } else {
-                      if (!values.includes(item)) {
-                        set([item]);
-                        setTimeout(() => {
-                          setOpen(false);
-                        }, 250);
-                      }
-                    }
-                  }}
-                  className=' bg-neutral-800 px-4 py-3 flex flex-row items-center justify-between'
-                >
-                  <Text className='flex shrink'>{renderItemLabel(item)}</Text>
-                  {values.some((i) => isEqual(i, item)) ? (
-                    <Ionicons name='radio-button-on' size={24} color='white' />
-                  ) : (
-                    <Ionicons name='radio-button-off' size={24} color='white' />
-                  )}
-                </TouchableOpacity>
-                <View
-                  style={{
-                    height: StyleSheet.hairlineWidth,
-                  }}
-                  className='h-1 divide-neutral-700 '
-                />
-              </View>
-            ))}
-          </View>
-          {data.length < (_data?.length || 0) && (
-            <Button
-              onPress={() => {
-                setOffset(offset + LIMIT);
-              }}
-            >
-              Load more
-            </Button>
-          )}
-        </View>
-      </BottomSheetScrollView>
-    </BottomSheetModal>
-  );
-};

components/filters/FilterSheetContent.tsx

@@ -0,0 +1,134 @@
+import { Ionicons } from "@expo/vector-icons";
+import { BottomSheetFlatList } from "@gorhom/bottom-sheet";
+import { isEqual } from "lodash";
+import { useMemo, useState } from "react";
+import { useTranslation } from "react-i18next";
+import { StyleSheet, TouchableOpacity, View } from "react-native";
+import { useSafeAreaInsets } from "react-native-safe-area-context";
+import { Input } from "@/components/common/Input";
+import { Text } from "@/components/common/Text";
+
+interface Props<T> {
+  title: string;
+  data: T[];
+  initialValues: T[];
+  set: (value: T[]) => void;
+  renderItemLabel: (item: T) => string;
+  multiple?: boolean;
+  onClose: () => void;
+}
+
+const SEARCH_THRESHOLD = 15;
+
+/**
+ * Sheet content for FilterButton, rendered inside the GlobalModal bottom
+ * sheet. The GlobalModal stores its content as a static snapshot, so this
+ * component owns the selection state locally and mirrors changes back to the
+ * caller through `set`.
+ *
+ * Uses a virtualized BottomSheetFlatList — filter lists (genres, tags, years)
+ * can contain thousands of entries.
+ */
+export const FilterSheetContent = <T,>({
+  title,
+  data,
+  initialValues,
+  set,
+  renderItemLabel,
+  multiple = false,
+  onClose,
+}: Props<T>) => {
+  const { t } = useTranslation();
+  const insets = useSafeAreaInsets();
+
+  const [values, setValues] = useState<T[]>(initialValues);
+  const [search, setSearch] = useState("");
+
+  const showSearch = data.length > SEARCH_THRESHOLD;
+
+  const filteredData = useMemo(() => {
+    if (!search || !showSearch) return data;
+    const query = search.toLowerCase();
+    return data.filter((item) =>
+      renderItemLabel(item).toLowerCase().includes(query),
+    );
+  }, [data, search, showSearch, renderItemLabel]);
+
+  const select = (item: T) => {
+    const selected = values.some((v) => isEqual(v, item));
+    if (multiple) {
+      const next = selected
+        ? values.filter((v) => !isEqual(v, item))
+        : values.concat(item);
+      setValues(next);
+      set(next);
+    } else {
+      if (!selected) {
+        setValues([item]);
+        set([item]);
+      }
+      setTimeout(() => onClose(), 250);
+    }
+  };
+
+  return (
+    <View
+      style={{
+        flex: 1,
+        paddingLeft: Math.max(16, insets.left),
+        paddingRight: Math.max(16, insets.right),
+      }}
+    >
+      <Text className='font-bold text-2xl mt-2'>{title}</Text>
+      <Text className='mb-2 text-neutral-500'>
+        {t("search.x_items", { count: data.length })}
+      </Text>
+      {showSearch && (
+        <Input
+          placeholder={t("search.search")}
+          className='my-2 border-neutral-800 border'
+          value={search}
+          onChangeText={setSearch}
+          returnKeyType='done'
+        />
+      )}
+      <View
+        style={{
+          flex: 1,
+          borderRadius: 20,
+          overflow: "hidden",
+          marginBottom: Math.max(16, insets.bottom),
+        }}
+      >
+        <BottomSheetFlatList
+          data={filteredData}
+          keyExtractor={(item, index) => `${renderItemLabel(item)}-${index}`}
+          keyboardShouldPersistTaps='handled'
+          initialNumToRender={20}
+          ItemSeparatorComponent={() => (
+            <View
+              style={{ height: StyleSheet.hairlineWidth }}
+              className='bg-neutral-700'
+            />
+          )}
+          renderItem={({ item }) => {
+            const selected = values.some((v) => isEqual(v, item));
+            return (
+              <TouchableOpacity
+                onPress={() => select(item)}
+                className='bg-neutral-800 px-4 py-3 flex flex-row items-center justify-between'
+              >
+                <Text className='flex shrink'>{renderItemLabel(item)}</Text>
+                <Ionicons
+                  name={selected ? "radio-button-on" : "radio-button-off"}
+                  size={24}
+                  color='white'
+                />
+              </TouchableOpacity>
+            );
+          }}
+        />
+      </View>
+    </View>
+  );
+};

components/search/DiscoverFilters.tsx

@@ -118,7 +118,6 @@ export const DiscoverFilters: React.FC<DiscoverFiltersProps> = ({
         renderItemLabel={(item) =>
           t(`home.settings.plugins.jellyseerr.order_by.${item}`)
         }
-        disableSearch={true}
       />
       <FilterButton
         id={orderFilterId}
@@ -128,7 +127,6 @@ export const DiscoverFilters: React.FC<DiscoverFiltersProps> = ({
         values={[jellyseerrSortOrder]}
         title={t("library.filters.sort_order")}
         renderItemLabel={(item) => t(`library.filters.${item}`)}
-        disableSearch={true}
       />
     </View>
   );

components/video-player/controls/BottomControls.tsx

@@ -15,7 +15,6 @@ import { useControlsSafeAreaInsets } from "@/hooks/useControlsSafeAreaInsets";
 import { useSettings } from "@/utils/atoms/settings";
 import { chapterMarkers, chapterNameAt } from "@/utils/chapters";
 import NextEpisodeCountDownButton from "./NextEpisodeCountDownButton";
-import SkipButton from "./SkipButton";
 import { TimeDisplay } from "./TimeDisplay";
 import { TrickplayBubble } from "./TrickplayBubble";
 
@@ -34,11 +33,8 @@ interface BottomControlsProps {
   showRemoteBubble: boolean;
   currentTime: number;
   remainingTime: number;
-  showSkipButton: boolean;
   showSkipCreditButton: boolean;
   hasContentAfterCredits: boolean;
-  skipIntro: () => void;
-  skipCredit: () => void;
   nextItem?: BaseItemDto | null;
   handleNextEpisodeAutoPlay: () => void;
   handleNextEpisodeManual: () => void;
@@ -86,11 +82,8 @@ export const BottomControls: FC<BottomControlsProps> = ({
   showRemoteBubble,
   currentTime,
   remainingTime,
-  showSkipButton,
   showSkipCreditButton,
   hasContentAfterCredits,
-  skipIntro,
-  skipCredit,
   nextItem,
   handleNextEpisodeAutoPlay,
   handleNextEpisodeManual,
@@ -180,21 +173,6 @@ export const BottomControls: FC<BottomControlsProps> = ({
           ) : null}
         </View>
         <View className='flex flex-row items-center space-x-2 shrink-0'>
-          <SkipButton
-            showButton={showSkipButton}
-            onPress={skipIntro}
-            buttonText={t("player.skip_intro")}
-          />
-          {/* Smart Skip Credits behavior:
-              - Show "Skip Credits" if there's content after credits OR no next episode
-              - Show "Next Episode" if credits extend to video end AND next episode exists */}
-          <SkipButton
-            showButton={
-              showSkipCreditButton && (hasContentAfterCredits || !nextItem)
-            }
-            onPress={skipCredit}
-            buttonText={t("player.skip_credits")}
-          />
           {settings.autoPlayNextEpisode !== false &&
             (settings.maxAutoPlayEpisodeCount.value === -1 ||
               settings.autoPlayEpisodeCount <

components/video-player/controls/Controls.tsx

@@ -39,6 +39,7 @@ import { useRemoteControl } from "./hooks/useRemoteControl";
 import { useVideoNavigation } from "./hooks/useVideoNavigation";
 import { useVideoSlider } from "./hooks/useVideoSlider";
 import { useVideoTime } from "./hooks/useVideoTime";
+import { SkipSegmentOverlay } from "./SkipSegmentOverlay";
 import { TechnicalInfoOverlay } from "./TechnicalInfoOverlay";
 import { useControlsTimeout } from "./useControlsTimeout";
 import { PlaybackSpeedScope } from "./utils/playback-speed-settings";
@@ -355,6 +356,16 @@ export const Controls: FC<Props> = ({
       maxMs,
     );
 
+  // Whether the "Next Episode" countdown will actually be rendered. The Skip
+  // Credits button yields to it only when this is true; if autoplay is
+  // disabled or its episode limit is reached, Skip Credits must stay available
+  // (mirrors the NextEpisodeCountDownButton mount gate in BottomControls).
+  const willShowNextEpisode =
+    !!nextItem &&
+    settings.autoPlayNextEpisode !== false &&
+    (settings.maxAutoPlayEpisodeCount.value === -1 ||
+      settings.autoPlayEpisodeCount < settings.maxAutoPlayEpisodeCount.value);
+
   const goToItemCommon = useCallback(
     (item: BaseItemDto) => {
       if (!item || !settings) {
@@ -587,11 +598,8 @@ export const Controls: FC<Props> = ({
               showRemoteBubble={showRemoteBubble}
               currentTime={currentTime}
               remainingTime={remainingTime}
-              showSkipButton={showSkipButton}
               showSkipCreditButton={showSkipCreditButton}
               hasContentAfterCredits={hasContentAfterCredits}
-              skipIntro={skipIntro}
-              skipCredit={skipCredit}
               nextItem={nextItem}
               handleNextEpisodeAutoPlay={handleNextEpisodeAutoPlay}
               handleNextEpisodeManual={handleNextEpisodeManual}
@@ -611,6 +619,17 @@ export const Controls: FC<Props> = ({
               time={isSliding || showRemoteBubble ? time : remoteTime}
             />
           </Animated.View>
+          {/* Skip Intro / Skip Credits float independently of the controls so
+              they're visible (and tappable) without summoning the controls. */}
+          <SkipSegmentOverlay
+            showSkipButton={showSkipButton}
+            showSkipCreditButton={showSkipCreditButton}
+            hasContentAfterCredits={hasContentAfterCredits}
+            willShowNextEpisode={willShowNextEpisode}
+            skipIntro={skipIntro}
+            skipCredit={skipCredit}
+            controlsVisible={showControls}
+          />
         </>
       )}
       {settings.maxAutoPlayEpisodeCount.value !== -1 && (

components/video-player/controls/Controls.tv.tsx

@@ -51,6 +51,7 @@ import { useOfflineMode } from "@/providers/OfflineModeProvider";
 import { useSettings } from "@/utils/atoms/settings";
 import type { TVOptionItem } from "@/utils/atoms/tvOptionModal";
 import { getDefaultPlaySettings } from "@/utils/jellyfin/getDefaultPlaySettings";
+import { compareTracksForMenu } from "@/utils/jellyfin/subtitleUtils";
 import { formatTimeString, msToTicks, ticksToMs } from "@/utils/time";
 import { CONTROLS_CONSTANTS } from "./constants";
 import { useVideoContext } from "./contexts/VideoContext";
@@ -317,8 +318,10 @@ export const Controls: FC<Props> = ({
     try {
       const streams = (await onRefreshSubtitleTracks?.()) ?? [];
       // Skip streams without a real index: `?? -1` would alias them to the
-      // "disable subtitles" sentinel and mis-route selection.
+      // "disable subtitles" sentinel and mis-route selection. Order like
-      return streams
+      // jellyfin-web (embedded first, externals last, forced/default up).
+      return [...streams]
+        .sort(compareTracksForMenu)
         .filter((stream) => typeof stream.Index === "number")
         .map((stream) => {
           const index = stream.Index as number;
@@ -601,6 +604,9 @@ export const Controls: FC<Props> = ({
       mediaSourceId: mediaSource?.Id,
       subtitleTracks: tracksWithoutDisable,
       currentSubtitleIndex: subtitleIndex ?? -1,
+      // In-player selection can navigate (replacePlayer for burn-in switches);
+      // apply it after the modal route is dismissed so it isn't swallowed.
+      deferApplyUntilDismissed: true,
       onDisableSubtitles: () => {
         // Find and call the "Disable" track's setTrack from VideoContext
         const disableTrack = videoContextSubtitleTracks?.find(

components/video-player/controls/SkipSegmentOverlay.tsx

@@ -0,0 +1,125 @@
+import type { FC } from "react";
+import { useEffect, useState } from "react";
+import { StyleSheet } from "react-native";
+import Animated, {
+  Easing,
+  useAnimatedStyle,
+  useSharedValue,
+  withTiming,
+} from "react-native-reanimated";
+import { useControlsSafeAreaInsets } from "@/hooks/useControlsSafeAreaInsets";
+import SkipButton from "./SkipButton";
+
+interface Props {
+  showSkipButton: boolean;
+  showSkipCreditButton: boolean;
+  hasContentAfterCredits: boolean;
+  willShowNextEpisode: boolean;
+  skipIntro: () => void;
+  skipCredit: () => void;
+  controlsVisible: boolean;
+}
+
+// Offsets are relative to the safe-area insets so they hold in both portrait
+// and landscape (the insets move with the notch / home indicator).
+//
+// Hidden: low, far-right — nothing else is drawn there, this is the familiar
+//         spot and was working fine.
+// Visible: shifted up (clear of the horizontal progress bar) and left (clear
+//          of the chapters icon), while staying below the vertical volume
+//          slider which sits at the vertical middle of the screen.
+const HIDDEN_BOTTOM = 24;
+const HIDDEN_RIGHT = 12;
+const VISIBLE_BOTTOM = 65;
+const VISIBLE_RIGHT = 42;
+const ANIM_DURATION = 250;
+
+// Keeps `value` true for `duration` ms after it turns false. SkipButton hides
+// itself instantly via a `hidden` (display:none) class, which would preempt
+// the parent's opacity fade-out — lagging the flag keeps the button rendered
+// (and visible) while the fade plays out.
+const useDelayedHide = (value: boolean, duration: number): boolean => {
+  const [display, setDisplay] = useState(value);
+  useEffect(() => {
+    if (value) {
+      setDisplay(true);
+      return;
+    }
+    const t = setTimeout(() => setDisplay(false), duration);
+    return () => clearTimeout(t);
+  }, [value, duration]);
+  return value || display;
+};
+
+/**
+ * Floating Skip Intro / Skip Credits buttons shown independently of the
+ * player controls. They appear on their own during an intro or credits segment
+ * without the user having to summon the controls.
+ */
+export const SkipSegmentOverlay: FC<Props> = ({
+  showSkipButton,
+  showSkipCreditButton,
+  hasContentAfterCredits,
+  willShowNextEpisode,
+  skipIntro,
+  skipCredit,
+  controlsVisible,
+}) => {
+  const insets = useControlsSafeAreaInsets();
+
+  const showCredit =
+    showSkipCreditButton && (hasContentAfterCredits || !willShowNextEpisode);
+  const visible = showSkipButton || showCredit;
+
+  // Drive each SkipButton with a lagged flag so it stays visible while the
+  // opacity fade-out plays, instead of disappearing the instant its segment
+  // ends. `visible` above still drives opacity/pointerEvents immediately.
+  const renderSkip = useDelayedHide(showSkipButton, ANIM_DURATION);
+  const renderCredit = useDelayedHide(showCredit, ANIM_DURATION);
+
+  const opacity = useSharedValue(visible ? 1 : 0);
+
+  useEffect(() => {
+    opacity.value = withTiming(visible ? 1 : 0, {
+      duration: ANIM_DURATION,
+      easing: Easing.out(Easing.quad),
+    });
+  }, [visible, opacity]);
+
+  const animatedStyle = useAnimatedStyle(() => ({
+    opacity: opacity.value,
+  }));
+
+  // Position is recomputed on render (no slide animation) so the button never
+  // sweeps through an overlap zone while the controls toggle.
+  const bottom =
+    insets.bottom + (controlsVisible ? VISIBLE_BOTTOM : HIDDEN_BOTTOM);
+  const right = insets.right + (controlsVisible ? VISIBLE_RIGHT : HIDDEN_RIGHT);
+
+  return (
+    <Animated.View
+      style={[styles.container, { right, bottom }, animatedStyle]}
+      pointerEvents={visible ? "box-none" : "none"}
+    >
+      <SkipButton
+        showButton={renderSkip}
+        onPress={skipIntro}
+        buttonText='Skip Intro'
+      />
+      <SkipButton
+        showButton={renderCredit}
+        onPress={skipCredit}
+        buttonText='Skip Credits'
+      />
+    </Animated.View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    position: "absolute",
+    flexDirection: "row",
+    gap: 8,
+    zIndex: 15,
+  },
+});

components/video-player/controls/contexts/VideoContext.tsx

@@ -23,32 +23,29 @@
  *    - Used to report playback state to Jellyfin server
  *    - Value of -1 means disabled/none
  *
- * 2. MPV INDEX (track.mpvIndex)
+ * 2. PLAYER TRACK (selected by IDENTITY, not position)
- *    - MPV's internal track ID
+ *    - Selection resolves the server Index against MPV's REAL track list via
- *    - MPV orders tracks as: [all embedded, then all external]
+ *      applyMpvSubtitleSelection: externals matched by external-filename,
- *    - IDs: 1..embeddedCount for embedded, embeddedCount+1.. for external
+ *      embedded by language/title. `track.mpvIndex` is no longer used to select
- *    - Value of -1 means track needs replacePlayer() (e.g., burned-in sub)
+ *      (kept -1) — positional mapping mis-selected when externals/embedded were
+ *      reordered or the server hid embedded subs (#954 et al.).
  *
  * ============================================================================
  * SUBTITLE HANDLING
  * ============================================================================
  *
- * Embedded (DeliveryMethod.Embed):
+ * Embedded & External:
- *   - Already in MPV's track list
+ *   - Selected via applyMpvSubtitleSelection (identity match against the live
- *   - Select via setSubtitleTrack(mpvId)
+ *     track list). Menu order matches jellyfin-web (compareTracksForMenu:
- *
+ *     embedded first, externals last, forced/default float up).
- * External (DeliveryMethod.External):
- *   - Loaded into MPV on video start
- *   - Select via setSubtitleTrack(embeddedCount + externalPosition + 1)
  *
  * Image-based during transcoding:
- *   - Burned into video by Jellyfin, not in MPV
+ *   - Burned into video by Jellyfin, not in MPV → replacePlayer() to change.
- *   - Requires replacePlayer() to change
  */
 
-import { SubtitleDeliveryMethod } from "@jellyfin/sdk/lib/generated-client";
 import { File } from "expo-file-system";
 import { useLocalSearchParams } from "expo-router";
+import { useAtomValue } from "jotai";
 import type React from "react";
 import {
   createContext,
@@ -61,16 +58,18 @@ import {
 import { Platform } from "react-native";
 import useRouter from "@/hooks/useAppRouter";
 import type { MpvAudioTrack } from "@/modules";
+import { apiAtom } from "@/providers/JellyfinProvider";
 import { useOfflineMode } from "@/providers/OfflineModeProvider";
 import { getSubtitlesForItem } from "@/utils/atoms/downloadedSubtitles";
-import { isImageBasedSubtitle } from "@/utils/jellyfin/subtitleUtils";
+import {
-import type { Track } from "../types";
+  applyMpvSubtitleSelection,
+  compareTracksForMenu,
+  getExternalSubtitleUrl,
+  isImageBasedSubtitle,
+} from "@/utils/jellyfin/subtitleUtils";
+import { LOCAL_SUBTITLE_INDEX_START, type Track } from "../types";
 import { usePlayerContext, usePlayerControls } from "./PlayerContext";
 
-// Starting index for local (client-downloaded) subtitles
-// Uses negative indices to avoid collision with Jellyfin indices
-const LOCAL_SUBTITLE_INDEX_START = -100;
-
 interface VideoContextProps {
   subtitleTracks: Track[] | null;
   audioTracks: Track[] | null;
@@ -87,6 +86,7 @@ export const VideoProvider: React.FC<{ children: ReactNode }> = ({
   const { tracksReady, mediaSource, downloadedItem } = usePlayerContext();
   const playerControls = usePlayerControls();
   const offline = useOfflineMode();
+  const api = useAtomValue(apiAtom);
   const router = useRouter();
 
   const { itemId, audioIndex, bitrateValue, subtitleIndex, playbackPosition } =
@@ -126,10 +126,17 @@ export const VideoProvider: React.FC<{ children: ReactNode }> = ({
     audioIndex?: string;
     subtitleIndex?: string;
   }) => {
+    // The URL param can hold a local-sub sentinel (selected via setParams) that
+    // only exists in the dying player — the server must get "none" (-1) instead.
+    // NaN (missing/blank param) fails the comparison and passes through as-is.
+    const fallbackSubtitleIndex =
+      Number.parseInt(subtitleIndex, 10) <= LOCAL_SUBTITLE_INDEX_START
+        ? "-1"
+        : subtitleIndex;
     const queryParams = new URLSearchParams({
       itemId: itemId ?? "",
       audioIndex: params.audioIndex ?? audioIndex,
-      subtitleIndex: params.subtitleIndex ?? subtitleIndex,
+      subtitleIndex: params.subtitleIndex ?? fallbackSubtitleIndex,
       mediaSourceId: mediaSource?.Id ?? "",
       bitrateValue: bitrateValue,
       playbackPosition: playbackPosition,
@@ -141,6 +148,19 @@ export const VideoProvider: React.FC<{ children: ReactNode }> = ({
   useEffect(() => {
     if (!tracksReady) return;
 
+    // Guard every state commit against stale runs: api?.basePath /
+    // isCurrentSubImageBased can flip mid-run and restart this effect, and an
+    // earlier async run (which captured an old `api`) must not finish later and
+    // overwrite the fresh track list with callbacks bound to stale closures.
+    // The cleanup flips `cancelled`, so any late commit from a dead run is dropped.
+    let cancelled = false;
+    const commitSubtitleTracks = (next: Track[]) => {
+      if (!cancelled) setSubtitleTracks(next);
+    };
+    const commitAudioTracks = (next: Track[]) => {
+      if (!cancelled) setAudioTracks(next);
+    };
+
     const fetchTracks = async () => {
       // Check if this is offline transcoded content
       // For transcoded offline content, only ONE audio track exists in the file
@@ -166,10 +186,10 @@ export const VideoProvider: React.FC<{ children: ReactNode }> = ({
               },
             },
           ];
-          setAudioTracks(audio);
+          commitAudioTracks(audio);
         } else {
           // Fallback: show no audio tracks if the stored track wasn't found
-          setAudioTracks([]);
+          commitAudioTracks([]);
         }
 
         // For subtitles in transcoded offline content:
@@ -179,6 +199,24 @@ export const VideoProvider: React.FC<{ children: ReactNode }> = ({
           downloadedItem.userData.subtitleStreamIndex;
         const subs: Track[] = [];
 
+        // If an IMAGE subtitle was burned into the transcoded download it's in the
+        // video pixels — it can't be turned off or swapped. Show only that entry
+        // instead of advertising "Disable"/text controls that can't affect it.
+        const burnedInSub = allSubs.find(
+          (s) => s.Index === downloadedSubtitleIndex,
+        );
+        if (burnedInSub && isImageBasedSubtitle(burnedInSub)) {
+          commitSubtitleTracks([
+            {
+              name: `${burnedInSub.DisplayTitle || "Unknown"} (burned in)`,
+              index: burnedInSub.Index ?? -1,
+              mpvIndex: -1,
+              setTrack: () => {},
+            },
+          ]);
+          return;
+        }
+
         // Add "Disable" option
         subs.push({
           name: "Disable",
@@ -190,123 +228,84 @@ export const VideoProvider: React.FC<{ children: ReactNode }> = ({
           },
         });
 
-        // For text-based subs, they should still be available in the file
+        // Text subs are muxed into the transcoded file and switchable; resolve by
-        let subIdx = 1;
+        // identity against MPV's real track list (same as online). Order matches web.
-        for (const sub of allSubs) {
+        // Image subs aren't in the transcoded file (only the burned one was, handled
-          if (sub.IsTextSubtitleStream) {
+        // above), so skip them here.
+        for (const sub of [...allSubs].sort(compareTracksForMenu)) {
+          if (!isImageBasedSubtitle(sub)) {
             subs.push({
               name: sub.DisplayTitle || "Unknown",
               index: sub.Index ?? -1,
-              mpvIndex: subIdx,
+              mpvIndex: -1,
               setTrack: () => {
-                playerControls.setSubtitleTrack(subIdx);
-                router.setParams({ subtitleIndex: String(sub.Index) });
-              },
-            });
-            subIdx++;
-          } else if (sub.Index === downloadedSubtitleIndex) {
-            // This image-based sub was burned in - show it but indicate it's active
-            subs.push({
-              name: `${sub.DisplayTitle || "Unknown"} (burned in)`,
-              index: sub.Index ?? -1,
-              mpvIndex: -1, // Can't be changed
-              setTrack: () => {
-                // Already burned in, just update params
                 router.setParams({ subtitleIndex: String(sub.Index) });
+                void applyMpvSubtitleSelection(playerControls, {
+                  subtitleStreams: allSubs,
+                  jellyfinSubtitleIndex: sub.Index ?? -1,
+                  getExpectedExternalUrl: (s) => {
+                    if (!s.DeliveryUrl) return undefined;
+                    if (offline) return s.DeliveryUrl;
+                    return api?.basePath
+                      ? `${api.basePath}${s.DeliveryUrl}`
+                      : undefined;
+                  },
+                });
               },
             });
           }
         }
 
-        setSubtitleTracks(subs.sort((a, b) => a.index - b.index));
+        commitSubtitleTracks(subs);
         return;
       }
 
       // MPV track handling
       const audioData = await playerControls.getAudioTracks().catch(() => null);
+      if (cancelled) return;
       const playerAudio = (audioData as MpvAudioTrack[]) ?? [];
 
-      // Separate embedded vs external subtitles from Jellyfin's list
-      // MPV orders tracks as: [all embedded, then all external]
-      const embeddedSubs = allSubs.filter(
-        (s) => s.DeliveryMethod === SubtitleDeliveryMethod.Embed,
-      );
-      const externalSubs = allSubs.filter(
-        (s) => s.DeliveryMethod === SubtitleDeliveryMethod.External,
-      );
-
-      // Count embedded subs that will be in MPV
-      // (excludes image-based subs during transcoding as they're burned in)
-      const embeddedInPlayer = embeddedSubs.filter(
-        (s) => !isTranscoding || !isImageBasedSubtitle(s),
-      );
-
       const subs: Track[] = [];
 
-      // Process all Jellyfin subtitles
+      // Process all Jellyfin subtitles. Selection resolves against MPV's real
-      for (const sub of allSubs) {
+      // track list by identity (applyMpvSubtitleSelection) — never positional
-        const isEmbedded = sub.DeliveryMethod === SubtitleDeliveryMethod.Embed;
+      // index math, which mis-selects across external/embedded reordering and
-        const isExternal =
+      // server-hidden embedded subs (#954/#1690/#618/#1467/#976/#1451).
-          sub.DeliveryMethod === SubtitleDeliveryMethod.External;
+      // Order matches jellyfin-web (embedded first, externals last, forced/default up).
-
+      for (const sub of [...allSubs].sort(compareTracksForMenu)) {
-        // For image-based subs during transcoding, need to refresh player
+        // Image-based subs during transcoding are burned into the video by the
-        if (isTranscoding && isImageBasedSubtitle(sub)) {
+        // server; both switching TO one and switching AWAY from a currently
-          subs.push({
+        // active one require a player refresh (re-transcode), not a track change.
-            name: sub.DisplayTitle || "Unknown",
+        const needsReplace =
-            index: sub.Index ?? -1,
+          isTranscoding &&
-            mpvIndex: -1,
+          (isImageBasedSubtitle(sub) || isCurrentSubImageBased);
-            setTrack: () => {
-              replacePlayer({ subtitleIndex: String(sub.Index) });
-            },
-          });
-          continue;
-        }
-
-        // Calculate MPV track ID based on type
-        // MPV IDs: [1..embeddedCount] for embedded, [embeddedCount+1..] for external
-        let mpvId = -1;
-
-        if (isEmbedded) {
-          // Find position among embedded subs that are in player
-          const embeddedPosition = embeddedInPlayer.findIndex(
-            (s) => s.Index === sub.Index,
-          );
-          if (embeddedPosition !== -1) {
-            mpvId = embeddedPosition + 1; // 1-based ID
-          }
-        } else if (isExternal) {
-          // Find position among external subs, offset by embedded count
-          const externalPosition = externalSubs.findIndex(
-            (s) => s.Index === sub.Index,
-          );
-          if (externalPosition !== -1) {
-            mpvId = embeddedInPlayer.length + externalPosition + 1;
-          }
-        }
 
         subs.push({
           name: sub.DisplayTitle || "Unknown",
           index: sub.Index ?? -1,
-          mpvIndex: mpvId,
+          mpvIndex: -1,
           setTrack: () => {
-            // Transcoding + switching to/from image-based sub
+            if (needsReplace) {
-            if (
-              isTranscoding &&
-              (isImageBasedSubtitle(sub) || isCurrentSubImageBased)
-            ) {
               replacePlayer({ subtitleIndex: String(sub.Index) });
               return;
             }
-
+            router.setParams({ subtitleIndex: String(sub.Index) });
-            // Direct switch in player
+            void applyMpvSubtitleSelection(playerControls, {
-            if (mpvId !== -1) {
+              subtitleStreams: allSubs,
-              playerControls.setSubtitleTrack(mpvId);
+              jellyfinSubtitleIndex: sub.Index ?? -1,
-              router.setParams({ subtitleIndex: String(sub.Index) });
+              // Mirror how external subs are loaded into MPV (online: basePath +
-              return;
+              // DeliveryUrl, offline: local DeliveryUrl) so identity matching by
-            }
+              // external-filename lines up.
-
+              getExpectedExternalUrl: (s) =>
-            // Fallback - refresh player
+                getExternalSubtitleUrl(s, { offline, basePath: api?.basePath }),
-            replacePlayer({ subtitleIndex: String(sub.Index) });
+            }).then((result) => {
+              // Safety net: a menu-listed sub the player can't select (server-
+              // burned Encode, sidecar never sub-added) only shows up after the
+              // server re-processes the stream with it.
+              if (result.kind === "notFound" || result.kind === "burnedIn") {
+                replacePlayer({ subtitleIndex: String(sub.Index) });
+              }
+            });
           },
         });
       }
@@ -374,12 +373,29 @@ export const VideoProvider: React.FC<{ children: ReactNode }> = ({
         }
       }
 
-      setSubtitleTracks(subs.sort((a, b) => a.index - b.index));
+      // Already in jellyfin-web order (sorted iteration above); "Disable" stays
-      setAudioTracks(audio);
+      // at the front (unshifted), local downloaded subs at the end.
+      commitSubtitleTracks(subs);
+      commitAudioTracks(audio);
     };
 
     fetchTracks();
-  }, [tracksReady, mediaSource, offline, downloadedItem, itemId]);
+    return () => {
+      cancelled = true;
+    };
+    // api?.basePath: setTrack builds external-sub URLs from it — rebuild once the
+    // API is ready so online externals don't resolve with undefined.
+    // isCurrentSubImageBased: setTrack closes over it for the transcode replacePlayer
+    // decision — rebuild when it flips so we refresh the stream when we should.
+  }, [
+    tracksReady,
+    mediaSource,
+    offline,
+    downloadedItem,
+    itemId,
+    api?.basePath,
+    isCurrentSubImageBased,
+  ]);
 
   return (
     <VideoContext.Provider value={{ subtitleTracks, audioTracks }}>

components/video-player/controls/types.ts

@@ -28,4 +28,20 @@ type Track = {
   localPath?: string;
 };
 
+/**
+ * Synthetic `Track.index` base for client-side downloaded subtitles (loaded via
+ * `addSubtitleFile`, no matching Jellyfin MediaStream). Local sub k gets
+ * `LOCAL_SUBTITLE_INDEX_START - k`, so `index <= LOCAL_SUBTITLE_INDEX_START`
+ * identifies a local track.
+ */
+export const LOCAL_SUBTITLE_INDEX_START = -100;
+
+/**
+ * Map a client-side subtitle index to what the Jellyfin stream API understands.
+ * Local sentinel indexes have no matching MediaStream on the server, which
+ * expects -1 ("no subtitles") when re-negotiating a stream.
+ */
+export const toServerSubtitleIndex = (index: number): number =>
+  index <= LOCAL_SUBTITLE_INDEX_START ? -1 : index;
+
 export type { EmbeddedSubtitle, ExternalSubtitle, Track, TranscodedSubtitle };

hooks/useTVSubtitleModal.ts

@@ -14,6 +14,7 @@ interface ShowSubtitleModalParams {
   onServerSubtitleDownloaded?: () => void;
   onLocalSubtitleDownloaded?: (path: string) => void;
   refreshSubtitleTracks?: () => Promise<Track[]>;
+  deferApplyUntilDismissed?: boolean;
 }
 
 export const useTVSubtitleModal = () => {
@@ -30,6 +31,7 @@ export const useTVSubtitleModal = () => {
         onServerSubtitleDownloaded: params.onServerSubtitleDownloaded,
         onLocalSubtitleDownloaded: params.onLocalSubtitleDownloaded,
         refreshSubtitleTracks: params.refreshSubtitleTracks,
+        deferApplyUntilDismissed: params.deferApplyUntilDismissed,
       });
       router.push("/(auth)/tv-subtitle-modal");
     },

modules/mpv-player/android/src/main/java/expo/modules/mpvplayer/MPVLayerRenderer.kt

@@ -535,6 +535,19 @@ class MPVLayerRenderer(private val context: Context) : MPVLib.EventObserver {
 
             mpv?.getPropertyString("track-list/$i/title")?.let { track["title"] = it }
             mpv?.getPropertyString("track-list/$i/lang")?.let { track["lang"] = it }
+            mpv?.getPropertyString("track-list/$i/codec")?.let { track["codec"] = it }
+
+            // Identity fields used to map a Jellyfin subtitle to the real track
+            // (instead of fragile positional counting). `external` + `external-filename`
+            // uniquely identify a sub-added sidecar. `ff-index` is exposed for
+            // diagnostics / potential future exact-index matching; the current
+            // resolver matches embedded tracks by language/title, not ff-index.
+            val external = mpv?.getPropertyBoolean("track-list/$i/external") ?: false
+            track["external"] = external
+            mpv?.getPropertyString("track-list/$i/external-filename")?.let {
+                track["externalFilename"] = it
+            }
+            mpv?.getPropertyInt("track-list/$i/ff-index")?.let { track["ffIndex"] = it }
 
             val selected = mpv?.getPropertyBoolean("track-list/$i/selected") ?: false
             track["selected"] = selected
@@ -840,6 +853,13 @@ class MPVLayerRenderer(private val context: Context) : MPVLib.EventObserver {
                 initialAudioId?.let { if (it > 0) setAudioTrack(it) }
                 initialSubtitleId?.let { setSubtitleTrack(it) } ?: disableSubtitles()
 
+                // The disable above can race a JS-side identity selection that
+                // landed before FILE_LOADED (JS no longer passes an initial sid).
+                // Re-emit tracksReady so the idempotent JS re-apply always runs
+                // after it — for embedded-only files this is the only
+                // post-FILE_LOADED fire.
+                mainHandler.post { delegate?.onTracksReady() }
+
                 if (!isReadyToSeek) {
                     isReadyToSeek = true
                     mainHandler.post { delegate?.onReadyToSeek() }

modules/mpv-player/ios/MPVLayerRenderer.swift

@@ -508,6 +508,15 @@ final class MPVLayerRenderer {
             } else {
                 disableSubtitles()
             }
+            // The disable above can race a JS-side identity selection that
+            // landed before FILE_LOADED (JS no longer passes an initial sid).
+            // Re-emit tracksReady so the idempotent JS re-apply always runs
+            // after it — for embedded-only files this is the only
+            // post-FILE_LOADED fire.
+            DispatchQueue.main.async { [weak self] in
+                guard let self else { return }
+                self.delegate?.renderer(self, didBecomeTracksReady: true)
+            }
             if !isReadyToSeek {
                 isReadyToSeek = true
                 DispatchQueue.main.async { [weak self] in
@@ -759,7 +768,7 @@ final class MPVLayerRenderer {
                   trackType == "sub" else { continue }
             
             var trackId: Int64 = 0
-            getProperty(handle: handle, name: "track-list/\(i)/id", format: MPV_FORMAT_INT64, value: &trackId)
+            guard getProperty(handle: handle, name: "track-list/\(i)/id", format: MPV_FORMAT_INT64, value: &trackId) >= 0 else { continue }
 
             var track: [String: Any] = ["id": Int(trackId)]
             
@@ -771,11 +780,33 @@ final class MPVLayerRenderer {
                 track["lang"] = lang
             }
 
+            if let codec = getStringProperty(handle: handle, name: "track-list/\(i)/codec") {
+                track["codec"] = codec
+            }
+
+            // Identity fields used to map a Jellyfin subtitle to the real track
+            // (instead of fragile positional counting). `external` + `external-filename`
+            // uniquely identify a sub-added sidecar. `ff-index` is exposed for
+            // diagnostics / potential future exact-index matching; the current
+            // resolver matches embedded tracks by language/title, not ff-index.
+            var external: Int32 = 0
+            getProperty(handle: handle, name: "track-list/\(i)/external", format: MPV_FORMAT_FLAG, value: &external)
+            track["external"] = external != 0
+
+            if let extFilename = getStringProperty(handle: handle, name: "track-list/\(i)/external-filename") {
+                track["externalFilename"] = extFilename
+            }
+
+            var ffIndex: Int64 = 0
+            if getProperty(handle: handle, name: "track-list/\(i)/ff-index", format: MPV_FORMAT_INT64, value: &ffIndex) >= 0 {
+                track["ffIndex"] = Int(ffIndex)
+            }
+
             var selected: Int32 = 0
             getProperty(handle: handle, name: "track-list/\(i)/selected", format: MPV_FORMAT_FLAG, value: &selected)
             track["selected"] = selected != 0
 
-            Logger.shared.log("getSubtitleTracks: found sub track id=\(trackId), title=\(track["title"] ?? "none"), lang=\(track["lang"] ?? "none")", type: "Info")
+            Logger.shared.log("getSubtitleTracks: found sub track id=\(trackId), title=\(track["title"] ?? "none"), lang=\(track["lang"] ?? "none"), external=\(external != 0)", type: "Info")
             tracks.append(track)
         }
         
@@ -872,7 +903,7 @@ final class MPVLayerRenderer {
                   trackType == "audio" else { continue }
             
             var trackId: Int64 = 0
-            getProperty(handle: handle, name: "track-list/\(i)/id", format: MPV_FORMAT_INT64, value: &trackId)
+            guard getProperty(handle: handle, name: "track-list/\(i)/id", format: MPV_FORMAT_INT64, value: &trackId) >= 0 else { continue }
 
             var track: [String: Any] = ["id": Int(trackId)]
             

modules/mpv-player/src/MpvPlayer.types.ts

@@ -141,6 +141,14 @@ export type SubtitleTrack = {
   id: number;
   title?: string;
   lang?: string;
+  /** Subtitle codec (mpv `codec`), e.g. "subrip", "ass", "hdmv_pgs_subtitle". */
+  codec?: string;
+  /** True if loaded from a separate file via `sub-add` (mpv `external`). */
+  external?: boolean;
+  /** For external tracks: the exact URL/path it was loaded from (mpv `external-filename`). */
+  externalFilename?: string;
+  /** FFmpeg stream index (mpv `ff-index`); not guaranteed for non-lavf demuxers. */
+  ffIndex?: number;
   selected?: boolean;
 };
 

utils/atoms/tvSubtitleModal.ts

@@ -11,6 +11,14 @@ export type TVSubtitleModalState = {
   onServerSubtitleDownloaded?: () => void;
   onLocalSubtitleDownloaded?: (path: string) => void;
   refreshSubtitleTracks?: () => Promise<Track[]>;
+  /**
+   * Run the selection callback AFTER the modal route is dismissed. Needed when
+   * `setTrack` navigates (the player's replacePlayer for a burn-in switch),
+   * which would be swallowed by the still-active modal route. Leave false for
+   * callers whose selection only updates state (the item detail page), so the
+   * update runs before dismissal and doesn't yank focus after it returns.
+   */
+  deferApplyUntilDismissed?: boolean;
 } | null;
 
 export const tvSubtitleModalAtom = atom<TVSubtitleModalState>(null);

utils/jellyfin/subtitleUtils.test.ts

@@ -0,0 +1,485 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  MediaStream,
+  SubtitleDeliveryMethod,
+} from "@jellyfin/sdk/lib/generated-client";
+import {
+  applyMpvSubtitleSelection,
+  compareTracksForMenu,
+  getExternalSubtitleUrl,
+  isExternalSubtitle,
+  type PlayerSubtitleTrack,
+  resolveSubtitleTrack,
+} from "@/utils/jellyfin/subtitleUtils";
+
+// String-enum values as typed literals — avoids a runtime SDK import (see subtitleUtils.ts).
+const External = "External" as SubtitleDeliveryMethod;
+const Embed = "Embed" as SubtitleDeliveryMethod;
+const Encode = "Encode" as SubtitleDeliveryMethod;
+const Hls = "Hls" as SubtitleDeliveryMethod;
+
+// --- fixtures --------------------------------------------------------------
+
+const sub = (o: Partial<MediaStream> & { Index: number }): MediaStream =>
+  ({ Type: "Subtitle", ...o }) as MediaStream;
+
+const ext = (Index: number, o: Partial<MediaStream> = {}): MediaStream =>
+  sub({
+    Index,
+    DeliveryMethod: External,
+    IsExternal: true,
+    DeliveryUrl: `/sub/${Index}.srt`,
+    ...o,
+  });
+
+const emb = (Index: number, o: Partial<MediaStream> = {}): MediaStream =>
+  sub({ Index, DeliveryMethod: Embed, ...o });
+
+const track = (o: PlayerSubtitleTrack): PlayerSubtitleTrack => o;
+
+// Mirror direct-player.tsx online URL builder.
+const urlBuilder =
+  (base: string) =>
+  (s: MediaStream): string | undefined =>
+    s.DeliveryUrl ? `${base}${s.DeliveryUrl}` : undefined;
+
+const resolve = (
+  streams: MediaStream[],
+  index: number | undefined,
+  player: PlayerSubtitleTrack[],
+  getExpectedExternalUrl = urlBuilder("http://srv"),
+) =>
+  resolveSubtitleTrack({
+    subtitleStreams: streams,
+    jellyfinSubtitleIndex: index,
+    playerTracks: player,
+    getExpectedExternalUrl,
+  });
+
+// --- tests -----------------------------------------------------------------
+
+describe("isExternalSubtitle", () => {
+  test("true for External delivery or the IsExternal flag, not a bare DeliveryUrl", () => {
+    expect(isExternalSubtitle(ext(0))).toBe(true);
+    expect(isExternalSubtitle(sub({ Index: 1, IsExternal: true }))).toBe(true);
+    expect(isExternalSubtitle(emb(2))).toBe(false);
+    // A DeliveryUrl alone (e.g. an Hls-delivered sub) is NOT a sub-added sidecar.
+    expect(isExternalSubtitle(sub({ Index: 3, DeliveryUrl: "/x.srt" }))).toBe(
+      false,
+    );
+  });
+
+  test("a sidecar re-delivered by the server (Hls/Encode) is NOT external", () => {
+    // IsExternal only wins while no device-specific delivery method is assigned;
+    // once the server picks Hls (inside the stream) or Encode (burned), the
+    // track is not a sub-added sidecar and must not use the external path.
+    expect(
+      isExternalSubtitle(
+        sub({ Index: 0, IsExternal: true, DeliveryMethod: Hls }),
+      ),
+    ).toBe(false);
+    expect(
+      isExternalSubtitle(
+        sub({ Index: 0, IsExternal: true, DeliveryMethod: Encode }),
+      ),
+    ).toBe(false);
+  });
+});
+
+describe("resolveSubtitleTrack — disable / notFound", () => {
+  test("index -1 or undefined disables", () => {
+    expect(resolve([], -1, [])).toEqual({ kind: "disable" });
+    expect(resolve([], undefined, [])).toEqual({ kind: "disable" });
+  });
+
+  test("index not present returns notFound", () => {
+    expect(resolve([emb(0)], 99, [track({ id: 1 })])).toEqual({
+      kind: "notFound",
+    });
+  });
+});
+
+describe("resolveSubtitleTrack — hidden embedded (#954)", () => {
+  // Server hides embedded subs: MediaStreams lists only the 3 externals,
+  // but mpv still demuxes the 3 embedded from the file → externals get ids 4,5,6.
+  const streams = [
+    ext(0, { Language: "por" }),
+    ext(1, { Language: "eng" }),
+    ext(2, { Language: "eng", Title: "SDH" }),
+  ];
+  const player = [
+    track({ id: 1, external: false, language: "eng", title: "CC" }),
+    track({ id: 2, external: false, language: "spa" }),
+    track({ id: 3, external: false, language: "fre" }),
+    track({ id: 4, external: true, externalFilename: "http://srv/sub/0.srt" }),
+    track({ id: 5, external: true, externalFilename: "http://srv/sub/1.srt" }),
+    track({ id: 6, external: true, externalFilename: "http://srv/sub/2.srt" }),
+  ];
+
+  test("each external maps to the right player id by filename (not 1,2,3)", () => {
+    expect(resolve(streams, 0, player)).toEqual({ kind: "select", trackId: 4 });
+    expect(resolve(streams, 1, player)).toEqual({ kind: "select", trackId: 5 });
+    expect(resolve(streams, 2, player)).toEqual({ kind: "select", trackId: 6 });
+  });
+
+  test("falls back to external ordinal when filenames are unavailable", () => {
+    const noNames = player.map((t) =>
+      t.external ? { ...t, externalFilename: undefined } : t,
+    );
+    expect(resolve(streams, 1, noNames)).toEqual({
+      kind: "select",
+      trackId: 5,
+    });
+  });
+});
+
+describe("resolveSubtitleTrack — external/embed reversal (non-hidden)", () => {
+  // Jellyfin lists externals first; mpv lists embedded first then externals.
+  const streams = [
+    ext(0, { Language: "eng" }),
+    emb(1, { Language: "spa" }),
+    emb(2, { Language: "fre" }),
+  ];
+  const player = [
+    track({ id: 1, external: false, language: "spa" }),
+    track({ id: 2, external: false, language: "fre" }),
+    track({ id: 3, external: true, externalFilename: "http://srv/sub/0.srt" }),
+  ];
+
+  test("external resolves by filename, embedded by language", () => {
+    expect(resolve(streams, 0, player)).toEqual({ kind: "select", trackId: 3 });
+    expect(resolve(streams, 1, player)).toEqual({ kind: "select", trackId: 1 });
+    expect(resolve(streams, 2, player)).toEqual({ kind: "select", trackId: 2 });
+  });
+});
+
+describe("resolveSubtitleTrack — external without DeliveryUrl (#1763 CodeRabbit)", () => {
+  // Middle external has no DeliveryUrl → never loaded into the player.
+  const streams = [
+    ext(0, { Language: "eng", DeliveryUrl: "/sub/a.srt" }),
+    sub({ Index: 1, DeliveryMethod: External, IsExternal: true }),
+    ext(2, { Language: "fre", DeliveryUrl: "/sub/c.srt" }),
+  ];
+  const player = [
+    track({ id: 4, external: true, externalFilename: "http://srv/sub/a.srt" }),
+    track({ id: 5, external: true, externalFilename: "http://srv/sub/c.srt" }),
+  ];
+
+  test("loaded externals still map correctly despite the gap", () => {
+    expect(resolve(streams, 0, player)).toEqual({ kind: "select", trackId: 4 });
+    expect(resolve(streams, 2, player)).toEqual({ kind: "select", trackId: 5 });
+  });
+
+  test("selecting the unloaded external returns notFound", () => {
+    expect(resolve(streams, 1, player)).toEqual({ kind: "notFound" });
+  });
+});
+
+describe("resolveSubtitleTrack — embedded matching", () => {
+  test("unique language match wins even when player order differs (not positional)", () => {
+    const streams = [emb(0, { Language: "eng" }), emb(1, { Language: "jpn" })];
+    // Player lists them in the OPPOSITE order — a positional map would mis-pick.
+    const player = [
+      track({ id: 1, external: false, language: "jpn" }),
+      track({ id: 2, external: false, language: "eng" }),
+    ];
+    expect(resolve(streams, 0, player)).toEqual({ kind: "select", trackId: 2 }); // eng
+    expect(resolve(streams, 1, player)).toEqual({ kind: "select", trackId: 1 }); // jpn
+  });
+
+  test("same-language tracks with no distinguishing title fall back to ordinal among matches", () => {
+    const streams = [emb(0, { Language: "eng" }), emb(1, { Language: "eng" })];
+    // Both eng, no title → identity can't disambiguate → ordinal among matches.
+    const player = [
+      track({ id: 5, external: false, language: "eng" }),
+      track({ id: 6, external: false, language: "eng" }),
+    ];
+    expect(resolve(streams, 0, player)).toEqual({ kind: "select", trackId: 5 });
+    expect(resolve(streams, 1, player)).toEqual({ kind: "select", trackId: 6 });
+  });
+
+  test("falls back to embedded ordinal when no language/title info", () => {
+    const streams = [emb(0), emb(1)];
+    const player = [
+      track({ id: 1, external: false }),
+      track({ id: 2, external: false }),
+    ];
+    expect(resolve(streams, 1, player)).toEqual({ kind: "select", trackId: 2 });
+  });
+});
+
+describe("compareTracksForMenu — jellyfin-web order", () => {
+  test("externals sort after embedded despite lower Index", () => {
+    const sorted = [
+      ext(0, { Language: "eng" }),
+      emb(7, { Language: "fra" }),
+    ].sort(compareTracksForMenu);
+    expect(sorted.map((s) => s.Index)).toEqual([7, 0]);
+  });
+
+  test("forced then default float to the top within a group", () => {
+    const sorted = [
+      emb(2, { Language: "eng" }),
+      emb(1, { Language: "eng", IsDefault: true }),
+      emb(0, { Language: "eng", IsForced: true }),
+    ].sort(compareTracksForMenu);
+    expect(sorted.map((s) => s.Index)).toEqual([0, 1, 2]);
+  });
+
+  test("full Okiku order: embedded first, externals last by Index", () => {
+    const streams = [
+      ext(0, { Language: "eng" }),
+      ext(1, { Language: "eng" }),
+      ext(2, { Language: "fra" }),
+      ext(3, { Language: "fra" }),
+      emb(7, { Language: "fra", Title: "French" }),
+    ];
+    expect([...streams].sort(compareTracksForMenu).map((s) => s.Index)).toEqual(
+      [7, 0, 1, 2, 3],
+    );
+  });
+});
+
+describe("resolveSubtitleTrack — same-identity group ordinal (duplicate languages)", () => {
+  // [jpn, eng, eng] with no titles: the eng group starts at embedded position 1,
+  // so the group ordinal (not the global one) must drive the pick.
+  const streams = [
+    emb(0, { Language: "jpn" }),
+    emb(1, { Language: "eng" }),
+    emb(2, { Language: "eng" }),
+  ];
+  const playerTracks = [
+    track({ id: 1, language: "jpn" }),
+    track({ id: 2, language: "eng" }),
+    track({ id: 3, language: "eng" }),
+  ];
+
+  test("first eng selects the first matching player track", () => {
+    expect(resolve(streams, 1, playerTracks)).toEqual({
+      kind: "select",
+      trackId: 2,
+    });
+  });
+
+  test("second eng selects the second matching player track", () => {
+    expect(resolve(streams, 2, playerTracks)).toEqual({
+      kind: "select",
+      trackId: 3,
+    });
+  });
+});
+
+describe("resolveSubtitleTrack — server-burned (Encode) streams", () => {
+  const burned = emb(2, {
+    DeliveryMethod: Encode,
+    IsTextSubtitleStream: false,
+    Codec: "pgssub",
+  });
+
+  test("selecting a burned-in sub returns burnedIn (a stream refresh, not a track)", () => {
+    expect(resolve([burned, emb(3)], 2, [track({ id: 1 })])).toEqual({
+      kind: "burnedIn",
+    });
+  });
+
+  test("burned-in streams do not shift the embedded ordinal", () => {
+    // Player only demuxes the two untagged text subs; the burned PGS is pixels.
+    const streams = [burned, emb(3), emb(4)];
+    const playerTracks = [track({ id: 1 }), track({ id: 2 })];
+    expect(resolve(streams, 3, playerTracks)).toEqual({
+      kind: "select",
+      trackId: 1,
+    });
+    expect(resolve([burned, emb(3)], 3, [track({ id: 1 })])).toEqual({
+      kind: "select",
+      trackId: 1,
+    });
+  });
+});
+
+describe("resolveSubtitleTrack — Hls-delivered sidecar goes through the embedded path", () => {
+  test("resolves by identity against the player's in-stream track", () => {
+    const hlsSidecar = sub({
+      Index: 0,
+      IsExternal: true,
+      DeliveryMethod: Hls,
+      DeliveryUrl: "/videos/x/subs/0.vtt",
+      Language: "fre",
+    });
+    const r = resolve([hlsSidecar, emb(1, { Language: "eng" })], 0, [
+      track({ id: 1, language: "fre" }),
+      track({ id: 2, language: "eng" }),
+    ]);
+    expect(r).toEqual({ kind: "select", trackId: 1 });
+  });
+});
+
+describe("applyMpvSubtitleSelection — short-circuits", () => {
+  test("disable (-1) never reads the player track list", async () => {
+    let enumerated = false;
+    let disabled = false;
+    const r = await applyMpvSubtitleSelection(
+      {
+        getSubtitleTracks: async () => {
+          enumerated = true;
+          return [];
+        },
+        setSubtitleTrack: () => {},
+        disableSubtitles: () => {
+          disabled = true;
+        },
+      },
+      { subtitleStreams: [], jellyfinSubtitleIndex: -1 },
+    );
+    expect(r).toEqual({ kind: "disable" });
+    expect(disabled).toBe(true);
+    expect(enumerated).toBe(false);
+  });
+
+  test("burned-in target returns without touching the player", async () => {
+    let enumerated = false;
+    const r = await applyMpvSubtitleSelection(
+      {
+        getSubtitleTracks: async () => {
+          enumerated = true;
+          return [];
+        },
+        setSubtitleTrack: () => {},
+        disableSubtitles: () => {},
+      },
+      {
+        subtitleStreams: [
+          emb(2, { DeliveryMethod: Encode, IsTextSubtitleStream: false }),
+        ],
+        jellyfinSubtitleIndex: 2,
+      },
+    );
+    expect(r).toEqual({ kind: "burnedIn" });
+    expect(enumerated).toBe(false);
+  });
+});
+
+describe("getExternalSubtitleUrl — server contract (MediaInfoHelper)", () => {
+  test("server-relative DeliveryUrl gets the basePath prefix", () => {
+    expect(
+      getExternalSubtitleUrl(ext(0, { DeliveryUrl: "/sub/0.srt" }), {
+        offline: false,
+        basePath: "http://srv",
+      }),
+    ).toBe("http://srv/sub/0.srt");
+  });
+
+  test("IsExternalUrl means DeliveryUrl is already absolute — no prefix", () => {
+    expect(
+      getExternalSubtitleUrl(
+        ext(0, {
+          DeliveryUrl: "https://cdn.example/sub.srt",
+          IsExternalUrl: true,
+        }),
+        { offline: false, basePath: "http://srv" },
+      ),
+    ).toBe("https://cdn.example/sub.srt");
+  });
+
+  test("offline returns the stored local path as-is", () => {
+    expect(
+      getExternalSubtitleUrl(ext(0, { DeliveryUrl: "file:///subs/0.srt" }), {
+        offline: true,
+        basePath: "http://srv",
+      }),
+    ).toBe("file:///subs/0.srt");
+  });
+
+  test("no DeliveryUrl or no basePath online → undefined", () => {
+    expect(
+      getExternalSubtitleUrl(sub({ Index: 0, IsExternal: true }), {
+        offline: false,
+        basePath: "http://srv",
+      }),
+    ).toBeUndefined();
+    expect(
+      getExternalSubtitleUrl(ext(0), { offline: false, basePath: undefined }),
+    ).toBeUndefined();
+  });
+});
+
+describe("resolveSubtitleTrack — language tag variants (ISO 639-1 / 639-2 B-T / IETF)", () => {
+  test("Jellyfin 639-2/B matches mpv 639-2/T and 639-1 tags", () => {
+    // Server says "ger" (639-2/B); muxers can surface "deu" (/T) or "de" (639-1).
+    const streams = [emb(0, { Language: "ger" }), emb(1, { Language: "fre" })];
+    const playerT = [
+      track({ id: 1, language: "deu" }),
+      track({ id: 2, language: "fra" }),
+    ];
+    expect(resolve(streams, 0, playerT)).toEqual({
+      kind: "select",
+      trackId: 1,
+    });
+    expect(resolve(streams, 1, playerT)).toEqual({
+      kind: "select",
+      trackId: 2,
+    });
+
+    const player1 = [
+      track({ id: 1, language: "de" }),
+      track({ id: 2, language: "fr" }),
+    ];
+    expect(resolve(streams, 0, player1)).toEqual({
+      kind: "select",
+      trackId: 1,
+    });
+  });
+
+  test("IETF tags reduce to their primary subtag", () => {
+    const streams = [emb(0, { Language: "eng" }), emb(1, { Language: "spa" })];
+    const player = [
+      track({ id: 1, language: "en-US" }),
+      track({ id: 2, language: "es-419" }),
+    ];
+    expect(resolve(streams, 0, player)).toEqual({ kind: "select", trackId: 1 });
+    expect(resolve(streams, 1, player)).toEqual({ kind: "select", trackId: 2 });
+  });
+
+  test("different languages still never match ('ger' vs 'gre')", () => {
+    const streams = [emb(0, { Language: "ger" })];
+    const player = [
+      track({ id: 1, language: "gre" }),
+      track({ id: 2, language: "ger" }),
+    ];
+    expect(resolve(streams, 0, player)).toEqual({ kind: "select", trackId: 2 });
+  });
+});
+
+describe("compareTracksForMenu — stable order across play methods (8 Mile live find)", () => {
+  test("transcode re-delivery (SRT→External, PGS→Encode) must not reshuffle the menu", () => {
+    // In-file order: srt(1) srt(2) pgs(3) pgs(4), plus a real sidecar ext(0).
+    const directPlay = [
+      ext(0, { Language: "eng" }),
+      emb(1, { Language: "fre" }),
+      emb(2, { Language: "eng" }),
+      emb(3, { Language: "fre", IsTextSubtitleStream: false }),
+      emb(4, { Language: "eng", IsTextSubtitleStream: false }),
+    ];
+    // Same file while transcoding: server re-delivers embedded text as External
+    // (extracted) and burns image subs (Encode). IsExternal stays a FILE property.
+    const transcoding = [
+      ext(0, { Language: "eng" }),
+      emb(1, { Language: "fre", DeliveryMethod: External, DeliveryUrl: "/x1" }),
+      emb(2, { Language: "eng", DeliveryMethod: External, DeliveryUrl: "/x2" }),
+      emb(3, {
+        Language: "fre",
+        IsTextSubtitleStream: false,
+        DeliveryMethod: Encode,
+      }),
+      emb(4, {
+        Language: "eng",
+        IsTextSubtitleStream: false,
+        DeliveryMethod: Encode,
+      }),
+    ];
+    const order = (streams: MediaStream[]) =>
+      [...streams].sort(compareTracksForMenu).map((s) => s.Index);
+    expect(order(directPlay)).toEqual([1, 2, 3, 4, 0]);
+    expect(order(transcoding)).toEqual(order(directPlay));
+  });
+});

utils/jellyfin/subtitleUtils.ts

@@ -1,120 +1,584 @@
 /**
- * Subtitle utility functions for mapping between Jellyfin and MPV track indices.
+ * Subtitle utilities: resolve a Jellyfin subtitle stream to the right track in
+ * the *player's real track list* by identity — never by positional counting.
  *
- * Jellyfin uses server-side indices (e.g., 3, 4, 5 for subtitles in MediaStreams).
+ * Why: Jellyfin renumbers MediaStreams (externals first); the player enumerates
- * MPV uses its own track IDs starting from 1, only counting tracks loaded into MPV.
+ * embedded-from-container first and externals (`sub-add`) last; and a library that
+ * hides embedded subs drops them from MediaStreams while the player still demuxes
+ * them from the file. Positional Index→id mapping therefore mis-selects (e.g.
+ * picking Spanish shows English). See {@link resolveSubtitleTrack}.
  *
  * Image-based subtitles (PGS, VOBSUB) during transcoding are burned into the video
- * and NOT available in MPV's track list.
+ * and absent from the player's track list.
  */
 
-import {
+import type {
-  type MediaSourceInfo,
+  MediaSourceInfo,
-  type MediaStream,
+  MediaStream,
   SubtitleDeliveryMethod,
 } from "@jellyfin/sdk/lib/generated-client";
 
+// "External" is the value of SubtitleDeliveryMethod.External. Compared as a typed
+// literal so this util needs no *runtime* import of the SDK barrel — which pulls in
+// the axios-dependent `/api` modules and breaks unit tests under `bun test`.
+const EXTERNAL_DELIVERY = "External" as SubtitleDeliveryMethod;
+const ENCODE_DELIVERY = "Encode" as SubtitleDeliveryMethod;
+
 /** Check if subtitle is image-based (PGS, VOBSUB, etc.) */
 export const isImageBasedSubtitle = (sub: MediaStream): boolean =>
   sub.IsTextSubtitleStream === false;
 
 /**
- * Determine if a subtitle will be available in MPV's track list.
+ * Burned into the video by the server (`DeliveryMethod === Encode`, e.g. image
- *
+ * subs while transcoding, or sidecar formats no profile can deliver). Never a
- * A subtitle is in MPV if:
+ * selectable player track — switching to/away requires a stream refresh.
- * - Delivery is Embed/Hls/External AND not an image-based sub during transcode
  */
-export const isSubtitleInMpv = (
+export const isBurnedInSubtitle = (sub: MediaStream): boolean =>
-  sub: MediaStream,
+  sub.DeliveryMethod === ENCODE_DELIVERY;
-  isTranscoding: boolean,
-): boolean => {
-  // During transcoding, image-based subs are burned in, not in MPV
-  if (isTranscoding && isImageBasedSubtitle(sub)) {
-    return false;
-  }
 
-  // Embed/Hls/External methods mean the sub is loaded into MPV
+/**
-  return (
+ * A Jellyfin subtitle stream is "external" when the server delivers it as a
-    sub.DeliveryMethod === SubtitleDeliveryMethod.Embed ||
+ * sub-added sidecar — i.e. `DeliveryMethod === External` (or the `IsExternal`
-    sub.DeliveryMethod === SubtitleDeliveryMethod.Hls ||
+ * flag before a device-specific delivery method is assigned).
-    sub.DeliveryMethod === SubtitleDeliveryMethod.External
+ *
-  );
+ * Deliberately NOT keyed on `DeliveryUrl`: an Hls-delivered sub also carries a
+ * `DeliveryUrl` but lives inside the player's track list (not `sub-add`-ed), so
+ * it must resolve through the embedded path. Keeping this in lockstep with the
+ * load sites (which only `sub-add` `DeliveryMethod === External`) and with the
+ * menu comparator below avoids a sub being sorted as embedded yet resolved as
+ * external (→ `notFound`).
+ */
+export const isExternalSubtitle = (sub: MediaStream): boolean =>
+  sub.DeliveryMethod === EXTERNAL_DELIVERY ||
+  (sub.DeliveryMethod == null && sub.IsExternal === true);
+
+/**
+ * The exact URL/path an external sub is (or would be) loaded into the player
+ * with. Single source of truth for BOTH the load site (`videoSource`
+ * externalSubtitles) and identity matching (`getExpectedExternalUrl`) — the
+ * filename match only works while the two stay byte-identical.
+ *
+ * Server contract (MediaInfoHelper.SetDeviceSpecificSubtitleInfo): DeliveryUrl
+ * is server-relative (`/Videos/...`, may carry `?ApiKey=`) UNLESS
+ * `IsExternalUrl` is set — then it is already an absolute URL and must not be
+ * prefixed. Offline: DeliveryUrl holds the local file path.
+ */
+export const getExternalSubtitleUrl = (
+  sub: MediaStream,
+  opts: { offline: boolean; basePath?: string | null },
+): string | undefined => {
+  if (!sub.DeliveryUrl) return undefined;
+  if (opts.offline || sub.IsExternalUrl) return sub.DeliveryUrl;
+  return opts.basePath ? `${opts.basePath}${sub.DeliveryUrl}` : undefined;
 };
 
 /**
- * Calculate the MPV track ID for a given Jellyfin subtitle index.
+ * Order subtitle MediaStreams for the selection menu exactly like jellyfin-web's
+ * `itemHelper.sortTracks`: in-container tracks first then external, and within
+ * each group forced first, then default, then `Index` ascending. Callers prepend
+ * their own "None/Off" entry separately.
  *
- * MPV track IDs are 1-based, but MPV's track list is NOT in MediaStreams order:
+ * The Jellyfin server inserts external (sidecar) streams at the FRONT of
- *   1. Embedded/HLS subs are enumerated from the container (or HLS playlist)
+ * `MediaStreams` (low indices), so raw Index order shows externals first — this
- *      first, in MediaStreams order.
+ * comparator flips that to match web (externals last). Uses the raw `IsExternal`
- *   2. External subs are appended via `sub-add` AFTER the file loads, in the
+ * flag exactly like web's `sortTracks` (itemHelper.js): it is a property of the
- *      order they are passed to MPV (here, also MediaStreams order — see
+ * FILE, so the menu order stays identical between direct play and transcode —
- *      direct-player.tsx where the externalSubtitles array is built by
+ * delivery-based grouping would reshuffle entries when the server re-delivers
- *      filtering MediaStreams).
+ * extracted text subs as External and burns image subs (Encode). Ordering is
- *
+ * purely cosmetic; selection resolves by `Index` identity regardless.
- * Iterating in pure MediaStreams order produces the wrong MPV ID whenever an
- * External sub is listed before an Embed sub in MediaStreams (common when
- * Jellyfin prepends a converted SRT/VTT ahead of an original PGS/ASS track),
- * causing e.g. English to select Spanish. We therefore count in two phases
- * that mirror MPV's actual ordering.
- *
- * Image-based subs (PGS/VOBSUB) during transcoding are burned into the video
- * and absent from MPV's track list; they are skipped in both phases.
- *
- * @param mediaSource - The media source containing subtitle streams
- * @param jellyfinSubtitleIndex - The Jellyfin server-side subtitle index (-1 = disabled)
- * @param isTranscoding - Whether the stream is being transcoded
- * @returns MPV track ID (1-based), or -1 if disabled, or undefined if not in MPV
  */
-export const getMpvSubtitleId = (
+export const compareTracksForMenu = (a: MediaStream, b: MediaStream): number =>
-  mediaSource: MediaSourceInfo | null | undefined,
+  Number(a.IsExternal ?? false) - Number(b.IsExternal ?? false) ||
-  jellyfinSubtitleIndex: number | undefined,
+  Number(b.IsForced ?? false) - Number(a.IsForced ?? false) ||
-  isTranscoding: boolean,
+  Number(b.IsDefault ?? false) - Number(a.IsDefault ?? false) ||
-): number | undefined => {
+  // Missing Index sorts to the end (not 0, which would float it to the top and
-  // -1 or undefined means disabled
+  // collide with a real Index 0).
+  (a.Index ?? Number.MAX_SAFE_INTEGER) - (b.Index ?? Number.MAX_SAFE_INTEGER);
+
+/**
+ * Identity of a subtitle track as reported by the *player's real track list*
+ * (mpv `track-list`, or a Cast media-track list). Player-agnostic on purpose so
+ * the same resolver can drive the mpv player today and the Chromecast backend later.
+ */
+export type PlayerSubtitleTrack = {
+  /** Player-side id used to actually select the track (mpv `sid`, cast trackId). */
+  id: number;
+  /** True if loaded from a separate file (mpv `external`). */
+  external?: boolean;
+  /** For external tracks: the exact URL/path it was loaded from (mpv `external-filename`). */
+  externalFilename?: string;
+  language?: string;
+  title?: string;
+  codec?: string;
+};
+
+export type SubtitleSelection =
+  | { kind: "select"; trackId: number }
+  | { kind: "disable" }
+  /** Target is server-burned (Encode) — only a stream refresh can show/hide it. */
+  | { kind: "burnedIn" }
+  | { kind: "notFound" };
+
+/** Decode percent-encoding and strip a leading `file://` scheme for tolerant comparison. */
+const normalizeUrl = (url: string): string => {
+  let u = url;
+  try {
+    u = decodeURIComponent(u);
+  } catch {
+    // not decodable — compare raw
+  }
+  return u.replace(/^file:\/\//, "");
+};
+
+const externalFilenameMatches = (
+  trackFilename: string | undefined,
+  expectedUrl: string | undefined,
+): boolean => {
+  if (!trackFilename || !expectedUrl) return false;
+  const a = normalizeUrl(trackFilename);
+  const b = normalizeUrl(expectedUrl);
+  return a === b || a.endsWith(b) || b.endsWith(a);
+};
+
+const eq = (a?: string | null, b?: string | null): boolean =>
+  !!a && !!b && a.toLowerCase() === b.toLowerCase();
+
+/**
+ * ISO 639-1 (2-letter) and ISO 639-2/T tags mapped to their ISO 639-2/B form,
+ * so tags from different muxers/servers compare equal ("de"/"deu"/"ger" → "ger").
+ * Jellyfin normalizes probe results to 639-2/B, but mkv `LanguageIETF` tags
+ * ("en-US") and some muxers' 639-1 or /T tags leak through to mpv's `lang`.
+ */
+const LANG_CANONICAL: Record<string, string> = {
+  // ISO 639-1 → 639-2/B
+  aa: "aar",
+  ab: "abk",
+  ae: "ave",
+  af: "afr",
+  ak: "aka",
+  am: "amh",
+  an: "arg",
+  ar: "ara",
+  as: "asm",
+  av: "ava",
+  ay: "aym",
+  az: "aze",
+  ba: "bak",
+  be: "bel",
+  bg: "bul",
+  bh: "bih",
+  bi: "bis",
+  bm: "bam",
+  bn: "ben",
+  bo: "tib",
+  br: "bre",
+  bs: "bos",
+  ca: "cat",
+  ce: "che",
+  ch: "cha",
+  co: "cos",
+  cr: "cre",
+  cs: "cze",
+  cu: "chu",
+  cv: "chv",
+  cy: "wel",
+  da: "dan",
+  de: "ger",
+  dv: "div",
+  dz: "dzo",
+  ee: "ewe",
+  el: "gre",
+  en: "eng",
+  eo: "epo",
+  es: "spa",
+  et: "est",
+  eu: "baq",
+  fa: "per",
+  ff: "ful",
+  fi: "fin",
+  fj: "fij",
+  fo: "fao",
+  fr: "fre",
+  fy: "fry",
+  ga: "gle",
+  gd: "gla",
+  gl: "glg",
+  gn: "grn",
+  gu: "guj",
+  gv: "glv",
+  ha: "hau",
+  he: "heb",
+  hi: "hin",
+  ho: "hmo",
+  hr: "hrv",
+  ht: "hat",
+  hu: "hun",
+  hy: "arm",
+  hz: "her",
+  ia: "ina",
+  id: "ind",
+  ie: "ile",
+  ig: "ibo",
+  ii: "iii",
+  ik: "ipk",
+  io: "ido",
+  is: "ice",
+  it: "ita",
+  iu: "iku",
+  ja: "jpn",
+  jv: "jav",
+  ka: "geo",
+  kg: "kon",
+  ki: "kik",
+  kj: "kua",
+  kk: "kaz",
+  kl: "kal",
+  km: "khm",
+  kn: "kan",
+  ko: "kor",
+  kr: "kau",
+  ks: "kas",
+  ku: "kur",
+  kv: "kom",
+  kw: "cor",
+  ky: "kir",
+  la: "lat",
+  lb: "ltz",
+  lg: "lug",
+  li: "lim",
+  ln: "lin",
+  lo: "lao",
+  lt: "lit",
+  lu: "lub",
+  lv: "lav",
+  mg: "mlg",
+  mh: "mah",
+  mi: "mao",
+  mk: "mac",
+  ml: "mal",
+  mn: "mon",
+  mr: "mar",
+  ms: "may",
+  mt: "mlt",
+  my: "bur",
+  na: "nau",
+  nb: "nob",
+  nd: "nde",
+  ne: "nep",
+  ng: "ndo",
+  nl: "dut",
+  nn: "nno",
+  no: "nor",
+  nr: "nbl",
+  nv: "nav",
+  ny: "nya",
+  oc: "oci",
+  oj: "oji",
+  om: "orm",
+  or: "ori",
+  os: "oss",
+  pa: "pan",
+  pi: "pli",
+  pl: "pol",
+  ps: "pus",
+  pt: "por",
+  qu: "que",
+  rm: "roh",
+  rn: "run",
+  ro: "rum",
+  ru: "rus",
+  rw: "kin",
+  sa: "san",
+  sc: "srd",
+  sd: "snd",
+  se: "sme",
+  sg: "sag",
+  si: "sin",
+  sk: "slo",
+  sl: "slv",
+  sm: "smo",
+  sn: "sna",
+  so: "som",
+  sq: "alb",
+  sr: "srp",
+  ss: "ssw",
+  st: "sot",
+  su: "sun",
+  sv: "swe",
+  sw: "swa",
+  ta: "tam",
+  te: "tel",
+  tg: "tgk",
+  th: "tha",
+  ti: "tir",
+  tk: "tuk",
+  tl: "tgl",
+  tn: "tsn",
+  to: "ton",
+  tr: "tur",
+  ts: "tso",
+  tt: "tat",
+  tw: "twi",
+  ty: "tah",
+  ug: "uig",
+  uk: "ukr",
+  ur: "urd",
+  uz: "uzb",
+  ve: "ven",
+  vi: "vie",
+  vo: "vol",
+  wa: "wln",
+  wo: "wol",
+  xh: "xho",
+  yi: "yid",
+  yo: "yor",
+  za: "zha",
+  zh: "chi",
+  zu: "zul",
+  // ISO 639-2/T → /B (the 20 languages with two distinct 3-letter codes)
+  bod: "tib",
+  ces: "cze",
+  cym: "wel",
+  deu: "ger",
+  ell: "gre",
+  eus: "baq",
+  fas: "per",
+  fra: "fre",
+  hye: "arm",
+  isl: "ice",
+  kat: "geo",
+  mkd: "mac",
+  mri: "mao",
+  msa: "may",
+  mya: "bur",
+  nld: "dut",
+  ron: "rum",
+  slk: "slo",
+  sqi: "alb",
+  zho: "chi",
+};
+
+/** Canonicalize a language tag: lowercase, primary subtag ("en-US" → "en"), 639-2/B. */
+const canonicalLang = (raw: string): string => {
+  const primary = raw.trim().toLowerCase().split("-")[0];
+  return LANG_CANONICAL[primary] ?? primary;
+};
+
+/** Language-tag comparison across ISO 639-1 / 639-2 B/T / IETF variants. */
+const langEq = (a?: string | null, b?: string | null): boolean =>
+  !!a && !!b && canonicalLang(a) === canonicalLang(b);
+
+/** Match an embedded player track to a Jellyfin stream by language/title (codec-agnostic). */
+const embeddedIdentityMatches = (
+  track: PlayerSubtitleTrack,
+  stream: MediaStream,
+): boolean => {
+  if (langEq(track.language, stream.Language)) {
+    // When both carry a title it must agree; otherwise language alone is enough.
+    if (track.title && stream.Title) return eq(track.title, stream.Title);
+    return true;
+  }
+  // No language on one side — fall back to a title match.
+  if (!track.language || !stream.Language) return eq(track.title, stream.Title);
+  return false;
+};
+
+/**
+ * Resolve the player track id for a given Jellyfin subtitle index by matching
+ * against the player's REAL track list (identity), never by positional counting.
+ *
+ * Why identity, not position: Jellyfin renumbers `MediaStreams` (externals first)
+ * while the player enumerates embedded-from-container first and externals
+ * (`sub-add`) last; and when a library hides embedded subs they vanish from
+ * `MediaStreams` but still physically exist in the file the player demuxes.
+ * Positional Index→id mapping therefore mis-selects (e.g. picking Spanish shows
+ * English — issues #954/#1690/#618/#1467/#976/#1451).
+ *
+ * Strategy:
+ *  - disabled (-1/undefined) → `disable`
+ *  - external Jellyfin sub → match the player track by `externalFilename`
+ *    (exact identity, immune to hidden-embedded shifts); fall back to the
+ *    ordinal among *loadable* externals (Swiftfin: externals are the list tail).
+ *  - embedded Jellyfin sub → match by language/title among non-external tracks;
+ *    fall back to the embedded ordinal (container order aligns on both sides).
+ *
+ * Player-agnostic: pass any player's track list + a URL builder, so the mpv
+ * player and (later) the Chromecast backend share one source of truth.
+ */
+export const resolveSubtitleTrack = (params: {
+  subtitleStreams: MediaStream[] | undefined;
+  jellyfinSubtitleIndex: number | undefined;
+  playerTracks: PlayerSubtitleTrack[];
+  /** Build the exact URL/path an external Jellyfin sub was loaded into the player with. */
+  getExpectedExternalUrl?: (sub: MediaStream) => string | undefined;
+}): SubtitleSelection => {
+  const { jellyfinSubtitleIndex, playerTracks, getExpectedExternalUrl } =
+    params;
+  const subtitleStreams = params.subtitleStreams ?? [];
+
   if (jellyfinSubtitleIndex === undefined || jellyfinSubtitleIndex === -1) {
-    return -1;
+    return { kind: "disable" };
   }
 
-  const allSubs =
+  const target = subtitleStreams.find((s) => s.Index === jellyfinSubtitleIndex);
-    mediaSource?.MediaStreams?.filter((s) => s.Type === "Subtitle") || [];
+  if (!target) return { kind: "notFound" };
 
-  // Find the subtitle with the matching Jellyfin index
+  // Server-burned subs are pixels, not tracks — signal the caller to refresh
-  const targetSub = allSubs.find((s) => s.Index === jellyfinSubtitleIndex);
+  // the stream instead of hunting for a track that cannot exist.
+  if (isBurnedInSubtitle(target)) return { kind: "burnedIn" };
 
-  // If the target subtitle isn't in MPV (e.g., image-based during transcode), return undefined
+  if (isExternalSubtitle(target)) {
-  if (!targetSub || !isSubtitleInMpv(targetSub, isTranscoding)) {
+    const playerExternals = playerTracks.filter((t) => t.external === true);
-    return undefined;
+
+    // 1) Exact identity by external filename — robust against hidden-embedded offset.
+    const expectedUrl = getExpectedExternalUrl?.(target);
+    const byName = playerExternals.find((t) =>
+      externalFilenameMatches(t.externalFilename, expectedUrl),
+    );
+    if (byName) return { kind: "select", trackId: byName.id };
+
+    // 2) Fallback: externals are appended in MediaStreams order → ordinal among
+    //    *loadable* externals (those actually added to the player) stays in lockstep
+    //    with the player's external list, skipping ones with no DeliveryUrl (#1763).
+    const externalStreams = subtitleStreams.filter(isExternalSubtitle);
+    const loadableExternals = getExpectedExternalUrl
+      ? externalStreams.filter((s) => getExpectedExternalUrl(s))
+      : externalStreams;
+    const ordinal = loadableExternals.findIndex(
+      (s) => s.Index === jellyfinSubtitleIndex,
+    );
+    if (ordinal >= 0 && ordinal < playerExternals.length) {
+      return { kind: "select", trackId: playerExternals[ordinal].id };
+    }
+    return { kind: "notFound" };
   }
 
-  const isExternal = (sub: MediaStream) =>
+  // Embedded / in-container subtitle. Burned-in (Encode) streams are excluded:
-    sub.DeliveryMethod === SubtitleDeliveryMethod.External;
+  // they are baked into the video and never appear in the player's track list,
+  // so counting them would shift every ordinal below.
+  const embeddedStreams = subtitleStreams.filter(
+    (s) => !isExternalSubtitle(s) && !isBurnedInSubtitle(s),
+  );
+  const playerEmbedded = playerTracks.filter((t) => t.external !== true);
 
-  let mpvIndex = 0;
+  // 1) Identity by language/title (unique match wins).
+  const identityMatches = playerEmbedded.filter((t) =>
+    embeddedIdentityMatches(t, target),
+  );
+  if (identityMatches.length === 1) {
+    return { kind: "select", trackId: identityMatches[0].id };
+  }
 
-  // Phase 1: embedded / HLS subs — these occupy MPV track IDs first because
+  // 2) Multiple same-identity tracks: ordinal within the same-identity GROUP —
-  // they come from the container or HLS playlist.
+  //    the k-th matching stream corresponds to the k-th matching player track
-  for (const sub of allSubs) {
+  //    (container order is preserved on both sides, filter preserves order).
-    if (isExternal(sub)) continue;
+  //    The group ordinal, not the global one: with [jpn, eng, eng] the first
-    if (!isSubtitleInMpv(sub, isTranscoding)) continue;
+  //    eng is global position 1 but group position 0.
-    mpvIndex++;
+  if (identityMatches.length > 1) {
-    if (sub.Index === jellyfinSubtitleIndex) {
+    const groupStreams = embeddedStreams.filter((s) =>
-      return mpvIndex;
+      identityMatches.some((t) => embeddedIdentityMatches(t, s)),
+    );
+    const groupOrdinal = groupStreams.findIndex(
+      (s) => s.Index === jellyfinSubtitleIndex,
+    );
+    if (groupOrdinal >= 0) {
+      const idx = Math.min(groupOrdinal, identityMatches.length - 1);
+      return { kind: "select", trackId: identityMatches[idx].id };
     }
   }
 
-  // Phase 2: external subs — appended via `sub-add` after the file loads,
+  // 3) Fallback: embedded order is container order on both sides → ordinal.
-  // so they come last in MPV's track list.
+  const ordinal = embeddedStreams.findIndex(
-  for (const sub of allSubs) {
+    (s) => s.Index === jellyfinSubtitleIndex,
-    if (!isExternal(sub)) continue;
+  );
-    if (!isSubtitleInMpv(sub, isTranscoding)) continue;
+  if (ordinal >= 0 && ordinal < playerEmbedded.length) {
-    mpvIndex++;
+    return { kind: "select", trackId: playerEmbedded[ordinal].id };
-    if (sub.Index === jellyfinSubtitleIndex) {
-      return mpvIndex;
-    }
   }
+  return { kind: "notFound" };
+};
 
-  return undefined;
+/**
+ * A subtitle track as reported by a concrete player's track-list API
+ * (mpv `getSubtitleTracks`, or a Cast track list). `lang` mirrors mpv's field name.
+ */
+export type PlayerSubtitleTrackRaw = {
+  id: number;
+  lang?: string;
+  title?: string;
+  codec?: string;
+  external?: boolean;
+  externalFilename?: string;
+};
+
+/**
+ * Minimal player surface needed to select a subtitle. Satisfied structurally by
+ * the mpv player ref and (later) implementable by the Chromecast backend.
+ */
+export interface SubtitleSelectablePlayer {
+  getSubtitleTracks: () => Promise<PlayerSubtitleTrackRaw[] | null | undefined>;
+  setSubtitleTrack: (trackId: number) => unknown;
+  disableSubtitles: () => unknown;
+}
+
+/**
+ * Read the player's real track list, resolve the Jellyfin subtitle index by
+ * identity ({@link resolveSubtitleTrack}) and apply the result. Single entry point
+ * for both the mobile controls and the player screen, so selection stays
+ * consistent everywhere. Returns the resolution for callers that want to react.
+ */
+export const applyMpvSubtitleSelection = async (
+  player: SubtitleSelectablePlayer | null | undefined,
+  params: {
+    subtitleStreams: MediaStream[] | undefined;
+    jellyfinSubtitleIndex: number;
+    /** Build the exact URL/path an external sub was loaded into the player with. */
+    getExpectedExternalUrl?: (sub: MediaStream) => string | undefined;
+  },
+): Promise<SubtitleSelection> => {
+  if (!player) return { kind: "notFound" };
+
+  // Called fire-and-forget (`void applyMpvSubtitleSelection(...)`), so any native
+  // rejection from getSubtitleTracks/setSubtitleTrack/disableSubtitles must be
+  // swallowed here instead of escaping as an unhandled promise rejection.
+  try {
+    // Short-circuit the outcomes that don't need the player's track list, so
+    // the common subtitles-off case skips a full native enumeration.
+    if (params.jellyfinSubtitleIndex === -1) {
+      await player.disableSubtitles();
+      return { kind: "disable" };
+    }
+    const burnTarget = params.subtitleStreams?.find(
+      (s) => s.Index === params.jellyfinSubtitleIndex,
+    );
+    if (burnTarget && isBurnedInSubtitle(burnTarget)) {
+      return { kind: "burnedIn" };
+    }
+
+    const tracks = (await player.getSubtitleTracks()) ?? [];
+    const selection = resolveSubtitleTrack({
+      subtitleStreams: params.subtitleStreams,
+      jellyfinSubtitleIndex: params.jellyfinSubtitleIndex,
+      playerTracks: tracks.map((t) => ({
+        id: t.id,
+        external: t.external,
+        externalFilename: t.externalFilename,
+        language: t.lang,
+        title: t.title,
+        codec: t.codec,
+      })),
+      getExpectedExternalUrl: params.getExpectedExternalUrl,
+    });
+
+    if (selection.kind === "select") {
+      await player.setSubtitleTrack(selection.trackId);
+    } else if (selection.kind === "disable") {
+      await player.disableSubtitles();
+    }
+    // notFound → leave current selection (e.g. image subs burned in while transcoding)
+    return selection;
+  } catch {
+    return { kind: "notFound" };
+  }
 };
 
 /**