80 lines
4.3 KiB
Markdown
80 lines
4.3 KiB
Markdown
# @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");
|
|
```
|
|
|