mel_harm_gen

This tool is part of the MarkMelGen ecosystem / toolchain and is part of the latest MarkMelGen release.

Automates running MarkMelGen toolchain to generate a melody, adds placeholder chord symbols, then runs VeeHarmGen to produce harmonised output.

See the implementation in mel_harm_gen.py.

Quick overview

mel_harm_gen.py automates a three-step pipeline:

1. Generate melody — runs MarkMelGen to create a melody
2. Add placeholders — inserts placeholder chord symbols into the generated MusicXML
3. Harmonize — runs VeeHarmGen to produce harmonized output

The workflow is defined by a JSON5 config file that specifies command sequences for each tool.

Configuration Files (.json5)

The .json5 config files define the pipeline workflow as a flat list of commands. Each file contains:

• MarkMelGen.py commands with options (melody generation parameters)
• VeeHarmGen.py commands with options (harmonization style, instrument choice)
• Optional mel_tran_gen.py commands (range and harmony spacing adjustments)

Example files:

• mel_harm_gen_examples_3_1_0.json5 — comprehensive examples across multiple genres
• mel_harm_gen.json5 — production configuration
• MarkMelGen_repeater.json5 — repeated melody generation

Each command string is executed in sequence, allowing you to:

• Generate multiple melody variations
• Apply different harmonization styles to each melody
• Transpose and adjust ranges as needed

Melody & Harmony Interest Calculators

mel_int_calc.py

Calculates melodic interest scores (0-100) for generated melodies using music-theory-informed metrics:

• Pitch range — evaluates whether range is singable and musical
• Interval variety — assesses step/leap balance and melodic shape
• Rhythmic diversity — scores variety in note durations
• Pitch variety — evaluates use of different pitch classes
• Phrase structure — detects coherent phrases and cadential patterns

Usage: python3 mel_int_calc.py <musicxml_or_midi_file>

harm_int_calc.py

Calculates harmonic interest scores (0-100) for harmonized output using chord analysis:

• Chord vocabulary — richness and variety of chord types used
• Functional harmonic motion — detects meaningful chord progressions
• Harmonic surprise — identifies unexpected but effective harmonies
• Tonal stability vs exploration — measures balance between familiar and novel harmonic regions
• Harmonic rhythm — evaluates pacing and timing of chord changes

Usage: python3 harm_int_calc.py <musicxml_file>

Both tools support multiple calculation methods and produce detailed reports for evaluating and selecting the best generated variations.

Requirements

• Python 3.8+

• Dependencies listed in requirements.txt. Install with:

    pip install -r requirements.txt
  

• Ensure the companion projects are present:

  • MarkMelGen at the path referenced by MARKMELGEN_DIR (default: ../MarkMelGen)
  • VeeHarmGen at the path referenced by VEEHARMGEN_DIR (default: ../VeeHarmGen)

Usage

Basic invocation:

python3 mel_harm_gen.py 

python3 mel_harm_gen.py -c mel_harm_gen_examples_3_1_0.json5

Show version:

python3 mel_harm_gen.py -v

prints mel_harm_gen Version:

mel_harm_gen.py Command-line Usage

python3 mel_harm_gen.py -h

usage: mel_harm_gen.py [-h] [-c CONFIG_FILE] [-v] [-o OVERRIDE]

mel_harm_gen automates generating a melody, adding placeholder chord symbols, producing harmonised output.

It runs MarkMelGen and VeeHarmGen etc with specified configurations.

Example usage:
  python3 mel_harm_gen.py -c mel_harm_gen_examples_3_1_0.json5

options:
  -h, --help            show this help message and exit
  -c, --config-file CONFIG_FILE
                        Path to the JSON5 file containing config (default: 'mel_harm_gen.json5')
  -v, --version         Show the version of mel_harm_gen and exit.
  -o, --override OVERRIDE
                        Override/replace strings in the loaded config (can be used multiple times). Format: 'search_string=replacement_string'. Example: -o rock_pop_0a=folk_1 -o TEMPO_BPM=120.0=TEMPO_BPM=90.0

For detailed help on MarkMelGen or VeeHarmGen options, refer to their respective projects.

Tips & troubleshooting

• If no .mxl appears after MarkMelGen runs, check the MarkMelGen output/ directory and logs (MarkMelGen prints logs to its log/ or output/ locations).
• Ensure music21 is configured correctly (MXL writing/reading).
• Paths are relative by default (see MARKMELGEN_DIR and VEEHARMGEN_DIR); adjust if your layout differs.
• Example config files are in the repo root: mel_harm_gen_examples_3_1_0.json5, mel_harm_gen_test.json5, etc.

Example leadsheet and demo Workflows

For Short and Long mel_harm_gen workflows, see the MarkMelGen README.

Produce a leadsheet (PDF or printable MusicXML)

• Preferred: open final MusicXML in MuseScore (GUI) and Export → PDF.
• Quick steps:
  • Locate final MusicXML in VeeHarmGen\output.
  • Open in MuseScore and File > Export PDF/PNG.
    
    
• If you have several versions of a song then score each section out of a 100 and get a total score to pick best version, e.g.:
  • soft_rock_0--Echo_in_the_Room-C-bpm130-ts4_4-C3_G5-wpch-soft_rock_0-ran-95-v01 section scores 50 + 60 + 60 + 60 + 70 + 60 = 360
    
    
• Change tempo. In MuseScore, at beginning of song, double click on BPM and type desired tempo. Play the chorus slower, normal, faster, (e.g., 96 / 102 / 108 BPM). Choose the one where the song breathes but doesn’t sag. It feels relaxed, not rushed.
• File > Export , musicxml, uncompressed e.g.
  • soft_rock_0--Echo_in_the_Room-C-bpm124-ts4_4-C3_G5-wpch-soft_rock_0-ran-95-v02.musicxml
    
    
• This is also an opportunity to correct bad notes and chords.
  • In Musescore play all the way through, note bars with bad notes/chords e.g. # bar x,y,z.
  • If a note is bad, click on the note, press cursor up or down until good, click on score background.
  • If a chord is bad, double click on the chord, type the new chord, click on score background.
  • If you need help with choosing alternative chords, go to the VeeHarmGen and search for AlternativeChords.
    
    
    • INTRO bar #
    • VERSE bar #
    • PRECHORUS bar #
    • CHORUS bar #
    • BRIDGE bar #
    • SOLO bar #
    • OUTRO bar #
    • repeat note/chord corrections as required for repeated sections
      
      

If the pitch range of the song is outside the range of your singer then either

1. use mel_tran_gen.py to move the melody into the correct register in a mel_harm_gen config or
2. manually transpose the song in MuseScore, File > Open e.g.

• rock_pop_0a--Dream_With_Your_Eyes-C-bpm140-ts4_4-C3_D6-wpch-rock_pop_0a-nth-0-v01.musicxml
• The pitch range of the song is C3_D6

- The Modal range of the singer (from free Piano tuner app) is E2 (82.41 Hz) on guitar bottom E string open - C4 (261.6 Hz) on guitar 1st Fret, B String - The Falsetto range of the singer is C4 (261.6 Hz) on guitar 5th Fret, G String - C5 (523.2 Hz) on guitar 8th Fret, top E String - The Whistle range of the singer is C5 (523.2 Hz) on guitar 17th Fret, G String - G5 (784 Hz) on guitar 20th Fret, B String (the Whistle range is weak)

- The usable range of the singer is **E2 to C5**, with a bit of Whistle room to G5. After tranposing the whole song down 1 octave, C2 would be too low, and D5 would be too high, so manually transpose each section (if that doesn't work manually transpose each bar / note !) e.g. - To transpose the notes down an actual octave (Changes playback AND written pitches.) - Select the notes (or press Ctrl+A to select all). - Go to Tools → Transpose…, By interval, Perfect octave, Down, OK. - Test the new range by getting the singer to use a neutral vocalization technique that strips away words to focus purely on pitch and range. By singing ‘la la la la’ instead of the lyrics, you can quickly gauge if the tune is too high or too low.

- INTRO phrase 1, 1 octave down - VERSE phrase 1-3, 1 octave down - PRECHORUS NA - CHORUS 1 octave down - BRIDGE phrase 4, 1 octave down - SOLO no transpose required - OUTRO phrase 1, 1 octave down, phrase 2, 1 octave up - repeat transpositions for repeated sections

• File > Export , musicxml, uncompressed e.g. v03.musicxml
  
  
• File > Export , MIDI (required for some demo tools) e.g. v02.mid
• To remove chords, reopen .mid in MuseScore , click on first piano treble clef bar with chords, shift click on last piano bass clef bar. Right click, Clear Bars. Export, MIDI.

Produce a demo recording (audio)

• Option A — Melody and chords demo. MuseScore export (easy): open MusicXML → File → Export → WAV/MP3.
  
  

• Option B — Backing track demo. Musicxml and mid → JJazzLab → mp3

  • Create a backing track using JJazzLab File > Import Songs... .musicxml.
  • Click on plus in a circle icon to add a User-defined track, Melodic, drop .mid, Humanize, check tempo matches Musicxml. Click on track 1 melody instrument, Grand Piano, select instrument.
    
    
  • Click on blue rhythm name e.g. 16BeatBallad, deselect "Use tempo of rhythm", double click on the desired rhythm for the given time signature. Click > or press Spacebar to play.
  • Before trying another rhythm, click on |< or tap F1 a few times to return to previous section until back to the beginning to select next rhythm to try.
  • It may help to click on tempo column to find a rhythm that matches your tempo.
    
    
  • Here are some rhythms on JJazzLab5 with extra jjazzlab_user_styles:

    • 3/4 Rhythms: FastFolkWaltz, JazzWaltzFast, JazzWaltzMed, JazzWaltzSlow, AcousticBallada, AmazingGospel, CountryWaltz, Flamenco, MariachiWaltz, GuitarSerenade, PopWaltz, 9-8Waltz, SwingWaltz, ChristmasWaltz, GospelSisters, JazzWaltz4, JazzWaltzFast, FrenchMusette.

    • 4/4 Rhythms: extended: 16beat, Catabile, JazzRock, LingusFunk, SambaCity. standard: 16BeatBallad, 6-8ModernBallad, 8Beat, 90'sGuitarPop, 90'sOrqRockBld, AcousticRock, AfroCuban, BluesRock, BossaNova2, BritPopSwing, Calyspso, ChaCha, ClassicHipHop, ClubBeat, Cool8Beat, CoolJazzBallad, DiscoHouse, EasyAcJazz, EtherealSynth, FastJazz, FolkBall, FranklySoul, FunkPopRock, FunkyHouse, GuitarPop, HappyReggae, JazzVocal, KoolFunk, Mambo5, MediumJazz, ModChartPop, ModPickin!, MrMac'sBlues, PopBossa1, PopRumba, PopShuffle1, RockShuffle, Soul, SoulBeat, SoulR&B, StandardRock, Swing1, USChartHit, UrbanFunk, 16Beat, 30'sBigBand, 40'sBigBand, 6-8SlowRock1, 6-8SlowRock2, 60's8Beat, 60'sGuitarPop.S652, 60'sRock1.S114, 60'sRock2.S601, 60'sRock3.S525, 70's8Beat.S782, 70'sDisco1.S515, 70'sDisco3.S722, 8Beat.S096, 8BeatAdria.S460, 8BeatBallad.S686, 8BeatBallad2.S508, 8BeatModern.S079, AcousticJazz.S351, AcousticJazz1.S563, BandaPolka.S179, Beguine.S617, BigBandBallad.S620, BigBandFast2.S611, BigBandMed1.S206, BigBandMed2.S613, BigBandSalsa, BigBandSamba.S206, BigBandShuffle.S574, BlueberryBlues.S559, BluesBallad.S530, BluesShuffle.S606, BoogieWoogie.S600, BossaNova, BossaNova1.S632, BossaNova2.S469, BrazilianSamba.S752, BritPop.S602, BritPopSwing.S726, Caribbean.S413, Carnival.S507, CatGroove.S609, Charleston.S248, ChartBallad.S859, Chillout.S502, ChristmasSwing1.S418, ClassicBigBand.S732, ClassicHipHop.S525, ClassicHipHop, Clubdance2, ClubHouse.S484, ComboBoogie.S725, ComboTwist.S725 Cool8Beat.S737 CoolBlues.S218 CoolJazzBallad.S738 CoolPop CopaCabana Country Country2-4.S651 Country8Beat.S650 CountryPop.S631 CountryRock.S644 CountrySwing1.S535 CountryWaltz.S472 CrocoTwist.S606 CubanBolero.S711 Dance DiscoLatin_P2k1.s643 DiscoPhilly DiscoPhilly1.S494 Dixieland1.S240 Dixieland2.S728 DreamDance.S297 EasyBallad.S310 EasyListening.S718 ElectricJazz.S598 EuroTrance.S303 FastJazz.S741 FrenchHouse.S750 GermanMarch1.S748 Groundbeat.S304 GuitarBallad.S093 GuitarPop.S557 GypsyPop.S093 Hawaiian.S710 HeartBeat.S119 Ibiza2002.S340 J-PopHit1_TyPrems.S851 JapaneseFolk.S684 JazzBluesSimple.S740 JazzGtrTrio184 9K.s460 JazzPop.S563 JazzSamba.S346 JazzWaltzFast.S499 JazzWaltzMed.S351 JazzWaltzSlow.S423 Jig.S943 JumpJive.S610 Latin Latin-a-GoGo.S629 LatinDisco1.S629 LatinDisco2.S643 LimboRock.S749 Live8Beat.S119 LoungePiano.S523 Mambo5.S722 MediumJazz.S737 Merengue.S635 MidnightSwing.S738 ModCntryBld1.S714 ModCntryBld2.S093 MoonlightBallad.S423 MotorCity.S489 Movie&Show MoviePanther.S732 NewCountry.S472 OrchBigBand1.S795 OrchBigBand2.S731 OrchestraSwing.S613 PianoBallad.S530 Pop&Rock PopBossa.S084 PopBossa1.S629 PopLatin.S637 PopNewAge.S850 PopR&B PopRumba.S625 PopSamba.S630 PopShuffle1.S552 PopShuffle2.S577 R&B Ragtime1.S010 Ragtime2.S010 Rock&Roll1.S601 Rock&Roll2.S610 Rock&RollShfl.S605 RockBallad.S130 RocknRoll RockShuffle.S547 RockShuffle RomanticBallad.S725 RumbaIsland.S705 Salsa.S639 Samba.S722 SambaCity213.s460 ScottishReel.S943 SheriffReggae.S647 Slow&Easy.S738 SlowBossa.S642 SlowBossa2.S460 SlowJazz SoftRock.S092 SouthernRock.S110 StandardRock Swing&Jazz Swing1.S737 Swing2.S249 Swingin'BigBand.S368 Swingin'Boogie.S595 SynthPop Tarantella.S661 TechnoParty.S527 Tijuana.S638 Twist.S599 Unplugged2.S534 USMarch.S659 WildWest.S536 World Zirtaki.S118 Zouk

    • Check tempo at top is correct.
      
      

    • Click on speaker icon above first User track to mute melody.

    • File > Export to audio file e.g. backing.mp3
      
      

    • Click on headphone icon above first User track to solo.

    • File > Export to audio file e.g. melody.mp3
      
      

• Option C — Vocal and backing track demo. Create vocal (real or synthetic) and mix with backing track

  • record a real vocal in a DAW (Audacity) or
    
    

  • create a synth vocal

    • Sinsy click English, choose MarkMelGen output (music)xml File, Send, Synthesizing …, right click download .wav or
      
      
    • Synthesizer V Studio Basic and voices
      • File > Import melody.mid. If Clean Up offered click Yes
      • In piano roll, Transport > Seek to beginning, right click on bar 1, set Tempo and Time Signature
      • select Voice e.g. Tsuramake Maki / ANRi / Eleanor Forte / ASTERIAN / Ritchy
      • adjust voice parameters
        
        
      • After making final choice of Voice, to change pronunciation,
        • at top of piano roll, ensure
          • Freehand tool:ON
          • Note Editing mode:ON
          • Playback: keep the playhead after pausing
        • Click on desired start bar number
        • Play (spacebar toggle) until incorrect phoneme, Pause (spacebar toggle)
        • double click on higher phoneme in white text (green if edited),
        • note bar, bad phoneme, good phoneme, example lyric e.g. 36, l ay, l ey, soft-[ly]
        • Select bad phoneme then type good phoneme, click on background to exit edit
          
          
      • Example bad phoneme, good phoneme, example lyric
        • A
        • ey v iy, ae v, [av]-en-ue
        • k aa r, k ae r, [ca]-rry
        • g ax n, g ah, [go]-nna
        • ae l, ao l, [al]-ways
        • E
        • v ax l, v eh l, [vel]-vet
        • m eh r, m er, su-[mmer]
        • l aa, l ey, [la]-zy
        • t ay, t ey, ci-[ty]
        • I
        • w ay n d, w ih n d, [wind]
        • ay z, ih z, prom-[ise]
        • r ey, r iy, [re]-frain
        • p l ay, p l iy, Sim-[ply]
        • O
        • U
        • m aa v, m uw v, [mov]-ing
        • Also see Phoneme Reference
        • Alteratively try another dictionary
        • or search the user forum
          
          
          
      • View > Render Panel, set Destination folder, Bounce to files e.g. voice.wav
      • If phonemes were edited then File > Save in examples\Synthesizer_V
        
        

  • mix backing track and vocal and export final audio in a DAW (Audacity)

    • Open Audacity,

    • on the timeline right click select Beats & Measures. In bottom left adjust tempo and time signature.

    • File → Import → Audio… and import backing melody and voice files.
      
      

    • Drag voice track to match vox in point. It may help to View > Snapping Toolbar, Select Snap and desired snap point e.g. Bar or 1/4.

      • Select your vocal track (click the waveform title). Go to Effect > EQ > Bass and Treble, adjust EQ. Go to Effect > Volume and Compression > Compressor. Presets & Settings, Factory Presets , e.g. Lead Vocals, Apply
      • For voice track, Effects, Add Effect, Audacity, Reverb, Solo, click effect name, Presets & Settings, Factory Presets , e.g. Medium Room.
        
        

    • View > Mixer, Use the Gain slider (on the left of each track) to set relative volumes.

    • Split & Mute Vocal during Solo : Select the section of the vocal track where the solo happens, eg bar 99 - 114. Go to Edit → Audio Clips → Split (or press Ctrl+I / Cmd+I). With the solo section highlighted, press: Ctrl+L / Cmd+L → Silence Audio. Similarly for melody track, split & mute as desired.
      
      

    • For a fade out: Near end of track at top, left click and drag to end of track then drag down so all tracks are selected. Effects > Fading > Fade Out. To remove the count in select and split and mute. Simarly, consider a fade in if required.

    • Select all the count in, split and mute.
      
      

    • Use the Limiter, Select the whole project, Ctrl+A (Windows) or Cmd+A (Mac). Go to Effect > Volume and Compression > Limiter… Presets and Setting > Factor Presets > Master Limiter , Apply.

    • File → Export Audio → Export as demo.mp3

Credits

The vocal demonstrations in the examples/demos folder were created using Synthesizer V Studio Basic (v1.11.2) by Dreamtonics.

Voice Databases

• Tsurumaki Maki (Lite) — © Dreamtonics / AH-Software
• ANRI (Lite) — © Dreamtonics
• Eleanor Forte (Lite) — © Dreamtonics
• ASTERIAN (Lite) — © Eclipsed Sounds
• Ritchy (FLT) — © Dreamtonics

All voice databases are used under their respective licenses for non-commercial demonstration purposes.
These samples are for educational/demo use only and are not intended to imply endorsement by the original voice providers.

Project files referenced

• Script: mel_harm_gen.py
• Example configs: mel_harm_gen_examples_3_1_0.json5, mel_harm_gen.json5
• Requirements: requirements.txt
• Examples folder: examples/

License & attribution

See repository-level license.