Look-ahead cache

Proactively prefetches upcoming streamed tracks to disk so they start instantly and survive brief network drops. It applies to http(s):// sources only — file:// (local) tracks are already on disk and are skipped.

Methods live on the TrackPlayer singleton:

import { getTrackPlayer } from 'react-native-queue-player';

const player = getTrackPlayer();

// Disk budget + eviction policy are configure-time (fixed at cache
// construction), not runtime controls. Set them once at app init alongside your
// other config; changing either later means calling configure() again (a full
// player reinit) with your complete config.
await player.configure({
  // ...your other PlayerConfig (httpHeaders, userAgent, ...)
  lookaheadCacheMaxSizeMb: 200,          // disk budget; default 100 MB
  lookaheadCacheEvictionPolicy: 'lru',   // 'lru' (default) or 'fifo'
});

// Runtime controls: enable/disable + how many tracks to prefetch. These apply
// live, no configure() cycle needed.
await player.setLookaheadCache({
  enabled: true,
  lookaheadCount: 3,     // prefetch the next N tracks
});

Methods

setLookaheadCache(config: LookaheadCacheConfig): Promise<void>
getLookaheadCacheStatus(): CacheStatus
clearLookaheadCache(): Promise<void>   // wipes + stops; does not auto-restart prefetch
onCacheStatusChange(callback: (status: CacheStatus) => void): () => void

Types

type LookaheadCacheConfig = {
  enabled: boolean;
  lookaheadCount: number;   // prefetch the next N tracks
};

// Disk budget + eviction policy live on PlayerConfig (configure-time only):
//   configure({ lookaheadCacheMaxSizeMb?: number,
//               lookaheadCacheEvictionPolicy?: 'lru' | 'fifo' })
// Both are fixed at cache construction (Android's SimpleCache can't resize or
// swap its evictor live); read the active ceiling back from CacheStatus.maxSizeMb.
//
// Eviction policy — default 'lru'. Changing it clears the cache and rebuilds:
//   'lru'  evicts the least-recently-used track first (recently played tracks
//          are kept).
//   'fifo' evicts the oldest-fetched track first, regardless of replays
//          ("keep the newest-fetched"); suits a forward-only prefetch queue.

type CacheStatus = {
  enabled: boolean;
  currentSizeMb: number;      // current disk usage
  maxSizeMb: number;          // the configured budget
  tracksFullyCached: number;  // total tracks fully downloaded on disk
  currentlyCaching: string[]; // URLs downloading right now
};

In React, see useLookaheadCache.