Initial Commit
This commit is contained in:
101
packages/media/audio/audio-core/README.md
Normal file
101
packages/media/audio/audio-core/README.md
Normal file
@@ -0,0 +1,101 @@
|
||||
# @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.
|
||||
|
||||
<!-- begin:auto-docs -->
|
||||
## Documentation tree
|
||||
|
||||
- [analysis](./src/analysis/analysis-op.md) — `AnalysisOp` is the operator contract every `@suaveplan/audio-analysis-*` package implements: spectrum, beat-tracking,…
|
||||
- [analysis-op](./src/analysis/analysis-op.md) — `AnalysisOp` is the operator contract every `@suaveplan/audio-analysis-*` package implements: spectrum, beat-tracking,…
|
||||
- [document](./src/document/document.md) — `AudioDocument` is the primary paged audio document model in `@suaveplan/audio-core`. It represents a multi-channel aud…
|
||||
- [document](./src/document/document.md) — `AudioDocument` is the primary paged audio document model in `@suaveplan/audio-core`. It represents a multi-channel aud…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module centralises every error code, metadata description, and severity level that the `@suaveplan/audio-core` pac…
|
||||
- [error-codes](./src/error-codes/error-codes.md) — This module centralises every error code, metadata description, and severity level that the `@suaveplan/audio-core` pac…
|
||||
- [page](./src/page/page.md) — This module provides the low-level building blocks for memory-efficient audio storage and retrieval inside an `AudioDoc…
|
||||
- [page](./src/page/page.md) — This module provides the low-level building blocks for memory-efficient audio storage and retrieval inside an `AudioDoc…
|
||||
- [plan-engine](./src/plan/plan-engine.md) — The `PlanEngine` class is the central coordinator for turning an `AudioDocument` edit list into an executable audio pla…
|
||||
- [segment](./src/plan/segment.md) — The segment helpers provide low-level geometric operations on `Segment` objects. A segment represents a contiguous mapp…
|
||||
- [block-processor](./src/process/block-processor.md) — `BlockProcessor` defines the standard lifecycle contract for audio processors that operate on fixed-size blocks of mult…
|
||||
- [process-pipeline](./src/process/process-pipeline.md) — `ProcessPipeline` executes a chain of audio editing operations on blocks of multi-channel PCM data. It bridges the decl…
|
||||
- [registry](./src/registry/op-registry.md) — `OpRegistry` is the central, in-memory catalog for all audio operations in `@suaveplan/audio-core`. It maps unique stri…
|
||||
- [crop](./src/registry/built-in/crop.md) — `registerCrop` adds the `crop` operation to an `OpRegistry`, making it available to the planning engine. The crop opera…
|
||||
- [dither](./src/registry/built-in/dither.md) — `registerDither` installs the `dither` processing operation into an `OpRegistry`. Dithering adds a small amount of pseu…
|
||||
- [fade](./src/registry/built-in/fade.md) — `registerFade` adds the `fade` operation to an `OpRegistry`. Fade applies a linear amplitude ramp across an entire proc…
|
||||
- [gain](./src/registry/built-in/gain.md) — `registerGain` installs the `gain` operation into an `OpRegistry`. It is the simplest block-level processor: every samp…
|
||||
- [insert](./src/registry/built-in/insert.md) — `registerInsert` adds the `insert` operation to an `OpRegistry`. Insert is a planning-stage edit that introduces silenc…
|
||||
- [mix](./src/registry/built-in/mix.md) — `registerMix` installs the `mix` operation into an `OpRegistry`. The mix processor adds a scaled copy of the input sign…
|
||||
- [normalize](./src/registry/built-in/normalize.md) — `registerNormalize` adds the `normalize` operation to an `OpRegistry`. Normalization scans an entire processing block t…
|
||||
- [pad](./src/registry/built-in/pad.md) — `registerPad` installs the `pad` operation into an `OpRegistry`. Pad is a planning function that extends the total time…
|
||||
- [pan](./src/registry/built-in/pan.md) — `registerPan` adds the `pan` operation to an `OpRegistry`. Pan is a block-level processor that adjusts the relative lou…
|
||||
- [remove](./src/registry/built-in/remove.md) — `registerRemove` installs the `remove` operation into an `OpRegistry`. Remove is a planning function that deletes sampl…
|
||||
- [repeat](./src/registry/built-in/repeat.md) — `registerRepeat` adds the `repeat` operation to an `OpRegistry`. Repeat is a planning function that duplicates the enti…
|
||||
- [resample](./src/registry/built-in/resample.md) — `registerResample` installs the `resample` operation into an `OpRegistry`. Resample is a planning function that changes…
|
||||
- [reverse](./src/registry/built-in/reverse.md) — `registerReverse` adds the `reverse` operation to an `OpRegistry`. Reverse is a planning function that flips the order…
|
||||
- [speed](./src/registry/built-in/speed.md) — `registerSpeed` installs the `speed` operation into an `OpRegistry`. Speed is a planning function that changes playback…
|
||||
- [stretch](./src/registry/built-in/stretch.md) — `registerStretch` adds the `stretch` operation to an `OpRegistry`. Stretch is a planning function that changes the dura…
|
||||
- [transform](./src/registry/built-in/transform.md) — `registerTransform` installs the `transform` operation into an `OpRegistry`. Transform is a block-level processor that…
|
||||
- [trim](./src/registry/built-in/trim.md) — `registerTrim` installs the `trim` operation into an `OpRegistry`. Trim is a planning function that shortens the audio…
|
||||
- [op-registry](./src/registry/op-registry.md) — `OpRegistry` is the central, in-memory catalog for all audio operations in `@suaveplan/audio-core`. It maps unique stri…
|
||||
- [render](./src/render/render.md) — The render module bridges the compiled plan produced by `PlanEngine` and the paged sample storage of an `AudioDocument`…
|
||||
- [render](./src/render/render.md) — The render module bridges the compiled plan produced by `PlanEngine` and the paged sample storage of an `AudioDocument`…
|
||||
- [stats](./src/stats/stats.md) — This module computes standard audio statistics across paged channel data. By scanning every sample in every page, it pr…
|
||||
- [stats](./src/stats/stats.md) — This module computes standard audio statistics across paged channel data. By scanning every sample in every page, it pr…
|
||||
- [stream](./src/stream/stream.md) — This module adapts the `@suaveplan/audio-core` processing pipeline to the Web Streams standard. It exports a factory fu…
|
||||
- [stream](./src/stream/stream.md) — This module adapts the `@suaveplan/audio-core` processing pipeline to the Web Streams standard. It exports a factory fu…
|
||||
- [telemetry](./src/telemetry/telemetry.md) — The telemetry module is the single OpenTelemetry integration point for `@suaveplan/audio-core`. It exposes thin, lazy h…
|
||||
- [telemetry](./src/telemetry/telemetry.md) — The telemetry module is the single OpenTelemetry integration point for `@suaveplan/audio-core`. It exposes thin, lazy h…
|
||||
<!-- end:auto-docs -->
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
bun add @suaveplan/audio-core
|
||||
```
|
||||
|
||||
## Quick start
|
||||
|
||||
```ts
|
||||
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`](src/document/document.md) — `AudioDocument` class and JSON round-trip
|
||||
- [`src/page/page.md`](src/page/page.md) — Page primitives: `walkPages`, `copyPages`, `readPages`, allocation pool
|
||||
- [`src/plan/plan-engine.md`](src/plan/plan-engine.md) — `PlanEngine` for compiling and resolving edits
|
||||
- [`src/plan/segment.md`](src/plan/segment.md) — Segment overlap, merge, and split helpers
|
||||
- [`src/process/process-pipeline.md`](src/process/process-pipeline.md) — `ProcessPipeline` for block-level DSP
|
||||
- [`src/process/block-processor.md`](src/process/block-processor.md) — `BlockProcessor` interface and `NoopBlockProcessor`
|
||||
- [`src/registry/op-registry.md`](src/registry/op-registry.md) — `OpRegistry` for registering plan and process ops
|
||||
- [`src/registry/built-in/`](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`](src/render/render.md) — `renderBlock` for copying source segments into output buffers
|
||||
- [`src/stats/stats.md`](src/stats/stats.md) — `computeStats` for peak, RMS, and DC offset
|
||||
- [`src/stream/stream.md`](src/stream/stream.md) — `createPlanTransformStream` for downstream transforms
|
||||
- [`src/error-codes.md`](src/error-codes.md) — Error codes and `AudioError` class
|
||||
|
||||
Reference in New Issue
Block a user