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

Constructors

constructor

Properties

Static Private cacheExpirationTime

cacheExpirationTime: number = ...

Static Private decodedBuffers

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

Static Private pendingCallbacks

pendingCallbacks: Map<string, {
    onLoadingProgress?: ((event) => void);
}[]> = ...

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: {
          onCacheError?: ((event) => void);
          onCacheHit?: ((event) => void);
          onCacheMiss?: ((event) => void);
          onLoadingComplete?: ((event) => void);
          onLoadingError?: ((event) => void);
          onLoadingProgress?: ((event) => void);
          onLoadingStart?: ((event) => void);
      }
      • Optional onCacheError?: ((event) => void)
          • (event): void

          • Parameters

            • event: any

            Returns void

      • Optional onCacheHit?: ((event) => void)
          • (event): void

          • Parameters

            • event: any

            Returns void

      • Optional onCacheMiss?: ((event) => void)
          • (event): void

          • Parameters

            • event: any

            Returns void

      • Optional onLoadingComplete?: ((event) => void)
          • (event): void

          • Parameters

            • event: any

            Returns void

      • Optional onLoadingError?: ((event) => void)
          • (event): void

          • Parameters

            • event: any

            Returns void

      • Optional onLoadingProgress?: ((event) => void)
          • (event): void

          • Parameters

            • event: any

            Returns void

      • Optional onLoadingStart?: ((event) => void)
          • (event): void

          • Parameters

            • event: any

            Returns void

    Returns Promise<AudioBuffer>

    Promise that resolves to decoded AudioBuffer

    Throws

    Error if audio cannot be fetched or decoded

Static Private callAllCallbacks

  • callAllCallbacks(url, callbackName, eventData): void

  • Calls all registered callbacks for a specific event type on a URL

    Parameters

    • url: string

      The URL to get callbacks for

    • callbackName: "onLoadingProgress"

      Name of the callback method to invoke

    • eventData: any

      Data to pass to the callbacks

    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): {
        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

    Parameters

    • response: Response

      The fetch Response object with ReadableStream body

    • url: string

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

    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, etag?, lastModified?, signal?, callbacks?): Promise<ArrayBuffer>

  • Parameters

    • url: string
    • cache: Cache
    • Optional etag: string
    • Optional lastModified: string
    • Optional signal: AbortSignal
    • Optional callbacks: {
          onCacheHit?: ((event) => void);
      }
      • Optional onCacheHit?: ((event) => void)
          • (event): void

          • Parameters

            • event: any

            Returns void

    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: {
          onLoadingProgress?: ((event) => void);
      }
      • Optional onLoadingProgress?: ((event) => void)
          • (event): void

          • Parameters

            • event: any

            Returns void

    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>

Settings

Member Visibility

Theme

On This Page

constructorcacheExpirationTimedecodedBufferspendingCallbackspendingRequestsclearMemoryCachegetAudioBuffercallAllCallbackscollectStreamToArrayBuffercreateProgressTrackingStreamdecodeAudioDatafetchAndCacheBuffergetBufferFromCachegetMetadataFromCachegetOrCreatePendingRequestopenCachesetCacheExpirationTimeupdateMetadata