@e9g/buffered-audio-nodes-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,285 @@
+import { z } from 'zod';
+export { ZodType as ModuleSchema } from 'zod';
+import { EventEmitter } from 'node:events';
+
+interface StreamEventMap {
+    started: [];
+    finished: [];
+    progress: [{
+        framesProcessed: number;
+        sourceTotalFrames?: number;
+    }];
+}
+declare abstract class BufferedStream<P extends BufferedAudioNodeProperties = BufferedAudioNodeProperties> {
+    readonly properties: P;
+    readonly events: EventEmitter<StreamEventMap>;
+    constructor(properties: P);
+    _teardown(): Promise<void> | void;
+}
+
+interface AudioChunk {
+    readonly samples: Array<Float32Array>;
+    readonly offset: number;
+    readonly sampleRate: number;
+    readonly bitDepth: number;
+}
+type ExecutionProvider = "gpu" | "cpu-native" | "cpu";
+interface StreamContext {
+    readonly executionProviders: ReadonlyArray<ExecutionProvider>;
+    readonly memoryLimit: number;
+    readonly durationFrames?: number;
+    readonly highWaterMark: number;
+    readonly signal?: AbortSignal;
+    readonly visited: Set<BufferedAudioNode>;
+}
+interface RenderOptions {
+    readonly chunkSize?: number;
+    readonly highWaterMark?: number;
+    readonly memoryLimit?: number;
+    readonly signal?: AbortSignal;
+    readonly executionProviders?: ReadonlyArray<ExecutionProvider>;
+}
+interface BufferedAudioNodeProperties {
+    readonly id?: string;
+    readonly bypass?: boolean;
+    readonly previousProperties?: BufferedAudioNodeProperties;
+    readonly bufferSize?: number;
+    readonly latency?: number;
+    readonly children?: ReadonlyArray<BufferedAudioNode>;
+}
+type BufferedAudioNodeInput<P extends BufferedAudioNodeProperties = BufferedAudioNodeProperties> = P;
+declare abstract class BufferedAudioNode<P extends BufferedAudioNodeProperties = BufferedAudioNodeProperties> {
+    static readonly packageName: string;
+    static readonly moduleName: string;
+    static readonly moduleDescription: string;
+    static readonly schema: z.ZodType;
+    abstract readonly type: ReadonlyArray<string>;
+    static is(value: unknown): value is BufferedAudioNode;
+    properties: P;
+    get id(): string | undefined;
+    get bufferSize(): number;
+    get latency(): number;
+    get isBypassed(): boolean;
+    get children(): ReadonlyArray<BufferedAudioNode>;
+    readonly streams: Array<BufferedStream>;
+    constructor(properties?: P);
+    abstract clone(overrides?: Partial<BufferedAudioNodeProperties>): BufferedAudioNode;
+    teardown(): Promise<void>;
+    _teardown(): Promise<void> | void;
+}
+
+interface FileInputMeta {
+    readonly input: "file" | "folder";
+    readonly mode?: "open" | "save";
+    readonly accept?: string;
+    readonly binary?: string;
+    readonly download?: string;
+}
+
+type BufferStorage = "memory" | "file";
+declare abstract class ChunkBuffer {
+    protected _frames: number;
+    protected _channels: number;
+    private _sampleRate?;
+    private _bitDepth?;
+    get frames(): number;
+    get channels(): number;
+    get sampleRate(): number | undefined;
+    get bitDepth(): number | undefined;
+    setSampleRate(rate: number): void;
+    setBitDepth(depth: number): void;
+    protected validateAndSetMetadata(sampleRate?: number, bitDepth?: number): void;
+    protected buildAudioChunk(samples: Array<Float32Array>, offset: number): AudioChunk;
+    abstract append(samples: Array<Float32Array>, sampleRate?: number, bitDepth?: number): Promise<void>;
+    abstract read(offset: number, frames: number): Promise<AudioChunk>;
+    abstract write(offset: number, samples: Array<Float32Array>): Promise<void>;
+    abstract truncate(frames: number): Promise<void>;
+    abstract iterate(chunkSize: number): AsyncGenerator<AudioChunk>;
+    abstract reset(): Promise<void>;
+    abstract close(): Promise<void>;
+}
+
+declare class FileChunkBuffer extends ChunkBuffer {
+    private tempPath?;
+    private tempHandle?;
+    private fileFramesWritten;
+    private fileChannels;
+    private memoryBuffer;
+    private readonly storageThreshold;
+    private readonly initialBufferSize;
+    private readonly initialChannels;
+    private flushed;
+    constructor(bufferSize: number, channels: number, memoryLimit?: number);
+    private syncMetadata;
+    get filePath(): string | undefined;
+    private ensureFileHandle;
+    private fileOffset;
+    private flushToFile;
+    append(samples: Array<Float32Array>, sampleRate?: number, bitDepth?: number): Promise<void>;
+    private appendFile;
+    read(offset: number, frames: number): Promise<AudioChunk>;
+    private readFile;
+    write(offset: number, samples: Array<Float32Array>): Promise<void>;
+    private writeFile;
+    truncate(frames: number): Promise<void>;
+    iterate(chunkSize: number): AsyncGenerator<AudioChunk>;
+    reset(): Promise<void>;
+    close(): Promise<void>;
+}
+
+declare class MemoryChunkBuffer extends ChunkBuffer {
+    private memoryChannels;
+    private memoryWriteOffset;
+    constructor(bufferSize: number, channels: number);
+    append(samples: Array<Float32Array>, sampleRate?: number, bitDepth?: number): Promise<void>;
+    read(offset: number, frames: number): Promise<AudioChunk>;
+    write(offset: number, samples: Array<Float32Array>): Promise<void>;
+    truncate(frames: number): Promise<void>;
+    iterate(chunkSize: number): AsyncGenerator<AudioChunk>;
+    reset(): Promise<void>;
+    close(): Promise<void>;
+    private appendMemory;
+    private readMemory;
+    private writeMemory;
+}
+
+interface SourceMetadata {
+    readonly sampleRate: number;
+    readonly channels: number;
+    readonly durationFrames?: number;
+}
+interface RenderTiming {
+    readonly totalMs: number;
+    readonly audioDurationMs: number;
+    readonly realTimeMultiplier: number;
+}
+interface SourceNodeProperties extends BufferedAudioNodeProperties {
+}
+declare abstract class BufferedSourceStream<P extends SourceNodeProperties = SourceNodeProperties> extends BufferedStream<P> {
+    private framesRead;
+    abstract getMetadata(): Promise<SourceMetadata>;
+    abstract _read(): Promise<AudioChunk | undefined>;
+    abstract _flush(): Promise<void>;
+    setup(context: StreamContext): Promise<ReadableStream<AudioChunk>>;
+    _setup(context: StreamContext): Promise<ReadableStream<AudioChunk>>;
+}
+declare abstract class SourceNode<P extends SourceNodeProperties = SourceNodeProperties> extends BufferedAudioNode<P> {
+    static is(value: unknown): value is SourceNode;
+    to(child: BufferedAudioNode): void;
+    private renderTimingData?;
+    get renderTiming(): RenderTiming | undefined;
+    protected abstract createStream(): BufferedSourceStream<P>;
+    getMetadata(): Promise<SourceMetadata>;
+    setup(context: StreamContext): Promise<void>;
+    private setupChildren;
+    render(options?: RenderOptions): Promise<void>;
+}
+
+interface TargetNodeProperties extends BufferedAudioNodeProperties {
+}
+declare abstract class BufferedTargetStream<P extends TargetNodeProperties = TargetNodeProperties> extends BufferedStream<P> {
+    private hasStarted;
+    private framesWritten;
+    private sourceTotalFrames?;
+    abstract _write(chunk: AudioChunk): Promise<void>;
+    abstract _close(): Promise<void>;
+    setup(readable: ReadableStream<AudioChunk>, context: StreamContext): Promise<void>;
+    _setup(input: ReadableStream<AudioChunk>, _context: StreamContext): Promise<void>;
+    private createWritableStream;
+}
+declare abstract class TargetNode<P extends TargetNodeProperties = TargetNodeProperties> extends BufferedAudioNode<P> {
+    static is(value: unknown): value is TargetNode;
+    abstract createStream(): BufferedTargetStream<P>;
+    setup(readable: ReadableStream<AudioChunk>, context: StreamContext): Promise<Array<Promise<void>>>;
+}
+
+declare const WHOLE_FILE: number;
+interface TransformNodeProperties extends BufferedAudioNodeProperties {
+    readonly overlap?: number;
+    readonly streamChunkSize?: number;
+}
+declare class BufferedTransformStream<P extends TransformNodeProperties = TransformNodeProperties> extends BufferedStream<P> {
+    bufferSize: number;
+    readonly overlap: number;
+    processingMs: number;
+    framesProcessed: number;
+    private chunkBuffer?;
+    private bufferOffset;
+    private inferredChunkSize?;
+    private hasStarted;
+    protected streamChunkSize?: number;
+    private sourceTotalFrames?;
+    private memoryLimit?;
+    constructor(properties: P);
+    protected get sampleRate(): number | undefined;
+    protected get bitDepth(): number | undefined;
+    private get outputChunkSize();
+    setup(input: ReadableStream<AudioChunk>, context: StreamContext): Promise<ReadableStream<AudioChunk>>;
+    _setup(input: ReadableStream<AudioChunk>, _context: StreamContext): Promise<ReadableStream<AudioChunk>>;
+    createTransformStream(): TransformStream<AudioChunk, AudioChunk>;
+    private handleTransform;
+    private handleFlush;
+    private processAndEmit;
+    private emitBuffer;
+    _buffer(chunk: AudioChunk, buffer: ChunkBuffer): Promise<void> | void;
+    _process(_buffer: ChunkBuffer): Promise<void> | void;
+    _unbuffer(chunk: AudioChunk): Promise<AudioChunk | undefined> | AudioChunk | undefined;
+}
+declare abstract class TransformNode<P extends TransformNodeProperties = TransformNodeProperties> extends BufferedAudioNode<P> {
+    static is(value: unknown): value is TransformNode;
+    to(child: BufferedAudioNode): void;
+    abstract createStream(): BufferedTransformStream;
+    setup(readable: ReadableStream<AudioChunk>, context: StreamContext): Promise<Array<Promise<void>>>;
+    private setupChildren;
+}
+
+declare abstract class CompositeNode extends TransformNode {
+    abstract get head(): BufferedAudioNode;
+    abstract get tail(): BufferedAudioNode;
+    to(child: BufferedAudioNode): void;
+    get children(): ReadonlyArray<BufferedAudioNode>;
+    setup(readable: ReadableStream<AudioChunk>, context: StreamContext): Promise<Array<Promise<void>>>;
+    render(options?: RenderOptions): Promise<void>;
+}
+
+declare const graphNodeSchema: z.ZodObject<{
+    id: z.ZodString;
+    packageName: z.ZodString;
+    nodeName: z.ZodString;
+    parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    options: z.ZodOptional<z.ZodObject<{
+        bypass: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+declare const graphEdgeSchema: z.ZodObject<{
+    from: z.ZodString;
+    to: z.ZodString;
+}, z.core.$strip>;
+declare const graphDefinitionSchema: z.ZodObject<{
+    name: z.ZodDefault<z.ZodString>;
+    nodes: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        packageName: z.ZodString;
+        nodeName: z.ZodString;
+        parameters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        options: z.ZodOptional<z.ZodObject<{
+            bypass: z.ZodOptional<z.ZodBoolean>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    edges: z.ZodArray<z.ZodObject<{
+        from: z.ZodString;
+        to: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+type GraphNode = z.infer<typeof graphNodeSchema>;
+type GraphEdge = z.infer<typeof graphEdgeSchema>;
+type GraphDefinition = z.infer<typeof graphDefinitionSchema>;
+type NodeRegistry = Map<string, Map<string, new (options?: Record<string, unknown>) => BufferedAudioNode>>;
+declare function validateGraphDefinition(json: unknown): GraphDefinition;
+declare function pack(sources: ReadonlyArray<SourceNode>, name?: string): GraphDefinition;
+declare function unpack(definition: GraphDefinition, registry: NodeRegistry): Array<SourceNode>;
+declare function renderGraph(definition: GraphDefinition, registry: NodeRegistry, options?: RenderOptions): Promise<void>;
+
+declare function teeReadable<T>(readable: ReadableStream<AudioChunk>, items: ReadonlyArray<T>): Array<[ReadableStream<AudioChunk>, T]>;
+
+export { type AudioChunk, type BufferStorage, BufferedAudioNode, type BufferedAudioNodeInput, type BufferedAudioNodeProperties, BufferedSourceStream, BufferedStream, BufferedTargetStream, BufferedTransformStream, ChunkBuffer, CompositeNode, type ExecutionProvider, FileChunkBuffer, type FileInputMeta, type GraphDefinition, type GraphEdge, type GraphNode, MemoryChunkBuffer, type NodeRegistry, type RenderOptions, type RenderTiming, type SourceMetadata, SourceNode, type SourceNodeProperties, type StreamContext, type StreamEventMap, TargetNode, type TargetNodeProperties, TransformNode, type TransformNodeProperties, WHOLE_FILE, pack, renderGraph, teeReadable, unpack, validateGraphDefinition };

package/dist/index.js

@@ -0,0 +1,912 @@
+import { randomUUID } from 'crypto';
+import { open, unlink } from 'fs/promises';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { z } from 'zod';
+import { EventEmitter } from 'events';
+
+// src/buffer/index.ts
+var ChunkBuffer = class {
+  constructor() {
+    this._frames = 0;
+    this._channels = 0;
+  }
+  get frames() {
+    return this._frames;
+  }
+  get channels() {
+    return this._channels;
+  }
+  get sampleRate() {
+    return this._sampleRate;
+  }
+  get bitDepth() {
+    return this._bitDepth;
+  }
+  setSampleRate(rate) {
+    this._sampleRate = rate;
+  }
+  setBitDepth(depth) {
+    this._bitDepth = depth;
+  }
+  validateAndSetMetadata(sampleRate, bitDepth) {
+    if (sampleRate !== void 0) {
+      if (this._sampleRate === void 0) {
+        this._sampleRate = sampleRate;
+      } else if (this._sampleRate !== sampleRate) {
+        throw new Error(`ChunkBuffer: sample rate mismatch \u2014 expected ${this._sampleRate}, got ${sampleRate}`);
+      }
+    }
+    if (bitDepth !== void 0) {
+      if (this._bitDepth === void 0) {
+        this._bitDepth = bitDepth;
+      } else if (this._bitDepth !== bitDepth) {
+        throw new Error(`ChunkBuffer: bit depth mismatch \u2014 expected ${this._bitDepth}, got ${bitDepth}`);
+      }
+    }
+  }
+  buildAudioChunk(samples, offset) {
+    return { samples, offset, sampleRate: this._sampleRate ?? 0, bitDepth: this._bitDepth ?? 0 };
+  }
+};
+
+// src/buffer/memory/index.ts
+var MemoryChunkBuffer = class extends ChunkBuffer {
+  constructor(bufferSize, channels) {
+    super();
+    this.memoryChannels = [];
+    this.memoryWriteOffset = 0;
+    this._channels = channels;
+    const initialCapacity = bufferSize === Infinity ? 44100 : bufferSize;
+    for (let ch = 0; ch < channels; ch++) {
+      this.memoryChannels.push(new Float32Array(initialCapacity));
+    }
+  }
+  async append(samples, sampleRate, bitDepth) {
+    const duration = samples[0]?.length ?? 0;
+    if (duration === 0) return;
+    this.validateAndSetMetadata(sampleRate, bitDepth);
+    while (this._channels < samples.length) {
+      const buf = new Float32Array(this.memoryChannels[0]?.length ?? duration);
+      this.memoryChannels.push(buf);
+      this._channels++;
+    }
+    this.appendMemory(samples);
+    this._frames += duration;
+  }
+  async read(offset, frames) {
+    const actualFrames = Math.min(frames, this._frames - offset);
+    if (actualFrames <= 0) {
+      return this.buildAudioChunk([], offset);
+    }
+    return this.readMemory(offset, actualFrames);
+  }
+  async write(offset, samples) {
+    const duration = samples[0]?.length ?? 0;
+    if (duration === 0) return;
+    while (this._channels < samples.length) {
+      const buf = new Float32Array(this.memoryChannels[0]?.length ?? duration);
+      this.memoryChannels.push(buf);
+      this._channels++;
+    }
+    const endFrame = offset + duration;
+    if (endFrame > this._frames) {
+      this._frames = endFrame;
+    }
+    this.writeMemory(offset, samples);
+  }
+  async truncate(frames) {
+    if (frames >= this._frames) return;
+    this.memoryWriteOffset = frames;
+    this._frames = frames;
+  }
+  async *iterate(chunkSize) {
+    let offset = 0;
+    while (offset < this._frames) {
+      const frames = Math.min(chunkSize, this._frames - offset);
+      const chunk = await this.read(offset, frames);
+      yield chunk;
+      offset += frames;
+    }
+  }
+  async reset() {
+    this._frames = 0;
+    this.memoryWriteOffset = 0;
+  }
+  async close() {
+    this.memoryChannels = [];
+    this.memoryWriteOffset = 0;
+    this._frames = 0;
+    this._channels = 0;
+  }
+  appendMemory(samples) {
+    const required = this.memoryWriteOffset + (samples[0]?.length ?? 0);
+    for (let ch = 0; ch < samples.length; ch++) {
+      const channel = samples[ch];
+      if (!channel) continue;
+      let buf = this.memoryChannels[ch];
+      if (!buf) continue;
+      if (required > buf.length) {
+        const newBuf = new Float32Array(Math.max(required, buf.length * 2));
+        newBuf.set(buf.subarray(0, this.memoryWriteOffset));
+        this.memoryChannels[ch] = newBuf;
+        buf = newBuf;
+      }
+      buf.set(channel, this.memoryWriteOffset);
+    }
+    this.memoryWriteOffset = required;
+  }
+  readMemory(offset, frames) {
+    const samples = [];
+    for (let ch = 0; ch < this._channels; ch++) {
+      const buf = this.memoryChannels[ch];
+      samples.push(buf ? buf.slice(offset, offset + frames) : new Float32Array(frames));
+    }
+    return this.buildAudioChunk(samples, offset);
+  }
+  writeMemory(offset, samples) {
+    for (let ch = 0; ch < samples.length; ch++) {
+      const source = samples[ch];
+      if (!source) continue;
+      let buf = this.memoryChannels[ch];
+      if (!buf) continue;
+      const needed = offset + source.length;
+      if (needed > buf.length) {
+        const newBuf = new Float32Array(Math.max(needed, buf.length * 2));
+        newBuf.set(buf.subarray(0, this.memoryWriteOffset));
+        this.memoryChannels[ch] = newBuf;
+        buf = newBuf;
+      }
+      buf.set(source, offset);
+      if (needed > this.memoryWriteOffset) {
+        this.memoryWriteOffset = needed;
+      }
+    }
+  }
+};
+
+// src/buffer/file/index.ts
+var DEFAULT_STORAGE_THRESHOLD = 10 * 1024 * 1024;
+var FileChunkBuffer = class extends ChunkBuffer {
+  constructor(bufferSize, channels, memoryLimit) {
+    super();
+    this.fileFramesWritten = 0;
+    this.flushed = false;
+    this.storageThreshold = memoryLimit ? Math.max(1024 * 1024, Math.min(memoryLimit * 0.04, 64 * 1024 * 1024)) : DEFAULT_STORAGE_THRESHOLD;
+    this._channels = channels;
+    this.fileChannels = channels;
+    this.initialBufferSize = bufferSize;
+    this.initialChannels = channels;
+    this.memoryBuffer = new MemoryChunkBuffer(bufferSize, channels);
+  }
+  syncMetadata() {
+    this._frames = this.memoryBuffer.frames;
+    this._channels = this.memoryBuffer.channels;
+    if (this.memoryBuffer.sampleRate) this.setSampleRate(this.memoryBuffer.sampleRate);
+    if (this.memoryBuffer.bitDepth) this.setBitDepth(this.memoryBuffer.bitDepth);
+  }
+  get filePath() {
+    return this.flushed ? this.tempPath : void 0;
+  }
+  async ensureFileHandle() {
+    if (!this.tempHandle) {
+      this.tempPath = join(tmpdir(), `chunk-buffer-${randomUUID()}.bin`);
+      this.tempHandle = await open(this.tempPath, "w+");
+      this.fileFramesWritten = 0;
+      this.fileChannels = this._channels;
+    }
+    return this.tempHandle;
+  }
+  fileOffset(frame, channel) {
+    return (frame * this.fileChannels + channel) * 4;
+  }
+  async flushToFile() {
+    const channels = this.memoryBuffer.channels;
+    const frames = this.memoryBuffer.frames;
+    const handle = await this.ensureFileHandle();
+    let filePos = 0;
+    for await (const chunk of this.memoryBuffer.iterate(8192)) {
+      const chunkFrames = chunk.samples[0]?.length ?? 0;
+      const interleaved = new Float32Array(chunkFrames * channels);
+      for (let frame = 0; frame < chunkFrames; frame++) {
+        const base = frame * channels;
+        for (let ch = 0; ch < channels; ch++) {
+          interleaved[base + ch] = chunk.samples[ch]?.[frame] ?? 0;
+        }
+      }
+      const buf = Buffer.from(interleaved.buffer, interleaved.byteOffset, interleaved.byteLength);
+      await handle.write(buf, 0, buf.length, filePos);
+      filePos += buf.length;
+    }
+    this.fileFramesWritten = frames;
+    this.flushed = true;
+  }
+  async append(samples, sampleRate, bitDepth) {
+    const duration = samples[0]?.length ?? 0;
+    if (duration === 0) return;
+    if (this.flushed) {
+      this.validateAndSetMetadata(sampleRate, bitDepth);
+      while (this._channels < samples.length) {
+        this._channels++;
+      }
+      await this.appendFile(samples, duration);
+    } else {
+      await this.memoryBuffer.append(samples, sampleRate, bitDepth);
+      this.syncMetadata();
+      if (this.memoryBuffer.frames * this.memoryBuffer.channels * 4 > this.storageThreshold) {
+        await this.flushToFile();
+      }
+    }
+  }
+  async appendFile(samples, duration) {
+    const handle = await this.ensureFileHandle();
+    const channels = this._channels;
+    const interleaved = new Float32Array(duration * channels);
+    for (let frame = 0; frame < duration; frame++) {
+      const base = frame * channels;
+      for (let ch = 0; ch < channels; ch++) {
+        interleaved[base + ch] = samples[ch]?.[frame] ?? 0;
+      }
+    }
+    const buf = Buffer.from(interleaved.buffer, interleaved.byteOffset, interleaved.byteLength);
+    const offset = this.fileOffset(this.fileFramesWritten, 0);
+    await handle.write(buf, 0, buf.length, offset);
+    this.fileFramesWritten += duration;
+    this._frames += duration;
+  }
+  async read(offset, frames) {
+    const actualFrames = Math.min(frames, this._frames - offset);
+    if (actualFrames <= 0) {
+      return this.buildAudioChunk([], offset);
+    }
+    if (this.flushed) {
+      return this.readFile(offset, actualFrames);
+    }
+    return this.memoryBuffer.read(offset, actualFrames);
+  }
+  async readFile(offset, actualFrames) {
+    if (!this.tempHandle) {
+      return this.buildAudioChunk([], offset);
+    }
+    const channels = this.fileChannels;
+    const byteLength = actualFrames * channels * 4;
+    const buf = Buffer.alloc(byteLength);
+    const filePos = this.fileOffset(offset, 0);
+    await this.tempHandle.read(buf, 0, byteLength, filePos);
+    const interleaved = new Float32Array(buf.buffer, buf.byteOffset, actualFrames * channels);
+    const samples = [];
+    for (let ch = 0; ch < this._channels; ch++) {
+      samples.push(new Float32Array(actualFrames));
+    }
+    for (let frame = 0; frame < actualFrames; frame++) {
+      const base = frame * channels;
+      for (let ch = 0; ch < channels; ch++) {
+        const channel = samples[ch];
+        if (channel) {
+          channel[frame] = interleaved[base + ch];
+        }
+      }
+    }
+    return this.buildAudioChunk(samples, offset);
+  }
+  async write(offset, samples) {
+    const duration = samples[0]?.length ?? 0;
+    if (duration === 0) return;
+    if (this.flushed) {
+      while (this._channels < samples.length) {
+        this._channels++;
+      }
+      const endFrame = offset + duration;
+      if (endFrame > this._frames) {
+        this._frames = endFrame;
+      }
+      await this.writeFile(offset, samples, duration);
+    } else {
+      await this.memoryBuffer.write(offset, samples);
+      this.syncMetadata();
+      if (this.memoryBuffer.frames * this.memoryBuffer.channels * 4 > this.storageThreshold) {
+        await this.flushToFile();
+      }
+    }
+  }
+  async writeFile(offset, samples, duration) {
+    const handle = await this.ensureFileHandle();
+    const channels = this._channels;
+    const interleaved = new Float32Array(duration * channels);
+    for (let frame = 0; frame < duration; frame++) {
+      const base = frame * channels;
+      for (let ch = 0; ch < channels; ch++) {
+        interleaved[base + ch] = samples[ch]?.[frame] ?? 0;
+      }
+    }
+    const buf = Buffer.from(interleaved.buffer, interleaved.byteOffset, interleaved.byteLength);
+    const filePos = this.fileOffset(offset, 0);
+    await handle.write(buf, 0, buf.length, filePos);
+    if (offset + duration > this.fileFramesWritten) {
+      this.fileFramesWritten = offset + duration;
+    }
+  }
+  async truncate(frames) {
+    if (frames >= this._frames) return;
+    if (this.flushed) {
+      if (this.tempHandle) {
+        await this.tempHandle.truncate(frames * this.fileChannels * 4);
+        this.fileFramesWritten = frames;
+      }
+      this._frames = frames;
+    } else {
+      await this.memoryBuffer.truncate(frames);
+      this.syncMetadata();
+    }
+  }
+  async *iterate(chunkSize) {
+    if (!this.flushed) {
+      yield* this.memoryBuffer.iterate(chunkSize);
+      return;
+    }
+    let offset = 0;
+    while (offset < this._frames) {
+      const frames = Math.min(chunkSize, this._frames - offset);
+      const chunk = await this.readFile(offset, frames);
+      yield chunk;
+      offset += frames;
+    }
+  }
+  async reset() {
+    if (this.flushed) {
+      if (this.tempHandle) {
+        await this.tempHandle.close();
+        this.tempHandle = void 0;
+      }
+      if (this.tempPath) {
+        await unlink(this.tempPath).catch(() => void 0);
+        this.tempPath = void 0;
+      }
+      this.fileFramesWritten = 0;
+    }
+    this.memoryBuffer = new MemoryChunkBuffer(this.initialBufferSize, this.initialChannels);
+    this.flushed = false;
+    this._frames = 0;
+  }
+  async close() {
+    if (this.tempHandle) {
+      await this.tempHandle.close();
+      this.tempHandle = void 0;
+    }
+    if (this.tempPath) {
+      await unlink(this.tempPath).catch(() => void 0);
+      this.tempPath = void 0;
+    }
+    await this.memoryBuffer.close();
+    this.flushed = false;
+    this._frames = 0;
+    this._channels = 0;
+    this.fileFramesWritten = 0;
+  }
+};
+var BufferedAudioNode = class {
+  constructor(properties) {
+    this.streams = [];
+    this.properties = {
+      ...properties
+    };
+  }
+  static is(value) {
+    return typeof value === "object" && value !== null && "type" in value && Array.isArray(value.type) && value.type[0] === "buffered-audio-node";
+  }
+  get id() {
+    return this.properties.id;
+  }
+  get bufferSize() {
+    return this.properties.bufferSize ?? 0;
+  }
+  get latency() {
+    return this.properties.latency ?? 0;
+  }
+  get isBypassed() {
+    return this.properties.bypass === true;
+  }
+  get children() {
+    const raw = this.properties.children ?? [];
+    const resolved = [];
+    for (const child of raw) {
+      if (child.isBypassed) {
+        resolved.push(...child.children);
+      } else {
+        resolved.push(child);
+      }
+    }
+    return resolved;
+  }
+  async teardown() {
+    await this._teardown();
+    for (const stream of this.streams) {
+      await stream._teardown();
+    }
+    this.streams.length = 0;
+    for (const child of this.children) {
+      await child.teardown();
+    }
+  }
+  _teardown() {
+    return;
+  }
+};
+BufferedAudioNode.moduleDescription = "";
+BufferedAudioNode.schema = z.object({});
+var BufferedStream = class {
+  constructor(properties) {
+    this.events = new EventEmitter();
+    this.properties = properties;
+  }
+  _teardown() {
+    return;
+  }
+};
+
+// src/target.ts
+var BufferedTargetStream = class extends BufferedStream {
+  constructor() {
+    super(...arguments);
+    this.hasStarted = false;
+    this.framesWritten = 0;
+  }
+  setup(readable, context) {
+    this.sourceTotalFrames = context.durationFrames;
+    return this._setup(readable, context);
+  }
+  async _setup(input, _context) {
+    return input.pipeTo(this.createWritableStream());
+  }
+  createWritableStream() {
+    this.hasStarted = false;
+    this.framesWritten = 0;
+    return new WritableStream({
+      write: async (chunk) => {
+        if (!this.hasStarted) {
+          this.hasStarted = true;
+          this.events.emit("started");
+        }
+        await this._write(chunk);
+        this.framesWritten += chunk.samples[0]?.length ?? 0;
+        this.events.emit("progress", { framesProcessed: this.framesWritten, sourceTotalFrames: this.sourceTotalFrames });
+      },
+      close: async () => {
+        await this._close();
+        this.events.emit("finished");
+      }
+    });
+  }
+};
+var TargetNode = class extends BufferedAudioNode {
+  static is(value) {
+    return BufferedAudioNode.is(value) && value.type[1] === "target";
+  }
+  setup(readable, context) {
+    const stream = this.createStream();
+    this.streams.push(stream);
+    return Promise.resolve([stream.setup(readable, context)]);
+  }
+};
+
+// src/utils/tee-readable.ts
+function teeReadable(readable, items) {
+  if (items.length === 0) return [];
+  const first = items[0];
+  if (items.length === 1) return [[readable, first]];
+  const pairs = [];
+  let current = readable;
+  for (let offset = 0; offset < items.length - 1; offset++) {
+    const [left, right] = current.tee();
+    pairs.push([left, items[offset]]);
+    current = right;
+  }
+  pairs.push([current, items[items.length - 1]]);
+  return pairs;
+}
+
+// src/transform.ts
+var WHOLE_FILE = Infinity;
+var BufferedTransformStream = class extends BufferedStream {
+  constructor(properties) {
+    super(properties);
+    this.processingMs = 0;
+    this.framesProcessed = 0;
+    this.bufferOffset = 0;
+    this.hasStarted = false;
+    this.bufferSize = properties.bufferSize ?? 0;
+    this.overlap = properties.overlap ?? 0;
+    this.streamChunkSize = properties.streamChunkSize;
+  }
+  get sampleRate() {
+    return this.chunkBuffer?.sampleRate;
+  }
+  get bitDepth() {
+    return this.chunkBuffer?.bitDepth;
+  }
+  get outputChunkSize() {
+    return this.streamChunkSize ?? this.inferredChunkSize ?? 44100;
+  }
+  setup(input, context) {
+    this.sourceTotalFrames = context.durationFrames;
+    this.memoryLimit = context.memoryLimit;
+    return this._setup(input, context);
+  }
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async _setup(input, _context) {
+    return input.pipeThrough(this.createTransformStream());
+  }
+  createTransformStream() {
+    return new TransformStream({
+      transform: (chunk, controller) => this.handleTransform(chunk, controller),
+      flush: (controller) => this.handleFlush(controller)
+    });
+  }
+  async handleTransform(chunk, controller) {
+    if (!this.hasStarted) {
+      this.hasStarted = true;
+      this.events.emit("started");
+    }
+    const chunkFrames = chunk.samples[0]?.length ?? 0;
+    this.inferredChunkSize ?? (this.inferredChunkSize = chunkFrames);
+    const channels = chunk.samples.length;
+    this.chunkBuffer ?? (this.chunkBuffer = new FileChunkBuffer(this.bufferSize, channels, this.memoryLimit));
+    const samplesIn = chunkFrames;
+    const start = performance.now();
+    await this._buffer(chunk, this.chunkBuffer);
+    if (this.bufferSize === 0) {
+      await this.emitBuffer(controller);
+      this.processingMs += performance.now() - start;
+      this.framesProcessed += samplesIn;
+      this.events.emit("progress", { framesProcessed: this.framesProcessed, sourceTotalFrames: this.sourceTotalFrames });
+      return;
+    }
+    if (this.bufferSize !== WHOLE_FILE && this.chunkBuffer.frames >= this.bufferSize) {
+      await this.processAndEmit(controller);
+      this.events.emit("progress", { framesProcessed: this.framesProcessed, sourceTotalFrames: this.sourceTotalFrames });
+    } else {
+      this.processingMs += performance.now() - start;
+      this.framesProcessed += samplesIn;
+      this.events.emit("progress", { framesProcessed: this.framesProcessed, sourceTotalFrames: this.sourceTotalFrames });
+    }
+  }
+  async handleFlush(controller) {
+    if (!this.chunkBuffer || this.chunkBuffer.frames === 0) {
+      this.events.emit("finished");
+      return;
+    }
+    if (this.bufferSize === 0) {
+      await this.chunkBuffer.close();
+      this.events.emit("finished");
+      return;
+    }
+    try {
+      await this.processAndEmit(controller);
+    } finally {
+      await this.chunkBuffer.close();
+      this.chunkBuffer = void 0;
+    }
+    this.events.emit("finished");
+  }
+  async processAndEmit(controller) {
+    if (!this.chunkBuffer) return;
+    const samplesBeforeProcess = this.chunkBuffer.frames;
+    const start = performance.now();
+    await this._process(this.chunkBuffer);
+    await this.emitBuffer(controller);
+    this.processingMs += performance.now() - start;
+    this.framesProcessed += samplesBeforeProcess;
+  }
+  async emitBuffer(controller) {
+    if (!this.chunkBuffer) return;
+    const emitSize = this.bufferSize === 0 ? this.chunkBuffer.frames : this.outputChunkSize;
+    for await (const chunk of this.chunkBuffer.iterate(emitSize)) {
+      const adjusted = {
+        samples: chunk.samples,
+        offset: this.bufferOffset + chunk.offset,
+        sampleRate: chunk.sampleRate,
+        bitDepth: chunk.bitDepth
+      };
+      const result = await this._unbuffer(adjusted);
+      if (result) {
+        controller.enqueue(result);
+      }
+    }
+    this.bufferOffset += this.chunkBuffer.frames;
+    if (this.overlap > 0 && this.bufferSize !== WHOLE_FILE) {
+      const overlapStart = this.chunkBuffer.frames - this.overlap;
+      if (overlapStart > 0) {
+        const overlapChunk = await this.chunkBuffer.read(overlapStart, this.overlap);
+        await this.chunkBuffer.reset();
+        await this.chunkBuffer.append(overlapChunk.samples, overlapChunk.sampleRate, overlapChunk.bitDepth);
+        this.bufferOffset -= this.overlap;
+      }
+    } else {
+      await this.chunkBuffer.reset();
+    }
+  }
+  _buffer(chunk, buffer) {
+    return buffer.append(chunk.samples, chunk.sampleRate, chunk.bitDepth);
+  }
+  _process(_buffer) {
+    return;
+  }
+  _unbuffer(chunk) {
+    return chunk;
+  }
+};
+var TransformNode = class _TransformNode extends BufferedAudioNode {
+  static is(value) {
+    return BufferedAudioNode.is(value) && value.type[1] === "transform";
+  }
+  to(child) {
+    this.properties = { ...this.properties, children: [...this.properties.children ?? [], child] };
+  }
+  async setup(readable, context) {
+    const stream = this.createStream();
+    this.streams.push(stream);
+    const output = await stream.setup(readable, context);
+    return this.setupChildren(output, context);
+  }
+  async setupChildren(readable, context) {
+    const resolved = this.children;
+    const pairs = teeReadable(readable, resolved);
+    const nested = await Promise.all(
+      pairs.map(async ([stream, child]) => {
+        if (context.visited.has(child)) throw new Error("Cycle detected in node graph");
+        context.visited.add(child);
+        if (child instanceof _TransformNode || child instanceof TargetNode) return child.setup(stream, context);
+        throw new Error(`Unknown child node type`);
+      })
+    );
+    return nested.flat();
+  }
+};
+
+// src/source.ts
+var BufferedSourceStream = class extends BufferedStream {
+  constructor() {
+    super(...arguments);
+    this.framesRead = 0;
+  }
+  setup(context) {
+    return this._setup(context);
+  }
+  // eslint-disable-next-line @typescript-eslint/require-await
+  async _setup(context) {
+    let done = false;
+    this.framesRead = 0;
+    const { signal, durationFrames: sourceTotalFrames, highWaterMark } = context;
+    return new ReadableStream(
+      {
+        pull: async (controller) => {
+          if (done) return;
+          if (signal?.aborted) {
+            done = true;
+            controller.close();
+            return;
+          }
+          try {
+            const chunk = await this._read();
+            if (!chunk) {
+              done = true;
+              await this._flush();
+              controller.close();
+              return;
+            }
+            this.framesRead += chunk.samples[0]?.length ?? 0;
+            controller.enqueue(chunk);
+            this.events.emit("progress", { framesProcessed: this.framesRead, sourceTotalFrames });
+          } catch (error) {
+            done = true;
+            controller.error(error);
+          }
+        },
+        cancel: () => {
+          done = true;
+        }
+      },
+      { highWaterMark }
+    );
+  }
+};
+var SourceNode = class extends BufferedAudioNode {
+  static is(value) {
+    return BufferedAudioNode.is(value) && value.type[1] === "source";
+  }
+  to(child) {
+    this.properties = { ...this.properties, children: [...this.properties.children ?? [], child] };
+  }
+  get renderTiming() {
+    return this.renderTimingData;
+  }
+  async getMetadata() {
+    const stream = this.createStream();
+    return stream.getMetadata();
+  }
+  async setup(context) {
+    const stream = this.createStream();
+    this.streams.push(stream);
+    const readable = await stream.setup(context);
+    const promises = await this.setupChildren(readable, context);
+    await Promise.all(promises);
+  }
+  async setupChildren(readable, context) {
+    const resolved = this.children;
+    const pairs = teeReadable(readable, resolved);
+    const nested = await Promise.all(
+      pairs.map(async ([stream, child]) => {
+        if (context.visited.has(child)) throw new Error("Cycle detected in node graph");
+        context.visited.add(child);
+        if (child instanceof TargetNode || child instanceof TransformNode) return child.setup(stream, context);
+        throw new Error(`Unknown child node type`);
+      })
+    );
+    return nested.flat();
+  }
+  async render(options) {
+    const defaultProviders = ["gpu", "cpu-native", "cpu"];
+    const memoryLimit = options?.memoryLimit ?? 256 * 1024 * 1024;
+    const meta = await this.getMetadata();
+    const stages = Math.max(1, countNodes(this));
+    const chunkSize = options?.chunkSize ?? 128 * 1024;
+    const bytesPerChunk = meta.channels * chunkSize * 4;
+    const computedHighWaterMark = Math.max(1, Math.floor(memoryLimit / (stages * bytesPerChunk)));
+    const context = {
+      executionProviders: options?.executionProviders ?? defaultProviders,
+      memoryLimit,
+      durationFrames: meta.durationFrames,
+      highWaterMark: options?.highWaterMark ?? computedHighWaterMark,
+      signal: options?.signal,
+      visited: /* @__PURE__ */ new Set()
+    };
+    const start = performance.now();
+    try {
+      await this.setup(context);
+    } finally {
+      const totalMs = performance.now() - start;
+      const audioDurationMs = meta.durationFrames !== void 0 ? meta.durationFrames / meta.sampleRate * 1e3 : 0;
+      this.renderTimingData = {
+        totalMs,
+        audioDurationMs,
+        realTimeMultiplier: audioDurationMs > 0 ? audioDurationMs / totalMs : 0
+      };
+      await this.teardown();
+    }
+  }
+};
+function countNodes(node) {
+  let count = 0;
+  for (const child of node.children) {
+    count += 1 + countNodes(child);
+  }
+  return count;
+}
+
+// src/composite.ts
+var CompositeNode = class extends TransformNode {
+  to(child) {
+    if (!(this.tail instanceof SourceNode) && !(this.tail instanceof TransformNode)) {
+      throw new Error("Cannot connect downstream from a TargetNode \u2014 this composite is a complete pipeline");
+    }
+    this.tail.to(child);
+  }
+  get children() {
+    return [this.head];
+  }
+  async setup(readable, context) {
+    if (!(this.head instanceof TransformNode)) {
+      throw new Error("Cannot setup a composite whose head is a SourceNode \u2014 use render() for complete pipelines");
+    }
+    return this.head.setup(readable, context);
+  }
+  async render(options) {
+    if (!(this.head instanceof SourceNode)) {
+      throw new Error("Cannot render a composite whose head is not a SourceNode");
+    }
+    return this.head.render(options);
+  }
+};
+var graphNodeSchema = z.object({
+  id: z.string().min(1),
+  packageName: z.string().min(1),
+  nodeName: z.string().min(1),
+  parameters: z.record(z.string(), z.unknown()).optional(),
+  options: z.object({
+    bypass: z.boolean().optional()
+  }).optional()
+});
+var graphEdgeSchema = z.object({
+  from: z.string().min(1),
+  to: z.string().min(1)
+});
+var graphDefinitionSchema = z.object({
+  name: z.string().default("Untitled"),
+  nodes: z.array(graphNodeSchema),
+  edges: z.array(graphEdgeSchema)
+});
+function validateGraphDefinition(json) {
+  return graphDefinitionSchema.parse(json);
+}
+function pack(sources, name) {
+  const visited = /* @__PURE__ */ new Set();
+  const nodes = [];
+  const edges = [];
+  const ensureId = (node) => {
+    if (node.id) return node.id;
+    const id = randomUUID();
+    node.properties = { ...node.properties, id };
+    return id;
+  };
+  const walk = (node) => {
+    if (visited.has(node)) return;
+    visited.add(node);
+    const ctor = node.constructor;
+    const id = ensureId(node);
+    const parameters = ctor.schema.parse(node.properties);
+    const options = {};
+    if (node.isBypassed) options.bypass = true;
+    const graphNode = {
+      id,
+      packageName: ctor.packageName,
+      nodeName: ctor.moduleName,
+      ...Object.keys(parameters).length > 0 && { parameters },
+      ...Object.keys(options).length > 0 && { options }
+    };
+    nodes.push(graphNode);
+    const rawChildren = node.properties.children ?? [];
+    for (const child of rawChildren) {
+      edges.push({ from: id, to: ensureId(child) });
+      walk(child);
+    }
+  };
+  for (const source of sources) {
+    walk(source);
+  }
+  return graphDefinitionSchema.parse({ name: name ?? "Untitled", nodes, edges });
+}
+function unpack(definition, registry) {
+  const nodeMap = /* @__PURE__ */ new Map();
+  for (const nodeDef of definition.nodes) {
+    const packageModules = registry.get(nodeDef.packageName);
+    if (!packageModules) throw new Error(`Unknown package: "${nodeDef.packageName}"`);
+    const NodeClass = packageModules.get(nodeDef.nodeName);
+    if (!NodeClass) throw new Error(`Unknown node: "${nodeDef.nodeName}" in package "${nodeDef.packageName}"`);
+    const instance = new NodeClass(nodeDef.parameters);
+    if (nodeDef.options?.bypass) {
+      instance.properties = { ...instance.properties, bypass: nodeDef.options.bypass };
+    }
+    nodeMap.set(nodeDef.id, instance);
+  }
+  for (const edge of definition.edges) {
+    const fromNode = nodeMap.get(edge.from);
+    const toNode = nodeMap.get(edge.to);
+    if (!fromNode) throw new Error(`Edge references unknown node: "${edge.from}"`);
+    if (!toNode) throw new Error(`Edge references unknown node: "${edge.to}"`);
+    if (fromNode instanceof SourceNode || fromNode instanceof TransformNode) {
+      fromNode.to(toNode);
+    } else {
+      throw new Error(`Cannot connect from target node "${edge.from}"`);
+    }
+  }
+  const targetIds = new Set(definition.edges.map((edge) => edge.to));
+  const sources = [];
+  for (const nodeDef of definition.nodes) {
+    if (!targetIds.has(nodeDef.id)) {
+      const node = nodeMap.get(nodeDef.id);
+      if (SourceNode.is(node)) {
+        sources.push(node);
+      }
+    }
+  }
+  if (sources.length === 0) {
+    throw new Error("No source nodes found in graph definition");
+  }
+  return sources;
+}
+async function renderGraph(definition, registry, options) {
+  const sources = unpack(definition, registry);
+  await Promise.all(sources.map((source) => source.render(options)));
+}
+
+export { BufferedAudioNode, BufferedSourceStream, BufferedStream, BufferedTargetStream, BufferedTransformStream, ChunkBuffer, CompositeNode, FileChunkBuffer, MemoryChunkBuffer, SourceNode, TargetNode, TransformNode, WHOLE_FILE, pack, renderGraph, teeReadable, unpack, validateGraphDefinition };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@e9g/buffered-audio-nodes-core",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "author": "Matt Cavender",
+  "license": "ISC",
+  "scripts": {
+    "check": "concurrently \"eslint . --fix --cache --format ../../agent-eslint.js\" \"tsc --noEmit --pretty false 2>&1 | node ../../agent-tsc.js\"",
+    "check:verbose": "concurrently \"eslint .\" \"tsc --noEmit\"",
+    "lint": "eslint . --fix --cache --format ../../agent-eslint.js",
+    "lint:verbose": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "build": "tsup",
+    "unit": "vitest run unit"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.5",
+    "concurrently": "*",
+    "tsup": "^8.0.0",
+    "typescript": "*",
+    "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.3.6"
+  }
+}