# CrescendoPatternEngine

The CrescendoPatternEngine is a PatternEngine that creates a pattern by taking a prefix pattern, concatenating a repeated pattern a number of times and concatenating a suffix pattern, while changing the velocity of each pattern entry in order to create a crescendo or a decrescendo. A crescendo can be obtained by using a positive velocity exponent (e.g., 1 for a linear velocity increase), a decrescendo by using a negative velocity exponent (e.g., -1 for a linear velocity decrease). This comes in handy in conditional patterns in the DrumSequenceEngine.

This PatternEngine will create a pattern from 3 pattern parts (prefix pattern, pattern and suffix pattern), where the first and the third are optional. The generated pattern is of the form "prefix pattern + repetitions * pattern + suffix pattern" (where "+" means concatenation, "*" means repeated concatenating the given number of times), where the number of repetitions is computed so that the generated pattern has the maximum number of ticks that does not exceed the given number of pattern ticks (the number of repetitions could even be 0). It is an error if the prefix and suffix pattern together have more ticks than the given number of pattern ticks. As an example, consider the prefix pattern having 16 ticks, the pattern having 4 ticks, the suffix pattern having 32 ticks and the number of desired pattern ticks being 128. The pattern will be repeated (128 - 16 - 32) / 4 = 20 times so that the total pattern has a length of 128 ticks. If the pattern were 3 ticks long instead of 4, the optimal number of repetitions would be (128 - 16 - 32) / 3 = 26 (rounded down), which would result in a total pattern length of 126 ticks.

The crescendo or decrescendo will be applied to this concatenated pattern on a per-tick basis. The first tick will be guaranteed to have the minimum velocity (or maximum for a negative exponent), the last tick will be guaranteed to have the maximum velocity (or minimum for a negative exponent). Note that the tick where a note starts will be used to compute the velocity, i.e., if the last note spans more than 1 tick, the last note need not have the maximum/minimum velocity; the last tick would, but the last note starts earlier.

Velocities in the generated pattern will be relative to the current crescendo velocity (interpolated between the minimum and maximum velocity using the velocity exponent) and the velocity specified in the pattern parts. For example, let's assume that your repeated pattern should contain a crescendo of the full velocity and half of the velocity of a note. For this, simply use "0/1:32767,0/1:16384" (or equivalently, "0/1,0/1:16384") in the pattern. Note that this means that the generated velocities can be less than the minimum velocity (if your minimum velocity is "100" and you use "0/1:16384" as the first pattern entry, the resulting velocity in the generated pattern will be "50"). If you don't need this velocity relativity, always use the full velocity in the patterns.

Available since version 0.3.

## Configuration

Tag Attribute Type # Example Description
patternTicks - int 1 64 The number of ticks of the generated pattern. The number of repetitions will be chosen so that the pattern ticks of the resulting pattern will match exactly this number (if this is possible), otherwise the next smaller number will be used.
minVelocity - int 1 4000 The minimum note velocity (between 0 and 32767).
maxVelocity - int 1 32767 The maximum note velocity (between 0 and 32767).
velocityExponent - double 1 3 The exponent used for choosing velocities. 1 is a linear mapping, 2 a square mapping, 0.5 a square root mapping, -1 a reverse linear mapping, -2 a reverse square mapping, -0.5 a reverse square root mapping, etc.
prefixPattern ticksPerBeat int 0/1 4 Specifies how many ticks in this 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 length 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 attribute is not provided, no length scaling is done. Available since version 0.8.
prefixPattern - string 0/1 0/4 The prefix pattern to use. Velocities in this pattern will be relative to the current crescendo/decrescendo velocity.
pattern ticksPerBeat int 0/1 4 Specifies how many ticks in this 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 length 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 attribute is not provided, no length scaling is done. Available since version 0.8.
pattern - string 1 0/1,3/3 The pattern fragment to repeat. Velocities in this pattern will be relative to the current crescendo/decrescendo velocity.
suffixPattern ticksPerBeat int 0/1 4 Specifies how many ticks in this 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 length 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 attribute is not provided, no length scaling is done. Available since version 0.8.
suffixPattern - string 0/1 0/1,0/1,0/1,0/1 The suffix pattern to use. Velocities in this pattern will be relative to the current crescendo/decrescendo velocity.

## Configuration example

``````
<patternEngine class="CrescendoPatternEngine">
<patternTicks><random list="64|128|256"/></patternTicks>
<minVelocity>1</minVelocity>
<maxVelocity>32767</maxVelocity>
<velocityExponent>3</velocityExponent>
<pattern>0/2</pattern>
<suffixPattern>0/1,0/1,0/1,0/1,0/1,0/1,0/1,0/1</suffixPattern>
</patternEngine>

``````