MKtl description files:
Filter:
Modality-toolkit/Reference (extension) | Libraries > Modality

MKtl description files
ExtensionExtension

describes the format for MKtl desc files and the entries in them.

A description file contains detailed information about a controller. Precise information about each of its interaction elements like sliders, knobs, or buttons help to create good performance setups very efficiently.

Evaluating the code in a desc file should return a Dictionary (or more conveniently, an Event) of a well-defined structure. Description files are located here:

NOTE: Find a similar controller that is already supported and use it as a blueprint for your new description file.

This document gives an overview on

Filename convention

The filename should be of the following format:

where

Semantic and technical information

NOTE: A description file is bound to a single protocol - currently one of \midi, \hid, and \osc (or \virtual for sketches). If a device communicates on multiple protocols (e.g. the icon iCONTROLS), or on multiple ports (the QuNexus), its components can be built from separate desc files and optionally be merged with CompMKtl where that is desirable.

Top level

deviceName | osx | linux [required]
For MIDI and HID, this is the device name as reported by the hardware or OS drivers. (OSC devices are not registered by the OS, so the name is only for description here).
protocol [required]
The protocol used by the device. one of [\hid, \midi, \osc, \virtual].
deviceType [optional, but highly recommended]
Semantic description of what kind of device it is. This will make it easier to find another device that might easily replace it. For examples, do:
elementTypes [optional, but highly recommended]
Description of what kind of elements the device has. For example: \fader, \button, \knob, \encoder, \joyAxis ...
status [optional, but highly recommended]
A string describing the status of this description, i.e. how complete and how well tested it is, by platform, with a nametag and date. E.g. the akai lpd8 has:

status is unknown until somebody tests the device, and incompleteness can be noted, such as "elements incomplete (X missing)" etc.

idInfo | osx | linux [required]
The info used to fully identify the device. For HID devices, this is a String with <productname>_<vendorname>, e.g.:

For MIDI devices with a single source and/or destination port, this is the same as the deviceName. For multi-port MIDI devices, this should be a dictionary with entries for

For OSC devices, this is a dictionary with information on the ipAdresses and ports used. (As NetAddresses may change, this often requires updating by hand. )

elementsDesc [required]
A (usually hierarchical) dictionary describing the control elements of the device. These controls are called elements within the Modality toolkit.
deviceInfo [optional]
A dictionary giving additional information on the device.
collectives [optional]
Specific groups that are needed to send or receive data collectively from the device. These are commonly used in OSC devices.
specs [optional]
A dictionary with specs in serialized notation, like (\key: [0, 144, \lin]). These overwrite existing spec definitions locally for this description only: When an element has a symbol for a spec, this is looked up locally first, then in MKtl.globalSpecs, then in global Spec.specs.

The description of a single element

A control element is a part of a controller (often for physical interaction, like a slider, knob, accelerometer etc. etc.) that does one or more of the following things:

For full details on single element description see also: Naming_conventions_in_element_descriptions

An element description is a dict (or event) containing these entries:

midiMsgType
midiMsgType has to be present for elements belonging to a MIDI device.
hidElementID | <hidUsage|hidUsagePage>
hidElementID or both hidUsage and hidUsagePage have to be present for elements belonging to an HID device.
oscPath
oscPath has to be present for elements belonging to an OSC device, or it has to use ioType: \groupIn or ioType: \groupOut
spec
The element \spec has to be present and is a symbol that, if called .asSpec upon, returns the (global) ControlSpec suitable for this element.
midiChan, midiNum
\midiChan is needed for all midi messages including \bend, \touch, \program, \midiNum is needed only for \noteOn, \noteOff, \control and \polyTouch messages.

The 'elementsDesc' field is a dictionary that can contain other dictionaries or arrays, which will be used to build hierarchical groups of elements in the MKtl to be built from the description. At the leaves of this data structure must be a dictionary describing an element. Its most important keys are \key, \shared, \elements; \key defines a local lookup name for the element or group; \shared defines properties shared between elements in this group, and \elements is an array of elements which again contains dictionaries describing elements or groups.

A typical structure would be:

The 'specs' field contains a dictionary of specifications of controller ranges which the MKtl will use. An example:

deviceInfo

The deviceInfo is typically of the following form. All entries are optional.

Identifier naming convention

Naming conventions for identifiers are:

Naming conventions for type values are:

NOTE: The description file for the "Korg nanoKONTROL 2"

is a good example for element naming. All naming examples are taken from there.

Generally, element names should be as clear as possible, and reasonably short to allow for compact code (e.g. for live coding mappings of controllers). The main advantage of following the conventions is that similar elements across devices will have identical or at least similar names, and thus allow substituting one device for a similar one with minimal code changes.

Unnamed buttons should be called \bt, sliders \sl, knobs \kn, pads \pad, etc., and when they are physically in arrays, they should be given like this:

When elements in an array are not explicitly given name keys, they will get self-generated keys as follows:

When in rows and columns, these can be nested:

Elements with names or symbols on them should be given that name, e.g. a button name "play" or with a > sign on it should be called \play or \playBt. in the nanoKontrol 2 file, such button names include transport buttons \rew, \fwd, \stop, \play, \rec, \cycle, track buttons \tleft, \tright, and marker buttons \mset, \mleft, \mright.

When in doubt, consult files of devices with similar elements, and follow the naming schemes there.

Grouping conventions:

Multiple elements of the same type, such as a bank of sliders, should be put in a single group, which can also be nested, as shown above.

Groups of elements which belong to a single physical control element (or otherwise belong together semantically) should be put in a single group. E.g. a gamepad thumbstick typically has an x-axis, a y-axis, and sometimes a hat switch, which should be in one group:

For MIDI noteOn and noteOff, one can create pairs with MKtlDesc.notePair, which creates a dict with elements for \on and \off, and proper shared info including some gui layout information.

When other elements should go into this group, one can also make them separately:

This creates a semantically clear group, and generates separate elements with independent actions for each message type. the noteOn action could be used to start a synth, touch to update one of its parameters while alive, and noteOff (using noteOff velocity) to end this synth.