VGVG Harmonizer — Complete Guide
Real-time MIDI harmonizer designed for VG Wind Ensemble. Generates scale-aware harmony voices from your wind controller in live performance.
Standard vs Pro
Both versions are standalone Python applications with dark-themed GUI. Choose based on how many sections and scale types you need.
VG Harmonizer
vg_harmonizer.pyThree fixed harmonizer sections with a curated set of jazz/modal chord types. Perfect for most live performance setups.
- 3 fixed sections (H1, H2, H3)
- 9 chord/scale types (Maj7, 7, m7, m, Maj7#11, m7b9, m7b5, sus4, Maj7b5)
- 3 voicing modes: Triad, Close 4, Open 4
- 7 voice filter options
- CC Switch for section switching with hysteresis
- Harmony Volume slider per section
- Melody channel selector
- Master Transpose (±24 semitones)
- Preset save/load (JSON)
- PANIC button (all notes off)
- loopMIDI detection & guidance
- Virtual Out button (macOS IAC)
- Window: 820 × 720 px (fixed)
VG Harmonizer Pro
vg_harmonizer_pro.pyEverything in Standard, plus variable section count, diatonic modes, parallel intervals, CC instrument switching, and legato chord transitions.
- All Standard features included
- 2–5 variable sections (window auto-resizes)
- 8 additional chord/scale types (diatonic, parallel, thirds, sixths)
- Voicing “Off” option per section
- CC Instrument — switches all harmony MIDI channels
- “+ Melody” checkbox — melody follows instrument switch
- Legato Chords — sustains common notes on section switch
- Section colors: Blue, Amber, Green, Purple, Pink
- Window: 660–1100 px wide (scales with section count)
How VG Harmonizer Works
VG Harmonizer sits between your wind controller and VG Wind Ensemble, adding harmony voices in real time.
MIDI Ch 1 (melody)
Scale-aware voicing tables
All voices bundled
Plays melody + harmony
Setup & Requirements
Two ways to run: from Python source, or as a pre-built .exe. The .exe requires no Python install on the target machine.
🐍 Run from Python Source
Install Python 3.x
Download from python.org. During installation, check "Add Python to PATH".
Install loopMIDI (Windows)
Download from tobias-erichsen.de. Create a virtual port named loopMIDI Port 1. macOS users use the built-in IAC Driver.
Run the batch file
Double-click RUN_VG_Harmonizer.bat (Standard) or RUN_VG_Harmonizer_Pro.bat (Pro). Dependencies are installed automatically on first run.
📦 Build & Run .exe
Build the executable
Run BUILD_EXE.bat or BUILD_EXE_Pro.bat. PyInstaller bundles everything into a single .exe in the dist/ folder.
Copy & run the .exe
Move the .exe anywhere — no Python needed. Run directly. The GUI, assets, and all dependencies are embedded.
Still need loopMIDI
loopMIDI (or macOS IAC) must still be running for virtual MIDI routing. The app will detect it and guide you if it's not found.
Windows: loopMIDI Required
On Windows, VG Harmonizer routes MIDI through loopMIDI's virtual port loopMIDI Port 1. If loopMIDI is not running, the app detects this and shows a setup guide. On macOS, use the built-in IAC Driver — click the Virtual Out button in the app to create it.
Python Dependencies
Interface Walkthrough
The UI is organized top-to-bottom. Controls at the top apply globally; the sections area contains per-section settings.
Sections & Controls
Each section is an independent harmonizer that runs simultaneously. Standard has 3 fixed sections; Pro has 2–5 selectable.
| Control | Range / Options | Description |
|---|---|---|
| ON / OFF toggle | On · Off | Enables or disables this section's harmony output. When off, no notes are sent and no CC forwarding happens. |
| Root | C · C# · D · Eb · E · F · F# · G · Ab · A · Bb · B | Sets the key center (tonic) for all harmony calculations in this section. |
| Chord | 9 types (Standard) · 17 types (Pro) | Selects the chord/scale type. Determines which scale intervals are used to harmonize below the melody. See Chord Reference table. |
| Voicing | Triad · Close 4 · Open 4 (+ Off in Pro) | Controls how many harmony voices are generated and their spacing. See Voicing Types section. |
| Voice Filter | Harmony · Voice 2 · Voice 3 · Voice 4 · V 2+3 · V 3+4 · V 2+4 | Selects which of the generated harmony voices are actually sent to MIDI output. "Harmony" = all voices. Does not affect the melody voice. |
| Harmony Volume | 0–200% | Scales the CC2/7/11 forwarding to this section's channel. 100% = full expression. 0% = mute. 200% = doubled expression value (capped at 127). |
| Transpose | Unlimited (− / + buttons) | Transposes all harmony notes in this section by semitones. Useful for octave adjustments — e.g. set to −12 for octave-down doubling. |
| Harmony Ch | 1–16 | MIDI channel used for this section's harmony output. Default: Ch 2 (H1), Ch 3 (H2), Ch 4 (H3), Ch 5 (H4), Ch 6 (H5). Must be unique per section. |
All Chord Types
Standard includes chord types 0–8. Pro adds types 9–16 with diatonic and parallel interval options.
| # | Name | Scale / Mode | Description | Voicing Applies |
|---|---|---|---|---|
| 0 | Maj7 | Ionian (Major) | Major 7th chord tones harmonized below melody. Bright, classic major sound. | ✓ Yes |
| 1 | 7 | Mixolydian | Dominant 7th chord tones. Jazz blues feel. Works great for swing lines. | ✓ Yes |
| 2 | m7 | Dorian | Minor 7th chord tones. Smooth minor sound with a major 6th flavor. | ✓ Yes |
| 3 | m | Natural Minor | Pure minor chord tones. Darker, classical minor — no added 7th. | ✓ Yes |
| 4 | Maj7#11 | Lydian | Lydian mode chord tones. Bright, floating quality with the raised 4th. | ✓ Yes |
| 5 | m7b9 | Phrygian | Phrygian mode chord tones. Exotic, Spanish/flamenco character. | ✓ Yes |
| 6 | m7b5 | Locrian | Half-diminished chord tones. Tense, unstable — good for passing harmonies. | ✓ Yes |
| 7 | sus4 | Suspended | Parallel 4ths and 5ths — uniform, open sound. Consistent intervals regardless of melody note. | ✓ Yes |
| 8 | Maj7b5 | — | Major with flat 5. Uniform intervals — consistent across all melody notes. | ✓ Yes |
| 9 | Dia Maj Pro | Diatonic Major | Strict diatonic harmonization in major scale. No chromatic notes — intervals follow C major scale degrees and shift diatonically. | ✓ Yes |
| 10 | Dia min Pro | Diatonic Minor | Strict diatonic harmonization in natural minor scale. Clean modal minor sound with no accidentals. | ✓ Yes |
| 11 | Par 4th Pro | Parallel | Single voice exactly −5 semitones below melody. Perfect fourth — consistent for all notes. | — Single interval |
| 12 | Par 8ve Pro | Parallel | Single voice exactly −12 semitones below melody. Octave doubling — great for adding depth. | — Single interval |
| 13 | 3rd Maj Pro | Diatonic Major | Diatonic third below in major scale. Alternates between minor 3rd (−3) and major 3rd (−4) depending on scale degree. | — Single interval |
| 14 | 3rd min Pro | Diatonic Minor | Diatonic third below in natural minor scale. Follows minor scale degree structure. | — Single interval |
| 15 | 6th Maj Pro | Diatonic Major | Diatonic sixth below in major scale. Full rich intervals — alternates between major (−8) and minor (−9) sixth. | — Single interval |
| 16 | 6th min Pro | Diatonic Minor | Diatonic sixth below in natural minor scale. Deep harmonic content below melody. | — Single interval |
Choosing a Chord Type
The Root selector sets the key center. The Chord determines which scale is used to pick harmony notes below the melody. For example, Root = F, Chord = m7 gives you F Dorian harmonization — ideal for funk or soul lines. For pop harmony, Dia Maj (Pro) gives perfectly diatonic voice leading in any key.
Voicing Types
Voicings control the number of harmony voices generated and how they are spaced relative to the melody.
Parallel and Interval Chords
For Pro chord types Par 4th, Par 8ve, 3rd Maj/min, and 6th Maj/min — only a single harmony voice is generated regardless of the Voicing setting. The Voicing selector has no effect on these types.
Voice Filter
Controls which of the generated harmony voices are actually sent to MIDI output. Does not affect the melody voice — melody always passes through separately.
| Filter Option | Voices Sent | Use Case |
|---|---|---|
| Harmony | All generated voices (V2 + V3 + V4) | Full harmony — default option. |
| Voice 2 | Highest harmony voice only (closest to melody) | Single-voice harmony line above the bass. |
| Voice 3 | Middle harmony voice only | Inner voice — blends smoothly with melody. |
| Voice 4 | Lowest harmony voice only (furthest from melody) | Bass voice only — deep harmonic foundation. |
| V 2+3 | Top two harmony voices | Tight upper harmony without low voice. |
| V 3+4 | Bottom two harmony voices | Lower harmony pad — useful with Triad/Open 4. |
| V 2+4 | Outer harmony voices (skip middle) | Open, spread sound — melody + outer frame. |
Tip: Combining Sections for Layered Harmony
Use multiple sections with different Voice Filters to build complex arrangements. For example: H1 = Voice 2 (high harmony), H2 = Voice 4 (low bass), H3 = Harmony (full chord pad on a separate MIDI channel). Each section can play a different instrument in VG Wind Ensemble.
CC Switch — Section Switching
Map any MIDI CC to switch between harmonizer sections in real time — using a foot pedal, expression pedal, or breath controller.
How It Works
The CC value range 0–127 is divided equally among all active sections. Only one section is "active" at any time — the active section's settings are used for harmony generation.
Select a CC number
Choose any CC 1–127, or "Off" to disable section switching. CC 2 (Breath) or CC 11 (Expression) are common choices for wind controllers.
Zone labels update
The UI shows the CC value range for each section automatically. Active zone is highlighted.
Hysteresis prevents flickering
A 3-unit buffer at each zone boundary prevents rapid toggling when the CC value sits right at a boundary.
Zone Examples
2 Sections (Pro):
3 Sections (Standard & Pro):
4 Sections (Pro):
Pro v3.0 — Exclusive Features
VG Harmonizer Pro adds three major capabilities beyond Standard: CC Instrument switching, variable section count, and Legato Chords mode.
Variable Section Count
Choose 2 to 5 simultaneous harmonizer sections. The window resizes automatically to fit.
| Sections | Window Width | Harmony Channels |
|---|---|---|
| 2 | 660 px | Ch 2, Ch 3 |
| 3 | 820 px | Ch 2, Ch 3, Ch 4 |
| 4 | 1000 px | Ch 2, Ch 3, Ch 4, Ch 5 |
| 5 | 1100 px | Ch 2, Ch 3, Ch 4, Ch 5, Ch 6 |
CC Instrument — Real-Time Instrument Switching
A second CC Switch that changes the MIDI channel for all harmony voices simultaneously — effectively switching the instrument sound playing the harmony in VG Wind Ensemble.
When switching, all current harmony notes are killed on the old channel and retriggered on the new channel. The 3 instrument zones are fixed at equal thirds of the CC range.
"+ Melody" Checkbox
When enabled, the melody channel follows the CC Instrument switch to the same channel as harmony — melody and harmony play through the same VG Wind Ensemble instrument. When disabled, melody stays on its original channel.
Legato Chords — Smooth Section Transitions
When Legato Chords is enabled, switching sections via CC Switch uses intelligent note diffing instead of retrigger-all behavior.
Without Legato Chords
All current harmony notes receive note-off, then all new harmony notes receive note-on. Creates an audible retrigger/attack on every section switch — good for rhythmic effects.
With Legato Chords
Notes common between old and new section (same pitch + same channel) are sustained — no note-off/note-on. Only changed notes are retriggered. Result: seamless chord transitions with no re-attack on shared notes.
Saving & Loading Presets
Presets save your complete Harmonizer state to a JSON file. Load them instantly for different songs or setups.
💾 Saving a Preset
Click "Save Preset"
A dialog opens asking for a preset name.
Enter a name
The preset is saved as name.json in the presets folder.
📂 Loading a Preset
Click "Load Preset"
A window opens listing all saved presets.
Click a preset
All settings are restored instantly — sections, channels, transpose, CC Switch, and more.
Preset Storage Location
Windows: %APPDATA%\VGHarmonizer\presets\
macOS / Linux: ~/.vgharmonizer/presets/
Each preset is a plain JSON file you can back up, share, or edit manually.
What a Preset Stores
MIDI Routing & Channels
Understanding channel assignments is important for setting up VG Wind Ensemble to respond to the correct MIDI channels.
| Signal | Default Channel | Notes |
|---|---|---|
| Melody (input) | Ch 1 | Fixed. Your wind controller must send on Ch 1. |
| Melody (output) | Ch 1 | Configurable via Melody Ch selector (1–16). Default Ch 1. |
| Harmony H1 | Ch 2 | Configurable in section's Harmony Ch dropdown. |
| Harmony H2 | Ch 3 | Configurable in section's Harmony Ch dropdown. |
| Harmony H3 | Ch 4 | Configurable in section's Harmony Ch dropdown. |
| Harmony H4 (Pro) | Ch 5 | Pro only. Configurable. |
| Harmony H5 (Pro) | Ch 6 | Pro only. Configurable. |
| CC2 / CC7 / CC11 | All active harmony channels | Forwarded from melody input, scaled by each section's Harmony Volume. |
VG Wind Ensemble Setup
In VG Wind Ensemble, set each instrument to respond to the MIDI channel matching the harmonizer section. For example: Trumpet 1 → Ch 1 (melody), Trumpet 2 → Ch 2 (H1), Saxophone → Ch 3 (H2), Trombone → Ch 4 (H3). All signals travel through the loopMIDI virtual port.