84 lines
4.0 KiB
Markdown
84 lines
4.0 KiB
Markdown
# Tasks: enterprise-audio-sprite-packer
|
||
|
||
**Change ID**: enterprise-audio-sprite-packer
|
||
**Package**: `@suaveplan/audio-sprite-packer`
|
||
**Target path**: `universal/compression/audio-sprite-packer`
|
||
**Prerequisite packages on Verdaccio**: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/mime`, `@suaveplan/crypto-utils`
|
||
|
||
---
|
||
|
||
## 1. Scaffold
|
||
|
||
- [ ] Create directory `universal/compression/audio-sprite-packer/` with `src/`, `tests/`, `src/__benchmarks__/`, and all feature subdirectories per the layout in `proposal.md`.
|
||
- [ ] Write `package.json` at version `0.1.0` with `"type": "module"`, `"sideEffects": false`, full `exports` map, deps: `@suaveplan/error workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/mime workspace:^`, `@suaveplan/crypto-utils workspace:^`, `zod catalog:forms`, `@opentelemetry/api catalog:observability`.
|
||
- [ ] Write `tsconfig.json` extending `@suaveplan/typescript-config/library.json`.
|
||
- [ ] Write `vitest.config.ts` using `createTestConfig()` from `@suaveplan/testing/config`.
|
||
- [ ] Add `lint`, `typecheck`, `test`, `test:coverage`, `build`, `docs:check` scripts.
|
||
|
||
---
|
||
|
||
## 2. Types + errors
|
||
|
||
- [ ] Write `src/types/common.ts` — `AudioFormat`, `AudioClipInput`, `AudioSpriteEntry`, `AudioSpriteManifest`, `AudioSprite`, `PackOptions`, `AudioAdapter`, `AudioSpritePackerOptions`.
|
||
- [ ] Write `src/types/common.md`.
|
||
- [ ] Write `src/error-codes.ts` — `AudioSpriteErrorCode`, `AUDIO_SPRITE_ERROR_METADATA`, `registerAudioSpriteErrorCodes()`.
|
||
- [ ] Write Zod schemas: `AudioSpriteEntrySchema`, `AudioSpriteManifestSchema`, `PackOptionsSchema`, `AudioSpritePackerOptionsSchema`.
|
||
|
||
---
|
||
|
||
## 3. NullAudioAdapter
|
||
|
||
- [ ] Implement `NullAudioAdapter` — `probe` returns configurable fixture metadata (WAV, 44100 Hz, 2ch, 1.0 s), `decode` returns 44100 × 2 float32 zeros, `encode` returns input bytes, `stripSilence` returns input unchanged, `normalise` returns input unchanged.
|
||
- [ ] Write `null-adapter.test.ts` and `null-adapter.md`.
|
||
|
||
---
|
||
|
||
## 4. Manifest utilities
|
||
|
||
- [ ] Implement `buildManifest(entries, packedBuffer): AudioSpriteManifest` — assembles manifest including SHA-256 content hash via `@suaveplan/crypto-utils`.
|
||
- [ ] Implement `validateManifest(manifest): void` — checks version, entries array non-empty, offsets non-overlapping.
|
||
- [ ] Write `manifest.test.ts` and `manifest.md`.
|
||
|
||
---
|
||
|
||
## 5. AudioSpritePacker
|
||
|
||
- [ ] Implement `AudioSpritePacker.pack(clips, options, signal)`:
|
||
1. Validate clips non-empty.
|
||
2. For each clip: detect format (`@suaveplan/mime`), probe, decode PCM.
|
||
3. If `stripSilence`, call `adapter.stripSilence`.
|
||
4. If `normalise`, call `adapter.normalise`.
|
||
5. Append silence padding (zero-fill float32 × sampleRate × silencePaddingMs / 1000).
|
||
6. Encode all clips concatenated as single output buffer.
|
||
7. Build manifest with byte offsets per clip.
|
||
8. Return `{ data, manifest }`.
|
||
- [ ] Implement `AudioSpritePacker.unpack(sprite, clipName)` — slice-and-return using manifest offsets.
|
||
- [ ] Wire `AbortSignal` propagation; throw on abort.
|
||
- [ ] Wire OTel: span `audio-sprite.pack`, counter, histogram, compression ratio.
|
||
- [ ] Write `audio-sprite-packer.test.ts` (≤500 lines): pack 3 clips, unpack each, abort, empty clips throws.
|
||
- [ ] Write `audio-sprite-packer.md`.
|
||
|
||
---
|
||
|
||
## 6. Benchmarks
|
||
|
||
- [ ] Write `src/__benchmarks__/audio-sprite-packer.bench.ts` — pack 10 clips, pack 50 clips (null adapter).
|
||
|
||
---
|
||
|
||
## 7. Tests
|
||
|
||
- [ ] Write `tests/integration.test.ts` — full pack/unpack round-trip.
|
||
- [ ] Write `tests/property.test.ts` (fast-check) — manifest entry count = clip count, unpack returns correct slice, silence padding duration.
|
||
|
||
---
|
||
|
||
## 8. Docs + verify + publish
|
||
|
||
- [ ] All co-located `.md` files (≥200 words each).
|
||
- [ ] Write `README.md` at package root.
|
||
- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/audio-sprite-packer` — green.
|
||
- [ ] `bunx turbo test:coverage --filter=@suaveplan/audio-sprite-packer` — 100%.
|
||
- [ ] `bun scripts/publish.ts --package @suaveplan/audio-sprite-packer`.
|
||
- [ ] Archive to `openspec/archive/2026-04-24-enterprise-audio-sprite-packer/`.
|