skills/docs/media/audio-ir/audio-ir-loader/README.md

@suaveplan/audio-ir-loader - Pipeline package for the @suaveplan audio-ir family: composes IrRegistry → StorageUriResolver → AudioDecoder → manifest validation into a single createIrLoader(). Universal.

Pipeline package for the @suaveplan/audio-ir-* family. Composes IrRegistry (from @suaveplan/audio-ir-core), a StorageUriResolver (from @suaveplan/storage-uri), and a map of AudioDecoders into a single IrLoader with load, preload, evict, and cacheStats.

Documentation tree

• cache — This module implements the in-process LRU that backs the loader's optional cache. The cache is keyed by IR id and bound…
  • cache — This module implements the in-process LRU that backs the loader's optional cache. The cache is keyed by IR id and bound…
• error-codes — This module is the single source of truth for every error code raised by @suaveplan/audio-ir-loader. It uses `defineC…
  • error-codes — This module is the single source of truth for every error code raised by @suaveplan/audio-ir-loader. It uses `defineC…
• loader — This module is the entry point for the package. createIrLoader(options) returns a typed IrLoader that composes the…
  • extension — The loader dispatches decoders by file extension. This module owns the canonicalisation step: given a URI string (which…
  • loader — This module is the entry point for the package. createIrLoader(options) returns a typed IrLoader that composes the…
  • manifest-validation — This module is the bridge between the DecodedAudio shape emitted by an AudioDecoder and the ImpulseResponse shape…
  • preload — This module implements the bounded-concurrency preload algorithm backing IrLoader.preload. It launches up to `concu…
• otel — This module owns the loader's OpenTelemetry instrumentation. It lazily builds a single, cached `AudioIrLoaderInstrument…
  • otel — This module owns the loader's OpenTelemetry instrumentation. It lazily builds a single, cached `AudioIrLoaderInstrument…

What ships

• createIrLoader(options): IrLoader — Zod-validated factory.
• Bounded-concurrency preload(ids, { concurrency }) with aggregate failure reporting.
• Optional in-process byte-bounded LRU cache.
• AUDIO_IR_LOADER.* error-code registry — exactly six codes (DECODER_UNAVAILABLE, MANIFEST_MISMATCH, ABORTED, CACHE_OVERFLOW, DECODE_FAILED, RESOLVE_FAILED).
• OpenTelemetry surface — audio_ir_loader.load_duration_ms, audio_ir_loader.bytes_read_total, audio_ir_loader.frames_out_total, audio_ir_loader.cache_hits_total, audio_ir_loader.cache_misses_total, audio_ir_loader.errors_total.

Modules

Module	Subpath	Docs
Error codes	./error-codes	src/error-codes/error-codes.md
OTel surface	(root)	src/otel/otel.md
LRU cache	(root)	src/cache/cache.md
createIrLoader	(root)	src/loader/loader.md
extractExtension	(root)	src/loader/extension.md
Manifest validation	(root)	src/loader/manifest-validation.md
Bounded preload	(root)	src/loader/preload.md

Design

The pipeline + dispatch + cache decisions live at

the cross-cutting IR-family model lives at

Quick install

import { createStorageUriResolver } from "@suaveplan/storage-uri";
import { bundleUriPlugin } from "@suaveplan/storage-uri-plugin-bundle";
import { decodeWav } from "@suaveplan/audio-decode-wav";
import { createIrLoader } from "@suaveplan/audio-ir-loader";

const resolver = createStorageUriResolver([
    bundleUriPlugin({
        packageSlug: "club",
        rootUrl: new URL("file:///opt/ir/club/"),
    }),
]);
const loader = createIrLoader({
    registry,
    resolver,
    decoders: { wav: decodeWav },
    cache: { maxBytes: 64 * 1024 * 1024 },
});
const ir = await loader.load("club-club1");