armin/xtc
1
0
Fork 0
forked from hanez/xtc
Code Pull requests Activity

Phase 15: host trusted LADSPA processors with persisted graph state

Browse source
This commit is contained in:
Johannes Findeisen 2026-10-27 04:00:27 +01:00
commit f72314b5a3
24 changed files with 1046 additions and 70 deletions
Download patch file Download diff file Expand all files Collapse all files

52
docs/decisions/0009-parameter-processors-and-ladspa.md Normal file
View file

@ -0,0 +1,52 @@
# 0009 — Parameter processors and bounded LADSPA hosting
Status: accepted, Phases 14–15 (2026-10-27).
Native ABI 1 remains compatible. ABI 2 adds explicitly parameter-only configuration,
metadata, validation and sample-offset parameter/MIDI ordering. It is a public C
facility; opaque state and automatic native descriptor registration in project
files remain unsupported. Native instrument and gain examples exercise the
interface before adding a dynamically loaded module lifetime.
Select LADSPA 1.1 for the first external host. Reconsidering the Phase 9 candidates,
LV2 needs RDF/features/URIDs/workers, CLAP needs host scheduling/extension
negotiation, and VST3 needs a separate C++ SDK adapter and release-specific license
review. LADSPA adds a mature Linux C ABI, installed real plugins, straightforward
port negotiation and no RDF/SDK runtime library. Its specification is old and
stable, not an actively expanding instrument/event ecosystem. This trades MIDI,
editors, opaque state and modern automation for a small testable first host.
No general multi-format abstraction is introduced.
Use the installed LGPL-2.1-or-later header, system dynamic loader (`-ldl`), and
user-selected, trusted module files. Neither the header nor plugin binaries are
vendored. Header absence or `XTC_DISABLE_LADSPA` yields unsupported hosting stubs;
metadata can still be loaded/saved. Plugin licenses are independent of the host
and require review before distribution. See LICENSES.md.
Support zero/one mono audio input and exactly one mono output, at most 64 ports
and 16 input controls. Graph stereo consists of independent instances, not a
stereo LADSPA layout. Reject incompatible layouts and identities explicitly.
Control outputs are connected to private storage, not exposed as graph events.
LADSPA has no MIDI or opaque state API: save control values only. Parameter
changes rebuild plans on the control thread; sample automation is deferred to
Phase 16. Rate-scaled bounds are recalculated at compile. Instance history/tails
reset on recompile, not every transport seek (LADSPA has no realtime reset rule).
Latency compensation is unsupported: the supported set is zero-latency amp,
inverter and sine source, not arbitrary lookahead/delay/routing plugins.
Discovery, dlopen, descriptor calls, instantiate, connect, activate, deactivate,
cleanup and dlclose are control-thread operations. Only preallocated copies and
run execute in audio; the usual pending/retired plan handoff owns module handles.
Partial initialization unwinds on the control thread. The host cannot enforce
third-party callback behavior, bound CPU time, catch native crashes/hangs, or
undo memory corruption. There is no sandbox or crash recovery inside the audio
process. A fault may kill xtc; previously saved documents/recording recovery files
remain subject to their ordinary durability guarantees. Test only trusted modules.
Project v5 stores plain identity/layout/control metadata. Parsing never opens
modules. Compile failure preserves the source document and active plan. GUI Open
rejects missing/incompatible modules, retains its current document, and reports
saved module identity/path. Restore the compatible module at that path and retry;
a metadata-only C client can preserve/save the document without the module.
No silent replacement or deletion occurs. Same-ID/label/ports do not authenticate
binaries or guarantee unchanged sound across plugin upgrades.