MKtl description files
Extension
ExtensionA 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:
This document gives an overview on
Filename convention
The filename should be of the following format:
where
<vendor>is lower-case name of vendor with spaces replaced by'-'.<device_name>is lower-case name of the device with spaces replaced by'-'. This is both unique enough to identify devices, and allows linking to the modality website entry on each device.<optional_setup_naming>can be used to create multiple desc files for the same device, e.g. to support multiple ports (as e.g. the QuNexus keyboard), for special presets, such as making separate desc files for switchable hardware pages, or for personalized versions of desc files.
Semantic and technical information
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:
- creates and sends a one-dimensional stream of values when played,
- accepts a one-dimensional stream of values when sent from software.
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
midiMsgTypehas to be present for elements belonging to a MIDI device.- hidElementID | <hidUsage|hidUsagePage>
hidElementIDor bothhidUsageandhidUsagePagehave to be present for elements belonging to an HID device.- oscPath
oscPathhas to be present for elements belonging to an OSC device, or it has to useioType: \groupInorioType: \groupOut- spec
- The element
\spechas to be present and is a symbol that, if called.asSpecupon, returns the (global)ControlSpecsuitable 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 \polyTouchmessages.
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:
knfor knobs,slfor sliders,btfor buttons,keyfor keys,padfor pads, etc. Elements with names or symbols on them should have that name, e.g. a play button should be called \play, a rewind button \rew, etc.
Naming conventions for type values are:
sliderfor sliders,knobfor knobs,buttonfor buttons,keyfor keys,padfor padsoscMessagefor osc-messages (of collectives)
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.
link::Modality-toolkit/Reference/MKtl_description_files::