suaveplan/packages/media/audio/audio-core/README.md

@suaveplan/audio-core - Universal audio data model and processing primitives: paged AudioDocument, non-destructive PlanEngine, block-level ProcessPipeline, and typed OpRegistry. Zero browser or Node dependencies.

Universal audio data model and processing primitives. Provides a paged AudioDocument, a non-destructive PlanEngine, a block-level ProcessPipeline, and a typed OpRegistry — all with zero browser or Node.js dependencies.

Documentation tree

• analysis — AnalysisOp is the operator contract every @suaveplan/audio-analysis-* package implements: spectrum, beat-tracking,…
  • analysis-op — AnalysisOp is the operator contract every @suaveplan/audio-analysis-* package implements: spectrum, beat-tracking,…
• document — AudioDocument is the primary paged audio document model in @suaveplan/audio-core. It represents a multi-channel aud…
  • document — AudioDocument is the primary paged audio document model in @suaveplan/audio-core. It represents a multi-channel aud…
• error-codes — This module centralises every error code, metadata description, and severity level that the @suaveplan/audio-core pac…
  • error-codes — This module centralises every error code, metadata description, and severity level that the @suaveplan/audio-core pac…
• page — This module provides the low-level building blocks for memory-efficient audio storage and retrieval inside an `AudioDoc…
  • page — This module provides the low-level building blocks for memory-efficient audio storage and retrieval inside an `AudioDoc…
• plan-engine — The PlanEngine class is the central coordinator for turning an AudioDocument edit list into an executable audio pla…
• segment — The segment helpers provide low-level geometric operations on Segment objects. A segment represents a contiguous mapp…
• block-processor — BlockProcessor defines the standard lifecycle contract for audio processors that operate on fixed-size blocks of mult…
• process-pipeline — ProcessPipeline executes a chain of audio editing operations on blocks of multi-channel PCM data. It bridges the decl…
• registry — OpRegistry is the central, in-memory catalog for all audio operations in @suaveplan/audio-core. It maps unique stri…
  • crop — registerCrop adds the crop operation to an OpRegistry, making it available to the planning engine. The crop opera…
  • dither — registerDither installs the dither processing operation into an OpRegistry. Dithering adds a small amount of pseu…
  • fade — registerFade adds the fade operation to an OpRegistry. Fade applies a linear amplitude ramp across an entire proc…
  • gain — registerGain installs the gain operation into an OpRegistry. It is the simplest block-level processor: every samp…
  • insert — registerInsert adds the insert operation to an OpRegistry. Insert is a planning-stage edit that introduces silenc…
  • mix — registerMix installs the mix operation into an OpRegistry. The mix processor adds a scaled copy of the input sign…
  • normalize — registerNormalize adds the normalize operation to an OpRegistry. Normalization scans an entire processing block t…
  • pad — registerPad installs the pad operation into an OpRegistry. Pad is a planning function that extends the total time…
  • pan — registerPan adds the pan operation to an OpRegistry. Pan is a block-level processor that adjusts the relative lou…
  • remove — registerRemove installs the remove operation into an OpRegistry. Remove is a planning function that deletes sampl…
  • repeat — registerRepeat adds the repeat operation to an OpRegistry. Repeat is a planning function that duplicates the enti…
  • resample — registerResample installs the resample operation into an OpRegistry. Resample is a planning function that changes…
  • reverse — registerReverse adds the reverse operation to an OpRegistry. Reverse is a planning function that flips the order…
  • speed — registerSpeed installs the speed operation into an OpRegistry. Speed is a planning function that changes playback…
  • stretch — registerStretch adds the stretch operation to an OpRegistry. Stretch is a planning function that changes the dura…
  • transform — registerTransform installs the transform operation into an OpRegistry. Transform is a block-level processor that…
  • trim — registerTrim installs the trim operation into an OpRegistry. Trim is a planning function that shortens the audio…
  • op-registry — OpRegistry is the central, in-memory catalog for all audio operations in @suaveplan/audio-core. It maps unique stri…
• render — The render module bridges the compiled plan produced by PlanEngine and the paged sample storage of an AudioDocument…
  • render — The render module bridges the compiled plan produced by PlanEngine and the paged sample storage of an AudioDocument…
• stats — This module computes standard audio statistics across paged channel data. By scanning every sample in every page, it pr…
  • stats — This module computes standard audio statistics across paged channel data. By scanning every sample in every page, it pr…
• stream — This module adapts the @suaveplan/audio-core processing pipeline to the Web Streams standard. It exports a factory fu…
  • stream — This module adapts the @suaveplan/audio-core processing pipeline to the Web Streams standard. It exports a factory fu…
• telemetry — The telemetry module is the single OpenTelemetry integration point for @suaveplan/audio-core. It exposes thin, lazy h…
  • telemetry — The telemetry module is the single OpenTelemetry integration point for @suaveplan/audio-core. It exposes thin, lazy h…

Install

bun add @suaveplan/audio-core

Quick start

import { AudioDocument, OpRegistry, PlanEngine } from "@suaveplan/audio-core";

const doc = new AudioDocument({
  sampleRate: 48000,
  channels: 2,
  sourceLength: 48000,
  pages: [
    {
      startSample: 0,
      channelData: [new Float32Array(48000), new Float32Array(48000)],
    },
  ],
  edits: [],
});

// Apply a non-destructive trim edit
doc.run({ type: "trim", opts: { start: 1000, end: 47000 } });

// Compile the plan
const registry = OpRegistry.createWithDefaults();
const engine = new PlanEngine(registry);
const plan = engine.compile(doc, true);

// Stream the result
for await (const block of doc.stream()) {
  // block is Float32Array[] — one per channel
}

Modules

• src/document/document.md — AudioDocument class and JSON round-trip
• src/page/page.md — Page primitives: walkPages, copyPages, readPages, allocation pool
• src/plan/plan-engine.md — PlanEngine for compiling and resolving edits
• src/plan/segment.md — Segment overlap, merge, and split helpers
• src/process/process-pipeline.md — ProcessPipeline for block-level DSP
• src/process/block-processor.md — BlockProcessor interface and NoopBlockProcessor
• src/registry/op-registry.md — OpRegistry for registering plan and process ops
• src/registry/built-in/ — Built-in operations: trim, crop, speed, stretch, reverse, insert, remove, repeat, pad, resample, gain, normalize, fade, pan, mix, dither, transform
• src/render/render.md — renderBlock for copying source segments into output buffers
• src/stats/stats.md — computeStats for peak, RMS, and DC offset
• src/stream/stream.md — createPlanTransformStream for downstream transforms
• src/error-codes.md — Error codes and AudioError class