Deterministic Melody Generator

A VST3 MIDI instrument plugin that generates deterministic, tempo-synced melodies for Ableton Live and other DAWs.

Architecture

This project uses a two-component design for optimal Ableton Live integration:

Component	Type	Purpose
Deterministic Melody V1	VST3	Original phrase generator
Deterministic Melody V2	VST3	Instrument with A/B/C/D slots + MIDI export
MelodyClipWriter	Max for Live	Writes MIDI directly into Ableton clips

Why Two Components?

• VST3 generates MIDI and works in any DAW
• Max for Live uses Ableton's API to write directly to clips
• Together, they provide a seamless "Generate → Commit to Clip" workflow

For detailed Ableton Live usage, see ableton_workflow.md.

---

Features

Core Engine

• Deterministic: Same parameters + same seed = same melody every time
• Tempo-synced: Generates notes at 1/16 resolution, locked to host tempo
• Musical contour: State machine (UP/DOWN/HOLD/PEAK/VALLEY) creates natural melodic movement
• Mood-based intervals: Low mood = minor/chromatic, high mood = major/consonant

V2 Additions

• A/B/C/D Slots: Generate and compare up to 4 phrase variations
• Playback Modes: Loop, Play Once, Play Once + Stop
• MIDI Export: Drag-and-drop or file export
• Enhanced UX: Status feedback, error handling, slot indicators

Parameters

Parameter	Range	Description
Key	C - B	Root key for the scale
Scale	Major, Minor, Dorian, Phrygian	Scale type
Mood	0 - 1	Dark ↔ Bright (affects interval selection)
Density	0 - 1	Sparse ↔ Dense (note probability)
Randomness	0 - 1	Predictable ↔ Chaotic
Seed	0 - 9999	Deterministic seed for reproducibility
Phrase Length	1 - 16	Number of bars to generate

---

Build Instructions (Windows + Visual Studio)

Prerequisites

1. Visual Studio 2022 (or 2019) with C++ development workload
2. CMake 3.22+ (download)
3. JUCE 7.x (included as submodule)

Step 1: Clone the Repository

git clone https://github.com/YOUR_USERNAME/DeterministicMelody.git
cd DeterministicMelody
git submodule update --init --recursive

Step 2: Configure with CMake

cmake -B build -G "Visual Studio 17 2022"

For Visual Studio 2019:

cmake -B build -G "Visual Studio 16 2019"

Step 3: Build

# Build V1
cmake --build build --config Release --target DeterministicMelody

# Build V2
cmake --build build --config Release --target DeterministicMelodyV2

Step 4: Locate the VST3 Files

build\DeterministicMelody_artefacts\Release\VST3\Deterministic Melody.vst3
build\DeterministicMelodyV2_artefacts\Release\VST3\Deterministic Melody V2.vst3

---

Installation

VST3 Plugin

Copy the .vst3 bundles to your VST3 folder:

Windows (User)

C:\Users\<YourUsername>\AppData\Roaming\Ableton\<Version>\Plug-Ins\VST3

Windows (System)

C:\Program Files\Common Files\VST3

Max for Live Device

Copy M4L/MelodyClipWriter/MelodyClipWriter.amxd to:

[User Library]\Presets\MIDI Effects\Max MIDI Effect\

Note: The .amxd file must be created in Max. See M4L/MelodyClipWriter/README.md for build instructions.

---

Quick Start (Ableton Live)

1. Create a MIDI track
2. Load Deterministic Melody V2 (VST3)
3. Load MelodyClipWriter (Max for Live)
4. Add a synth (Operator, Wavetable, etc.)
5. Set parameters and click Generate
6. Select a clip slot and click Commit to Clip
7. Edit your MIDI in the piano roll!

For detailed workflow, see ableton_workflow.md.

---

Project Structure

DeterministicMelody/
├── CMakeLists.txt              # Build configuration
├── README.md                   # This file
├── ableton_workflow.md         # Ableton-specific workflow guide
├── JUCE/                       # JUCE framework (submodule)
├── Source/
│   ├── V1/                     # Original plugin
│   │   ├── PluginProcessor.cpp/h
│   │   ├── PluginEditor.cpp/h
│   │   ├── MelodyGenerator.cpp/h
│   │   └── ScaleDefinitions.h
│   └── V2/                     # V2 with slots and export
│       ├── PluginProcessorV2.cpp/h
│       ├── PluginEditorV2.cpp/h
│       ├── MelodyGeneratorV2.cpp/h
│       ├── PhraseExporter.cpp/h
│       └── ScaleDefinitions.h
└── M4L/
    └── MelodyClipWriter/       # Max for Live device
        ├── README.md
        └── code/
            └── midi_clip_writer.js

---

Version History

Version	Description
v1.0.0	Original phrase generator (stable)
v2.0.0-alpha	V2 instrument with A/B/C/D slots, MIDI export

---

Troubleshooting

Plugin doesn't appear in Ableton

• Check VST3 folder paths
• Rescan plugins in Preferences → Plug-ins
• Ensure 64-bit version

No sound output

• This is a MIDI effect/instrument — route output to a synth
• Check MIDI routing in track settings

Notes get stuck

• Click Clear in the plugin
• Stop and restart playback

Drag MIDI doesn't work (Ableton)

• Use the MelodyClipWriter M4L device instead
• Drag MIDI works better in other DAWs

---

License

MIT License - Use freely in your projects.

---

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request