You need to agree to share your Hugging Face information to access this model

This repository is publicly accessible, but you have to accept the conditions to access its files and content.

Log in or Sign Up to review the conditions and access this model content.

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
Safetensors
Model size
18.4M params
Tensor type
F32
·
Video Preview
loading

Collection including CloudHolic/harmonyrl-smooth

Paper for CloudHolic/harmonyrl-smooth