str-native-video-player 2.0.0 → 2.0.1

package/android/src/main/java/com/strtv/app/STRTV.java

@@ -1,430 +1,430 @@
-package com.strtv.app;
-
-import android.content.Context;
-import android.util.Log;
-
-import com.getcapacitor.JSArray;
-import com.getcapacitor.JSObject;
-import com.getcapacitor.Logger;
-
-import org.json.JSONArray;
-import org.json.JSONObject;
-
-import java.io.*;
-import java.net.URL;
-import java.util.*;
-import java.util.concurrent.*;
-import javax.net.ssl.HttpsURLConnection;
-
-/**
- * STRTV - streaming + cache manager (Option 1 MVP)
- *
- * Behavior:
- *  - getVideoFile(uuid, url): returns cached File if present (updates LRU). Does NOT download.
- *  - downloadInBackground(uuid, url): downloads into a .tmp file -> rename to final, update LRU, enforce cache.
- *
- * Notes:
- *  - Concurrent downloads for same uuid are deduplicated.
- *  - LRU persisted via file lastModified timestamps and loaded on init.
- */
-public class STRTV {
-
-    private static final String TAG = "STRTV";
-    private final Context context;
-    private final File storageDir;
-
-    // In-memory LRU map: uuid -> lastAccessedTime (access-order LinkedHashMap)
-    // Access to lruMap must be synchronized on lruLock.
-    private final LinkedHashMap<String, Long> lruMap = new LinkedHashMap<>(16, 0.75f, true);
-    private final Object lruLock = new Object();
-
-    private long maxCacheBytes = 1024L * 1024L * 1024L; // 1 GB default cache size
-
-
-
-    // Background download executor & tracking
-    private final ExecutorService dlExecutor = Executors.newFixedThreadPool(2);
-    private final ConcurrentHashMap<String, Future<?>> activeDownloads = new ConcurrentHashMap<>();
-
-    public STRTV(Context context) {
-        this.context = context;
-        this.storageDir = new File(context.getFilesDir(), "strtv_videos");
-
-        if (!storageDir.exists()) {
-            boolean ok = storageDir.mkdirs();
-            if (!ok) Log.w(TAG, "Failed to create storageDir: " + storageDir.getAbsolutePath());
-        }
-
-        // Populate LRU map from existing files (persisted lastModified)
-        initializeLRU();
-    }
-
-    public String echo(String value) {
-        Logger.info(TAG, value);
-        return value;
-    }
-
-    // ------------------------------------------------------------
-    // Public API used by plugin
-    // ------------------------------------------------------------
-
-    /**
-     * Returns cached file if present; otherwise returns null.
-     * DOES NOT attempt to download. Caller should call downloadInBackground(uuid, url) if needed.
-     */
-    public File getVideoFile(String uuid, String url) {
-        if (uuid == null || uuid.isEmpty()) return null;
-        File f = findLocalVideo(uuid);
-        if (f != null) {
-            updateLRU(uuid);
-            return f;
-        }
-        return null;
-    }
-
-    public interface VideoDownloadCallback {
-        void onDownloadComplete(File cachedFile);
-    }
-
-    /**
-     * Request a background download. Non-blocking.
-     * If a download for this uuid is already in progress, this is a no-op.
-     */
-    public void downloadInBackground(final String uuid, final String url, VideoDownloadCallback callback) {
-        if (uuid == null || url == null) {
-            Log.w(TAG, "downloadInBackground called with null uuid or url");
-            return;
-        }
-
-        // Deduplicate concurrent downloads
-        if (activeDownloads.containsKey(uuid)) {
-            Log.i(TAG, "Download already active for uuid=" + uuid);
-            return;
-        }
-
-        Future<?> future = dlExecutor.submit(() -> {
-            try {
-                Log.i(TAG, "Background download started: " + uuid + " -> " + url);
-                File downloaded = streamAndCacheVideoSync(uuid, url);
-                if (downloaded != null) {
-                    updateLRU(uuid);
-                    enforceCacheLimit();
-                    Log.i(TAG, "Background download finished: " + downloaded.getAbsolutePath());
-                     if (callback != null) {
-                        Log.i(TAG, "Calling download completion handler: ");
-                        callback.onDownloadComplete(downloaded);
-                    }
-                } else {
-                    Log.w(TAG, "Background download returned null for uuid=" + uuid);
-                }
-            } catch (Exception e) {
-                Log.e(TAG, "Background download failed for uuid=" + uuid + " : " + e.getMessage());
-                // ensure partial file cleanup handled in streamAndCacheVideoSync
-            } finally {
-                activeDownloads.remove(uuid);
-            }
-        });
-
-        // track active download
-        activeDownloads.put(uuid, future);
-    }
-
-    /**
-     * Preload syncronously or asynchronously? We choose to kick off background download and return quickly.
-     */
-    public boolean preloadVideo(String uuid, String url) {
-        File f = findLocalVideo(uuid);
-        if (f != null) {
-            updateLRU(uuid);
-            return true;
-        }
-        // Start background download, return immediately
-        downloadInBackground(uuid, url, null);
-        return true;
-    }
-
-    // ------------------------------------------------------------
-    // Core download (synchronous helper used by background task)
-    // ------------------------------------------------------------
-
-    /**
-     * Synchronously download url -> storageDir/uuid.<ext>.tmp then atomically rename to final file.
-     * Returns final File on success, null on failure.
-     *
-     * This is intended to be called off the main thread.
-     */
-    private File streamAndCacheVideoSync(String uuid, String urlString) {
-        String ext = getExtensionFromUrl(urlString);
-        File tmpFile = new File(storageDir, uuid + ext + ".tmp");
-        File outFile = new File(storageDir, uuid + ext);
-
-        HttpsURLConnection conn = null;
-        FileOutputStream fos = null;
-        InputStream input = null;
-
-        try {
-            // If final file already exists (race), return it
-            if (outFile.exists() && outFile.length() > 0) {
-                Log.i(TAG, "Final file already exists, skipping download: " + outFile.getAbsolutePath());
-                return outFile;
-            }
-
-            URL url = new URL(urlString);
-            conn = (HttpsURLConnection) url.openConnection();
-            conn.setConnectTimeout(15_000);
-            conn.setReadTimeout(30_000);
-            conn.connect();
-
-            int code = conn.getResponseCode();
-            if (code != HttpsURLConnection.HTTP_OK) {
-                throw new IOException("HTTP " + code);
-            }
-
-            input = new BufferedInputStream(conn.getInputStream());
-            fos = new FileOutputStream(tmpFile);
-
-            byte[] buffer = new byte[64 * 1024]; // 64KB
-            int read;
-            long total = 0L;
-            while ((read = input.read(buffer)) != -1) {
-                fos.write(buffer, 0, read);
-                total += read;
-            }
-            fos.getFD().sync();
-            fos.close();
-            fos = null;
-
-            // Optional sanity check: minimal file size
-            if (!tmpFile.exists() || tmpFile.length() == 0) {
-                throw new IOException("Downloaded file empty");
-            }
-
-            // Atomically rename tmp -> final
-            if (tmpFile.renameTo(outFile)) {
-                // Ensure lastModified is set to now (for LRU)
-                outFile.setLastModified(System.currentTimeMillis());
-                Log.i(TAG, "Download saved: " + outFile.getAbsolutePath() + " (" + total + " bytes)");
-                return outFile;
-            } else {
-                // Rename failed: attempt copy & delete fallback
-                Log.w(TAG, "renameTo failed; attempting copy fallback");
-                copyFile(tmpFile, outFile);
-                tmpFile.delete();
-                outFile.setLastModified(System.currentTimeMillis());
-                return outFile;
-            }
-        } catch (Exception e) {
-            Log.e(TAG, "streamAndCacheVideoSync error: " + e.getMessage());
-            // cleanup partial file
-            if (tmpFile.exists()) {
-                boolean deleted = tmpFile.delete();
-                if (!deleted) Log.w(TAG, "Failed to delete partial tmp file: " + tmpFile.getAbsolutePath());
-            }
-            return null;
-        } finally {
-            if (conn != null) conn.disconnect();
-            try {
-                if (fos != null) fos.close();
-            } catch (IOException ignored) {}
-            try {
-                if (input != null) input.close();
-            } catch (IOException ignored) {}
-        }
-    }
-
-    private void copyFile(File src, File dst) throws IOException {
-        try (FileInputStream fis = new FileInputStream(src);
-             FileOutputStream fos = new FileOutputStream(dst)) {
-            byte[] buf = new byte[64 * 1024];
-            int r;
-            while ((r = fis.read(buf)) != -1) {
-                fos.write(buf, 0, r);
-            }
-            fos.getFD().sync();
-        }
-    }
-
-    // ------------------------------------------------------------
-    // LRU & Cache management
-    // ------------------------------------------------------------
-
-    private void initializeLRU() {
-        File[] files = storageDir.listFiles();
-        if (files == null) return;
-
-        synchronized (lruLock) {
-            lruMap.clear();
-            for (File file : files) {
-                String name = file.getName();
-                if (!isVideoFilename(name)) continue;
-                String uuid = name.substring(0, name.lastIndexOf('.'));
-                lruMap.put(uuid, file.lastModified());
-            }
-        }
-    }
-
-    private void updateLRU(String uuid) {
-        long now = System.currentTimeMillis();
-        synchronized (lruLock) {
-            lruMap.put(uuid, now); // LinkedHashMap in access-order: put moves to tail
-        }
-        // Persist via file timestamp if file exists
-        File f = findLocalVideo(uuid);
-        if (f != null) {
-            f.setLastModified(now);
-        }
-    }
-
-    public void setMaxCacheSize(long bytes) {
-        this.maxCacheBytes = bytes;
-        enforceCacheLimit();
-    }
-
-    /**
-     * Evicts least-recently used files until cache <= maxCacheBytes.
-     * Note: synchronize when iterating lruMap
-     */
-    private void enforceCacheLimit() {
-        long total = calculateDirectorySize(storageDir);
-        Log.i(TAG, "Total directory size: " + total);
-
-
-        synchronized (lruLock) {
-            Iterator<Map.Entry<String, Long>> iterator = lruMap.entrySet().iterator();
-            while (total > maxCacheBytes && iterator.hasNext()) {
-                String uuid = iterator.next().getKey();
-                File f = findLocalVideo(uuid);
-                if (f != null) {
-                    long len = f.length();
-                    if (f.delete()) {
-                        total -= len;
-                        iterator.remove();
-                        Log.i(TAG, "Evicted video due to cache limit: " + uuid);
-                    } else {
-                        // Could not delete; remove from LRU to avoid infinite loop
-                        iterator.remove();
-                        Log.w(TAG, "Failed to delete file when evicting: " + f.getAbsolutePath());
-                    }
-                } else {
-                    iterator.remove(); // file missing; remove from LRU
-                }
-            }
-        }
-    }
-
-    // ------------------------------------------------------------
-    // Utilities & file ops
-    // ------------------------------------------------------------
-
-    private boolean isVideoFilename(String name) {
-        String lower = name.toLowerCase();
-        return lower.endsWith(".mp4") || lower.endsWith(".webm");
-    }
-
-    private File findLocalVideo(String uuid) {
-        if (uuid == null || uuid.isEmpty()) return null;
-        File mp4 = new File(storageDir, uuid + ".mp4");
-        if (mp4.exists()) return mp4;
-        File webm = new File(storageDir, uuid + ".webm");
-        if (webm.exists()) return webm;
-        return null;
-    }
-
-    public boolean evictVideos(JSONArray uuids) {
-        boolean allDeleted = true;
-        for (int i = 0; i < uuids.length(); i++) {
-            try {
-                String uuid = uuids.getString(i);
-                File f = findLocalVideo(uuid);
-                if (f != null && !f.delete()) allDeleted = false;
-                synchronized (lruLock) {
-                    lruMap.remove(uuid);
-                }
-            } catch (Exception e) {
-                allDeleted = false;
-            }
-        }
-        return allDeleted;
-    }
-
-    public JSArray listCachedVideos() {
-        JSArray arr = new JSArray();
-        File[] files = storageDir.listFiles();
-        if (files == null) return arr;
-
-        for (File f : files) {
-            String name = f.getName();
-            if (!isVideoFilename(name)) continue;
-            String uuid = name.substring(0, name.lastIndexOf('.'));
-            JSONObject obj = new JSONObject();
-            try {
-                obj.put("uuid", uuid);
-                obj.put("url", f.getAbsolutePath());
-                obj.put("size_bytes", f.length());
-                long lastAccessed;
-                synchronized (lruLock) {
-                    lastAccessed = lruMap.getOrDefault(uuid, f.lastModified());
-                }
-                obj.put("last_accessed", lastAccessed);
-                arr.put(obj);
-            } catch (Exception ignored) {}
-        }
-
-        return arr;
-    }
-
-    public JSObject getStorageStats() {
-        JSObject ret = new JSObject();
-        long availableBytes = context.getFilesDir().getUsableSpace();
-        long totalBytes = context.getFilesDir().getTotalSpace();
-        long usedBytesVideos = calculateDirectorySize(storageDir);
-        long usedBytesApp = calculateDirectorySize(context.getFilesDir());
-
-        ret.put("available_bytes", availableBytes);
-        ret.put("total_bytes", totalBytes);
-        ret.put("used_bytes_videos", usedBytesVideos);
-        ret.put("used_bytes_app", usedBytesApp);
-
-        return ret;
-    }
-
-    private long calculateDirectorySize(File dir) {
-        if (dir == null || !dir.exists()) return 0;
-        if (dir.isFile()) return dir.length();
-
-        long size = 0;
-        File[] files = dir.listFiles();
-        if (files != null) {
-            for (File f : files) {
-                size += calculateDirectorySize(f);
-            }
-        }
-        return size;
-    }
-
-    private String getExtensionFromUrl(String url) {
-        try {
-            String lower = url.toLowerCase();
-            if (lower.contains("?")) lower = lower.substring(0, lower.indexOf("?"));
-            if (lower.endsWith(".mp4")) return ".mp4";
-            if (lower.endsWith(".webm")) return ".webm";
-            return ".mp4";
-        } catch (Exception e) {
-            return ".mp4";
-        }
-    }
-
-    // Optional: call this to cancel an active background download
-    public boolean cancelDownload(String uuid) {
-        Future<?> f = activeDownloads.remove(uuid);
-        if (f != null) {
-            return f.cancel(true);
-        }
-        return false;
-    }
-
-    // Graceful shutdown (if needed)
-    public void shutdown() {
-        dlExecutor.shutdownNow();
-    }
-}
+package com.strtv.app;
+
+import android.content.Context;
+import android.util.Log;
+
+import com.getcapacitor.JSArray;
+import com.getcapacitor.JSObject;
+import com.getcapacitor.Logger;
+
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+import java.io.*;
+import java.net.URL;
+import java.util.*;
+import java.util.concurrent.*;
+import javax.net.ssl.HttpsURLConnection;
+
+/**
+ * STRTV - streaming + cache manager (Option 1 MVP)
+ *
+ * Behavior:
+ *  - getVideoFile(uuid, url): returns cached File if present (updates LRU). Does NOT download.
+ *  - downloadInBackground(uuid, url): downloads into a .tmp file -> rename to final, update LRU, enforce cache.
+ *
+ * Notes:
+ *  - Concurrent downloads for same uuid are deduplicated.
+ *  - LRU persisted via file lastModified timestamps and loaded on init.
+ */
+public class STRTV {
+
+    private static final String TAG = "STRTV";
+    private final Context context;
+    private final File storageDir;
+
+    // In-memory LRU map: uuid -> lastAccessedTime (access-order LinkedHashMap)
+    // Access to lruMap must be synchronized on lruLock.
+    private final LinkedHashMap<String, Long> lruMap = new LinkedHashMap<>(16, 0.75f, true);
+    private final Object lruLock = new Object();
+
+    private long maxCacheBytes = 1024L * 1024L * 1024L; // 1 GB default cache size
+
+
+
+    // Background download executor & tracking
+    private final ExecutorService dlExecutor = Executors.newFixedThreadPool(2);
+    private final ConcurrentHashMap<String, Future<?>> activeDownloads = new ConcurrentHashMap<>();
+
+    public STRTV(Context context) {
+        this.context = context;
+        this.storageDir = new File(context.getFilesDir(), "strtv_videos");
+
+        if (!storageDir.exists()) {
+            boolean ok = storageDir.mkdirs();
+            if (!ok) Log.w(TAG, "Failed to create storageDir: " + storageDir.getAbsolutePath());
+        }
+
+        // Populate LRU map from existing files (persisted lastModified)
+        initializeLRU();
+    }
+
+    public String echo(String value) {
+        Logger.info(TAG, value);
+        return value;
+    }
+
+    // ------------------------------------------------------------
+    // Public API used by plugin
+    // ------------------------------------------------------------
+
+    /**
+     * Returns cached file if present; otherwise returns null.
+     * DOES NOT attempt to download. Caller should call downloadInBackground(uuid, url) if needed.
+     */
+    public File getVideoFile(String uuid, String url) {
+        if (uuid == null || uuid.isEmpty()) return null;
+        File f = findLocalVideo(uuid);
+        if (f != null) {
+            updateLRU(uuid);
+            return f;
+        }
+        return null;
+    }
+
+    public interface VideoDownloadCallback {
+        void onDownloadComplete(File cachedFile);
+    }
+
+    /**
+     * Request a background download. Non-blocking.
+     * If a download for this uuid is already in progress, this is a no-op.
+     */
+    public void downloadInBackground(final String uuid, final String url, VideoDownloadCallback callback) {
+        if (uuid == null || url == null) {
+            Log.w(TAG, "downloadInBackground called with null uuid or url");
+            return;
+        }
+
+        // Deduplicate concurrent downloads
+        if (activeDownloads.containsKey(uuid)) {
+            Log.i(TAG, "Download already active for uuid=" + uuid);
+            return;
+        }
+
+        Future<?> future = dlExecutor.submit(() -> {
+            try {
+                Log.i(TAG, "Background download started: " + uuid + " -> " + url);
+                File downloaded = streamAndCacheVideoSync(uuid, url);
+                if (downloaded != null) {
+                    updateLRU(uuid);
+                    enforceCacheLimit();
+                    Log.i(TAG, "Background download finished: " + downloaded.getAbsolutePath());
+                     if (callback != null) {
+                        Log.i(TAG, "Calling download completion handler: ");
+                        callback.onDownloadComplete(downloaded);
+                    }
+                } else {
+                    Log.w(TAG, "Background download returned null for uuid=" + uuid);
+                }
+            } catch (Exception e) {
+                Log.e(TAG, "Background download failed for uuid=" + uuid + " : " + e.getMessage());
+                // ensure partial file cleanup handled in streamAndCacheVideoSync
+            } finally {
+                activeDownloads.remove(uuid);
+            }
+        });
+
+        // track active download
+        activeDownloads.put(uuid, future);
+    }
+
+    /**
+     * Preload syncronously or asynchronously? We choose to kick off background download and return quickly.
+     */
+    public boolean preloadVideo(String uuid, String url) {
+        File f = findLocalVideo(uuid);
+        if (f != null) {
+            updateLRU(uuid);
+            return true;
+        }
+        // Start background download, return immediately
+        downloadInBackground(uuid, url, null);
+        return true;
+    }
+
+    // ------------------------------------------------------------
+    // Core download (synchronous helper used by background task)
+    // ------------------------------------------------------------
+
+    /**
+     * Synchronously download url -> storageDir/uuid.<ext>.tmp then atomically rename to final file.
+     * Returns final File on success, null on failure.
+     *
+     * This is intended to be called off the main thread.
+     */
+    private File streamAndCacheVideoSync(String uuid, String urlString) {
+        String ext = getExtensionFromUrl(urlString);
+        File tmpFile = new File(storageDir, uuid + ext + ".tmp");
+        File outFile = new File(storageDir, uuid + ext);
+
+        HttpsURLConnection conn = null;
+        FileOutputStream fos = null;
+        InputStream input = null;
+
+        try {
+            // If final file already exists (race), return it
+            if (outFile.exists() && outFile.length() > 0) {
+                Log.i(TAG, "Final file already exists, skipping download: " + outFile.getAbsolutePath());
+                return outFile;
+            }
+
+            URL url = new URL(urlString);
+            conn = (HttpsURLConnection) url.openConnection();
+            conn.setConnectTimeout(15_000);
+            conn.setReadTimeout(30_000);
+            conn.connect();
+
+            int code = conn.getResponseCode();
+            if (code != HttpsURLConnection.HTTP_OK) {
+                throw new IOException("HTTP " + code);
+            }
+
+            input = new BufferedInputStream(conn.getInputStream());
+            fos = new FileOutputStream(tmpFile);
+
+            byte[] buffer = new byte[64 * 1024]; // 64KB
+            int read;
+            long total = 0L;
+            while ((read = input.read(buffer)) != -1) {
+                fos.write(buffer, 0, read);
+                total += read;
+            }
+            fos.getFD().sync();
+            fos.close();
+            fos = null;
+
+            // Optional sanity check: minimal file size
+            if (!tmpFile.exists() || tmpFile.length() == 0) {
+                throw new IOException("Downloaded file empty");
+            }
+
+            // Atomically rename tmp -> final
+            if (tmpFile.renameTo(outFile)) {
+                // Ensure lastModified is set to now (for LRU)
+                outFile.setLastModified(System.currentTimeMillis());
+                Log.i(TAG, "Download saved: " + outFile.getAbsolutePath() + " (" + total + " bytes)");
+                return outFile;
+            } else {
+                // Rename failed: attempt copy & delete fallback
+                Log.w(TAG, "renameTo failed; attempting copy fallback");
+                copyFile(tmpFile, outFile);
+                tmpFile.delete();
+                outFile.setLastModified(System.currentTimeMillis());
+                return outFile;
+            }
+        } catch (Exception e) {
+            Log.e(TAG, "streamAndCacheVideoSync error: " + e.getMessage());
+            // cleanup partial file
+            if (tmpFile.exists()) {
+                boolean deleted = tmpFile.delete();
+                if (!deleted) Log.w(TAG, "Failed to delete partial tmp file: " + tmpFile.getAbsolutePath());
+            }
+            return null;
+        } finally {
+            if (conn != null) conn.disconnect();
+            try {
+                if (fos != null) fos.close();
+            } catch (IOException ignored) {}
+            try {
+                if (input != null) input.close();
+            } catch (IOException ignored) {}
+        }
+    }
+
+    private void copyFile(File src, File dst) throws IOException {
+        try (FileInputStream fis = new FileInputStream(src);
+             FileOutputStream fos = new FileOutputStream(dst)) {
+            byte[] buf = new byte[64 * 1024];
+            int r;
+            while ((r = fis.read(buf)) != -1) {
+                fos.write(buf, 0, r);
+            }
+            fos.getFD().sync();
+        }
+    }
+
+    // ------------------------------------------------------------
+    // LRU & Cache management
+    // ------------------------------------------------------------
+
+    private void initializeLRU() {
+        File[] files = storageDir.listFiles();
+        if (files == null) return;
+
+        synchronized (lruLock) {
+            lruMap.clear();
+            for (File file : files) {
+                String name = file.getName();
+                if (!isVideoFilename(name)) continue;
+                String uuid = name.substring(0, name.lastIndexOf('.'));
+                lruMap.put(uuid, file.lastModified());
+            }
+        }
+    }
+
+    private void updateLRU(String uuid) {
+        long now = System.currentTimeMillis();
+        synchronized (lruLock) {
+            lruMap.put(uuid, now); // LinkedHashMap in access-order: put moves to tail
+        }
+        // Persist via file timestamp if file exists
+        File f = findLocalVideo(uuid);
+        if (f != null) {
+            f.setLastModified(now);
+        }
+    }
+
+    public void setMaxCacheSize(long bytes) {
+        this.maxCacheBytes = bytes;
+        enforceCacheLimit();
+    }
+
+    /**
+     * Evicts least-recently used files until cache <= maxCacheBytes.
+     * Note: synchronize when iterating lruMap
+     */
+    private void enforceCacheLimit() {
+        long total = calculateDirectorySize(storageDir);
+        Log.i(TAG, "Total directory size: " + total);
+
+
+        synchronized (lruLock) {
+            Iterator<Map.Entry<String, Long>> iterator = lruMap.entrySet().iterator();
+            while (total > maxCacheBytes && iterator.hasNext()) {
+                String uuid = iterator.next().getKey();
+                File f = findLocalVideo(uuid);
+                if (f != null) {
+                    long len = f.length();
+                    if (f.delete()) {
+                        total -= len;
+                        iterator.remove();
+                        Log.i(TAG, "Evicted video due to cache limit: " + uuid);
+                    } else {
+                        // Could not delete; remove from LRU to avoid infinite loop
+                        iterator.remove();
+                        Log.w(TAG, "Failed to delete file when evicting: " + f.getAbsolutePath());
+                    }
+                } else {
+                    iterator.remove(); // file missing; remove from LRU
+                }
+            }
+        }
+    }
+
+    // ------------------------------------------------------------
+    // Utilities & file ops
+    // ------------------------------------------------------------
+
+    private boolean isVideoFilename(String name) {
+        String lower = name.toLowerCase();
+        return lower.endsWith(".mp4") || lower.endsWith(".webm");
+    }
+
+    private File findLocalVideo(String uuid) {
+        if (uuid == null || uuid.isEmpty()) return null;
+        File mp4 = new File(storageDir, uuid + ".mp4");
+        if (mp4.exists()) return mp4;
+        File webm = new File(storageDir, uuid + ".webm");
+        if (webm.exists()) return webm;
+        return null;
+    }
+
+    public boolean evictVideos(JSONArray uuids) {
+        boolean allDeleted = true;
+        for (int i = 0; i < uuids.length(); i++) {
+            try {
+                String uuid = uuids.getString(i);
+                File f = findLocalVideo(uuid);
+                if (f != null && !f.delete()) allDeleted = false;
+                synchronized (lruLock) {
+                    lruMap.remove(uuid);
+                }
+            } catch (Exception e) {
+                allDeleted = false;
+            }
+        }
+        return allDeleted;
+    }
+
+    public JSArray listCachedVideos() {
+        JSArray arr = new JSArray();
+        File[] files = storageDir.listFiles();
+        if (files == null) return arr;
+
+        for (File f : files) {
+            String name = f.getName();
+            if (!isVideoFilename(name)) continue;
+            String uuid = name.substring(0, name.lastIndexOf('.'));
+            JSONObject obj = new JSONObject();
+            try {
+                obj.put("uuid", uuid);
+                obj.put("url", f.getAbsolutePath());
+                obj.put("size_bytes", f.length());
+                long lastAccessed;
+                synchronized (lruLock) {
+                    lastAccessed = lruMap.getOrDefault(uuid, f.lastModified());
+                }
+                obj.put("last_accessed", lastAccessed);
+                arr.put(obj);
+            } catch (Exception ignored) {}
+        }
+
+        return arr;
+    }
+
+    public JSObject getStorageStats() {
+        JSObject ret = new JSObject();
+        long availableBytes = context.getFilesDir().getUsableSpace();
+        long totalBytes = context.getFilesDir().getTotalSpace();
+        long usedBytesVideos = calculateDirectorySize(storageDir);
+        long usedBytesApp = calculateDirectorySize(context.getFilesDir());
+
+        ret.put("available_bytes", availableBytes);
+        ret.put("total_bytes", totalBytes);
+        ret.put("used_bytes_videos", usedBytesVideos);
+        ret.put("used_bytes_app", usedBytesApp);
+
+        return ret;
+    }
+
+    private long calculateDirectorySize(File dir) {
+        if (dir == null || !dir.exists()) return 0;
+        if (dir.isFile()) return dir.length();
+
+        long size = 0;
+        File[] files = dir.listFiles();
+        if (files != null) {
+            for (File f : files) {
+                size += calculateDirectorySize(f);
+            }
+        }
+        return size;
+    }
+
+    private String getExtensionFromUrl(String url) {
+        try {
+            String lower = url.toLowerCase();
+            if (lower.contains("?")) lower = lower.substring(0, lower.indexOf("?"));
+            if (lower.endsWith(".mp4")) return ".mp4";
+            if (lower.endsWith(".webm")) return ".webm";
+            return ".mp4";
+        } catch (Exception e) {
+            return ".mp4";
+        }
+    }
+
+    // Optional: call this to cancel an active background download
+    public boolean cancelDownload(String uuid) {
+        Future<?> f = activeDownloads.remove(uuid);
+        if (f != null) {
+            return f.cancel(true);
+        }
+        return false;
+    }
+
+    // Graceful shutdown (if needed)
+    public void shutdown() {
+        dlExecutor.shutdownNow();
+    }
+}