quantizedmaps-tutorial [konduktiva]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== What Are QuantizedMaps? ======

**Overview: ** This tutorial will teach you about QuantizedMaps and how they are used inside of Konduktiva.

**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>

QuantizedMap is a class to nodejs:

```
K.QuantizedMap
//[class QuantizedMap]
```

The instance of QuantizedMap is used to store data in Konduktiva. You will see it used everywhere. For example, assuming you have e as a default MusicalEnvironment:
```
//Make e variable a default MusicalEnvironment:
let e = K.setUpMusicalEnvironment(K.defaultConfigurationObject,4,'exampleMidiPlayer')

console.log(e.noteMaps)
//It is full of QuantizedMaps. We can know that because after the variable name, it will say QuantizedMap like this "default: QuantizedMap {". We can also verify that using code:
console.log(e.noteMaps.default instanceof K.QuantizedMap)
```

The full QuantizedMap documentation can be found [here](https://github.com/renickbell/konduktiva/blob/main/README.md#quantized-map) but generally keys represents the timing. Values represents the values that should be used at a specific timing and keyspan is the total.

The QuantizedMaps are all recorded in different variables in the MusicalEnvironment but they are only used when the players are told to use them. For example:
```
//The modeMap variable in e.players.exampleMidiPlayer4.noteMap is default
console.log(e.players.exampleMidiPlayer4.noteMap)
//So that means when the player is going to play something, it will look at:
console.log(e.noteMaps.default)
```
</markdown>

====== Adding QuantizedMaps To The MusicalEnvironment ======

Konduktiva has three main ways for users to add their music into the MusicalEnironment. Having multiple means for this was necessary to provide appropriate interfaces for different use cases and users. The first is the most direct yet potentially dangerous way: to add things directly to the MusicalEnvironment. This is the quickest way for those who know their way around the system, but it will not stop the user from inputting incorrect types of information or inputting things in the wrong format. The second way of doing this is using configuration objects which allows the user to place all the data into a JavaScript object under specific property names. This method is usually only used when the MusicalEnvironment is created or when a new Player is created because the usage of this method automatically removes the old data without further confirmation (the method users are advised to start the MusicalEnvironment in these tutorials). There is limited error checking for this part of the process. The third way which is recommended for novice users: the addMap method of the MusicalEnvironment. This method has extensive error checking and it will do actions like convert or format data when necessary. The error thrown will also inform the user of what needs to be fixed.

The recommended way to change specific variables in the MusicalEnvironment is to use the addMap method because it checks for many different types of errors and common mistakes when coding quickly. However, if you are confident and need more speed you can choose to directly interact with the MusicalEnvironment object. Here are some examples
===== Changing Octaves =====

For example, if I wanted to change the octaves of exampleMidiPlayer4 without changing timing I would do this:
<code javascript>
//Identify which octave map exampleMidiPlayer4 is looking at:
e.players.exampleMidiPlayer4.octaveMap
    
//see what it looks like currently
console.log(e.octaveMaps[e.players.exampleMidiPlayer4.octaveMap].values)

//Next (the safer way):
 e.addMap('octaveMaps',
    e.players.exampleMidiPlayer4.octaveMap,
    e.octaveMaps[e.players.exampleMidiPlayer4.octaveMap].keyspan,
    e.octaveMaps[e.players.exampleMidiPlayer4.octaveMap].keys,
    [[ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ]]
)
//to see the changes:
console.log(e.octaveMaps[e.players.exampleMidiPlayer4.octaveMap].values)

//OR do this the less safe way but potentially faster with more control:
e.octaveMaps[e.players.exampleMidiPlayer4.octaveMap].values =[[ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ], [ 6 ]]

//to see the changes:
console.log(e.octaveMaps[e.players.exampleMidiPlayer4.octaveMap].values)
</code>
===== Changing RhythmMap =====
Example changing rhythmMap for exampleMidiPlayer4 without changing timing. Similar to [[http://konduktiva.org/doku.php?id=first_steps#changing_octaves|changing octave]].
<code javascript>
//Recommended safe way:
e.addMap('rhythmMaps',
    e.players.exampleMidiPlayer4.rhythmMap,
    e.rhythmMaps[e.players.exampleMidiPlayer4.rhythmMap].values[0].keyspan,
    e.rhythmMaps[e.players.exampleMidiPlayer4.rhythmMap].values[0].keys,
    [2, 4, 6]
)
//other potentially faster way:
e.rhythmMaps[e.players.exampleMidiPlayer4.rhythmMap].values[0].values = [2, 4, 6]
</code>

===== Changing Melody, Notes or Chords ====
Example of changing notes played for exampleMidiPlayer4 Similar to [[http://konduktiva.org/doku.php?id=first_steps#changing_octaves|changing octave]].:
<code javascript>
//Recommended way
e.addMap('noteMaps',
    e.players.exampleMidiPlayer4.noteMap,
    5,
    [0, 1, 2, 3, 4],
    [ [40],[50], [60], [70], [80]]
)
//OR
e.noteMaps[e.players.exampleMidiPlayer4.noteMap] = new K.QuantizedMap(5, [0, 1, 2, 3, 4], [ [40],[50], [60], [70], [80]])
</code>

===== Changing The MusicalEnvironment In General =====

To change things in the MusicalEnviornment, one should use the addMap method. The documentation is in [[https://github.com/renickbell/konduktiva/blob/main/konduktiva-documentation.md|konduktiva-documentation.md]]

Or read about the different ways to generate music [[http://konduktiva.org/doku.php?id=music_generation|here]]

====== Changing The QuantizedMaps Used By A Player ======
The sound output can be easily changed by simply switching the data the player looks at without creating any new data.
====== Changing notes played =====
This will cause the notes to loop between 0 to 11.
<code javascript>
e.players.exampleMidiPlayer1.noteMap = 'default'
//To look at the information being used:
console.log(e.noteMaps.default)
</code>
====== Changing modeMap used =====
This will cause the chord progression chromatic to be used.
<code javascript>
e.players.exampleMidiPlayer1.modeMap = 'default'
//To look at the information being used:
console.log(e.modeMaps.default)
</code>
====== Changing melody used =====
This will cause the player to cycle between the notes 0 to 3.
<code javascript>
e.players.exampleMidiPlayer1.noteMap = 'default'
//To look at the information being used:
console.log(e.noteMaps.default)
</code>

====== Playing Chords =====
To play chords another action function will have to be used. To switch action functions do this:
<code javascript>
e.players.exampleMidiPlayer1.action = 'sendChordMidiInfo'
</code>

[[music_generation|Click here to learn about music generation and generating melodies in Konduktiva]]