XY Pads & Keyboard - XML Edit mode

Pads on the XY-Pads and Keyboard screens can be customized in terms of the MIDI they generate and their visual appearance (colors, labeling etc.). The XY controllers are not directly editable, but they can be overlayed with user defineable sets of controls. While this feature is still evolving, it provides the basics for creating your own custom controllers.


From the menu select "Edit Pads" and touch a pad or control to switch the screen into edit mode. On the Keyboard screen the menu entry will only be present when any pads are visible on screen.

Launchpads can be edited right away. To create an overlay for the XY controllers first select a preset, then edit it to your needs.

All edits are done in a popup dialog that lets you edit properties of single pads resp. single elements of an XY overlay.

User edits are stored in the currently selected xml file that also holds MIDI mode settings for the mixer screen etc. See general MIDI mode documentation for more info on xml mappings.

The properties dialog will have slightly different content depending on the currently edited control. There will be MIDI, Text and Color tabs for pad


controllers while XY overlays will have the Color tab replaced by selectors for the type of control shown (fader, pitchwheel, encoder etc). In both cases there is an additional "Global" tab that holds a preset selector and eventually some options affecting all elements of the edited screen half or block of pads.

Edits will only take effect and be written to the xml document when confirmed with the OK button. Multiple components can be edited before confirming, though: The target component can be changed by touching another one directly or you can use the arrow buttons ( ◀︎ ▶︎ ) in the dialog's header to step through components.

The dialog itself can be moved around with the Trigram symbol ( ☳ ) in the middle of its header. The menu icon on the left ( ☰︎ ) gives access to copy / paste options that work in context of the current tab. It also provides a shortcut to the currently edited control in the xml document itself.

Use the "Done" button or touch the screen's menu again to exit edit mode. (Note that the "Done" button does NOT confirm edits! Neither does the menu.)




XY-Pads screen specific

Some of the general preferences carry over into edit mode and keep affecting the basic setup of what appears on screen: The "XYPad Shows" preference keeps determining the overall layout of the screen (i.e. whether you will see two XY or two pad controllers or a combination of both). Equally the "Launchpad Count" preference remains responsible for the number of pads that appear in visble pad controllers.

Undoing edits

Entering edit mode will set a launchpad's layout to "XML defined". To revert to one of the presets use the pad's "Note Layout" preference in the app settings.


Installed XY overlays can be removed by selecting the "XY-Pad" preset in the edit dialog or toggled on and off by additional controls that will be added to the screen's floating transport.




 Editable properties / Editor tabs


MIDI

Configures the MIDI data sent by the edited pad or slider. The popups represent MIDI channel, message type (status byte) plus one or two data bytes depending on the selected message type. The display format of the last two popups can be changed between decimal, hex and note name by touching the "Data..." labels above them.

Entries in the "Type" popup from "Bank + Prg. Change" onwards will change the appearance of the dialog:

Bank / Prg. Change allows to attach combined bank and program change commands with both MSB and LSB fields for the bank part to a single touch action. Both the LSB part of the bank change command as well as the Program Change can be ommitted by setting the resp. popup to their last ("Ignore") entry.

Sysex will in most cases consist of more than three arbitrary bytes and needs to be entered via a multiline textfield. Alternatively you can import sysex from the internal library or from .syx files selectable through a standard file picker (Android 4.3 and larger). You can also use this field to attach System realtime commands or combinations of multiple MIDI messages to a pad.
XY overlays can modify sysex like the mixer's MIDI mode (See xml sample. Only the fader related parts are supported here).

MIDI Channel (Pads only): Forces all pads configured to send standard MIDI to a given MIDI channel (not currently overwritable with individual settings). If the "All" option is checked, this will also affect standard MIDI controls in an eventual XY overlay or a second xml customized pad.



Data Offset (Pads only): Adds the given value to the individually configured ones for all (standard MIDI) pads. This can be used for some sort of "controller-side bank switching". Unlike the "MIDI channel" modifier this option only affects the screen half it is invoked in. Note that the data field is context dependent: While it will usually be "Data 1" (ie. Note, CC or program number), pads set to bank select CCs will have "Data 2" modified. Also be aware that MIDI still uses 7bit values. The actual output may be clamped if it would exceed the maximum range.

DAW Command lets you attach standard DAW Control functions to a pad. The displayed popup will contain command names depending on the app's "Sequencer" preference. For sliders in an XY overlay this will only be channel and master volume. Note that these commands will be sent out via the app's first MIDI port.

App Navigation (Pads only) can be used to make pads switch to other screens in the app. This also provides a way to toggle the xy overlay on and off in mixed setups.

The ◀︎ button in the lower row resets any of these extensions to standard MIDI.

Button mode & groups (Pads only):

The group of radiobuttons underneath the MIDI popups determines how and when a pad will send its MIDI when touched. See general MIDI mode documentation for button-mode details. Note that some MIDI data types are always sent as "Single": There is no "off" state for Program and Bank changes, Sysex or most of the non-MIDI commands.

The "Excl.Group" popup lets you combine several pads into virtual groups out of which only one button will then be selectable at a time. This primarily affects the pad's visual representation. A pad's button-mode setting (Momentary,..,Single) remains in effect. "Toggle" pads that were the selected pad in a group will send their "off" state when another member of the group is pressed.




Text

Sets a pad's label along with some basic font size and alignment options. Linebreaks are supported, the textfield will expand when you hit enter. Unicode symbols can be used by entering codepoints in "\u....", "U+...." or HTML entity ("&#x....;") notation, but availability and rendering of unicode glyphs depends much on system version and manufacturer preferences.

The textfield may be prefilled by some of the custom MIDI types described before, namely "DAW command", "App Navigation", "MIDI Channel" and "Data Offset" if no text was previously set.

Labels for sliders will be displayed underneath the slider followed by a representation of the control's current value. If the label textfield is left empty, no value will be displayed. Sliders set to control DAW channel volumes will use MCU or HUI input for the labels if the label text contains "MCU" or "HUI".
Colors (Pads only)



The three color fields bring up a colorpicker to set a pad's background, text and highlight colors. When you check the "Apply to all" box, selected colors will be written to the parent xml node and will apply to all pads that do not have individual colors set. The "Hit" color will be used both when a pad is touched as well as for indicating MIDI input unless there is also a velocity code set.

Velocity codes are used to map incoming MIDI velocity values to colors. This is commonly used with grid controllers to


reflect clip state and to mirror clipcolors on external controllers. A few velocity codes are predefined in the app and you can define additional ones in the xml.

To reset a color to its default value (or an eventual global setting), touch and hold the color field.




 Control (XY Overlay only)




Here you can add and remove controls, change their type and set type-specific properties.

To initially create an overlay for the XY controller first select a preset.

Controls will by default be layed out in a horizontal orientation. Rotary controls and buttons are added in vertically stacked groups (effectivly filling another fader slot spacewise). See Layout for more on layouts.

Once a group has been added, you can access its children (change their type, add / remove children etc.) with an additional popup. Touch the labels preceding the popups to target either the group itself or its child components.

Selecting a different control type will by default change the type of the currently selected one when "OK" is touched. Check the "Insert" or "Append" boxes in the dialog's lower half to add an additional control instead. New controls will then either be inserted before the selected one or appended at the end.

To remove a control, set the popup to "None (Remove)".

Overlays will show a maximum of 9 (linear) controls at a time. If there are more defined, the overlay will be scrollable.
Controls available on the top level and their specific options:

Fader & Small Fader: Standard faders as used on the DAW Controller and Keyboard screens.
  • Invert - Inverts the MIDI output (sends 0 when fader is up, max value when down
  • Centered - Initially shows with knob at 50%. Resets to 50% on double-click.
  • Allow Jumps - Move knob without directly touching it. This disables double-click resets when also 'centered'.
Pitchwheel: Pitch / Modulation wheels as used on the Keyboard screen.
  • Same options as faders. Allows jumps by default. Will be centered by default if MIDI status is Pitchbend.
Drawbar: Classic (Hammond) organ style control.
  • Step: Moves in eight steps and only sends MIDI when high nibble changes.
  • Black: Render with a dark knob.
Space: Adds some empty space. No further options.

Group (...): Adds a group prefilled with the type noted in brackets. Child components can be modified afterwards.


Groups can contain all of the 'top-level' controls described before (with identical options) and additionally:

Button: Simple button as used throughout the app.

Transport Button: Larger button as used on the Transport resp. tablet DAW Controller screens. "Title" here takes a number between 0 and 11 as an index into standard transport icons.

Encoder: Endless encoder or potentiometer as used on the DAW Controller screens.
  • Invert - Inverts the MIDI output (inverting the 'direction' in endless mode)
  • Centered - Initially shows at 50%. Resets to 50% on double-click. No effect in endless mode.
  • Operation - Touch interaction options. 'Relative (Circular)' has no effect in endless mode.
Jogwheel: Jogshuttle style control as used on the Transport screen &
Scrubwheel: DJ controller style wheel.
  • Invert - Inverts the MIDI output (inverting the 'direction' in endless mode).
Rotary controls switch between endless and linear mode depending on their MIDI settings: With a 'Control Change' (CC, 0xBn) status byte, values of 0 - 2 for the second databyte select between 3 endless modes (see MIDI Mode). Higher values make the control 'linear' (and define the range for potentiometers).



Layout

This is work in progress. Layout options are sparse. Most of them are not accessible via the UI so far, but need to be written directly into the xml. Additionally the app will make assumptions about the distribution of space for controls in mixed groups that may not be ideal at times.
No attempts are made to automatically fit layouts to different screensizes or aspect ratios beyond scaling the topmost level to fill available space vertically (resp. horizontally for vertically oriented layouts).



The default layout direction is horizontal with linear controls oriented vertically and appearing next to each other like faders usually do.

An orientation="1" attribute can be added to the overlay node to change this. Controls will then be stacked vertically. Faders, pitchwheels etc. will be flipped by 90 degrees and appear horizontally.

Groups always flip the layout direction. A group in a horizontal layout will stack its children vertically, a group in a vertical layout aligns its children horizontally. A group inside a group will flip the direction again.



Groups and (some) controls can use a margin="L[,T,R,B]" attribute to add space around them. Values are interpreted as 'device independent pixels'.

Groups additionally can use padding="L[,T,R,B]" to define some inner spacing

The entire overlay, groups and most controls will interpret the first value in a color="0xFFFF0000" attribute as their background color (very red here). Some controls in the Pseudo Hardware skin will also read a second (hit or accent color) and third (text color) value.



Global / Presets

For pad controllers this tab contains a display field for global color and velocity code settings. Global colors are not editable here (see "Colors" above instead), but can be cleared like individual ones with touch and hold gestures on the field. Global colors and velocity codes apply to all pads that do not have individual settings.

The "Preset" popups contain basic presets that will change all individual pads or controls in one go. This may well be the only thing you ever need to touch, but presets also serve as starting points for individual setups. Some of them also contain examples for global settings, exclusive groups etc.

Individual setups can be saved and reloaded using the Import / Export icons. On import your settings will be merged into the global xml file.



Up to 64 Program Change buttons (MIDI values 0 - 63) in a single large exclusive group.

MIDI channel is initially selectable.
Up to 64 Program Change buttons (MIDI values 64 - 127) in a single large exclusive group.

MIDI channel is initially selectable.
Pads are divided into two groups calling bank selects resp. program changes.

MIDI channel is initially selectable.

This is the default setting for the pads underneath the keyrange selector on the Keyboard screen.
First 8 pads call DAW transport functions and send to the first MIDI connection.

Remaining pads use a standard bottom up drumpad layout on MIDI channel 10 and send to the second MIDI connection.

This is the default setting for the right block of pads underneath the keyboard itself on the Keyboard screen.
Collection of channel mode utility CCs (Omni mode, Reset controllers etc.).

MIDI channel is initially selectable.
Octave per row (resp. start of an octave) in top down orientation.

MIDI channel and root note are initially selectable.
Octave per row (resp. start of an octave) in bottom up orientation.

MIDI channel and root note are initially selectable.
Hex strip (resp. <= 16 notes) per row in top down orientation. Common layout on hardware grid controllers.

MIDI channel and root note are initially selectable.
Hex strip (resp. <= 16 notes) in bottom up orientation. Common layout on hardware grid controllers.

MIDI channel and root note are initially selectable.
Scaled notelayout in top down orientation.

MIDI channel, scale and root note are initially selectable.
Scaled notelayout in bottom up orientation.

MIDI channel, scale and root note are initially selectable.
This is not truely a preset. Instead it removes a defined overlay and resets an XY-Pad to its default uncovered state.
Standard drawbar controller using CCs 12 - 20.

MIDI channel is initially selectable on the XY-Pads screen. On the keyboard screen the MIDI channel will follow keyboard channel selection.
Secondary drawbar controller using CCs 21 - 29.

MIDI channel is initially selectable on the XY-Pads screen. On the keyboard screen the MIDI channel will follow keyboard channel selection.
Scrollable two bank drawbar controller using CCs 12 - 29.

MIDI channel is initially selectable on the XY-Pads screen. On the keyboard screen the MIDI channel will follow keyboard channel selection.
Pitch and Modulation wheels plus 4 sound controllers (CC 71 - 74).

MIDI channel is initially selectable.

This preset is not available on the keyboard screen.
16 channel MIDI volume mixer (i.e: CC 7 on all 16 channels).

This preset is not available on the keyboard screen because it would clash with the screen's channel following principle.
Collection of CCs that the original MIDI 1.0 specs loosely predefine as global sound and effects controls. Should work with most standard keyboards / sound modules, but these definitions are not mandatory and different manufacturers may support them in varying depth.

MIDI channel is initially selectable on the XY-Pads screen. On the keyboard screen the MIDI channel will follow keyboard channel selection.
A bunch of rotary controls in standard potentiometer (i.e: not endless) mode starting at CC 1.

MIDI channel is initially selectable.
Rotary controls in encoder (i.e: endless or increment/decrement) mode. Starts at CC 0.

MIDI channel is initially selectable.
8 faders generating MCU or HUI volume commands depending on the selected DAW (Pro Tools == HUI).

Sends via the app's first MIDI port.
8 faders plus a master fader generating MCU volume commands.

Sends via the app's first MIDI port.
Basic DJ controller with scrubwheels, pitch controls, a crossfader, EQ knobs and some utility buttons.

Defaults to emulating a Hercules RMX 2 controller. [ Setup example for Mixxx ]



 XML - XY Pads

All user edits are stored in the "xy-pads" node of the currently selected XML file. A default file will have been created on your device's SD card upon installation of the app, but you can have multiple files there and select the one to use via the "XML File" preference at Setup / MIDI Utilities / XML Mappings. That preference also provides access to a simple in-app xml editor where you can edit the raw xml, create copies etc.

All required subnodes will be created if not already present when you set a pad's notelayout to "XML defined" in the setup or start editing via the menu. Initial pad settings will be taken from any eventually present "larger" xml-layout or - if non is present - will be copied from the previously set preset layout, taking the "Basenote" setting into account.

Depending on the overall screenlayout the "xy-pads" node will have one or two "launchpad" and / or one or two "xy-pad" subnodes, where an "id" of 0 always refers to the upper resp. left screen-half and 1 to the lower / right one:


A "launchpad" node can hold up to 6 "notelayout" nodes for different numbers of pads (id 0: 1*1,...,id 5: 8*8) which then contain the actual "pad" nodes:



"xy-pad" nodes can have an "overlay" subnode which then contains "control" nodes, defining the sliders and their properties. Groups are themselves "control" nodes that contain "control" child nodes:



Possible attribute values include:
  • "midi": Comma separated list of hexadecimal byte values
  • "color": Comma separated list of 32bit hex color values
  • "vc": Integer index into defined velocity codes
  • "title": Label string
  • "tf": Integer text flags
  • "mode": Integer flags for button modes, slider inversion etc.
  • "grp": (launchpad/notelayout/pad only): Integer group index
  • "type" (xy-pad/overlay/control only): String control type
Examples:






 XML - Keyboard

Once pads or sliders have been edited the xml will contain a 'keyboard' node with three 'launchpad' and a 'sliders' subnode.

Launchpad id 0 refers to the pads over the keyboard. Id 1 (left under-keyboard) is the pad block belonging to the Program Change tool and available in both portrait and landscape mode, id='2' refers to the right under-keyboard one.

There are no 'notelayout' subnodes on the keyboards's 'launchpad' nodes, 'pad' nodes are direct children to the 'launchpad' nodes.

The 'sliders' node is an exact equivalent to the 'overlay' nodes on the XY-Pads screen.



Attributes on pad and control nodes are identical to those described above for the XY-Pads screen. The Keyboard screen may additionally add a global 'fc' (Force Channel) attribute to launchpad nodes (its pads otherwise follow the keyboard's MIDI channel settings).