Class AudioCache

AudioCache provides efficient caching of audio resources using HTTP caching standards.

Features:

  • Three-layer caching: Memory (LRU) → Browser Cache API → Network
  • HTTP conditional requests with ETag and Last-Modified support
  • Robust error handling with cache inconsistency recovery

Caching Strategy:

  • Always makes conditional requests when validation tokens (ETag/Last-Modified) are available
  • Uses TTL as fallback only when no validation tokens exist
  • Conditional requests are lightweight (304 responses have no body)

Example

const cache = new AudioCache();
const audioBuffer = await cache.getAudioBuffer(audioContext, 'audio.mp3');

// Optional: Configure TTL for when no validation tokens exist
AudioCache.setCacheExpirationTime(60 * 60 * 1000); // 1 hour

Implements

  • ICache

Constructors

constructor

Properties

cacheExpirationTime decodedBuffers pendingCallbacks pendingRequests

Methods

clearMemoryCache getAudioBuffer callAllCallbacks collectStreamToArrayBuffer createProgressTrackingStream decodeAudioData fetchAndCacheBuffer getBufferFromCache getMetadataFromCache getOrCreatePendingRequest openCache setCacheExpirationTime updateMetadata writeBufferAndMetadata

Constructors

constructor

Properties

Static Private cacheExpirationTime

cacheExpirationTime: number = ...

Static Private decodedBuffers

decodedBuffers: ByteBoundedLRUCache<string, AudioBuffer> = ...

Static Private pendingCallbacks

pendingCallbacks: Map<string, Pick<CacheCallbacks, "onLoadingProgress">[]> = ...

Static Private pendingRequests

pendingRequests: Map<string, Promise<AudioBuffer>> = ...

Methods

clearMemoryCache

  • clearMemoryCache(): void

  • Returns void

getAudioBuffer

  • getAudioBuffer(context, url, signal?, callbacks?): Promise<AudioBuffer>

  • Get an AudioBuffer for the specified URL, using intelligent caching strategies.

    Caching Flow:

    1. Check memory cache (LRU) for decoded AudioBuffer
    2. Check persistent cache for raw ArrayBuffer and metadata
    3. Make conditional HTTP request if validation tokens available
    4. Decode audio data and cache at all levels

    The cache prioritizes HTTP conditional requests (ETag/Last-Modified) over TTL to ensure content freshness while maintaining performance through 304 responses.

    Parameters

    • context: BaseContext

      AudioContext for decoding audio data

    • url: string

      URL of the audio resource to fetch

    • Optional signal: AbortSignal

      Optional AbortSignal to cancel the operation

    • Optional callbacks: CacheCallbacks

    Returns Promise<AudioBuffer>

    Promise that resolves to decoded AudioBuffer

    Throws

    Error if audio cannot be fetched or decoded

Static Private callAllCallbacks

  • callAllCallbacks<K>(url, callbackName, eventData): void

  • Calls all registered callbacks for a specific event type on a URL. Generic over the callback name so the payload type is checked against the canonical CacheCallbacks shape rather than any.

    Type Parameters

    • K extends "onLoadingStart" | "onLoadingProgress" | "onLoadingComplete" | "onLoadingError" | "onCacheHit" | "onCacheMiss" | "onCacheError"

    Parameters

    • url: string
    • callbackName: K
    • eventData: Parameters<NonNullable<CacheCallbacks[K]>>[0]

    Returns void

Static Private collectStreamToArrayBuffer

  • collectStreamToArrayBuffer(stream, knownLength?): Promise<ArrayBuffer>

  • Collects all chunks from a ReadableStream into a single ArrayBuffer

    Parameters

    • stream: ReadableStream<Uint8Array>

      The ReadableStream to collect from

    • Optional knownLength: number

    Returns Promise<ArrayBuffer>

    Promise that resolves to the complete ArrayBuffer

Static Private createProgressTrackingStream

  • createProgressTrackingStream(response, url, signal?): {
        stream: ReadableStream<Uint8Array>;
        total: null | number;
    }

  • Creates a ReadableStream wrapper that tracks download progress. Uses the callback aggregation system to emit progress to all registered listeners. Honours signal between reads and releases the underlying reader on any exit path (done, error, abort).

    Parameters

    • response: Response

      The fetch Response object with ReadableStream body

    • url: string

      URL being downloaded (for progress event data and callback lookup)

    • Optional signal: AbortSignal

      Optional AbortSignal observed at chunk boundaries

    Returns {
        stream: ReadableStream<Uint8Array>;
        total: null | number;
    }

    Object containing the progress-tracking stream and total size

    • stream: ReadableStream<Uint8Array>
    • total: null | number

Static Private decodeAudioData

  • decodeAudioData(context, arrayBuffer): Promise<AudioBuffer>

  • Parameters

    Returns Promise<AudioBuffer>

Static Private fetchAndCacheBuffer

  • fetchAndCacheBuffer(url, cache, validators?, signal?, callbacks?): Promise<ArrayBuffer>

  • Parameters

    • url: string
    • cache: Cache
    • Optional validators: CacheValidators
    • Optional signal: AbortSignal
    • Optional callbacks: Pick<CacheCallbacks, "onCacheHit">

    Returns Promise<ArrayBuffer>

Static Private getBufferFromCache

  • getBufferFromCache(url, cache): Promise<null | ArrayBuffer>

  • Parameters

    • url: string
    • cache: Cache

    Returns Promise<null | ArrayBuffer>

Static Private getMetadataFromCache

  • getMetadataFromCache(url, cache): Promise<null | CacheMetadata>

  • Parameters

    • url: string
    • cache: Cache

    Returns Promise<null | CacheMetadata>

Static Private getOrCreatePendingRequest

  • getOrCreatePendingRequest(url, createRequest, signal?, callbacks?): Promise<AudioBuffer>

  • Parameters

    • url: string
    • createRequest: (() => Promise<undefined | AudioBuffer>)
        • (): Promise<undefined | AudioBuffer>

        • Returns Promise<undefined | AudioBuffer>

    • Optional signal: AbortSignal
    • Optional callbacks: Pick<CacheCallbacks, "onLoadingProgress">

    Returns Promise<AudioBuffer>

Static Private openCache

Static setCacheExpirationTime

  • setCacheExpirationTime(time): void

  • Parameters

    • time: number

    Returns void

Static Private updateMetadata

  • updateMetadata(cache, url, data): Promise<void>

  • Parameters

    • cache: Cache
    • url: string
    • data: Partial<CacheMetadata>

    Returns Promise<void>

Static Private writeBufferAndMetadata

  • writeBufferAndMetadata(cache, url, response, metadata): Promise<void>

  • Atomically write a response body and its metadata into the cache. On failure, deletes both partial entries (best-effort via allSettled) and rethrows the original error.

    Parameters

    • cache: Cache
    • url: string
    • response: Response
    • metadata: Partial<CacheMetadata>

    Returns Promise<void>

Settings

Member Visibility

Theme

On This Page

constructorcacheExpirationTimedecodedBufferspendingCallbackspendingRequestsclearMemoryCachegetAudioBuffercallAllCallbackscollectStreamToArrayBuffercreateProgressTrackingStreamdecodeAudioDatafetchAndCacheBuffergetBufferFromCachegetMetadataFromCachegetOrCreatePendingRequestopenCachesetCacheExpirationTimeupdateMetadatawriteBufferAndMetadata