react-native-hls-cache

HLS segment caching for React Native via a local TCP proxy server.

| Platform | Support | |----------|---------| | iOS | Full proxy — manifests + segments cached to disk | | Android | No-op — ExoPlayer/Media3 handles caching natively |

Powered by Nitro Modules for zero-overhead FFI.

Installation

npm install react-native-hls-cache react-native-nitro-modules

Bare React Native

cd ios && pod install

Expo

expo prebuild regenerates ios/Podfile from scratch, wiping manual edits. Use the config plugin to inject the Cache pod automatically:

// app.json
{
  "expo": {
    "plugins": ["react-native-hls-cache"]
  }
}

How it works

AVPlayer
  → http://127.0.0.1:9000/proxy?url=<encoded>
  → Local proxy (NWListener)
      ├── Cache hit  → serve from disk instantly
      └── Cache miss → fetch from origin, stream to player + write to disk

All HLS manifest URLs are rewritten to route through the proxy. Subsequent plays of the same video are served entirely from disk — zero network traffic.

Quick start

import { useEffect } from 'react';
import { startServer, convertUrl, precacheBatch, cancelPrecache } from 'react-native-hls-cache';
import Video from 'react-native-video';

// 1. Start the proxy once on app mount
useEffect(() => {
  startServer(9000, 1_073_741_824, false, (e) => {
    if (e.type === 'ready') console.log('Proxy ready on port 9000');
  });
}, []);

// 2. Warm upcoming videos before the user scrolls to them
useEffect(() => {
  const sessionId = precacheBatch(upcomingUrls, 3);
  return () => cancelPrecache(sessionId);
}, [upcomingUrls]);

// 3. Route playback through the proxy
const url = convertUrl('https://cdn.example.com/video.m3u8');
<Video source={{ uri: url }} />;

API

startServer(port?, maxCacheSize?, headOnlyCache?, onCacheEvent?)

Starts the local proxy server. Call once on app mount.

startServer(
  9000,            // port (default: 9000)
  1_073_741_824,   // max disk cache in bytes (default: 1 GB)
  false,           // headOnlyCache: only cache the first 3 segments (default: false)
  (event) => {
    // event.type: 'ready' | 'hit' | 'miss' | 'download' | 'error'
    // event.url:   origin URL (empty when not applicable)
    // event.bytes: bytes transferred (0 when not applicable)
    // event.error: error message (empty when not applicable)
    console.log(event);
  }
);

headOnlyCache is optimised for vertical video feeds — it caches just enough to ensure the first play is fast without filling disk on content the user might never finish watching.

convertUrl(url, isCacheable?)

Rewrites a remote HLS URL to route through the proxy. Returns the original URL unchanged on Android or when the server is not running.

const proxyUrl = convertUrl('https://cdn.example.com/video.m3u8');
// → "http://127.0.0.1:9000/proxy?url=https%3A%2F%2Fcdn..."

// Bypass the proxy for a specific video:
const directUrl = convertUrl(url, false);

Pass proxyUrl to your video player instead of the original URL.

clearCache()

Deletes all cached files from disk.

await clearCache();

precache(url, segmentCount?)

Downloads the manifest and first N segments of a stream to disk before the user presses play. Subsequent playback will be instant cache hits.

// Cache the first 5 segments (≈ first 30s at 6s/segment)
await precache('https://cdn.example.com/video.m3u8', 5);

// Cache the entire stream:
await precache('https://cdn.example.com/video.m3u8', 0);

precacheBatch(urls, segmentCount?)

Concurrently precaches multiple streams. Returns a session ID for cancellation.

const sessionId = precacheBatch(
  ['https://cdn.example.com/v1.m3u8', 'https://cdn.example.com/v2.m3u8'],
  3 // segments per stream (default: 3)
);

// Cancel all in-flight downloads (e.g. user navigates away):
cancelPrecache(sessionId);

cancelPrecache(sessionId)

Cancels all in-flight downloads for a session returned by precacheBatch.

cancelPrecache(sessionId);

getVariants(url)

Fetches an HLS master playlist and returns all variant renditions sorted by bandwidth (lowest → highest). Useful for picking which quality to precache.

const variants = await getVariants('https://cdn.example.com/master.m3u8');
// [
//   { url, bandwidth: 365811,  resolution: '270x480',  codecs: '...', frameRate: 30 },
//   { url, bandwidth: 613626,  resolution: '480x854',  ... },
//   { url, bandwidth: 1096138, resolution: '720x1280', ... },
// ]

// Precache only the lowest quality:
await precache(variants[0]!.url, 5);

Returns [] if the URL is a media playlist (no #EXT-X-STREAM-INF) or if the fetch fails.

Cache behaviour

| Detail | Value | |--------|-------| | Storage location | ~/Library/Caches/HLSVideoCache/ | | Cache key | SHA-256 of URL (+ byte range for fMP4 segments) | | Eviction | LRU — oldest files pruned on each write until under maxCacheSize | | Manifest rewriting | EXT-X-MAP, EXT-X-MEDIA, EXT-X-PART, EXT-X-PRELOAD-HINT URIs all rewritten to proxy URLs | | Range requests | Supported — fMP4 byte-range requests cached per range, with fallback slice from full cached file |

License

MIT