first commit

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

@@ -0,0 +1,79 @@
+# @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");
+```
+