@libraz/libsonare 1.7.2 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.7.2",
+  "version": "1.8.0",
   "type": "module",
   "packageManager": "yarn@4.18.0",
   "description": "Audio analysis, mastering, mixing, and MIDI synthesis in WebAssembly",
@@ -26,33 +26,42 @@
     "./wasm": "./dist/sonare.wasm",
     "./schemas/realtime-voice-changer-preset.schema.json": "./dist/schemas/realtime-voice-changer-preset.schema.json",
     "./schemas/realtime-voice-changer-preset-pack.schema.json": "./dist/schemas/realtime-voice-changer-preset-pack.schema.json",
+    "./schemas/mixer-scene.schema.json": "./dist/schemas/mixer-scene.schema.json",
+    "./schemas/playback-renderer-config.schema.json": "./dist/schemas/playback-renderer-config.schema.json",
+    "./hrtf/default.shrf": "./dist/hrtf/default.shrf",
     "./package.json": "./package.json"
   },
   "files": [
     "dist",
-    "src"
+    "src",
+    "NOTICE",
+    "!dist/*.sources.json"
   ],
   "sideEffects": false,
   "scripts": {
     "build": "yarn build:wasm && yarn build:js",
     "build:wasm": "yarn build:wasm:full && yarn build:wasm:analysis",
-    "build:wasm:full": "mkdir -p build-wasm/em-cache && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm/em-cache emcmake cmake -S ../.. -B build-wasm -DBUILD_WASM=ON -DSONARE_WASM_ANALYSIS_ONLY=OFF -DSONARE_WASM_OUTPUT_NAME=sonare -DBUILD_MASTERING=ON -DBUILD_MIXING=ON -DBUILD_GRAPH=ON -DBUILD_FX=ON -DBUILD_ACOUSTIC_SIM=ON -DBUILD_PITCH_EDITOR=ON -DBUILD_VOICE_CHANGER=ON -DBUILD_ARRANGEMENT=ON -DBUILD_ASSIST=ON -DCMAKE_BUILD_TYPE=Release && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm/em-cache cmake --build build-wasm",
-    "build:wasm:analysis": "mkdir -p build-wasm-analysis/em-cache && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm-analysis/em-cache emcmake cmake -S ../.. -B build-wasm-analysis -DBUILD_WASM=ON -DSONARE_WASM_ANALYSIS_ONLY=ON -DSONARE_WASM_OUTPUT_NAME=sonare-analysis -DBUILD_MASTERING=OFF -DBUILD_MIXING=OFF -DBUILD_GRAPH=OFF -DBUILD_FX=OFF -DBUILD_ACOUSTIC_SIM=OFF -DBUILD_VOICE_CHANGER=OFF -DBUILD_ARRANGEMENT=OFF -DBUILD_ASSIST=OFF -DCMAKE_BUILD_TYPE=Release && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm-analysis/em-cache cmake --build build-wasm-analysis --target sonare",
+    "build:wasm:full": "mkdir -p build-wasm/em-cache && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm/em-cache emcmake cmake -S ../.. -B build-wasm -DBUILD_WASM=ON -DSONARE_WASM_ANALYSIS_ONLY=OFF -DSONARE_WASM_OUTPUT_NAME=sonare -DBUILD_MASTERING=ON -DBUILD_MIXING=ON -DBUILD_MIXING_ASSISTANT=ON -DBUILD_GRAPH=ON -DBUILD_FX=ON -DBUILD_ACOUSTIC_SIM=ON -DBUILD_PITCH_EDITOR=ON -DBUILD_VOICE_CHANGER=ON -DBUILD_ARRANGEMENT=ON -DBUILD_ASSIST=ON -DCMAKE_BUILD_TYPE=Release && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm/em-cache cmake --build build-wasm && node scripts/dist-source-manifest.mjs --write sonare",
+    "build:wasm:analysis": "mkdir -p build-wasm-analysis/em-cache && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm-analysis/em-cache emcmake cmake -S ../.. -B build-wasm-analysis -DBUILD_WASM=ON -DSONARE_WASM_ANALYSIS_ONLY=ON -DSONARE_WASM_OUTPUT_NAME=sonare-analysis -DBUILD_MASTERING=OFF -DBUILD_MIXING=OFF -DBUILD_MIXING_ASSISTANT=OFF -DBUILD_GRAPH=OFF -DBUILD_FX=OFF -DBUILD_ACOUSTIC_SIM=OFF -DBUILD_VOICE_CHANGER=OFF -DBUILD_ARRANGEMENT=OFF -DBUILD_ASSIST=OFF -DCMAKE_BUILD_TYPE=Release && EM_NODE_JS=\"$(mise which node 2>/dev/null || command -v node)\" EM_CACHE=$PWD/build-wasm-analysis/em-cache cmake --build build-wasm-analysis --target sonare && node scripts/dist-source-manifest.mjs --write sonare-analysis",
+    "check:dist-freshness": "node scripts/dist-source-manifest.mjs",
     "check:wasm-size": "python3 ../../tools/check_wasm_size.py --baseline wasm-size-budget.json --artifact sonare.wasm=dist/sonare.wasm --artifact sonare-analysis.wasm=dist/sonare-analysis.wasm",
+    "check:wasm-size:record": "python3 ../../tools/check_wasm_size.py --baseline wasm-size-baseline.json --artifact sonare.wasm=dist/sonare.wasm --artifact sonare-analysis.wasm=dist/sonare-analysis.wasm --write-baseline",
     "bench:wasm:isp": "mkdir -p build-wasm-bench/em-cache /tmp/libsonare-wasm-bench && EM_CACHE=$PWD/build-wasm-bench/em-cache emcmake cmake -S ../.. -B build-wasm-bench -DBUILD_WASM=ON -DBUILD_MASTERING=ON -DBUILD_BENCH=ON -DBUILD_TESTING=OFF -DBUILD_CLI=OFF -DCMAKE_BUILD_TYPE=Release && EM_CACHE=$PWD/build-wasm-bench/em-cache cmake --build build-wasm-bench --target sonare_mastering_isp_bench && cp build-wasm-bench/bin/sonare_mastering_isp_bench.js /tmp/libsonare-wasm-bench/sonare_mastering_isp_bench.cjs && cp build-wasm-bench/bin/sonare_mastering_isp_bench.wasm /tmp/libsonare-wasm-bench/sonare_mastering_isp_bench.wasm && node /tmp/libsonare-wasm-bench/sonare_mastering_isp_bench.cjs",
+    "bench:wasm:playback": "mkdir -p build-wasm-bench/em-cache /tmp/libsonare-wasm-bench && EM_CACHE=$PWD/build-wasm-bench/em-cache emcmake cmake -S ../.. -B build-wasm-bench -DBUILD_WASM=ON -DBUILD_MASTERING=ON -DBUILD_MIXING=ON -DBUILD_ACOUSTIC_SIM=ON -DBUILD_PLAYBACK=ON -DBUILD_BENCH=ON -DBUILD_TESTING=OFF -DBUILD_CLI=OFF -DCMAKE_BUILD_TYPE=Release && EM_CACHE=$PWD/build-wasm-bench/em-cache cmake --build build-wasm-bench --target sonare_playback_binaural_bench && cp build-wasm-bench/bin/sonare_playback_binaural_bench.js /tmp/libsonare-wasm-bench/sonare_playback_binaural_bench.cjs && cp build-wasm-bench/bin/sonare_playback_binaural_bench.wasm /tmp/libsonare-wasm-bench/sonare_playback_binaural_bench.wasm && node /tmp/libsonare-wasm-bench/sonare_playback_binaural_bench.cjs",
     "bench:wasm:phase-vocoder": "mkdir -p build-wasm-bench/em-cache /tmp/libsonare-wasm-bench && EM_CACHE=$PWD/build-wasm-bench/em-cache emcmake cmake -S ../.. -B build-wasm-bench -DBUILD_WASM=ON -DBUILD_BENCH=ON -DBUILD_TESTING=OFF -DBUILD_CLI=OFF -DCMAKE_BUILD_TYPE=Release && EM_CACHE=$PWD/build-wasm-bench/em-cache cmake --build build-wasm-bench --target sonare_phase_vocoder_streaming_bench && cp build-wasm-bench/bin/sonare_phase_vocoder_streaming_bench.js /tmp/libsonare-wasm-bench/sonare_phase_vocoder_streaming_bench.cjs && cp build-wasm-bench/bin/sonare_phase_vocoder_streaming_bench.wasm /tmp/libsonare-wasm-bench/sonare_phase_vocoder_streaming_bench.wasm && node /tmp/libsonare-wasm-bench/sonare_phase_vocoder_streaming_bench.cjs",
-    "build:js": "tsup && node scripts/copy-schemas.mjs",
+    "build:js": "tsup && yarn build:types && node scripts/copy-schemas.mjs && node scripts/copy-hrtf.mjs && node scripts/copy-module-types.mjs && node scripts/dist-source-manifest.mjs --write bundle",
+    "build:types": "node scripts/prune-dist-declarations.mjs && tsc -p tsconfig.json --emitDeclarationOnly",
     "clean": "rm -rf dist build-wasm build-wasm-analysis LICENSE",
     "lint": "biome check src/ tests/",
-    "lint:fix": "biome check --write src/ tests/",
-    "format": "biome format --write src/ tests/",
+    "lint:fix": "git ls-files -z -- 'src/**' 'tests/**' | xargs -0 biome check --write",
+    "format": "git ls-files -z -- 'src/**' 'tests/**' | xargs -0 biome format --write",
     "test": "vitest run",
-    "test:types": "tsc --noEmit --ignoreConfig --strict --module ESNext --moduleResolution bundler --target ES2020 tests/typing/analysis-entry.ts tests/typing/worklet-capture-response.ts",
+    "test:types": "tsc --noEmit --ignoreConfig --strict --module ESNext --moduleResolution bundler --target ES2020 tests/typing/analysis-entry.ts tests/typing/dist-entry-shared-types.ts tests/typing/worklet-capture-response.ts && tsc --noEmit -p tsconfig.json && tsc -p tsconfig.test.json",
     "test:browser": "node scripts/audio-worklet-smoke.mjs",
     "test:browser:worker": "node scripts/offline-worker-smoke.mjs",
     "test:browser:boundary": "node scripts/boundary-smoke.mjs",
     "test:watch": "vitest",
-    "prepublishOnly": "yarn clean && cp ../../LICENSE LICENSE && yarn build && yarn lint && yarn test && yarn test:types"
+    "prepublishOnly": "yarn clean && cp ../../LICENSE LICENSE && cp ../../NOTICE NOTICE && yarn build && yarn lint && yarn test && yarn test:types"
   },
   "keywords": [
     "audio",
@@ -90,10 +99,12 @@
     "node": ">=18.0.0"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.4.16",
-    "ajv": "^8.17.1",
+    "@biomejs/biome": "^2.5.13",
+    "@types/node": "^22.20.3",
+    "ajv": "^8.20.0",
     "tsup": "^8.5.1",
     "typescript": "^6.0.3",
-    "vitest": "^4.1.8"
+    "vite": "^8.3.0",
+    "vitest": "^5.0.1"
   }
 }

package/src/_effects_common.ts

@@ -0,0 +1,17 @@
+/**
+ * Input conversion the effect families share.
+ */
+
+import type { VoicedFlags } from './public_types';
+
+// The embind layer reads the companion voicing array as Float32Array. A flag is
+// a decision, not a magnitude: collapse to 1/0 on truthiness, which is the same
+// reduction the Node facade applies, so both surfaces agree on every accepted
+// input type.
+export function toVoicedFloat32(voiced: VoicedFlags): Float32Array {
+  const out = new Float32Array(voiced.length);
+  for (let index = 0; index < voiced.length; index += 1) {
+    out[index] = voiced[index] ? 1 : 0;
+  }
+  return out;
+}

package/src/_feature_validation.ts

@@ -0,0 +1,34 @@
+/**
+ * Input checks the spectrogram and inverse-transform entries share.
+ */
+
+import type { ValidateOptions } from './validation';
+import { assertFiniteScalar, assertPositiveInteger } from './validation';
+
+export type GuardedOptions = ValidateOptions;
+
+export function validatePositiveIntegers(fnName: string, values: Record<string, number>): void {
+  for (const [name, value] of Object.entries(values)) {
+    assertPositiveInteger(fnName, value, name);
+  }
+}
+
+export function validateMelFrequencyRange(
+  fnName: string,
+  fmin: number,
+  fmax: number,
+  sampleRate: number,
+): void {
+  assertFiniteScalar(fnName, fmin, 'fmin');
+  assertFiniteScalar(fnName, fmax, 'fmax');
+  if (fmin < 0) {
+    throw new RangeError(`${fnName}: fmin must be non-negative`);
+  }
+  if (fmax < 0) {
+    throw new RangeError(`${fnName}: fmax must be non-negative`);
+  }
+  const effectiveFmax = fmax === 0 ? sampleRate / 2 : fmax;
+  if (effectiveFmax <= fmin) {
+    throw new RangeError(`${fnName}: fmax must be greater than fmin`);
+  }
+}

package/src/_fft_options.ts

@@ -0,0 +1,39 @@
+import {
+  assertEvenIntegerAtLeast,
+  assertIntegerValue,
+  assertPositiveInteger,
+} from './validation.js';
+
+/**
+ * The facade's single FFT-size/hop domain.
+ *
+ * This module is deliberately internal: sibling facade modules import it, but
+ * nothing re-exports it, so it stays out of the package entry point and out of
+ * the C-ABI parity surface (which is defined by the index's re-export closure).
+ */
+
+/**
+ * Resolves and validates the `nFft` / `hopLength` pair every STFT-backed entry
+ * point takes.
+ *
+ * The core FFT is mixed-radix, so any even size transforms exactly; only the
+ * real one-sided spectrum's `n_fft / 2 + 1` bin layout needs the evenness. A
+ * power-of-two restriction rejects sizes the C ABI and the native CLI accept,
+ * which is what a second copy of this rule used to do: `hpss({ nFft: 1536 })`
+ * worked while `hpssWithResidual({ nFft: 1536 })` threw, with the message
+ * asserting a constraint this project had explicitly written down as untrue.
+ * One implementation, so the two cannot disagree again.
+ */
+export function resolveFftOptions(
+  fnName: string,
+  nFft: unknown,
+  hopLength: unknown,
+): { nFft: number; hopLength: number } {
+  const resolvedNFft = nFft === undefined ? 2048 : nFft;
+  const resolvedHopLength = hopLength === undefined ? 512 : hopLength;
+  assertIntegerValue(fnName, resolvedNFft, 'nFft');
+  assertEvenIntegerAtLeast(fnName, resolvedNFft, 'nFft', 2, 2 ** 30);
+  assertIntegerValue(fnName, resolvedHopLength, 'hopLength');
+  assertPositiveInteger(fnName, resolvedHopLength, 'hopLength');
+  return { nFft: resolvedNFft, hopLength: resolvedHopLength };
+}

package/src/align_take.ts

@@ -0,0 +1,64 @@
+import { projectModule } from './project_internal';
+import type { AlignTakeToReferenceRequest, AlignTakeToReferenceResult } from './project_types';
+import { assertSampleRate, assertSamples } from './validation';
+
+/**
+ * Aligns one take to a reference timeline and returns the warp anchors that place
+ * the take under it.
+ *
+ * A chromagram is measured for each signal and the two are aligned, then the
+ * alignment is reduced to anchors {@link Project.setWarpMap} accepts: at least
+ * two finite, strictly increasing pairs. The reduction is needed rather than
+ * decorative — an alignment path advances one axis at a time, so the raw
+ * correspondence repeats a coordinate wherever one signal carries more frames
+ * than the other, and those pairs are refused as a warp map.
+ *
+ * **The anchors are oriented for the take's own clip.** `warpSample` is a
+ * position on the REFERENCE timeline and `sourceSample` the corresponding
+ * position in the TAKE, which is the direction a clip whose source is that take
+ * needs. This is why the entry point exists rather than the core alignment
+ * primitive being exposed directly: that one names its arguments the other way
+ * round, so passing the reference as its reference yields the inverse map and
+ * nothing reports it.
+ *
+ * Both signals are read at `sampleRate`; resample first if they differ, since
+ * the alignment does no I/O and no rate conversion.
+ *
+ * {@link AlignTakeToReferenceResult.alignment} is descriptive only — it says how
+ * far the path strayed from a constant rate, so a caller can tell a take the
+ * reference genuinely fits from one it does not, and supplies its own threshold.
+ *
+ * @param request - The two signals, their shared sample rate, and the chroma
+ *   resolution
+ * @returns The anchors and how well the alignment was conditioned
+ * @throws {RangeError} on an empty buffer, a non-finite sample, or a `sampleRate`
+ *   outside `[8000, 384000]`
+ * @throws {SonareError} `InvalidParameter` on a non-positive `hopLength` or
+ *   `binsPerOctave`, on a `binsPerOctave` that is not a multiple of 12, on a
+ *   signal too short to measure two chroma frames, or when the two signals produce
+ *   no pair of distinct anchors — which is what an unalignable pair looks like,
+ *   and is reported rather than answered with a map you cannot use
+ *
+ * @example
+ * ```typescript
+ * const { anchors } = alignTakeToReference({ reference: guide, take, sampleRate });
+ * const project = new Project();
+ * const trackId = project.addTrack({ kind: 'audio' });
+ * const clipId = project.addClip({ trackId, lengthPpq: 64, audio: take, audioSampleRate: sampleRate }); // 16 bars at 4/4, in quarter notes (PPQ)
+ * project.setWarpMap({ id: 1, anchors });
+ * project.setClipWarpRef(clipId, 1);
+ * ```
+ */
+export function alignTakeToReference(
+  request: AlignTakeToReferenceRequest,
+): AlignTakeToReferenceResult {
+  assertSamples('alignTakeToReference', request.reference, true, 'reference');
+  assertSamples('alignTakeToReference', request.take, true, 'take');
+  assertSampleRate('alignTakeToReference', request.sampleRate);
+  return projectModule().alignTakeToReference(
+    request.reference,
+    request.take,
+    request.sampleRate,
+    request,
+  );
+}

package/src/analysis.ts

@@ -12,11 +12,61 @@ import type { SonareModule } from './sonare.js';
 
 export { ErrorCode, isSonareError, SonareError } from './errors';
 export * from './feature_core';
+// Several modules here also hold functions the analysis-only embind source set
+// never registers, so those are re-exported by name rather than wholesale:
+// `export *` published symbols that imported fine and then threw
+// "is not a function" at call time, on a binary that never had them. Types stay
+// wholesale — a type cannot fail to resolve. `analysis-entry.test.ts` guards
+// these lists in one direction: every function the entry exports must be
+// registered by the module it loads, so a name the analysis binary lacks fails
+// as a test rather than at a caller's first call. The other direction is not
+// guarded and a strict form of it would be wrong — the module also registers
+// enums, emscripten internals and raw `_` / `Ex` variants this entry withholds
+// deliberately — so a name dropped from a list below shrinks the published
+// surface silently.
+export type * from './feature_decompose';
+export {
+  segmentAgglomerative,
+  segmentCrossSimilarity,
+  segmentLagToRecurrence,
+  segmentPathEnhance,
+  segmentRecurrenceMatrix,
+  segmentRecurrenceToLag,
+  segmentSubsegment,
+} from './feature_decompose';
+export type * from './feature_inverse';
+export { griffinLim, melToAudio, melToStft, mfccToAudio, mfccToMel } from './feature_inverse';
+export type * from './feature_loudness';
+export { ebur128LoudnessRange, lufsInterleaved, lufsSeriesInterleaved } from './feature_loudness';
 export * from './feature_music';
 export * from './feature_pitch';
-export * from './feature_resample';
-export * from './feature_spectral';
-export * from './feature_spectrogram';
+export type * from './feature_resample';
+export type * from './feature_spectral';
+export {
+  polyFeatures,
+  rmsEnergy,
+  spectralBandwidth,
+  spectralCentroid,
+  spectralContrast,
+  spectralFlatness,
+  spectralFlux,
+  spectralRolloff,
+  zeroCrossingRate,
+  zeroCrossings,
+} from './feature_spectral';
+export type * from './feature_spectrogram';
+export {
+  bassChroma,
+  chroma,
+  chromaCens,
+  chromaCqt,
+  melDelta,
+  melSpectrogram,
+  mfcc,
+  reassignedSpectrogram,
+  stft,
+  stftDb,
+} from './feature_spectrogram';
 export * from './metering';
 export * from './public_types';
 export type {
@@ -33,6 +83,8 @@ export type {
   DetectChordsRequest,
   DetectKeyRequest,
   DynamicsAnalysisResult,
+  DynamicsResult,
+  EstimateMeterRequest,
   MusicAnalyzeOptions,
   MusicAnalyzeRequest,
   RhythmAnalysisResult,
@@ -57,6 +109,7 @@ export {
   detectKey,
   detectKeyCandidates,
   detectOnsets,
+  estimateMeter,
   hasFfmpegSupport,
 } from './quick_analysis';
 

package/src/analysis_helpers.ts

@@ -118,6 +118,7 @@ export function convertChordAnalysisResult(wasm: WasmChordAnalysisResult): Chord
       quality: c.quality as ChordQuality,
       start: c.start,
       end: c.end,
+      duration: c.end - c.start,
       confidence: c.confidence,
       name: c.name,
     })),
@@ -158,6 +159,10 @@ export function convertAnalysisResult(wasm: WasmAnalysisResult): AnalysisResult
     timeSignatureCandidates: wasm.timeSignatureCandidates,
     beatTimes,
     beats: wasm.beats,
+    downbeatIndices: wasm.downbeatIndices,
+    downbeatPhase: wasm.downbeatPhase,
+    beatObservations: wasm.beatObservations,
+    beatLocalBpm: wasm.beatLocalBpm,
     chords: wasm.chords.map((c) => ({
       root: c.root as PitchClass,
       bass: c.bass as PitchClass,
@@ -166,8 +171,10 @@ export function convertAnalysisResult(wasm: WasmAnalysisResult): AnalysisResult
       quality: c.quality as ChordQuality,
       start: c.start,
       end: c.end,
+      duration: c.end - c.start,
       confidence: c.confidence,
       name: c.name,
+      romanNumeral: c.romanNumeral,
     })),
     sections: wasm.sections.map((s) => ({
       type: s.type as SectionType,

package/src/audio.ts

@@ -17,6 +17,7 @@ import {
 } from './effects_mastering';
 import {
   chroma,
+  ebur128LoudnessRange,
   lufs,
   melSpectrogram,
   mfcc,
@@ -37,6 +38,26 @@ import {
   trim,
   zeroCrossingRate,
 } from './features';
+import type {
+  ClippingReport,
+  DynamicRangeReport,
+  MeteringDetectClippingOptions,
+  MeteringDynamicRangeOptions,
+  SpectrumOptions,
+  SpectrumReport,
+} from './metering';
+import {
+  meteringCrestFactorDb,
+  meteringDcOffset,
+  meteringDetectClipping,
+  meteringDynamicRange,
+  meteringPeakDb,
+  meteringRmsDb,
+  meteringSilenceRatio,
+  meteringSpectrum,
+  meteringSpectrumFrame,
+  meteringTruePeakDb,
+} from './metering';
 import { getSonareModule } from './module_state';
 import type {
   AnalysisResult,
@@ -63,6 +84,7 @@ import type {
   SoloProcessor,
   StftResult,
 } from './public_types';
+import type { MusicAnalyzeOptions } from './quick_analysis';
 import {
   analyze,
   analyzeWithProgress,
@@ -76,6 +98,7 @@ import {
   detectOnsets,
 } from './quick_analysis';
 import type { ProgressCallback, WasmNnlsChromaResult } from './sonare.js';
+import type { ValidateOptions } from './validation';
 import { validateAudioBuffer } from './validation';
 
 // ============================================================================
@@ -146,7 +169,14 @@ async function closeCreatedContext(context: BrowserDecodeContext): Promise<void>
 }
 
 /**
- * Wrapper around audio data that exposes all analysis and feature functions as instance methods.
+ * Wrapper around audio data that exposes analysis and feature functions as
+ * instance methods.
+ *
+ * Not every module-level function has a method here — `analyzeBpm`,
+ * `analyzeRhythm`, `analyzeDynamics`, `analyzeTimbre`, `analyzeImpulseResponse`
+ * and `detectAcoustic` are reachable as free functions only, and the Node
+ * facade exposes them as methods as well. Where a method does exist on both, it
+ * takes the same arguments.
  *
  * @example
  * ```typescript
@@ -302,8 +332,15 @@ export class Audio {
     return chordFunctionalAnalysis(this._samples, keyRoot, keyMode, this._sampleRate, options);
   }
 
-  analyze(): AnalysisResult {
-    return analyze(this._samples, this._sampleRate);
+  /**
+   * Full music analysis of the held buffer.
+   *
+   * Takes the same option bag as the module-level {@link analyze} and as the
+   * Node facade's `Audio.analyze`; this method used to drop it, so the same
+   * call was tunable on one binding and fixed at the defaults on the other.
+   */
+  analyze(options: MusicAnalyzeOptions = {}): AnalysisResult {
+    return analyze(this._samples, this._sampleRate, options);
   }
 
   analyzeWithProgress(onProgress: ProgressCallback): AnalysisResult {
@@ -517,4 +554,70 @@ export class Audio {
   resample(targetSr: number): Float32Array {
     return resample(this._samples, this._sampleRate, targetSr);
   }
+
+  // -- Metering --
+  //
+  // These delegate to the module-level buffer-form functions rather than a
+  // native handle: WASM's Audio is a plain JS wrapper around a Float32Array,
+  // not an embind class, so there is no cheaper path to reach the same
+  // measurement. The methods exist for call-shape parity with Node/Python,
+  // which do hold a native handle here.
+
+  peakDb(): number {
+    return meteringPeakDb(this._samples, this._sampleRate);
+  }
+
+  rmsDb(): number {
+    return meteringRmsDb(this._samples, this._sampleRate);
+  }
+
+  dcOffset(): number {
+    return meteringDcOffset(this._samples, this._sampleRate);
+  }
+
+  crestFactorDb(): number {
+    return meteringCrestFactorDb(this._samples, this._sampleRate);
+  }
+
+  silenceRatio(thresholdDb = -45, frameLength = 1024, hopLength = 256): number {
+    return meteringSilenceRatio(
+      this._samples,
+      this._sampleRate,
+      thresholdDb,
+      frameLength,
+      hopLength,
+    );
+  }
+
+  /**
+   * Inter-sample (true) peak in dBFS. `oversampleFactor` must be a power of two
+   * in [1, 16]; pass 0 to use the library default (4).
+   */
+  truePeakDb(oversampleFactor = 4): number {
+    return meteringTruePeakDb(this._samples, this._sampleRate, oversampleFactor);
+  }
+
+  detectClipping(options: MeteringDetectClippingOptions = {}): ClippingReport {
+    return meteringDetectClipping(this._samples, this._sampleRate, options);
+  }
+
+  dynamicRange(options: MeteringDynamicRangeOptions = {}): DynamicRangeReport {
+    return meteringDynamicRange(this._samples, this._sampleRate, options);
+  }
+
+  spectrum(options: SpectrumOptions & ValidateOptions = {}): SpectrumReport {
+    return meteringSpectrum(this._samples, this._sampleRate, options);
+  }
+
+  /**
+   * True single-frame magnitude / power / dB spectrum starting at `frameOffset`.
+   * See {@link meteringSpectrumFrame} for the frame-validation contract.
+   */
+  spectrumFrame(frameOffset = 0, options: SpectrumOptions & ValidateOptions = {}): SpectrumReport {
+    return meteringSpectrumFrame(this._samples, this._sampleRate, frameOffset, options);
+  }
+
+  ebur128LoudnessRange(): number {
+    return ebur128LoudnessRange(this._samples, this._sampleRate);
+  }
 }

package/src/codes.ts

@@ -1,4 +1,12 @@
-import type { AutomationCurve, MeterTap, PanLawInput, PanMode, SendTiming } from './public_types';
+import type { ProjectAutomationCurve } from './project_types';
+import type {
+  AutomationCurve,
+  MeterTap,
+  PanLawInput,
+  PanMode,
+  SendTiming,
+  SidechainSourceKind,
+} from './public_types';
 
 /** Resolve a numeric ordinal in an inclusive range without coercion. */
 export function resolveOrdinalInRange(
@@ -41,12 +49,30 @@ export function resolveEnumOrdinal(
   throw new RangeError(`Invalid ${enumName}: ${String(value)}`);
 }
 
-const AUTOMATION_CURVE_VALUES = {
+/**
+ * Automation curve spellings and their `SonareAutomationCurve` ordinals.
+ *
+ * Single source of truth for the vocabulary: {@link AutomationCurve} and
+ * {@link ProjectAutomationCurve} are derived from these keys, so a spelling
+ * cannot be documented without resolving, or resolve without being documented.
+ */
+export const AUTOMATION_CURVE_VALUES = {
   linear: 0,
   exponential: 1,
   hold: 2,
   's-curve': 3,
 } as const;
+
+/**
+ * The Project facade additionally accepts the legacy `'scurve'` spelling for
+ * compatibility with project data written before `'s-curve'` was canonical.
+ * The Node package declares the same pair of tables, so a breakpoint accepted
+ * by one facade resolves to the same ordinal on the other.
+ */
+export const PROJECT_AUTOMATION_CURVE_VALUES = {
+  ...AUTOMATION_CURVE_VALUES,
+  scurve: 3,
+} as const;
 const PAN_LAW_VALUES: Readonly<Record<string, number>> = {
   const3db: 0,
   'const-3db': 0,
@@ -72,12 +98,18 @@ const PAN_MODE_VALUES = {
 } as const;
 const METER_TAP_VALUES = { preFader: 0, postFader: 1 } as const;
 const SEND_TIMING_VALUES = { postFader: 0, preFader: 1 } as const;
+const SIDECHAIN_SOURCE_KIND_VALUES = { track: 0, bus: 1 } as const;
 const TRACK_MONITOR_MODE_VALUES = { off: 0, pfl: 1, afl: 2 } as const;
 
 export function automationCurveCode(curve: AutomationCurve): number {
   return resolveEnumOrdinal(curve, AUTOMATION_CURVE_VALUES, 'automation curve');
 }
 
+/** Resolve a Project automation breakpoint curve, legacy spellings included. */
+export function projectAutomationCurveCode(curve: ProjectAutomationCurve | undefined): number {
+  return resolveEnumOrdinal(curve ?? 'linear', PROJECT_AUTOMATION_CURVE_VALUES, 'automation curve');
+}
+
 export function panLawCode(panLaw: PanLawInput): number {
   const normalized = typeof panLaw === 'string' ? panLaw.toLowerCase().replace(/_/g, '-') : panLaw;
   return resolveEnumOrdinal(normalized, PAN_LAW_VALUES, 'pan law');
@@ -101,6 +133,11 @@ export function sendTimingCode(timing: SendTiming | number): number {
   return resolveEnumOrdinal(timing, SEND_TIMING_VALUES, 'send timing');
 }
 
+/** Resolve a sidechain source kind to its `SonareSidechainSourceKind` ordinal. */
+export function sidechainSourceKindCode(kind: SidechainSourceKind | number): number {
+  return resolveEnumOrdinal(kind, SIDECHAIN_SOURCE_KIND_VALUES, 'sidechain source kind');
+}
+
 /** Resolve a per-track PFL/AFL monitor mode to its C-ABI ordinal. */
 export function trackMonitorModeCode(mode: unknown): number {
   return resolveEnumOrdinal(mode, TRACK_MONITOR_MODE_VALUES, 'track monitor mode');