@libraz/libsonare 1.7.2 → 1.8.0

package/src/stream_analyzer.ts

@@ -53,6 +53,7 @@ export function streamAnalyzerConfigDefaults(): StreamConfigDefaults {
  */
 export class StreamAnalyzer {
   private analyzer: WasmStreamAnalyzer;
+  private released = false;
 
   /**
    * Create a new StreamAnalyzer.
@@ -107,6 +108,9 @@ export class StreamAnalyzer {
   /**
    * Process audio samples.
    *
+   * Feeding a finalized analyzer is an invalid-state error; call `reset()`
+   * first to start a new stream.
+   *
    * @param samples - Audio samples (mono, float32)
    */
   process(samples: Float32Array): void {
@@ -115,7 +119,8 @@ export class StreamAnalyzer {
 
   /**
    * Process audio samples with a contiguous explicit sample offset. A gap,
-   * seek, or switch from `process()` requires `reset()` first.
+   * seek, or switch from `process()` requires `reset()` first, as does feeding
+   * a finalized analyzer.
    *
    * @param samples - Audio samples (mono, float32)
    * @param sampleOffset - Cumulative sample count at start of this chunk
@@ -126,6 +131,12 @@ export class StreamAnalyzer {
 
   /**
    * Drain any high-rate resampler tail, then zero-pad the final partial frame.
+   *
+   * Repeating a successful call is a no-op, and a call that fails leaves the
+   * stream un-finalized so a retry resumes from the same point. Call `reset()`
+   * before reusing the analyzer for another stream: more audio fed to a
+   * finalized analyzer is rejected rather than silently analyzed without the
+   * overlap context the finalized tail consumed.
    */
   finalize(): void {
     this.analyzer.finalize();
@@ -194,6 +205,7 @@ export class StreamAnalyzer {
       droppedOutputFrames: s.droppedOutputFrames,
       droppedChordProgressionEntries: s.droppedChordProgressionEntries,
       droppedBarProgressionEntries: s.droppedBarProgressionEntries,
+      nonFiniteDiscardBlocks: s.nonFiniteDiscardBlocks,
       estimate: {
         bpm: s.estimate.bpm,
         bpmConfidence: s.estimate.bpmConfidence,
@@ -274,7 +286,15 @@ export class StreamAnalyzer {
   /**
    * Set normalization gain for loud/compressed audio.
    *
-   * @param gain - Gain factor to apply (e.g., 0.5 for -6dB reduction)
+   * Throws for a value outside 0.01..100 rather than clamping into it. The
+   * usual recipe (`gain = targetLevel / measuredLevel`) can land outside that
+   * range for a buffer that is not in the conventional ±1 float domain — an
+   * integer-scaled one asks for about 3e-4 — and no getter exposes the
+   * effective gain, so a clamped request would leave the analysis far off
+   * target undetectably. Convert such a buffer before feeding it instead.
+   *
+   * @param gain - Gain factor to apply (e.g., 0.5 for -6dB reduction, range
+   *   0.01..100)
    */
   setNormalizationGain(gain: number): void {
     this.analyzer.setNormalizationGain(gain);
@@ -283,7 +303,10 @@ export class StreamAnalyzer {
   /**
    * Set tuning reference frequency for non-standard tuning.
    *
-   * @param refHz - Reference frequency for A4 (default 440 Hz)
+   * Throws for a value outside 220..880 Hz rather than clamping into it, so
+   * this and `tuningRefHz` at create time accept exactly the same range.
+   *
+   * @param refHz - Reference frequency for A4 (default 440 Hz, range 220..880)
    * @example
    * // If audio is 1 semitone sharp (A4 = 466.16 Hz)
    * analyzer.setTuningRefHz(466.16);
@@ -294,11 +317,20 @@ export class StreamAnalyzer {
     this.analyzer.setTuningRefHz(refHz);
   }
 
-  /** Release the underlying WASM object. Safe to call only once. */
+  /** Release the underlying WASM object. Idempotent, as the Node facade is. */
   delete(): void {
+    if (this.released) {
+      return;
+    }
+    this.released = true;
     this.analyzer.delete();
   }
 
+  /** Alias for {@link delete}, provided for cross-binding (Node) compatibility. */
+  destroy(): void {
+    this.delete();
+  }
+
   /** Alias for {@link delete}, kept for backward compatibility (historical name). */
   dispose(): void {
     this.delete();

package/src/stream_types.ts

@@ -14,9 +14,21 @@ export interface ChordChange {
  * A chord detected at bar boundary (beat-synchronized)
  */
 export interface BarChord {
+  /**
+   * Bar number, not the index of this entry in the array: bars with no
+   * confident chord are not recorded and the oldest entries are dropped at the
+   * history cap. Group bars by pattern position with this, never with the array
+   * index. In `votedPattern` it is the pattern position instead.
+   */
   barIndex: number;
   root: PitchClass;
   quality: ChordQuality;
+  /**
+   * Start of the bar, on the same timeline as `StreamFrame.timestamp`
+   * (including a `sampleOffset` anchor). Consecutive bars are `barDuration`
+   * apart rather than snapped to the analysis frame grid. Unused in
+   * `votedPattern`.
+   */
   startTime: number;
   confidence: number;
 }
@@ -35,6 +47,11 @@ export interface PatternScore {
 export interface ProgressiveEstimate {
   bpm: number;
   bpmConfidence: number;
+  /**
+   * Tempo candidates the most recent BPM estimate chose from; 0 until an
+   * estimate has run. Same quantity as the batch analysis result's field of the
+   * same name.
+   */
   bpmCandidateCount: number;
   key: PitchClass;
   keyMinor: boolean;
@@ -54,6 +71,11 @@ export interface ProgressiveEstimate {
   allPatternScores: PatternScore[];
   accumulatedSeconds: number;
   usedFrames: number;
+  /**
+   * True when the key or BPM was re-estimated since the previous stats
+   * snapshot. One change sets it on exactly one snapshot however the caller
+   * chunks its input, and a call that produced no frame does not repeat it.
+   */
   updated: boolean;
 }
 
@@ -68,6 +90,19 @@ export interface AnalyzerStats {
   droppedOutputFrames: number;
   droppedChordProgressionEntries: number;
   droppedBarProgressionEntries: number;
+  /**
+   * Blocks in which a non-finite input sample was replaced before it could
+   * reach the analyzer's recursive state.
+   *
+   * Unlike the drop counts above, nothing is missing from the output: every
+   * estimate is produced as usual and simply stops describing the input, so
+   * this is the only report that the stream was degraded. The unit is one
+   * {@link StreamAnalyzer.process} call, never a sample, so a block carrying a
+   * thousand NaNs adds one. Cleared by {@link StreamAnalyzer.reset} alongside
+   * the drop counts, because that call rebuilds the timeline and the count
+   * describes a segment rather than the analyzer.
+   */
+  nonFiniteDiscardBlocks: number;
   estimate: ProgressiveEstimate;
 }
 
@@ -164,6 +199,8 @@ export interface StreamConfig {
   nMels?: number;
   fmin?: number;
   fmax?: number;
+  /** A4 tuning reference in Hz. Defaults to 440; must be within 220..880, the
+   *  same range `setTuningRefHz` accepts live. */
   tuningRefHz?: number;
   /** Unsupported: no read path surfaces per-frame magnitude spectra. */
   computeMagnitude?: boolean;

package/src/streaming_mixing.ts

@@ -1,4 +1,4 @@
-export type { MixerRealtimeBuffer } from './mixer';
+export type { MixerMeterSnapshot, MixerRealtimeBuffer, StripMeteringOptions } from './mixer';
 export { Mixer } from './mixer';
 export type {
   RealtimeVoiceChangerInterleavedBuffer,

package/src/streaming_processors.ts

@@ -4,6 +4,7 @@ import type {
   EqBand,
   EqMatchOptions,
   EqSpectrumSnapshot,
+  EqStereoPlacement,
   StreamingEqualizerConfig,
   StreamingMasteringChainConfig,
   StreamingRetuneConfig,
@@ -21,6 +22,14 @@ type EqPhaseMode =
   | 'linear_phase'
   | number;
 
+const EQ_PLACEMENTS: Record<string, number> = {
+  stereo: 0,
+  left: 1,
+  right: 2,
+  mid: 3,
+  side: 4,
+};
+
 const EQ_PHASE_MODES: Record<string, number> = {
   zero: 1,
   'zero-latency': 1,
@@ -41,10 +50,29 @@ const EQ_PHASE_MODES: Record<string, number> = {
  * Block-by-block streaming variant of {@link masteringChain}.
  *
  * Maintains processor state across {@link processMono}/{@link processStereo}
- * calls. Only ProcessorBase-backed stages are supported. Configurations that
- * enable `repair.denoise` throw at construction. An enabled `loudness` stage
- * also throws unless {@link StreamingMasteringChainConfig.loudnessStaticGainDb}
- * supplies a precomputed normalization gain.
+ * calls. Only ProcessorBase-backed stages are supported: `eq.tilt`,
+ * `dynamics.deesser`, `dynamics.transientShaper`, `dynamics.compressor`,
+ * `dynamics.multibandComp`, `saturation.tape`, `saturation.exciter`,
+ * `spectral.airBand`, `stereo.imager` (stereo only), `stereo.monoMaker`
+ * (stereo only), `maximizer.truePeakLimiter`. Configurations that enable ANY of
+ * the five whole-signal repair stages (`repair.declick`, `repair.declip`,
+ * `repair.decrackle`, `repair.dehum`, `repair.dereverb`) throw at construction.
+ *
+ * `repair.denoise` runs here, but only with a noise estimator that is recursive
+ * in time. Its default ranks every frame of the whole signal by energy, which a
+ * stream never reaches the end of, so it is refused by name rather than
+ * substituted; set `repair.denoise.noiseEstimator` to `1` (MCRA), `2` (IMCRA)
+ * or `3` (speech-presence probability). The two minimum-tracking estimators
+ * (`1` and `2`) seed their noise floor from the first frame they see and hold it
+ * for the half second their minimum window spans, so a stream opened in the
+ * middle of the programme is over-suppressed until it turns over; `3` tracks no
+ * minimum and is unaffected. Prefer `3` past that opening too: `1` and `2`
+ * over-report the floor for as long as the programme stays intermittent, and on
+ * a gated tone they leave the result below the untreated input.
+ *
+ * An enabled `loudness` stage also throws unless
+ * {@link StreamingMasteringChainConfig.loudnessStaticGainDb} supplies a
+ * precomputed normalization gain.
  *
  * Call {@link delete} (or use a `try/finally`) to release the underlying WASM
  * object — the embind handle is not garbage-collected automatically.
@@ -80,6 +108,7 @@ const EQ_PHASE_MODES: Record<string, number> = {
  */
 export class StreamingMasteringChain {
   private chain: import('./sonare.js').WasmStreamingMasteringChain;
+  private released = false;
 
   constructor(config: StreamingMasteringChainConfig) {
     const module = getSonareModule();
@@ -152,10 +181,78 @@ export class StreamingMasteringChain {
     return this.chain.stageNames();
   }
 
-  /** Release the underlying WASM object. Safe to call only once. */
+  /**
+   * Samples a stage replaced with a finite in-domain one, keeping the output
+   * finite and in range.
+   *
+   * A non-finite sample supplied by the caller is rejected before any stage
+   * runs, so a replacement is always of a value a stage itself produced.
+   *
+   * Only the true-peak limiters replace anything, so with the maximizer's
+   * limiter and the loudness stage both disabled a zero here means no stage was
+   * able to replace anything rather than that nothing needed replacing.
+   *
+   * Cumulative over every block since {@link prepare}, and aggregated over the
+   * stages and channels, so it identifies neither which block nor which stage.
+   * Read it per block and compare against the previous reading to localize one.
+   *
+   * {@link prepare} rebuilds the stages and so clears it; {@link reset} does
+   * not, because it drops processor state without rebuilding.
+   *
+   * @example
+   * ```typescript
+   * chain.processMono(block);
+   * if (chain.nonFiniteSubstitutionCount() > previous) {
+   *   // the block just produced is not derived from `block` everywhere
+   * }
+   * ```
+   */
+  nonFiniteSubstitutionCount(): number {
+    return this.chain.nonFiniteSubstitutionCount();
+  }
+
+  /**
+   * Processing calls in which a stage discarded its own recursive state
+   * because a non-finite value had reached it.
+   *
+   * The companion to {@link nonFiniteSubstitutionCount}, and not the same
+   * measurement -- a caller who assumes they are will read one and think
+   * they have the other. That one counts SAMPLES a stage replaced and so
+   * sums across stages; a discard is a whole stage returning to its
+   * post-reset value and is counted once per call however many stages did
+   * it. A stage may run more than once per call, which is why this is a
+   * delta over the call and never a sum.
+   *
+   * Non-finite input is rejected before any stage runs, so what a stage
+   * discards is always state it produced itself -- a finite sample large
+   * enough to overflow inside a filter, most often. Unlike the substitution
+   * count every stage can contribute, so a zero here means no stage
+   * discarded rather than that none could.
+   *
+   * Both {@link processMono}/{@link processStereo} and
+   * {@link flushMono}/{@link flushStereo} count, since a flush drives the
+   * same stages. {@link prepare} rebuilds the stages and so clears it (as it
+   * does {@link nonFiniteSubstitutionCount}, so the two counters on one
+   * handle share an epoch); {@link reset} does not, because it drops
+   * processor state without rebuilding.
+   */
+  nonFiniteDiscardCount(): number {
+    return this.chain.nonFiniteDiscardCount();
+  }
+
+  /** Release the underlying WASM object. Idempotent, as the Node facade is. */
   delete(): void {
+    if (this.released) {
+      return;
+    }
+    this.released = true;
     this.chain.delete();
   }
+
+  /** Alias for {@link delete}, provided for cross-binding (Node) compatibility. */
+  destroy(): void {
+    this.delete();
+  }
 }
 
 // ============================================================================
@@ -185,6 +282,7 @@ export class StreamingMasteringChain {
  */
 export class StreamingEqualizer {
   private eq: import('./sonare.js').WasmStreamingEqualizer;
+  private released = false;
 
   constructor(config: StreamingEqualizerConfig = {}) {
     const module = getSonareModule();
@@ -267,6 +365,33 @@ export class StreamingEqualizer {
     return this.eq.latencySamples();
   }
 
+  /**
+   * Number of blocks in which the EQ discarded recursive state because a
+   * non-finite value had reached it.
+   *
+   * Advisory telemetry, and the only thing that separates a degraded EQ from
+   * a clean one. A discard returns the affected filter cells to their
+   * post-reset value, so the EQ recovers in silence and the output stays
+   * finite and in range while carrying samples unrelated to the input;
+   * nothing else reports that this happened.
+   *
+   * The count covers every IIR plane the band layout uses -- stereo, per
+   * channel, and mid/side -- together with the automatic output gain and the
+   * detector state the dynamic bands drive. Linear-phase bands are not
+   * included and have nothing to include: an FIR keeps no recursive state,
+   * so a non-finite sample leaves its history on its own.
+   *
+   * Unlike a mixer strip's meters, nothing here lags: this EQ has no meter of
+   * its own, so a discard is always attributed to the block that carried it.
+   *
+   * Cumulative since this handle was created and never cleared, so two
+   * readings bracket a span of audio. The unit is one processed block, never
+   * a channel or a plane.
+   */
+  nonFiniteDiscardCount(): number {
+    return this.eq.nonFiniteDiscardCount();
+  }
+
   /**
    * Process one mono block, returning the equalized samples (same length).
    */
@@ -287,6 +412,39 @@ export class StreamingEqualizer {
     return this.eq.processStereo(left, right);
   }
 
+  /**
+   * The composite magnitude of the bands, in dB, at each requested frequency —
+   * the curve to draw over {@link spectrum}.
+   *
+   * Built from the same coefficient design, tilt expansion and cut-slope
+   * cascade the audio path uses, so it states what the equalizer does rather
+   * than what its settings look like, and it carries the output gain, the gain
+   * scale and whatever each dynamic band is applying at the moment of the call.
+   * Disabled, bypassed and — when anything is soloed — unsoloed bands drop out,
+   * and a soloed band is drawn as the band pass it is heard as.
+   *
+   * `placement` selects which signal path the curve is for. A band placed on
+   * `'Stereo'` is on every path; one placed elsewhere appears only on its own,
+   * a mid band having no per-channel magnitude to fold into a left or right
+   * curve. Frequencies are clamped to [0 Hz, Nyquist].
+   *
+   * @example
+   * ```ts
+   * const freqs = new Float32Array([100, 1000, 10000]);
+   * const db = eq.magnitudeResponse(freqs);
+   * ```
+   */
+  magnitudeResponse(
+    frequenciesHz: Float32Array,
+    placement: EqStereoPlacement = 'Stereo',
+  ): Float32Array {
+    const value = EQ_PLACEMENTS[placement.toLowerCase()];
+    if (value === undefined) {
+      throw new Error(`unknown EQ band placement: ${placement}`);
+    }
+    return this.eq.magnitudeResponse(value, frequenciesHz);
+  }
+
   /**
    * Read the latest pre/post spectrum snapshot for metering. `seq` increments
    * each time a new snapshot is published.
@@ -306,10 +464,19 @@ export class StreamingEqualizer {
     this.eq.match(source, reference, options as Record<string, unknown>);
   }
 
-  /** Release the underlying WASM object. Safe to call only once. */
+  /** Release the underlying WASM object. Idempotent, as the Node facade is. */
   delete(): void {
+    if (this.released) {
+      return;
+    }
+    this.released = true;
     this.eq.delete();
   }
+
+  /** Alias for {@link delete}, provided for cross-binding (Node) compatibility. */
+  destroy(): void {
+    this.delete();
+  }
 }
 
 // ============================================================================
@@ -325,6 +492,7 @@ export class StreamingEqualizer {
  */
 export class StreamingRetune {
   private retune: import('./sonare.js').WasmStreamingRetune;
+  private released = false;
 
   constructor(config: StreamingRetuneConfig = {}) {
     const module = getSonareModule();
@@ -345,14 +513,16 @@ export class StreamingRetune {
   }
 
   /**
-   * Update retune settings. Changing `grainSize` takes effect after the next
-   * {@link prepare} call.
+   * Update the live controls; omitted keys keep their current value. Changing
+   * `grainSize` takes effect after the next {@link prepare} call, and an
+   * omitted `grainSize` keeps whatever was last requested — including the `0`
+   * sentinel, so a re-{@link prepare} at another sample rate re-derives it.
    */
   setConfig(config: StreamingRetuneConfig): void {
     this.retune.setConfig(config as Record<string, unknown>);
   }
 
-  /** Current native config. */
+  /** The currently applied controls, with `grainSize` as the effective one. */
   config(): Required<StreamingRetuneConfig> {
     return this.retune.config();
   }
@@ -362,13 +532,27 @@ export class StreamingRetune {
     return this.retune.grainSize();
   }
 
+  /** Fixed overlap-add latency in samples (one grain); 0 before prepare. */
+  latencySamples(): number {
+    return this.retune.latencySamples();
+  }
+
   /** Process one mono block, returning the shifted samples (same length). */
   processMono(samples: Float32Array): Float32Array {
     return this.retune.processMono(samples);
   }
 
-  /** Release the underlying WASM object. Safe to call only once. */
+  /** Release the underlying WASM object. Idempotent, as the Node facade is. */
   delete(): void {
+    if (this.released) {
+      return;
+    }
+    this.released = true;
     this.retune.delete();
   }
+
+  /** Alias for {@link delete}, provided for cross-binding (Node) compatibility. */
+  destroy(): void {
+    this.delete();
+  }
 }

package/src/transcribe.ts

@@ -0,0 +1,89 @@
+import { projectModule } from './project_internal';
+import type { TranscribeOptions, TranscribeResult } from './project_types';
+import { assertSampleRate, assertSamples } from './validation';
+
+/**
+ * Canonical request form for {@link transcribe}.
+ *
+ * Deliberately does NOT extend `ValidateOptions`. That option's contract is
+ * that skipping the JS-side scan is safe because the native layer re-validates
+ * with an equivalent result -- and here it would not be equivalent: the
+ * transcription C ABI (`sonare_transcribe`) does re-validate the buffer,
+ * including a non-finite scan, but a rejection there surfaces as a
+ * `SonareError` `InvalidParameter`, not the `RangeError` this function
+ * documents and every other empty/non-finite/rate check on this surface
+ * raises. A `{ validate: false }` here would silently change the thrown error
+ * class instead of skipping a redundant check. The scan is also nearly free
+ * against this pipeline, which already reads every sample several times.
+ */
+export interface TranscribeRequest extends TranscribeOptions {
+  /** Mono source audio. Must be non-empty and all-finite. */
+  samples: Float32Array;
+  /** Sample rate of `samples` in Hz, `[8000, 384000]`. */
+  sampleRate: number;
+  /**
+   * Tempo the PPQ grid is built on, in BPM. **Omit to have it detected** from
+   * `samples`, which costs an onset/tempo pass; a detector that finds nothing
+   * usable falls back to 120 rather than failing the transcription.
+   *
+   * Supplying a tempo is not a claim about the audio — it is the coordinate
+   * system the events come back in. Twice the tempo is twice as many beats per
+   * second, so the same audio lands on twice the ppq.
+   */
+  tempoBpm?: number;
+}
+
+/**
+ * Transcribes mono audio into MIDI events on a constant-tempo grid.
+ *
+ * This joins parts that already exist rather than adding a detector: the note
+ * spans and their measured pitch and level come from the monophonic (pYIN) or
+ * polyphonic (multi-F0) chain, and the output is the flat
+ * {@link ProjectMidiEvent} shape {@link Project.setMidiEvents} takes, so
+ * nothing is left to convert.
+ *
+ * Finding no notes is not an error. Silence, and material the chain cannot
+ * resolve, come back with an empty `events` array and `noteCount` 0, and
+ * `tempoBpm` still reports the tempo that was used or detected.
+ *
+ * Three things are deliberately **not** done here, because the library already
+ * does each of them somewhere else and a second implementation would drift:
+ *
+ * - **Quantizing to a grid** — {@link Project.bakeMidiFx}'s `quantizePpq` /
+ *   `quantizeStrength`.
+ * - **Detecting and installing a tempo map** — {@link Project.autoTempo}. The
+ *   `tempoBpm` fallback here builds one constant-tempo grid for this call and
+ *   installs nothing; use {@link Project.transcribeToClip} to transcribe onto a
+ *   project's real map.
+ * - **Annotating key and chords** — {@link Project.annotateKeys} /
+ *   {@link Project.annotateChords}.
+ *
+ * The tuning reference is likewise not measured — see
+ * {@link TranscribeOptions.referenceHz}.
+ *
+ * @throws {RangeError} on empty `samples`, a non-finite sample, or a
+ *   `sampleRate` outside `[8000, 384000]`
+ * @throws {SonareError} `InvalidParameter` on an option outside its domain —
+ *   a non-negative `velocityFloorDb`, a `fixedVelocity` outside `[1, 127]`, a
+ *   `group` or `channel` outside `[0, 15]`, an `fmax` at or below `fmin`, or a
+ *   written `0` on any field but `group` and `channel` — or `NotSupported`
+ *   when the library was built without the pitch editor
+ *
+ * @example
+ * ```typescript
+ * const { events, noteCount, tempoBpm } = transcribe({ samples, sampleRate, tempoBpm: 120 });
+ * const project = new Project();
+ * const { clipId } = project.addMidiClip(0, 16); // 4 bars at 4/4, in quarter notes (PPQ)
+ * project.setMidiEvents(clipId, events);
+ * ```
+ */
+export function transcribe(request: TranscribeRequest): TranscribeResult {
+  assertSamples('transcribe', request.samples, true);
+  assertSampleRate('transcribe', request.sampleRate);
+  return projectModule().transcribe(
+    request.samples,
+    request.sampleRate,
+    request.tempoBpm,
+    request as unknown as TranscribeOptions,
+  );
+}