====== L-system Wrappers =======

** Overview: ** This tutorial teaches you how to use L-system wrapper functions. 

**Things To Note:** This tutorial assumes you have already installed Konduktiva successfully using the [[https://github.com/renickbell/konduktiva|Konduktiva installation]] instructions and have read through and understood the [[:first_steps|first steps tutorial]]. The tutorial also assumes 2 things. One, Konduktiva has been assigned to the //K// variable. Two, user created a Musical Environment using the //setUpMusicalEnvironment// function using //K.defaultConfigurationObject// as the first argument and //'exampleMidiPlayer'// as the third argument then, assigned the output to the //e// variable.
<code javascript>
const K = require('konduktiva')
let e = K.setUpMusicalEnvironment(K.defaultConfigurationObject,4,'exampleMidiPlayer')
</code>

<markdown>
I will list all the functions here. They all have the same syntax so for all functions refer to this documentation. All the functions use variousLsystems function. See docs for variousLsystems [[music_generation#variouslsystems|here]].

The wrapper functions are lsystemNoteMap, lsystemRhythmMap, lsystemChordMap, lsystemGeneralMap, lsystemLegatoMap, lsystemNoteDurationMap, lsystemOctaveMap, lsystemVelocityMap, lsystemPolyphonyMap, lsystemMaskMap, lsystemModeMap, lsystemModeFilter, and lsystemRootMap.

## L-system function wrapper Syntax 
These are functions that will return the information in a form that the MusicalEnvironment will accept for each specific case (QuantizedMap usually). The lsystemNoteMap function will be used as an example here.

### Syntax 
```
K.lsystemNoteMap(baseName,n,patternLength,rules,generations,replacementValues,inputString, allChars = getAllAlphabets(), rhythmMap, e)
```

### Parameters
#### baseName: String
The baseName of the variables in the Object returned by variousLsystems. It will also be used if the returned item needs a name. RhythmPattern is an example of this.

#### n: Number
Number of variables variousLsystems should should generate.

#### patternLength: Number
Total value of each array returned by variousLsystems.

#### rules: Object{}
Rules for generating an L-system

#### generations: Number
The number of generations the L-system should generate for.

#### replacementValues: Number[]
The values each L-system letter should be replaced with.

#### inputString: String
The string that the L-system should start with. The L-system axiom.

#### allCharas: String[]
All the characters the L-system uses.

#### rhythmMap: QuantizedMap or String
If string, it should be the location/name of a rhythmMap. A MusicalEnvironment that contains that rhythmMap should be provided as last argument.

If QuantizedMap provided, it can be both the top level rhythmMap where the values are other QuantizedMap or just a normal QuantizedMap.

#### e
MusicalEnvironment. Fill in when filled in location of rhythmMap or when using the modeMap wrapper.

## Examples
For these examples, the aeolian chord progression will be used. The variables that are repeatedly used will be defined here:
```
let allChars = ['a', 'b', 'c']
let rules = {'a': 'ab', 'b': 'cc', 'c': 'abc'}
let startingLetter = 'a'
let rhythmMap = e.rhythmMaps.straight
```

The audios provided will be the audio produced by 1 Player that has been created with defaultConfigurationObject. The audio example will of the Player with 1 difference/modification from the original. So, after each modification, the player is reset. This is the line of code we used to create the 1 Player:
```
let e = K.setUpMusicalEnvironment(K.defaultConfigurationObject,1,'exampleMidiPlayer')
```
This is the line of code used to play the Player:
```
e.stop('exampleMidiPlayer1')
```

Here is the audio from the original player without any modifications.

[./lsystem-wrapper-basic-no-config-audio.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-basic-no-config-audio.wav)

### noteMap
```
e.noteMaps.aeolianFiltered = await K.lsystemNoteMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.noteMap = 'aeolianFiltered'
```

[./lsystem-wrapper-noteMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-noteMap.wav)

### lsystemRhythmMap
```
e.rhythmMaps.aeolianFiltered = await K.lsystemRhythmMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.rhythmMap = 'aeolianFiltered'
```

[./lsystem-wrapper-rhythmMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-rhythmMap.wav)

### lsystemChordMap
```
e.chordMaps.aeolianFiltered = await K.lsystemChordMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.chordMap = 'aeolianFiltered'
e.players.exampleMidiPlayer1.action = 'sendChordMidiInfo'
```

[./lsystem-wrapper-chordMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-chordMap.wav)

### lsystemGeneralMap
Can be applied to any map that use numbers as values. Many function use this under the hood. Here an example is made using legatoMaps.

```
e.legatoMaps.aeolianFiltered = await K.lsystemGeneralMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.legatoMap = 'aeolianFiltered'
```

[./lsystem-wrapper-legatoMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-legatomap.wav)

### lsystemLegatoMap

```
e.legatoMaps.aeolianFiltered = await K.lsystemLegatoMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.legatoMap = 'aeolianFiltered'
```

[./lsystem-wrapper-legatoMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-legatomap.wav)

### lsystemNoteDurationMap
Not in use currently the duration of a note is being handled by legatoMap and rhythmMap.

```
e.noteDurationMaps.aeolianFiltered = await K.lsystemNoteDurationMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.noteDurationMap = 'aeolianFiltered'
```

### lsystemOctaveMap
```
e.octaveMaps.aeolianFiltered = await K.lsystemOctaveMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.octaveMap = 'aeolianFiltered'
```

[./lsystem-wrapper-octaveMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-octaveMap.wav)

### lsystemVelocityMap

```
e.velocityMaps.aeolianFiltered = await K.lsystemVelocityMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values.map(x => {return x * 13}), startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.velocityMap = 'aeolianFiltered'
```

[./lsystem-wrapper-velocityMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-velocityMap.wav)

### lsystemPolyphonyMap

```
e.maxPolyphonyMaps.aeolianFiltered = await K.lsystemPolyphonyMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.polyphonyMap = 'aeolianFiltered'
```

[./lsystem-wrapper-polyphonyMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-polyphonyMap.wav)

### lsystemMaskMap

```
e.maskMaps.aeolianFiltered = await K.lsystemMaskMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap)
e.players.exampleMidiPlayer1.maskMap = 'aeolianFiltered'
```

[./lsystem-wrapper-maskMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-maskMap.wav)

### lsystemModeMap

```
e.modeMaps.aeolianFiltered = await K.lsystemModeMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap, e)
e.players.exampleMidiPlayer1.modeMap = 'aeolianFiltered'
```

[./lsystem-wrapper-modeMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-modeMap.wav)

### lsystemModeFilter

```
e.modeFilters.aeolianFiltered = await K.lsystemModeFilter('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap, e)
e.players.exampleMidiPlayer1.modeFilter = 'aeolianFiltered'
```

[./lsystem-wrapper-modeFilter.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-modeFilter.wav)

### lsystemRootMap

```
e.rootMaps.aeolianFiltered = await K.lsystemRootMap('aeolianFiltered',2 , 30, rules, 10, e.modeFilters.aeolian.values, startingLetter,allChars, rhythmMap, e)
e.players.exampleMidiPlayer1.rootMap = 'aeolianFiltered'
```

[./lsystem-wrapper-rootMap.wav](https://konduktiva.org/doku.php?id=lsystem-wrappers-audio-viewer&lsystem-wrapper-rootmap.wav)

</markdown>