Architecture

High-Level Design

The project is organized around a single melody-generation pipeline:

  1. launch the default configuration from code/main.py

  2. parse CLI settings and workflow commands in code/app_cli.py

  3. build a GenerationSettings object

  4. generate rhythm, form targets, and harmony-aware note candidates

  5. score candidates with melodic constraints

  6. export LilyPond and optionally render PDF/WAV assets

Core Modules

melody_engine.structure

Defines the core data model such as melodies, notes, time signatures, form plans, harmony plans, and voice profiles.

melody_engine.theory

Handles key spelling, Roman numeral interpretation, chord-tone targeting, and pitch conversion helpers.

melody_engine.constraints

Contains the soft constraints that shape the generated melody. These include stepwise motion, leap recovery, climax control, form-section behavior, large-leap punishment, and rest usage.

melody_engine.generator

Builds rhythm, motif targets, and note candidates, then performs weighted selection across multiple attempts to keep the best result.

melody_engine.lilypond

Converts melodies to LilyPond and handles rendering to PDF, MIDI, and WAV.

code/app_cli.py

Owns the reusable command-line workflow: parsing, harmony/form setup, render mode, and generation orchestration.

code/main.py

Defines the default constraint stack and acts as the project entry point.

Current Design Priorities

  • form-aware self-similarity

  • harmonic awareness

  • voice-compatible ranges

  • thesis-friendly notation export

  • future compatibility with multi-voice and chorale generation

Chorale Direction

The current codebase already includes voice profiles and a ChoralePlan placeholder so the melody engine can later be extended into SATB-style harmonization without rewriting the entire model.