@libraz/libsonare 1.7.2 → 1.8.1

package/src/public_types.ts

@@ -2,7 +2,9 @@ export * from './public_types_acoustic';
 export * from './public_types_mastering';
 export * from './public_types_mixing';
 export * from './public_types_music';
+export * from './public_types_playback';
 export * from './public_types_realtime';
+export * from './public_types_repair';
 export * from './public_types_spectral';
 
 /** Runtime capabilities reported by the loaded libsonare build. */
@@ -16,8 +18,32 @@ export interface SonareCapabilities {
   features: {
     mastering: boolean;
     mixing: boolean;
+    /**
+     * True when the offline mixing assistant is compiled in. Separate from
+     * `mixing` because it can be dropped on its own — the analysis-only bundle
+     * has it off — and its entry points stay registered either way, throwing
+     * rather than disappearing, so probing for the function tells a host
+     * nothing.
+     */
+    mixingAssistant: boolean;
     fx: boolean;
     ffmpeg: boolean;
+    /**
+     * True when hosted instruments expose continuously automatable
+     * parameters (`RealtimeEngine.resolveInstrumentAutomationId`).
+     */
+    instrumentParamAutomation: boolean;
+    /**
+     * The four below name the remaining build options that change which
+     * commands and entry points a binary answers. Without them a caller can
+     * observe that a capability is missing but not that it was never built.
+     */
+    arrangement: boolean;
+    acousticSim: boolean;
+    pitchEditor: boolean;
+    voiceChanger: boolean;
+    /** True when the playback renderer (upmix, binaural, speaker output) is compiled in. */
+    playback: boolean;
   };
   decode: {
     builtin: string[];
@@ -27,16 +53,89 @@ export interface SonareCapabilities {
   hardwareConcurrency: number;
 }
 
-/** One parameter descriptor in the cross-surface capability catalog. */
+/** One named value an enum- or closed-integer-typed insert param accepts. */
+export interface MasteringInsertParamChoice {
+  /** Display/identification name (lowerCamelCase); never accepted as input. */
+  name: string;
+  /** The numeric wire value construction reads for this choice. */
+  value: number;
+}
+
+/**
+ * A group of an insert's keys that exists only under a condition: an EQ band,
+ * a multiband crossover band, or a dynamic sub-band inside one. A parameter
+ * belongs to the slot its `slot` field names.
+ */
+export interface MasteringInsertSlot {
+  /** Key prefix without the trailing dot, e.g. `midBand3` or `band1.dyn2`. */
+  name: string;
+  /**
+   * Enclosing slot, which has to exist for this one to; null for a top-level
+   * slot. A parent is always listed before the slots naming it.
+   */
+  parent: string | null;
+  /**
+   * `anyKey`: the slot exists once any one of its keys is supplied, so an EQ
+   * band is built as soon as a host sends any of its keys. `always`: it exists
+   * without any of its keys, subject to `minCrossoverCutoffs`.
+   */
+  activation: 'anyKey' | 'always';
+  /**
+   * Crossover cutoffs (`cutoff<i>Hz` keys) the insert needs in effect for the
+   * slot to exist; 0 when it needs none. With no cutoff key supplied, the
+   * default split applies: the cutoffs that publish a non-null default.
+   */
+  minCrossoverCutoffs: number;
+}
+
+/**
+ * One parameter descriptor in the cross-surface capability catalog, covering
+ * every key a processor's construction reads. Entries come in two runs: first
+ * the processor's realtime automation targets in id order (`id` non-null),
+ * then, sorted by name, every other construction key with `id` null and
+ * `rtSafe` false.
+ *
+ * `type` is `"enum"` when `choices` names every declared enumerator
+ * construction accepts (sent as the number in its `choices` entry), or
+ * `"string"` / `"array"` for a construction-only key (an embedded impulse
+ * response, a per-band list) that reports null for `min`, `max`, `default`
+ * and `choices`.
+ *
+ * `default` is the value the processor uses when the key is absent, read from
+ * the config struct's own field initializer, an enum as its number; it is
+ * null for a param id with no construction key, a `"string"` / `"array"` key,
+ * or a construction key with no fallback.
+ *
+ * `min` and `max` are the range construction ACCEPTS, measured by handing
+ * candidate values to the same code path a caller would use. They are a hard
+ * constraint, not a recommended UI range — a value outside them is an error,
+ * while an unvalidated control (most gains) reports null on both, meaning
+ * "this catalog states no limit" rather than "unknown". Non-null only when
+ * `choices` is null: `choices` non-null names the closed accepted set instead
+ * (every declared enumerator, or a `"number"` key whose accepted integers
+ * have holes), and then both bounds are null. Three properties to plan for: a
+ * bound is measured with every other parameter at its default, so two
+ * parameters that constrain each other each report the other's default; a
+ * sample-rate-derived bound reflects the un-prepared processor and rises once
+ * the insert is prepared at a higher rate; and an exclusive bound is reported
+ * as its limit value, so a control requiring `> 0` reports `min` 0 and still
+ * rejects 0.
+ */
 export interface CapabilityCatalogParameter {
   name: string;
-  id: number;
+  id: number | null;
   rtSafe: boolean;
-  type: 'boolean' | 'number';
+  type: 'boolean' | 'number' | 'enum' | 'string' | 'array';
   min: number | null;
   max: number | null;
   default: boolean | number | null;
   unit: string | null;
+  choices: MasteringInsertParamChoice[] | null;
+  /**
+   * The {@link MasteringInsertSlot} this key belongs to, or null for a key that
+   * always exists.
+   */
+  slot: string | null;
 }
 
 /** One named mastering processor and its host-facing capabilities. */
@@ -52,6 +151,11 @@ export interface CapabilityCatalogProcessor {
   channelPolicy: 'multichannel' | 'stereoPairOnly' | 'perChannel' | 'passthrough';
   category: string;
   params: CapabilityCatalogParameter[];
+  /**
+   * The insert's conditional key groups in declaration order, named by each
+   * parameter's `slot`. Empty for entries that are not realtime-insertable.
+   */
+  slots: MasteringInsertSlot[];
 }
 
 /** Built-in preset names grouped by feature family. */
@@ -60,6 +164,20 @@ export interface CapabilityCatalogPresets {
   synth: string[];
   mixingScene: string[];
   voiceChanger: string[];
+  playbackRoom: string[];
+}
+
+/**
+ * One entry of {@link CapabilityCatalog.masteringPresets}. The restoration
+ * kind's three loudness values are null: its repair stages leave level alone,
+ * so it carries no loudness target, ceiling or limiter allowance.
+ */
+export interface CapabilityCatalogMasteringPreset {
+  name: string;
+  kind: 'mastering' | 'restoration';
+  targetLufs: number | null;
+  truePeakCeilingDb: number | null;
+  maxLimiterGainReductionDb: number | null;
 }
 
 /** Complete runtime catalog exposed by {@link capabilityCatalog}. */
@@ -68,6 +186,7 @@ export interface CapabilityCatalog {
   abi: SonareCapabilities['abi'];
   processors: CapabilityCatalogProcessor[];
   presets: CapabilityCatalogPresets;
+  masteringPresets: CapabilityCatalogMasteringPreset[];
 }
 
 /** Synchronous progress callback for offline operations. Its return value is ignored. */

package/src/public_types_acoustic.ts

@@ -13,7 +13,20 @@ export interface AcousticOptions extends ValidateOptions {
 }
 
 /**
- * Room acoustic parameters from an impulse response
+ * Room acoustic parameters from a blind recording or a measured impulse
+ * response (`isBlind` distinguishes the two).
+ *
+ * Only `rt60` (and `rt60Bands`) is estimated in both modes. `c50`/`c80`/`d50`
+ * and `edt` require a known direct-sound arrival time, which only a measured
+ * impulse response provides, so they are NaN when `isBlind` is true -- `edt`
+ * measures the 0 to -10 dB decay and the blind estimator only fits the late
+ * decay `rt60` comes from.
+ *
+ * A band array that was not computed is EMPTY, never zero-filled: a zero-filled
+ * clarity array is indistinguishable from a genuine 0 dB measurement. So
+ * `c50Bands` and `c80Bands` have length 0 when `isBlind` is true. `edtBands` is
+ * the exception -- it keeps its full length and is all NaN, so it can be indexed
+ * by the same band index as `rt60Bands`.
  */
 export interface AcousticResult {
   rt60: number;
@@ -34,14 +47,29 @@ export interface RoomGeometryOptions {
   lengthM?: number;
   widthM?: number;
   heightM?: number;
-  /** Uniform wall absorption, clamped to [0, 0.999] (the back-compat scalar). */
+  /**
+   * Uniform wall absorption, clamped to [0, 0.999] (the back-compat scalar).
+   * Defaults to 0.2. Higher absorption shortens RT60, so it changes both the
+   * rendered content and the tail length rather than only the timbre.
+   */
   absorption?: number;
   /**
    * Optional per-octave-band wall absorption (125/250/500/1k/2k/4k.. Hz). When
    * provided it overrides `absorption` unless `materialPreset` is set.
+   *
+   * The late tail's decay time runs continuously between octave centres, so
+   * where absorption (a preset's included) changes steeply from one octave to
+   * the next, the octave-band RT60 measured back from the result leans toward
+   * the slower neighbour, as it does for a real room. The design value holds
+   * at the octave centre.
    */
   bandAbsorption?: Float32Array | number[];
-  /** Optional per-band wall scattering; missing bands default to 0. */
+  /**
+   * Optional per-band wall scattering; missing bands default to 0. Independent
+   * of `bandAbsorption` and `materialPreset` — it applies to whichever material
+   * the absorption precedence selected, so a preset or a scalar-absorption room
+   * can still be given rough walls.
+   */
   bandScattering?: Float32Array | number[];
   /**
    * Named wall-material preset (0 none; 1 concrete, 2 wood, 3 curtain,
@@ -57,6 +85,25 @@ export interface RoomGeometryOptions {
   ismOrder?: number;
   seed?: number;
   maxSeconds?: number;
+  /**
+   * Add the ISO 9613-1 atmospheric-absorption term to the late tail's per-band
+   * RT60. Off by default so the RIR is unchanged; it mainly shortens the high
+   * bands of a large room.
+   */
+  airAbsorptionEnabled?: boolean;
+  /**
+   * Air temperature in degrees Celsius; 0 (or omitted) selects the ISO
+   * reference climate's 20 degC. A literal 0 degC is therefore not
+   * distinguishable from unset -- use 0.01 for a freezing room, which absorbs
+   * identically.
+   */
+  airTemperatureC?: number;
+  /**
+   * Relative humidity in percent; 0 (or omitted) selects the ISO reference
+   * climate's 50 %. Both climate values are read only while
+   * `airAbsorptionEnabled` is set.
+   */
+  airHumidityPercent?: number;
 }
 
 export interface RirSynthOptions extends RoomGeometryOptions {
@@ -69,15 +116,41 @@ export interface RirSynthOptions extends RoomGeometryOptions {
   crossfadeMs?: number;
 }
 
+/** One diagnostic reported by the RIR synthesizer. */
+export interface RirDiagnostic {
+  /** Stable machine-readable id, e.g. `acoustic.source_outside_room`. */
+  code: string;
+  message: string;
+  severity: 'info' | 'warning' | 'error';
+}
+
 export interface RirResult {
   rir: Float32Array;
   sampleRate: number;
   hasError: boolean;
+  /**
+   * First error diagnostic as `code: message`, empty when `hasError` is false.
+   * Matches the string the C ABI leaves in `sonare_last_error_message()`.
+   */
+  errorMessage: string;
+  /**
+   * Every diagnostic the synthesizer reported, in order. Warnings appear here on
+   * successful calls too — a `maxSeconds` clamp that cut the tail is a warning,
+   * not an error, and is otherwise indistinguishable from an untruncated RIR.
+   */
+  diagnostics: RirDiagnostic[];
 }
 
 export interface RoomEstimateOptions {
   aspectHintLw?: number;
   aspectHintLh?: number;
+  /**
+   * Mean-absorption prior anchoring the volume scale (0 = library default,
+   * 0.15). Clamped into `[0.01, 0.99]` rather than refused: a value outside that
+   * range still returns a successful estimate, computed from the clamped prior.
+   * The reported volume scales with the cube of the prior, so the substitution
+   * is worth three orders of magnitude at the low end.
+   */
   referenceAbsorption?: number;
   preferEyring?: boolean;
   nOctaveBands?: number;
@@ -90,6 +163,12 @@ export interface RoomEstimateOptions {
 }
 
 export interface RoomEstimateResult {
+  /**
+   * Equivalent volume (m^3) and representative dimensions (m). NaN, with
+   * `confidence` 0, when the recording has no measurable broadband decay
+   * (silence, or an RT60 the analyzer could not fit) — the acoustic family's
+   * "not measurable", as in `rt60Bands`.
+   */
   volume: number;
   length: number;
   width: number;
@@ -113,3 +192,33 @@ export interface RoomMorphOptions extends RoomGeometryOptions {
   /** Equal-power crossfade width around the mixing time in ms (0 = default). */
   crossfadeMs?: number;
 }
+
+/**
+ * Morphed audio and what the target-room synthesis had to change to make it.
+ *
+ * Shaped like {@link RirResult} because the same synthesis runs underneath.
+ * There is no `hasError` / `errorMessage` counterpart: an unusable morph throws,
+ * so every entry in {@link RoomMorphResult.diagnostics} is a warning.
+ */
+export interface RoomMorphResult {
+  /** Morphed samples: input length plus the target room's reverb tail. */
+  audio: Float32Array;
+  sampleRate: number;
+  /**
+   * Every diagnostic the target-room synthesis reported, in order. Each says the
+   * morph went through a room other than the one requested — an image-source
+   * order reduced to the safe maximum (`acoustic.ism_order_clamped`), a tail cut
+   * against `maxSeconds` (`acoustic.rir_length_clamped`), a `maxSeconds` shorter
+   * than the direct sound's flight time and extended to fit it
+   * (`acoustic.rir_length_floored`), a `maxSeconds` shorter than the longest
+   * band's RT60, which cuts that band before it decays by 60 dB so its
+   * reverberation time cannot be measured from the RIR
+   * (`acoustic.rir_tail_truncated`), a request that produced no diffuse tail
+   * (`acoustic.no_late_tail`) — and is otherwise invisible.
+   *
+   * These are the five codes the synthesis can emit here, so a `switch` over
+   * them needs no fall-through case. `roomMorph` forwards `maxSeconds`
+   * unchanged, which is why the floored one reaches a morph at all.
+   */
+  diagnostics: RirDiagnostic[];
+}