commit 5b99f51bd1a3eace64ef969e951216c2f35b1177
Author: Igor Barcik <igor1606553@gmail.com>
Date:   Tue Sep 8 14:47:41 2026 +0200

    first commit

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..fa29201
--- /dev/null
+++ b/README.md
@@ -0,0 +1,105 @@
+# SerumAlt
+
+A modern, commercial-quality wavetable synthesiser plugin (VST3 / AU / Standalone)
+built with **JUCE 7**, **CMake** and **C++17**. SerumAlt is a self-contained synth
+inspired by the workflow of Serum/Vital: two morphing wavetable oscillators, a full
+filter section, four envelopes and LFOs, a modulation matrix, a reorderable FX rack,
+four macros and a one-click **RAVE** button.
+
+![SerumAlt](Source/Resources/logo.svg)
+
+## Features
+
+- **Two wavetable oscillators** — 256 frames × 2048 samples, bilinear morphing,
+  8 warp modes (Bend+/-, Sync, PWM, Asym, Mirror, Fold), unison 1–16 with phase
+  spread/detune/width.
+- **10 factory wavetables** (Basic Shapes, Saw PWM, Square Sync, Triangle Fold,
+  Vowel, Organ, Warm Saw, Digital, Glass, Bass), generated lazily and RAM-resident.
+- **Sub oscillator** (sine/triangle, −2/−1/0 oct) and **noise** (white/pink).
+- **Filter section** — two slots, 7 models (Ladder LP/HP/BP, Diode, Comb, Formant,
+  Screamer), 6/12/24 dB slopes, drive, keytrack, and serial/parallel/split routing.
+- **4 ADSR envelopes** with curve tension and live preview.
+- **4 LFOs** — tempo-sync, 7 shapes (sine/tri/saw/square/S&H/step/freehand),
+  editable step-sequencer and freehand drawing, fade-in and start delay.
+- **Modulation matrix** — direct source→destination connections with bipolar depth.
+- **FX rack** — 9 effects (Hyper/OTT, Chorus, Flanger, Phaser, Distortion, EQ,
+  Compressor, Delay, Reverb) in 8 reorderable slots.
+- **4 macros** (Energy, Width, Drive, Atmosphere) with assignable destinations.
+- **RAVE** — one-click boost (unison, width, drive, OTT, reverb) with snapshot/restore.
+- **16 factory presets** with production-quality values.
+- **Scalable GUI** (75% / 100% / 125% / 150% / 200%) — dark modern vector look,
+  Path-drawn controls, SVG logo/background, real-time waveform/filter/envelope/LFO
+  displays.
+
+## Architecture
+
+```
+Source/
+  PluginProcessor.{h,cpp}     APVTS, presets, state, RAVE/UI-scale glue
+  PluginEditor.{h,cpp}        Tabbed dark GUI, scaling, visualisations
+  Params.{h,cpp}              Parameter IDs, enums, mod sources/targets, mappings
+  Wavetable.{h,cpp}           256×2048 tables + lazy library
+  Oscillator.{h,cpp}          Morph/warp/unison oscillator
+  SubOscillator.{h,cpp}       Sine/triangle sub
+  NoiseOscillator.{h,cpp}     White/pink noise
+  Filter.{h,cpp}              7 filter models
+  FilterBank.{h,cpp}          2 slots + routing
+  Envelope.{h,cpp}            ADSR with curve
+  LFO.{h,cpp}                 Synced LFO + shape editing
+  ModulationMatrix.{h,cpp}    Connections
+  FXProcessor.{h,cpp}         Reorderable rack
+  EffectUnits/                Hyper, Chorus, Flanger, Phaser, Distortion, EQ,
+                              Compressor, Delay, Reverb
+  MacroControls.{h,cpp}       4 assignable macros
+  RAVEButton.{h,cpp}          RAVE snapshot/boost
+  SynthVoice.{h,cpp}          32-voice pool render path
+  Engine.{h,cpp}              Per-block DSP + MIDI + FX + limiting
+  GUI/                        Knob, Slider, ToggleButton, Display, Panel,
+                              Waveform/Filter/Envelope/LFO displays
+  Presets/FactoryPresets.cpp  16 factory presets
+  Resources/                  SVG assets
+```
+
+Key architectural decisions: a fixed 32-voice pool with pre-allocated unison
+sub-voices (max 16/osc), scalar processing (SIMD deferred), control-rate modulation
+(one level, no modulation-of-modulation), and a `juce::AudioProcessorValueTreeState`
+backed parameter store that survives preset save/load together with the mod matrix,
+macro assignments and LFO shape data.
+
+## Building
+
+Requirements: CMake ≥ 3.22, a C++17 compiler, and the Linux dev libraries
+(`libasound2-dev`, `libjack-dev`, `libfreetype-dev`, `libcurl`, X11, OpenGL).
+JUCE 7.0.12 is vendored under `third_party/JUCE`.
+
+```bash
+cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release
+cmake --build build
+```
+
+Outputs:
+
+- `build/SerumAlt_artefacts/Release/VST3/SerumAlt.vst3` — VST3
+- `build/SerumAlt_artefacts/Release/Standalone/SerumAlt` — standalone app
+- (on macOS, the `AU` target is produced automatically)
+
+Cross-compilation for Windows/macOS is handled by JUCE: configure with the relevant
+toolchain and add `-DCMAKE_TOOLCHAIN_FILE=...` as usual.
+
+## Headless QA harness
+
+A console app drives the processor through every factory preset, plays a chord,
+verifies finite (non-NaN) output and non-silence, and exercises the RAVE toggle.
+Build and run with:
+
+```bash
+cmake --build build --target SerumAltTest
+./build/SerumAltTest_artefacts/Release/SerumAltTest
+```
+
+(Disable it with `-DSERUMALT_BUILD_TESTS=OFF`.)
+
+## License
+
+JUCE is licensed separately (see `third_party/JUCE/LICENSE.md`). This project is
+provided for evaluation/development purposes.