/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`.\n\n| Method | Description |\n|--------|-------------|\n| `getSamplePackRoot(packId)` | Absolute path to the installed pack root, or null if missing/stale |\n| `isSamplePackCurrent(packId)` | True iff the installed version matches this build's expected version |\n| `getSamplePackInstalledVersion(packId)` | Installed version string, or null if not installed |\n| `startSamplePackDownload(packId)` | Trigger download + install; resolves `{ success, error? }` |\n| `onSamplePackProgress(packId, listener)` | Subscribe to `{ status, progress }` updates; returns an unsubscribe fn |\n\n### Deck Playback *(since SDK 2.9.0)*\nThe 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.\n\n| Method | Description |\n|--------|-------------|\n| `deckPlay(deckId, contentId?, contentType?)` | Start a deck playing a scene/transition (`contentType` defaults to `'scene'`); resolves `{ success, error?, code? }` |\n| `deckStop(deckId)` | Stop a deck; resolves `{ success, error? }` |\n| `onDeckStateChanged(listener)` | Subscribe to `{ deckId, property, value }` (e.g. `property: 'playing'`); returns an unsubscribe fn |\n| `onAllDecksStopped(listener)` | Subscribe to the global \"all decks stopped\" event; returns an unsubscribe fn |\n\n### Transport & Events\n| Method | Description |\n|--------|-------------|\n| `onTrackStateChange(listener)` | Real-time mute, solo, volume, pan updates |\n| `onTransportEvent(listener)` | Play, stop, BPM change, position |\n| `onDeckBoundary(listener)` | Loop boundary events (bar, beat, loopCount) |\n| `onSceneChange(listener)` | Scene selection changes |\n| `onEngineReady(listener)` | Engine finished loading tracks |\n| `getTransportState()` | Current playback state snapshot |\n\n### LLM Access\n| Method | Description |\n|--------|-------------|\n| `generateWithLLM(request)` | Generate text/JSON (metered, requires auth) |\n| `isLLMAvailable()` | Check auth + gateway reachability |\n\n### Preset System\n| Method | Description |\n|--------|-------------|\n| `getPresetCategories(pluginName)` | Available Surge XT categories |\n| `getRandomPreset(category)` | Random preset from category |\n| `getPresetByName(category, name)` | Specific preset lookup |\n| `classifyPresetCategory(description)` | LLM-based text-to-category |\n\n### Scene Composition\n| Method | Description |\n|--------|-------------|\n| `composeScene(options)` | Bulk LLM arrangement generation |\n| `onComposeProgress(listener)` | Progress events (planning, generating, complete) |\n\n### Data Persistence\n| Method | Description |\n|--------|-------------|\n| `getSceneData/setSceneData/getAllSceneData/deleteSceneData` | Per-scene key-value storage |\n| `getProjectData/setProjectData` | Project-wide storage |\n| `settings.get/set/getAll/onChange` | Global settings (cross-project) |\n| `getDataDirectory()` | Plugin's isolated data directory path |\n\n### Plugin Presets\n| Method | Description |\n|--------|-------------|\n| `getPluginPresets(category?)` | Get saved presets for this plugin |\n| `savePluginPreset(options)` | Save a preset (name, category, data) |\n| `deletePluginPreset(id)` | Delete a preset |\n\n### File System & Network\n| Method | Description |\n|--------|-------------|\n| `showOpenDialog/showSaveDialog` | Native file dialogs (requires `fileDialog` capability) |\n| `downloadFile/importFile` | Download/copy files to plugin data directory |\n| `httpRequest(options)` | HTTP requests (requires `network` capability with `allowedHosts`) |\n\n### Secure Storage\n| Method | Description |\n|--------|-------------|\n| `storeSecret/getSecret/deleteSecret` | OS keychain encryption, per-plugin scoped |\n\n### Sample Library\n| Method | Description |\n|--------|-------------|\n| `getSamples/getSampleById` | Query sample library |\n| `importSamples(filePaths)` | Import audio files |\n| `createSampleTrack/deleteSampleTrack` | Manage sample tracks |\n| `getPluginSampleTracks()` | List owned sample tracks |\n| `timeStretchSample(sampleId, targetBpm)` | Time-stretch to target BPM |\n\n### Notifications & Progress\n| Method | Description |\n|--------|-------------|\n| `showToast(type, title, message?)` | Toast notification (info/success/warning/error) |\n| `setProgress(trackId, progress)` | Track progress bar (0-100, -1 to hide) |\n| `setStatusMessage(message)` | Accordion header status text |\n| `confirmAction(title, message)` | Confirmation dialog |\n\n## Error Codes\n\nAll errors are `PluginError` instances with a typed `code` property:\n\n| Code | Description |\n|------|-------------|\n| `NOT_OWNED` | Tried to modify a track not owned by this plugin |\n| `TRACK_NOT_FOUND` | Track ID doesn't exist in engine |\n| `TRACK_LIMIT_EXCEEDED` | Plugin has too many tracks (default: 16 per scene) |\n| `NO_ACTIVE_SCENE` | No scene is selected |\n| `ENGINE_ERROR` | Audio engine call failed |\n| `INVALID_MIDI` | Malformed MIDI data |\n| `FILE_NOT_FOUND` | Referenced file doesn't exist |\n| `INVALID_FORMAT` | Unsupported audio format |\n| `PLUGIN_NOT_FOUND` | VST/AU plugin not installed |\n| `LLM_BUDGET_EXCEEDED` | Over daily token limit |\n| `LLM_UNAVAILABLE` | LLM gateway unreachable |\n| `NOT_AUTHENTICATED` | User not logged in |\n| `TIMEOUT` | Operation timed out |\n| `CANCELLED` | User cancelled the operation |\n| `INCOMPATIBLE` | Plugin requires newer SDK version |\n| `CAPABILITY_DENIED` | Plugin lacks required capability in manifest |\n| `SECRET_NOT_FOUND` | Secret key doesn't exist |\n\n## Security Model\n\n- **Ownership scoping** — Plugins can only modify tracks they created (enforced at runtime)\n- **Capability gating** — Network and file system access require manifest declarations\n- **Secret isolation** — Each plugin's secrets are encrypted and scoped per plugin\n- **Track limits** — 16 tracks per plugin per scene (configurable)\n\n## The Signals & Sorcery Ecosystem\n\n- **[Signals & Sorcery](https://signalsandsorcery.com)** — the flagship AI music production workstation\n- **[sas-synth-plugin](https://github.com/shiehn/sas-synth-plugin)** — AI MIDI generation with Surge XT\n- **[sas-loops-plugin](https://github.com/shiehn/sas-loops-plugin)** — Audio loop / sample library browser with time-stretching\n- **[sas-stems-plugin](https://github.com/shiehn/sas-stems-plugin)** — AI audio-from-text generation with stem splitting\n- **[DeclarAgent](https://github.com/shiehn/DeclarAgent)** — Declarative agent + MCP transport for S&S\n\n\n signalsandsorcery.com\n
\n\n## License\n\nMIT\n","readmeFilename":"README.md"}![\"Signals](\"assets/signals-and-sorcery.png\")
\n