Modality Tutorial

Extension

Finding present devices

The first step is to discover which devices are available for use:MKtl.find;

This will find all currently available devices, all the known info on them, and post instructions with example lines of code for several possible cases:

• Often - Device is supported (many devices are):// [ [ "iCON iControl V1.02", "Port 1", 74435252 ] ] // Supported. Create by lookupName only if necessary: // MKtl('midi_1_icon_i', 'midi_1_icon_icontrol_v1_02_port_1'); // Best create MKtl from desc file: MKtl('midi_1_icon_i', "icon-icontrols-102");

• Less often - Device is not supported in modality yet:// [ [ "IAC Driver", "IAC Bus 1", -476939297 ] ] // Unknown - Create from lookupName and explore: MKtl('midi_0_iac_dr', 'midi_0_iac_driver');

• Sometimes - Device has multiple matching desc files:// [ [ "Arturia BeatStep", "Arturia BeatStep", -512494375 ] ] // Supported by 2 desc files. // Create MKtl from lookupName only if necessary: // MKtl('midi_1_arturi', 'midi_1_arturia_beatstep'); // Best create MKtl from one of the desc files: MKtl('midi_1_arturi', "arturia-beatstep-rel-0"); MKtl('midi_1_arturi', "arturia-beatstep-rel-16");

• Rarely - Multiples identical devices are found, code includes a multiIndex:// [ "USB Game Controllers", "Mega World" ] // Best create MKtl from desc file: MKtl('hid_5_usb_ga', "saitek-impact-gamepad", multiIndex: 0); // [ "USB Game Controllers", "Mega World" ] // Best create MKtl from desc file: MKtl('hid_6_usb_ga', "saitek-impact-gamepad", multiIndex: 1);

Copy the code line for the device you want to use from the post window to a text document and change its nickname to one you like:// create a MKtl with the desired name and desc file MKtl('nk2', "korg-nanokontrol2"); // access it by its MKtl lookup name MKtl('nk2'); // or assign it to a global variable for less typing: k = MKtl('nk2'); // if you do not have that device, create a gui to replace it: k.gui;

You can see the output from all elements by doing//turn it on k.trace; //turn it off k.trace(false);

The same for a Thrustmaster RunNDrive gamepad:g = MKtl(\gp, "*impact-gamepad"); g.gui; g.trace; g.trace(false);

Elements and Groups

Each control (i.e. knob, slider, button, etc) on the device is represented by an MKtlElement. All elements are contained in the elementGroup in a hierarchical order:k.elementGroup; // you can access elements in each group by index or name: k.elementGroup[0]; k.elementGroup[\tr]; // post the tree of all groups and elements to see the hierachical order: k.postElements;

The elementGroup is an (MKtlElementGroup) and usually contains some nested groups, where the final node is always an MKtlElement. The structure of the groups follows a meaningful order, e.g. the spatial arrangement on the device (rows, columns, areas) or a logical order (pages, function groups, etc). (One can create custom orders of elements as well, see Creating_Custom_Elements_and_Groups.

This organization is defined in an MKtlDesc file for the device, which are provided for many devices already.k.desc.openFile; // the top level keys - some may be individual elements, others groups of elements: k.elementGroup.keys; //the play button k.elAt(\tr, \play); //the first slider k.elAt(\sl, 0); k.elAt(\sl, \1); //all sliders as a group k.elAt(\sl); //the third knob k.elAt(\kn, 2); k.elAt(\kn, \3); //the button on row 2 and column 5 //buttons are organized first by rows and then columns. k.elAt(\bt, 1, 4) k.elAt(\bt, \M, \5) //all buttons on row 2 k.elAt(\bt, 1); //all buttons on column 5 k.elAt(\bt, nil, 4);

Using actions

Actions for an element (or group) are defined using the "action_" or the "addAction" methods of MKtlElement. These methods take a function as argument which receives a single argument, the MKtlElement it belongs to. One can get the current value of the element by ".value". The value returned by an MKtlElement is always between 0 and 1.//Assign an action to the third knob k.elAt(\kn, 2).action_({ |el| [el.name, el.value.round(0.0001)].postcs }); // reset the of this knob to nothing (nil) k.elAt(\kn, 2).resetAction; //Add an action to the group of all knobs ( k.elAt(\kn).action_({ |el| "knob % value: %\n".postf(el.parent.indexOf(el), el.value) }); ) //reset the \kn group's action to nil k.elAt(\kn).resetAction;

Controlling a very simple sound process

... Now you can control four parameters of synth z.

Using named elements for actions

For more flexibility and clarity, one can give the elements names for their functions, and use those:( k.addNamed(\amp1, k.elAt(\sl, 0)); k.addNamed(\pan1, k.elAt(\kn, 0)); k.addNamed(\param1, k.elAt(\sl, 1)); k.addNamed(\param2, k.elAt(\kn, 2)); // why not prepare buttons for start and stop k.addNamed(\start1, k.elAt(\bt, \S, 0)); k.addNamed(\stop1, k.elAt(\bt, \R, 0)); ) // give them the same actions as above: ( k.elAt(\amp1).action_({ |elem| z !? _.set(\amp, \amp.asSpec.map(elem.value)) }); k.elAt(\pan1).action_({ |elem| z !? _.set(\pan, \pan.asSpec.map(elem.value)) }); k.elAt(\param1).action_({ |elem| z !? _.set(\freq, elem.value.linlin(0.0, 1.0, 50, 2000) ) }); k.elAt(\param2).action_({ |elem| z !? _.set(\numHarmonics, elem.value.linexp(0.0, 1.0, 1, 50) ) }); // and new functions for start and stop: k.elAt(\start1).action_({ |elem| if(elem.value > 0) { // only start on button down z !? _.free; z = Synth(\blippy, [\freq, 440, \numHarmonics, 100, \amp, 0.5, \pan, 0]) } }); k.elAt(\stop1).action_({ |elem| if(elem.value > 0) { // only stop on button down z !? _.free; ~syn1 = nil; } }); )

Controlling the same process from a different device

And now run the same function setting code as above for the gamepad controller! For a full example of this approach, see Substituting_MKtls.

Using multiple actions

For very flexible use of multiple actions, see also MFunc in the "adclib" Quark.// Assigning multiple actions to an element can be done with .addAction: ( k.elAt(\amp1).addAction({ |elem| ("1 :"++elem.value).postln }); k.elAt(\amp1).addAction({ |elem| ("2 :"++elem.value).postln }); ) //clear all k.elAt(\sl, 0).resetAction; /// to remove them you need to have a reference to the function ( f = { |elem| ("1 :"++elem.value).postln }; g = { |elem| ("2 :"++elem.value).postln }; k.elAt(\sl, 0).addAction(f); k.elAt(\sl, 0).addAction(g); ) //remove first action k.elAt(\sl, 0).removeAction(f); // just action 2 is left //clear all k.elAt(\sl, 0).action = nil;

Output elements

Some devices can be set to specific values, e.g. setting motorfaders or LED rings around encoder knobs to the corresponding values.// input elements of the device : k.inputElements; // output elements k.outputElements; // sending data to the output elements // value range between 0 and 1, will be mapped according to the // deviceSpec given in the description file // here, should set LEDs on all S buttons /* MKtl(\nk2).elAt(\bt, \S).do { |elem| elem.value_(1.0) }; MKtl(\nk2).elAt(\bt, \S).do { |elem| elem.value_(0.0) }; */ k.free;