@libraz/libsonare 1.8.1 → 1.8.2

package/src/public_types_vocal_edit.ts

@@ -0,0 +1,289 @@
+/** Public value types for the monophonic vocal edit surface. */
+
+/** A uint64 value crossing the JavaScript boundary is decimal text. */
+export type VocalUint64 = string;
+
+export interface VocalRange {
+  startSample: number;
+  endSample: number;
+}
+
+export interface VocalStateToken {
+  sessionEpoch: VocalUint64;
+  revision: VocalUint64;
+  draftId: VocalUint64;
+  generation: VocalUint64;
+  requestId: VocalUint64;
+  profileId: number;
+}
+
+export interface VocalPitchPoint {
+  sourceSample: number;
+  midi: number;
+}
+
+export type VocalPitchTarget =
+  | { mode: 'none' }
+  | { mode: 'center'; midi: number }
+  | { mode: 'curve'; points: readonly VocalPitchPoint[] };
+
+export interface VocalPitchEdit {
+  target: VocalPitchTarget;
+  amount: number;
+  speedMs: number;
+  maxCorrectionSemitones: number;
+  transposeSemitones: number;
+  driftScale: number;
+  vibratoScale: number;
+}
+
+export type VocalFormantMode = 'preserve' | 'shift';
+
+export interface VocalFormantEdit {
+  mode: VocalFormantMode;
+  shiftSemitones: number;
+}
+
+export interface VocalNoteEdit {
+  pitch: VocalPitchEdit;
+  destinationStartSample: number;
+  destinationLengthSamples: number;
+  gainDb: number;
+  muted: boolean;
+  amplitudeEnvelope: readonly number[];
+  formant: VocalFormantEdit;
+}
+
+export interface VocalNote {
+  id: number;
+  sourceStartSample: number;
+  sourceEndSample: number;
+  analysisFrameStart: VocalUint64;
+  analysisFrameEnd: VocalUint64;
+  hasPitch: boolean;
+  medianHz: number;
+  centerMidi: number;
+  f0Stability: number;
+  amplitude: Float32Array;
+  edit: VocalNoteEdit;
+}
+
+export interface VocalTransition {
+  leftNoteId: number;
+  rightNoteId: number;
+  leftWindowSamples: number;
+  rightWindowSamples: number;
+  strength: number;
+  curve: 'smoothstep';
+}
+
+export interface VocalNotesResult {
+  notes: VocalNote[];
+  transitions: VocalTransition[];
+}
+
+export interface VocalAnalysis {
+  frameOriginSample: number;
+  samplesPerFrame: number;
+  frameLengthSamples: number;
+  f0Hz: Float32Array;
+  voiced: Uint8Array;
+  algorithmId: string;
+  algorithmVersion: number;
+  sourceLengthSamples: number;
+  sampleRate: number;
+  sourceSha256: string;
+  analysisSha256: string;
+  fminHz: number;
+  fmaxHz: number;
+  yinThreshold: number;
+  voicedThreshold: number;
+  centered: boolean;
+  segmentationThresholdCents: number;
+  minNoteMs: number;
+  referenceHz: number;
+}
+
+export interface VocalCapabilities {
+  apiVersion: number;
+  profileId: number;
+  monophonicOnly: true;
+  analysisCancellable: boolean;
+  minimumFormantShiftSemitones: number;
+  maximumFormantShiftSemitones: number;
+}
+
+export interface VocalHistory {
+  canUndo: boolean;
+  canRedo: boolean;
+}
+
+export type VocalHistoryState = VocalHistory;
+
+export interface VocalSessionLimits {
+  maxHistoryBytes?: VocalUint64;
+  maxCacheBytes?: VocalUint64;
+  maxUndoDepth?: number;
+  maxRenderJobs?: number;
+}
+
+export interface VocalAnalysisInput {
+  frameOriginSample: number;
+  samplesPerFrame: number;
+  frameLengthSamples: number;
+  f0Hz: Float32Array;
+  voiced: Uint8Array;
+  algorithmId?: string;
+  algorithmVersion?: number;
+  fminHz?: number;
+  fmaxHz?: number;
+  yinThreshold?: number;
+  voicedThreshold?: number;
+  centered?: boolean;
+  segmentationThresholdCents?: number;
+  minNoteMs?: number;
+  referenceHz?: number;
+}
+
+export interface VocalCreateOptions {
+  outputLengthSamples?: number;
+  edgeFadeMs?: number;
+  vibratoCutoffHz?: number;
+  segmentationThresholdCents?: number;
+  minNoteMs?: number;
+  frameLengthSamples?: number;
+  hopLengthSamples?: number;
+  fminHz?: number;
+  fmaxHz?: number;
+  yinThreshold?: number;
+  voicedThreshold?: number;
+  centered?: boolean;
+  referenceHz?: number;
+  limits?: VocalSessionLimits;
+  analysis?: VocalAnalysisInput;
+}
+
+export interface VocalCreateRequest extends VocalCreateOptions {
+  samples: Float32Array;
+  sampleRate: number;
+}
+
+export interface VocalRestoreRequest {
+  samples: Float32Array;
+  sampleRate: number;
+  state: Uint8Array;
+  /** Runtime limits; omitted fields take the same defaults as session creation. */
+  limits?: VocalSessionLimits;
+}
+
+export interface VocalSetEditOperation {
+  kind: 'setEdit';
+  noteId: number;
+  edit: VocalNoteEdit;
+}
+
+export interface VocalSetSourceSpanOperation {
+  kind: 'setSourceSpan';
+  noteId: number;
+  sourceStartSample: number;
+  sourceEndSample: number;
+  destinationStartSample: number;
+  destinationLengthSamples: number;
+}
+
+export interface VocalSplitOperation {
+  kind: 'split';
+  noteId: number;
+  sourceSample: number;
+}
+
+export interface VocalMergeOperation {
+  kind: 'merge';
+  noteIds: readonly number[];
+  policy?: 'preserve' | 'reset';
+}
+
+export interface VocalSetTransitionOperation {
+  kind: 'setTransition';
+  transition: VocalTransition;
+}
+
+export interface VocalRemoveTransitionOperation {
+  kind: 'removeTransition';
+  leftNoteId: number;
+  rightNoteId: number;
+}
+
+export interface VocalResetOperation {
+  kind: 'reset';
+  noteIds: readonly number[];
+}
+
+export type VocalEditOperation =
+  | VocalSetEditOperation
+  | VocalSetSourceSpanOperation
+  | VocalSplitOperation
+  | VocalMergeOperation
+  | VocalSetTransitionOperation
+  | VocalRemoveTransitionOperation
+  | VocalResetOperation;
+
+export interface VocalApplyRequest {
+  expectedGeneration: VocalUint64;
+  operations: readonly VocalEditOperation[];
+}
+
+export interface VocalIdChange {
+  operationIndex: number;
+  retiredId: number;
+  newIds: readonly number[];
+}
+
+export interface VocalEditResult {
+  token: VocalStateToken;
+  dirtyRanges: readonly VocalRange[];
+  idChanges: readonly VocalIdChange[];
+}
+
+export interface VocalPitchEvaluation {
+  sourceSamples: Float64Array;
+  measuredMidi: Float64Array;
+  targetMidi: Float64Array;
+  effectiveMidi: Float64Array;
+  voiced: Uint8Array;
+  hasTarget: Uint8Array;
+}
+
+export interface VocalRenderRequest {
+  /** Omit to render the complete destination output. */
+  range?: VocalRange;
+  requestId?: VocalUint64;
+  signal?: AbortSignal;
+}
+
+export interface VocalRenderResult {
+  samples: Float32Array;
+  startSample: number;
+  token: VocalStateToken;
+  processedRanges: readonly VocalRange[];
+  cacheHitUnits: VocalUint64;
+  dryPassedFrames: VocalUint64;
+  limitedCorrectionFrames: VocalUint64;
+}
+
+export interface VocalStateBytes {
+  data: Uint8Array;
+}
+
+export interface VocalJobProgress {
+  complete: boolean;
+}
+
+export interface VocalErrorShape {
+  readonly reason: number;
+  readonly field: string;
+  readonly expected: VocalUint64;
+  readonly actual: VocalUint64;
+  readonly expectedText: string;
+  readonly actualText: string;
+}

package/src/public_types_vocal_project.ts

@@ -0,0 +1,69 @@
+import type { VocalStateToken, VocalUint64 } from './public_types_vocal_edit';
+
+/** A full source render and persisted vocal session ready for Project apply. */
+export interface ProjectVocalEditApplyRequest {
+  clipId: number;
+  /** Zero selects the clip's base source; a non-zero id selects a take. */
+  takeId?: number;
+  expectedSourceId: number;
+  expectedSourceSampleRate: number;
+  expectedSourceSampleCount: number;
+  /** Canonical source digest as exactly 64 hexadecimal characters. */
+  expectedSourceSha256: string;
+  expectedClipLengthPpq: number;
+  expectedSourceOffsetPpq: number;
+  /** Full-source mono render. The v1 Project adapter requires startSample 0. */
+  renderedMono: Float32Array;
+  renderedSampleRate: number;
+  renderedStartSample?: number;
+  renderToken: VocalStateToken;
+  /** SVE1 state exported from the committed vocal edit session. */
+  sve1: Uint8Array;
+}
+
+export interface ProjectVocalEditApplyResult {
+  clipId: number;
+  takeId: number;
+  originalSourceId: number;
+  derivedSourceId: number;
+  committedRevision: VocalUint64;
+  profileId: number;
+  derivedSourceSha256: string;
+  sidecarKey: string;
+}
+
+export type ProjectVocalReason = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7;
+
+export interface ProjectVocalEditDependency {
+  clipId: number;
+  takeId: number;
+  originalSourceId: number;
+  derivedSourceId: number;
+  sourceSampleRate: number;
+  profileId: number;
+  sourceSampleCount: number;
+  committedRevision: VocalUint64;
+  originalSourceSha256: string;
+  derivedSourceSha256: string;
+  originalPcmAvailable: boolean;
+  derivedPcmAvailable: boolean;
+  reason: ProjectVocalReason | number;
+  sidecarKey: string;
+}
+
+export interface ProjectVocalOriginalSource {
+  sourceId: number;
+  mono: Float32Array;
+  sampleRate: number;
+}
+
+/** Native status values from SonareProjectVocalRehydrateStatus. */
+export type ProjectVocalRehydrateStatus = 0 | 1 | 2;
+
+export interface ProjectVocalRehydrateItem {
+  clipId: number;
+  takeId: number;
+  derivedSourceId: number;
+  status: ProjectVocalRehydrateStatus;
+  reason: ProjectVocalReason | number;
+}

package/src/realtime_engine.ts

@@ -12,16 +12,24 @@ import type {
   ControllerBinding,
   MpeDimension,
   NoteTracking,
+  PartRigInsert,
+  PartRigMode,
   ProjectMidiCcBinding,
   SynthPatch,
 } from './project';
-import { normalizeSynthInstrument } from './project_internal';
+import type { ProjectTimeline } from './project_class';
+import {
+  normalizeSynthInstrument,
+  partRigInsertsJson,
+  projectTimelineNativeId,
+} from './project_internal';
 import type {
   EqBand,
   PanLawInput,
   PanMode,
   SendTiming,
   SidechainSourceKind,
+  SurroundPan,
   UmpWords,
 } from './public_types';
 import type {
@@ -576,6 +584,23 @@ export class RealtimeEngine {
     this.native.setArticulation(destinationId, channel, articulation);
   }
 
+  /**
+   * Set the rig of one part (0-15), or of the destination's default when `part`
+   * is `PART_RIG_ALL_PARTS`, on the instrument bound to `destinationId`. A
+   * direct call, not a stored edit: a destination with no instrument is an
+   * invalid parameter, and an instrument without part rigs (a builtin, a
+   * host-callback instrument) is refused as not implemented rather than
+   * succeeding quietly. `'chain'` takes 1-8 `inserts`; no other mode does.
+   */
+  setPartRig(
+    destinationId: number,
+    part: number,
+    mode: PartRigMode | number,
+    inserts?: PartRigInsert[],
+  ): void {
+    this.native.setPartRig(destinationId, part, mode, partRigInsertsJson(inserts));
+  }
+
   /**
    * Read back {@link setArticulation} as the canonical name. An ordinal this
    * build cannot spell is handed back as the number, the way every other enum
@@ -1142,11 +1167,44 @@ export class RealtimeEngine {
   /**
    * Keys one insert of a lane strip from another lane's post-strip audio
    * (ducking/sidechainRouter inserts). sourceTrackId 0 removes the binding.
+   * Lanes are processed in key order and the key is delay-compensated to the
+   * destination strip input, so the result depends on neither the lane order
+   * nor the block size. Throws, leaving the bindings unchanged, for a lane
+   * keying itself, a binding that would close a cycle over the lane bindings,
+   * a full binding table and an alignment past the delay ceiling. Not callable
+   * while a block is being processed.
    */
   setLaneSidechain(trackId: number, insertIndex: number, sourceTrackId: number): void {
     this.native.setLaneSidechain(trackId, insertIndex, sourceTrackId);
   }
 
+  /**
+   * Installs a compiled project timeline into this stopped engine, all or
+   * nothing: tempo and time-signature segments, markers, track lanes, track
+   * automation, audio and MIDI clips, and the per-track strips of the project's
+   * mixer scene are replaced in full (a later low-level setter on those domains
+   * is overwritten by the next apply). Instruments, buses, the master strip,
+   * metronome, loop and capture are not touched; bind instruments separately.
+   *
+   * Throws while the transport is playing, for a timeline the engine cannot
+   * hold, and for a scene strip routed from several tracks. A validation
+   * failure leaves the engine unchanged. The engine keeps its own reference, so
+   * {@link ProjectTimeline.dispose} may follow immediately.
+   *
+   * Also throws on an unprepared engine and on a timeline whose sample rate
+   * differs from the engine's. Once a timeline is applied, a later prepare at
+   * another rate is refused until the timeline's clips are cleared.
+   */
+  applyProjectTimeline(timeline: ProjectTimeline): void {
+    // Resolve through the identity registry so no raw native handle crosses the
+    // facade boundary and the realtime bundle needs no value class import.
+    const timelineId = projectTimelineNativeId(timeline);
+    if (timelineId === undefined) {
+      throw new TypeError('timeline must be a ProjectTimeline instance');
+    }
+    this.native.applyProjectTimeline(timelineId);
+  }
+
   setTrackBuses(buses: EngineBus[]): void {
     // Array.isArray guards a caller-fabricated array-like (e.g. `{ length }`)
     // meant to probe the native array-length read: passing it through
@@ -1441,12 +1499,9 @@ export class RealtimeEngine {
    * return `-1`: they resize voice pools or swap DSP topology, which is not
    * audio-thread safe. Rebind the instrument with a new patch instead.
    *
-   * `gain`, `busDrive`, `cutoffHz`, `resonanceQ`, `envToCutoffCents`,
-   * `lfoToPitchCents` and `pitchOffsetCents` reach voices that are already
-   * sounding from the next block; the rest are cached into per-voice state at
-   * note-on and take effect from the next note, so a lane that moves one of
-   * them under a held note looks inert until the next one speaks — that is the
-   * behaviour, not a dropped write.
+   * All automatable parameters of a NativeSynth reach already-sounding voices
+   * from the next processed block. Voices using GM program patches are
+   * unaffected; parameters apply to NativeSynth's own patch only.
    *
    * The id survives an unbind/rebind of the same destination and applies
    * nothing while that destination is unbound.
@@ -1475,6 +1530,17 @@ export class RealtimeEngine {
     this.native.setTrackStripDualPan(trackId, leftPan, rightPan);
   }
 
+  /**
+   * Sets a track lane strip's surround placement in realtime (glitch-free; a
+   * constant-power 5 ms one-pole glide). Used when the destination has more than
+   * two channels. Omitted fields default to a centered point source
+   * (`distance` 1); a `distance` of 0 or less is treated as 1. Throws for an
+   * unknown track, a track without a lane strip, or a non-finite field.
+   */
+  setTrackStripSurroundPan(trackId: number, pan: SurroundPan): void {
+    this.native.setTrackStripSurroundPan(trackId, pan);
+  }
+
   /**
    * Sets a bus strip's output pan position in realtime (glitch-free). Throws
    * for an unknown bus or one wider than stereo.
@@ -1499,8 +1565,9 @@ export class RealtimeEngine {
   }
 
   /**
-   * Sets a track lane strip's inter-channel alignment delay (whole samples).
-   * Adjusts strip latency, so PDC and reported graph latency are refreshed.
+   * Sets a track lane strip's alignment delay (whole samples), moving this lane
+   * later relative to every other lane. It is not latency: PDC does not
+   * compensate it and the reported graph latency is unchanged.
    */
   setTrackStripChannelDelaySamples(trackId: number, delaySamples: number): void {
     this.native.setTrackStripChannelDelaySamples(trackId, delaySamples);
@@ -1833,6 +1900,16 @@ export class RealtimeEngine {
     return this.native.drainMeterTelemetryWide(maxRecords);
   }
 
+  /**
+   * Per-insert gain reduction in dB (each <= 0) of a meter target's strip from the
+   * last rendered block, in combined pre-to-post insert order. `targetId` uses the
+   * meter-record encoding (0 master, 1..32 lanes, 33..40 buses; 0xFFFF monitor
+   * yields an empty array). Throws for an id outside that range.
+   */
+  meterTargetInsertGainReduction(targetId: number): number[] {
+    return this.native.meterTargetInsertGainReduction(targetId);
+  }
+
   /**
    * Enables per-target spectrum + vectorscope capture. @param intervalFrames is
    * the minimum render-frame gap between snapshots (0 disables). @param bandCount

package/src/repair_dereverb.ts

@@ -19,6 +19,7 @@ export interface DereverbClassicalOptions {
   threshold?: number;
   attenuation?: number;
   nFft?: number;
+  /** Hop in samples, in (0, nFft / 2]. */
   hopLength?: number;
   t60Sec?: number;
   lateDelayMs?: number;

package/src/repair_noise.ts

@@ -26,6 +26,7 @@ export interface DenoiseClassicalOptions {
   mode?: DenoiseClassicalMode;
   noiseEstimator?: DenoiseClassicalNoiseEstimator;
   nFft?: number;
+  /** Hop in samples, in (0, nFft / 2]. */
   hopLength?: number;
   ddAlpha?: number;
   reductionDb?: number;

package/src/sonare.js.d.ts

@@ -25,6 +25,7 @@ import type {
   SpectralRegionOp,
   SurroundPan,
 } from './public_types';
+import type { VocalWasmExports } from './vocal_edit';
 
 export interface SonareModuleOptions {
   locateFile?: (path: string, prefix: string) => string;
@@ -1288,7 +1289,17 @@ export interface WasmEngineBounceOptions {
   totalFrames: number;
   blockSize?: number;
   numChannels?: number;
+  /**
+   * Output sample rate. Omitting it (or `0`) keeps the source rate, so nothing
+   * is resampled; a different rate resamples. The result's `sampleRate`
+   * reports the rate of the returned audio.
+   */
   targetSampleRate?: number;
+  /**
+   * Rate `totalFrames` is counted in. Omitting it (or `0`) means the engine's
+   * prepared rate; a different value throws an `InvalidParameter` `SonareError`,
+   * because the render always runs at the prepared rate.
+   */
   sourceSampleRate?: number;
   normalizeLufs?: boolean;
   /**
@@ -1413,6 +1424,7 @@ export interface WasmRealtimeEngine {
   clipCount: () => number;
   setTrackLanes: (lanes: Array<number | WasmEngineTrackLane>) => void;
   setLaneSidechain: (trackId: number, insertIndex: number, sourceTrackId: number) => void;
+  applyProjectTimeline: (timelineId: number) => void;
   setTrackBuses: (buses: WasmEngineBus[]) => void;
   setBusSidechain: (
     busId: number,
@@ -1506,6 +1518,7 @@ export interface WasmRealtimeEngine {
   setTrackStripPanLaw: (trackId: number, panLaw: number) => void;
   setTrackStripPanMode: (trackId: number, panMode: number) => void;
   setTrackStripDualPan: (trackId: number, leftPan: number, rightPan: number) => void;
+  setTrackStripSurroundPan: (trackId: number, pan: SurroundPan) => void;
   setBusStripPan: (busId: number, pan: number) => void;
   setBusStripPanLaw: (busId: number, panLaw: number) => void;
   setBusStripPanMode: (busId: number, panMode: number) => void;
@@ -1579,6 +1592,12 @@ export interface WasmRealtimeEngine {
     channel: number,
   ) => import('./instrument_types').Articulation | number;
   legatoFallbackCount: (destinationId: number) => number;
+  setPartRig: (
+    destinationId: number,
+    part: number,
+    mode: import('./instrument_types').PartRigMode | number,
+    insertsJson: string | undefined,
+  ) => void;
   setMidiFx: (destinationId: number, configJson: string) => void;
   clearMidiFx: (destinationId: number) => void;
   setMidiInputSource: (destinationId: number) => void;
@@ -1726,6 +1745,7 @@ export interface WasmRealtimeEngine {
   meterScratchInputPeakDbR: () => number;
   drainMeterTelemetry: (maxRecords: number) => WasmEngineMeterTelemetry[];
   drainMeterTelemetryWide: (maxRecords: number) => WasmEngineMeterTelemetryWide[];
+  meterTargetInsertGainReduction: (targetId: number) => number[];
   configureScopeTelemetry: (intervalFrames: number, bandCount: number) => number;
   drainScopeTelemetry: (maxRecords: number) => WasmEngineScopeTelemetry[];
   popScopeTelemetryToScratch: () => boolean;
@@ -1759,6 +1779,39 @@ export interface WasmSynthEnumTables {
 }
 
 export interface SonareModule {
+  vocalEditApiVersion: VocalWasmExports['vocalEditApiVersion'];
+  vocalEditAvailable: VocalWasmExports['vocalEditAvailable'];
+  vocalEditSessionCreate: VocalWasmExports['vocalEditSessionCreate'];
+  vocalEditSessionRestore: VocalWasmExports['vocalEditSessionRestore'];
+  vocalEditSessionDestroy: VocalWasmExports['vocalEditSessionDestroy'];
+  vocalEditSessionNotes: VocalWasmExports['vocalEditSessionNotes'];
+  vocalEditDraftNotes: VocalWasmExports['vocalEditDraftNotes'];
+  vocalEditSessionToken: VocalWasmExports['vocalEditSessionToken'];
+  vocalEditDraftToken: VocalWasmExports['vocalEditDraftToken'];
+  vocalEditSessionAnalysis: VocalWasmExports['vocalEditSessionAnalysis'];
+  vocalEditSessionCapabilities: VocalWasmExports['vocalEditSessionCapabilities'];
+  vocalEditSessionOutputLength: VocalWasmExports['vocalEditSessionOutputLength'];
+  vocalEditSessionHistory: VocalWasmExports['vocalEditSessionHistory'];
+  vocalEditSessionBeginEdit: VocalWasmExports['vocalEditSessionBeginEdit'];
+  vocalEditDraftApply: VocalWasmExports['vocalEditDraftApply'];
+  vocalEditDraftCommit: VocalWasmExports['vocalEditDraftCommit'];
+  vocalEditDraftCancel: VocalWasmExports['vocalEditDraftCancel'];
+  vocalEditDraftDestroy: VocalWasmExports['vocalEditDraftDestroy'];
+  vocalEditSessionApplyHistory: VocalWasmExports['vocalEditSessionApplyHistory'];
+  vocalEditEvaluatePitch: VocalWasmExports['vocalEditEvaluatePitch'];
+  vocalEditMapCoordinate: VocalWasmExports['vocalEditMapCoordinate'];
+  vocalEditCaptureSnapshot: VocalWasmExports['vocalEditCaptureSnapshot'];
+  vocalEditSnapshotDestroy: VocalWasmExports['vocalEditSnapshotDestroy'];
+  vocalEditSnapshotOutputLength: VocalWasmExports['vocalEditSnapshotOutputLength'];
+  vocalEditSnapshotRender: VocalWasmExports['vocalEditSnapshotRender'];
+  vocalEditRenderJobBegin: VocalWasmExports['vocalEditRenderJobBegin'];
+  vocalEditRenderJobNext: VocalWasmExports['vocalEditRenderJobNext'];
+  vocalEditRenderJobFinalize: VocalWasmExports['vocalEditRenderJobFinalize'];
+  vocalEditRenderJobAbort: VocalWasmExports['vocalEditRenderJobAbort'];
+  vocalEditRenderJobDestroy: VocalWasmExports['vocalEditRenderJobDestroy'];
+  vocalEditSessionExportState: VocalWasmExports['vocalEditSessionExportState'];
+  vocalEditLastErrorDetail: VocalWasmExports['vocalEditLastErrorDetail'];
+
   audioFromMemory: (bytes: Uint8Array) => WasmAudioFromMemoryResult;
 
   // Quick API (high-level)