suaveplan/packages/media/audio/audio-engine-server/README.md

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

Documentation tree

• bus-orchestrator — BusOrchestrator is the project-level wrapper around BusRegistry that ServerTimelineAdapter owns for its entire li…
• server-adapter — ServerTimelineAdapter is the server-tier implementation of plugin slot 5 (the TimelineAdapter interface from `@suav…
• fx — PluginChain owns the ordered list of FX plugins attached to a single track, the per-chain ambient state, the chain-le…
  • plugin-chain — PluginChain owns the ordered list of FX plugins attached to a single track, the per-chain ambient state, the chain-le…
• fs-like — FsLike is the dependency-inversion seam between the audio engine's source and sink adapters and the underlying filesy…
• sanitize-path — sanitizePath is the single boundary check every method that accepts a filesystem path passes through before invoking…
• sink — FileSinkAdapter is the server-tier exit point for AudioDocument instances: it encodes a document through `@suavepla…
  • file-sink — FileSinkAdapter is the server-tier exit point for AudioDocument instances: it encodes a document through `@suavepla…
• source — FileSourceAdapter is the server-tier entry point for reading audio files into the universal AudioDocument model. It…
  • file-source — FileSourceAdapter is the server-tier entry point for reading audio files into the universal AudioDocument model. It…

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.