Capabilities Reference¶
A categorized inventory of what Pulp can do today. Each capability lists its current status, the module that provides it, and pointers to relevant documentation and examples.
Status vocabulary: stable | usable | experimental | partial | planned | unsupported
See docs/guides/status-ladder.md for the evidence rule on usable labels.
Known Limitations¶
The following section is auto-generated from the limitations: block of docs/status/support-matrix.yaml. Run python3 tools/docs_generate.py generate to refresh.
Known limitations (21 items across 13 capabilities)¶
| Capability | Limitation | Tracked in |
|---|---|---|
formats.clap |
Only bus index 0 is routed to process(); multi-bus + sidechain not wired to set_sidechain(). | link |
formats.clap |
MIDI vocabulary limited to note on/off; CC, pitchbend, aftertouch, sysex, MIDI 2.0/UMP not routed. | link |
formats.vst3 |
Only bus index 0 routed to process(); multi-bus + sidechain not wired. | link |
formats.vst3 |
setBusArrangements forwards without validating channel counts or reading negotiated layout. | link |
formats.vst3 |
MIDI vocabulary limited to note on/off; controller, poly pressure, note expression not routed. | link |
formats.au_v2 |
Plugin-side parameter changes do not propagate back to the host (no AUParameterListenerNotify). | link |
formats.au_v2 |
MIDI input dead: AUEffectBase has no MIDI routing. | link |
formats.auv3 |
Single input bus; no sidechain support. | link |
formats.auv3 |
MIDI arrives as raw bytes; no type dispatch to note/CC/pitchbend/aftertouch. | link |
formats.auv3 |
iOS validation is stale — no on-device example or AVAudioSession ↔ C++ bridge. | link |
formats.lv2 |
Atom sysex events are not routed — only 1–3-byte short MIDI messages in the atom input sequence reach Processor::process(). | link |
audio_io.wasapi |
Shared mode only; no exclusive mode. | link |
audio_io.wasapi |
Input capture not wired — input_view is always empty. | link |
audio_io.alsa |
No input capture path. | link |
audio_io.alsa |
Hardcoded sample-rate list; no real enumeration. | link |
audio_io.jack |
Dead code — factory always returns AlsaSystem; JACK is never selected at runtime. | link |
midi_io.coremidi |
UMP type-4 (MIDI 2.0 channel voice) packets are silently dropped in the input handler. | link |
midi_io.win32_midi |
Legacy mmeapi; no windows.devices.midi2, no hotplug. SysEx input routed via MIM_LONGDATA; WinRT MIDI runtime still pending. | link |
midi_io.alsa_midi |
Running status not handled; timestamps always 0; no hotplug. SysEx input accumulator landed. | link |
platform_maturity.accessibility.windows |
UIA provider tree and event emission pending (bootstrap in place via #283). | link |
platform_maturity.accessibility.linux |
AT-SPI per-view accessible objects and events pending (bridge bootstrap in place via #280). | link |
Plugin Formats¶
Pulp wraps a single Processor subclass and exposes it through multiple plugin format adapters.
| Capability | Status | Module | Docs | Examples |
|---|---|---|---|---|
| VST3 effect | usable | format | getting-started | pulp-gain, pulp-effect, pulp-compressor |
| VST3 instrument | usable | format | PulpSynth, PulpDrums | |
| Audio Unit v2 effect | usable | format | getting-started | pulp-gain, pulp-effect |
| Audio Unit v2 instrument | usable | format | PulpSynth | |
| CLAP effect | usable | format | pulp-gain, pulp-effect | |
| CLAP instrument | usable | format | PulpSynth | |
| Standalone app | usable | format | pulp-gain | |
| Headless host | usable | format | testing | |
| AU v3 (macOS + iOS) | usable | format | ||
| LV2 (Linux) | experimental | format | ||
| WAM v2 (Web) | experimental | format | web-plugins | |
| WebCLAP (Web) | experimental | format | ||
| AAX native (optional, macOS/Windows) | experimental | format | aax | pulp-gain |
Key headers: pulp/format/processor.hpp, pulp/format/vst3_adapter.hpp, pulp/format/clap_adapter.hpp, pulp/format/headless.hpp
AAX support is intentionally opt-in. It requires a developer-supplied AAX SDK, is not bundled by Pulp, and is unsupported on Linux and Ubuntu.
Known Limitations (plugin formats)¶
These are the production gaps currently tracked per adapter. The authoritative
list lives at docs/status/support-matrix.yaml under format_limitations:;
this section mirrors it for human readers. A status of usable means the
adapter compiles and loads — not that every host-facing feature is wired.
- VST3 — Dynamic bus arrangements limited;
setBusArrangementsonly renegotiates the primary stereo bus today. Tracked: production-readiness workstream 01. - Audio Unit v2 — Outbound parameter changes are not emitted to the host; automation read on AU v2 effects only flows host → plugin. Tracked: workstream 01.
- CLAP — Only the first input bus and first output bus are routed;
declared sidechain or additional buses are ignored.
Processor::set_sidechainis never called from the CLAP adapter. Tracked: workstream 01. - LV2 — Atom sysex is ignored; the
run()loop only promotes 1–3-byte short MIDI messages out of the input atom sequence. Sysex sidecar wiring is tracked under issue #239 (workstream 01). - AAX — Custom editor surface not wired; Pro Tools shows the
auto-generated parameter strip rather than a Pulp ViewBridge editor.
AudioSuite role is declared but not exercised end-to-end. Tracked:
planning/signalgraph-and-bridge-followups-plan.mdrows 7 and 13. - AUv3 — iOS jetsam pressure not modeled; heavy V8 / WebView workloads in the AUv3 process risk termination at ~50 MB. Tracked: workstream 05.
- WAM v2 / WebCLAP — Browser origin sandbox only; no Pulp-side capability
manifest yet. Tracked:
planning/security/container-and-sandbox-strategy-v4.md.
If you hit a limitation not listed, check
planning/production-readiness/01-format-adapters.md and file an issue.
Platforms¶
| Capability | Status | Module | Notes |
|---|---|---|---|
| macOS (ARM64) | usable | platform | Primary development platform |
| Windows | experimental | platform | WASAPI, Win32 MIDI, NSIS installer, CI |
| Linux | experimental | platform | ALSA, JACK, LV2, .deb packaging, CI |
| iOS | experimental | platform | AVAudioSession, AUv3, UIKit, Metal |
| Web / WASM | experimental | platform | WAMv2, WebCLAP, Emscripten pipeline |
Key headers: pulp/platform/detect.hpp, pulp/platform/native_handle.hpp
Audio I/O¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| BufferView (non-owning channel pointer wrapper) | usable | audio | modules |
| Audio device enumeration and streaming (CoreAudio) | usable | audio | |
| Audio file read/write | usable | audio | |
| WASAPI device I/O | experimental | audio | |
| ALSA device I/O | experimental | audio | |
| AVAudioSession (iOS) | experimental | audio |
Key headers: pulp/audio/buffer.hpp, pulp/audio/device.hpp, pulp/audio/audio_file.hpp
MIDI I/O¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| MidiEvent / MidiBuffer | usable | midi | modules |
| MIDI device I/O (CoreMIDI) | usable | midi | |
| MIDI file read/write | usable | midi | |
| Win32 MIDI | experimental | midi | |
| ALSA Raw MIDI | experimental | midi |
Key headers: pulp/midi/message.hpp, pulp/midi/buffer.hpp, pulp/midi/device.hpp, pulp/midi/midi_file.hpp
DSP / Signal Processing¶
All signal processors live in the signal module. Each is a standalone, stateless-friendly C++ class.
| Capability | Status | Module | Examples |
|---|---|---|---|
| Gain | usable | signal | pulp-gain |
| ADSR envelope | usable | signal | PulpSynth |
| Biquad filter | usable | signal | pulp-effect |
| State-variable filter (SVF) | usable | signal | |
| Ladder filter | usable | signal | PulpSynth |
| Linkwitz-Riley crossover | usable | signal | |
| Oscillator | usable | signal | pulp-tone, PulpSynth |
| Delay line | usable | signal | pulp-effect |
| Chorus | usable | signal | |
| Phaser | usable | signal | |
| Compressor | usable | signal | pulp-compressor |
| Noise gate | usable | signal | |
| Reverb | usable | signal | pulp-effect |
| Waveshaper | usable | signal | |
| Panner | usable | signal | |
| Oversampling | usable | signal | |
| FFT | usable | signal | |
| Windowing functions | usable | signal | |
| SmoothedValue | usable | signal |
Key headers: all under pulp/signal/ -- e.g., pulp/signal/compressor.hpp, pulp/signal/oscillator.hpp
DSP DSLs¶
| Capability | Status | Module | Docs | Examples |
|---|---|---|---|---|
| FAUST offline codegen via external compiler + checked-in generated C++ | experimental | dsl | faust guide, pulp-dsl contract | faust-gain, faust-filter, faust-tremolo |
| Cmajor external-toolchain support lane | experimental | dsl | cmajor guide, pulp-dsl contract | cmajor-gain (source-only) |
| JSFX bounded subset support lane | experimental | dsl | jsfx guide, pulp-dsl contract | jsfx-gain, jsfx-tremolo, jsfx-delay (source-only) |
Key headers: pulp/dsl/dsl_processor.hpp, pulp/dsl/faust_processor.hpp
State and Automation¶
| Capability | Status | Module | Docs | Examples |
|---|---|---|---|---|
| ParamValue (lock-free atomic float) | stable | state | modules | all |
| ParamInfo (metadata, range, units) | stable | state | all | |
| ParamRange (normalize / denormalize) | stable | state | ||
| StateStore (centralized parameter registry) | stable | state | all | |
| Parameter groups | stable | state | ||
| Binding (reactive UI-parameter link) | stable | state | ||
| Gesture begin/end (host undo grouping) | stable | state | ||
| State serialization / deserialization | stable | state | ||
| CLAP modulation offset | stable | state | ||
| Change listeners | stable | state |
Key headers: pulp/state/parameter.hpp, pulp/state/store.hpp, pulp/state/binding.hpp
View / UI¶
Core¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| View hierarchy (tree, bounds, hit-testing) | usable | view | modules |
| Flex layout (full CSS Flexbox L1) | usable | view | web-compat |
| Grid layout (CSS Grid L1 — templates, fr, gaps) | usable | view | |
| Theme system (color/dimension tokens, inheritance) | usable | view | design-tokens |
| JS scripting (QuickJS default, V8 and JavaScriptCore available) | usable | view | js-bridge |
| Hot reload | partial | view | Scripted UI live reload is runtime-validated in the standalone macOS lane. Plugin targets can load UI_SCRIPT, but live reload is not yet guaranteed across hosts/platforms. |
| Screenshot capture (headless PNG) | partial | view | Native on mac/iOS; Windows/Linux/Android require a host-registered provider via set_screenshot_provider (#299). |
| Component inspector | usable | view | |
| Animation (FrameClock, ValueAnimation, motion tokens) | usable | view | animation |
| Design export (JSON, SVG) | usable | view | |
| App framework (commands, menus, key bindings) | usable | view | |
Interactive AI design tool (pulp design) |
experimental | view | cli |
Design debug harness (pulp design-debug) |
experimental | view | cli |
Widgets¶
| Capability | Status | Module | Notes |
|---|---|---|---|
| Knob, Fader, Toggle, Checkbox, ToggleButton | usable | view | Full interaction + accessibility roles |
| Label (multi-line, text-transform, decoration) | usable | view | |
| TextEditor (selection, clipboard, undo, IME) | usable | view | |
| ComboBox (dropdown, keyboard nav) | usable | view | |
| ListBox (virtualized, scroll, keyboard) | usable | view | |
| ScrollView (smooth scroll, fade bars) | usable | view | |
| Meter (RMS + peak hold), ProgressBar | usable | view | |
| XYPad, WaveformView, SpectrumView | usable | view | |
| ImageView | usable | view | Placeholder rendering |
| TreeView, Tooltip, Panel, Icon | usable | view | |
| SpectrogramView (scrolling STFT) | usable | view | |
| MultiMeter, CorrelationMeter | usable | view | |
| PresetBrowser (search, categories, nav) | usable | view | |
| MidiKeyboard (display + interaction) | usable | view | |
| WaveformEditor (selection, zoom, regions) | usable | view | |
| EqCurveView (draggable band handles) | usable | view | |
| FileBrowser, FileDropZone | usable | view | |
| GraphEditorView (canvas-based node editor) | usable | view | SignalGraph UI |
| ConcertinaPanel, SplitView, Breadcrumb, Toolbar | usable | view | |
| ColorPicker, Lasso, PropertyList, CodeEditor | usable | view | |
| CanvasWidget (25 draw commands) | usable | view | custom-rendering |
| ModulationMatrix, A/B compare, sortable TableView | planned | view | Production-readiness workstream 07 |
Web-Compat Layer¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| document.createElement / appendChild / remove | usable | view | web-compat |
| element.style (81 CSS properties) | usable | view | web-compat |
| CSS calc() / min() / max() / clamp() | usable | view | |
| CSS unit resolution (em, rem, %, vw, vh) | usable | view | |
| CSS colors (L4: hex, rgb, hsl, 148 named) | usable | view | |
| StyleSheet (class rules, pseudo-classes) | usable | view | |
| Selectors (:nth-child, :not, descendant, child) | usable | view | |
| closest / matches / innerHTML | usable | view | |
| matchMedia (responsive breakpoints) | usable | view | |
| Pointer events (W3C Level 2) | usable | view | js-bridge |
| Gesture events (scale, rotation) | partial | view | macOS trackpad gestures shipped; iOS multi-touch gesture analysis is still incomplete |
Platform Maturity¶
| Capability | Status | Platform | Notes |
|---|---|---|---|
| Cursor management (7 styles) | usable | macOS | NSCursor in mouseMoved |
| Tab focus traversal | usable | all | Tab/Shift+Tab cycles focusable views |
| VoiceOver accessibility | usable | macOS | NSAccessibilityElement + AccessRole |
| VoiceOver accessibility | usable | iOS | UIAccessibilityElement with slider increment/decrement |
| TalkBack accessibility | usable | Android | JNI bridge: role, label, value, table metadata, actions |
| UIA accessibility | partial | Windows | Role map only; provider pending (production-readiness 04) |
| AT-SPI accessibility | partial | Linux | Role map only; D-Bus registration pending (production-readiness 04) |
| IME composition (marked text) | usable | macOS | Full NSTextInputClient |
| Right-click context menu | usable | macOS | on_context_menu + PopupMenu |
| Keyboard shortcuts | usable | all | registerShortcut bridge |
| File dialogs (open, save, folder) | usable | macOS | NSOpenPanel/NSSavePanel |
| Drag and drop | usable | macOS | File + text drop targets |
| Plugin view hosting | usable | macOS/iOS | Native NSView/UIView + Metal. Windows/Linux/Android require a host-registered PluginViewHost::Factory (#299). |
| SDL window host | partial | all | Cross-platform windowing via SDL3. Non-Apple platforms require a host-registered WindowHost::Factory for native presentation (#299); recording-canvas-only for now. |
Key headers: pulp/view/view.hpp, pulp/view/widgets.hpp, pulp/view/theme.hpp, pulp/view/script_engine.hpp, pulp/view/widget_bridge.hpp
Rendering / GPU¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| Dawn/Metal GPU surface | experimental | render | modules |
| Skia Graphite rendering | experimental | render | |
| Dawn/Metal iOS surface | experimental | render | |
| Dawn/D3D12 surface (Windows) | experimental | render | Surface creation implemented, not runtime-validated |
| Dawn/Vulkan surface (Linux) | experimental | render | Surface creation implemented, not runtime-validated |
| CoreGraphics fallback | usable | render | Default render path on macOS |
Key headers: pulp/render/gpu_surface.hpp, pulp/render/skia_surface.hpp
Canvas / 2D Drawing¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| Canvas abstraction (paths, fills, strokes, text) | usable | canvas | modules |
| RecordingCanvas (command capture for testing) | usable | canvas | |
| CoreGraphics backend | usable | canvas | |
| Skia backend | experimental | canvas | |
| SVG rendering | experimental | canvas | |
| Effects (shadow, blur, gradients) | usable | canvas |
Key headers: pulp/canvas/canvas.hpp, pulp/canvas/cg_canvas.hpp, pulp/canvas/skia_canvas.hpp, pulp/canvas/svg.hpp, pulp/canvas/effects.hpp
Runtime Primitives¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| SeqLock (coherent multi-field reads) | stable | runtime | architecture |
| TripleBuffer (latest-value publication) | stable | runtime | architecture |
| SPSCQueue (single-producer single-consumer FIFO) | stable | runtime | |
| ScopeGuard | stable | runtime | |
| Logging | stable | runtime | |
| Assertions | stable | runtime |
Key headers: pulp/runtime/seqlock.hpp, pulp/runtime/triple_buffer.hpp, pulp/runtime/spsc_queue.hpp, pulp/runtime/log.hpp
Events¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| Event loop | usable | events | modules |
| Timers | usable | events |
Key headers: pulp/events/event_loop.hpp, pulp/events/timer.hpp
Platform Services¶
| Capability | Status | Module |
|---|---|---|
| OS detection | usable | platform |
| Clipboard access | partial | platform |
| Native file dialogs | partial | platform |
| Popup menus | usable | platform |
| Native window handle | usable | platform |
Key headers: pulp/platform/detect.hpp, pulp/platform/clipboard.hpp, pulp/platform/file_dialog.hpp, pulp/platform/popup_menu.hpp
OSC (Open Sound Control)¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| OSC 1.0 message encode/decode | experimental | osc | modules |
| UDP sender | experimental | osc | |
| UDP receiver | experimental | osc |
Key header: pulp/osc/osc.hpp
Agent / Automation¶
| Capability | Status | Docs | Notes |
|---|---|---|---|
Repo-level MCP server (pulp-mcp) |
experimental | Project/repo automation server in tools/mcp/pulp_mcp.cpp; not a per-plugin control surface |
|
| Plugin CLI harness pattern | usable | cli | tools/plugin-cli/plugin_cli.hpp; usable for batch/headless workflows, but not auto-generated for every plugin |
| Per-plugin/app MCP control contract | planned | claim-audit-baseline | Active follow-up work rather than a shipped default capability |
Tooling / CLI¶
The pulp CLI wraps common development workflows.
| Capability | Status | Docs |
|---|---|---|
pulp build (configure + build) |
usable | cli |
pulp test (run test suite) |
usable | cli |
pulp validate (pluginval, clap-validator, auval, optional AAX validator) |
usable | cli |
pulp status (show project info, build state, source counts) |
usable | cli |
pulp clean (remove build directory) |
usable | cli |
pulp ship sign |
usable | cli |
pulp ship package |
usable | cli |
pulp ship check |
usable | cli |
pulp docs (local docs lookup) |
usable | cli |
pulp create (new project from template) |
usable | cli |
pulp run (launch standalone binary) |
usable | cli |
pulp upgrade (self-update) |
usable | cli |
pulp doctor (check system dependencies) |
usable | cli |
pulp inspect (component inspector) |
usable | cli |
pulp audit (dependency license check) |
usable | cli |
pulp add (add dependency) |
usable | cli |
pulp cache (build cache management) |
usable | cli |
pulp design (interactive AI design tool) |
experimental | cli |
pulp design-debug (design debug harness) |
experimental | cli |
pulp import-design (import from external design tools) |
experimental | cli |
pulp export-tokens (export design tokens) |
experimental | cli |
pulp ci-local (local CI runner — Mac + VM validation) |
experimental | local-ci |
Shipping / Release¶
| Capability | Status | Module | Docs |
|---|---|---|---|
| Code signing (macOS) | usable | ship | cli |
| Notarization submit/check/staple | usable | ship | |
| DMG creation | usable | ship | |
| PKG installer creation | usable | ship | |
| Combined multi-format PKG | usable | ship | |
| Entitlements generation | usable | ship | |
| Signing identity listing | usable | ship | |
| Appcast feed generation (Sparkle-compatible) | usable | ship | |
| Appcast XML parsing | usable | ship | |
| Ed25519 update signing | planned | ship | API present; CLI hard-fails when invoked until impl lands (#295) |
| Semantic version comparison | usable | ship | |
| Windows code signing | partial | ship | Stub exists |
| Linux packaging | partial | ship | Stub exists |
Key headers: pulp/ship/codesign.hpp, pulp/ship/appcast.hpp
Processor Interface¶
The Processor base class defines what plugin developers implement.
| Capability | Status | Module | Docs | Examples |
|---|---|---|---|---|
| Plugin descriptor (name, category, buses, MIDI flags) | usable | format | getting-started | all |
| Multi-bus I/O (sidechain, aux) | usable | format | pulp-compressor | |
| Effect / Instrument / MidiEffect categories | usable | format | ||
| Transport context (tempo, time sig, position) | usable | format | ||
| Latency reporting | usable | format | ||
| Tail time | usable | format | ||
| Plugin registry (multi-plugin bundles) | usable | format |