refactor: Feature/offline mode rework (#859)

Co-authored-by: lostb1t <coding-mosses0z@icloud.com>
Co-authored-by: Fredrik Burmester <fredrik.burmester@gmail.com>
Co-authored-by: Gauvain <68083474+Gauvino@users.noreply.github.com>
Co-authored-by: Gauvino <uruknarb20@gmail.com>
Co-authored-by: storm1er <le.storm1er@gmail.com>
Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: Chris <182387676+whoopsi-daisy@users.noreply.github.com>
Co-authored-by: arch-fan <55891793+arch-fan@users.noreply.github.com>
Co-authored-by: Alex Kim <alexkim@Alexs-MacBook-Pro.local>

hooks/useAdjacentEpisodes.ts

@@ -1,64 +0,0 @@
-import type { BaseItemDto } from "@jellyfin/sdk/lib/generated-client";
-import { getTvShowsApi } from "@jellyfin/sdk/lib/utils/api";
-import { useQuery } from "@tanstack/react-query";
-import { useAtomValue } from "jotai";
-import { useMemo } from "react";
-import { apiAtom } from "@/providers/JellyfinProvider";
-
-interface AdjacentEpisodesProps {
-  item?: BaseItemDto | null;
-}
-
-export const useAdjacentItems = ({ item }: AdjacentEpisodesProps) => {
-  const api = useAtomValue(apiAtom);
-
-  const { data: adjacentItems } = useQuery({
-    queryKey: ["adjacentItems", item?.Id, item?.SeriesId],
-    queryFn: async (): Promise<BaseItemDto[] | null> => {
-      if (!api || !item || !item.SeriesId) {
-        return null;
-      }
-
-      const res = await getTvShowsApi(api).getEpisodes({
-        seriesId: item.SeriesId,
-        adjacentTo: item.Id,
-        limit: 3,
-        fields: ["MediaSources", "MediaStreams", "ParentId"],
-      });
-
-      return res.data.Items || null;
-    },
-    enabled:
-      !!api &&
-      !!item?.Id &&
-      !!item?.SeriesId &&
-      (item?.Type === "Episode" || item?.Type === "Audio"),
-    staleTime: 0,
-  });
-
-  const previousItem = useMemo(() => {
-    if (!adjacentItems || adjacentItems.length <= 1) {
-      return null;
-    }
-
-    if (adjacentItems.length === 2) {
-      return adjacentItems[0].Id === item?.Id ? null : adjacentItems[0];
-    }
-
-    return adjacentItems[0];
-  }, [adjacentItems, item]);
-
-  const nextItem = useMemo(() => {
-    if (!adjacentItems || adjacentItems.length <= 1) {
-      return null;
-    }
-
-    if (adjacentItems.length === 2) {
-      return adjacentItems[1].Id === item?.Id ? null : adjacentItems[1];
-    }
-
-    return adjacentItems[2];
-  }, [adjacentItems, item]);
-
-  return { previousItem, nextItem };
-};

hooks/useCreditSkipper.ts

@@ -1,33 +1,16 @@
-import { useQuery } from "@tanstack/react-query";
-import { useAtom } from "jotai";
 import { useCallback, useEffect, useState } from "react";
-import { apiAtom } from "@/providers/JellyfinProvider";
-import { getAuthHeaders } from "@/utils/jellyfin/jellyfin";
-import { writeToLog } from "@/utils/log";
+import { useSegments } from "@/utils/segments";
 import { msToSeconds, secondsToMs } from "@/utils/time";
 import { useHaptic } from "./useHaptic";
 
-interface CreditTimestamps {
-  Introduction: {
-    Start: number;
-    End: number;
-    Valid: boolean;
-  };
-  Credits: {
-    Start: number;
-    End: number;
-    Valid: boolean;
-  };
-}
-
 export const useCreditSkipper = (
-  itemId: string | undefined,
+  itemId: string,
   currentTime: number,
   seek: (time: number) => void,
   play: () => void,
   isVlc = false,
+  isOffline = false,
 ) => {
-  const [api] = useAtom(apiAtom);
   const [showSkipCreditButton, setShowSkipCreditButton] = useState(false);
   const lightHapticFeedback = useHaptic("light");
 
@@ -43,52 +26,30 @@ export const useCreditSkipper = (
     seek(seconds);
   };
 
-  const { data: creditTimestamps } = useQuery<CreditTimestamps | null>({
-    queryKey: ["creditTimestamps", itemId],
-    queryFn: async () => {
-      if (!itemId) {
-        return null;
-      }
-
-      const res = await api?.axiosInstance.get(
-        `${api.basePath}/Episode/${itemId}/Timestamps`,
-        {
-          headers: getAuthHeaders(api),
-        },
-      );
-
-      if (res?.status !== 200) {
-        return null;
-      }
-
-      return res?.data;
-    },
-    enabled: !!itemId,
-    retry: false,
-  });
+  const { data: segments } = useSegments(itemId, isOffline);
+  const creditTimestamps = segments?.creditSegments?.[0];
 
   useEffect(() => {
     if (creditTimestamps) {
       setShowSkipCreditButton(
-        currentTime > creditTimestamps.Credits.Start &&
-          currentTime < creditTimestamps.Credits.End,
+        currentTime > creditTimestamps.startTime &&
+          currentTime < creditTimestamps.endTime,
       );
     }
   }, [creditTimestamps, currentTime]);
 
   const skipCredit = useCallback(() => {
     if (!creditTimestamps) return;
-    console.log(`Skipping credits to ${creditTimestamps.Credits.End}`);
     try {
       lightHapticFeedback();
-      wrappedSeek(creditTimestamps.Credits.End);
+      wrappedSeek(creditTimestamps.endTime);
       setTimeout(() => {
         play();
       }, 200);
     } catch (error) {
-      writeToLog("ERROR", "Error skipping intro", error);
+      console.error("Error skipping credit", error);
     }
-  }, [creditTimestamps]);
+  }, [creditTimestamps, lightHapticFeedback, wrappedSeek, play]);
 
   return { showSkipCreditButton, skipCredit };
 };

hooks/useDownloadedFileOpener.ts

@@ -1,41 +1,28 @@
 import type { BaseItemDto } from "@jellyfin/sdk/lib/generated-client";
-import * as FileSystem from "expo-file-system";
 import { useRouter } from "expo-router";
 import { useCallback } from "react";
 import { usePlaySettings } from "@/providers/PlaySettingsProvider";
 import { writeToLog } from "@/utils/log";
 
-export const getDownloadedFileUrl = async (itemId: string): Promise<string> => {
-  const directory = FileSystem.documentDirectory;
-
-  if (!directory) {
-    throw new Error("Document directory is not available");
-  }
-
-  if (!itemId) {
-    throw new Error("Item ID is not available");
-  }
-
-  const files = await FileSystem.readDirectoryAsync(directory);
-  const path = itemId!;
-  const matchingFile = files.find((file) => file.startsWith(path));
-
-  if (!matchingFile) {
-    throw new Error(`No file found for item ${path}`);
-  }
-
-  return `${directory}${matchingFile}`;
-};
-
 export const useDownloadedFileOpener = () => {
   const router = useRouter();
   const { setPlayUrl, setOfflineSettings } = usePlaySettings();
 
   const openFile = useCallback(
     async (item: BaseItemDto) => {
+      if (!item.Id) {
+        writeToLog("ERROR", "Attempted to open a file without an ID.");
+        console.error("Attempted to open a file without an ID.");
+        return;
+      }
+      const queryParams = new URLSearchParams({
+        itemId: item.Id,
+        offline: "true",
+        playbackPosition:
+          item.UserData?.PlaybackPositionTicks?.toString() ?? "0",
+      });
       try {
-        // @ts-expect-error
-        router.push(`/player/direct-player?offline=true&itemId=${item.Id}`);
+        router.push(`/player/direct-player?${queryParams.toString()}`);
       } catch (error) {
         writeToLog("ERROR", "Error opening file", error);
         console.error("Error opening file:", error);

hooks/useIntroSkipper.ts

@@ -1,34 +1,21 @@
-import { useQuery } from "@tanstack/react-query";
-import { useAtom } from "jotai";
 import { useCallback, useEffect, useState } from "react";
-import { apiAtom } from "@/providers/JellyfinProvider";
-import { getAuthHeaders } from "@/utils/jellyfin/jellyfin";
-import { writeToLog } from "@/utils/log";
+import { useSegments } from "@/utils/segments";
 import { msToSeconds, secondsToMs } from "@/utils/time";
 import { useHaptic } from "./useHaptic";
 
-interface IntroTimestamps {
-  EpisodeId: string;
-  HideSkipPromptAt: number;
-  IntroEnd: number;
-  IntroStart: number;
-  ShowSkipPromptAt: number;
-  Valid: boolean;
-}
-
 /**
  * Custom hook to handle skipping intros in a media player.
  *
  * @param {number} currentTime - The current playback time in seconds.
  */
 export const useIntroSkipper = (
-  itemId: string | undefined,
+  itemId: string,
   currentTime: number,
   seek: (ticks: number) => void,
   play: () => void,
   isVlc = false,
+  isOffline = false,
 ) => {
-  const [api] = useAtom(apiAtom);
   const [showSkipButton, setShowSkipButton] = useState(false);
   if (isVlc) {
     currentTime = msToSeconds(currentTime);
@@ -43,35 +30,14 @@ export const useIntroSkipper = (
     seek(seconds);
   };
 
-  const { data: introTimestamps } = useQuery<IntroTimestamps | null>({
-    queryKey: ["introTimestamps", itemId],
-    queryFn: async () => {
-      if (!itemId) {
-        return null;
-      }
-
-      const res = await api?.axiosInstance.get(
-        `${api.basePath}/Episode/${itemId}/IntroTimestamps`,
-        {
-          headers: getAuthHeaders(api),
-        },
-      );
-
-      if (res?.status !== 200) {
-        return null;
-      }
-
-      return res?.data;
-    },
-    enabled: !!itemId,
-    retry: false,
-  });
+  const { data: segments } = useSegments(itemId, isOffline);
+  const introTimestamps = segments?.introSegments?.[0];
 
   useEffect(() => {
     if (introTimestamps) {
       setShowSkipButton(
-        currentTime > introTimestamps.ShowSkipPromptAt &&
-          currentTime < introTimestamps.HideSkipPromptAt,
+        currentTime > introTimestamps.startTime &&
+          currentTime < introTimestamps.endTime,
       );
     }
   }, [introTimestamps, currentTime]);
@@ -80,14 +46,14 @@ export const useIntroSkipper = (
     if (!introTimestamps) return;
     try {
       lightHapticFeedback();
-      wrappedSeek(introTimestamps.IntroEnd);
+      wrappedSeek(introTimestamps.endTime);
       setTimeout(() => {
         play();
       }, 200);
     } catch (error) {
-      writeToLog("ERROR", "Error skipping intro", error);
+      console.error("Error skipping intro", error);
     }
-  }, [introTimestamps]);
+  }, [introTimestamps, lightHapticFeedback, wrappedSeek, play]);
 
   return { showSkipButton, skipIntro };
 };

hooks/useItemQuery.ts

@@ -0,0 +1,31 @@
+import { getUserLibraryApi } from "@jellyfin/sdk/lib/utils/api";
+import { useQuery } from "@tanstack/react-query";
+import { useAtom } from "jotai";
+import { useDownload } from "@/providers/DownloadProvider";
+import { apiAtom, userAtom } from "@/providers/JellyfinProvider";
+
+export const useItemQuery = (itemId: string, isOffline: boolean) => {
+  const [api] = useAtom(apiAtom);
+  const [user] = useAtom(userAtom);
+  const { getDownloadedItemById } = useDownload();
+
+  return useQuery({
+    queryKey: ["item", itemId],
+    queryFn: async () => {
+      if (isOffline) {
+        return getDownloadedItemById(itemId)?.item;
+      }
+      if (!api || !user || !itemId) return null;
+      const res = await getUserLibraryApi(api).getItem({
+        itemId: itemId,
+        userId: user?.Id,
+      });
+      return res.data;
+    },
+    staleTime: 0,
+    refetchOnMount: true,
+    refetchOnWindowFocus: true,
+    refetchOnReconnect: true,
+    networkMode: "always",
+  });
+};

hooks/useMarkAsPlayed.ts

@@ -1,102 +1,25 @@
 import type { BaseItemDto } from "@jellyfin/sdk/lib/generated-client/models";
-import { useQueryClient } from "@tanstack/react-query";
-import { useAtom } from "jotai";
-import { apiAtom, userAtom } from "@/providers/JellyfinProvider";
-import { markAsNotPlayed } from "@/utils/jellyfin/playstate/markAsNotPlayed";
-import { markAsPlayed } from "@/utils/jellyfin/playstate/markAsPlayed";
 import { useHaptic } from "./useHaptic";
+import { usePlaybackManager } from "./usePlaybackManager";
+import { useInvalidatePlaybackProgressCache } from "./useRevalidatePlaybackProgressCache";
 
 export const useMarkAsPlayed = (items: BaseItemDto[]) => {
-  const [api] = useAtom(apiAtom);
-  const [user] = useAtom(userAtom);
-  const queryClient = useQueryClient();
   const lightHapticFeedback = useHaptic("light");
+  const { markItemPlayed, markItemUnplayed } = usePlaybackManager();
+  const invalidatePlaybackProgressCache = useInvalidatePlaybackProgressCache();
 
-  const invalidateQueries = () => {
-    const queriesToInvalidate = [
-      ["resumeItems"],
-      ["continueWatching"],
-      ["nextUp-all"],
-      ["nextUp"],
-      ["episodes"],
-      ["seasons"],
-      ["home"],
-    ];
-
-    items.forEach((item) => {
-      if (!item.Id) return;
-      queriesToInvalidate.push(["item", item.Id]);
-    });
-
-    queriesToInvalidate.forEach((queryKey) => {
-      queryClient.invalidateQueries({ queryKey });
-    });
-  };
-
-  const markAsPlayedStatus = async (played: boolean) => {
+  const toggle = async (played: boolean) => {
     lightHapticFeedback();
+    // Process all items
+    await Promise.all(
+      items.map((item) => {
+        if (!item.Id) return Promise.resolve();
+        return played ? markItemPlayed(item.Id) : markItemUnplayed(item.Id);
+      }),
+    );
 
-    items.forEach((item) => {
-      // Optimistic update
-      queryClient.setQueryData(
-        ["item", item.Id],
-        (oldData: BaseItemDto | undefined) => {
-          if (oldData) {
-            return {
-              ...oldData,
-              UserData: {
-                ...oldData.UserData,
-                Played: played,
-              },
-            };
-          }
-          return oldData;
-        },
-      );
-    });
-
-    try {
-      // Process all items
-      await Promise.all(
-        items.map((item) =>
-          played
-            ? markAsPlayed({ api, item, userId: user?.Id })
-            : markAsNotPlayed({ api, itemId: item?.Id, userId: user?.Id }),
-        ),
-      );
-
-      // Bulk invalidate
-      queryClient.invalidateQueries({
-        queryKey: [
-          "resumeItems",
-          "continueWatching",
-          "nextUp-all",
-          "nextUp",
-          "episodes",
-          "seasons",
-          "home",
-          ...items.map((item) => ["item", item.Id]),
-        ].flat(),
-      });
-    } catch (error) {
-      // Revert all optimistic updates on any failure
-      items.forEach((item) => {
-        queryClient.setQueryData(
-          ["item", item.Id],
-          (oldData: BaseItemDto | undefined) =>
-            oldData
-              ? {
-                  ...oldData,
-                  UserData: { ...oldData.UserData, Played: played },
-                }
-              : oldData,
-        );
-      });
-      console.error("Error updating played status:", error);
-    }
-
-    invalidateQueries();
+    await invalidatePlaybackProgressCache();
   };
 
-  return markAsPlayedStatus;
+  return toggle;
 };

hooks/usePlaybackManager.ts

@@ -0,0 +1,284 @@
+import type { BaseItemDto } from "@jellyfin/sdk/lib/generated-client";
+import { getPlaystateApi, getTvShowsApi } from "@jellyfin/sdk/lib/utils/api";
+import { useNetInfo } from "@react-native-community/netinfo";
+import { useQuery } from "@tanstack/react-query";
+import { useAtomValue } from "jotai";
+import { useMemo } from "react";
+import { useDownload } from "@/providers/DownloadProvider";
+import { DownloadedItem } from "@/providers/Downloads/types";
+import { apiAtom, userAtom } from "@/providers/JellyfinProvider";
+
+interface PlaybackManagerProps {
+  item?: BaseItemDto | null;
+  isOffline?: boolean;
+}
+
+/**
+ * Gets adjacent items (previous/current/next) for offline mode from downloaded files
+ */
+const getOfflineAdjacentItems = (
+  item: BaseItemDto,
+  downloadedFiles: DownloadedItem[],
+): BaseItemDto[] | null => {
+  if (!item.SeriesId || !downloadedFiles) {
+    return null;
+  }
+
+  const seriesEpisodes = downloadedFiles
+    .filter((f) => f.item.SeriesId === item.SeriesId)
+    .map((f) => f.item);
+
+  seriesEpisodes.sort((a, b) => {
+    if (a.ParentIndexNumber !== b.ParentIndexNumber) {
+      return (a.ParentIndexNumber ?? 0) - (b.ParentIndexNumber ?? 0);
+    }
+    return (a.IndexNumber ?? 0) - (b.IndexNumber ?? 0);
+  });
+
+  const currentIndex = seriesEpisodes.findIndex((ep) => ep.Id === item.Id);
+
+  if (currentIndex === -1) {
+    return null;
+  }
+
+  const result: BaseItemDto[] = [];
+  if (currentIndex > 0) {
+    result.push(seriesEpisodes[currentIndex - 1]);
+  }
+  result.push(seriesEpisodes[currentIndex]);
+  if (currentIndex < seriesEpisodes.length - 1) {
+    result.push(seriesEpisodes[currentIndex + 1]);
+  }
+  return result;
+};
+
+/**
+ * A hook to manage playback state, abstracting away the complexities of
+ * online/offline and local/remote state management.
+ *
+ * This provides a simple facade for player components to report playback
+ * without needing to know the underlying details of data syncing.
+ */
+export const usePlaybackManager = ({
+  item,
+  isOffline = false,
+}: PlaybackManagerProps = {}) => {
+  const api = useAtomValue(apiAtom);
+  const user = useAtomValue(userAtom);
+  const netInfo = useNetInfo();
+  const { getDownloadedItemById, updateDownloadedItem, getDownloadedItems } =
+    useDownload();
+
+  /** Whether the device is online. actually it's connected to the internet. */
+  const isOnline = netInfo.isConnected;
+
+  // Adjacent episodes logic
+  const { data: adjacentItems } = useQuery({
+    queryKey: ["adjacentItems", item?.Id, item?.SeriesId, isOffline],
+    queryFn: async (): Promise<BaseItemDto[] | null> => {
+      if (!item || !item.SeriesId) {
+        return null;
+      }
+
+      if (isOffline) {
+        return getOfflineAdjacentItems(item, getDownloadedItems() || []);
+      }
+
+      if (!api) {
+        return null;
+      }
+
+      const res = await getTvShowsApi(api).getEpisodes({
+        seriesId: item.SeriesId,
+        adjacentTo: item.Id,
+        limit: 3,
+        fields: ["MediaSources", "MediaStreams", "ParentId"],
+      });
+
+      return res.data.Items || null;
+    },
+    enabled:
+      (isOffline || !!api) &&
+      !!item?.Id &&
+      !!item?.SeriesId &&
+      (item?.Type === "Episode" || item?.Type === "Audio"),
+    staleTime: 0,
+  });
+
+  const previousItem = useMemo(() => {
+    if (!adjacentItems || adjacentItems.length <= 1) {
+      return null;
+    }
+
+    if (adjacentItems.length === 2) {
+      return adjacentItems[0].Id === item?.Id ? null : adjacentItems[0];
+    }
+
+    return adjacentItems[0];
+  }, [adjacentItems, item]);
+
+  /** The next item in the series */
+  const nextItem = useMemo(() => {
+    if (!adjacentItems || adjacentItems.length <= 1) {
+      return null;
+    }
+
+    if (adjacentItems.length === 2) {
+      return adjacentItems[1].Id === item?.Id ? null : adjacentItems[1];
+    }
+
+    return adjacentItems[2];
+  }, [adjacentItems, item]);
+
+  /**
+   * Reports playback progress.
+   *
+   * - If offline and the item is downloaded, updates are saved locally.
+   * - If online and the item is downloaded, it updates locally and syncs with the server.
+   * - If online and streaming, it reports directly to the server.
+   *
+   * @param itemId The ID of the item.
+   * @param positionTicks The current playback position in ticks.
+   */
+  const reportPlaybackProgress = async (
+    itemId: string,
+    positionTicks: number,
+    metadata?: {
+      AudioStreamIndex: number;
+      SubtitleStreamIndex: number;
+    },
+  ) => {
+    const localItem = getDownloadedItemById(itemId);
+
+    // Handle local state update for downloaded items
+    if (localItem) {
+      const isItemConsideredPlayed =
+        (localItem.item.UserData?.PlayedPercentage ?? 0) > 90;
+      updateDownloadedItem(itemId, {
+        ...localItem,
+        item: {
+          ...localItem.item,
+          UserData: {
+            ...localItem.item.UserData,
+            PlaybackPositionTicks: isItemConsideredPlayed
+              ? 0
+              : Math.floor(positionTicks),
+            Played: isItemConsideredPlayed,
+            LastPlayedDate: new Date().toISOString(),
+            PlayedPercentage: isItemConsideredPlayed
+              ? 0
+              : (positionTicks / localItem.item.RunTimeTicks!) * 100,
+          },
+        },
+      });
+    }
+
+    // Handle remote state update if online
+    if (isOnline && api) {
+      try {
+        await getPlaystateApi(api).reportPlaybackProgress({
+          playbackProgressInfo: {
+            ItemId: itemId,
+            PositionTicks: Math.floor(positionTicks),
+            ...(metadata && { AudioStreamIndex: metadata.AudioStreamIndex }),
+            ...(metadata && {
+              SubtitleStreamIndex: metadata.SubtitleStreamIndex,
+            }),
+          },
+        });
+      } catch (error) {
+        console.error("Failed to report playback progress", error);
+      }
+    }
+  };
+
+  /**
+   * Marks an item as played.
+   *
+   * - If offline and downloaded, it marks as played locally.
+   * - If online, it marks as played on the server and syncs the state back to the local item if it exists.
+   *
+   * @param itemId The ID of the item.
+   */
+  const markItemPlayed = async (itemId: string) => {
+    const localItem = getDownloadedItemById(itemId);
+
+    // Handle local state update for downloaded items
+    if (localItem) {
+      updateDownloadedItem(itemId, {
+        ...localItem,
+        item: {
+          ...localItem.item,
+          UserData: {
+            ...localItem.item.UserData,
+            Played: true,
+            PlaybackPositionTicks: 0,
+            PlayedPercentage: 0,
+            LastPlayedDate: new Date().toISOString(),
+          },
+        },
+      });
+    }
+
+    // Handle remote state update if online
+    if (isOnline && api && user) {
+      try {
+        await getPlaystateApi(api).markPlayedItem({
+          itemId,
+          userId: user.Id,
+        });
+      } catch (error) {
+        console.error("Failed to mark item as played on server", error);
+      }
+    }
+  };
+
+  /**
+   * Marks an item as unplayed.
+   *
+   * - If offline and downloaded, it marks as unplayed locally.
+   * - If online, it marks as unplayed on the server and syncs the state back to the local item if it exists.
+   *
+   * @param itemId The ID of the item.
+   */
+  const markItemUnplayed = async (itemId: string) => {
+    const localItem = getDownloadedItemById(itemId);
+
+    // Handle local state update for downloaded items
+    if (localItem) {
+      updateDownloadedItem(itemId, {
+        ...localItem,
+        item: {
+          ...localItem.item,
+          UserData: {
+            ...localItem.item.UserData,
+            Played: false,
+            PlaybackPositionTicks: 0,
+            PlayedPercentage: 0,
+            LastPlayedDate: new Date().toISOString(), // Keep track of when it was marked unplayed
+          },
+        },
+      });
+    }
+
+    // Handle remote state update if online
+    if (isOnline && api && user) {
+      try {
+        await getPlaystateApi(api).markUnplayedItem({
+          itemId,
+          userId: user.Id,
+        });
+      } catch (error) {
+        console.error("Failed to mark item as unplayed on server", error);
+      }
+    }
+  };
+
+  return {
+    reportPlaybackProgress,
+    markItemPlayed,
+    markItemUnplayed,
+    previousItem,
+    nextItem,
+  };
+};

hooks/useRevalidatePlaybackProgressCache.ts

@@ -1,10 +1,14 @@
 import { useQueryClient } from "@tanstack/react-query";
+import { useDownload } from "@/providers/DownloadProvider";
+import { useTwoWaySync } from "./useTwoWaySync";
 
 /**
  * useRevalidatePlaybackProgressCache invalidates queries related to playback progress.
  */
 export function useInvalidatePlaybackProgressCache() {
   const queryClient = useQueryClient();
+  const { getDownloadedItems } = useDownload();
+  const { syncPlaybackState } = useTwoWaySync();
 
   const revalidate = async () => {
     // List of all the queries to invalidate
@@ -17,11 +21,34 @@ export function useInvalidatePlaybackProgressCache() {
       ["episodes"],
       ["seasons"],
       ["home"],
+      ["downloadedItems"],
     ];
 
-    // Invalidate each query
-    for (const queryKey of queriesToInvalidate) {
-      await queryClient.invalidateQueries({ queryKey });
+    // We Invalidate all the queries to the latest server versions
+    await Promise.all(
+      queriesToInvalidate.map((queryKey) =>
+        queryClient.invalidateQueries({ queryKey }),
+      ),
+    );
+
+    const downloadedFiles = getDownloadedItems();
+    // Sync playback state for downloaded items
+    if (downloadedFiles) {
+      // We sync the playback state for the downloaded items
+      const syncResults = await Promise.all(
+        downloadedFiles.map((downloadedItem) =>
+          syncPlaybackState(downloadedItem.item.Id!),
+        ),
+      );
+      // We invalidate the queries again in case we have updated a server's playback progress.
+      const shouldInvalidate = syncResults.some((result) => result);
+
+      console.log("shouldInvalidate", shouldInvalidate);
+      if (shouldInvalidate) {
+        queriesToInvalidate.map((queryKey) =>
+          queryClient.invalidateQueries({ queryKey }),
+        );
+      }
     }
   };
 

hooks/useTrickplay.ts

@@ -1,11 +1,80 @@
 import type { BaseItemDto } from "@jellyfin/sdk/lib/generated-client";
 import { Image } from "expo-image";
-import { useAtom } from "jotai";
+import { useGlobalSearchParams } from "expo-router";
 import { useCallback, useMemo, useRef, useState } from "react";
+import { useDownload } from "@/providers/DownloadProvider";
 import { apiAtom } from "@/providers/JellyfinProvider";
+import { store } from "@/utils/store";
 import { ticksToMs } from "@/utils/time";
 
-interface TrickplayData {
+interface TrickplayUrl {
+  x: number;
+  y: number;
+  url: string;
+}
+
+/** Hook to handle trickplay logic for a given item. */
+export const useTrickplay = (item: BaseItemDto) => {
+  const [trickPlayUrl, setTrickPlayUrl] = useState<TrickplayUrl | null>(null);
+  const { getDownloadedItemById } = useDownload();
+  const lastCalculationTime = useRef(0);
+  const throttleDelay = 200;
+  const isOffline = useGlobalSearchParams().offline === "true";
+  const trickplayInfo = useMemo(() => getTrickplayInfo(item), [item]);
+
+  /** Generates the trickplay URL for the given item and sheet index.
+   * We change between offline and online trickplay URLs depending on the state of the app. */
+  const getTrickplayUrl = useCallback(
+    (item: BaseItemDto, sheetIndex: number) => {
+      // If we are offline, we can use the downloaded item's trickplay data path
+      const downloadedItem = getDownloadedItemById(item.Id!);
+      if (isOffline && downloadedItem?.trickPlayData?.path) {
+        return `${downloadedItem.trickPlayData.path}${sheetIndex}.jpg`;
+      }
+      return generateTrickplayUrl(item, sheetIndex);
+    },
+    [trickplayInfo],
+  );
+
+  /** Calculates the trickplay URL for the current progress. */
+  const calculateTrickplayUrl = useCallback(
+    (progress: number) => {
+      const now = Date.now();
+      if (
+        !trickplayInfo ||
+        !item.Id ||
+        now - lastCalculationTime.current < throttleDelay
+      )
+        return;
+      lastCalculationTime.current = now;
+      const { sheetIndex, x, y } = calculateTrickplayTile(
+        progress,
+        trickplayInfo,
+      );
+      const url = getTrickplayUrl(item, sheetIndex);
+      if (url) setTrickPlayUrl({ x, y, url });
+    },
+    [trickplayInfo, item, throttleDelay, getTrickplayUrl],
+  );
+
+  /** Prefetches all the trickplay images for the item. */
+  const prefetchAllTrickplayImages = useCallback(() => {
+    if (!trickplayInfo || !item.Id) return;
+    for (let index = 0; index < trickplayInfo.totalImageSheets; index++) {
+      const url = getTrickplayUrl(item, index);
+      if (url) Image.prefetch(url);
+    }
+  }, [trickplayInfo, item, getTrickplayUrl]);
+
+  return {
+    trickPlayUrl,
+    calculateTrickplayUrl,
+    prefetchAllTrickplayImages,
+    trickplayInfo,
+  };
+};
+
+export interface TrickplayData {
   Interval?: number;
   TileWidth?: number;
   TileHeight?: number;
@@ -14,136 +83,93 @@ interface TrickplayData {
   ThumbnailCount?: number;
 }
 
-interface TrickplayUrl {
-  x: number;
-  y: number;
-  url: string;
+export interface TrickplayInfo {
+  resolution: string;
+  aspectRatio: number;
+  data: TrickplayData;
+  totalImageSheets: number;
 }
 
-export const useTrickplay = (item: BaseItemDto, enabled = true) => {
-  const [api] = useAtom(apiAtom);
-  const [trickPlayUrl, setTrickPlayUrl] = useState<TrickplayUrl | null>(null);
-  const lastCalculationTime = useRef(0);
-  const throttleDelay = 200; // 200ms throttle
+/** Generates a trickplay URL based on the item, resolution, and sheet index. */
+export const generateTrickplayUrl = (item: BaseItemDto, sheetIndex: number) => {
+  const api = store.get(apiAtom);
+  const resolution = getTrickplayInfo(item)?.resolution;
+  if (!resolution || !api) return null;
+  return `${api.basePath}/Videos/${item.Id}/Trickplay/${resolution}/${sheetIndex}.jpg?api_key=${api.accessToken}`;
+};
 
-  const trickplayInfo = useMemo(() => {
-    if (!enabled || !item.Id || !item.Trickplay) {
-      return null;
-    }
+/**
+ * Parses the trickplay metadata from a BaseItemDto.
+ * @param item The Jellyfin media item.
+ * @returns Parsed trickplay information or null if not available.
+ */
+export const getTrickplayInfo = (item: BaseItemDto): TrickplayInfo | null => {
+  if (!item.Id || !item.Trickplay) return null;
 
-    const mediaSourceId = item.Id;
-    const trickplayData: Record<string, TrickplayData> | undefined =
-      item.Trickplay[mediaSourceId];
+  const mediaSourceId = item.Id;
+  const trickplayDataForSource = item.Trickplay[mediaSourceId];
 
-    if (!trickplayData) {
-      return null;
-    }
+  if (!trickplayDataForSource) {
+    return null;
+  }
 
-    // Get the first available resolution
-    const firstResolution = Object.keys(trickplayData)[0];
-    return firstResolution
-      ? {
-          resolution: firstResolution,
-          aspectRatio:
-            trickplayData[firstResolution].Width! /
-            trickplayData[firstResolution].Height!,
-          data: trickplayData[firstResolution],
-        }
-      : null;
-  }, [item, enabled]);
+  const firstResolution = Object.keys(trickplayDataForSource)[0];
+  if (!firstResolution) {
+    return null;
+  }
 
-  // Takes in ticks.
-  const calculateTrickplayUrl = useCallback(
-    (progress: number) => {
-      if (!enabled) {
-        return null;
-      }
+  const data = trickplayDataForSource[firstResolution];
+  const { Interval, TileWidth, TileHeight, Width, Height } = data;
 
-      const now = Date.now();
-      if (now - lastCalculationTime.current < throttleDelay) {
-        return null;
-      }
-      lastCalculationTime.current = now;
+  if (
+    !Interval ||
+    !TileWidth ||
+    !TileHeight ||
+    !Width ||
+    !Height ||
+    !item.RunTimeTicks
+  ) {
+    return null;
+  }
 
-      if (!trickplayInfo || !api || !item.Id) {
-        return null;
-      }
-
-      const { data, resolution } = trickplayInfo;
-      const { Interval, TileWidth, TileHeight, Width, Height } = data;
-
-      if (
-        !Interval ||
-        !TileWidth ||
-        !TileHeight ||
-        !resolution ||
-        !Width ||
-        !Height
-      ) {
-        throw new Error("Invalid trickplay data");
-      }
-
-      const currentTimeMs = Math.max(0, ticksToMs(progress));
-      const currentTile = Math.floor(currentTimeMs / Interval);
-
-      const tileSize = TileWidth * TileHeight;
-      const tileOffset = currentTile % tileSize;
-      const index = Math.floor(currentTile / tileSize);
-
-      const tileOffsetX = tileOffset % TileWidth;
-      const tileOffsetY = Math.floor(tileOffset / TileWidth);
-
-      const newTrickPlayUrl = {
-        x: tileOffsetX,
-        y: tileOffsetY,
-        url: `${api.basePath}/Videos/${item.Id}/Trickplay/${resolution}/${index}.jpg?api_key=${api.accessToken}`,
-      };
-
-      setTrickPlayUrl(newTrickPlayUrl);
-      return newTrickPlayUrl;
-    },
-    [trickplayInfo, item, api, enabled],
-  );
-
-  const prefetchAllTrickplayImages = useCallback(() => {
-    if (!api || !enabled || !trickplayInfo || !item.Id || !item.RunTimeTicks) {
-      return;
-    }
-
-    const { data, resolution } = trickplayInfo;
-    const { Interval, TileWidth, TileHeight, Width, Height } = data;
-
-    if (
-      !Interval ||
-      !TileWidth ||
-      !TileHeight ||
-      !resolution ||
-      !Width ||
-      !Height
-    ) {
-      throw new Error("Invalid trickplay data");
-    }
-
-    // Calculate tiles per sheet
-    const tilesPerRow = TileWidth;
-    const tilesPerColumn = TileHeight;
-    const tilesPerSheet = tilesPerRow * tilesPerColumn;
-    const totalTiles = Math.ceil(ticksToMs(item.RunTimeTicks) / Interval);
-    const totalIndexes = Math.ceil(totalTiles / tilesPerSheet);
-
-    // Prefetch all trickplay images
-    for (let index = 0; index < totalIndexes; index++) {
-      const url = `${api.basePath}/Videos/${item.Id}/Trickplay/${resolution}/${index}.jpg?api_key=${api.accessToken}`;
-      Image.prefetch(url);
-    }
-  }, [trickplayInfo, item, api, enabled]);
+  const tilesPerSheet = TileWidth * TileHeight;
+  const totalTiles = Math.ceil(ticksToMs(item.RunTimeTicks) / Interval);
+  const totalImageSheets = Math.ceil(totalTiles / tilesPerSheet);
 
   return {
-    trickPlayUrl: enabled ? trickPlayUrl : null,
-    calculateTrickplayUrl: enabled ? calculateTrickplayUrl : () => null,
-    prefetchAllTrickplayImages: enabled
-      ? prefetchAllTrickplayImages
-      : () => null,
-    trickplayInfo: enabled ? trickplayInfo : null,
+    resolution: firstResolution,
+    aspectRatio: Width / Height,
+    data,
+    totalImageSheets,
   };
 };
+
+/**
+ * Calculates the specific image sheet and tile offset for a given time.
+ * @param progressTicks The current playback time in ticks.
+ * @param trickplayInfo The parsed trickplay information object.
+ * @returns An object with the image sheet index, and the X/Y coordinates for the tile.
+ */
+const calculateTrickplayTile = (
+  progressTicks: number,
+  trickplayInfo: TrickplayInfo,
+) => {
+  const { data } = trickplayInfo;
+  const { Interval, TileWidth, TileHeight } = data;
+
+  if (!Interval || !TileWidth || !TileHeight) {
+    throw new Error("Invalid trickplay data provided to calculateTile");
+  }
+
+  const currentTimeMs = Math.max(0, ticksToMs(progressTicks));
+  const currentTile = Math.floor(currentTimeMs / Interval);
+
+  const tilesPerSheet = TileWidth * TileHeight;
+  const sheetIndex = Math.floor(currentTile / tilesPerSheet);
+  const tileIndexInSheet = currentTile % tilesPerSheet;
+
+  const x = tileIndexInSheet % TileWidth;
+  const y = Math.floor(tileIndexInSheet / TileWidth);
+
+  return { sheetIndex, x, y };
+};

hooks/useTwoWaySync.ts

@@ -0,0 +1,86 @@
+import { getItemsApi, getUserLibraryApi } from "@jellyfin/sdk/lib/utils/api";
+import { useNetInfo } from "@react-native-community/netinfo";
+import { useAtomValue } from "jotai";
+import { useDownload } from "@/providers/DownloadProvider";
+import { apiAtom, userAtom } from "../providers/JellyfinProvider";
+
+/**
+ * This hook is used to sync the playback state of a downloaded item with the server
+ * when the application comes back online after being used offline.
+ */
+export const useTwoWaySync = () => {
+  const api = useAtomValue(apiAtom);
+  const user = useAtomValue(userAtom);
+  const netInfo = useNetInfo();
+  const { getDownloadedItemById, updateDownloadedItem } = useDownload();
+
+  /**
+   * Syncs the playback state of an offline item with the server.
+   * It determines if the local or remote state is more recent and applies the necessary update.
+   *
+   * @returns A Promise<boolean> indicating whether a server update was made (true) or not (false).
+   */
+  const syncPlaybackState = async (itemId: string): Promise<boolean> => {
+    if (!api || !user || !netInfo.isConnected) {
+      // Cannot sync if offline or not logged in
+      return false;
+    }
+
+    const localItem = getDownloadedItemById(itemId);
+    if (!localItem) return false;
+
+    const remoteItem = (
+      await getUserLibraryApi(api).getItem({ itemId, userId: user.Id })
+    ).data;
+    if (!remoteItem) return false;
+
+    const localLastPlayed = localItem.item.UserData?.LastPlayedDate
+      ? new Date(localItem.item.UserData.LastPlayedDate)
+      : new Date(0);
+    const remoteLastPlayed = remoteItem.UserData?.LastPlayedDate
+      ? new Date(remoteItem.UserData.LastPlayedDate)
+      : new Date(0);
+
+    // If the remote item has been played more recently, we take the server's version as the source of truth.
+    if (remoteLastPlayed > localLastPlayed) {
+      updateDownloadedItem(itemId, {
+        ...localItem,
+        item: {
+          ...localItem.item,
+          UserData: {
+            ...localItem.item.UserData,
+            LastPlayedDate: remoteItem.UserData?.LastPlayedDate,
+            PlaybackPositionTicks: remoteItem.UserData?.PlaybackPositionTicks,
+            Played: remoteItem.UserData?.Played,
+            PlayedPercentage: remoteItem.UserData?.PlayedPercentage,
+          },
+        },
+      });
+      return false;
+    } else if (remoteLastPlayed < localLastPlayed) {
+      // Since we're this is the source of truth, essentially need to make sure the played status matches the local item.
+      try {
+        await getItemsApi(api).updateItemUserData({
+          itemId: localItem.item.Id!,
+          userId: user.Id,
+          updateUserItemDataDto: {
+            Played: localItem.item.UserData?.Played,
+            PlaybackPositionTicks:
+              localItem.item.UserData?.PlaybackPositionTicks,
+            PlayedPercentage: localItem.item.UserData?.PlayedPercentage,
+            LastPlayedDate: localItem.item.UserData?.LastPlayedDate,
+          },
+        });
+      } catch (error) {
+        console.error(
+          "Failed to update item user data during syncPlaybackState:",
+          error,
+        );
+      }
+      return true;
+    }
+    return false;
+  };
+
+  return { syncPlaybackState };
+};