# @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 `AudioDecoder`s into a
single `IrLoader` with `load`, `preload`, `evict`, and `cacheStats`.

<!-- begin:auto-docs -->
## Documentation tree

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

## 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`](./src/error-codes/error-codes.md) |
| OTel surface | (root) | [`src/otel/otel.md`](./src/otel/otel.md) |
| LRU cache | (root) | [`src/cache/cache.md`](./src/cache/cache.md) |
| `createIrLoader` | (root) | [`src/loader/loader.md`](./src/loader/loader.md) |
| `extractExtension` | (root) | [`src/loader/extension.md`](./src/loader/extension.md) |
| Manifest validation | (root) | [`src/loader/manifest-validation.md`](./src/loader/manifest-validation.md) |
| Bounded `preload` | (root) | [`src/loader/preload.md`](./src/loader/preload.md) |

## Design

The pipeline + dispatch + cache decisions live at

the cross-cutting IR-family model lives at

## Quick install

```ts
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");
```