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 Konduktiva installation instructions and have read through and understood the first steps tutorial. The tutorial also assumes that you have imported Konduktiva to the K variable and assigned any of the example MusicalEnvironments to the e variable.

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.

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

Run this to view what type of input each configuration option is expecting:

K.emptyConfigObj.toString()

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

{
        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]
    }
 

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

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).

K.recordConfigurationDataIntoMusicalEnvironment (noteValueData, name, e)

==== Parameters

The configuration object.

The name of the items the function should create.

The MusicalEnvironment the information should be recorded in.

//Code modified from Konduktiva setUpVerySimpleMusicalEnvironment function
//Create configuration object:
let simpleMelodyData = K.R.clone(K.simpleMelodyDataTemplate)
simpleMelodyData.velocity = [100, 100, 100, 100]
simpleMelodyData.rhythmMap = [1, 2, 3, 4]
simpleMelodyData.noteValues = [[1], [2], [3], [4]]
simpleMelodyData.rootMap = [ 'C', 'C', 'C', 'C' ]
 
//Add it to MuiscalEnvironment:
recordConfigurationDataIntoMusicalEnvironment(simpleMelodyData, 'p1', e)

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

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.

K.assignPlayerForMusicSynthesizerMidiOutput (e, defaultName, playerName, playerData)
 
==== 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)
simpleMelodyData.velocity = [100, 100, 100, 100]
simpleMelodyData.rhythmMap = [1, 2, 3, 4]
simpleMelodyData.noteValues = [[1], [2], [3], [4]]
simpleMelodyData.rootMap = [ 'C', 'C', 'C', 'C' ]
 
//Add it to MuiscalEnvironment:
K.recordConfigurationDataIntoMusicalEnvironment(simpleMelodyData, 'p1', e)

New example starts here: