@signalsandsorcery/plugin-sdk 2.0.1 → 2.3.1

package/dist/index.d.mts

@@ -362,6 +362,20 @@ interface PluginHost {
     getPluginSampleTracks(): Promise<PluginSampleTrackInfo[]>;
     /** Time-stretch a sample to a target BPM. Returns the new sample info. */
     timeStretchSample(sampleId: string, targetBpm: number): Promise<PluginSampleInfo>;
+    /**
+     * Fit a sample to the active scene's `(bpm, length_bars)`. Composes:
+     *   1. Time-stretch to scene BPM (no-op if already matching).
+     *   2. Chop / loop-stitch / passthrough so the resulting clip's duration
+     *      equals exactly `length_bars × 4 × (60 / bpm)` seconds.
+     *
+     * Required because the deck loops the clip at the scene's bar boundary —
+     * a 4-bar sample dropped into a 2-bar scene used to over-run; a 4-bar
+     * sample dropped into an 8-bar scene used to leave 4 bars of silence.
+     *
+     * The fitted sample is cached in the library by content hash, so
+     * subsequent calls for the same `(sample, bpm, bars)` return instantly.
+     */
+    fitSampleToScene(sampleId: string): Promise<PluginSampleInfo>;
     /**
      * Lightweight one-shot sample audition through the cue (headphone) output.
      *
@@ -379,6 +393,56 @@ interface PluginHost {
     stopPreview(): Promise<void>;
     /** Invoke the host's audio texture generation pipeline. */
     generateAudioTexture(request: PluginAudioTextureRequest): Promise<PluginAudioTextureResult>;
+    /**
+     * Persist cue points (detected beat positions) for an audio track.
+     * Called once after `writeAudioClip` to remember the trim metadata so the
+     * UI can later draw beat ticks and snap-to-beat the manual offset.
+     *
+     * Pass `null` to clear cue points. Throws OWNERSHIP_VIOLATION if the
+     * track wasn't created by this plugin.
+     */
+    setCuePoints(trackId: string, cues: PluginCuePoints | null): Promise<void>;
+    /** Read cue points previously written by `setCuePoints`. Returns null when none stored. */
+    getCuePoints(trackId: string): Promise<PluginCuePoints | null>;
+    /**
+     * Set the manual sample-offset applied to the track's audio clip during
+     * playback. Positive shifts later, negative shifts earlier with head
+     * silence. Throws OWNERSHIP_VIOLATION if not owned by this plugin.
+     */
+    setAudioOffsetSamples(trackId: string, offsetSamples: number): Promise<void>;
+    /** Read the current manual offset (0 if never set). */
+    getAudioOffsetSamples(trackId: string): Promise<number>;
+    /**
+     * Read raw bytes of an audio file written by the host. The path may be
+     * `~app/`-relative or project-relative — the host resolves it using the
+     * same logic as `writeAudioClip`. Throws FILE_NOT_FOUND if the path
+     * can't be resolved or doesn't exist on disk.
+     */
+    getAudioFileBytes(filePath: string): Promise<ArrayBuffer>;
+    /** Persist the original (raw, un-trimmed) audio file path for a track. */
+    setRawAudioFilePath(trackId: string, filePath: string | null): Promise<void>;
+    /** Read the raw audio file path persisted via `setRawAudioFilePath`. */
+    getRawAudioFilePath(trackId: string): Promise<string | null>;
+    /**
+     * Persist the cue-points detected in the raw (un-trimmed) audio file.
+     * Sample positions are in input-file coordinates.
+     */
+    setRawCuePoints(trackId: string, cues: PluginCuePoints | null): Promise<void>;
+    /** Read raw-domain cue points persisted via `setRawCuePoints`. */
+    getRawCuePoints(trackId: string): Promise<PluginCuePoints | null>;
+    /** Persist the current trim window inside the raw audio file. */
+    setTrimWindow(trackId: string, window: PluginTrimWindow | null): Promise<void>;
+    /** Read the current trim window persisted via `setTrimWindow`. */
+    getTrimWindow(trackId: string): Promise<PluginTrimWindow | null>;
+    /**
+     * Re-trim the raw audio file at the given sample offset and replace the
+     * track's audio clip with the new slice. Persists updated trimmed-domain
+     * cue points and the new trim window.
+     */
+    commitTrimWindow(trackId: string, startSample: number, durationSamples: number): Promise<{
+        filePath: string;
+        cuePoints: PluginCuePoints | null;
+    }>;
     /** Trigger bulk composition for the active scene (LLM plans arrangement, creates tracks, generates MIDI). */
     composeScene(options: ComposeSceneOptions): Promise<ComposeSceneResult>;
     /** Subscribe to composition progress events (planning, generating, complete, error). */
@@ -401,6 +465,108 @@ interface PluginHost {
     splitStems(trackId: string): Promise<PluginStemSplitResult>;
     /** Check if the stem splitter binary is available. */
     isStemSplitterAvailable(): Promise<boolean>;
+    /**
+     * Enumerate audio input devices visible to the engine. Empty list means
+     * no input device is available (or the OS denied permission). Requires
+     * `audioCapture` capability.
+     * @since SDK 2.1.0
+     */
+    getAudioInputDevices(): Promise<AudioInputDevice[]>;
+    /**
+     * Snapshot of engine state needed to start a recording session. Reads
+     * the engine sample rate, the active scene id, the transition-render
+     * lock state, and current BPM/bars. Requires `audioCapture`.
+     * @since SDK 2.1.0
+     */
+    getRecordingTargetInfo(): Promise<RecordingTargetInfo>;
+    /**
+     * Begin a recording session. Engine writes integer-PCM WAV chunks to
+     * disk; one chunk per call to `markRecordingChunkBoundary`. Each
+     * finalized chunk fires a `RecordingChunkFinalizedEvent` to
+     * subscribers of `onRecordingChunkFinalized`. Throws
+     * AUDIO_CAPTURE_DENIED on permission failure or if no device is
+     * available.
+     *
+     * Pass `deviceId` to override the platform-configured input (rare —
+     * only useful for tests or workflows that need a specific device).
+     * Omit it to use the platform's selected input from
+     * `AudioRoutingConfig.inputDeviceId` — this is the recommended path
+     * for plugins post-SDK-2.2.0.
+     *
+     * @since SDK 2.1.0 (deviceId required) — 2.2.0 made it optional.
+     */
+    startTrackRecording(deviceId?: string): Promise<void>;
+    /**
+     * Mark the boundary between two recording chunks. The engine closes the
+     * currently-open WAV writer and opens a new one; the closed file fires
+     * a `RecordingChunkFinalizedEvent` once flush completes. No-op if no
+     * recording session is active.
+     *
+     * Pass `boundaryHostTimeNs` from `DeckBoundaryEvent.boundaryHostTimeNs`
+     * for sample-perfect take alignment (Path 2). The engine then splits
+     * the chunk at the EXACT recorder-sample that corresponds to that
+     * host-time, eliminating the ~5–50 ms of jitter introduced by the
+     * legacy "split wherever the writer is" path. Required for any
+     * workflow that overlays multiple takes (vocalist comping, layered
+     * dubs); optional for single-take captures.
+     *
+     * @since SDK 2.1.0 — 2.4.0 added optional boundaryHostTimeNs.
+     */
+    markRecordingChunkBoundary(boundaryHostTimeNs?: number): Promise<void>;
+    /**
+     * Stop the active recording session. The final chunk is closed and
+     * finalized; its `RecordingChunkFinalizedEvent` fires before this
+     * promise resolves. Returns the path of the final chunk (also delivered
+     * via the event for symmetry).
+     * @since SDK 2.1.0
+     */
+    stopTrackRecording(): Promise<{
+        finalChunkPath: string;
+        durationMs: number;
+    }>;
+    /**
+     * Subscribe to chunk-finalized events for this plugin's active recording
+     * session. Auto-unsubscribed on `deactivate`. Returns unsubscribe fn.
+     * @since SDK 2.1.0
+     */
+    onRecordingChunkFinalized(listener: (event: RecordingChunkFinalizedEvent) => void): UnsubscribeFn;
+    /**
+     * Get the platform-configured audio input device, or null when no
+     * device is set. Read-only; configured via the assistant's
+     * AudioRoutingPanel. Plugins use this to display the current input
+     * to the user without exposing their own picker.
+     *
+     * @since SDK 2.2.0
+     */
+    getCurrentInputDevice(): Promise<AudioInputDevice | null>;
+    /**
+     * Get the platform's mic-to-output round-trip latency offset in
+     * samples. 0 = uncalibrated. Plugins recording audio apply this via
+     * `setAudioOffsetSamples` so takes line up with the source loop.
+     *
+     * @since SDK 2.2.0
+     */
+    getRecordingLatencyOffsetSamples(): Promise<number>;
+    /**
+     * Snapshot of the input level for the most recent audio block.
+     * Renderer polls at ~30Hz to drive a level meter / scrolling
+     * waveform without an event-channel subscription.
+     *
+     * @since SDK 2.3.0
+     */
+    getRecordingInputLevel(): Promise<{
+        peakDb: number;
+        peakLinear: number;
+        clipped: boolean;
+        active: boolean;
+    }>;
+    /**
+     * Reset the latched clip indicator. Safe regardless of whether
+     * monitoring or recording is active.
+     *
+     * @since SDK 2.3.0
+     */
+    clearRecordingInputClipIndicator(): Promise<void>;
 }
 /** Stem type identifiers */
 type StemType = 'vocals' | 'drums' | 'bass' | 'other';
@@ -683,6 +849,20 @@ interface DeckBoundaryEvent {
     bar: number;
     beat: number;
     loopCount: number;
+    /**
+     * Stream-time sample index at which the loop wrap was detected in the
+     * audio thread (engine's AudioBoundaryProbe). Undefined when the
+     * audio-thread anchor was unavailable. @since SDK 2.4.0
+     */
+    boundaryAudioSamplePosition?: number;
+    /**
+     * Monotonic host-time (nanoseconds) at the audio block in which the
+     * loop wrap was detected. Same clock as
+     * `juce::AudioIODeviceCallbackContext::hostTimeNs`. Pair with
+     * `markRecordingChunkBoundary(boundaryHostTimeNs)` for sample-perfect
+     * take alignment. @since SDK 2.4.0
+     */
+    boundaryHostTimeNs?: number;
 }
 interface PluginTransportState {
     isPlaying: boolean;
@@ -793,7 +973,7 @@ interface PluginSettingsStore {
     /** Subscribe to settings changes. Returns unsubscribe fn. */
     onChange(listener: (key: string, value: unknown) => void): UnsubscribeFn;
 }
-type PluginErrorCode = 'NOT_OWNED' | 'TRACK_NOT_FOUND' | 'TRACK_LIMIT_EXCEEDED' | 'NO_ACTIVE_SCENE' | 'ENGINE_ERROR' | 'INVALID_MIDI' | 'FILE_NOT_FOUND' | 'INVALID_FORMAT' | 'PLUGIN_NOT_FOUND' | 'LLM_BUDGET_EXCEEDED' | 'LLM_UNAVAILABLE' | 'NOT_AUTHENTICATED' | 'TIMEOUT' | 'CANCELLED' | 'INCOMPATIBLE' | 'CAPABILITY_DENIED' | 'SECRET_NOT_FOUND';
+type PluginErrorCode = 'NOT_OWNED' | 'TRACK_NOT_FOUND' | 'TRACK_LIMIT_EXCEEDED' | 'NO_ACTIVE_SCENE' | 'ENGINE_ERROR' | 'INVALID_MIDI' | 'FILE_NOT_FOUND' | 'INVALID_FORMAT' | 'PLUGIN_NOT_FOUND' | 'LLM_BUDGET_EXCEEDED' | 'LLM_UNAVAILABLE' | 'NOT_AUTHENTICATED' | 'TIMEOUT' | 'CANCELLED' | 'INCOMPATIBLE' | 'CAPABILITY_DENIED' | 'SECRET_NOT_FOUND' | 'VALIDATION_ERROR' | 'AUDIO_CAPTURE_DENIED';
 declare class PluginError extends Error {
     readonly code: PluginErrorCode;
     readonly details?: Record<string, unknown>;
@@ -826,6 +1006,82 @@ interface PluginCapabilities {
     };
     /** Plugin needs native file dialog access */
     fileDialog?: boolean;
+    /**
+     * Plugin needs microphone / line-in capture. Gates the recording host
+     * methods (getAudioInputDevices, startTrackRecording, etc).
+     * @since SDK 2.1.0
+     */
+    audioCapture?: boolean;
+}
+/**
+ * Audio input device exposed by the audio engine. The `deviceId` is the
+ * stable identifier returned by JUCE's AudioDeviceManager and accepted as
+ * the device argument to `startTrackRecording`.
+ * @since SDK 2.1.0
+ */
+interface AudioInputDevice {
+    /** Stable device identifier — passed back to startTrackRecording. */
+    deviceId: string;
+    /** Human-readable device name (e.g., "MacBook Pro Microphone", "USB Mic"). */
+    label: string;
+    /** True if this is the system default input device. */
+    isDefault: boolean;
+    /** Number of input channels the device supports (1 = mono, 2 = stereo). */
+    channelCount: number;
+}
+/**
+ * Engine state snapshot that an audio-recording plugin needs before
+ * starting a session.
+ * @since SDK 2.1.0
+ */
+interface RecordingTargetInfo {
+    /** Engine device sample rate, e.g. 44100 or 48000. */
+    engineSampleRate: number;
+    /** Active scene id, or null when no scene is selected. */
+    sceneId: string | null;
+    /** True when a transition render lock is held — recorder must refuse. */
+    isRenderLocked: boolean;
+    /** Current project BPM. */
+    bpm: number;
+    /** Active scene length in bars (4/4 assumed), or null when no scene. */
+    bars: number | null;
+    /**
+     * Sample-perfect-recording compatibility (Path 2 gate). When false,
+     * the recorder must refuse to start a session and surface
+     * `recordingCompatibilityReason` to the user — input + output
+     * devices cannot be sample-aligned.
+     * @since SDK 2.4.0
+     */
+    canRecordSamplePerfect?: boolean;
+    recordingCompatibilityReason?: string;
+}
+/**
+ * Event payload fired when the engine finalizes a recording chunk WAV
+ * file (either at a boundary mark or at session stop).
+ * @since SDK 2.1.0
+ */
+interface RecordingChunkFinalizedEvent {
+    /** Absolute path to the finalized WAV file on disk. */
+    filePath: string;
+    /** Zero-based chunk index within the active session. */
+    chunkIndex: number;
+    /** Duration of this chunk in milliseconds. */
+    durationMs: number;
+    /** WAV sample rate. */
+    sampleRate: number;
+    /** WAV channel count. */
+    channels: number;
+    /**
+     * Sample-perfect-recording metadata (Path 2). When the chunk was
+     * closed via a host-time-anchored `markRecordingChunkBoundary` call,
+     * carries recorder-local sample positions plus the host-time at
+     * which the boundary fired. Undefined / -1 means the boundary
+     * lacked a host-time anchor (legacy or stop-driven finalize).
+     * @since SDK 2.4.0
+     */
+    recorderSampleStart?: number;
+    recorderSampleEnd?: number;
+    boundaryHostTimeNs?: number;
 }
 interface PluginFileDialogOptions {
     title?: string;
@@ -905,6 +1161,56 @@ interface PluginAudioTextureResult {
     filePath: string;
     /** Duration of the generated audio in seconds */
     durationSeconds: number;
+    /**
+     * Beat positions inside the generated audio file plus the detected BPM.
+     * Sample positions are relative to the file at `filePath`. Null when the
+     * audio-processor did not surface detection data (older binary, fallback
+     * path, or processing failed). Persist via `host.setCuePoints` after the
+     * clip is written so the OffsetScrubber UI can read them later.
+     */
+    cuePoints: PluginCuePoints | null;
+    /**
+     * Path to the un-trimmed (raw) Lyria output. Used by the audio-texture
+     * trim editor to draw the full waveform. Persist via
+     * `host.setRawAudioFilePath`. Null when no raw file is available.
+     */
+    rawFilePath?: string | null;
+    /** Same beats as `cuePoints` in raw-file sample coordinates. */
+    rawCuePoints?: PluginCuePoints | null;
+    /**
+     * Auto-detected start of the trim window inside the raw file (sample
+     * offset). Null when detection was skipped.
+     */
+    inputStartSample?: number | null;
+}
+/**
+ * Cue-points sidecar surfaced by the audio-processor `trim` command —
+ * sample positions for each detected beat inside the generated WAV.
+ * Mirrors the canonical `CuePoints` shape from the assistant; duplicated
+ * here so external plugins don't reach into sas-assistant internals.
+ */
+interface PluginCuePoints {
+    /** Schema version (currently 1). */
+    schema: 1;
+    /** Sample rate the beat positions are expressed in. */
+    sample_rate: number;
+    /** Detected BPM (may differ from project BPM). Null when detection failed. */
+    detected_bpm: number | null;
+    /** Sample position of bar 1 / beat 1 inside the clip. */
+    downbeat_sample: number;
+    /** Monotone-increasing array of beat positions in samples. */
+    beats: number[];
+    /** ISO-8601 timestamp of when detection ran. */
+    detected_at: string;
+}
+/**
+ * A trim window inside a raw (un-trimmed) audio file. `start_sample` is
+ * the offset from the start of the raw file; `duration_samples` is the
+ * length of the trimmed slice. Both are in raw-file sample coordinates.
+ */
+interface PluginTrimWindow {
+    start_sample: number;
+    duration_samples: number;
 }
 /** Options for composing a full scene arrangement via LLM. */
 interface ComposeSceneOptions {
@@ -1348,7 +1654,7 @@ declare function useSceneState<T>(activeSceneId: string | null, initialValue: T)
  * Registry checks semver.gte(PLUGIN_SDK_VERSION, manifest.minHostVersion)
  * during activation and marks incompatible plugins accordingly.
  */
-declare const PLUGIN_SDK_VERSION = "2.0.0";
+declare const PLUGIN_SDK_VERSION = "2.3.0";
 
 /**
  * FX Preset Definitions
@@ -1402,4 +1708,4 @@ declare function sliderToDb(slider: number): number;
  */
 declare function dbToSlider(db: number): number;
 
-export { type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, type CreateTrackOptions, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, type DeckBoundaryEvent, type DeckBoundaryListener, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, type ExportMidiBundleOptions, type ExportMidiBundleResult, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, type GeneratorPlugin, type GeneratorType, type InstrumentDescriptor, InstrumentDrawer, type InstrumentDrawerProps, type LLMGenerationRequest, type LLMGenerationResult, type MidiClipData, type MidiWriteResult, type MixInterpolation, type MusicalContext, PLUGIN_SDK_VERSION, PanSlider, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginSkill, type PluginSkillInputSchema, type PluginStatus, type PluginStemSplitResult, type PluginStemTrackInfo, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackRuntimeState, type PluginTransportState, type PluginUIProps, type PostProcessOptions, type SDKTrackRowProps, SLIDER_UNITY, type SavePluginPresetOptions, type SceneChangeListener, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type StemType, type TrackFxDetailState, type TrackFxState, TrackRow, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };
+export { type AudioInputDevice, type BulkAddPlaceholderTrack, type ComposeProgressEvent, type ComposeProgressListener, type ComposeSceneOptions, type ComposeSceneResult, type CreateTrackOptions, DB_MAX, DB_MIN, DEFAULT_FX_CATEGORY_DETAIL, DEFAULT_FX_DRY_WET, type DeckBoundaryEvent, type DeckBoundaryListener, EMPTY_FX_DETAIL_STATE, EMPTY_FX_STATE, type ExportMidiBundleOptions, type ExportMidiBundleResult, type ExportedPluginData, FX_CATEGORIES, FX_CHAIN_ORDER, FX_DISPLAY_LABELS, FX_ENGINE_PLUGIN_NAMES, FX_PRESET_CONFIGS, type FxCategory, type FxCategoryDetailState, type FxPreset, type FxPresetConfig, type FxPresetData, type FxPresetDataEntry, FxToggleBar, type FxToggleBarProps, type GeneratorPlugin, type GeneratorType, type InstrumentDescriptor, InstrumentDrawer, type InstrumentDrawerProps, type LLMGenerationRequest, type LLMGenerationResult, type MidiClipData, type MidiWriteResult, type MixInterpolation, type MusicalContext, PLUGIN_SDK_VERSION, PanSlider, type PluginAppTool, type PluginAppToolInputSchema, type PluginAppToolResult, type PluginAudioTextureRequest, type PluginAudioTextureResult, type PluginCapabilities, type PluginChordSegment, type PluginChordTiming, type PluginConcurrentTrackInfo, type PluginCuePoints, type PluginDownloadOptions, PluginError, type PluginErrorCode, type PluginFileDialogOptions, type PluginFxCategoryDetailState, type PluginGenerationContext, type PluginHost, type PluginHttpRequestOptions, type PluginHttpResponse, type PluginManifest, type PluginMidiNote, type PluginPresetData, type PluginPresetInfo, type PluginRegistration, type PluginSampleFilter, type PluginSampleImportResult, type PluginSampleInfo, type PluginSampleTrackInfo, type PluginSceneContext, type PluginSceneInfo, type PluginSettingsSchema, type PluginSettingsStore, type PluginSkill, type PluginSkillInputSchema, type PluginStatus, type PluginStemSplitResult, type PluginStemTrackInfo, type PluginSynthInfo, type PluginTrackFxDetailState, type PluginTrackHandle, type PluginTrackInfo, type PluginTrackRuntimeState, type PluginTransportState, type PluginTrimWindow, type PluginUIProps, type PostProcessOptions, type RecordingChunkFinalizedEvent, type RecordingTargetInfo, type SDKTrackRowProps, SLIDER_UNITY, type SavePluginPresetOptions, type SceneChangeListener, type SettingDefinition, type ShufflePresetResult, SorceryProgressBar, type StemType, type TrackFxDetailState, type TrackFxState, TrackRow, type TrackStateChangeListener, type TransportEvent, type TransportEventListener, type UnsubscribeFn, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };