xtc/examples/juce

JUCE + xtc examples

These optional examples use an external JUCE 9.0.4 checkout (qualified revision 3fb5cbc0340758596dac39f7c8de47d562b4896e). JUCE is AGPLv3/commercial; a commercial licence may be required for distribution. Read the integration/license details. Original xtc example code is MIT; JUCE and combined binaries retain their applicable licence obligations. No SDK or linked binary is copied into normal xtc packages.

Build and test (Linux)

Supply JUCE explicitly, for example in /your/path/JUCE. With CMake >= 3.25, Ninja or another CMake backend, a C/C++17 toolchain and JUCE's Linux development prerequisites, configure from the repository root:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release \
  -DXTC_BUILD_JUCE=ON -DXTC_JUCE_ROOT=/your/path/JUCE
cmake --build build --target juce-examples --parallel 3
cmake --build build --target test-juce

The build never downloads JUCE, installs dependencies or copies plugins into user plugin directories. The bridge links the root xtc-core PIC C99 target; there is no recursive Make build or duplicate core archive. test-juce requires Xvfb and runs the processor, JUCE-host, file/editor and xtc C-host checks. Normal builds leave XTC_BUILD_JUCE=OFF and remain JUCE-independent.

Build products (Release):

• build/juce/XtcJuceSynth_artefacts/Release/VST3/xtc JUCE Synth.vst3
• build/juce/XtcJuceSynth_artefacts/Release/Standalone/xtc JUCE Synth
• build/juce/xtc-juce-render_artefacts/Release/xtc-juce-render

Use CMake's -B argument to select another binary directory. Debug builds use Debug in place of Release. The examples can also be configured directly with cmake -S examples/juce -B build/juce-only -DXTC_JUCE_ROOT=/your/path/JUCE -DCMAKE_BUILD_TYPE=Release; that standalone path adds the same root CMake core with GUI/JACK/tests disabled rather than invoking Make. Its artefacts are directly under build/juce-only, without the additional juce directory.

Play and shape Soft Keys

"./build/juce/XtcJuceSynth_artefacts/Release/Standalone/xtc JUCE Synth"

The standalone opens JUCE's audio/MIDI device interface. Select the intended output and MIDI inputs explicitly. Play its on-screen keyboard or a selected MIDI source. Enable Filter + reverb, adjust Tone/Room/Mix, and set Output. Save/load .xtcjuce presets; Panic clears held voices. The native editor is also available when loading the VST3 into a host with editor support. xtc's existing C host supports its default instrument configuration, without the JUCE editor. Building/testing these examples does not open a physical audio device. Running the standalone may open the system default device; hardware playback is not inferred from successful builds.

Render a chord or MIDI file without an audio server

./build/juce/xtc-juce-render_artefacts/Release/xtc-juce-render --render /absolute/new-demo.wav
./build/juce/xtc-juce-render_artefacts/Release/xtc-juce-render --render /absolute/new-song.wav --midi /absolute/song.mid

The output is 48 kHz stereo float32 WAV with filter/reverb enabled and -6 dB output. The default renders a staggered C-major chord. MIDI input is type 0/1 PPQN, including its tempo map, merged stably across tracks. Supported note, CC and bend messages use rounded sample positions; other messages are ignored. Input limits: 4 MiB, 100000 supported events and ten minutes of event timestamps. The renderer allows half a second after the last event, forces all-notes-off, then renders a fixed three-second tail. It does not derive exact plugin tails.

Output is written to a same-directory temporary file and atomically linked to an absent destination. Existing files are preserved, including a concurrent creator at publication. Errors remove the temporary and publish no output. On a machine without an X server, prefix commands with xvfb-run -a.

Inspect/host a trusted VST3

./build/juce/xtc-juce-render_artefacts/Release/xtc-juce-render --inspect-vst3 /absolute/Plugin.vst3
./build/juce/xtc-juce-render_artefacts/Release/xtc-juce-render --host-check "$PWD/build/juce/XtcJuceSynth_artefacts/Release/VST3/xtc JUCE Synth.vst3"

Inspection loads only the named module, enumerates its classes and instantiates them to list parameters and channels. It executes trusted code and is not an isolated scanner. --host-check is specific to the example: it checks five parameters, opaque state restoration and actual MIDI processing through JUCE's VST3 host. These operations do not start an audio device.

Regression checks and an actual editor image

ctest --test-dir build --output-on-failure -R juce
xvfb-run -a ./build/juce/xtc-juce-render_artefacts/Release/xtc-juce-render --snapshot /absolute/new-editor.png

The processor test checks exact C-synth output, note timing, variable blocks, mono/stereo, reset, host/GUI MIDI overflow, preset recovery and effect processing. The snapshot command renders the actual editor to a 1560 × 980 PNG and checks that it can close/reopen without starting audio hardware. It refuses to overwrite a destination. Windows/macOS, alternate plugin formats and physical devices have not been qualified. See Phase 107 for recorded results.