# SerumAlt A wavetable synthesiser experiment built with JUCE 7, CMake and C++17. It targets VST3, AU and Standalone formats, with a workflow inspired by Serum and Vital. This is a fun proof of concept, not a commercial release. Development favors working builds and hands-on listening over elaborate test infrastructure. ![SerumAlt](Source/Resources/logo.svg) ## Features - Two wavetable oscillators, each with 256 frames of 2048 samples, bilinear morphing, seven warp effects plus bypass, and up to 16 unison voices. - Ten factory wavetables, built before audio rendering and kept in memory. - Sine/triangle sub oscillator and white/pink noise. - Two filter slots with seven models, drive, key tracking and serial, parallel or split routing. - Four ADSR envelopes and four free-running or tempo-synced LFOs, including editable step and freehand shapes. - A modulation matrix and four assignable macros. - Nine effect types in eight reorderable slots, with independent state per slot. - A non-destructive RAVE boost for unison, spread, drive, Hyper and reverb. - Sixteen factory presets and a scalable vector GUI with waveform, envelope, LFO and schematic filter previews. ## Architecture ``` Source/ PluginProcessor.{h,cpp} APVTS, presets, state, RAVE/UI-scale glue PluginEditor.{h,cpp} Tabbed GUI, owned controls, scaling, previews Params.{h,cpp} Parameter IDs, indexed groups, enums, mappings Wavetable.{h,cpp} 256×2048 tables, prebuilt by the engine Oscillator.{h,cpp} Morph/warp/unison oscillator SubOscillator.{h,cpp} Sine/triangle sub NoiseOscillator.{h,cpp} White/pink noise Filter.{h,cpp} Seven filter models and cached coefficients FilterBank.{h,cpp} Two slots and routing Envelope.{h,cpp} ADSR with curve LFO.{h,cpp} Continuous phase, sync and shape editing ModulationMatrix.{h,cpp} Connections FXProcessor.{h,cpp} Independent effect state per rack slot EffectUnits/ Hyper, Chorus, Flanger, Phaser, Distortion, EQ, Compressor, Delay, Reverb MacroControls.{h,cpp} Four assignable macros RAVEButton.{h,cpp} Render-time boost, without rewriting parameters SynthVoice.{h,cpp} Per-voice oscillators, filters and envelopes Engine.{h,cpp} 32 voices, MIDI timing, control snapshots, FX GUI/ Controls and previews Presets/FactoryPresets.cpp Factory preset definitions Resources/ SVG assets ``` The engine splits rendering at MIDI event positions and into segments of at most 64 samples. Buffers and effect instances are prepared ahead of time. GUI edits use a control-side copy; audio tries to capture that copy once per host block and keeps its previous settings if an edit is still in progress. ### Behavior notes - Loading a factory preset resets sound parameters before applying its settings, while preserving UI scale. - RAVE is automatable and saved with the project. It changes the rendered sound without moving the underlying knobs; turning it off removes the boost. - Modulation of Master and FX mixes uses global sources directly. Envelope, velocity, note and random sources for these destinations use the newest active voice. - Effect types can repeat across slots. Reordering swaps settings, not running delay or reverb tails. Preconstructing effects uses more memory but avoids allocating effect instances while audio is running. - Filter graphs are schematic previews, not measurements of the nonlinear DSP. - LFO shape data is stored as JSON text inside the project's XML state. Older saves containing only the literal `[Array]` did not preserve the shape data and fall back to the default pattern. ## Building Each script configures and builds its own directory. Production builds disable the QA harness explicitly; the harness script creates no plugin or standalone targets. JUCE 7.0.12 is vendored under `third_party/JUCE` and is not downloaded by the scripts. ### Prerequisites All scripts require Bash, CMake 3.22+, Ninja, and C/C++17 compilers. The harness also uses CTest, included with CMake, when invoked with `--run`. On Linux, install GCC or Clang, `pkg-config`, and the ALSA, FreeType, X11 and OpenGL development libraries. For Debian/Ubuntu: ```bash sudo apt update sudo apt install build-essential cmake ninja-build pkg-config \ libasound2-dev libfreetype6-dev libx11-dev libxcomposite-dev \ libxcursor-dev libxext-dev libxinerama-dev libxrandr-dev libxrender-dev \ libgl1-mesa-dev ``` For Arch/CachyOS: ```bash sudo pacman -S --needed base-devel cmake ninja pkgconf alsa-lib freetype2 \ libx11 libxcomposite libxcursor libxext libxinerama libxrandr libxrender libglvnd ``` JACK is disabled by JUCE's default `JUCE_JACK=0`. Curl and the web browser are explicitly disabled in both project targets. Their development packages are not required for these builds, even though JUCE probes for them during configuration. See `third_party/JUCE/docs/Linux Dependencies.md` if enabling additional JUCE modules. On macOS, install Apple's Command Line Tools with `xcode-select --install`, or select an installed Xcode toolchain. Install CMake and Ninja, for example with `brew install cmake ninja` if Homebrew is already installed. The macOS script checks that `xcrun` can locate the macOS SDK. It must run on a Mac; JUCE does not provide an Apple cross-compilation toolchain for Linux. For Windows cross-compilation, also install MinGW-w64 on the Linux host: ```bash sudo apt install gcc-mingw-w64-x86-64 g++-mingw-w64-x86-64 binutils-mingw-w64-x86-64 ``` On Arch/CachyOS, use `sudo pacman -S --needed mingw-w64-gcc` instead. Keep the native Linux tools and libraries installed: JUCE builds `juceaide` for the host before compiling the Windows plugin. The checked-in `mingw64-toolchain.cmake` selects the `x86_64-w64-mingw32-*` tools and isolates target library searches. ### Production builds | Host | Command | Build directory | Formats | | --- | --- | --- | --- | | Linux | `./build_linux.sh` | `build_linux/` | VST3, Standalone | | macOS | `./build_macos.sh` | `build_macos/` | VST3, AU, Standalone | | Linux targeting Windows x64 | `./build_windows.sh` | `build_windows/` | VST3 only | Default Release artifacts: - Linux: `build_linux/SerumAlt_artefacts/Release/VST3/SerumAlt.vst3` and `build_linux/SerumAlt_artefacts/Release/Standalone/SerumAlt`. - macOS: `build_macos/SerumAlt_artefacts/Release/VST3/SerumAlt.vst3`, `build_macos/SerumAlt_artefacts/Release/AU/SerumAlt.component`, and `build_macos/SerumAlt_artefacts/Release/Standalone/SerumAlt.app`. - Windows: `build_windows/SerumAlt_artefacts/Release/VST3/SerumAlt.vst3`, also copied to `SerumAlt_Windows/SerumAlt.vst3`. The Windows script reuses the toolchain file without rewriting it. It injects `moduleinfo.json` because the cross-compiled JUCE manifest helper cannot run on Linux. Keep this manifest's metadata in sync with `CMakeLists.txt`, `cmake/Plugin.cmake`, and the vendored VST3 SDK. MinGW links its C++ and threading runtimes statically via `-static-libgcc -static-libstdc++ -static`. Before staging, the script verifies the linked module is x86-64, imports none of those MinGW runtimes, and exports the VST3 entry points, so a module that a stock Windows host could not load fails the build instead of being staged silently. macOS builds target the host architecture by default. To request a universal binary: ```bash CMAKE_OSX_ARCHITECTURES='arm64;x86_64' ./build_macos.sh ``` `CMAKE_OSX_DEPLOYMENT_TARGET` can also be passed to that script. Architecture and SDK settings persist in CMake's cache. Use a separate build directory when changing toolchains. These scripts build local artifacts, not signed or notarized releases, and do not install plugins into a DAW's plugin directories. ### Independent QA harness On Linux or macOS, build the console harness without production targets: ```bash ./build_harness.sh ``` Build and run the checks: ```bash ./build_harness.sh --run ``` Or rerun an already-built Release harness: ```bash ctest --test-dir build_harness --build-config Release --output-on-failure --no-tests=error ``` The executable is `build_harness/SerumAltTest_artefacts/Release/SerumAltTest`. It renders the initial state and every factory preset, checks for non-finite samples and aggregate non-silence, and exercises the RAVE toggle. A failed check returns a nonzero exit status. This is a processor integration smoke test, not a complete DSP, GUI, or real-time safety test suite. The harness does not open an editor or audio device, but it still compiles the real processor, editor and JUCE GUI dependencies. Its separate build directory and CMake options isolate its outputs from production bundles; it is not a DSP-only library. It is built and run natively, not as a Windows cross-compiled executable. ### Build options and layout - `BUILD_TYPE` defaults to `Release`; set it to `Debug` for a debug build. - `BUILD_DIR` overrides a script's build directory. Relative paths are resolved from the repository root, even when the script is invoked elsewhere. - `CMAKE_BUILD_PARALLEL_LEVEL` defaults to `2` to limit memory use, including JUCE's configure-time helper build. Increase it if memory permits. - Windows-only `OUTPUT_DIR` overrides the staging directory. For example: ```bash BUILD_TYPE=Debug BUILD_DIR=build_harness_debug ./build_harness.sh --run CMAKE_BUILD_PARALLEL_LEVEL=4 ./build_linux.sh ``` `CMakeLists.txt` owns the shared source list and target configuration. `cmake/Plugin.cmake` owns production formats and platform-specific linking. `cmake/Harness.cmake` owns the test executable and its CTest registration. For direct CMake use, `SERUMALT_BUILD_PLUGIN` defaults to `ON` and `SERUMALT_BUILD_TESTS` defaults to `OFF`. A harness-only configure is: ```bash cmake -S . -B build_harness -G Ninja -DCMAKE_BUILD_TYPE=Release \ -DSERUMALT_BUILD_PLUGIN=OFF -DSERUMALT_BUILD_TESTS=ON cmake --build build_harness --target SerumAltTest ``` An existing CMake cache retains its old option values; changing the defaults does not turn tests off in an old `build/` directory. Use the scripts to set the flags explicitly. An alternate JUCE checkout can be selected with `-DJUCE_ROOT=/path/to/JUCE` when configuring directly with CMake. ### Fresh builds The scripts reuse their build directories without deleting files, resetting Git, or installing packages. Generated `build/`, `build_*/`, and `SerumAlt_Windows/` directories are git-ignored. Leave existing builds intact and select an unused build directory for a fresh configure: ```bash BUILD_DIR=build_linux_fresh ./build_linux.sh ``` Windows staging updates generated files without deleting extra files already in the destination. For a clean distribution bundle, choose unused build and output paths together: ```bash BUILD_DIR=build_windows_fresh OUTPUT_DIR=build_windows_fresh/staged ./build_windows.sh ``` ## License JUCE is licensed separately (see `third_party/JUCE/LICENSE.md`). This project is provided for evaluation/development purposes.