first commit

docs/media/audio/audio-sprite-packer/src/adapters/null-adapter/null-adapter.md

@@ -0,0 +1,114 @@
+# NullAudioAdapter
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`NullAudioAdapter` is a deterministic, test-only implementation of the `AudioAdapter` interface. It produces predictable fixture data without touching real audio codecs, file systems, or browser APIs, making it ideal for unit tests, property-based tests, and CI pipelines.
+
+## Features
+
+- **Zero external dependencies** — No `AudioContext`, no `ffmpeg`, no file I/O.
+- **Deterministic output** — `decode` returns zero-filled `Float32Array` sized by fixture config.
+- **Configurable dimensions** — Duration, sample rate, channels, and format can be overridden per instance.
+- **Pass-through processing** — `stripSilence` and `normalise` return the input unchanged.
+- **Self-describing encode** — `encode` prefixes raw sample bytes with a JSON header containing metadata.
+
+## Usage: Basic Example
+
+```ts
+import { AudioSpritePacker, NullAudioAdapter } from "@suaveplan/audio-sprite-packer";
+
+const packer = new AudioSpritePacker({ adapter: new NullAudioAdapter() });
+const sprite = await packer.pack([
+  { name: "beep", data: new Uint8Array([1]) },
+]);
+```
+
+## Usage: Advanced Example
+
+```ts
+import { NullAudioAdapter } from "@suaveplan/audio-sprite-packer";
+
+// Simulate a 5-second 48 kHz stereo clip.
+const adapter = new NullAudioAdapter({
+  durationSeconds: 5,
+  sampleRate: 48000,
+  channels: 2,
+});
+
+const probed = await adapter.probe(new Uint8Array(0));
+console.log(probed.durationSeconds); // 5
+
+const pcm = await adapter.decode(new Uint8Array(0));
+console.log(pcm.length); // 480000
+```
+
+## API Reference
+
+### `NullAudioAdapterOptions`
+
+```ts
+interface NullAudioAdapterOptions {
+  readonly durationSeconds?: number;
+  readonly sampleRate?: number;
+  readonly channels?: number;
+  readonly format?: AudioFormat;
+}
+```
+
+All fields are optional. Defaults are:
+
+- `durationSeconds` — `0.1`
+- `sampleRate` — `44100`
+- `channels` — `1`
+- `format` — `"wav"`
+
+### `constructor(options?: NullAudioAdapterOptions)`
+
+Creates a new `NullAudioAdapter` with the supplied fixture configuration. If no options are provided, the defaults above are used.
+
+### `supportedFormats`
+
+```ts
+readonly supportedFormats: readonly AudioFormat[] = ["wav", "mp3", "ogg", "flac"];
+```
+
+All formats are nominally supported; the adapter does not inspect the actual bytes.
+
+### `probe(data: Uint8Array): Promise<AudioProbeResult>`
+
+Returns the fixture `durationSeconds`, `sampleRate`, `channels`, and `format`. The `data` argument is ignored.
+
+### `decode(data: Uint8Array): Promise<Float32Array>`
+
+Allocates a `Float32Array` of length `sampleRate * channels * durationSeconds` (floored) and fills it with zeros. If `data.length > 0`, index `0` is explicitly set to `0` so the branch is covered during testing.
+
+### `encode(samples, sampleRate, channels, format): Promise<Uint8Array>`
+
+Produces a buffer consisting of:
+
+1. A JSON header (`TextEncoder`-encoded) containing `sampleRate`, `channels`, `format`, and `length`.
+2. The raw sample bytes from `samples.buffer`.
+
+This makes the encoded output self-describing and deterministic.
+
+### `stripSilence(samples: Float32Array): Float32Array`
+
+Returns `samples` unchanged.
+
+### `normalise(samples: Float32Array): Float32Array`
+
+Returns `samples` unchanged.
+
+### `createNullAudioAdapter(options?: NullAudioAdapterOptions): NullAudioAdapter`
+
+Factory function equivalent to `new NullAudioAdapter(options)`.
+
+## Implementation Notes
+
+- The adapter is **not** suitable for production use. It exists solely to satisfy the `AudioAdapter` contract in test environments.
+- `decode` sets `result[0] = 0` when `data.length > 0` purely to exercise the conditional branch for 100 % code coverage.
+- `encode` reuses `samples.buffer` via `new Uint8Array(samples.buffer, samples.byteOffset, samples.byteLength)` without copying, which is safe because the packer does not mutate encoded chunks after creation.