Add generic headless plugin test host (Phase 1: core + audio I/O)

tools/testhost/ is a standalone CLI executable, not a JaySynth-specific
tool: it drives any VST2 plugin offline (no audio device, no GUI event
loop) via JUCE's own format-agnostic AudioPluginFormatManager /
AudioPluginInstance hosting API, so adding another format later (VST3,
LADSPA, eventually LV2) is just another addFormat() call - none of the
host logic changes.

- PluginHost: format-agnostic load/prepare/process/release, parameter
  get/set, and patch/bank state I/O, all delegating straight to
  AudioProcessor. Always queries the plugin's real input/output channel
  counts rather than assuming "0 in" (instrument) or a fixed channel
  layout - the same code path drives JaySynth (0 in/2 out, MIDI-driven)
  and a stereo/mono effect identically.
- AudioInputSource: fills the plugin's input channels with silence
  (default, correct no-op for instruments), a sine tone, white/pink
  noise, or an impulse - what makes the host equally useful for
  effect plugins, which need a real input signal to do anything.
- WavRecorder: records the plugin's actual output channel count to a
  WAV file via WavAudioFormat/AudioFormatWriter.
- main.cpp: CLI (--plugin/--patch/--param/--note/--input/--duration/
  --wav/--sampleRate/--blockSize), with basic NaN/Inf output detection.

Has its own JuceLibraryCode-equivalent package that compiles only the
module amalgams needed for hosting (not juce_audio_plugin_client,
which is the plugin-side VST entry point and would collide with this
executable's own main()), reusing the already-vendored
sdk/juce/JUCE-3.1.1 rather than a second JUCE copy - the host and any
plugin it loads are decoupled at the VST2 ABI, not the JUCE source
level, so this doesn't need to track JaySynth's own future JUCE
version bump.

Verified: builds clean (no new warnings) via
`MAKE_HOME=... make -C tools/testhost`. Smoke-tested against two very
different real plugins:
- build/linux/release/JaySynth.so (0 in/2 out, MIDI-driven): --note
  60 100 --duration 2 --wav produces correct-length, non-silent,
  NaN-free stereo audio.
- /usr/lib/vst/ZamDelay-vst.so (1 in/1 out, real third-party VST2
  effect, no MIDI): --input pink --duration 2 --wav correctly sizes
  input/output to mono and produces non-silent, NaN-free audio -
  proof the host is generic, not JaySynth-shaped.
- /usr/lib/vst/ZamEQ2-vst.so: the host's own NaN/Inf detection caught
  a real NaN in this plugin's default state on first render - exactly
  the kind of regression this tool exists to catch without a GUI.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011dhtwRLARk4eiPngcQykLJ
This commit is contained in:
2026-07-27 19:09:06 +02:00
co-authored by Claude Sonnet 5
parent e9a5784ed1
commit 97b1c34cee
14 changed files with 862 additions and 0 deletions
@@ -0,0 +1,66 @@
/*
AppConfig.h for the testhost tool.
Unlike JaySynth's own JuceLibraryCode/AppConfig.h, this one carries no
JucePlugin_* macros at all - those only matter to the plugin-client side
(juce_audio_plugin_client), which this executable never compiles or links.
*/
#ifndef __JUCE_APPCONFIG_TESTHOST__
#define __JUCE_APPCONFIG_TESTHOST__
//==============================================================================
#define JUCE_MODULE_AVAILABLE_juce_audio_basics 1
#define JUCE_MODULE_AVAILABLE_juce_audio_devices 1
#define JUCE_MODULE_AVAILABLE_juce_audio_formats 1
#define JUCE_MODULE_AVAILABLE_juce_audio_processors 1
#define JUCE_MODULE_AVAILABLE_juce_core 1
#define JUCE_MODULE_AVAILABLE_juce_data_structures 1
#define JUCE_MODULE_AVAILABLE_juce_events 1
#define JUCE_MODULE_AVAILABLE_juce_graphics 1
#define JUCE_MODULE_AVAILABLE_juce_gui_basics 1
#define JUCE_MODULE_AVAILABLE_juce_gui_extra 1
//==============================================================================
// juce_audio_devices flags: none of the real device backends are needed -
// the host never opens a soundcard, it only calls processBlock() directly.
#ifndef JUCE_ALSA
//#define JUCE_ALSA
#endif
#ifndef JUCE_JACK
//#define JUCE_JACK
#endif
//==============================================================================
// juce_audio_processors flags: this is the whole point of this tool - enable
// plugin hosting. VST2 today; VST3/LADSPA/(future LV2) can be added here the
// same way without touching any host source code.
#ifndef JUCE_PLUGINHOST_VST
#define JUCE_PLUGINHOST_VST 1
#endif
#ifndef JUCE_PLUGINHOST_VST3
//#define JUCE_PLUGINHOST_VST3
#endif
#ifndef JUCE_PLUGINHOST_AU
//#define JUCE_PLUGINHOST_AU
#endif
//==============================================================================
// juce_gui_basics flags: no window is ever shown, but the module still needs
// to compile/link (juce_audio_processors.h unconditionally includes it).
#ifndef JUCE_USE_XSHM
//#define JUCE_USE_XSHM
#endif
#ifndef JUCE_USE_XRENDER
//#define JUCE_USE_XRENDER
#endif
#ifndef JUCE_USE_XCURSOR
//#define JUCE_USE_XCURSOR
#endif
#endif // __JUCE_APPCONFIG_TESTHOST__