107 lines
5.2 KiB
Markdown
107 lines
5.2 KiB
Markdown
# Tasks: enterprise-audio-transport
|
|
|
|
**Change ID**: enterprise-audio-transport
|
|
**Package**: `@suaveplan/audio-transport`
|
|
**Target path**: `packages/audio/audio-transport`
|
|
**Prerequisite packages on Verdaccio**: `@suaveplan/timing`, `@suaveplan/events`, `@suaveplan/fsm`, `@suaveplan/types`, `@suaveplan/error`
|
|
|
|
---
|
|
|
|
## 1. Scaffold
|
|
|
|
- [ ] Create directory `packages/audio/audio-transport/` 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/timing workspace:^`, `@suaveplan/events workspace:^`, `@suaveplan/fsm workspace:^`, `@suaveplan/types workspace:^`, `@suaveplan/error workspace:^`, `zod catalog:forms`.
|
|
- [ ] 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/transport/transport.types.ts` — `TransportOptions`, `TransportTime`, `Ticks`, `BarsBeatsSixteenths`, `BPM`, `Subdivision`, `TransportCallback`, `TransportEventMap`.
|
|
- [ ] Write `src/scheduler/scheduler.types.ts` — `SchedulerState`.
|
|
- [ ] Write `src/tick-source/tick-source.types.ts` — `TickSourceState`.
|
|
- [ ] Write `src/signal/signal.types.ts` — `SignalConfig`.
|
|
- [ ] Write `src/time/time.types.ts` — `TimeToken`, `TimeParseResult`.
|
|
- [ ] Write co-located `.md` files for each types module (≥200 words).
|
|
- [ ] Write `src/error-codes.ts` — `TransportErrorCode`, `AUDIO_TRANSPORT_ERROR_METADATA`, `registerTransportErrorCodes()`.
|
|
- [ ] Write Zod schemas: `TransportOptionsSchema`, `TransportTimeSchema`, `TicksSchema`, `BarsBeatsSixteenthsSchema`.
|
|
|
|
---
|
|
|
|
## 3. Signal module
|
|
|
|
- [ ] Implement `src/signal/signal.ts` — `Signal<BPM>` wrapper around `@suaveplan/timing` `Signal` with ramp/hold curves for tempo automation.
|
|
- [ ] Write `signal.test.ts` and `signal.md`.
|
|
|
|
---
|
|
|
|
## 4. Time parsing
|
|
|
|
- [ ] Implement `src/time/time.ts` — parse musical time strings (`"4n"`, `"8t"`, `"1m"`, `"2:1:0"`, `"+1"`, `"@4m"`), convert to seconds and ticks, `toSeconds`, `toTicks`, `toBarsBeatsSixteenths`.
|
|
- [ ] Write `time.test.ts` and `time.md`.
|
|
|
|
---
|
|
|
|
## 5. TickSource
|
|
|
|
- [ ] Implement `TickSource` in `src/tick-source/tick-source.ts`:
|
|
- `getTicksAtTime`, `getTimeOfTick`, `setTicksAtTime` with tempo curve support.
|
|
- `start`, `stop`, `pause` with offset handling.
|
|
- `forEachTickBetween` iterating ticks between two audio times, invoking callback with sample-accurate `time` and `ticks`.
|
|
- [ ] Write `tick-source.test.ts` and `tick-source.md`.
|
|
|
|
---
|
|
|
|
## 6. TransportScheduler
|
|
|
|
- [ ] Implement `TransportScheduler` in `src/scheduler/scheduler.ts`:
|
|
- Constructor takes `Transport` and `Clock`.
|
|
- `start()` begins the ~100Hz lookahead loop via `@suaveplan/timing` `createScheduler`.
|
|
- `stop()` halts the scheduler.
|
|
- On each tick: emit FSM state changes between last update and now, then invoke `tickSource.forEachTickBetween` to fire scheduled callbacks with sample-accurate times.
|
|
- [ ] Write `scheduler.test.ts` and `scheduler.md`.
|
|
|
|
---
|
|
|
|
## 7. Transport
|
|
|
|
- [ ] Implement `Transport` in `src/transport/transport.ts`:
|
|
- Constructor accepts `TransportOptions`; initializes `TickSource`, FSM state machine (`stopped` → `playing` → `paused`), and internal event list.
|
|
- `start`, `stop`, `pause` drive FSM transitions and tick source.
|
|
- `schedule`, `scheduleRepeat`, `scheduleOnce` return numeric event IDs; store callbacks in a priority queue.
|
|
- `cancel` removes event by ID; `cancelAfter` removes all events after a given time.
|
|
- `bpm` as `Signal<BPM>` with ramp/hold support.
|
|
- `swing` (0..1) and `swingSubdivision` applied per-tick during `_processTick()` using sine-based offset.
|
|
- `toSeconds`, `toTicks`, `toBarsBeatsSixteenths` delegate to time module.
|
|
- `loop`, `loopStart`, `loopEnd` — when enabled, transport jumps to `loopStart` after crossing `loopEnd`.
|
|
- Events: `start`, `stop`, `pause`, `loop`, `bpm` via `@suaveplan/events`.
|
|
- `dispose()` cancels all events, stops scheduler, and cleans up.
|
|
- [ ] Write `transport.test.ts` (≤500 lines): start/stop/pause, schedule/cancel, loop region, tempo ramp, swing application, time conversion round-trip.
|
|
- [ ] Write `transport.md`.
|
|
|
|
---
|
|
|
|
## 8. Benchmarks
|
|
|
|
- [ ] Write `src/__benchmarks__/transport.bench.ts` — schedule 1 000 callbacks, 100 BPM ramps, 10 000 tick iterations.
|
|
|
|
---
|
|
|
|
## 9. Integration tests
|
|
|
|
- [ ] Write `tests/integration.test.ts` — full transport lifecycle with `FakeClock`: start, schedule repeated callback, verify callback times are sample-accurate, loop jump, cancel after time, tempo automation curve.
|
|
|
|
---
|
|
|
|
## 10. 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-transport` — green.
|
|
- [ ] `bunx turbo test:coverage --filter=@suaveplan/audio-transport` — 100%.
|
|
- [ ] `bun scripts/publish.ts --package @suaveplan/audio-transport`.
|
|
- [ ] Fold `specs/audio-transport/spec.md` into `openspec/specs/audio-transport/spec.md`.
|
|
- [ ] Archive to `openspec/archive/2026-05-14-enterprise-audio-transport/`.
|