action-functions [konduktiva]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
====== Action Functions ======
**Overview: ** This tutorial will teach you about what actions function do in Konduktiva and how they work.


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


An Action Function is the function the player calls when the Konduktiva scheduler tells it that to do something.  The action function the player uses can be controlled at the variable //e.players.playerName.action//. It should be a string and the strings refer to a variable which is a function in the //e.actions// object. This analogy might help, players are like an employee working in a company. The action function is the job the employee has to do and the scheduler is the manager telling the employee when to start or stop working.
<code javascript>
//Code will work if you have imported Konduktiva to K variable and assigned any of the example MusicalEnvironments to e.
//View all the actions functions.
console.log(e.actions)

//View the action function players exampleMidiPlayer1 is using:
console.log(e.players.exampleMidiPlayer1.action)
</code>

To test if the action function is being triggered you can assign the player to use the default action function and turn on verbose. Verbose is a feature that will prompt the functions to log many things which is useful for debugging.:
<code javascript>
e.players.exampleMidiPlayer1.action = 'default'
e.players.exampleMidiPlayer1.verbose = true
e.play("exampleMidiPlayer1")
</code>

And assuming that you have the other maps left configured like the example MusicalEnvironment configured it you should see logging like this:
<code>
Hi this is the default action function being triggered
This is the session:  exampleMidiPlayer1
This is the beat:  1561
</code>

If you do not, restart Konduktiva and assign the //MusicalEnvironment// to //e// again. 

===== Existing Action Functions =====
==== default: ====
{{ :default-action-funciton-flowchart.svg |}}

==== sendNotesMidiInfo: =====

{{ :sendnotesmidiinfo-action-function-flowchart.svg |}}

==== sendChordMidiInfo: ====
{{ :sendchordsmidiinfo-action-function-flowchart.svg |}}

==== superDirt/playSuperDirtSample: ====
{{ :superdirt-playsuperdirtsample-action-function-flowchart.svg |}}

====== How to write an action function ======

**Overview: ** This tutorial will teach you how to make your own action function by going through the steps of making a new action function called //testAction//.

**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 [[http://konduktiva.org/doku.php?id=action-functions|action functions tutorial should]] also be read.

Setup:
<code javascript>
const K = require('konduktiva')
let e = K.setUpMusicalEnvironment(K.defaultConfigurationObject,4,'exampleMidiPlayer', K.exampleMusicalEnvironmentsExtraConfig)
</code>

===== Example 1 =====
The action function arguments should be in this order for Konduktiva to be able to use it properly: player name, beat, MusicalEnvironment.
So we will start this function like this:
<code javascript>
function testAction (playerName, b, e) {
</code>
Next we will make the action function do something very simple like log messages in the console. When making an action function, it is important to keep in mind that because JavaScript is single threaded, a computationally heavy action function could block the next events, and that's especially weird for events that are supposed to be simultaneous or temporally near.
<code javascript>
function testAction (playerName, b, e) {
    console.log('Hi this is my new action function called testAction.')
    console.log('testAction playerName: ', playerName)
    console.log('testAction beat: ', e.currentBeat())
}
</code>

Notice we did not use b argument. The b argument is for next onset. To get beat use e.currentBeat().

Next we have to make it so the players in the MusicalEnvironment can use it. To do so, we have the add it to the actions object of the MusicalEnvironment:
<code javascript>
e.actions.testAction = testAction
</code>
Now to get a player to use it, modify the action variable of the Player:
<code javascript>
e.players.exampleMidiPlayer1.action = 'testAction'
</code>
Now if you play the player you will see that it will use the //testAction// action function:
<code javascript>
e.play('exampleMidiPlayer1')
</code>

===== Example 2 =====
Making an action function that plays a random note each time it is triggered.

<code javascript>
function sendRandomMidiNote(){
   K.checkIfUseVerboseLogging('Playing random note to midi output 0')
    let noteToPlay = K.randomRange(0, 127)
    e.midiOutputs[0].send('noteon', {
        note: noteToPlay,
      velocity: 100,
      channel: 0,
    });
    setTimeout(() => {
        e.midiOutputs[0].send('noteon', {
          note: noteToPlay,
          velocity: 100,
          channel: 0,
        });
   }, 1000)
}
e.actions.sendRandomMidiNote = sendRandomMidiNote
e.players.exampleMidiPlayer1.action = 'sendRandomMidiNote'
e.play('exampleMidiPlayer1')
</code>

It should sound something like this:

{{ :random-notes.mp3 |}}

[[https://konduktiva.org/doku.php?id=displaying-musicalenvironment-content|Click here to learn about displaying Musical Environment Content ]] OR [[https://github.com/renickbell/konduktiva/blob/main/konduktiva-documentation.md|Click her to see full Konduktiva documentation]]