@signalsandsorcery/plugin-sdk 1.2.1 → 1.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (5) hide show
  1. package/dist/index.d.mts +43 -1
  2. package/dist/index.d.ts +43 -1
  3. package/dist/index.js.map +1 -1
  4. package/dist/index.mjs.map +1 -1
  5. package/package.json +1 -1
package/dist/index.d.mts CHANGED
@@ -70,6 +70,33 @@ interface GeneratorPlugin {
70
70
  * (chords updated, tracks added/removed, BPM changed).
71
71
  */
72
72
  onContextChanged?(context: MusicalContext): void;
73
+ /**
74
+ * Optional: Declare LLM-callable skills this plugin provides.
75
+ * Skills are registered as namespaced tools (plugin:<pluginId>:<skillId>)
76
+ * and become available to AI agents for orchestration.
77
+ *
78
+ * Example: the chat-panel plugin declares a `chat` skill so external
79
+ * agents (Claude Code, OpenClaw) can delegate scene-scoped natural
80
+ * language work to the in-app agent via a single call.
81
+ */
82
+ getSkills?(): PluginSkill[];
83
+ }
84
+ /** An LLM-callable action declared by a plugin. */
85
+ interface PluginSkill {
86
+ /** Unique skill id within this plugin (e.g., 'chat', 'generate_bassline') */
87
+ id: string;
88
+ /** Human-readable description — drives LLM tool selection */
89
+ description: string;
90
+ /** JSON Schema for the skill's input parameters */
91
+ inputSchema: PluginSkillInputSchema;
92
+ /** Whether this skill only reads state (no mutations). Default: false */
93
+ isReadOnly?: boolean;
94
+ }
95
+ /** JSON Schema shape for skill input parameters. */
96
+ interface PluginSkillInputSchema {
97
+ type: 'object';
98
+ properties?: Record<string, unknown>;
99
+ required?: string[];
73
100
  }
74
101
  /** Props passed to every plugin's React component by the host */
75
102
  interface PluginUIProps {
@@ -262,6 +289,21 @@ interface PluginHost {
262
289
  getPluginSampleTracks(): Promise<PluginSampleTrackInfo[]>;
263
290
  /** Time-stretch a sample to a target BPM. Returns the new sample info. */
264
291
  timeStretchSample(sampleId: string, targetBpm: number): Promise<PluginSampleInfo>;
292
+ /**
293
+ * Lightweight one-shot sample audition through the cue (headphone) output.
294
+ *
295
+ * Plays the file via a dedicated SimpleLoopPlayer instance in the audio
296
+ * engine — no Tracktion track or clip is created, no BPM matching, no
297
+ * sync. Calling previewSample again with a different file replaces the
298
+ * current preview cleanly. Independent of loop-b: starting/stopping a
299
+ * preview never affects the performance deck and vice versa.
300
+ */
301
+ previewSample(filePath: string): Promise<void>;
302
+ /**
303
+ * Stop any in-flight sample preview started by previewSample(). Safe to
304
+ * call when no preview is active — never throws.
305
+ */
306
+ stopPreview(): Promise<void>;
265
307
  /** Invoke the host's audio texture generation pipeline. */
266
308
  generateAudioTexture(request: PluginAudioTextureRequest): Promise<PluginAudioTextureResult>;
267
309
  /** Trigger bulk composition for the active scene (LLM plans arrangement, creates tracks, generates MIDI). */
@@ -1205,4 +1247,4 @@ declare function sliderToDb(slider: number): number;
1205
1247
  */
1206
1248
  declare function dbToSlider(db: number): number;
1207
1249
 
1208
- 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 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 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, VALID_INSTRUMENT_ROLES, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };
1250
+ 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 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, VALID_INSTRUMENT_ROLES, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };
package/dist/index.d.ts CHANGED
@@ -70,6 +70,33 @@ interface GeneratorPlugin {
70
70
  * (chords updated, tracks added/removed, BPM changed).
71
71
  */
72
72
  onContextChanged?(context: MusicalContext): void;
73
+ /**
74
+ * Optional: Declare LLM-callable skills this plugin provides.
75
+ * Skills are registered as namespaced tools (plugin:<pluginId>:<skillId>)
76
+ * and become available to AI agents for orchestration.
77
+ *
78
+ * Example: the chat-panel plugin declares a `chat` skill so external
79
+ * agents (Claude Code, OpenClaw) can delegate scene-scoped natural
80
+ * language work to the in-app agent via a single call.
81
+ */
82
+ getSkills?(): PluginSkill[];
83
+ }
84
+ /** An LLM-callable action declared by a plugin. */
85
+ interface PluginSkill {
86
+ /** Unique skill id within this plugin (e.g., 'chat', 'generate_bassline') */
87
+ id: string;
88
+ /** Human-readable description — drives LLM tool selection */
89
+ description: string;
90
+ /** JSON Schema for the skill's input parameters */
91
+ inputSchema: PluginSkillInputSchema;
92
+ /** Whether this skill only reads state (no mutations). Default: false */
93
+ isReadOnly?: boolean;
94
+ }
95
+ /** JSON Schema shape for skill input parameters. */
96
+ interface PluginSkillInputSchema {
97
+ type: 'object';
98
+ properties?: Record<string, unknown>;
99
+ required?: string[];
73
100
  }
74
101
  /** Props passed to every plugin's React component by the host */
75
102
  interface PluginUIProps {
@@ -262,6 +289,21 @@ interface PluginHost {
262
289
  getPluginSampleTracks(): Promise<PluginSampleTrackInfo[]>;
263
290
  /** Time-stretch a sample to a target BPM. Returns the new sample info. */
264
291
  timeStretchSample(sampleId: string, targetBpm: number): Promise<PluginSampleInfo>;
292
+ /**
293
+ * Lightweight one-shot sample audition through the cue (headphone) output.
294
+ *
295
+ * Plays the file via a dedicated SimpleLoopPlayer instance in the audio
296
+ * engine — no Tracktion track or clip is created, no BPM matching, no
297
+ * sync. Calling previewSample again with a different file replaces the
298
+ * current preview cleanly. Independent of loop-b: starting/stopping a
299
+ * preview never affects the performance deck and vice versa.
300
+ */
301
+ previewSample(filePath: string): Promise<void>;
302
+ /**
303
+ * Stop any in-flight sample preview started by previewSample(). Safe to
304
+ * call when no preview is active — never throws.
305
+ */
306
+ stopPreview(): Promise<void>;
265
307
  /** Invoke the host's audio texture generation pipeline. */
266
308
  generateAudioTexture(request: PluginAudioTextureRequest): Promise<PluginAudioTextureResult>;
267
309
  /** Trigger bulk composition for the active scene (LLM plans arrangement, creates tracks, generates MIDI). */
@@ -1205,4 +1247,4 @@ declare function sliderToDb(slider: number): number;
1205
1247
  */
1206
1248
  declare function dbToSlider(db: number): number;
1207
1249
 
1208
- 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 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 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, VALID_INSTRUMENT_ROLES, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };
1250
+ 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 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, VALID_INSTRUMENT_ROLES, VolumeSlider, calculateTimeBasedTarget, dbToSlider, sliderToDb, useSceneState };