# @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.