@libraz/libsonare 1.7.2 → 1.8.1

package/src/public_types_music.ts

@@ -85,12 +85,28 @@ export const ChordQuality = {
   Major9: 14,
   Dominant9: 15,
   Sus2Add4: 16,
+  Major6: 17,
+  Minor6: 18,
+  MinorMajor7: 19,
+  Dominant7Sus4: 20,
+  Dominant11: 21,
+  Dominant13: 22,
+  Dominant7Flat9: 23,
+  Dominant7Sharp9: 24,
 } as const;
 
 export type ChordQuality = (typeof ChordQuality)[keyof typeof ChordQuality];
 
 /**
- * Section type
+ * Section type.
+ *
+ * `PreChorus` is never produced by `analyze()`: it has no detection branch, so
+ * filtering sections on it always yields an empty result. Every other value is
+ * reachable. `Unknown` means the analyzer did not name the segment: no
+ * boundary was detected, the segment matched none of the positive branches, or
+ * the evidence for a musical function was too weak to assert one. The first
+ * case comes with `confidence` 0; the last keeps the sub-threshold score, so a
+ * caller can see how close the segment came to a label.
  */
 export const SectionType = {
   Intro: 0,
@@ -111,6 +127,20 @@ export type SectionType = (typeof SectionType)[keyof typeof SectionType];
 export interface Key {
   root: PitchClass;
   mode: Mode;
+  /**
+   * Share of the model's belief that this key is the answer, in `[0, 1)`.
+   *
+   * A softmax over the profile correlations of every candidate that was scored,
+   * so it falls as the runner-up closes in and two keys that split the evidence
+   * -- a relative major and minor, typically -- each report about half.
+   *
+   * This is the model's own belief, **not** a measured accuracy. It says how
+   * decisively the chroma picked this key out of the candidate set; it does not
+   * say how often that pick is right, and nothing here has been fitted against
+   * annotated recordings. A confident wrong answer is entirely possible, so a
+   * pipeline that branches on it must choose its own threshold against its own
+   * material.
+   */
   confidence: number;
   name: string;
   shortName: string;
@@ -143,6 +173,7 @@ export interface ChordDetectionOptions extends ValidateOptions {
   /** Final-template correlation threshold in [0, 1]; below it emits Unknown / N.C. */
   threshold?: number;
   useTriadsOnly?: boolean;
+  /** STFT chroma window in samples at 22050 Hz, rescaled to the input rate so its duration is the same at every rate. */
   nFft?: number;
   hopLength?: number;
   useBeatSync?: boolean;
@@ -153,6 +184,11 @@ export interface ChordDetectionOptions extends ValidateOptions {
   keyMode?: Mode;
   detectInversions?: boolean;
   chromaMethod?: 'stft' | 'nnls';
+  /**
+   * Tuning offset of the recording in fractions of a semitone, the unit
+   * `estimateTuning` returns; must be in `[-0.5, 0.5)`. Default 0 (concert A440).
+   */
+  tuning?: number;
 }
 
 /** Options for `analyzeBpm`. All fields are optional. */
@@ -223,10 +259,52 @@ export interface AnalyzeSectionsOptions {
  * Detected beat
  */
 export interface Beat {
+  /** Beat position in seconds. */
   time: number;
+  /**
+   * Onset-envelope value sampled at the beat's frame.
+   *
+   * @remarks
+   * A single raw frame of the onset envelope, not a normalized or relative
+   * salience: it is unbounded, its scale depends on the material, and it moves
+   * with any jitter in the beat position. For accent scoring use
+   * {@link BeatObservations.onsetStrength}, which is the windowed aggregate the
+   * library's own downbeat pass scores.
+   */
   strength: number;
 }
 
+/**
+ * Beat-level evidence behind the downbeat and meter decisions.
+ *
+ * @remarks
+ * These are inputs to the library's decision, not outputs of it, exposed so a
+ * caller running its own meter work scores the same evidence instead of
+ * reconstructing a weaker approximation from the frame-level onset envelope.
+ * Each non-empty stream holds one value per entry of
+ * {@link AnalysisResult.beats} and indexes in parallel with it. An empty stream
+ * means the analysis could not produce it, which is not the same as every beat
+ * having scored zero.
+ */
+export interface BeatObservations {
+  /**
+   * Beat-local onset-strength window.
+   *
+   * @remarks
+   * Unlike {@link Beat.strength} this is aggregated over a window around the
+   * beat rather than sampled at a single frame, so it is the stream to score
+   * accents with.
+   */
+  onsetStrength: number[];
+  /**
+   * Beat-local low-frequency energy — the accent evidence a log-spectral
+   * difference discards. Empty when the analysis ran without audio.
+   */
+  lowFrequencyEnergy: number[];
+  /** Per-beat chord-change evidence. Empty until chords are analyzed. */
+  chordChange: number[];
+}
+
 /**
  * Detected chord
  */
@@ -240,10 +318,22 @@ export interface Chord {
   quality: ChordQuality;
   start: number;
   end: number;
+  /** Derived from `end - start`; the core carries only the two endpoints. */
+  duration: number;
   confidence: number;
   name: string;
 }
 
+/** A chord in {@link AnalysisResult.chords}, which carries its function in the key. */
+export interface AnalysisChord extends Chord {
+  /**
+   * Roman numeral of the chord relative to {@link AnalysisResult.key}, e.g.
+   * `'V7'`, `'vi'`, `'bVII'`. The same spelling `chordFunctionalAnalysis`
+   * returns for that chord and key. Empty for a chord that is N.C.
+   */
+  romanNumeral: string;
+}
+
 export interface ChordAnalysisResult {
   chords: Chord[];
 }
@@ -260,6 +350,94 @@ export interface Section {
   name: string;
 }
 
+/** Options for `detectBoundaries`. All fields are optional. */
+export interface BoundaryOptions {
+  /** FFT size used for the structural features. Default 2048. */
+  nFft?: number;
+  /** Hop length in samples. Default 512. */
+  hopLength?: number;
+  /** Checkerboard kernel size in frames. Default 64. */
+  kernelSize?: number;
+  /**
+   * Relative novelty threshold, applied to the curve after it has been scaled by
+   * its own maximum. Selects how prominent a peak must be *within this track*; it
+   * says nothing about how much the features actually changed. Default 0.3.
+   */
+  threshold?: number;
+  /**
+   * Novelty floor applied to the raw response before that scaling, asking whether
+   * anything changed at all. Default 0.005. Set to 0 to gate on {@link threshold}
+   * alone -- but self-scaling turns residual fluctuation into peaks of 1.0, so a
+   * stationary input then segments anyway. Lowering the floor does not recover
+   * level-only structure: a level change turns the feature vector about five times
+   * less than a comparable pitch change, landing below what steady noise produces,
+   * so the noise is admitted first.
+   */
+  absoluteThreshold?: number;
+  /** Number of MFCC coefficients. Default 13. */
+  nMfcc?: number;
+  /** Number of chroma bins. Default 12. */
+  nChroma?: number;
+  /** Minimum spacing between peaks, in seconds. Default 2. */
+  peakDistance?: number;
+  /** Use MFCC features. Default `true`. */
+  useMfcc?: boolean;
+  /** Use chroma features. Default `true`. */
+  useChroma?: boolean;
+}
+
+/**
+ * A single detected structural boundary (mirrors the C `SonareBoundary`).
+ */
+export interface Boundary {
+  /** Boundary time in seconds (the authoritative output). */
+  time: number;
+  /**
+   * Index into the analysis grid, on {@link BoundaryResult.sampleRate}'s time
+   * base rather than the source's. For a long-form input the feature grid is
+   * additionally mean-pooled, so this indexes the pooled grid; use `time` for
+   * sample/second mapping either way.
+   */
+  frame: number;
+  /** Boundary strength (novelty score). */
+  strength: number;
+}
+
+/**
+ * Result of `detectBoundaries` (mirrors the C `SonareBoundaryResult`).
+ */
+export interface BoundaryResult {
+  /** Detected transitions, in time order. */
+  boundaries: Boundary[];
+  /**
+   * Novelty curve scaled by its own maximum, one value per analysis frame. A
+   * peak of 1 means "the most novel frame here", not "a large change"; multiply
+   * by {@link noveltyPeak} to recover the raw response
+   * {@link BoundaryOptions.absoluteThreshold} is compared against.
+   */
+  noveltyCurve: Float32Array;
+  /**
+   * The largest raw checkerboard response, before normalization. Zero when the
+   * curve was left unnormalized because nothing rose above the numerical floor.
+   */
+  noveltyPeak: number;
+  /**
+   * The rate the analysis ran at, not the input's: a source above 22050 Hz is
+   * resampled to 22050 Hz before any feature is computed, which is what makes
+   * {@link Boundary.frame} interpretable.
+   */
+  sampleRate: number;
+  /** Hop length the analysis grid was built on. */
+  hopLength: number;
+  /** Analysis frame count, pooled for a long-form input. */
+  nFrames: number;
+  /**
+   * Feature pooling stride: 1 for every realistic input length, otherwise the
+   * number of raw STFT frames averaged into each analysis frame.
+   */
+  frameStride: number;
+}
+
 /**
  * A single melody contour point (mirrors the C `SonareMelodyPoint`).
  */
@@ -312,9 +490,96 @@ export interface Dynamics {
 export interface TimeSignature {
   numerator: number;
   denominator: number;
+  /**
+   * Support for this signature in `[0, 1]`.
+   *
+   * @remarks
+   * What it measures depends on which field the signature arrived in. On
+   * {@link MeterEstimate.timeSignature} it is derived from the margin over the
+   * runner-up; on a {@link MeterEstimate.candidates} entry it is that
+   * candidate's share of the summed support. The two are not comparable, so
+   * read the value from the field you meant rather than from whichever one is
+   * to hand.
+   */
   confidence: number;
 }
 
+/**
+ * Meter estimated over a caller-supplied beat series.
+ */
+export interface MeterEstimate {
+  /**
+   * Selected time signature.
+   *
+   * @remarks
+   * Its `confidence` is the margin over the runner-up — how separated the
+   * winner is — not the share-of-support a {@link candidates} entry carries
+   * under the same field name.
+   */
+  timeSignature: TimeSignature;
+  /** Beat index the first measure starts on, in `[0, timeSignature.numerator)`. */
+  downbeatPhase: number;
+  /**
+   * Whether a search ran, as opposed to the fixed fallback being reported.
+   *
+   * @remarks
+   * `false` means the beat series was too short to score any candidate, and
+   * every other field then carries that fallback rather than a measurement —
+   * `timeSignature.confidence` included, which is 0, so an unchecked read
+   * degrades toward "no idea" rather than toward a middling detection. Read
+   * this before treating a short span's answer as a detection.
+   */
+  searched: boolean;
+  /**
+   * How the bar divides, in beats per accent group.
+   *
+   * @remarks
+   * `[3, 2, 2]` is the 7/8 an aksak meter notates as 3+2+2, and `[2, 2]` an
+   * ordinary four. Always sums to `timeSignature.numerator`.
+   *
+   * A single entry means no internal division was resolved — the numerator has
+   * none to find, it was too wide to search, or the span was too short to
+   * search at all.
+   *
+   * This is also what tells a compound bar from a simple one: per-beat accents
+   * cannot say how a beat subdivides, so a six accented 3+3 keeps the requested
+   * denominator and reports `[3, 3]` rather than being promoted to 6/8.
+   */
+  grouping: number[];
+  /**
+   * Multi-comb score per requested candidate numerator.
+   *
+   * @remarks
+   * Parallel to the `candidateNumerators` that were requested, in the order
+   * they were given. This does NOT index alike with {@link candidates}, which
+   * is ordered by descending support.
+   *
+   * Standardized and signed: zero is the level a numerator reaches on beats
+   * carrying no meter, so a negative entry means less support than noise would
+   * produce. Only the ordering and the gaps between entries carry meaning.
+   *
+   * Comparable only within one result. A score grows with the square root of
+   * how many beats were scored, so the same meter over twice the beats scores
+   * about 1.41 times as high; a segmentation search comparing spans of
+   * different lengths has to normalize for length first.
+   */
+  candidateScores: number[];
+  /**
+   * Candidate signatures ordered by descending support.
+   *
+   * @remarks
+   * A ranking, so entry `k` is the k-th best hypothesis — not the k-th
+   * requested numerator. Use {@link candidateScores} to read the score of a
+   * specific requested numerator.
+   *
+   * Each entry's `confidence` is that candidate's share of the summed support,
+   * so the entries sum to one. It is a different quantity from
+   * {@link timeSignature}'s margin-derived confidence, which shares the field
+   * name and nothing else.
+   */
+  candidates: TimeSignature[];
+}
+
 /** Existing tempo-estimator hypothesis retained by unified analysis. */
 export interface BpmHypothesis {
   value: number;
@@ -356,7 +621,52 @@ export interface AnalysisResult {
   timeSignatureCandidates: TimeSignature[];
   beatTimes: Float32Array;
   beats: Beat[];
-  chords: Chord[];
+  /**
+   * Indices into {@link AnalysisResult.beats} that fall on a measure start.
+   *
+   * @remarks
+   * Not the same length as `beats` — it holds one entry per detected downbeat,
+   * and each entry indexes `beats`, so `beats[downbeatIndices[k]]` is the k-th
+   * downbeat. Testing a beat for downbeat status is a membership check on this
+   * list rather than a time comparison against a separate downbeat series.
+   */
+  downbeatIndices: number[];
+  /**
+   * Beat index the first measure starts on, in `[0, timeSignature.numerator)`.
+   *
+   * @remarks
+   * The meter estimator's phase, so `downbeatIndices` normally begins at this
+   * value. It is not re-derived when downbeats are refined from chord and
+   * low-frequency-energy evidence, so the two can disagree when the refinement
+   * moves the first measure start.
+   */
+  downbeatPhase: number;
+  /**
+   * Beat-level evidence behind the downbeat and meter decisions, parallel to
+   * {@link AnalysisResult.beats}.
+   */
+  beatObservations: BeatObservations;
+  /**
+   * Smoothed local tempo at each beat, in BPM, parallel to
+   * {@link AnalysisResult.beats}.
+   *
+   * @remarks
+   * Empty unless `computeTempoCurve` was set, and empty regardless when fewer
+   * than two beats were detected, since a tempo is a property of the interval
+   * between two beats. The last entry repeats the tempo of the interval leading
+   * into the final beat, which opens no interval of its own.
+   *
+   * Values are continuous, not points on a tempo grid: each is a weighted
+   * average, in log tempo, of the beat intervals around it. A steady tempo
+   * reads within about 1% at every beat, and a tempo that moves is followed a
+   * few beats late.
+   *
+   * This is the local tempo rather than {@link AnalysisResult.bpm} resampled:
+   * on material whose tempo moves it departs from `bpm`, and reading a single
+   * number out of it is not how to get the global tempo.
+   */
+  beatLocalBpm: number[];
+  chords: AnalysisChord[];
   sections: Section[];
   timbre: Timbre;
   dynamics: Dynamics;

package/src/public_types_playback.ts

@@ -0,0 +1,196 @@
+// Type-only: erased before runtime, so this does not create a module cycle with
+// playback_renderer.ts, which imports the config types declared below.
+import type { HrtfSet } from './playback_renderer';
+
+/**
+ * The playback renderer configuration document, in the schema
+ * `schemas/playback-renderer-config.schema.json` (also shipped as the
+ * `./schemas/playback-renderer-config.schema.json` package export). Field
+ * spelling is the schema's own (snake_case, dotted nesting) rather than this
+ * binding's usual camelCase: the document is parsed by the shared C++ core, so
+ * every surface has to agree on one literal spelling.
+ *
+ * Every key is either a "prepare" key (fixed at {@link PlaybackRenderer}
+ * construction; changing one through `setConfig` throws) or a "realtime" key
+ * (adopted at the next processed block). Omitted keys take the schema defaults
+ * documented on each field below.
+ */
+export interface PlaybackRendererConfig {
+  input?: PlaybackInputConfig;
+  target?: PlaybackTargetConfig;
+  /** LFE level folded into L/R when the output has no LFE plane or no subwoofer. Realtime, default 0. */
+  lfe_mix_db?: number;
+  upmix?: PlaybackUpmixConfig;
+  /** Static gain on the discrete centre of 5.1 / 7.1 input. Realtime, [-12, 12], default 0. */
+  dialogue_level_db?: number;
+  loudness?: PlaybackLoudnessConfig;
+  night_mode?: PlaybackNightModeConfig;
+  room?: PlaybackRoomConfig;
+  head_tracking?: PlaybackHeadTrackingConfig;
+  output_limiter?: PlaybackOutputLimiterConfig;
+}
+
+/** A speaker role name (`schemas/playback-renderer-config.schema.json` `$defs.role`). */
+export type PlaybackChannelRole = 'L' | 'R' | 'C' | 'LFE' | 'Ls' | 'Rs' | 'Lss' | 'Rss';
+
+export interface PlaybackInputConfig {
+  /** Prepare. `"auto"` follows the channel count of each processed block (1, 2, 6 or 8). Default `"auto"`. */
+  layout?: 'auto' | 'mono' | 'stereo' | '5.1' | '7.1';
+  /**
+   * Prepare. Role of each input channel, covering the fixed layout's roles
+   * exactly once; requires a fixed `layout`. `null` means canonical order.
+   */
+  channel_map?: PlaybackChannelRole[] | null;
+}
+
+export interface PlaybackSpeakerConfig {
+  /** Prepare. Listener distance in metres, [0.1, 30]; `null` disables distance compensation. Default `null`. */
+  distance_m?: number | null;
+  /** Realtime. Level trim in dB, [-20, 20]. Default 0. */
+  trim_db?: number;
+  /** Prepare. A `"small"` speaker is high-passed at the crossover when bass management is enabled. Default `"large"`. */
+  size?: 'large' | 'small';
+}
+
+export interface PlaybackBassManagementConfig {
+  /** Prepare. Default false. */
+  enabled?: boolean;
+  /** Prepare. LR4 crossover frequency, [40, 200]. Default 80. */
+  crossover_hz?: number;
+  /** Prepare. false folds the low band and LFE into the large L/R pair; L and R must then be large. Default true. */
+  subwoofer?: boolean;
+  /** Realtime. LFE gain when feeding the subwoofer, [-10, 15]. Default 10. */
+  lfe_gain_db?: number;
+}
+
+export interface PlaybackTargetConfig {
+  /** Prepare. Default `"headphones"`. */
+  kind?: 'headphones' | 'speakers';
+  /** Prepare. Required for `kind: "speakers"`, forbidden for `"headphones"`. */
+  layout?: 'stereo' | '5.1' | '7.1';
+  /** Per-speaker calibration keyed by role; only the non-LFE roles of the output layout. */
+  speakers?: Partial<Record<Exclude<PlaybackChannelRole, 'LFE'>, PlaybackSpeakerConfig>>;
+  bass_management?: PlaybackBassManagementConfig;
+}
+
+export interface PlaybackUpmixConfig {
+  /** Realtime. Stereo input only; the latency does not change. Default true. */
+  enabled?: boolean;
+  /** Realtime. Width of the centre window on the panning index, [0.05, 1]. Default 0.2. */
+  center_width?: number;
+  /** Realtime. Power share of the ambience kept in the front pair, [0, 1]. Default 0.5. */
+  front_ambience?: number;
+  /** Realtime. Derive LFE from the low-passed L/R sum. Default false. */
+  lfe_from_upmix?: boolean;
+}
+
+export interface PlaybackLoudnessConfig {
+  /** Realtime. Measured program loudness, [-70, 0]; `null` means no alignment gain. Default `null`. */
+  program_lufs?: number | null;
+  /** Realtime. [-40, -5]. Default -24. */
+  target_lufs?: number;
+}
+
+export interface PlaybackNightModeConfig {
+  /** Realtime. 0 disables the dynamic range control. [0, 1]. Default 0. */
+  amount?: number;
+}
+
+export interface PlaybackRoomConfig {
+  /** Prepare. Headphones only. Default `"living_room"`. */
+  preset?: 'none' | 'living_room' | 'home_theater' | 'screening_room';
+  /** Realtime. Level of the early reflections and the late reverberation, [-30, 6]. Default -6. */
+  mix_db?: number;
+  /** Realtime. Default true. */
+  enabled?: boolean;
+}
+
+export interface PlaybackHeadTrackingConfig {
+  /** Realtime. false treats the head pose as zero. Default true. */
+  enabled?: boolean;
+}
+
+export interface PlaybackOutputLimiterConfig {
+  /** Realtime. The latency does not change. Default true. */
+  enabled?: boolean;
+  /** Realtime. [-12, 0]. Default -1. */
+  ceiling_db?: number;
+}
+
+/** A stage name used in {@link PlaybackDiagnostics.inactive_stages} and `.latency.stages`. */
+export type PlaybackStageName =
+  | 'reorder'
+  | 'dialogue_level'
+  | 'upmix'
+  | 'loudness'
+  | 'night_mode'
+  | 'layout_convert'
+  | 'speaker_calibration'
+  | 'bass_management'
+  | 'binaural'
+  | 'room_early'
+  | 'room_late'
+  | 'output_limiter';
+
+/** Per-stage reported latency, in samples and in Q8 fixed-point. */
+export interface PlaybackStageLatency {
+  samples: number;
+  q8: number;
+}
+
+/**
+ * The renderer's diagnostics document, a plain object that can be sent through
+ * `postMessage` as is. Field spelling is the core's own (snake_case), the same
+ * pass-through convention as {@link PlaybackRendererConfig}.
+ */
+export interface PlaybackDiagnostics {
+  active_input_layout: 'mono' | 'stereo' | '5.1' | '7.1';
+  layout_switches: number;
+  truncated_drains: number;
+  /** Stages this configuration does not exercise (e.g. `room_early` for a speakers target). */
+  inactive_stages: PlaybackStageName[];
+  latency: {
+    samples: number;
+    /** Every stage name reports an entry, whether or not it is currently active. */
+    stages: Record<PlaybackStageName, PlaybackStageLatency>;
+  };
+  loudness_gain_db: number;
+  loudness_gain_clamped: boolean;
+  /** True when an `hrtf` was supplied to a speakers target, which ignores it. */
+  hrtf_ignored: boolean;
+  /** Deepest last-block gain reduction across the main and LFE limiters, in dB (<= 0). */
+  limiter_gain_reduction_db: number;
+  non_finite_discards: number;
+}
+
+/** Request shape for the {@link PlaybackRenderer} constructor. */
+export interface PlaybackRendererOptions {
+  config: PlaybackRendererConfig | string;
+  /**
+   * Required for a headphones target: this build embeds no HRTF data. Load the
+   * package asset `./hrtf/default.shrf` (or any SHRF v1 file) and pass it
+   * through `HrtfSet.fromBytes`. Ignored by a speakers target.
+   */
+  hrtf?: HrtfSet;
+  /** Default 48000. */
+  sampleRate?: number;
+  /** Upper bound on the frames of every process call. Default 1024. */
+  maxBlockSize?: number;
+}
+
+/** Request shape for the one-shot `renderPlayback`. */
+export interface RenderPlaybackRequest {
+  /** Interleaved input, `channels` samples per frame. */
+  samples: Float32Array;
+  channels: number;
+  sampleRate: number;
+  config: PlaybackRendererConfig | string;
+  /** Required for a headphones target; see {@link PlaybackRendererOptions.hrtf}. */
+  hrtf?: HrtfSet;
+}
+
+/** `renderPlayback`'s result: interleaved output with the target's own channel count. */
+export interface RenderPlaybackResult {
+  samples: Float32Array;
+  channels: number;
+}

package/src/public_types_realtime.ts

@@ -1,12 +1,17 @@
 /**
- * Realtime equalizer spectrum snapshot.
+ * Realtime equalizer snapshot.
  *
  * Mirrors the C++ `EqualizerSpectrumSnapshot`: `preLeft`/`preRight` and
- * `postLeft`/`postRight` are the pre- and post-EQ spectrum streams (trimmed to
- * their valid count). `bandGainDb` holds per-band applied gain (24 entries),
- * `profileDb` the smoothed magnitude profile (16 entries), `lastAutoGainDb`
- * the latest auto-gain compensation, and `seq` increments each time a new
- * snapshot is published.
+ * `postLeft`/`postRight` are the pre- and post-EQ waveform streams (uniformly
+ * decimated time-domain samples, trimmed to their valid count), so they are a
+ * scope feed rather than a spectral estimate. `bandGainDb` holds per-band
+ * applied gain (24 entries). `profileDb` is the frequency-domain view: the
+ * post-EQ signal is Hann-windowed, transformed and its bin powers summed into
+ * 16 geometrically spaced bands covering 20 Hz to 20 kHz, in amplitude decibels
+ * relative to full scale (a full-scale sine reads about 0 dB in its own band),
+ * rising immediately and falling smoothly. `lastAutoGainDb` is the latest
+ * auto-gain compensation, and `seq` increments each time a new snapshot is
+ * published.
  */
 export interface EqSpectrumSnapshot {
   preLeft: Float32Array;
@@ -31,7 +36,8 @@ export type EqBandType =
   | 'BandPass'
   | 'Notch'
   | 'TiltShelf'
-  | 'FlatTilt';
+  | 'FlatTilt'
+  | 'AllPass';
 
 /** Biquad coefficient design mode. */
 export type EqCoeffMode = 'Rbj' | 'Vicanek';
@@ -52,11 +58,27 @@ export interface EqBand {
   type?: EqBandType;
   frequencyHz?: number;
   gainDb?: number;
+  /**
+   * Resonance/slope. Ignored for a LowShelf/HighShelf band once `phase:
+   * 'NaturalPhase'` forces Vicanek coefficients (the Vicanek matched-Z shelf
+   * design has no Q/S parameter) -- the value is still stored and read back
+   * verbatim, so a reflected `q` on such a band does not describe the applied
+   * response. Set `coeffMode: 'Rbj'` for a Q-controllable shelf.
+   */
   q?: number;
   enabled?: boolean;
   coeffMode?: EqCoeffMode;
+  /**
+   * Slope in dB/octave. 6 selects a first-order section on a pass or shelf
+   * band; a first-order shelf's frequency is its half-gain point and its `q`
+   * is unused.
+   */
   slopeDbOct?: number;
   placement?: EqStereoPlacement;
+  /**
+   * `'NaturalPhase'` forces `coeffMode: 'Vicanek'` for this band, which
+   * ignores `q` for LowShelf/HighShelf (see `q`'s doc).
+   */
   phase?: EqBandPhase;
   soloed?: boolean;
   bypassed?: boolean;
@@ -69,6 +91,13 @@ export interface EqBand {
   rangeDb?: number;
   attackMs?: number;
   releaseMs?: number;
+  /**
+   * Delays the detector's view of the signal by this many ms; a larger value
+   * makes the band react LATER, not earlier -- this is a detector delay, not
+   * true look-ahead, and adds no latency to the audio path.
+   */
+  detectorDelayMs?: number;
+  /** Former (misleading) spelling of `detectorDelayMs`, still accepted; `detectorDelayMs` wins if both are set. */
   lookaheadMs?: number;
   externalSidechain?: boolean;
   sidechainFreqHz?: number;
@@ -179,3 +208,6 @@ export interface RealtimeVoiceChangerPodConfig {
   /** True-peak ceiling in dBTP applied by the ISP limiter (default -1.0). */
   limiterIspCeilingDbtp: number;
 }
+
+/** One raw UMP message: 1 to 4 words, most significant word first. */
+export type UmpWords = Uint32Array | readonly number[];