====== Creating Players ======

**Overview: ** This tutorial will teach you how to create your own players like the ones that came with the example MusicalEnvironment.

**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', K.exampleMusicalEnvironmentsExtraConfig)
</code>


====== Configuration Object ======

One useful tool to help create players is using configuration objects. 

The function //recordConfigurationDataIntoMusicalEnvironment// will take a configuration object and convert that to QuantizedMaps and put it into the right areas of a MusicalEnvironment.

There are many configuration options in the configuration object so, there are functions to help with the creation of these configuration objects. 

The function //emptyConfigObj// will return a configuration object with all the available configuration options set to undefined.

<code javascript>

let emptyConfig = K.emptyConfigObj()
console.log(emptyConfig)
/*
{
  total: undefined,
  noteValuesKeyspan: undefined,
  octaveMapKespan: undefined,
  noteDurationKeyspan: undefined,
  rootMapKeyspan: undefined,
  modeFilterKeyspan: undefined,
  modeMapKeyspan: undefined,
  channelKeyspan: undefined,
  noteValuesKeys: undefined,
  rootMapKeys: undefined,
  octaveMapKeys: undefined,
  noteDurationKeys: undefined,
  velocityKeys: undefined,
  modeFilterKeys: undefined,
  modeMapKeys: undefined,
  channelKeys: undefined,
  noteValues: undefined,
  bools: undefined,
  rootMap: undefined,
  octaveMap: undefined,
  noteDurations: undefined,
  velocity: undefined,
  polyphonyMap: undefined,
  modeFilter: undefined,
  modeMap: undefined,
  channelValues: undefined
}
undefined
*/

</code>

Run this to view what type of input each configuration option is expecting:
<code javascript>

K.emptyConfigObj.toString()

</code>

Or view an empty configuration object with the expected type input each configuration object is expecting here:
<code javascript>

{
        total: undefined, //number
        noteValuesKeyspan: undefined, //number
        octaveMapKespan: undefined, //number
        noteDurationKeyspan: undefined, //number
        rootMapKeyspan: undefined, //number
        modeFilterKeyspan: undefined, //number
        modeMapKeyspan: undefined, //number
        rootMapKeyspan: undefined, //number
        channelKeyspan: undefined, //number

        noteValuesKeys: undefined, //number
        rootMapKeys: undefined, //number 
        octaveMapKeys: undefined, //[number]
        noteDurationKeys: undefined, //[number]
        velocityKeys: undefined, //[number]
        modeFilterKeys: undefined, //[number]
        modeMapKeys: undefined, //[number]
        rootMapKeys: undefined, //[number]
        channelKeys: undefined, //[number]

        noteValues: undefined, //[[number],[number]]
        bools: undefined, //[booleans]
        rootMap: undefined, //[Musical letter notation]
        octaveMap: undefined, //[number]
        noteDurations: undefined, //[number]
        velocity: undefined, //[number]
        polyphonyMap: undefined, //[number]
        modeFilter: undefined, //[number]
        modeMap: undefined, //[number]
        rootMap: undefined, //[string]
        channelValues: undefined, //[number]
    }
    
</code>

After the configuration object has been created, the //recordConfigurationDataIntoMusicalEnvironment// will put your changes into the MusicalEnvironment.

===== recordConfigurationDataIntoMusicalEnvironment =====

Object -> string -> MusicalEnvironment -> string

Takes the configuration object (first argument) and puts it into the MusicalEnvironment(third argument) under the user provided name (second argument).

==== Syntax ====
<code javascript>

K.recordConfigurationDataIntoMusicalEnvironment (noteValueData, name, e)

</code>

==== Parameters ====
=== noteValueData ===
The configuration object.
=== name ===
The name of the items the function should create.
=== e ===
The MusicalEnvironment the information should be recorded in.

==== Example ====
<code javascript>
//Code modified from Konduktiva setUpVerySimpleMusicalEnvironment function
//Create configuration object:
let simpleMelodyData = K.R.clone(K.simpleMelodyDataTemplate)
//K.simpleMelodyDataTemplate is a simple template of a configuration object
simpleMelodyData.velocity = [100, 100, 100, 100]
simpleMelodyData.rhythmMap = [1, 1, 1, 1]
simpleMelodyData.noteValues = [[1], [2], [3], [4]]
simpleMelodyData.rootMap = [ 'C', 'C', 'C', 'C' ]

//Add it to MuiscalEnvironment:
K.recordConfigurationDataIntoMusicalEnvironment(simpleMelodyData, 'p1', e)
</code>

Next a Player has to be created to make use of the data in the MusicalEnvironment. Use the //assignPlayerForMusicSynthesizerMidiOutput// function to do so.

===== assignPlayerForMusicSynthesizerMidiOutput =====
MusicalEnvironment -> string -> string -> Object -> 

Function will configure a player to use the maps under the defaultName(second argument) unless otherwise stated in the playerData object (fourth argument). The code will create a player if a player by the name user provided (third argument) is not found. If found will modify the player found.

==== Syntax ====
<code javascript>
K.assignPlayerForMusicSynthesizerMidiOutput (e, defaultName, playerName, playerData)
</code>

==== Parameters ====
=== e ===
MusicalEnvironment
=== defaultName ===
The name that the function will default all player variables it will configure to unless otherwise stated.
=== playerData ===
Names to assign specific variables to. Overrides the default name. An object with all the argument variables set to undefined can be found by running the emptyPlayerDataConfigObj function found inside the Konduktiva package. The types of input the argument variables expect can be found as comments inside the function which can be viewed in the source code or simply using the JavaScript built in .toString() method. 

==== Example ===
The example here is a continuation of the example from above. If you have not run the code from the example from above here it is again:
<code javascript>
//Code modified from Konduktiva setUpVerySimpleMusicalEnvironment function
//Create configuration object:
let simpleMelodyData = K.R.clone(K.simpleMelodyDataTemplate)
//K.simpleMelodyDataTemplate is a simple template of a configuration object
simpleMelodyData.velocity = [100, 100, 100, 100]
simpleMelodyData.rhythmMap = [1, 1, 1, 1]
simpleMelodyData.noteValues = [[1], [2], [3], [4]]
simpleMelodyData.rootMap = [ 'C', 'C', 'C', 'C' ]

//Add it to MuiscalEnvironment:
K.recordConfigurationDataIntoMusicalEnvironment(simpleMelodyData, 'p1', e)
</code>

New example starts here:
<code javascript>
//make or modify player to use info:
K.assignPlayerForMusicSynthesizerMidiOutput(e, 'p1','exampleMidiPlayer1')
//configure legatoMap:
e.players.exampleMidiPlayer1.legatoMap = 'default'

//signal to player to start playing:
e.play('exampleMidiPlayer1')
</code>

===== configObjCreation =====
Number -> [Number] -> [Number] -> [String] -> [[Number]] -> [Number] -> [Number] -> Object

A useful tool for creating very basic configuration objects.

==== Syntax ====
<code javascript>
K.configObjCreation (total, keys, octave, root, note, noteDuration, velocity)
</code>

==== Paramters ====
=== total ===
They keyspan of the QuantizedMaps. Also the total variable in the configuration object.
=== keys ====
The keys of the QuantizedMaps.
=== octave ===
The value of the octave maps
=== root ===
The value of the root maps.
=== note ===
The value of the note maps.
=== noteDuration ===
The value of the noteDuration maps.
=== velocity===
The value of the velocity maps.

==== Example ====
<code javascript>
let basicConfig = K.configObjCreation(4, [0, 1, 2, 3], [3, 3, 3, 3], ['C', 'C', 'C', 'C'], [[3], [4], [5], [6]], [2, 2, 2, 2], [100, 100, 100, 100])
</code>