@signalsandsorcery/plugin-sdk 2.0.2 → 2.24.1

package/README.md

@@ -31,8 +31,8 @@ These built-in plugins serve as reference implementations:
 | Plugin | Type | Description | Source |
 |--------|------|-------------|--------|
 | Synth Generator | `midi` | AI-powered MIDI generation with Surge XT presets | [sas-synth-plugin](https://github.com/shiehn/sas-synth-plugin) |
-| Sample Player | `sample` | Sample library browser with time-stretching | [sas-sample-plugin](https://github.com/shiehn/sas-sample-plugin) |
-| Audio Texture | `audio` | AI audio texture generation | [sas-audio-plugin](https://github.com/shiehn/sas-audio-plugin) |
+| Loops | `sample` | Audio loop / sample library browser with time-stretching | [sas-loops-plugin](https://github.com/shiehn/sas-loops-plugin) |
+| Stems | `audio` | AI audio-from-text generation with optional stem splitting | [sas-stems-plugin](https://github.com/shiehn/sas-stems-plugin) |
 
 ## What's in the SDK
 
@@ -66,9 +66,36 @@ Pre-built components that match the host app's visual style:
 | `FxToggleBar` | Per-track FX control panel with 6 categories, 5 presets each, and dry/wet sliders |
 | `SorceryProgressBar` | Animated progress bar with time-based pacing for long operations |
 | `InstrumentDrawer` | Searchable grid of available VST3/AU instrument plugins |
+| `DownloadPackButton` | Download/verify/extract button for a sample pack; driven through `host.startSamplePackDownload` + `host.onSamplePackProgress` (since 2.8.0) |
+| `SamplePackCTACard` | Empty-state card a generator panel renders when its sample pack is missing or stale; wraps `DownloadPackButton` (since 2.8.0) |
+
+**Waveform / audio-clip toolkit** *(since 2.10.0)* — shared by audio-oriented plugins (stems, recorder):
+
+| Export | Kind | Description |
+|--------|------|-------------|
+| `WaveformView` | component | Static waveform render of an audio file (decodes + draws peaks) |
+| `ScrollingWaveform` | component | Live scrolling waveform for input monitoring / recording |
+| `LevelMeter` | component | Peak/RMS level meter |
+| `OffsetScrubber` | component | Drag-to-offset clip start with beat tick marks + snap |
+| `computePeaks` / `drawWaveform` | util | Peak math + canvas drawing (`WaveformPeaks`) |
+| `analyzeWavPeak` | util | Peak analysis of a WAV (`PeakAnalysis`) |
+| `synthesizeCuePoints` | util | Derive cue points from a clip (`SynthesizeCuePointsOptions`) |
 
 ```typescript
-import { TrackRow, VolumeSlider, PanSlider, FxToggleBar, SorceryProgressBar } from '@signalsandsorcery/plugin-sdk';
+import {
+  TrackRow, VolumeSlider, PanSlider, FxToggleBar, SorceryProgressBar,
+  SamplePackCTACard, DownloadPackButton,
+} from '@signalsandsorcery/plugin-sdk';
+
+// SamplePackCTACard / DownloadPackButton take the `host` the plugin received
+// and drive the download entirely through PluginHost — a plugin never reaches
+// the app's renderer or window.electronAPI to manage its sample pack.
+<SamplePackCTACard
+  host={host}
+  pack={{ packId: 'sas-drum-pack', displayName: 'Drum Sample Library', description: 'Kicks, snares, hats', sizeBytes: 100_934_888 }}
+  status={packStatus}            // 'missing' | 'stale' | 'checking'
+  onDownloadComplete={refresh}   // re-check pack status when the download finishes
+/>
 ```
 
 ### Hooks
@@ -84,13 +111,16 @@ const [prompts, setPrompts, setPromptsForScene] = useSceneState(activeSceneId, {
 
 ```typescript
 import {
-  VALID_INSTRUMENT_ROLES,  // ['bass', 'kick', 'snare', 'lead', 'pad', ...]
-  PLUGIN_SDK_VERSION,      // '1.0.0'
+  PLUGIN_SDK_VERSION,      // '2.8.0'
   FX_CATEGORIES,           // ['eq', 'compressor', 'chorus', 'phaser', 'delay', 'reverb']
   FX_PRESET_CONFIGS,       // Preset definitions for all 6 FX categories
 } from '@signalsandsorcery/plugin-sdk';
 ```
 
+> **Instrument roles are not a static export.** `VALID_INSTRUMENT_ROLES` was
+> removed in SDK 2.0.0 — call `host.getValidRoles()` at runtime instead. The
+> canonical role list lives in the host app, so plugins always see the current set.
+
 ## Quick Start
 
 ### 1. Create the manifest (`plugin.json`)
@@ -264,6 +294,27 @@ Six categories in signal chain order: `eq` > `compressor` > `chorus` > `phaser`
 | `getActiveSceneId()` | Current scene ID (synchronous) |
 | `getSceneList()` | All scenes in the project |
 
+### Sample Packs *(status methods since SDK 2.7.0; download/progress since 2.8.0)*
+Versioned sample packs (drums, instruments, the loop/sample library) install on demand under `<userData>/samples/`. A plugin checks install state to decide between its normal UI and a "download library" CTA, then drives the download **through the host** — never `window.electronAPI`.
+
+| Method | Description |
+|--------|-------------|
+| `getSamplePackRoot(packId)` | Absolute path to the installed pack root, or null if missing/stale |
+| `isSamplePackCurrent(packId)` | True iff the installed version matches this build's expected version |
+| `getSamplePackInstalledVersion(packId)` | Installed version string, or null if not installed |
+| `startSamplePackDownload(packId)` | Trigger download + install; resolves `{ success, error? }` |
+| `onSamplePackProgress(packId, listener)` | Subscribe to `{ status, progress }` updates; returns an unsubscribe fn |
+
+### Deck Playback *(since SDK 2.9.0)*
+The two playback decks: `'loop-a'` (composition / cue, headphones) and `'loop-b'` (performance / main). These route through the **same host path the workstation UI uses**, so the deck mutual-exclusivity rules (the host's PlaybackRuleEngine) are enforced identically — a plugin can't bypass them. Used by playback-driven plugins (e.g. the recorder, which starts loop-a so a take has a backing loop). Available to renderer-hosted plugins.
+
+| Method | Description |
+|--------|-------------|
+| `deckPlay(deckId, contentId?, contentType?)` | Start a deck playing a scene/transition (`contentType` defaults to `'scene'`); resolves `{ success, error?, code? }` |
+| `deckStop(deckId)` | Stop a deck; resolves `{ success, error? }` |
+| `onDeckStateChanged(listener)` | Subscribe to `{ deckId, property, value }` (e.g. `property: 'playing'`); returns an unsubscribe fn |
+| `onAllDecksStopped(listener)` | Subscribe to the global "all decks stopped" event; returns an unsubscribe fn |
+
 ### Transport & Events
 | Method | Description |
 |--------|-------------|
@@ -373,8 +424,8 @@ All errors are `PluginError` instances with a typed `code` property:
 
 - **[Signals & Sorcery](https://signalsandsorcery.com)** — the flagship AI music production workstation
 - **[sas-synth-plugin](https://github.com/shiehn/sas-synth-plugin)** — AI MIDI generation with Surge XT
-- **[sas-sample-plugin](https://github.com/shiehn/sas-sample-plugin)** — Sample library browser with time-stretching
-- **[sas-audio-plugin](https://github.com/shiehn/sas-audio-plugin)** — AI audio texture generation
+- **[sas-loops-plugin](https://github.com/shiehn/sas-loops-plugin)** — Audio loop / sample library browser with time-stretching
+- **[sas-stems-plugin](https://github.com/shiehn/sas-stems-plugin)** — AI audio-from-text generation with stem splitting
 - **[DeclarAgent](https://github.com/shiehn/DeclarAgent)** — Declarative agent + MCP transport for S&S
 
 <p align="center">