@libraz/libsonare 1.3.2 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@libraz/libsonare",
-  "version": "1.3.2",
+  "version": "1.4.0",
   "type": "module",
   "packageManager": "yarn@4.15.0",
   "description": "Audio analysis library for music information retrieval",

package/src/codes.ts

@@ -52,5 +52,10 @@ export function meterTapCode(tap: MeterTap | number): number {
 }
 
 export function sendTimingCode(timing: SendTiming | number): number {
-  return timing === 'preFader' || timing === 0 ? 0 : 1;
+  // Mirrors SonareSendTiming: post-fader is 0 (so an omitted/zeroed value is
+  // post-fader), pre-fader is 1. A raw number is passed through as the C ABI int.
+  if (typeof timing === 'number') {
+    return timing;
+  }
+  return timing === 'preFader' ? 1 : 0;
 }

package/src/effects_mastering.ts

@@ -16,13 +16,15 @@ import type {
   PairProcessor,
   RealtimeVoiceChangerConfigInput,
   SoloProcessor,
+  SpectralEditOptions,
+  SpectralRegionOp,
   StereoAnalysis,
   StreamingPlatform,
 } from './public_types';
 import type { ProgressCallback } from './sonare.js';
 import { RealtimeVoiceChanger } from './streaming_mixing';
 import type { ValidateOptions } from './validation';
-import { assertSamples } from './validation';
+import { assertSampleRate, assertSamples } from './validation';
 
 function requireModule() {
   return getSonareModule();
@@ -339,6 +341,31 @@ export function normalize(
   return requireModule().normalize(samples, sampleRate, targetDb);
 }
 
+/**
+ * Apply region-based spectral edits (gain/attenuate/mute/heal) to mono audio.
+ *
+ * Each op is a time x frequency rectangle applied in array order over a single
+ * STFT buffer, so a later op observes the result of earlier ops. The output has
+ * the same length and sample rate as the input; an empty `ops` list is an
+ * identity transform (within the iSTFT's own tolerance).
+ *
+ * @param samples - Audio samples (mono, float32)
+ * @param sampleRate - Sample rate in Hz
+ * @param ops - Region edit ops applied in order ({@link SpectralRegionOp})
+ * @param options - STFT + heal configuration ({@link SpectralEditOptions})
+ * @returns Edited audio
+ */
+export function spectralEdit(
+  samples: Float32Array,
+  sampleRate: number,
+  ops: SpectralRegionOp[] = [],
+  options: SpectralEditOptions & ValidateOptions = {},
+): Float32Array {
+  assertSamples('spectralEdit', samples, options.validate !== false);
+  assertSampleRate('spectralEdit', sampleRate);
+  return requireModule().spectralEdit(samples, sampleRate, ops, options as Record<string, unknown>);
+}
+
 /**
  * Apply mastering loudness normalization with a true-peak ceiling.
  *
@@ -392,6 +419,81 @@ export function masteringInsertParamNames(name: string): string[] {
   ).masteringInsertParamNames(name);
 }
 
+/** One realtime-automatable parameter of an insert processor. */
+export interface MasteringInsertParamInfo {
+  /** JSON-key parameter name, as used in scene insert params. */
+  name: string;
+  /** Integer param id for realtime automation lanes / MIDI-CC binding. */
+  id: number;
+  /** Whether the param can be changed live from the audio thread. */
+  rtSafe: boolean;
+}
+
+/**
+ * Returns the realtime-automatable parameter descriptors for an insert / FX
+ * processor: each entry maps a JSON-key parameter name to the integer id used by
+ * realtime automation and reports whether it is realtime-safe. Unlike
+ * {@link masteringInsertParamNames} (every construction key), this lists only the
+ * realtime-controllable subset — the keys accepted by
+ * {@link RealtimeEngine.setTrackStripInsertParamByName}. Returns an empty array
+ * for an unknown name or a processor with no automatable parameters.
+ *
+ * @param name - Insert processor name (see {@link masteringInsertNames}).
+ */
+export function masteringInsertParamInfo(name: string): MasteringInsertParamInfo[] {
+  const json = (
+    requireModule() as unknown as { masteringInsertParamInfo: (name: string) => string }
+  ).masteringInsertParamInfo(name);
+  return JSON.parse(json) as MasteringInsertParamInfo[];
+}
+
+/**
+ * How a processor handles a buffer with more than two channels (a surround
+ * bed). "multichannel" processes every plane in one call; "stereoPairOnly"
+ * operates on the front L/R pair and passes any surround planes through dry.
+ * "perChannel"/"passthrough" are reserved and unused by the current catalog.
+ */
+export type MasteringChannelPolicy =
+  | 'multichannel'
+  | 'stereoPairOnly'
+  | 'perChannel'
+  | 'passthrough';
+
+/** One processor's realtime/offline/pair classification in the catalog. */
+export interface MasteringProcessorCatalogEntry {
+  /** Processor id (the name used for scene inserts / named processors). */
+  id: string;
+  /**
+   * Primary classification, by precedence pair > realtime > offline: "pair" for
+   * two-input match.* processors, "realtime" for ids that build as a realtime
+   * scene insert, "offline" for whole-file-only processors.
+   */
+  kind: 'realtime' | 'offline' | 'pair';
+  /** True exactly for ids that always succeed as a realtime scene insert. */
+  realtimeInsertable: boolean;
+  /** True for processors with no mono implementation (stereo-only). */
+  stereoOnly: boolean;
+  /**
+   * How the mixer wraps the processor on a >2-channel (surround) bus insert:
+   * "multichannel" (one full-buffer call) or "stereoPairOnly" (front L/R pair,
+   * surround planes passed through dry).
+   */
+  channelPolicy: MasteringChannelPolicy;
+}
+
+/**
+ * Returns the machine-readable classification catalog for every named processor
+ * id, merging the offline registry, the realtime insert factory, and the pair
+ * registry. Lets a host filter a processor picker by realtime insertability
+ * instead of offering ids the realtime strip would reject.
+ */
+export function masteringProcessorCatalog(): MasteringProcessorCatalogEntry[] {
+  const json = (
+    requireModule() as unknown as { masteringProcessorCatalog: () => string }
+  ).masteringProcessorCatalog();
+  return JSON.parse(json) as MasteringProcessorCatalogEntry[];
+}
+
 export function masteringPairProcessorNames(): PairProcessor[] {
   return requireModule().masteringPairProcessorNames() as PairProcessor[];
 }

package/src/feature_music.ts

@@ -257,11 +257,21 @@ export function analyzeMelody(
   const fmin = options.fmin ?? 65.0;
   const fmax = options.fmax ?? 2093.0;
   validateFrequencyBounds('analyzeMelody', fmin, fmax);
+  // The melody tracker's fmin is a YIN pitch floor: 0 is meaningless, and the
+  // flat C ABI (sonare_analyze_melody) rejects it. validateFrequencyBounds only
+  // guards fmin >= 0, so enforce strict positivity here for parity.
+  if (fmin <= 0) {
+    throw new RangeError('analyzeMelody: fmin must be positive');
+  }
   validatePositiveIntegers('analyzeMelody', {
     frameLength: options.frameLength ?? 2048,
     hopLength: options.hopLength ?? 256,
   });
-  assertFiniteScalar('analyzeMelody', options.threshold ?? 0.1, 'threshold');
+  const threshold = options.threshold ?? 0.1;
+  assertFiniteScalar('analyzeMelody', threshold, 'threshold');
+  if (threshold <= 0) {
+    throw new RangeError('analyzeMelody: threshold must be positive');
+  }
   return requireModule().analyzeMelody(
     samples,
     sampleRate,
@@ -371,7 +381,9 @@ export function tempogramRatio(
  * Measure loudness (EBU R128 / ITU-R BS.1770).
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param sampleRate - Sample rate in Hz. The default (22050) is non-standard for
+ *   audio; pass the buffer's actual rate, as K-weighting is sample-rate
+ *   dependent and a wrong rate yields wrong loudness.
  * @returns Loudness measurement result
  */
 export function lufs(
@@ -388,7 +400,8 @@ export function lufs(
  * Compute the momentary loudness (LUFS) over time.
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param sampleRate - Sample rate in Hz. The default (22050) is non-standard and
+ *   K-weighting is sample-rate dependent; pass the buffer's actual rate.
  * @returns Momentary LUFS values over time
  */
 export function momentaryLufs(
@@ -405,7 +418,8 @@ export function momentaryLufs(
  * Compute the short-term loudness (LUFS) over time.
  *
  * @param samples - Audio samples (mono, float32)
- * @param sampleRate - Sample rate in Hz (default: 22050)
+ * @param sampleRate - Sample rate in Hz. The default (22050) is non-standard and
+ *   K-weighting is sample-rate dependent; pass the buffer's actual rate.
  * @returns Short-term LUFS values over time
  */
 export function shortTermLufs(

package/src/feature_spectral.ts

@@ -218,6 +218,10 @@ export function hpssWithResidual(
  * Channel-weighted multichannel integrated loudness + LRA (ITU-R BS.1770 /
  * EBU R128) from an interleaved buffer of `frames * channels` samples. The
  * per-channel frame count is derived from the buffer length and `channels`.
+ *
+ * Pass the buffer's actual `sampleRate`: the default (22050) is non-standard for
+ * audio, and K-weighting is sample-rate dependent, so a wrong rate yields wrong
+ * loudness.
  */
 export function lufsInterleaved(
   samples: Float32Array,
@@ -231,7 +235,9 @@ export function lufsInterleaved(
 }
 
 /**
- * Standards-compliant EBU R128 loudness range (LRA) in LU.
+ * Standards-compliant EBU R128 loudness range (LRA) in LU. Pass the buffer's
+ * actual `sampleRate`: the default (22050) is non-standard and K-weighting is
+ * sample-rate dependent.
  */
 export function ebur128LoudnessRange(samples: Float32Array, sampleRate = 22050): number {
   return requireModule().ebur128LoudnessRange(samples, sampleRate);

package/src/index.ts

@@ -43,6 +43,9 @@ export type {
   DereverbClassicalOptions,
   DynamicsResult,
   GateOptions,
+  MasteringChannelPolicy,
+  MasteringInsertParamInfo,
+  MasteringProcessorCatalogEntry,
   TransientShaperOptions,
   TrimSilenceMode,
   TrimSilenceOptions,
@@ -67,6 +70,7 @@ export {
   masteringDynamicsGate,
   masteringDynamicsTransientShaper,
   masteringInsertNames,
+  masteringInsertParamInfo,
   masteringInsertParamNames,
   masteringPairAnalysisNames,
   masteringPairAnalyze,
@@ -74,6 +78,7 @@ export {
   masteringPairProcessorNames,
   masteringPresetNames,
   masteringProcess,
+  masteringProcessorCatalog,
   masteringProcessorNames,
   masteringProcessStereo,
   masteringRepairDeclick,
@@ -95,6 +100,7 @@ export {
   pitchCorrectToMidi,
   pitchCorrectToMidiTimevarying,
   pitchShift,
+  spectralEdit,
   timeStretch,
   voiceChange,
   voiceChangeRealtime,
@@ -245,6 +251,7 @@ export type {
   ProjectLoopMode,
   ProjectLoopRecordingDesc,
   ProjectLoopRecordingResult,
+  ProjectMarker,
   ProjectMidiClipResult,
   ProjectMidiEvent,
   ProjectNotePairValidation,
@@ -268,6 +275,7 @@ export type {
 } from './project';
 export {
   EXPECTED_PROJECT_ABI_VERSION,
+  MarkerKind,
   Project,
   projectAbiVersion,
   SYNTH_BODY_TYPES,
@@ -348,6 +356,10 @@ export type {
   Section,
   SendTiming,
   SoloProcessor,
+  SpectralEditMode,
+  SpectralEditOptions,
+  SpectralEditWindow,
+  SpectralRegionOp,
   StereoAnalysis,
   StftPowerResult,
   StftResult,
@@ -401,6 +413,7 @@ export type {
   EngineAutomationPoint,
   EngineBounceOptions,
   EngineBounceResult,
+  EngineBus,
   EngineCapabilities,
   EngineCaptureStatus,
   EngineClip,
@@ -409,9 +422,17 @@ export type {
   EngineGraphSpec,
   EngineMarker,
   EngineMeterTelemetry,
+  EngineMeterTelemetryWide,
   EngineMetronomeConfig,
+  EngineMidiClipSchedule,
+  EngineMidiEvent,
   EngineParameterInfo,
+  EngineScopeTelemetry,
   EngineTelemetry,
+  EngineTempoSegment,
+  EngineTimeSignatureSegment,
+  EngineTrackLane,
+  EngineTrackSend,
   EngineTransportState,
   MidiCcBindOptions,
 } from './realtime_engine';
@@ -484,6 +505,11 @@ let initPromise: Promise<void> | null = null;
  */
 export async function init(options?: {
   locateFile?: (path: string, prefix: string) => string;
+  wasmBinary?: ArrayBuffer | Uint8Array;
+  moduleFactory?: (options?: {
+    locateFile?: (path: string, prefix: string) => string;
+    wasmBinary?: ArrayBuffer | Uint8Array;
+  }) => Promise<SonareModule>;
 }): Promise<void> {
   if (module) {
     return;
@@ -495,7 +521,7 @@ export async function init(options?: {
 
   initPromise = (async () => {
     try {
-      const createModule = (await import('./sonare.js')).default;
+      const createModule = options?.moduleFactory ?? (await import('./sonare.js')).default;
       module = await createModule(options);
       setSonareModule(module);
     } catch (error) {

package/src/mixer.ts

@@ -15,6 +15,7 @@ import type {
   PanLaw,
   PanMode,
   SendTiming,
+  SurroundPan,
 } from './public_types';
 
 export interface MixerRealtimeBuffer {
@@ -348,6 +349,14 @@ export class Mixer {
     this.mixer.setDualPan(stripIndex, leftPan, rightPan);
   }
 
+  /**
+   * Set the strip's surround pan position, used when it feeds a >2-channel bus.
+   * Stored on the scene; inert until the surround DSP path applies it.
+   */
+  setSurroundPan(stripIndex: number, pan: SurroundPan): void {
+    this.mixer.setSurroundPan(stripIndex, pan);
+  }
+
   /**
    * Add a send to a strip after construction.
    *

package/src/module_state.ts

@@ -70,6 +70,7 @@ function makeSonareError(raw: SonareModule, thrown: number): SonareError {
  */
 function wrapModuleErrors(raw: SonareModule): SonareModule {
   const cache = new Map<PropertyKey, unknown>();
+  const objectCache = new WeakMap<object, unknown>();
   const convert = (error: unknown): never => {
     const ptr = nativeExceptionPtr(error);
     if (ptr !== null) {
@@ -77,6 +78,86 @@ function wrapModuleErrors(raw: SonareModule): SonareModule {
     }
     throw error;
   };
+
+  const wrapNativeObject = (value: unknown): unknown => {
+    if (value === null || typeof value !== 'object') {
+      return value;
+    }
+    if (ArrayBuffer.isView(value) || value instanceof ArrayBuffer || value instanceof Promise) {
+      return value;
+    }
+    const objectValue = value as object;
+    const cached = objectCache.get(objectValue);
+    if (cached) {
+      return cached;
+    }
+    const methodCache = new Map<PropertyKey, unknown>();
+    const wrapped = new Proxy(objectValue, {
+      get(target, prop, receiver) {
+        const member = Reflect.get(target, prop, receiver);
+        if (typeof member !== 'function') {
+          return member;
+        }
+        const cachedMethod = methodCache.get(prop);
+        if (cachedMethod) {
+          return cachedMethod;
+        }
+        const method = member as (...a: unknown[]) => unknown;
+        const wrappedMethod = (...args: unknown[]) => {
+          try {
+            return wrapNativeObject(Reflect.apply(method, target, args));
+          } catch (error) {
+            return convert(error);
+          }
+        };
+        methodCache.set(prop, wrappedMethod);
+        return wrappedMethod;
+      },
+    });
+    objectCache.set(objectValue, wrapped);
+    return wrapped;
+  };
+
+  const wrapFunction = (value: (...a: unknown[]) => unknown): unknown => {
+    const fnCache = new Map<PropertyKey, unknown>();
+    return new Proxy(value, {
+      get(target, prop, receiver) {
+        const member = Reflect.get(target, prop, receiver);
+        if (typeof member !== 'function') {
+          return member;
+        }
+        const cachedMember = fnCache.get(prop);
+        if (cachedMember) {
+          return cachedMember;
+        }
+        const fn = member as (...a: unknown[]) => unknown;
+        const wrappedMember = (...args: unknown[]) => {
+          try {
+            return wrapNativeObject(Reflect.apply(fn, target, args));
+          } catch (error) {
+            return convert(error);
+          }
+        };
+        fnCache.set(prop, wrappedMember);
+        return wrappedMember;
+      },
+      apply(t, thisArg, args) {
+        try {
+          return wrapNativeObject(Reflect.apply(t, thisArg, args as unknown[]));
+        } catch (error) {
+          return convert(error);
+        }
+      },
+      construct(t, args, newTarget) {
+        try {
+          return wrapNativeObject(Reflect.construct(t, args as unknown[], newTarget));
+        } catch (error) {
+          return convert(error) as object;
+        }
+      },
+    });
+  };
+
   return new Proxy(raw, {
     get(target, prop, receiver) {
       const value = Reflect.get(target, prop, receiver);
@@ -90,23 +171,7 @@ function wrapModuleErrors(raw: SonareModule): SonareModule {
       // Wrap as a Proxy (not a plain function) so embind class constructors
       // invoked via `new module.Foo(...)` keep their `[[Construct]]` behaviour
       // and prototype while still converting thrown native pointers.
-      const fn = value as (...a: unknown[]) => unknown;
-      const wrapped = new Proxy(fn, {
-        apply(t, thisArg, args) {
-          try {
-            return Reflect.apply(t, thisArg, args as unknown[]);
-          } catch (error) {
-            return convert(error);
-          }
-        },
-        construct(t, args, newTarget) {
-          try {
-            return Reflect.construct(t, args as unknown[], newTarget) as object;
-          } catch (error) {
-            return convert(error) as object;
-          }
-        },
-      });
+      const wrapped = wrapFunction(value as (...a: unknown[]) => unknown);
       cache.set(prop, wrapped);
       return wrapped;
     },

package/src/opfs_clip_pages.ts

@@ -29,10 +29,25 @@ interface PageResponse {
 }
 
 export const opfsClipPageWorkerSource = `
+const sonareClipPageReadQueues = new Map();
+
+function sonareEnqueueClipPageRead(key, task) {
+  const previous = sonareClipPageReadQueues.get(key) || Promise.resolve();
+  const next = previous.catch(() => undefined).then(task);
+  const queued = next.finally(() => {
+    if (sonareClipPageReadQueues.get(key) === queued) {
+      sonareClipPageReadQueues.delete(key);
+    }
+  });
+  sonareClipPageReadQueues.set(key, queued);
+  return next;
+}
+
 self.onmessage = async (event) => {
   const message = event.data;
   if (!message || message.type !== 'sonare:read-clip-page') return;
   const { requestId, path, pageIndex, numChannels, numSamples, pageFrames, dataOffsetBytes = 0 } = message;
+  await sonareEnqueueClipPageRead(String(path), async () => {
   try {
     if (pageIndex < 0) {
       self.postMessage({ type: 'sonare:clip-page', requestId, pageIndex, ok: false });
@@ -95,6 +110,7 @@ self.onmessage = async (event) => {
       error: error instanceof Error ? error.message : String(error),
     });
   }
+  });
 };
 `;
 
@@ -119,6 +135,7 @@ export function createOpfsClipPageProvider(
   const ownsWorker = options.worker === undefined || options.terminateWorkerOnClose === true;
   let nextRequestId = 1;
   let closed = false;
+  let readQueue: Promise<void> = Promise.resolve();
   const pending = new Map<
     number,
     { resolve: (value: boolean) => void; reject: (reason: unknown) => void }
@@ -165,15 +182,32 @@ export function createOpfsClipPageProvider(
     const promise = new Promise<boolean>((resolve, reject) => {
       pending.set(requestId, { resolve, reject });
     });
-    worker.postMessage({
-      type: 'sonare:read-clip-page',
-      requestId,
-      path: options.path,
-      pageIndex,
-      numChannels: options.numChannels,
-      numSamples: options.numSamples,
-      pageFrames: options.pageFrames,
-      dataOffsetBytes: options.dataOffsetBytes ?? 0,
+    readQueue = readQueue
+      .catch(() => undefined)
+      .then(() => {
+        if (closed) {
+          const entry = pending.get(requestId);
+          pending.delete(requestId);
+          entry?.reject(new Error('OpfsClipPageProvider is closed'));
+          return;
+        }
+        worker.postMessage({
+          type: 'sonare:read-clip-page',
+          requestId,
+          path: options.path,
+          pageIndex,
+          numChannels: options.numChannels,
+          numSamples: options.numSamples,
+          pageFrames: options.pageFrames,
+          dataOffsetBytes: options.dataOffsetBytes ?? 0,
+        });
+        return promise.then(
+          () => undefined,
+          () => undefined,
+        );
+      });
+    readQueue.catch(() => {
+      // The per-request promise carries the user-visible failure.
     });
     return promise;
   };

package/src/project.ts

@@ -25,6 +25,34 @@ export interface ProjectBounceOptions {
   instrumentLatencySamples?: number;
 }
 
+/**
+ * Marker kind ordinals. Mirrors `SonareMarkerKind` in `src/sonare_c_types.h`;
+ * the values are part of the ABI and must not be renumbered.
+ */
+export const MarkerKind = {
+  marker: 0,
+  text: 1,
+  lyric: 2,
+  cuePoint: 3,
+  keySignature: 4,
+} as const;
+
+/** A project timeline marker with its kind and (for key signatures) the key. */
+export interface ProjectMarker {
+  /** Stable marker id (0 when allocating a new id via {@link Project.setMarkerEx}). */
+  id: number;
+  /** Marker position in PPQ (quarter notes). */
+  ppq: number;
+  /** Marker label. */
+  name?: string;
+  /** {@link MarkerKind} ordinal (default 0 = marker). */
+  kind?: number;
+  /** Key signature only: -7..7 (sharps positive). */
+  keyFifths?: number;
+  /** Key signature only: false = major, true = minor. */
+  keyMinor?: boolean;
+}
+
 /** Oscillator waveform for the built-in synth. */
 export type BuiltinSynthWaveform =
   | 'sine'
@@ -544,6 +572,10 @@ interface WasmProject {
   setWarpMap: (map: ProjectWarpMapDesc) => void;
   removeWarpMap: (warpRefId: number) => void;
   setTrackMidiDestination: (trackId: number, destinationId: number) => void;
+  setTrackGain: (trackId: number, gain: number) => void;
+  setTrackMute: (trackId: number, mute: boolean) => void;
+  setTrackSolo: (trackId: number, solo: boolean) => void;
+  setTrackPan: (trackId: number, pan: number) => void;
   undo: () => void;
   redo: () => void;
   setMidiEvents: (
@@ -627,6 +659,9 @@ interface WasmProject {
   getSampleRate: () => number;
   setMixerSceneJson: (sceneJson: string) => void;
   setMarker: (markerId: number, ppq: number, name: string) => number;
+  setMarkerEx: (marker: ProjectMarker) => number;
+  markerByIndex: (index: number) => ProjectMarker;
+  markerCount: () => number;
   trackCount: () => number;
   sourceCount: () => number;
   tempoSegmentCount: () => number;
@@ -1166,6 +1201,26 @@ export class Project {
     this.native.setTrackMidiDestination(trackId, destinationId);
   }
 
+  /** Set a track's linear playback gain (1.0 = unity; >= 0) via an undoable edit. */
+  setTrackGain(trackId: number, gain: number): void {
+    this.native.setTrackGain(trackId, gain);
+  }
+
+  /** Set a track's mute flag via an undoable edit (a muted track is silent). */
+  setTrackMute(trackId: number, mute: boolean): void {
+    this.native.setTrackMute(trackId, mute);
+  }
+
+  /** Set a track's solo flag via an undoable edit (when any track is soloed, only soloed tracks sound). */
+  setTrackSolo(trackId: number, solo: boolean): void {
+    this.native.setTrackSolo(trackId, solo);
+  }
+
+  /** Set a track's stereo balance in [-1, +1] (0 = center) via an undoable edit. */
+  setTrackPan(trackId: number, pan: number): void {
+    this.native.setTrackPan(trackId, pan);
+  }
+
   /** Undo the most recent edit. */
   undo(): void {
     this.native.undo();
@@ -1527,6 +1582,25 @@ export class Project {
     return this.native.setMarker(markerId, ppq, name);
   }
 
+  /**
+   * Add or replace a marker from a full {@link ProjectMarker}, including its
+   * {@link MarkerKind} and (for key signatures) the key. Pass `id` 0 to allocate
+   * a new id; returns the stable marker id.
+   */
+  setMarkerEx(marker: ProjectMarker): number {
+    return this.native.setMarkerEx(marker);
+  }
+
+  /** Read a project marker by index (0-based, in stored order). */
+  markerByIndex(index: number): ProjectMarker {
+    return this.native.markerByIndex(index);
+  }
+
+  /** Number of markers in the project. */
+  markerCount(): number {
+    return this.native.markerCount();
+  }
+
   /** Number of tracks in the project. */
   trackCount(): number {
     return this.native.trackCount();