@signalsandsorcery/plugin-sdk 2.0.1 → 2.0.2

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,25 @@ 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>;
     /** 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). */
@@ -793,7 +826,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';
 declare class PluginError extends Error {
     readonly code: PluginErrorCode;
     readonly details?: Record<string, unknown>;
@@ -905,6 +938,34 @@ 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;
+}
+/**
+ * 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;
 }
 /** Options for composing a full scene arrangement via LLM. */
 interface ComposeSceneOptions {
@@ -1402,4 +1463,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 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 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 };

package/dist/index.d.ts

@@ -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,25 @@ 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>;
     /** 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). */
@@ -793,7 +826,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';
 declare class PluginError extends Error {
     readonly code: PluginErrorCode;
     readonly details?: Record<string, unknown>;
@@ -905,6 +938,34 @@ 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;
+}
+/**
+ * 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;
 }
 /** Options for composing a full scene arrangement via LLM. */
 interface ComposeSceneOptions {
@@ -1402,4 +1463,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 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 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 };