@soundor/vst3-host 0.0.0-stage → 0.1.1

package/dist/cli.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.mjs","names":[],"sources":["../src/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n// soundor-vst3-host <command>\n//\n//   open <plugin.vst3> [--class <name>] [--bare | --interface]\n//        [--sample-rate <hz>] [--block-size <frames>]     open a plugin's editor until its window closes\n//   prepare [--mode prebuilt|published|source] [--artifact <dir>]   select or build the executable\n//   resolve                                               print the executable launchHost() runs\n//   inputs                                                print the native input fingerprint\nimport { parseArgs } from 'node:util';\n\nimport { Vst3HostError } from './errors.ts';\nimport { launchHost } from './host.ts';\nimport { nativeInputs } from './inputs.ts';\nimport { type BuildMode, prepareHost } from './prepare.ts';\nimport { resolveHost } from './resolve.ts';\n\nconst { positionals, values } = parseArgs({\n  allowPositionals: true,\n  options: {\n    mode: { type: 'string' },\n    artifact: { type: 'string' },\n    commit: { type: 'string' },\n    class: { type: 'string' },\n    bare: { type: 'boolean' },\n    interface: { type: 'boolean' },\n    'sample-rate': { type: 'string' },\n    'block-size': { type: 'string' },\n  },\n});\n\nconst USAGE = `usage: soundor-vst3-host <command>\n  open <plugin.vst3> [--class <name>] [--bare | --interface] [--sample-rate <hz>] [--block-size <frames>]\n  prepare [--mode prebuilt|published|source] [--artifact <dir>] [--commit <sha>]\n  resolve\n  inputs`;\n\n/** Opens a plugin's editor and waits until its window is closed. */\nasync function open(): Promise<void> {\n  const plugin = positionals[1];\n  if (plugin === undefined) throw new Error('open needs a .vst3 bundle');\n  if (values.bare && values.interface)\n    throw new Error('--bare and --interface are opposites');\n  const number = (name: 'sample-rate' | 'block-size'): number | undefined => {\n    const text = values[name];\n    if (text === undefined) return undefined;\n    const value = Number(text);\n    if (!Number.isFinite(value)) throw new Error(`--${name} is a number`);\n    return value;\n  };\n  const host = await launchHost({\n    plugin,\n    className: values.class,\n    editor: true,\n    presentation: values.bare ? 'editor' : values.interface ? 'host' : null,\n    sampleRate: number('sample-rate'),\n    blockSize: number('block-size'),\n    requestTimeout: 0x7fffffff,\n    onLog: (line) => console.error(line),\n  });\n  const closed = new Promise<void>((resolve) => {\n    host.once('editorClosed', () => resolve());\n    host.once('exit', () => resolve());\n    process.once('SIGINT', () => resolve());\n    process.once('SIGTERM', () => resolve());\n  });\n  console.error(\n    `${host.info.name}: close its window (or press Ctrl+C) to quit`,\n  );\n  await closed;\n  await host.close();\n}\n\ntry {\n  switch (positionals[0]) {\n    case 'open':\n      await open();\n      break;\n    case 'prepare': {\n      const mode = values.mode ?? 'prebuilt';\n      if (mode !== 'prebuilt' && mode !== 'published' && mode !== 'source')\n        throw new Error(\n          `--mode is \"prebuilt\", \"published\" or \"source\", not \"${mode}\"`,\n        );\n      await prepareHost({\n        mode: mode as BuildMode,\n        artifact: values.artifact,\n        commit: values.commit,\n      });\n      break;\n    }\n    case 'resolve': {\n      const resolved = resolveHost();\n      console.log(\n        `${resolved.executable}\\t(${resolved.source}: ${resolved.reason})`,\n      );\n      break;\n    }\n    case 'inputs':\n      console.log(JSON.stringify(nativeInputs(), null, 2));\n      break;\n    default:\n      console.error(USAGE);\n      process.exitCode = 64;\n  }\n} catch (error) {\n  console.error(\n    error instanceof Vst3HostError\n      ? `error (${error.code}): ${error.message}`\n      : `error: ${(error as Error).message}`,\n  );\n  process.exitCode = 1;\n}\n"],"mappings":";;;;AAgBA,MAAM,EAAE,aAAa,WAAW,UAAU;CACxC,kBAAkB;CAClB,SAAS;EACP,MAAM,EAAE,MAAM,SAAS;EACvB,UAAU,EAAE,MAAM,SAAS;EAC3B,QAAQ,EAAE,MAAM,SAAS;EACzB,OAAO,EAAE,MAAM,SAAS;EACxB,MAAM,EAAE,MAAM,UAAU;EACxB,WAAW,EAAE,MAAM,UAAU;EAC7B,eAAe,EAAE,MAAM,SAAS;EAChC,cAAc,EAAE,MAAM,SAAS;CACjC;AACF,CAAC;AAED,MAAM,QAAQ;;;;;;AAOd,eAAe,OAAsB;CACnC,MAAM,SAAS,YAAY;CAC3B,IAAI,WAAW,KAAA,GAAW,MAAM,IAAI,MAAM,2BAA2B;CACrE,IAAI,OAAO,QAAQ,OAAO,WACxB,MAAM,IAAI,MAAM,sCAAsC;CACxD,MAAM,UAAU,SAA2D;EACzE,MAAM,OAAO,OAAO;EACpB,IAAI,SAAS,KAAA,GAAW,OAAO,KAAA;EAC/B,MAAM,QAAQ,OAAO,IAAI;EACzB,IAAI,CAAC,OAAO,SAAS,KAAK,GAAG,MAAM,IAAI,MAAM,KAAK,KAAK,aAAa;EACpE,OAAO;CACT;CACA,MAAM,OAAO,MAAM,WAAW;EAC5B;EACA,WAAW,OAAO;EAClB,QAAQ;EACR,cAAc,OAAO,OAAO,WAAW,OAAO,YAAY,SAAS;EACnE,YAAY,OAAO,aAAa;EAChC,WAAW,OAAO,YAAY;EAC9B,gBAAgB;EAChB,QAAQ,SAAS,QAAQ,MAAM,IAAI;CACrC,CAAC;CACD,MAAM,SAAS,IAAI,SAAe,YAAY;EAC5C,KAAK,KAAK,sBAAsB,QAAQ,CAAC;EACzC,KAAK,KAAK,cAAc,QAAQ,CAAC;EACjC,QAAQ,KAAK,gBAAgB,QAAQ,CAAC;EACtC,QAAQ,KAAK,iBAAiB,QAAQ,CAAC;CACzC,CAAC;CACD,QAAQ,MACN,GAAG,KAAK,KAAK,KAAK,6CACpB;CACA,MAAM;CACN,MAAM,KAAK,MAAM;AACnB;AAEA,IAAI;CACF,QAAQ,YAAY,IAApB;EACE,KAAK;GACH,MAAM,KAAK;GACX;EACF,KAAK,WAAW;GACd,MAAM,OAAO,OAAO,QAAQ;GAC5B,IAAI,SAAS,cAAc,SAAS,eAAe,SAAS,UAC1D,MAAM,IAAI,MACR,uDAAuD,KAAK,EAC9D;GACF,MAAM,YAAY;IACV;IACN,UAAU,OAAO;IACjB,QAAQ,OAAO;GACjB,CAAC;GACD;EACF;EACA,KAAK,WAAW;GACd,MAAM,WAAW,YAAY;GAC7B,QAAQ,IACN,GAAG,SAAS,WAAW,KAAK,SAAS,OAAO,IAAI,SAAS,OAAO,EAClE;GACA;EACF;EACA,KAAK;GACH,QAAQ,IAAI,KAAK,UAAU,aAAa,GAAG,MAAM,CAAC,CAAC;GACnD;EACF;GACE,QAAQ,MAAM,KAAK;GACnB,QAAQ,WAAW;CACvB;AACF,SAAS,OAAO;CACd,QAAQ,MACN,iBAAiB,gBACb,UAAU,MAAM,KAAK,KAAK,MAAM,YAChC,UAAW,MAAgB,SACjC;CACA,QAAQ,WAAW;AACrB"}

package/dist/index.d.mts

@@ -0,0 +1,586 @@
+import { ChildProcess } from "node:child_process";
+/** A bus's speaker arrangement: a channel count, or a name ("mono",
+    "stereo", an SDK name such as "5.1"), or a hexadecimal mask ("0x3"). */
+interface BusSetup {
+  channels?: number;
+  arrangement?: string;
+  /** Default: main buses and the buses the plugin marks default-active. */
+  active?: boolean;
+}
+type ProcessMode = 'realtime' | 'offline' | 'prefetch';
+interface ProcessingSetup {
+  /** Hz. Default 48000. */
+  sampleRate?: number;
+  /** The largest block the plugin is given, in frames. Default 512. */
+  blockSize?: number;
+  /** The mode the plugin is told it runs in (ProcessSetup::processMode).
+        Default "realtime": what a DAW's playback does. Processing is offline
+        either way. */
+  processMode?: ProcessMode;
+  /** By audio input bus index; `null` or a missing entry keeps the
+        plugin's default. */
+  inputs?: (BusSetup | null)[];
+  outputs?: (BusSetup | null)[];
+}
+interface BusInfo {
+  index: number;
+  name: string;
+  type: 'main' | 'aux';
+  channels: number;
+  /** Audio buses: the arrangement's name, or its mask in hexadecimal. */
+  arrangement?: string;
+  active: boolean;
+  defaultActive: boolean;
+}
+interface PluginClass {
+  name: string;
+  /** The class's 32-digit hexadecimal id. */
+  classId: string;
+}
+interface PluginInfo {
+  path: string;
+  name: string;
+  classId: string;
+  vendor: string;
+  version: string;
+  sdkVersion: string;
+  subCategories: string[];
+  factory: {
+    vendor: string;
+    url: string;
+    email: string;
+  };
+  /** Every audio processor class of the bundle. */
+  classes: PluginClass[];
+  separateController: boolean;
+  hasController: boolean;
+  sampleRate: number;
+  blockSize: number;
+  processMode: ProcessMode;
+  buses: {
+    audioInputs: BusInfo[];
+    audioOutputs: BusInfo[];
+    eventInputs: BusInfo[];
+    eventOutputs: BusInfo[];
+  };
+  parameterCount: number;
+  latencySamples: number;
+  tailSamples: number | 'infinite';
+}
+/** A VST3 parameter. `id` is the plugin's ParamID (an unsigned 32-bit
+    integer), stable across instances and sessions of the same plugin. */
+interface ParameterInfo {
+  id: number;
+  title: string;
+  shortTitle: string;
+  units: string;
+  /** 0: continuous; 1: a toggle; n: n + 1 discrete values. */
+  stepCount: number;
+  defaultNormalized: number;
+  unitId: number;
+  flags: {
+    canAutomate: boolean;
+    readOnly: boolean;
+    wrap: boolean;
+    list: boolean;
+    hidden: boolean;
+    programChange: boolean;
+    bypass: boolean;
+  };
+  /** The current value, from 0 to 1. */
+  normalized: number;
+  /** The same value in the plugin's own units (normalizedParamToPlain). */
+  plain: number;
+  /** The plugin's text for it (getParamStringByValue), or null. */
+  display: string | null;
+}
+/** Either value; the other is derived by the plugin's controller. */
+type ParameterValue = {
+  normalized: number;
+} | {
+  plain: number;
+};
+/** A parameter found by its title, from `Vst3Host.parameter()`. */
+interface HostParameter {
+  /** Its current values. */
+  get(options?: RequestOptions): Promise<ParameterInfo>;
+  /** Sets the controller's value now and hands the change to the processor
+        at the first frame of the next process call. */
+  set(value: ParameterValue | number, options?: RequestOptions): Promise<ParameterInfo>;
+}
+interface ParameterChange {
+  id: number;
+  /** Normalized, 0 to 1. */
+  value: number;
+  /** The frame it applies at, from the start of the process call. Default 0. */
+  time?: number;
+}
+interface TimedEvent {
+  /** The frame, from the start of the process call. Default 0. */
+  time?: number;
+  /** MIDI channel 0–15. Default 0. */
+  channel?: number;
+}
+interface NoteEventBase extends TimedEvent {
+  /** Event bus index. Default 0. */
+  bus?: number;
+  pitch: number;
+  /** -1 (default): none. */
+  noteId?: number;
+}
+interface NoteOnEvent extends NoteEventBase {
+  type: 'noteOn';
+  /** 0 to 1. Default 1. */
+  velocity?: number;
+  /** Cents. */
+  tuning?: number;
+  /** Frames, when known in advance. */
+  length?: number;
+}
+interface NoteOffEvent extends NoteEventBase {
+  type: 'noteOff';
+  velocity?: number;
+  tuning?: number;
+}
+interface PolyPressureEvent extends NoteEventBase {
+  type: 'polyPressure';
+  pressure: number;
+}
+/** MIDI controllers reach VST3 plugins as parameter changes, through the
+    plugin's IMidiMapping; one it does not map is dropped with a warning. */
+interface ControlChangeEvent extends TimedEvent {
+  type: 'controlChange';
+  bus?: number;
+  controller: number;
+  /** 0 to 1 (MIDI value / 127). */
+  value: number;
+}
+interface PitchBendEvent extends TimedEvent {
+  type: 'pitchBend';
+  bus?: number;
+  /** -1 to 1. */
+  value: number;
+}
+interface ChannelPressureEvent extends TimedEvent {
+  type: 'channelPressure';
+  bus?: number;
+  /** 0 to 1. */
+  value: number;
+}
+type InputEvent = NoteOnEvent | NoteOffEvent | PolyPressureEvent | ControlChangeEvent | PitchBendEvent | ChannelPressureEvent;
+type OutputEvent = {
+  type: 'noteOn' | 'noteOff';
+  time: number;
+  bus: number;
+  channel: number;
+  pitch: number;
+  velocity: number;
+  noteId: number;
+} | {
+  type: 'polyPressure';
+  time: number;
+  bus: number;
+  channel: number;
+  pitch: number;
+  pressure: number;
+  noteId: number;
+} | {
+  type: 'midiCC';
+  time: number;
+  bus: number;
+  channel: number;
+  controller: number;
+  value: number;
+  value2: number;
+} | {
+  type: 'other';
+  time: number;
+  bus: number;
+  vstType: number;
+};
+interface Transport {
+  playing: boolean;
+  /** Beats per minute. */
+  tempo: number;
+  timeSignature: {
+    numerator: number;
+    denominator: number;
+  };
+  /** The project position, in frames. */
+  samplePosition: number;
+  /** The same position in quarter notes. */
+  musicalPosition: number;
+}
+/** Changes to the host's transport, kept for later calls. Give the position
+    in frames or in quarter notes, not both. */
+interface TransportUpdate {
+  playing?: boolean;
+  tempo?: number;
+  timeSignature?: {
+    numerator?: number;
+    denominator?: number;
+  };
+  samplePosition?: number;
+  musicalPosition?: number;
+}
+/** Audio as channels: one Float32Array per channel, all the same length. */
+type AudioBus = readonly Float32Array[];
+interface RequestOptions {
+  /** Milliseconds; the host is stopped if it does not answer in time.
+        Default: the host's requestTimeout. */
+  timeout?: number;
+  signal?: AbortSignal;
+}
+interface ProcessRequest extends RequestOptions {
+  /** Frames to process. Default: the length of the given input channels;
+        required when no input is given (instruments). */
+  frames?: number;
+  /** By audio input bus index. A missing, `null` or `undefined` bus gets
+        silence. A given bus has exactly the bus's channel count. */
+  inputs?: readonly (AudioBus | null | undefined)[];
+  events?: readonly InputEvent[];
+  parameterChanges?: readonly ParameterChange[];
+  transport?: TransportUpdate;
+}
+interface ProcessResult {
+  frames: number;
+  /** By audio output bus index; an inactive bus has no channels. The
+        arrays are the caller's. */
+  outputs: Float32Array[][];
+  events: OutputEvent[];
+  /** What the processor reported (meters, read-only values), with the
+        frame each applies at. */
+  parameterChanges: Required<ParameterChange>[];
+  /** The transport after the call. */
+  transport: Transport;
+  /** Input the plugin could not take (an unmapped MIDI controller). */
+  warnings: string[];
+}
+/** A plugin's saved state: its processor's, then its controller's. */
+interface PluginState {
+  component: Uint8Array;
+  controller: Uint8Array;
+}
+/**
+ * How an editor is shown: `editor`, a window that is the plugin's editor
+ * alone, or `host`, the editor with the host interface around it (a dock
+ * and a side panel). Either way the editor has the same size, and
+ * everything the interface does can be done through this API.
+ */
+type Presentation = 'editor' | 'host';
+interface EditorInfo {
+  open: boolean;
+  /** The editor's size (not the window's). */
+  width?: number;
+  height?: number;
+  resizable?: boolean;
+  scale?: number;
+  platformType?: string;
+  presentation?: Presentation;
+  /** The window's content size: the editor's in `editor`, more in `host`. */
+  window?: {
+    width: number;
+    height: number;
+  };
+  /** `host`: the frames the interface has presented. An idle window
+        presents none. */
+  interfaceFrames?: number;
+}
+/** Where live audio's input comes from: a 220 Hz triangle wave, a WAV
+    file (looped), the default recording device, or silence. It plays while
+    the transport does. */
+type AudioInput = 'oscillator' | 'file' | 'microphone' | 'none';
+interface AudioSettings {
+  input?: AudioInput;
+  /** A WAV file's path, for the `file` input (selects it when no input is given). */
+  file?: string;
+  muted?: boolean;
+  /** The output volume, from 0 to 1. */
+  volume?: number;
+}
+interface AudioStatus {
+  /** Live audio plays through the default output device. */
+  running: boolean;
+  muted: boolean;
+  volume: number;
+  input: AudioInput;
+  file: string | null;
+  /** The output device's name while running. */
+  device: string | null;
+  /** The device or the plugin's processing failed. */
+  error: string | null;
+  /** The input could not be opened (a microphone) or read (a file). */
+  inputError: string | null;
+}
+interface LatencyInfo {
+  latencySamples: number;
+  tailSamples: number | 'infinite';
+}
+interface HostEvents {
+  /** The editor's controller began, made or ended a parameter edit. */
+  beginEdit: {
+    id: number;
+  };
+  performEdit: {
+    id: number;
+    value: number;
+  };
+  endEdit: {
+    id: number;
+  };
+  /** The plugin asked to be restarted; the host did so between calls. */
+  restart: {
+    flags: number;
+    reasons: string[];
+    latencySamples: number;
+  };
+  dirty: {
+    dirty: boolean;
+  };
+  editorRequested: Record<string, never>;
+  editorResized: EditorInfo;
+  /** The user closed the editor's window. */
+  editorClosed: Record<string, never>;
+  /** Live audio changed from the host interface (started, stopped, muted,
+        another input or volume). */
+  audioChanged: AudioStatus;
+  /** The host process ended. */
+  exit: {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+  };
+}
+interface LaunchOptions extends ProcessingSetup {
+  /** The .vst3 bundle to load, by path; it need not be installed. */
+  plugin: string;
+  /** The audio processor class, when the bundle has several. */
+  className?: string;
+  classId?: string;
+  /** UI mode: open the plugin's editor in a native window. Default false
+        (headless: no window, no display needed). */
+  editor?: boolean;
+  /** The editor's content scale (Windows, Linux). Default: the window's. */
+  scale?: number;
+  /** How the editor is shown (with `editor: true`): `editor` (the default),
+        a window that is the editor alone, or `host`, with the host interface.
+        `null`: as the user's host settings say (`host` unless they turned the
+        interface off), what the `open` command does. */
+  presentation?: Presentation | null;
+  /** The executable. Default: resolveHost(). */
+  executable?: string;
+  /** Runs the host in a process group of its own, so that a terminal's Ctrl+C
+        reaches only Node, which can ask the plugin for its state before calling
+        `close()`. It still ends with Node. Default false. */
+  detached?: boolean;
+  /** Added to (or, with inheritEnv: false, instead of) process.env.
+        SOUNDOR_DEVTOOLS_SESSION reaches the plugin this way. */
+  env?: Record<string, string | undefined>;
+  inheritEnv?: boolean;
+  cwd?: string;
+  /** Milliseconds for the host to start and load the plugin. Default 30000. */
+  startTimeout?: number;
+  /** Default timeout of each request, in milliseconds. Default 60000. */
+  requestTimeout?: number;
+  /** The largest frame either side accepts. Default 256 MiB. */
+  maxPayloadBytes?: number;
+  /** Each line the host or the plugin writes to stderr. */
+  onLog?: (line: string) => void;
+  signal?: AbortSignal;
+}
+/** Starts a host process, loads the plugin and resolves once it is ready. */
+export declare function launchHost(options: LaunchOptions): Promise<Vst3Host>;
+interface HostOptions {
+  maxPayloadBytes: number;
+  requestTimeout: number;
+  onLog: ((line: string) => void) | undefined;
+  executable: string;
+}
+interface HostIdentity {
+  protocol: number;
+  version: string;
+  sdkVersion: string;
+  platform: string;
+  arch: string;
+  mode: 'ui' | 'headless';
+  maxPayloadBytes: number;
+}
+/** A running host with one plugin loaded. Requests run one at a time, in
+    the order they are made. */
+export declare class Vst3Host {
+  #private;
+  /** @internal Use launchHost(). */
+  constructor(child: ChildProcess, options: HostOptions);
+  /** The host process's id. */
+  get pid(): number | undefined;
+  /** What the host reported when it started. */
+  get identity(): HostIdentity;
+  /** The loaded plugin, as of launch or the last recreate/configure. */
+  get info(): PluginInfo;
+  /** Resolves when the process has ended. */
+  get exited(): Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+  }>;
+  /** The end of what the host and the plugin wrote to stderr. */
+  get diagnostics(): string;
+  on<E extends keyof HostEvents>(event: E, listener: (params: HostEvents[E]) => void): this;
+  off<E extends keyof HostEvents>(event: E, listener: (params: HostEvents[E]) => void): this;
+  once<E extends keyof HostEvents>(event: E, listener: (params: HostEvents[E]) => void): this;
+  /** @internal */
+  ready(timeout: number, signal?: AbortSignal): Promise<void>;
+  /** @internal */
+  load(options: LaunchOptions, timeout: number, signal?: AbortSignal): Promise<void>;
+  getInfo(options?: RequestOptions): Promise<PluginInfo>;
+  getParameters(options?: RequestOptions): Promise<ParameterInfo[]>;
+  getParameter(id: number, options?: RequestOptions): Promise<ParameterInfo>;
+  /** Sets the controller's value now and hands the change to the processor
+        at the first frame of the next process call. */
+  setParameter(id: number, value: ParameterValue | number, options?: RequestOptions): Promise<ParameterInfo>;
+  /** A parameter by its title, looked up at each use (see
+        {@link parameterTitled}). */
+  parameter(title: string): HostParameter;
+  getLatency(options?: RequestOptions): Promise<LatencyInfo>;
+  /** Processes `frames` frames, in blocks of at most the block size. */
+  process(request?: ProcessRequest): Promise<ProcessResult>;
+  /** The processor's and the controller's state. Pending parameter changes
+        reach the processor first (in a process call of zero frames). */
+  getState(options?: RequestOptions): Promise<PluginState>;
+  setState(state: PluginState, options?: RequestOptions): Promise<void>;
+  /** Deactivates and reactivates the plugin: it clears delay lines, held
+        notes and other processing state. The transport is kept. */
+  reset(options?: RequestOptions): Promise<void>;
+  /** A fresh instance of the same class and setup, in the same process.
+        The transport starts over. */
+  recreate(options?: RequestOptions): Promise<PluginInfo>;
+  /** A new sample rate, block size, mode or bus layout. What is not given
+        stays as it is. */
+  configure(setup: ProcessingSetup, options?: RequestOptions): Promise<PluginInfo>;
+  /** Opens the editor, or shows an open one in another presentation (it
+        opens again there, at the same size). */
+  openEditor(options?: RequestOptions & {
+    scale?: number;
+    presentation?: Presentation;
+  }): Promise<EditorInfo>;
+  closeEditor(options?: RequestOptions): Promise<EditorInfo>;
+  resizeEditor(width: number, height: number, options?: RequestOptions): Promise<EditorInfo>;
+  getEditor(options?: RequestOptions): Promise<EditorInfo>;
+  /** Starts live audio through the default output device, with `settings`
+        applied first. Fails with `audio-unavailable` without a device.
+        While it runs, `process` fails: the plugin is processing live. */
+  startAudio(settings?: AudioSettings & RequestOptions): Promise<AudioStatus>;
+  stopAudio(options?: RequestOptions): Promise<AudioStatus>;
+  /** Changes live audio's input, volume or muting, running or not. */
+  setAudio(settings: AudioSettings & RequestOptions): Promise<AudioStatus>;
+  getAudio(options?: RequestOptions): Promise<AudioStatus>;
+  /** The host's transport, which live audio advances while it plays. */
+  getTransport(options?: RequestOptions): Promise<Transport>;
+  /** Changes the transport, as `process({ transport })` does, without
+        processing: play and stop live audio's transport, or set its tempo. */
+  setTransport(update: TransportUpdate, options?: RequestOptions): Promise<Transport>;
+  /** Unloads the plugin and ends the process: politely, then by force.
+        Safe to call more than once and after a failure. */
+  close(timeout?: number): Promise<{
+    code: number | null;
+    signal: NodeJS.Signals | null;
+  }>;
+  [Symbol.asyncDispose](): Promise<void>;
+}
+/** Codes the host reports, and the client's own. */
+type Vst3HostErrorCode = 'plugin-not-found' | 'invalid-bundle' | 'incompatible-architecture' | 'load-failed' | 'unsupported-plugin' | 'no-matching-class' | 'ambiguous-class' | 'initialization-failed' | 'unsupported-configuration' | 'unknown-parameter' | 'plugin-error' | 'no-editor' | 'no-display' | 'headless' | 'audio-unavailable' | 'invalid-request' | 'invalid-state' | 'unknown-method' | 'message-too-large' | 'internal-error' | 'host-exited' | 'timeout' | 'aborted' | 'closed' | 'protocol-error' | 'incompatible-host' | 'executable-not-found' | 'platform-package-missing' | 'unsupported-platform' | 'selection-failed';
+export declare class Vst3HostError extends Error {
+  readonly name = "Vst3HostError";
+  readonly code: Vst3HostErrorCode;
+  readonly details: Record<string, unknown> | undefined;
+  constructor(code: Vst3HostErrorCode, message: string, details?: Record<string, unknown>, options?: ErrorOptions);
+}
+interface Provenance {
+  format: 1;
+  name: '@soundor/vst3-host';
+  version: string;
+  protocol: number;
+  target: string;
+  architectures: string[];
+  configuration: 'Release';
+  /** The commit it was built from (CI), or null for a local build. */
+  sourceCommit: string | null;
+  /** nativeInputs() of the sources it was built from. */
+  sourceFingerprint: string;
+  executable: {
+    path: string;
+    sha256: string;
+    size: number;
+  };
+  /** Linux: the newest glibc symbol version the executable needs. */
+  glibc?: string;
+}
+interface ResolvedHost {
+  executable: string;
+  source: 'explicit' | 'package' | 'selection';
+  /** Why this one, for logs. */
+  reason: string;
+  provenance?: Provenance;
+}
+interface ResolveOptions {
+  executable?: string;
+  /** Default: this package's root. */
+  root?: string;
+}
+export declare function resolveHost(options?: ResolveOptions): ResolvedHost;
+type Fetch = typeof fetch;
+interface Target {
+  target: string;
+  package: string;
+  os: string[];
+  cpu: string[];
+  libc?: string[];
+  runner: string;
+  architectures: string[];
+  /** Relative to the platform package's root. */
+  executable: string;
+}
+/** The platform packages a release generates (targets.json). */
+export declare const targets: readonly Target[];
+interface Platform {
+  platform: NodeJS.Platform;
+  arch: string;
+  /** Linux: "glibc" or "musl". */
+  libc?: string;
+  /** Linux with glibc: its version, such as "2.39". */
+  glibc?: string;
+}
+/** The target whose executable runs here, if any. */
+export declare function targetFor(platform?: Platform): Target | undefined;
+type BuildMode = 'prebuilt' | 'published' | 'source';
+interface PrepareOptions {
+  mode?: BuildMode;
+  /** A CI artifact directory (an executable and its soundor-vst3-host.json).
+        Default: SOUNDOR_VST3_HOST_ARTIFACT. */
+  artifact?: string;
+  /** The commit an artifact must come from. Default: GITHUB_SHA when set. */
+  commit?: string;
+  /** Default: SOUNDOR_CACHE, else the user cache directory. */
+  cache?: string;
+  registry?: string;
+  fetcher?: Fetch;
+  /** Default: console.log. */
+  log?: (message: string) => void;
+  root?: string;
+  /** @internal Replaces the CMake build (tests). */
+  build?: (reason: string) => PreparedHost;
+}
+interface PreparedHost {
+  executable: string;
+  mode: 'prebuilt' | 'source' | 'artifact';
+  reason: string;
+  sourceFingerprint: string;
+}
+export declare function prepareHost(options?: PrepareOptions): Promise<PreparedHost>;
+interface NativeInputs {
+  fingerprint: string;
+  files: string[];
+  version: string;
+}
+export declare function nativeInputs(root?: string): NativeInputs;
+export declare const PROTOCOL_VERSION: number;
+export type { AudioBus, AudioInput, AudioSettings, AudioStatus, BuildMode, BusInfo, BusSetup, ChannelPressureEvent, ControlChangeEvent, EditorInfo, HostEvents, HostIdentity, HostParameter, InputEvent, LatencyInfo, LaunchOptions, NoteOffEvent, NoteOnEvent, OutputEvent, ParameterChange, ParameterInfo, ParameterValue, PitchBendEvent, PluginClass, PluginInfo, PluginState, PolyPressureEvent, PrepareOptions, PreparedHost, Presentation, ProcessMode, ProcessRequest, ProcessResult, ProcessingSetup, RequestOptions, ResolveOptions, ResolvedHost, Target, Transport, TransportUpdate, Vst3HostErrorCode };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/types.ts","../src/host.ts","../src/errors.ts","../src/provenance.ts","../src/resolve.ts","../src/npm.ts","../src/targets.ts","../src/prepare.ts","../src/inputs.ts","../src/protocol.ts"],"mappings":"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"}

package/dist/index.mjs

@@ -0,0 +1 @@
+export { c as PROTOCOL_VERSION, n as Vst3Host, l as Vst3HostError, r as launchHost, a as nativeInputs, t as prepareHost, i as resolveHost, o as targetFor, s as targets } from "./prepare-ayjTVhfk.mjs";