@libraz/libsonare 1.5.4 → 1.6.0

package/src/sonare.js.d.ts

@@ -2,7 +2,12 @@
  * Type declarations for the Emscripten-generated WASM module with embind
  */
 
-import type { SpectralRegionOp, SurroundPan } from './public_types';
+import type {
+  ProgressCallback,
+  SonareCapabilities,
+  SpectralRegionOp,
+  SurroundPan,
+} from './public_types';
 
 export interface SonareModuleOptions {
   locateFile?: (path: string, prefix: string) => string;
@@ -133,8 +138,10 @@ export interface WasmMelodyContourResult {
 export interface WasmAnalysisResult {
   bpm: number;
   bpmConfidence: number;
+  bpmCandidates: WasmBpmHypothesis[];
   key: WasmKeyResult;
   timeSignature: WasmTimeSignatureResult;
+  timeSignatureCandidates: WasmTimeSignatureResult[];
   beats: WasmBeatResult[];
   chords: WasmChordResult[];
   sections: WasmSectionResult[];
@@ -145,6 +152,12 @@ export interface WasmAnalysisResult {
   form: string;
 }
 
+export interface WasmBpmHypothesis {
+  value: number;
+  confidence: number;
+  relation: 'primary' | 'half' | 'double' | 'other';
+}
+
 export interface WasmBpmCandidate {
   bpm: number;
   confidence: number;
@@ -324,6 +337,12 @@ export interface WasmMatrix2dResult {
   cols: number;
 }
 
+export interface WasmSegmentMatrixResult {
+  rows: number;
+  cols: number;
+  values: Float32Array;
+}
+
 export interface WasmDecomposeResult {
   w: Float32Array;
   h: Float32Array;
@@ -390,6 +409,14 @@ export interface WasmPitchResult {
   meanF0: number;
 }
 
+export interface WasmNoteSegment {
+  frameStart: number;
+  frameEnd: number;
+  startSeconds: number;
+  endSeconds: number;
+  medianCents: number;
+}
+
 export interface WasmTrimResult {
   audio: Float32Array;
   startSample: number;
@@ -458,6 +485,8 @@ export interface WasmLufsResult {
   integratedLufs: number;
   momentaryLufs: number;
   shortTermLufs: number;
+  maxMomentaryLufs: number;
+  maxShortTermLufs: number;
   loudnessRange: number;
 }
 
@@ -467,6 +496,7 @@ export interface WasmMasteringResult {
   inputLufs: number;
   outputLufs: number;
   appliedGainDb: number;
+  loudnessTargetLimited?: boolean;
   latencySamples?: number;
 }
 
@@ -475,11 +505,30 @@ export interface WasmStageGainReduction {
   gainReductionDb: number;
 }
 
+export interface WasmMasteringLoudnessSummary {
+  integratedLufs: number;
+  maxMomentaryLufs: number;
+  maxShortTermLufs: number;
+  truePeakDbtp: number;
+  loudnessRange: number;
+}
+
+export interface WasmMasteringReport {
+  before: WasmMasteringLoudnessSummary;
+  after: WasmMasteringLoudnessSummary;
+  appliedGainDb: number;
+  maxGainReductionDb: number;
+  loudnessTargetLimited: boolean;
+  bandEnergyDeltaDb: Float32Array;
+}
+
 export interface WasmMasteringChainResult extends WasmMasteringResult {
   stages: string[];
   outputTruePeakDbtp: number;
   outputLra: number;
+  loudnessTargetLimited: boolean;
   stageGainReductions: WasmStageGainReduction[];
+  report: WasmMasteringReport;
 }
 
 export interface WasmMasteringStereoChainResult {
@@ -492,7 +541,9 @@ export interface WasmMasteringStereoChainResult {
   stages: string[];
   outputTruePeakDbtp: number;
   outputLra: number;
+  loudnessTargetLimited: boolean;
   stageGainReductions: WasmStageGainReduction[];
+  report: WasmMasteringReport;
 }
 
 export interface WasmMasteringStereoResult {
@@ -619,13 +670,44 @@ export interface WasmProjectMarker {
   keyFifths?: number;
   keyMinor?: boolean;
 }
+export interface WasmProjectTrack {
+  id: number;
+  kind: number;
+  midiDestinationId: number;
+  gain: number;
+  pan: number;
+  mute: boolean;
+  solo: boolean;
+  name: string;
+}
+export interface WasmProjectClip {
+  id: number;
+  trackId: number;
+  sourceId: number;
+  sourceKind: number;
+  startPpq: number;
+  lengthPpq: number;
+  sourceOffsetPpq: number;
+  gain: number;
+  loopMode: number;
+  loopLengthPpq: number;
+}
+export interface WasmProjectSource {
+  id: number;
+  kind: number;
+  channelCount: number;
+  storageHandleId: number;
+  sampleRateHint: number;
+  nameOrUri: string;
+}
 
 export interface WasmEngineMetronomeConfig {
   enabled: boolean;
   beatGain?: number;
   accentGain?: number;
+  /** Explicit click length in samples (0..384000). The engine caps it to one second at its sample rate. */
   clickSamples?: number;
-  /** Optional click length in seconds; > 0 overrides the engine 2 ms default. */
+  /** Optional click length in seconds (0..1); > 0 overrides the engine 2 ms default. */
   clickSeconds?: number;
 }
 
@@ -837,6 +919,7 @@ export interface WasmRealtimeEngine {
   stop: (renderFrame: number) => void;
   seekSample: (timelineSample: number, renderFrame: number) => void;
   settleParameters: () => void;
+  flushControlCommands: () => void;
   seekPpq: (ppq: number, renderFrame: number) => void;
   setTempo: (bpm: number) => void;
   setTempoSegments: (segments: WasmEngineTempoSegment[]) => void;
@@ -920,10 +1003,14 @@ export interface WasmRealtimeEngine {
   clearClipPage: (providerId: number, pageIndex: number) => void;
   destroyClipPageProvider: (providerId: number) => void;
   popClipPageRequest: () => WasmClipPageRequest | null;
+  popClipPageRequestToScratch: () => boolean;
+  clipPageRequestScratchClipId: () => number;
+  clipPageRequestScratchSample: () => number;
+  clipPageRequestOverflowCount: () => number;
   setCaptureBuffer: (numChannels: number, capacityFrames: number) => void;
   armCapture: (armed: boolean) => void;
   setCapturePunch: (startSample: number, endSample: number, enabled: boolean) => void;
-  setCaptureSource: (source: WasmEngineCaptureStatus['source']) => void;
+  setCaptureSource: (source: WasmEngineCaptureStatus['source'] | number) => void;
   setRecordOffsetSamples: (offsetSamples: number) => void;
   setInputMonitor: (enabled: boolean, gain: number) => void;
   resetCapture: () => void;
@@ -943,6 +1030,7 @@ export interface WasmRealtimeEngine {
     minValue: number,
     maxValue: number,
   ) => void;
+  bindMidiCcBinding: (binding: import('./project_types').ProjectMidiCcBinding) => void;
   clearMidiCcBindings: () => void;
   midiCcBindingCount: () => number;
   setMidiFx: (destinationId: number, configJson: string) => void;
@@ -995,14 +1083,29 @@ export interface WasmRealtimeEngine {
     value: number,
     renderFrame: number,
   ) => void;
+  pushMidiUmp: (destinationId: number, word0: number, renderFrame: number) => void;
   pushMidiSysex: (destinationId: number, data: Uint8Array, renderFrame: number) => void;
   pushMidiPanic: (renderFrame: number) => void;
   setMidiDestinationExternal: (destinationId: number, external: boolean) => void;
   setExternalMidiClockEnabled: (enabled: boolean) => void;
   externalMidiDroppedCount: () => number;
+  externalMidiPendingCount: () => number;
   drainExternalMidi: (maxRecords: number) => WasmExternalMidiEvent[];
+  popExternalMidiToScratch: () => boolean;
+  externalMidiScratchDestinationId: () => number;
+  externalMidiScratchRenderFrame: () => number;
+  externalMidiScratchByteWord: () => number;
+  externalMidiScratchByteCount: () => number;
+  consumeExternalMidiScratch: () => void;
   clearParameters: () => void;
   process: (channels: Float32Array[]) => Float32Array[];
+  prepareWithChannels: (
+    sampleRate: number,
+    maxBlockSize: number,
+    commandCapacity: number,
+    telemetryCapacity: number,
+    maxChannels: number,
+  ) => void;
   prepareChannels: (numChannels: number, maxFrames: number) => void;
   getChannelBuffer: (channel: number, numFrames: number) => Float32Array;
   processPrepared: (numFrames: number) => void;
@@ -1011,19 +1114,40 @@ export interface WasmRealtimeEngine {
   bounceOffline: (options: WasmEngineBounceOptions) => WasmEngineBounceResult;
   freezeOffline: (options: WasmEngineFreezeOptions) => WasmEngineFreezeResult;
   drainTelemetry: (maxRecords: number) => WasmEngineTelemetry[];
+  popTelemetryToScratch: () => boolean;
+  telemetryScratchType: () => number;
+  telemetryScratchError: () => number;
+  telemetryScratchRenderFrame: () => number;
+  telemetryScratchTimelineSample: () => number;
+  telemetryScratchAudibleTimelineSample: () => number;
+  telemetryScratchGraphLatencySamplesQ8: () => number;
+  telemetryScratchValue: () => number;
+  popMeterTelemetryToScratch: () => boolean;
+  meterScratchTargetId: () => number;
+  meterScratchRenderFrame: () => number;
+  meterScratchValue: (field: number) => number;
   drainMeterTelemetry: (maxRecords: number) => WasmEngineMeterTelemetry[];
   drainMeterTelemetryWide: (maxRecords: number) => WasmEngineMeterTelemetryWide[];
   configureScopeTelemetry: (intervalFrames: number, bandCount: number) => number;
   drainScopeTelemetry: (maxRecords: number) => WasmEngineScopeTelemetry[];
+  popScopeTelemetryToScratch: () => boolean;
+  scopeScratchTargetId: () => number;
+  scopeScratchRenderFrame: () => number;
+  scopeScratchBandCount: () => number;
+  scopeScratchBand: (index: number) => number;
+  scopeScratchPointCount: () => number;
+  scopeScratchPointLeft: (index: number) => number;
+  scopeScratchPointRight: (index: number) => number;
   delete: () => void;
 }
 
-export type ProgressCallback = (progress: number, stage: string) => void;
+export type { ProgressCallback } from './public_types';
 export type TempogramMode = 'autocorrelation' | 'auto' | 'ac' | 'cosine' | 0 | 1;
 
 export interface WasmSynthEnumTables {
   engineModes: string[];
   waveforms: string[];
+  builtinWaveforms: string[];
   filterModels: string[];
   filterOutputs: string[];
   bodyTypes: string[];
@@ -1061,7 +1185,7 @@ export interface SonareModule {
     profileType: number,
     genreHint: string,
   ) => WasmKeyCandidateResult[];
-  detectOnsets: (samples: Float32Array, sampleRate: number) => Float32Array;
+  detectOnsets: (samples: Float32Array, sampleRate: number, options: object) => Float32Array;
   detectBeats: (samples: Float32Array, sampleRate: number) => Float32Array;
   detectDownbeats: (samples: Float32Array, sampleRate: number) => Float32Array;
   detectChords: (
@@ -1100,7 +1224,7 @@ export interface SonareModule {
     detectInversions: boolean,
     chromaMethod: number,
   ) => string[];
-  analyze: (samples: Float32Array, sampleRate: number) => WasmAnalysisResult;
+  analyze: (samples: Float32Array, sampleRate: number, options: object) => WasmAnalysisResult;
   _synthEnumTables: () => WasmSynthEnumTables;
   _synthPatchRoundTrip: (patch: unknown) => unknown;
   _analysisResultSchemaPaths: () => string[];
@@ -1135,6 +1259,7 @@ export interface SonareModule {
     samples: Float32Array,
     sampleRate: number,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmAnalysisResult;
   analyzeBpm: (
     samples: Float32Array,
@@ -1174,14 +1299,23 @@ export interface SonareModule {
   detectKeyCandidates: (samples: Float32Array, sampleRate: number) => WasmKeyCandidateResult[];
   hasFfmpegSupport: () => boolean;
   version: () => string;
+  capabilities: () => SonareCapabilities;
+  capabilityCatalog: () => string;
   abiVersion: () => number;
   engineAbiVersion: () => number;
   voiceChangerAbiVersion: () => number;
-  voiceCharacterPresetId: (preset: number) => string | null;
-  realtimeVoiceChangerPresetConfig: (preset: number) => WasmRealtimeVoiceChangerPodConfig | null;
+  voiceCharacterPresetId: (preset: number) => string;
+  realtimeVoiceChangerPresetConfig: (preset: number) => WasmRealtimeVoiceChangerPodConfig;
 
   meteringPeakDb: (samples: Float32Array, sampleRate: number) => number;
   meteringRmsDb: (samples: Float32Array, sampleRate: number) => number;
+  meteringSilenceRatio: (
+    samples: Float32Array,
+    sampleRate: number,
+    thresholdDb: number,
+    frameLength: number,
+    hopLength: number,
+  ) => number;
   meteringCrestFactorDb: (samples: Float32Array, sampleRate: number) => number;
   meteringDcOffset: (samples: Float32Array, sampleRate: number) => number;
   meteringTruePeakDb: (
@@ -1576,6 +1710,7 @@ export interface SonareModule {
     sampleRate: number,
     config: Record<string, unknown>,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmMasteringChainResult;
   masteringChainStereoWithProgress: (
     left: Float32Array,
@@ -1583,6 +1718,7 @@ export interface SonareModule {
     sampleRate: number,
     config: Record<string, unknown>,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmMasteringStereoChainResult;
   masteringPresetNames: () => string[];
   masterAudio: (
@@ -1604,6 +1740,7 @@ export interface SonareModule {
     sampleRate: number,
     overrides: Record<string, number | boolean> | null,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmMasteringChainResult;
   masterAudioStereoWithProgress: (
     presetName: string,
@@ -1612,6 +1749,7 @@ export interface SonareModule {
     sampleRate: number,
     overrides: Record<string, number | boolean> | null,
     progressCallback: ProgressCallback | null,
+    cancelCallback: (() => boolean) | null,
   ) => WasmMasteringStereoChainResult;
   mixingScenePresetNames: () => string[];
   mixingScenePresetJson: (presetName: string) => string;
@@ -1666,6 +1804,79 @@ export interface SonareModule {
     htk: boolean,
     lifter: number,
   ) => WasmMfccResult;
+  melDelta: (
+    features: Float32Array,
+    nFeatures: number,
+    nFrames: number,
+    width: number,
+  ) => Float32Array;
+  reassignedSpectrogram: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    refPower: number,
+    fillNan: boolean,
+  ) => {
+    nBins: number;
+    nFrames: number;
+    magnitude: Float32Array;
+    times: Float32Array;
+    frequencies: Float32Array;
+  };
+  segmentCrossSimilarity: (
+    x: Float32Array,
+    xRows: number,
+    xCols: number,
+    y: Float32Array,
+    yRows: number,
+    yCols: number,
+    k: number,
+    metric: string,
+    mode: string,
+  ) => WasmSegmentMatrixResult;
+  segmentRecurrenceMatrix: (
+    data: Float32Array,
+    rows: number,
+    cols: number,
+    k: number,
+    width: number,
+    sym: boolean,
+    metric: string,
+    mode: string,
+  ) => WasmSegmentMatrixResult;
+  segmentRecurrenceToLag: (
+    recurrence: Float32Array,
+    n: number,
+    pad: boolean,
+  ) => WasmSegmentMatrixResult;
+  segmentLagToRecurrence: (
+    lag: Float32Array,
+    rows: number,
+    lags: number,
+  ) => WasmSegmentMatrixResult;
+  segmentSubsegment: (
+    data: Float32Array,
+    rows: number,
+    cols: number,
+    boundaries: Int32Array,
+    nSegments: number,
+  ) => Int32Array;
+  segmentAgglomerative: (
+    data: Float32Array,
+    rows: number,
+    cols: number,
+    k: number,
+    linkage: string,
+  ) => Int32Array;
+  segmentPathEnhance: (
+    recurrence: Float32Array,
+    n: number,
+    win: number,
+    maxRatio: number,
+    minRatio: number,
+    nFilters: number,
+  ) => WasmSegmentMatrixResult;
 
   // Features - Inverse reconstruction
   melToStft: (
@@ -1690,11 +1901,22 @@ export interface SonareModule {
     nIter: number,
     htk: boolean,
   ) => Float32Array;
+  griffinLim: (
+    magnitude: Float32Array,
+    nBins: number,
+    nFrames: number,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    nIter: number,
+    momentum: number,
+  ) => Float32Array;
   mfccToMel: (
     mfcc: Float32Array,
     nMfcc: number,
     nFrames: number,
     nMels: number,
+    lifter: number,
   ) => WasmMelPowerResult;
   mfccToAudio: (
     mfcc: Float32Array,
@@ -1708,6 +1930,7 @@ export interface SonareModule {
     fmax: number,
     nIter: number,
     htk: boolean,
+    lifter: number,
   ) => Float32Array;
 
   // Features - Chroma
@@ -1730,6 +1953,7 @@ export interface SonareModule {
     sampleRate: number,
     nFft: number,
     hopLength: number,
+    p: number,
   ) => Float32Array;
   spectralRolloff: (
     samples: Float32Array,
@@ -1744,6 +1968,13 @@ export interface SonareModule {
     nFft: number,
     hopLength: number,
   ) => Float32Array;
+  spectralFlux: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    lag: number,
+  ) => Float32Array;
   zeroCrossingRate: (
     samples: Float32Array,
     sampleRate: number,
@@ -1810,6 +2041,30 @@ export interface SonareModule {
     threshold: number,
     fillNa: boolean,
   ) => WasmPitchResult;
+  piptrack: (
+    samples: Float32Array,
+    sampleRate: number,
+    nFft: number,
+    hopLength: number,
+    fmin: number,
+    fmax: number,
+    threshold: number,
+  ) => {
+    nBins: number;
+    nFrames: number;
+    pitches: Float32Array;
+    magnitudes: Float32Array;
+  };
+  noteSegments: (
+    f0Hz: Float32Array,
+    voicedProb: Float32Array,
+    frameRate: number,
+    options: {
+      segmentationThresholdCents?: number;
+      minNoteMs?: number;
+      referenceHz?: number;
+    },
+  ) => WasmNoteSegment[];
 
   // Core - Conversion
   hzToMel: (hz: number) => number;
@@ -1841,9 +2096,31 @@ export interface SonareModule {
     hopLength: number,
   ) => Int32Array;
   frameSignal: (samples: Float32Array, frameLength: number, hopLength: number) => WasmFrameResult;
+  tone: (
+    frequency: number,
+    sampleRate: number,
+    duration: number,
+    phase: number,
+    amplitude: number,
+  ) => Float32Array;
+  chirp: (
+    fmin: number,
+    fmax: number,
+    sampleRate: number,
+    duration: number,
+    linear: boolean,
+  ) => Float32Array;
+  clicks: (
+    times: Float32Array,
+    sampleRate: number,
+    length: number,
+    frequency: number,
+    clickDuration: number,
+  ) => Float32Array;
   padCenter: (values: Float32Array, size: number, padValue: number) => Float32Array;
   fixLength: (values: Float32Array, size: number, padValue: number) => Float32Array;
   fixFrames: (frames: Int32Array, xMin: number, xMax: number, pad: boolean) => Int32Array;
+  onsetBacktrack: (events: Int32Array, energy: Float32Array) => Int32Array;
   peakPick: (
     values: Float32Array,
     preMax: number,
@@ -1867,6 +2144,8 @@ export interface SonareModule {
     hopLength: number,
     winLength: number,
     mode: TempogramMode,
+    center: boolean,
+    norm: boolean,
   ) => WasmTempogramResult;
   cyclicTempogram: (
     onsetEnvelope: Float32Array,
@@ -1889,12 +2168,14 @@ export interface SonareModule {
     sampleRate: number,
     hopLength: number,
     nChroma: number,
+    binsPerOctave: number,
   ) => WasmChromaResult;
   chromaCqt: (
     samples: Float32Array,
     sampleRate: number,
     hopLength: number,
     nChroma: number,
+    binsPerOctave: number,
   ) => WasmChromaResult;
   bassChroma: (
     samples: Float32Array,
@@ -1902,7 +2183,13 @@ export interface SonareModule {
     hopLength: number,
     nChroma: number,
   ) => WasmChromaResult;
-  nnlsChroma: (samples: Float32Array, sampleRate: number) => WasmNnlsChromaResult;
+  nnlsChroma: (
+    samples: Float32Array,
+    sampleRate: number,
+    enableStftBlend: boolean,
+    stftBlendWeight: number,
+    stftBlendNFft: number,
+  ) => WasmNnlsChromaResult;
   cqt: (
     samples: Float32Array,
     sampleRate: number,
@@ -1995,6 +2282,8 @@ export interface SonareModule {
     sampleRate: number,
     hopLength: number,
     winLength: number,
+    center: boolean,
+    norm: boolean,
   ) => WasmFourierTempogramResult;
   tempogramRatio: (
     tempogramData: Float32Array,
@@ -2091,6 +2380,7 @@ export interface SonareModule {
     maxBlockSize: number,
     commandCapacity: number,
     telemetryCapacity: number,
+    maxChannels?: number,
   ) => WasmRealtimeEngine;
 
   // Streaming - StreamingMasteringChain
@@ -2128,6 +2418,8 @@ export interface WasmStreamingMasteringChain {
     left: Float32Array,
     right: Float32Array,
   ) => { left: Float32Array; right: Float32Array };
+  flushMono: () => Float32Array;
+  flushStereo: () => { left: Float32Array; right: Float32Array };
   reset: () => void;
   latencySamples: () => number;
   stageNames: () => string[];
@@ -2182,8 +2474,10 @@ export interface WasmRealtimeVoiceChanger {
   prepare: (sampleRate: number, maxBlockSize: number, channels: number) => void;
   reset: () => void;
   setConfig: (config: Record<string, unknown> | string) => void;
+  setPodConfig: (config: WasmRealtimeVoiceChangerPodConfig) => void;
   configJson: () => string;
   latencySamples: () => number;
+  bufferGeneration: () => number;
   processMono: (samples: Float32Array) => Float32Array;
   processMonoInto: (samples: Float32Array, output: Float32Array) => void;
   processInterleaved: (samples: Float32Array, channels: number) => Float32Array;
@@ -2255,6 +2549,7 @@ export interface WasmMixer {
   removeSend: (stripIndex: number, sendIndex: number) => void;
   meterTap: (stripIndex: number, tap: number) => WasmMixMeterSnapshot;
   stripMeter: (stripIndex: number) => WasmMixMeterSnapshot;
+  busMeter: (busId: string) => WasmMixMeterSnapshot;
   scheduleFaderAutomation: (
     stripIndex: number,
     samplePos: number,
@@ -2286,6 +2581,7 @@ export interface WasmMixer {
   busCount: () => number;
   addVcaGroup: (id: string, gainDb: number, members: string[]) => void;
   setVcaGroupGainDb: (id: string, gainDb: number) => void;
+  setVcaGroupMembers: (id: string, members: string[]) => void;
   removeVcaGroup: (id: string) => void;
   vcaGroupCount: () => number;
   toSceneJson: () => string;

package/src/streaming_processors.ts

@@ -1,3 +1,4 @@
+import { flattenChainConfig } from './_chain_config';
 import { getSonareModule } from './module_state';
 import type {
   EqBand,
@@ -64,7 +65,12 @@ export class StreamingMasteringChain {
 
   constructor(config: StreamingMasteringChainConfig) {
     const module = getSonareModule();
-    this.chain = module.createStreamingMasteringChain(config as Record<string, unknown>);
+    const { loudnessStaticGainDb, loudnessStaticGainPeakDb, ...chainConfig } = config;
+    this.chain = module.createStreamingMasteringChain({
+      __flatParams: flattenChainConfig(chainConfig),
+      loudnessStaticGainDb,
+      loudnessStaticGainPeakDb,
+    });
   }
 
   /**
@@ -98,6 +104,21 @@ export class StreamingMasteringChain {
     return this.chain.processStereo(left, right);
   }
 
+  /**
+   * Emit delayed audio and finite processor tails after the final mono block.
+   * Call until this returns an empty array. The initial `latencySamples()`
+   * samples of the concatenated stream are delayed and should be discarded for
+   * time-aligned output.
+   */
+  flushMono(): Float32Array {
+    return this.chain.flushMono();
+  }
+
+  /** Stereo counterpart of {@link flushMono}. */
+  flushStereo(): { left: Float32Array; right: Float32Array } {
+    return this.chain.flushStereo();
+  }
+
   /** Reset all processor state without rebuilding. */
   reset(): void {
     this.chain.reset();

package/src/validation.ts

@@ -78,6 +78,12 @@ export function assertSampleRate(fnName: string, sampleRate: number): void {
   }
 }
 
+/** Validate and retain the public Audio.fromBuffer construction contract. */
+export function validateAudioBuffer(samples: Float32Array, sampleRate: number): void {
+  assertSamples('Audio.fromBuffer', samples, true);
+  assertSampleRate('Audio.fromBuffer', sampleRate);
+}
+
 export function assertNonNegativeInteger(fnName: string, value: number, argName: string): void {
   if (!Number.isInteger(value) || value < 0) {
     throw new RangeError(`${fnName}: ${argName} must be a non-negative integer`);