HarmonyRL Smooth
Chord progressions for a melody, consonant and resolving. A transformer chord policy pretrained on human accompaniments, then fine-tuned with reinforcement learning on a per-note reward while a KL penalty keeps it close to the pretrained policy.
| Model | Style | Time under chords outside the key |
|---|---|---|
| harmonyrl-chromatic | rich reharmonization | 12.9% |
| harmonyrl-smooth | consonant, resolving progressions | 5.5% |
| harmonyrl-base | close to the training data | 6.9% |
Usage
Install the harmonyrl package with
pip install harmonyrl (Python 3.12 or later), then:
from pathlib import Path
from harmonyrl import HarmonyRL
from harmonyrl.ingest import read_lead_sheet
from harmonyrl.render import write_lead_sheet
model = HarmonyRL.from_pretrained("CloudHolic/harmonyrl-smooth")
sheet = read_lead_sheet(Path("melody.musicxml")).sheet
candidates = model.harmonize_sheet(sheet, candidates=3)
write_lead_sheet(candidates[0], Path("harmonized.musicxml"))
# Redraw bars 4 and 5, counted from 0, and keep every other chord
redrawn = model.harmonize_sheet(candidates[0], bars=range(4, 6), candidates=2)
write_lead_sheet(redrawn[0], Path("redrawn.musicxml"))
Parts longer than 32 bars are harmonized in overlapping windows. Defaults such as the
temperature come from generation_config.json; pass temperature=... to override. The
repository README covers file formats, chord symbols
already in a score, and the generation settings.
Training
- Data: Hooktheory melodies with their chords, as released with Sheet Sage (data), 18,937 training segments.
- Pretraining: next chord event given the melody and the chords before it.
- Fine-tuning: RLOO, 200 updates, with a per-note reward after RL-Chord: agreement with the human chord, consonance with the melody, and progression rules. KL coefficient 0.8 to the pretrained policy sharpened to temperature 0.85.
Evaluation
Test split, 2,473 segments, 8 samples each.
| Human | Base | Smooth | Chromatic | |
|---|---|---|---|---|
| Time under chords outside the key | 9.6% | 6.9% | 5.5% | 12.9% |
| Time with 1 chord held beyond 2 bars | 3.2% | 4.1% | 5.3% | 1.4% |
| Disagreement between samples | – | 0.77 | 0.72 | 0.80 |
In blind rankings by 1 listener, the 3 models were not distinguishable once each could be redrawn; single draws of Chromatic had problems more often.
Limitations
- One call harmonizes up to 32 bars. Longer parts go in overlapping windows, so song-level structure such as repeated verses is not modeled.
- An imported score gets 1 key for the whole piece, from its key signature and notes.
- Outputs differ per draw: redraw, or ask for several candidates.
License
CC BY-NC-SA 3.0, following the training data. Data: Donahue, Thickstun, Liang, "Melody Transcription via Generative Pre-Training", ISMIR 2022 (Sheet Sage).
- Downloads last month
- 27