@libraz/libsonare 1.7.2 → 1.8.0

package/src/project_types.ts

@@ -1,3 +1,5 @@
+// Type-only, so the erased import adds no runtime edge to the codes module.
+import type { PROJECT_AUTOMATION_CURVE_VALUES } from './codes';
 import type { Project } from './project_class';
 
 // ============================================================================
@@ -9,7 +11,7 @@ import type { Project } from './project_class';
  * `src/sonare_c_project.h`; checked against {@link projectAbiVersion} to detect
  * a WASM build whose flat project POD layout has drifted from this wrapper.
  */
-export const EXPECTED_PROJECT_ABI_VERSION = 1;
+export const EXPECTED_PROJECT_ABI_VERSION = 2;
 
 /** Render options for {@link Project.bounce}. All fields are optional. */
 export interface ProjectBounceOptions {
@@ -17,9 +19,18 @@ export interface ProjectBounceOptions {
   totalFrames?: number;
   /** Render block size; <= 0 uses the engine default (128). */
   blockSize?: number;
-  /** Output channel count; <= 0 uses the default (2). */
+  /**
+   * Output channel count: 1, 2, 6 or 8, and at most the width of the scene
+   * master's layout (mono/stereo/no master allow 2). The master is mixed at
+   * this width; 1 folds a 2-channel master to 0.5(L+R). <= 0 uses the default
+   * (2).
+   */
   numChannels?: number;
-  /** Output sample rate; <= 0 uses the project sample rate. */
+  /**
+   * Output sample rate. This is not a resample: a positive value must equal
+   * the project's own sample rate, or the bounce is refused. <= 0 uses the
+   * project sample rate.
+   */
   sampleRate?: number;
   /** Host-instrument PDC (latency) fed to the compiler. */
   instrumentLatencySamples?: number;
@@ -116,255 +127,6 @@ export interface ProjectSource {
   externalStemRole: string;
 }
 
-/** Names accepted by the minimal built-in oscillator synth. */
-export const BUILTIN_SYNTH_WAVEFORMS = ['sine', 'saw', 'sawtooth', 'square', 'triangle'] as const;
-
-/** Oscillator waveform for the built-in synth. */
-export type BuiltinSynthWaveform = (typeof BUILTIN_SYNTH_WAVEFORMS)[number] | 0 | 1 | 2 | 3;
-
-/**
- * Built-in synth patch + MIDI routing for
- * {@link Project.bounceWithBuiltinInstrument}. Every field is optional; a
- * non-positive (or omitted) numeric field falls back to the C-ABI default
- * (gain 0.2, attack 5ms, decay 60ms, sustain 0.7, release 120ms, 16 voices),
- * so `{}` is a usable default sine patch.
- */
-export interface BuiltinSynthBinding {
-  /** MIDI destination id this patch answers to (default 0; see {@link Project.setTrackMidiDestination}). */
-  destinationId?: number;
-  /** Oscillator waveform (default `'sine'`). */
-  waveform?: BuiltinSynthWaveform;
-  /** Master output gain, linear (0 => 0.2). */
-  gain?: number;
-  /** ADSR attack in ms (0 => 5). */
-  attackMs?: number;
-  /** ADSR decay in ms (0 => 60). */
-  decayMs?: number;
-  /** ADSR sustain level [0,1] (0 => 0.7). */
-  sustain?: number;
-  /** ADSR release in ms (0 => 120). */
-  releaseMs?: number;
-  /** Max simultaneous voices (0 => 16, clamped to [1, 64]). */
-  polyphony?: number;
-}
-
-/**
- * Cross-binding alias of {@link BuiltinSynthBinding}. The same built-in-synth
- * patch concept is named `BuiltinSynthConfig` in the Python binding; this alias
- * lets portable code use that shared name on the WASM surface too.
- */
-export type BuiltinSynthConfig = BuiltinSynthBinding;
-
-/**
- * SoundFont (SF2) player patch + MIDI routing for
- * {@link Project.bounceWithSf2Instrument}. Every field is optional; a
- * non-positive (or omitted) numeric field falls back to the C-ABI default
- * (gain 0.5, 48 voices), so `{}` is a usable default patch.
- */
-export interface Sf2InstrumentConfig {
-  /** MIDI destination id this player answers to (default 0; see {@link Project.setTrackMidiDestination}). */
-  destinationId?: number;
-  /** Master output gain, linear (0 => 0.5). */
-  gain?: number;
-  /** Max simultaneous voices (0 => 48, clamped to [1, 64]). */
-  polyphony?: number;
-  /** Prefer dedicated physical models for covered melodic GM programs. Defaults to false; drums stay SF2-first. */
-  preferModelForModeledFamilies?: boolean;
-}
-
-/** Source backend a resolved MIDI program renders through. */
-export type SourceBackend = 'sf2' | 'synth';
-
-/**
- * One {@link Project.soundFontManifest} entry: a (channel, bank, program)
- * combination the arrangement plays, with the backend it resolves to.
- */
-export interface Sf2ProgramStatus {
-  /** MIDI channel (0-15). */
-  channel: number;
-  /** Effective SF2 bank (drum channels report 128). */
-  bank: number;
-  /** Program number (0-127). */
-  program: number;
-  /** `'sf2'` when the loaded SoundFont covers the program, else `'synth'`. */
-  backend: SourceBackend;
-  /** Resolved SF2 preset name (GS fallback included); empty for `'synth'`. */
-  presetName: string;
-}
-
-export const SYNTH_ENGINE_MODES = [
-  'default',
-  'subtractive',
-  'fm',
-  'karplus-strong',
-  'modal',
-  'additive',
-  'percussion',
-  'piano',
-  'pipe-organ',
-  'bowed-string',
-  'reed',
-  'brass',
-  'flute',
-  'plucked-string',
-  'vocal',
-  'free-reed',
-] as const;
-export const SYNTH_OSC_WAVEFORMS = [
-  'default',
-  'sine',
-  'saw',
-  'square',
-  'triangle',
-  'noise',
-] as const;
-export const SYNTH_FILTER_MODELS = [
-  'default',
-  'svf',
-  'moog-ladder',
-  'diode-ladder',
-  'sallen-key',
-] as const;
-export const SYNTH_FILTER_OUTPUTS = ['default', 'lowpass', 'bandpass', 'highpass'] as const;
-export const SYNTH_BODY_TYPES = [
-  'default',
-  'none',
-  'guitar',
-  'violin',
-  'wood-tube',
-  'brass-bell',
-  'vocal',
-] as const;
-export const SYNTH_MOD_SOURCES = [
-  'none',
-  'amp-env',
-  'filter-env',
-  'lfo1',
-  'lfo2',
-  'velocity',
-  'key-track',
-  'mod-wheel',
-  'random',
-] as const;
-export const SYNTH_MOD_DESTINATIONS = [
-  'none',
-  'pitch-cents',
-  'cutoff-cents',
-  'amp-gain',
-  'pan-units',
-] as const;
-
-export interface SynthEnumTables {
-  engineModes: string[];
-  waveforms: string[];
-  builtinWaveforms: string[];
-  filterModels: string[];
-  filterOutputs: string[];
-  bodyTypes: string[];
-  modSources: string[];
-  modDestinations: string[];
-}
-
-/** NativeSynth engine selector ({@link SynthPatch}; `'default'` keeps the base patch's). */
-export type SynthEngineMode = (typeof SYNTH_ENGINE_MODES)[number];
-
-/** NativeSynth oscillator waveform (`'default'` keeps the base patch's). */
-export type SynthOscWaveform = (typeof SYNTH_OSC_WAVEFORMS)[number];
-
-/** NativeSynth filter model — the character core (`'default'` keeps the base patch's). */
-export type SynthFilterModel = (typeof SYNTH_FILTER_MODELS)[number];
-
-/** NativeSynth filter output (SVF only; `'default'` keeps the base patch's). */
-export type SynthFilterOutput = (typeof SYNTH_FILTER_OUTPUTS)[number];
-
-/** NativeSynth body/formant resonance voicing (`'default'` keeps the base patch's). */
-export type SynthBodyType = (typeof SYNTH_BODY_TYPES)[number];
-
-/** {@link SynthPatch} mod-matrix source. */
-export type SynthModSource = (typeof SYNTH_MOD_SOURCES)[number];
-
-/** {@link SynthPatch} mod-matrix destination. */
-export type SynthModDestination = (typeof SYNTH_MOD_DESTINATIONS)[number];
-
-/** One {@link SynthPatch} mod-matrix routing (name or C ordinal per field). */
-export interface SynthModRouting {
-  source: SynthModSource | number;
-  destination: SynthModDestination | number;
-  /** Destination units at full source deflection. */
-  depth: number;
-}
-
-/**
- * Versioned NativeSynth patch for {@link Project.bounceWithSynthInstrument}
- * and {@link RealtimeEngine.setSynthInstrument}.
- *
- * The patch starts from a BASE — the named `preset` (see
- * {@link synthPresetNames}; a `"va:"` routing prefix is accepted) or, when
- * `preset` is omitted, the default subtractive patch. Omitting a numeric field
- * keeps the base value; supplying one overrides it (clamped to its audible
- * range), including an explicit `0` such as `stereoSpread: 0`. The enum fields
- * reserve `'default'` as keep. A `modRoutings` array REPLACES the base mod
- * matrix, and an empty array clears it, while omitting the key keeps it.
- *
- * Mode-specific deep parameters (FM operator stacks, modal mode tables,
- * drawbar registrations, kit pieces, piano strings) travel inside the named
- * presets; the patch exposes the wrapper sections every engine shares.
- */
-export interface SynthPatch {
-  /**
-   * Optional binding convenience for JS realtime/offline helpers. It is not
-   * part of the NativeSynth patch itself; Python uses explicit
-   * `(destination_id, patch)` bindings instead. Defaults to `0`.
-   */
-  destinationId?: number;
-  /** Resolve MIDI channels from incoming GM bank/program changes; defaults to false. */
-  useGmPrograms?: boolean;
-  /** Base preset name (see {@link synthPresetNames}); omit for the init patch. */
-  preset?: string;
-  engineMode?: SynthEngineMode | number;
-  waveform?: SynthOscWaveform | number;
-  /** Detuned-stack width [1, 7]. */
-  unison?: number;
-  detuneCents?: number;
-  /** Per-voice slow pitch drift depth (cents). */
-  driftCents?: number;
-  /** Pre-filter drive [0, 1]. */
-  drive?: number;
-  filterModel?: SynthFilterModel | number;
-  filterOutput?: SynthFilterOutput | number;
-  cutoffHz?: number;
-  resonanceQ?: number;
-  /** Cutoff keyboard tracking [0, 1]. */
-  keyTrack?: number;
-  envToCutoffCents?: number;
-  velToCutoffCents?: number;
-  ampAttackMs?: number;
-  ampDecayMs?: number;
-  ampSustain?: number;
-  ampReleaseMs?: number;
-  filterAttackMs?: number;
-  filterDecayMs?: number;
-  filterSustain?: number;
-  filterReleaseMs?: number;
-  lfoRateHz?: number;
-  lfoToPitchCents?: number;
-  lfo2RateHz?: number;
-  glideMs?: number;
-  body?: SynthBodyType | number;
-  /** Body resonance mix [0, 1]. */
-  bodyMix?: number;
-  /** Seeded per-voice pan scatter [0, 1]. */
-  stereoSpread?: number;
-  /** Mod matrix (at most 8 routings; REPLACES the base matrix when non-empty). */
-  modRoutings?: SynthModRouting[];
-  /** Master output gain (linear). */
-  gain?: number;
-  /** Max simultaneous voices [1, 64]. */
-  polyphony?: number;
-  /** Gain-neutral bus saturation [0, 1]. */
-  busDrive?: number;
-}
-
 /** Clip fade-curve for {@link Project.setClipFade}. */
 export type ProjectFadeCurve =
   | 'linear'
@@ -402,6 +164,8 @@ export interface ProjectClipCompSegment {
   startPpq: number;
   endPpq: number;
   takeId?: number;
+  /** Equal-power crossfade from the preceding segment, in PPQ (default 0 = butt join). */
+  crossfadePpq?: number;
 }
 
 /** Descriptor for {@link Project.addLoopRecordingTakes}. */
@@ -422,24 +186,29 @@ export interface ProjectLoopRecordingResult {
 
 /** Clip loop mode for {@link Project.setClipLoop}. */
 export type ProjectLoopMode = 'off' | 'loop' | 0 | 1;
-export type ProjectWarpMode = 'off' | 'repitch' | 'tempo-sync' | 0 | 1 | 2;
+/**
+ * How a clip follows its warp map.
+ *
+ * - `'off'` — no warping.
+ * - `'repitch'` — resample along the map, so a rate change moves the pitch with
+ *   the timing (tape-style).
+ * - `'tempo-sync'` — control-thread bake against the tempo map.
+ * - `'time-stretch'` — realtime pitch-preserving stretch. Follows the same map
+ *   as `'repitch'` but overlap-adds instead of resampling, so a new anchor set
+ *   takes effect from the next block with no re-bake. Falls back to `'repitch'`
+ *   behaviour when the stretcher's voice budget is exhausted.
+ */
+export type ProjectWarpMode = 'off' | 'repitch' | 'tempo-sync' | 'time-stretch' | 0 | 1 | 2 | 3;
 
 /**
  * Automation breakpoint interpolation for {@link ProjectAutomationPoint}.
  *
  * `'s-curve'` is the canonical spelling, matching the Node engine and the mixer
  * automation types. The legacy `'scurve'` remains accepted for compatibility.
+ * The spellings are derived from the resolver's own table, so the documented
+ * set and the accepted set cannot drift apart.
  */
-export type ProjectAutomationCurve =
-  | 'linear'
-  | 'exponential'
-  | 'hold'
-  | 's-curve'
-  | 'scurve'
-  | 0
-  | 1
-  | 2
-  | 3;
+export type ProjectAutomationCurve = 0 | 1 | 2 | 3 | keyof typeof PROJECT_AUTOMATION_CURVE_VALUES;
 
 /** One automation breakpoint accepted by the automation-lane edit ops. */
 export interface ProjectAutomationPoint {
@@ -449,6 +218,8 @@ export interface ProjectAutomationPoint {
   value: number;
   /** Curve to the next breakpoint (default `'linear'`). */
   curve?: ProjectAutomationCurve;
+  /** Alias of {@link ProjectAutomationPoint.curve}; `curve` wins when both are set. */
+  curveToNext?: ProjectAutomationCurve;
 }
 
 /**
@@ -487,7 +258,11 @@ export interface ProjectTempoSegment {
   startPpq: number;
   /** Tempo in beats per minute at the segment start. */
   bpm: number;
-  /** Derived segment start in samples. Accepted for compatibility, ignored on input. */
+  /**
+   * Derived segment start in samples. Accepted for compatibility and ignored on
+   * input; never returned, because a project stores musical positions only and
+   * sample positions are derived when it is compiled.
+   */
   startSample?: number;
   /** Optional ramp end tempo in BPM (0 = constant tempo over the segment). */
   endBpm?: number;
@@ -504,6 +279,40 @@ export interface ProjectTimeSignatureSegment {
 }
 
 /** A ranked primary/half/double tempo hypothesis returned by {@link Project.analyzeTempo}. */
+/**
+ * Scoring options for the beat-analysis to tempo-map bridge, shared by
+ * {@link Project.analyzeTempo} and {@link Project.autoTempo}.
+ *
+ * @remarks
+ * Every field is optional and falls back to the native default. Pair the two
+ * calls on the same options: `candidateIndex` indexes the ranking `analyzeTempo`
+ * produced under whatever options it was given.
+ */
+export interface ProjectTempoOptions {
+  /**
+   * Whether beat tracking may follow a tempo that moves during the take
+   * (default: `false`).
+   *
+   * @remarks
+   * With it off the tracker fits one tempo to the whole take, so on a
+   * performance that accelerates, slows or breathes every segment the bridge
+   * emits sits near the take's average. Leave it off for material recorded to a
+   * click; turn it on for a performance. Constant-tempo material still comes
+   * back as a single segment either way.
+   */
+  adaptiveTempo?: boolean;
+  /** Beats of context the local tempo estimate is read over. Used only when {@link adaptiveTempo} is on. */
+  tempoUpdateIntervalBeats?: number;
+  /**
+   * Relative tempo change at which one segment closes and the next opens
+   * (default: `0.02`). Smaller follows the performance more closely and emits
+   * more segments; larger merges more of it into constant stretches.
+   */
+  rampThreshold?: number;
+  /** Whether to rank the half- and double-tempo alternatives alongside the primary (default: `true`). */
+  includeOctaveCandidates?: boolean;
+}
+
 export interface ProjectTempoCandidate {
   bpm: number;
   confidence: number;
@@ -586,6 +395,79 @@ export interface ProjectWarpMapDesc {
   anchors: ProjectWarpAnchor[];
 }
 
+/**
+ * Canonical request form for {@link alignTakeToReference}.
+ *
+ * Both resolution fields are optional and omitting one takes the library value.
+ * A `0` is **refused** rather than read as a request for the default: neither
+ * field has a meaning at 0, so omission is already how you ask for the default,
+ * and a substituted value is indistinguishable downstream from one you chose.
+ */
+export interface AlignTakeToReferenceRequest {
+  /**
+   * The reference timeline — the guide take, or the backing track the takes were
+   * sung against. Must be non-empty and all-finite.
+   */
+  reference: Float32Array;
+  /** The take to be placed under it. Must be non-empty and all-finite. */
+  take: Float32Array;
+  /**
+   * Sample rate of **both** buffers in Hz, `[8000, 384000]`. Resample first if
+   * they differ: the alignment does no rate conversion.
+   */
+  sampleRate: number;
+  /**
+   * Chroma hop in samples, which sets the time resolution of the anchors — a
+   * smaller hop measures more frames and yields more anchors. Default `512`;
+   * must be a positive integer.
+   */
+  hopLength?: number;
+  /**
+   * Chroma bins per octave — the CQT resolution the twelve pitch classes are
+   * folded from. Default `12`; must be a positive **multiple of 12**, since each
+   * pitch class takes the mean of a whole number of CQT bins.
+   */
+  binsPerOctave?: number;
+}
+
+/**
+ * How well an alignment was conditioned, reported by
+ * {@link AlignTakeToReferenceResult}.
+ *
+ * Every field is descriptive: none of them makes the call fail, and a caller
+ * deciding what is acceptable supplies its own threshold.
+ */
+export interface TakeAlignment {
+  /**
+   * Mean absolute frame residual of the path around its diagonal trend. A coarse
+   * indicator of how far the alignment strayed from a constant rate, not an error
+   * bound.
+   */
+  meanResidualFrames: number;
+  /** Chroma frames the reference produced. */
+  referenceFrames: number;
+  /**
+   * Chroma frames the take produced. Its ratio to `referenceFrames` is the
+   * overall rate difference the anchors encode.
+   */
+  takeFrames: number;
+}
+
+/** Result of {@link alignTakeToReference}. */
+export interface AlignTakeToReferenceResult {
+  /**
+   * At least two finite, strictly increasing anchors, ready to hand to
+   * {@link Project.setWarpMap} as the take clip's own warp map.
+   *
+   * `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.
+   */
+  anchors: ProjectWarpAnchor[];
+  /** How well the alignment was conditioned. */
+  alignment: TakeAlignment;
+}
+
 /** Descriptor for {@link Project.addClip}. */
 export interface ProjectClipDesc {
   trackId: number;
@@ -596,6 +478,11 @@ export interface ProjectClipDesc {
   gain?: number;
   audio?: Float32Array;
   audioChannels?: number;
+  /**
+   * Sample rate of `audio` in Hz. Required whenever `audio` is supplied, and
+   * must be in `[8000, 384000]`: omitting it sends 0, which the native side
+   * rejects. Ignored for a metadata-only clip.
+   */
   audioSampleRate?: number;
   sourceUri?: string;
 }
@@ -607,6 +494,15 @@ export interface ProjectMidiClipResult {
 }
 
 /** Flat MIDI event accepted by {@link Project.setMidiEvents}. */
+/**
+ * One MIDI event in a clip's list: a position plus the first two UMP words.
+ *
+ * @remarks
+ * Channel-voice messages only. A clip's SysEx payloads live beside the event
+ * list and are reached by a handle this type does not carry — they survive
+ * {@link Project.importSmf}, {@link Project.exportSmf} and project
+ * serialization, and are destroyed by {@link Project.setMidiEvents}.
+ */
 export interface ProjectMidiEvent {
   ppq: number;
   data0: number;
@@ -643,16 +539,18 @@ export interface MidiCcLearnOptions {
 /** MIDI CC <-> automation binding descriptor used by CC learn/conversion helpers. */
 export interface ProjectMidiCcBinding {
   ccNumber: number;
-  /** MIDI channel 0..15, or 255 for any channel. */
-  channel: number;
-  /** 0 = 7-bit CC, 1 = 14-bit CC, 2 = RPN, 3 = NRPN. */
-  kind: ProjectMidiCcBindingKind;
+  /** MIDI channel 0..15, or 255 for any channel. Omit for the any-channel sentinel `255`. */
+  channel?: number;
+  /** 0 = 7-bit CC, 1 = 14-bit CC, 2 = RPN, 3 = NRPN. Default `0`. */
+  kind?: ProjectMidiCcBindingKind;
   ccLsbNumber?: number;
   selectorMsb?: number;
   selectorLsb?: number;
   paramId: number;
-  minValue: number;
-  maxValue: number;
+  /** Lower end of the mapped parameter range. Default `0`. */
+  minValue?: number;
+  /** Upper end of the mapped parameter range. Default `1`. */
+  maxValue?: number;
 }
 
 /** Result of {@link Project.validateMidiNotes}. */
@@ -699,6 +597,106 @@ export interface ProjectMidiFxPreviewRequest {
   configJson: string;
 }
 
+/**
+ * Detector settings shared by {@link transcribe} and
+ * {@link Project.transcribeToClip}.
+ *
+ * Every field is optional and omitting one takes the documented default. A
+ * value outside a field's domain is **refused**, never silently replaced — a
+ * substituted default is indistinguishable downstream from one you chose.
+ *
+ * That includes `0` on the fields whose domain excludes it (`referenceHz`,
+ * `fmin`, `fmax`, `minNoteMs`, `segmentationThresholdCents`,
+ * `velocityFloorDb`, `fixedVelocity`): omitting the field is how you ask for
+ * the default, so a `0` you wrote is a value, and it is out of domain. Only
+ * `group` and `channel` accept `0` — there it is a value you can mean.
+ */
+export interface TranscribeOptions {
+  /**
+   * `true` reads the multi-F0 chain, which finds overlapping notes at the cost
+   * of a full STFT and a mask per tracked ridge. `false` (the default) reads
+   * pYIN cut into notes, which follows one line at a time.
+   */
+  polyphonic?: boolean;
+  /**
+   * Tuning reference in Hz the MIDI note numbers are measured against.
+   * Default `440`; must be finite and positive.
+   *
+   * **It is not measured for you.** A take recorded away from A440 should have
+   * its reference measured first — run `pitchPyin` and feed its F0 array to
+   * `pitchTuning` — and the answer passed in here. Measuring it internally
+   * would track the pitch twice and hide which of the two answers a wrong
+   * transcription came from.
+   */
+  referenceHz?: number;
+  /**
+   * Monophonic tracker range in Hz. Defaults `65` and `2093`; both must be
+   * finite and positive, and `fmax` must exceed `fmin`. The polyphonic chain
+   * sets its own range and reads neither.
+   */
+  fmin?: number;
+  /** Upper end of the monophonic tracker range in Hz. Default `2093`. */
+  fmax?: number;
+  /** Shortest span kept as a note, in milliseconds. Default `30`; must be positive. */
+  minNoteMs?: number;
+  /**
+   * Pitch movement, in cents, that ends one note and starts the next.
+   * Default `50`; must be positive.
+   */
+  segmentationThresholdCents?: number;
+  /**
+   * Level mapped to velocity 1, in dBFS. Default `-48`; **must be negative**.
+   *
+   * A note's peak per-frame RMS is taken in dBFS and mapped linearly from
+   * `[velocityFloorDb, 0]` onto `[1, 127]`, clamped at both ends.
+   */
+  velocityFloorDb?: number;
+  /**
+   * An integer in `[1, 127]` gives every note that velocity and skips the level
+   * measurement. **Omit the field to measure** — `0` is refused, because it is
+   * not a MIDI velocity and omission already says "measure".
+   */
+  fixedVelocity?: number;
+  /** UMP group the events are emitted on, `0..15`. Default `0`. */
+  group?: number;
+  /** MIDI channel the events are emitted on, `0..15`. Default `0`. */
+  channel?: number;
+}
+
+/** Result of {@link transcribe}. */
+export interface TranscribeResult {
+  /**
+   * Note-on / note-off pairs in canonical PPQ order, ready to hand straight to
+   * {@link Project.setMidiEvents}.
+   *
+   * Ordering is `(ppq, note-off before note-on)`. A note-off sharing a tick
+   * with the next note's on comes first, so a consumer playing the events in
+   * order does not start a legato repeat of the same pitch and immediately
+   * stop it.
+   */
+  events: ProjectMidiEvent[];
+  /** Number of notes, which is always half `events.length`. */
+  noteCount: number;
+  /** The tempo the PPQ coordinates were built on — yours when you gave one, the detected one otherwise. */
+  tempoBpm: number;
+}
+
+/**
+ * Request form of {@link Project.transcribeToClip}.
+ *
+ * No `tempoBpm`: the PPQ grid is the **project's own tempo map**, so a project
+ * whose tempo was installed by {@link Project.autoTempo} transcribes onto that
+ * map rather than onto a second, separately detected tempo.
+ */
+export interface ProjectTranscribeRequest extends TranscribeOptions {
+  /** Target MIDI clip id. Its entire event list is replaced. */
+  clipId: number;
+  /** Mono source audio. Must be non-empty and all-finite. */
+  samples: Float32Array;
+  /** Sample rate of `samples` in Hz, `[8000, 384000]`. */
+  sampleRate: number;
+}
+
 /** One compile diagnostic (mirrors SonareProjectDiagnostic). */
 export interface ProjectDiagnostic {
   code: number;