react-native-hls-cache 0.1.0

package/HlsCache.podspec

@@ -0,0 +1,29 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "HlsCache"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = package["homepage"]
+  s.license      = package["license"]
+  s.authors      = package["author"]
+
+  s.platforms    = { :ios => min_ios_version_supported }
+  s.source       = { :git => "https://github.com/chanphiromsok/react-native-hls-cache.git", :tag => "#{s.version}" }
+
+  s.source_files = [
+    "ios/**/*.{swift}",
+    "ios/**/*.{m,mm}",
+    "cpp/**/*.{hpp,cpp}",
+  ]
+
+  s.dependency 'React-jsi'
+  s.dependency 'React-callinvoker'
+
+  load 'nitrogen/generated/ios/HlsCache+autolinking.rb'
+  add_nitrogen_files(s)
+
+  install_modules_dependencies(s)
+end

package/LICENSE

@@ -0,0 +1,20 @@
+MIT License
+
+Copyright (c) 2026 Rom
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,233 @@
+# react-native-hls-cache
+
+HLS video caching for React Native — intercepts segment requests via a local TCP proxy, caches them to disk, and serves subsequent playback from cache.
+
+- **iOS** — full proxy implementation (Swift, Network framework)
+- **Android** — no-op; ExoPlayer/Media3 handle caching natively
+- **Bridge** — [Nitro Modules](https://nitro.margelo.com/) (type-safe FFI)
+
+---
+
+## Installation
+
+```sh
+npm install react-native-hls-cache react-native-nitro-modules
+# or
+yarn add react-native-hls-cache react-native-nitro-modules
+```
+
+> `react-native-nitro-modules` is a required peer dependency.
+
+---
+
+## Quick Start
+
+```tsx
+import { startServer, convertUrl } from 'react-native-hls-cache';
+import { useVideoPlayer, VideoView } from 'expo-video';
+import { useEffect } from 'react';
+
+export default function App() {
+  useEffect(() => {
+    // Start the proxy once on app launch
+    startServer();
+  }, []);
+
+  const remoteUrl = 'https://stream.mux.com/abc123.m3u8';
+
+  const player = useVideoPlayer(
+    convertUrl(remoteUrl), // rewrites to http://127.0.0.1:9000/proxy?url=...
+    (p) => { p.loop = true; }
+  );
+
+  return <VideoView player={player} style={{ flex: 1 }} />;
+}
+```
+
+---
+
+## API
+
+### `startServer(port?, maxCacheSize?, headOnlyCache?)`
+
+Starts the local HLS proxy server. Call once on app mount.
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `port` | `number` | `9000` | Local TCP port to bind |
+| `maxCacheSize` | `number` | `1073741824` | Max disk cache in bytes (1 GB) |
+| `headOnlyCache` | `boolean` | `false` | Only cache the first 3 segments per stream. Recommended for vertical video feeds |
+
+```ts
+startServer();                          // defaults
+startServer(9000, 512 * 1024 * 1024);  // 512 MB cache
+startServer(9000, undefined, true);     // head-only mode for feeds
+```
+
+- Synchronous and fast (< 1ms) — does not block the JS thread
+- Safe to call multiple times; no-op if already running on the same port
+- Throws with code `409` if a server is already running on a different port
+- No-op on Android / Web
+
+---
+
+### `convertUrl(url, isCacheable?)`
+
+Rewrites a remote HLS URL to route through the local proxy.
+
+```ts
+const localUrl = convertUrl('https://cdn.example.com/video.m3u8');
+// → 'http://127.0.0.1:9000/proxy?url=https%3A%2F%2Fcdn.example.com%2Fvideo.m3u8'
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | — | Remote HLS URL |
+| `isCacheable` | `boolean` | `true` | Pass `false` to bypass the proxy and return the original URL |
+
+- Returns the original URL unchanged on Android / Web, or if the server is not running
+- Synchronous — safe to call inline during render
+
+---
+
+### `clearCache()`
+
+Deletes all cached files from disk.
+
+```ts
+await clearCache();
+```
+
+- Runs on a background thread — does not block the JS thread
+- No-op on Android / Web
+
+---
+
+### `prefetch(url, segmentCount?)`
+
+Downloads an HLS stream into cache before the user plays it. Returns a `taskId` for cancellation.
+
+```ts
+const taskId = prefetch('https://cdn.example.com/video.m3u8');
+const taskId = prefetch('https://cdn.example.com/video.m3u8', 5); // cache 5 segments
+```
+
+| Parameter | Type | Default | Description |
+|---|---|---|---|
+| `url` | `string` | — | Remote HLS URL |
+| `segmentCount` | `number` | `3` | Number of segments to prefetch |
+
+**What it does:**
+1. Downloads the master playlist
+2. Picks the lowest-bandwidth media playlist (lightweight for background work)
+3. Downloads the first `segmentCount` segments into the disk cache
+4. When the player requests those segments via the proxy → instant cache hit
+
+- Returns immediately — all work happens in the background
+- Returns `''` on Android / Web (no-op)
+
+---
+
+### `cancelPrefetch(taskId)`
+
+Cancels a specific prefetch task.
+
+```ts
+const taskId = prefetch(url);
+// later...
+cancelPrefetch(taskId);
+```
+
+---
+
+### `cancelAllPrefetch()`
+
+Cancels all active prefetch tasks.
+
+```ts
+cancelAllPrefetch();
+```
+
+---
+
+## Patterns
+
+### Vertical video feed (TikTok-style)
+
+```tsx
+import { startServer, convertUrl, prefetch, cancelAllPrefetch } from 'react-native-hls-cache';
+
+// App.tsx — start with head-only cache to minimise storage on feeds
+useEffect(() => {
+  startServer(9000, 512 * 1024 * 1024, true);
+  return () => cancelAllPrefetch();
+}, []);
+
+// VideoItem.tsx — prefetch the next video as the user scrolls
+useEffect(() => {
+  if (shouldPreload) {
+    const taskId = prefetch(videoUrl);
+    return () => cancelPrefetch(taskId);
+  }
+}, [shouldPreload, videoUrl]);
+
+const player = useVideoPlayer(convertUrl(videoUrl), (p) => {
+  p.loop = true;
+});
+```
+
+### Selective caching
+
+```ts
+// Skip cache for live streams or DRM content
+const url = convertUrl(streamUrl, !isLive && !isDRM);
+```
+
+### Clear cache on logout
+
+```ts
+async function onLogout() {
+  cancelAllPrefetch();
+  await clearCache();
+}
+```
+
+---
+
+## How It Works
+
+```
+Media Player
+  → HTTP request to localhost:9000/proxy?url=<encoded>
+  → VideoProxyServer (NWListener, TCP)
+  → ClientConnectionHandler (per-connection HTTP handler)
+  → DataSource (cache-first router)
+      ├── Cache hit  → memory-mapped read from disk → instant response
+      └── Cache miss → NetworkDownloader (priority queue, 32 concurrent)
+                           → stream to player + write to disk simultaneously
+```
+
+**Cache storage** — files are keyed by SHA256 hash of the URL (+ byte range for fMP4 segments), stored in the system Caches directory under `ExpoVideoCache/`. LRU eviction runs 5 seconds after server start.
+
+**Manifest rewriting** — `.m3u8` responses are intercepted and all segment URLs are rewritten to route through the proxy, so every subsequent segment request is also cacheable.
+
+**Priority queue** — `.m3u8` manifests and small requests bypass the concurrency semaphore for instant playback startup. Heavy segment downloads are queued with a limit of 32 concurrent connections.
+
+---
+
+## Requirements
+
+- React Native 0.73+
+- iOS 15.1+
+- Android — no native requirements (no-op)
+
+---
+
+## Contributing
+
+- [Development workflow](CONTRIBUTING.md#development-workflow)
+- [Sending a pull request](CONTRIBUTING.md#sending-a-pull-request)
+
+## License
+
+MIT

package/android/CMakeLists.txt

@@ -0,0 +1,24 @@
+project(hlscache)
+cmake_minimum_required(VERSION 3.9.0)
+
+set(PACKAGE_NAME hlscache)
+set(CMAKE_VERBOSE_MAKEFILE ON)
+set(CMAKE_CXX_STANDARD 20)
+
+# Define C++ library and add all sources
+add_library(${PACKAGE_NAME} SHARED src/main/cpp/cpp-adapter.cpp)
+
+# Add Nitrogen specs :)
+include(${CMAKE_SOURCE_DIR}/../nitrogen/generated/android/hlscache+autolinking.cmake)
+
+# Set up local includes
+include_directories("src/main/cpp" "../cpp")
+
+find_library(LOG_LIB log)
+
+# Link all libraries together
+target_link_libraries(
+        ${PACKAGE_NAME}
+        ${LOG_LIB}
+        android # <-- Android core
+)

package/android/build.gradle

@@ -0,0 +1,118 @@
+buildscript {
+  ext.HlsCache = [
+    kotlinVersion: "2.0.21",
+    minSdkVersion: 24,
+    compileSdkVersion: 36,
+    targetSdkVersion: 36
+  ]
+
+  ext.getExtOrDefault = { prop ->
+    if (rootProject.ext.has(prop)) {
+      return rootProject.ext.get(prop)
+    }
+
+    return HlsCache[prop]
+  }
+
+  repositories {
+    google()
+    mavenCentral()
+  }
+
+  dependencies {
+    classpath "com.android.tools.build:gradle:8.7.2"
+    // noinspection DifferentKotlinGradleVersion
+    classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:${getExtOrDefault('kotlinVersion')}"
+  }
+}
+
+def reactNativeArchitectures() {
+  def value = rootProject.getProperties().get("reactNativeArchitectures")
+  return value ? value.split(",") : ["armeabi-v7a", "x86", "x86_64", "arm64-v8a"]
+}
+
+apply plugin: "com.android.library"
+apply plugin: "kotlin-android"
+apply from: '../nitrogen/generated/android/hlscache+autolinking.gradle'
+
+apply plugin: "com.facebook.react"
+
+android {
+  namespace "com.margelo.nitro.hlscache"
+
+  compileSdkVersion getExtOrDefault("compileSdkVersion")
+
+  defaultConfig {
+    minSdkVersion getExtOrDefault("minSdkVersion")
+    targetSdkVersion getExtOrDefault("targetSdkVersion")
+
+    externalNativeBuild {
+      cmake {
+        cppFlags "-frtti -fexceptions -Wall -fstack-protector-all"
+        arguments "-DANDROID_STL=c++_shared", "-DANDROID_SUPPORT_FLEXIBLE_PAGE_SIZES=ON"
+        abiFilters (*reactNativeArchitectures())
+
+        buildTypes {
+          debug {
+            cppFlags "-O1 -g"
+          }
+          release {
+            cppFlags "-O2"
+          }
+        }
+      }
+    }
+  }
+
+  externalNativeBuild {
+    cmake {
+      path "CMakeLists.txt"
+    }
+  }
+
+  packagingOptions {
+    excludes = [
+      "META-INF",
+      "META-INF/**",
+      "**/libc++_shared.so",
+      "**/libfbjni.so",
+      "**/libjsi.so",
+      "**/libfolly_json.so",
+      "**/libfolly_runtime.so",
+      "**/libglog.so",
+      "**/libhermes.so",
+      "**/libhermes-executor-debug.so",
+      "**/libhermes_executor.so",
+      "**/libreactnative.so",
+      "**/libreactnativejni.so",
+      "**/libturbomodulejsijni.so",
+      "**/libreact_nativemodule_core.so",
+      "**/libjscexecutor.so"
+    ]
+  }
+
+  buildFeatures {
+    buildConfig true
+    prefab true
+  }
+
+  buildTypes {
+    release {
+      minifyEnabled false
+    }
+  }
+
+  lint {
+    disable "GradleCompatible"
+  }
+
+  compileOptions {
+    sourceCompatibility JavaVersion.VERSION_1_8
+    targetCompatibility JavaVersion.VERSION_1_8
+  }
+}
+
+dependencies {
+  implementation "com.facebook.react:react-android"
+  implementation project(":react-native-nitro-modules")
+}

package/android/src/main/AndroidManifest.xml

@@ -0,0 +1,2 @@
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+</manifest>

package/android/src/main/cpp/cpp-adapter.cpp

@@ -0,0 +1,6 @@
+#include <jni.h>
+#include "hlscacheOnLoad.hpp"
+
+JNIEXPORT jint JNICALL JNI_OnLoad(JavaVM* vm, void*) {
+  return margelo::nitro::hlscache::initialize(vm);
+}

package/android/src/main/java/com/margelo/nitro/hlscache/HlsCache.kt

@@ -0,0 +1,32 @@
+package com.margelo.nitro.hlscache
+
+import androidx.annotation.Keep
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.core.Promise
+
+@DoNotStrip
+@Keep
+class HlsCache : HybridHlsCacheSpec() {
+
+    // Android uses ExoPlayer/Media3 native caching — no proxy needed.
+
+    override fun startServer(port: Double?, maxCacheSize: Double?, headOnlyCache: Boolean?): Unit {
+        // no-op: Android uses ExoPlayer/Media3 native caching
+    }
+
+    override fun convertUrl(url: String, isCacheable: Boolean?): String {
+        return url
+    }
+
+    override fun clearCache(): Promise<Unit> {
+        return Promise.resolved(Unit)
+    }
+
+    override fun prefetch(url: String, segmentCount: Double?): String {
+        return ""
+    }
+
+    override fun cancelPrefetch(taskId: String): Unit {}
+
+    override fun cancelAllPrefetch(): Unit {}
+}

package/android/src/main/java/com/margelo/nitro/hlscache/HlsCachePackage.kt

@@ -0,0 +1,22 @@
+package com.margelo.nitro.hlscache
+
+import com.facebook.react.BaseReactPackage
+import com.facebook.react.bridge.NativeModule
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.module.model.ReactModuleInfoProvider
+
+class HlsCachePackage : BaseReactPackage() {
+    override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? {
+        return null
+    }
+
+    override fun getReactModuleInfoProvider(): ReactModuleInfoProvider {
+        return ReactModuleInfoProvider { HashMap() }
+    }
+
+    companion object {
+        init {
+            System.loadLibrary("hlscache")
+        }
+    }
+}