73 lines
4.4 KiB
Markdown
73 lines
4.4 KiB
Markdown
# @suaveplan/audio-engine-server - Server-tier audio I/O layer: FileSourceAdapter, FileSinkAdapter, and ServerTimelineAdapter for offline rendering. Reuses universal audio-core / audio-timeline / audio-codecs primitives; adds only filesystem I/O and a file-output TimelineAdapter.
|
|
|
|
Server-tier audio I/O layer for the `@suaveplan/audio-*` family. Provides
|
|
the thinnest possible bridge between universal `AudioDocument` primitives
|
|
and a Node.js filesystem: `FileSourceAdapter`, `FileSinkAdapter`, and a
|
|
`ServerTimelineAdapter` whose backend is a file on disk.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [bus-orchestrator](./src/adapter/bus-orchestrator.md) — `BusOrchestrator` is the project-level wrapper around `BusRegistry` that `ServerTimelineAdapter` owns for its entire li…
|
|
- [server-adapter](./src/adapter/server-adapter.md) — `ServerTimelineAdapter` is the server-tier implementation of plugin slot 5 (the `TimelineAdapter` interface from `@suav…
|
|
- [fx](./src/fx/plugin-chain.md) — `PluginChain` owns the ordered list of FX plugins attached to a single track, the per-chain ambient state, the chain-le…
|
|
- [plugin-chain](./src/fx/plugin-chain.md) — `PluginChain` owns the ordered list of FX plugins attached to a single track, the per-chain ambient state, the chain-le…
|
|
- [fs-like](./src/internal/fs-like.md) — `FsLike` is the dependency-inversion seam between the audio engine's source and sink adapters and the underlying filesy…
|
|
- [sanitize-path](./src/internal/sanitize-path.md) — `sanitizePath` is the single boundary check every method that accepts a filesystem path passes through before invoking…
|
|
- [sink](./src/sink/file-sink.md) — `FileSinkAdapter` is the server-tier exit point for `AudioDocument` instances: it encodes a document through `@suavepla…
|
|
- [file-sink](./src/sink/file-sink.md) — `FileSinkAdapter` is the server-tier exit point for `AudioDocument` instances: it encodes a document through `@suavepla…
|
|
- [source](./src/source/file-source.md) — `FileSourceAdapter` is the server-tier entry point for reading audio files into the universal `AudioDocument` model. It…
|
|
- [file-source](./src/source/file-source.md) — `FileSourceAdapter` is the server-tier entry point for reading audio files into the universal `AudioDocument` model. It…
|
|
<!-- end:auto-docs -->
|
|
|
|
## Scope
|
|
|
|
This package implements plugin slot 5 of the audio family — the
|
|
`TimelineAdapter` interface — for server environments where rendering is
|
|
not real-time. Every piece of DSP, plan compilation, segment maths, and
|
|
codec work is delegated to the universal packages
|
|
(`@suaveplan/audio-core`, `@suaveplan/audio-codecs`,
|
|
`@suaveplan/audio-timeline`). The only environment-specific code in this
|
|
package is the filesystem source/sink and the file-output adapter.
|
|
|
|
## Public surface
|
|
|
|
- `FileSourceAdapter` — `load`, `loadMany`, `createReadStream`
|
|
- `FileSinkAdapter` — `save`, `saveMany`, `createWriteStream`
|
|
- `ServerTimelineAdapter` — every `TimelineAdapter` member plus a
|
|
non-interface `render(opts)` method for finite-range exports
|
|
- `PluginChain`, `DefaultBusRegistry`, `SidechainPublisher` — the
|
|
per-track FX chain and project-level bus registry the adapter hosts
|
|
- `sanitizePath`, `isHttpUrl`, `checkAborted` — internal helpers reused
|
|
by every I/O entry point
|
|
- `AudioEngineServerError`, `AUDIO_ENGINE_SERVER_CODES`,
|
|
`AUDIO_ENGINE_SERVER_ERROR_METADATA` — typed error surface
|
|
|
|
## Error codes
|
|
|
|
`AUDIO_ENGINE_SERVER.FILE_NOT_FOUND`, `.DECODE_FAILED`, `.ENCODE_FAILED`,
|
|
`.IO_FAILED`, `.INVALID_PATH`, `.INVALID_OPTIONS`, `.ABORTED`,
|
|
`.BUS_CYCLE_DETECTED`. Every code is thrown by at least one production
|
|
call site that the test suite exercises against a real
|
|
`node:fs.mkdtemp` tmpdir.
|
|
|
|
## OpenTelemetry
|
|
|
|
The package emits spans `file.load`, `file.save`, `server.render`, counters
|
|
`audio_engine_bytes_read_total` / `audio_engine_bytes_written_total`, and
|
|
histograms `audio_engine_load_duration_ms` / `audio_engine_save_duration_ms` /
|
|
`audio_engine_render_duration_ms`. All instrumentation is inert when no
|
|
exporter is registered and has no import-time side effects.
|
|
|
|
## Quality gates
|
|
|
|
- 100% test coverage (`vitest run --coverage`, istanbul provider).
|
|
- 100% docs coverage — every implementation file has a sibling `.md`
|
|
with the standard six sections.
|
|
- `engines.node >= 22` — `Readable.toWeb` / `Writable.toWeb` are required.
|
|
- `sideEffects: false`; every feature module has its own subpath export.
|
|
|
|
See the specification for the full
|
|
requirement set.
|
|
|