# RandomPatternEngine

The RandomPatternEngine is a PatternEngine that generates random patterns.

This PatternEngine generates a pattern of length patternTicks * list size of patternString. For each distinct element in the patternString, a pattern is generated. If a pattern for the same pattern part group has already been generated, a variation of that pattern will be generated (by making a slight change that results in a unique pattern), otherwise a new pattern is generated. For example, if you use "A1,A2,A1,B1", A1 will generate new a random pattern, A2 will create a variation of A1, A1 will use the already generated pattern and B1 will generate a new random pattern. These pattern parts will then be concatenated in this order to form the final pattern. The element "-" can be used to generate an empty pattern (e.g. "A1,-,A2,-").

It builds the pattern by generating notes and pauses with the given probability, where the notes and pauses have a randomly chosen length each, taken from the list of lengths for notes and pauses, respectively, with uniform probability. Notes will have the legato flag set with the given probability. For each note, a random velocity between minVelocity and maxVelocity is generated, with the given correlation to the pitch and the given velocity exponent. After the pattern has been generated, it is checked if its active number of ticks lies in the given range (between minActiveTicks and maxActiveTicks). If not, the pattern is regenerated until this is the case.

Note that the last note's or pause's length of a pattern part will be truncated if it would be longer than the pattern part length. For example, if the pattern part is already 13 ticks long, the maximum length is 16 ticks and a note with 5 ticks was randomly chosen, its length is truncated to 3 so that it can be added to the pattern part without exceeding the maximum length of 16 ticks.

It seems pleasant to a listener to use pattern strings based on the Towers-of-Hanoi method (see http://en.wikipedia.org/wiki/Tower_of_Hanoi). It goes like this: Start with a list of undefined pattern entries which has a length of a power of 2. For every other pattern entry (starting with the first) use A1. For every other remaining free pattern entry (starting with the first free one) use A2. For every other remaining free pattern entry (starting with the first) use A3, etc., until there are no free entries. This is shown in the following table:

Length Pattern string
1 A1
2 A1,A2
4 A1,A2,A1,A3
8 A1,A2,A1,A3,A1,A2,A1,A4
16 A1,A2,A1,A3,A1,A2,A1,A4,A1,A2,A1,A3,A1,A2,A1,A5

A recursive description is as follows: The pattern for length 1 is "A1". The pattern for length n can be obtained by concatenating the pattern for length n/2 with itself and by increasing the number of the last pattern entry (the number after the "A") by 1.

Of course, nice-sounding variations of this pattern are also possible. Time to experiment!

## Configuration

Tag Attribute Type # Example Description
uniquePatternParts - boolean 0/1 false If true, all generated pattern parts are guaranteed to be unique. Defaults to true. Available since version 0.2.
patternTicks - int 1 16 The number of ticks of the generated pattern parts.
ticksPerBeat - int 0/1 4 Specifies how many ticks in the generated pattern are considered to be a beat. If the actual ticks-per-beat value of the song is different from the one provided here, all note/pause lengths are scaled by the appropriate factor. For example, if the pattern uses 4 and the song uses 12, each pattern note/pause length is multiplied by 3. If this tag is not provided, no length scaling is done. Available since version 0.8.
patternString - string 1 A1,A2,A1,B1 A comma-separated list of pattern parts. Each part consists of two characters or the single character "-". The first character is the pattern part group, the second one defines the group part. "-" generates an empty pattern.
noteProbability - int 1 60 The probability (between 0 and 100) of choosing a note (instead of a pause).
legatoProbability - int 1 30 The probability (between 0 and 100) of adding the legato flag to a chosen note.
minVelocity - int 1 4000 The minimum note velocity (between 0 and 32767).
maxVelocity - int 1 32767 The maximum note velocity (between 0 and 32767).
minActiveTicks - int 1 6 The minimum number of active ticks for each pattern part.
maxActiveTicks - int 1 13 The maximum number of active ticks for each pattern part.
offsets - string 1 0,1,2,3,4 The comma-separated list of offsets or wildcard characters. Offsets or wildcards will be chosen uniformly from this list whenever a note is generated.
noteLengths - list of ints 1 1,2,2,3 The comma-separated list of note lengths in ticks. Lengths will be chosen uniformly from this list whenever a note is generated.
pauseLengths - list of ints 1 2,3 The comma-separated list of pause lengths in ticks. Lengths will be chosen uniformly from this list whenever a pause is generated.
pitchVelocityCorrelation - int 1 80 The correlation between pitch and velocity in percent (between 0 and 100). 0 means that the velocity is chosen uniformly between minVelocity and maxVelocity, 100 means that the pitch alone decides the velocity (minVelocity for smallest offset, maxVelocity for the largest offset); these two extremes are interpolated for values between 0 and 100. If the minimum and maximum offset are the same, the pitch part is ignored.
velocityExponent - double 1 3 The exponent used for choosing velocities. 1 is a linear mapping, 2 a square mapping, -1 is a reverse linear mapping, -2 a reverse square mapping, etc.

## Configuration example

``````
<patternEngine class="RandomPatternEngine">
<patternTicks>8</patternTicks>
<patternString><random list="A1,A2,A1,A3|A1,A2,A1,A3,A1,A2,A1,A4"/></patternString>
<noteProbability>90</noteProbability>
<legatoProbability>0</legatoProbability>
<minVelocity>28000</minVelocity>
<maxVelocity>28000</maxVelocity>
<minActiveTicks>6</minActiveTicks>
<maxActiveTicks>8</maxActiveTicks>
<offsets>0,1,2,3,4,5</offsets>
<noteLengths>1</noteLengths>
<pauseLengths>1</pauseLengths>
<pitchVelocityCorrelation>100</pitchVelocityCorrelation>
<velocityExponent>3</velocityExponent>
</patternEngine>
``````