Documentation Wiki rss-feed

Keygroup


Name

Keygroup:

image:keygroup_expanded.png

788
keygroup

Description

Keygroups contain a group of keys in a user defined orientation, thus providing a way of dividing and remapping the Eigenharp keyboard and allowing the user complete control over the orientation and direction of notes.

The Keygroup Agent has two primary functions:

  1. It allows for the division of the Eigenharp keyboard to provide easy access to functionality within EigenD.

  2. It allows keyboard divisions to be set into different modes, which can then be arranged hierarchically.

The keys will be numbered according to the order in which you choose the keys - the first key you choose will be one, second will be two etc. This numbering is important, and is used in a number of cases by other Agents - e.g. the Scaler uses the first key as the tonic of the scale, and the scale will ascend in conjunction with the ordering of the keys within you Keygroup.

Ports

Strip Position inputs 1 and 2

  • Name:

133 1464 116 ?
strip position input X

  • (X is the strip position input number - it can be 1 or 2)
  • Input
  • Type: Number
  • Range: -1 to 1

Strip position inputs are normally used to receive a relative strip controller position from an upstream Agent (either another Keygroup or from the Keyboard Agent).

Breath input

  • Name:

134 116
breath input

  • Input
  • Type: Number
  • Range: 0 to 1

The breath input is normally used to receive breath controller information from an upstream Agent (either another Keygroup or from the Keyboard Agent)

Octave

  • Name:

324
octave

  • Input, Set
  • Type: Number
  • Range: -1 to 9

Octave sets the keygroup's octave. When playing a keygroup that has an octave set, downstream Scalers automatically adjust their octave to match that of the keygroup (unless the Scaler's 'override' parameter is set).

Tonic

  • Name:

145
tonic

  • Input, Set
  • Type: Number
  • Range: -1 to 9

Tonic sets the tonic of the keygroup's scale. When playing a keygroup that has a tonic set, downstream Scalers automatically adjust their tonic to match that of the keygroup (unless the Scaler's 'override' parameter is set).

Absolute Strip inputs 1 and 2

  • Name:

8735 133 116 ?
absolute strip input X

  • (X is the strip position input number - it can be 1 or 2)
  • Input
  • Type: Number
  • Range: -1 to 1

Absolute strip inputs are normally used to receive an absolute strip controller position from an upstream Agent (either another Keygroup or from the Keyboard Agent).

Pedal input 1, 2, 3 and 4

  • Name:

161 116 ?
pedal input X

  • (X is the pedal input number - it can be 1, 2, 3 or 4)
  • Input
  • Type: Generic
  • Range: None

The pedal inputs are normally used to receive pedal data from an upstream Agent (either another Keygroup or from the Keyboard Agent.)

Key input

  • Name:

114 116
key input

  • Input
  • Type: Key

The key input is normally used to receive key position and hardness signals from upstream and processes them accordingly.

Pressure input

  • Name:

128 116
pressure input

  • Input
  • Type: Number
  • Range: 0 to 1

The pressure input is normally used to receive key pressure signals from upstream and processes them accordingly.

Roll input

  • Name:

131 116
roll input

  • Input
  • Type: Number
  • Range: -1 to 1

The roll input is normally used to receive key roll signals from upstream and processes them accordingly.

Yaw input

  • Name:

132 116
yaw input

  • Input
  • Type: Number
  • Range: -1 to 1

The yaw input is normally used to receive key yaw signals from upstream and processes them accordingly.

Base note

  • Name:

1812 124
base note

  • Input, Set
  • Type: Number
  • Range: -20 to 20

The base note is a value (in semitones) between -20 and 20 - the base note determines which note of the scale corresponds to key 1 of the keygroup.

Controller input

  • Name:

1775 116
controller input

  • Input
  • Type: Generic

The controller input is used to pass on information that changes infrequently and usually carries configuration data from an upstream Agent, for instance Keygroup octave, tonic, scale, mapping, ...

Mode key input

  • Name:

2318 114 116
mode key input

  • Input
  • Type: Key

A connection is made to the Mode Key Input from the key output of an upstream agent, typically an instrument or another keygroup. A mode key is used to switch between keygroup outputs. The position of the mode key is specified based on the layout of the upstream agent, using the Mode Key Column and Mode Key Row ports.

Mode key column

  • Name:

2318 114 1156
mode key column

  • Input
  • Type: Integer

To determine whether a keygroup's mode key is pressed, the physical key data coming in on the Mode Key Input port will be compared with the values in the Mode Key Column and Mode Key Row ports. When they correspond, the mode key will activate and the switching behaviour will be available.

Mode key column end relative

  • Name:

2318 114 1156 447 8821
mode key column end relative

  • Input
  • Type: On/Off
  • Default: Off

When turned on, the mode key column number will be counted from the opposite end, meaning that instead of 1 being the first column, 1 becomes the last, 2 the second last, and so on.

Mode key row

  • Name:

2318 114 8612
mode key row

  • Input
  • Type: Integer

See the documentation of Mode Key Column above for more information.

Mode key row end relative

  • Name:

2318 114 8612 447 8821
mode key row end relative

  • Input
  • Type: On/Off
  • Default: Off

When turned on, the mode key row number will be counted from the opposite end, meaning that instead of 1 being the first row, 1 becomes the last, 2 the second last, and so on.

Mode key controller input

  • Name:

2318 114 1775 116
mode key controller input

  • Input
  • Type: Generic

The controller input is used to pass on information that changes infrequently and usually carries configuration data from an upstream Agent, for instance Keygroup octave, tonic, scale, mapping, ... This will be used to evaluate the coordinates of the mode key.

Blink

  • Name:

8836
blink

  • Input, Set
  • Type: Number
  • Range: 0 to 20; default = 0.5

Light output

  • Name:

3122 125
light output

  • Output
  • Type: Light

The light output is a connection made against the normal flow of signals to send data back to the Keyboard Agent to determine which LEDs should be lit at the appropriate time.

Nouns

Course:

Courses are a subdivision of Keygroups which allow the user to define an offset between groups of keys within a Keygroup. This allows Keygroups to exhibit behaviour similar to that of a stringed instrument, such as a guitar - i.e. each string is a certain distance apart in pitch from the previous string.

Course Offset:

The offset between Courses can be defined in both semitones and scale increments.

Keygroup Output and Mode Key:

Keys within a Keygroup can have two types of behaviour - they can either be 'active' or 'switching'. The behaviour of the Keygroup as a whole can be controlled by a further key called a Mode Key.

When a Mode Key is pressed, the keys within the Keygroup exhibit switching behaviour. A number of LEDs will light up adjacent to keys within the Keygroup - each illuminated LED represents a mode available for selection. The currently selected mode is represented by a green LED, whilst the other modes available for selection are represented by red LEDs.

A mode is selected by holding down the mode key, pressing the key adjacent to the LED representing the desired mode and then releasing the Mode Key.

When a Mode Key is not pressed, or when there is only one mode and therefore no requirement for a mode key, the Keygroup exhibits active behaviour. The selection of a mode routes the EigenD key performance data (such as pressure, roll and yaw) from the active Keygroups to specific Keygroup Output(s). The data from other EigenD controllers (such as strip controller, breath controller and pedal data) is combined with the key data and also sent to the active Keygroup Output(s). Keygroup Outputs are connected to Agents downstream, which then use the active performance information in a certain way. This could be playing an instrument, triggering an action e.g. starting the Metronome (also see Talker) or indeed controlling another Keygroup. Keygroup hierarchy is achieved when one Keygroup is used to control another Keygroup.

The outputs of a Keygroup are created by the user on demand. The number of outputs created depends on the required number of destinations.

Keygroup Scale, Tonic and Octave:

As you may have read in the Scaler article, each Keygroup can have its own independent scale, tonic and octave. This allow for example independent tuning of the same instrument across different parts of the Eigenharp keyboard. The Belcanto used to set the scale, tonic and octave for the Keygroup is exactly the same as the Scaler - please see the Scaler article for more information.

Verbs

Create:

111
create

The 'create' verbs is used to create Keygroup Outputs for a Keygroup.

Choose:

122
choose

The 'choose' verb is used to choose keys within a Keygroup or within a Course.

It is also used to choose which output of the Keygroup is active.

Un Choose:

6 122
un choose

The 'un choose' verb is used to cancel choose mode without making any changes to the mappings.

Clear:

228
clear

The 'clear' verb is to clear all previously chosen keys from a Keygroup.

Add:

62
add

The 'add' verb is used to add specific keys or ranges of keys to a Keygroup or Course.

Examples:

Assuming you already have Keygroups contained within your setup, before using the Belcanto commands below, make sure you have the desired Keygroup within your conversation using

788 ? 1131
keygroup X listen

where X is the number of your desired Keygroup.

Choosing keys for a keygroup:

To choose the keys for a Keygroup use:

114 122
key choose

EigenD will now enter 'choose mode'. You will see a number of LEDs light up - the LEDs adjacent to keys already contained within the Keygroup will light green, and the LEDs adjacent to keys not currently within the Keygroup but available for selection will light red.

Press a key to choose it for your Keygroup. The LEDs will now change - newly selected keys will now be accompanied by a green LED, whereas keys that were previously within the Keygroup will now light amber. The LEDs adjacent to keys that are available for selection but neither not currently selected nor previously part of the Keygroup will remain red.

Once you have selected all the desired keys for your Keygroup, press the last key twice. All the LEDs will go out, confirming that you have now exited 'choose mode'.

Courses are created at the point of the key choosing process by using a variation on the normal Belcanto phrase for key choosing.

You need to decide on the number of courses and the keys that you wish to include within the courses before you start the choosing process.

Choosing keys for courses

To choose the keys for Course 1, use

114 65 11 122
key as 1 choose

EigenD will now enter 'choose mode' - you will have already encountered this in the above example.

You will see a number of LEDs light up - the LEDs adjacent to keys already contained within the Course will light green, and the LEDs adjacent to keys not currently within the Course but available for selection will light red.

Press a key to choose it for your Course. The LEDs will now change - newly selected keys will now be accompanied by a green LED, whereas keys that were previously within the Course will now light amber. The LEDs adjacent to keys that are available for selection but neither not currently selected nor previously part of the Course will remain red.

Once you have selected all the desired keys for your Course, press the last key twice. All the LEDs will go out, confirming that you have now exited 'choose mode'.

You now need to repeat the process for each Course, replacing '1' in the Belcanto phrase above with the number of the desired Course.

Setting the offset between Courses:

The Belcanto phrase below sets the starting note of the specified Course as a note with a distance of four semitones higher than the starting note of the previous course:

1471 ? 1436 23 14 4177 67
course X offset to 4 semitone set

The Belcanto phrase below sets the starting note of the specified Course as a note with a distance of four scale steps lower than the starting note of the previous course:

1471 ? 1436 23 26 14 1241 67
course X offset to - 4 interval set

There is an upper and lower limit of 500 semitones and 9500 scale steps.

Physical and musical mapping

Selecting the keys that are part of the Keygroup, specifies how the position of an upstream key is changed when that information travels through the Keygroup. We've identified two totally independent uses of key position: a physical one and a musical one.

A physical key position is typically used for Talkers and Controllers, you usually expect these to stay at the same location at all times.

A musical key position is typically used for playing notes, every musician has a preference for note layout, they might run down the keyboard, across the keyboard, from top to bottom, from bottom to top. They might run along the columns of the keyboard or across it, or maybe even be arranged in circles or other creative shapes.

By allowing the musical key mapping to be changed independently of the physical mapping, musicians are able to customize their playing experience without changing the instrument's control or configuration mechanism.

Key position nomenclature (column, row, course, key)

A physical position is specified with a row and a column. The keyboard agents define the columns as running along the length of the instruments: there are two columns on the Pico's keyboard, four columns on the Tau's main keyboard, and five columns on the Alpha's main keyboard. The rows in the keyboard agents are defined to run across the keyboard: there are nine rows on the Pico's keyboard, sixteen rows on columns one and two as well as twenty rows on columns three and four of the Tau's main keyboard, and twenty-four rows on the Alpha's main keyboard.

A musical position is specified with a course and a key. Courses are created when you logically change the musical layout of keys. The Keyboard agent of each instrument has only one course and the keys are a long series of sequential numbers that run along the rows of the keyboard, following one row after the other.

Note that as soon as the key data travels through a Keygroup , the orientation of columns, rows, courses and keys can be completely modified and maybe not even be linear or sequential.

Adding keys to a Keygroup/Course

As well as choosing keys using 'choose mode', you can also add keys to a Keygroup in Belcanto.

To add a musical mapping:

1471 ? 114 ? 23 1471 ? 114 ? 62
course X key Y to course X key Y add

where X is the desired course number and Y is the desired key number.

You can also add physical mappings to your Keygroup:

1156 ? 8612 ? 23 8612 ? 1156 ? 62
column X row Y to row X column Y add

where X is the desired column number and Y is the desired row number.

Clearing keys from a Keygroup:

The Belcanto phrase below clears all musical keys within the specified Keygroup.

8638 228
musical clear

This phrase clears all the physical keys:

8637 228
physical clear

It's also possible to clear specific columns or courses with the following Belcanto:

1471 ? 228
course X clear

where X is the desired course number

1156 ? 228
column X clear

where X is the desired column number

Creating a Keygroup Output

You can create an output using

125 ? 111
output X create

where X is a number that is used to identify the output. The key position by which the output can be selected when the Mode Key is depressed is specified by providing values for the Key Column and Key Row ports of the output itself. By default, these are 0, meaning that the output can't be selected through the Mode Key.

Choosing an active Keygroup Output

You can tell the Keygroup to activate a single output and deactivate all others:

125 ? 122
output X choose

where X is the number that is used to identify the output.

Enabling a Keygroup Output

If you don't want to deactivate all other outputs, an output can directly be enabled:

788 125 ? 5584 67
keygroup output X enable set

or disabled:

788 125 ? 5584 6 67
keygroup output X enable un set

It's also possible to toggle an output's enable status:

788 125 ? 5584 441 67
keygroup output X enable toggle set

where X is each time the number that is used to identify the output.

Setting the Base Note

The base note parameter allows you to start the scale of your playing Keygroup from a note other than the scale tonic. It is defined as a offset in scale increments from the tonic in Belcanto with the following phrase:

1812 124 23 ? 67
base note to X set

where X is the number (positive or negative depending on whether you need the offset to be higher or lower than the current tonic) in scale increments from the current tonic. For example, in C major if you used the following Belcanto phrase:

1812 124 23 11 67
base note to 1 set

it would set the first playing note of your Keygroup to be the D above the current tonic C.

Removing Keygroup Scale, Tonic and Octave information

As explained above, the Keygroup can have its own Scale, Tonic and Octave set independently from the Scaler. If you have set this within the Keygroup, you can remove Keygroup tuning information using the Belcanto command below - the instrument will revert to using the Scale, Tonic and Octave from the Scaler:

6 67
un set

See also