How to create a description file

Extension

Introduction

The functionality of MKtl relies on descriptions of the devices to be used. For many controllers, there are already descriptions available, but your preferred device may not be among them.

This tutorial shows how to describe elements, which is largely the same for all description files (regardless of protocol). For the specifics of the three supported protocols, there are these three specific tutorials:

• How_to_create_a_description_file_for_MIDI
• How_to_create_a_description_file_for_HID
• How_to_create_a_description_file_for_OSC

When your controller is rather typical example of its class, say a gamepad or faderbox, you can also find a similar device and adapt its description: How_to_adapt_a_description_file

Basic structure of the description file

The description file is a Dictionary with a number of required entries.

The main entry is the elementsDesc which contains all the elements/controls of a device.

For physical devices, you need to define the protocol and the idInfo. The protocol is one of [\osc, \midi, \hid]. The \idInfo is different per protocol, please see the respective tutorial for an elaborate description.

If you want to create a virtual device, the minimum info required is the idInfo and protocol: (idInfo: \something, protocol: \virtual) and in the description, every element needs an ioType and a spec.

For example:// create a dictionary that can be turned into an MKtlDesc: // it has a name - only needed for the demo here // it has an idInfo - this is for matching with physical devices // a protocol - one of \osc, \midi, \hid for real devices, or \virtual // and an elementsDesc - here, this has one button. ( ~descOneBut = ( name: \oneBut, idInfo: \oneBut, protocol: \virtual, elementsDesc: ( elements: [ (key: \bt, type: \button, ioType: \in, \spec: \but ) ] ) ); ); // One create an MKtlDesc from it: d = MKtlDesc.fromDict(~descOneBut); ) // now, to test that the desc dict works, // we use the desc dict directly to create an MKtl: ( m = MKtl.new( \oneButton, ( idInfo: \oneBut, protocol: \virtual, elementsDesc: ( elements: [ (key: \bt, type: \button, ioType: \in, \spec: \but ) ] ) ), false ); ); m.gui; // create a gui for the MKtl m.elAt; // access its elementGroup m.elAt(0); // the only element in it by index m.elAt(\bt); // the only element in it by key m.free; // free m's resources and remove it from MKtl.all

Simple Element Groups

Descs for devices with multiple elements can be written in multiple ways:// 1. write out every element fully: ( elementsDesc: ( elements: [ (key: \bt1, type: \button, ioType: \in, \spec: \but ), (key: \bt2, type: \button, ioType: \in, \spec: \but ), (key: \bt3, type: \button, ioType: \in, \spec: \but ), (key: \bt4, type: \button, ioType: \in, \spec: \but ) ] ) ); // 2. put all shared properties in the entry 'shared': // note that keys are still made by hand here ( elementsDesc: ( shared: (elementType: \button, ioType: \in, \spec: \but ), elements: [ (key: \1), (key: \2), (key: \3), (key: \4) ] ) ) // 3. generate the elements by code - may seem complicated // for 2-3 elements, but useful for more. // note that keys are passed in here ( key: \bt, shared: (elementType: \button, ioType: \in, \spec: \but ), elements: [\a, \b, \c, \d].collect { |key| (key: key) } ) ( m = MKtl.new( \fourButtons, ( idInfo: \oneBut, protocol: \virtual, elementsDesc: ( key: \bt, shared: (elementType: \button, ioType: \in, \spec: \but ), elements: [\a, \b, \c, \d].collect { |key| (key: key) } // this generates [\1, \2, \3, \4] automagically: // elements: (1..4).collect { |i| () } ) ), false ); ); // element names get put together from group key and local keys // - if not defined explicitly, local keys are \1, \2, \3 ... m.postElements;

See also: MKtl_description_files for a discussion of all possible keys.

Specs

If a control of your device needs a custom Spec, then you can define this in the element spec of the device description.

For example:specs: ( mantaTouch: [ 0, 227 ].asSpec, mantaSlider: [ 0, 4095 ].asSpec, // led can be off, amber or red mantaLed: ItemsSpec.new( ["off","amber","red"] ), )

Many common specs in SC are in Spec.specs, and some specs that many MKtls share can be found in MKtl.globalSpecs:Spec.specs.keys; // get the names MKtl.globalSpecs.keys; MKtl.getSpec( \hidHat ); // look up a specific one

Elements in depth

Elements require an elementType describing which kind of physical thing it is, such as button, slider, joyAxis, mouseWheel, or any of:

MKtlElement.types

Multiple elements can go into nested groups, which is helpful for semantic clarity. For example, an MKtl with 6 sliders and 4 buttons, and two labeled buttons (play and stop) would look like this:( m = MKtl.new( \sliders_knobs, ( idInfo: \ex, protocol: \virtual, elementsDesc: ( elements: [ ( key: \sl, shared: ( elementType: \slider, ioType: \in, \spec: \midiCC ), elements: (1..4).collect { |i| (key: i.asSymbol) }), ( key: \bt, shared: ( elementType: \button, ioType: \in, \spec: \but ), elements: (1..4).collect { |i| (key: i.asSymbol) }), ( key: \play, elementType: \button, ioType: \in, \spec: \but ), ( key: \stop, elementType: \button, ioType: \in, \spec: \but ) ] ) ), false ); ); m.gui; m.elAt(\sl, 0).elemDesc; m.elAt(\sl, \1); // you can access the elements by hierarchical names: m.elAt(\play) m.elAt(\stop).value_(1) m.elAt(\bt) // the group of 5 buttons m.elAt(\bt, 0).value_(1) // one of them m.elAt(\sl).do(_.value_(1.0.rand)) // all sliders // one can also access them by direct names: m.dictAt(\sl_1).action = { |sl| "yo slider: % > %\n".postf(sl.name, sl.value) }; m.elAt(\sl, 0).valueAction_(1.0.rand); m.free; // free m's resources and remove it from MKtl.all

For full details on single element descriptions see also: Naming_conventions_in_element_descriptions

Finding descriptions for similar devices

Many devices already have description files, which are used by the MKtlDesc class. They can be found here:MKtlDesc.defaultFolder.openOS;

While developing new descs in files, you can also keep them inMKtlDesc.userFolder;

You are cordially invited to contribute desc files for any devices you have and find useful! For details on making descs for devices using MIDI, HID, or OSC, please read on here:

• How_to_create_a_description_file_for_MIDI
• How_to_create_a_description_file_for_HID
• How_to_create_a_description_file_for_OSC
• How_to_adapt_a_description_file