The PatternHarmonyEngine is a HarmonyEngine which can be configured by providing patterns of chords and chord random tables. The PatternHarmonyEngine will randomly choose one of the chord patterns, will replace each chord random table reference by a randomly chosen chord from the referenced table and will use the resulting chords as the song harmony.

Note that lengths in patterns are provided as number of beats rather than number of ticks. The lengths are therefore independent of the number of ticks per beat. Starting with version 0.3, the lengths can be fractions of beats as well (e.g., "Am/7.5" is a chord that lasts 7.5 beats, which would result in a length of 30 ticks if 4 ticks per beat were used). The chord lengths will be rounded to the nearest integer number of ticks.

An interesting feature is the ability to use positive and negative backreferences (see below). As an example, consider the pattern "Am/4,0/4,0!1/4,$1/4". The first chord will always be A minor, the second one is a randomly chosen chord from chord random table 0, the third one - which is a negative backreference - also is a chord from chord random table 0, but must be different one than chord 1 (which is the second chord, because the offsets are counted from 0), the fourth one - which is a positive backreference - will be the same as the second one. All chords in this example have a length of four beats.

One note about the "minimizeChordDistance" tag/attribute: unless you have specific needs for the chords to have them exactly as provided, you should set this to true. Then, in all SequenceEngines that support it, you can choose whether you want to normalize the chords or not. For example, for arpeggios, chords or pads, do not normalize (usage of chord inversion is fine there). Normalization makes sense for bass lines, which should mostly make use of the root note. Without chord normalization, the root note of a chord can be in any of the chord offsets (due to using first or second chord inversion), rather than only in chord offsets that are multiples of 3, which might sound strange. If you set the setting to true, all inversions specified for the chords in the configuration will effectively be ignored, except for the very first chord.


Tag Attribute Type # Example Description
minimizeChordDistance - boolean 0/1 true If set to true, all chords will be rotated so that their middle pitch is as close as possible to the middle pitch of the very first chord, otherwise the chords are not changed. Defaults to true, because this was automatically done up to version 0.2. Since version 0.4, this value can be overridden per chordPattern tag. Available since version 0.3.
crossoverPitch - int 0/1 6 Defines the starting root pitch where chords are transposed one octave down. Must be between 1 and 12. For example, if this is set to 5, then the root pitches C, C#, D, D#, E are not transposed, everything between F and B is transposed one octave down. This only applies if chords are specified by name rather than in pitch1:pitch2:pitch3 syntax. Defaults to 3 for backwards compatibility. Since version 0.9, this value can be overridden per chordPattern tag. Available since version 0.5.
chordPattern minimizeChordDistance boolean 0/1 false Sets the override for minimizeChordDistance for this chord pattern. If undefined, the global minimizeChordDistance value will be used. Defaults to undefined. Available since version 0.4.
chordPattern crossoverPitch int 0/1 6 Sets the override for crossoverPitch for this chord pattern. If undefined, the global crossoverPitch value will be used. Defaults to undefined. Available since version 0.9.
chordPattern - list of strings 1-n 0/4,1/4,1/4,2/4 The comma-separated list of chord placeholders. Each placeholder is either directly a chord name (e.g., "C" for C major or "Am" for A minor) plus a number of beats or the number of a chord random table (counted from 0) plus a number of beats. For the latter, an extended syntax is supported. Positive back references in the form "$x" (e.g, "$0") will use the x'th chord generated so far (chord offsets are counted from 0). Negative back references in the form "x!y" (e.g., "1!0") will generate a chord from random table x, but a different one than the y'th chord generated so far (chords offsets are counted from 0). If a placeholder starts with a "+" character, this marks the start of a new chord section.
chordRandomTable - list of strings 0-n C,Dm,Em,F,G,Am The comma-separated list of chords. The chord random table can be referenced by its index (counted from 0).

Configuration example

<harmonyEngine class="PatternHarmonyEngine">
  <chordPattern minimizeChordDistance="false">Am/4,-5:-1:5/2,G/2,Dm4/4,-7:-3:4/2,F/2,Am/4,-5:-1:5/2,G/2,Dm4/4,-7:-3:4/2,Em4/2</chordPattern>
  <chordPattern minimizeChordDistance="false">Am/4,Em4/4,-7:-3:4/4,Dm4/4,Am/4,Em4/4,Dm4/4,F/4</chordPattern>

Add new comment