MIDI and consoles

This page covers connecting a keyboard, a pedalboard or a full console to Masterpiece: which MIDI inputs are open, which MIDI channel plays which manual, the dialog that sets the range, transposition and velocity of one manual, MIDI learn for stops, couplers, pistons and swell shoes, what Masterpiece sends back to a console (lamps, motorised faders, key echo, text displays), and where the mapping is stored. Playing a whole organ from one keyboard is covered on Split keyboard.

How a message reaches the organ

Every MIDI input that Masterpiece opens delivers its messages tagged with the input’s name. A mapping can match a message on four things: the input (Any device or one named device), the channel (any, or 1 to 16), the message type and its number.

• Notes on a channel that a manual claims play that manual. A manual claims a channel through its entries in the manual dialog or through the Keyboards rows of the MIDI tab. A note on a channel that no manual claims reaches the manual the organ itself assigns to that channel, so a partly mapped console plays every manual.
• Notes, controllers, program changes and system exclusive messages that a control claims operate that control: a stop, coupler, piston, shoe or one of the program’s own buttons. A claimed message operates only that control.

When several mappings could take the same message, the most specific one wins: device and channel named, then device only, then channel only, then neither.

Messages from a plug-in host, from a MIDI file played back, and from the on-screen keyboard and the clicks on drawn keys carry no input. Only mappings set to Any device match them.

A Universal Real Time master volume message (F0 7F <device> 04 01 <lsb> <msb> F7) sets the master volume with no mapping. A system exclusive message is accepted up to 256 bytes.

MIDI inputs and outputs

The MIDI tab of General settings (Settings > General settings > MIDI) holds the input and output choices. The same tab is also in Settings > Organ settings > MIDI; both edit the same mapping.

MIDI inputs

The MIDI inputs list has one tick box per input: the inputs the system reports (ALSA ports on Linux), then the inputs Masterpiece opens itself (see Inputs that Masterpiece creates). A ticked input plays; an unticked input is closed and its messages are dropped.

Masterpiece opens its inputs at start. Connect and switch on every console before starting Masterpiece; a console connected later does not play until the next start.

When another program holds an input

Windows gives a MIDI port to one program at a time, so an input that another program has open cannot be opened by Masterpiece. Masterpiece keeps the input ticked and shows it as <name> - in use by another program; opened when it is free. Ticking such an input opens a message box titled <name> could not be opened. A timer checks every 3 seconds, and the input opens as soon as the other program lets it go; the log then records midi: <name> is free now and has been opened. At startup the same case is logged as midi: <name> could not be opened (another program may be using it); it is tried again every few seconds.

How a console is identified

A mapping refers to an input by name, and by an identifier where the system supplies one that lasts:

Two consoles of one model keep separate mappings. The second is stored as <name>-1 and shown as <name> (USB 1.1.2) with its USB socket, or as <name> #2 where the system gives no socket. A console that moves to another USB socket keeps its mapping when its name is unique.

Inputs that Masterpiece creates

On Windows no program can publish a MIDI port. A loopback MIDI driver (loopMIDI, for example) provides one; Masterpiece lists it with the other inputs.

MIDI with JACK on Linux

Masterpiece opens a JACK client named Masterpiece MIDI with one input port, midi_in (full name Masterpiece MIDI:midi_in), for programs that send MIDI only through JACK. The client opens at startup when libjack.so.0 loads and a JACK server is already running. Masterpiece never starts a server. The port appears in the MIDI inputs list as JACK MIDI.

• Messages of up to three bytes pass. System exclusive messages do not arrive through this port.
• The connections made to the port are saved when Masterpiece closes, one JACK source port per line, in jack-connections.txt in the data folder. At the next start Masterpiece reconnects each source; a source whose program is not running yet is retried every 2 seconds until its port appears. A connection taken away by hand stays away once it has been restored.

MIDI output

The MIDI tab opens the output and closes it again when its window closes. Lamps, motorised faders, key echo and console displays therefore work while General settings (or Organ settings) is open. The choice is not kept between sessions: choose the output again after each start.

Feedback and learn options

One MIDI channel per manual

The Keyboards heading of the MIDI tab lists every playable manual of the loaded organ, one row each:

A choice takes effect at once and is saved with the organ. Two behaviours are worth knowing:

• Choosing a channel replaces all the manual’s entries in its dialog with one entry that covers the whole compass on that channel. Choosing a device replaces them in the same way, and removes the channel from any other manual mapped to the same device.
• Manuals may share a channel. A line under the rows lists them (Shared -- Channel 2: Great, Swell) after a change. One keyboard that plays two divisions is a coupler a player can build in this way.

Channels decide which division sounds, and the couplers work from that. A wrong channel makes a manual sound like another one.

Default console

A line beside the buttons reads Default for organs with no channels saved: Pedal 1; Manual 1 2; ... or No default: each organ starts from its own channels.

The dialog for one manual

Right-click a drawn manual on the console, or press Range, transpose… in the MIDI tab. The window is titled <manual> - MIDI and has three tabs: Keys, Pistons and Send.

Keys tab

The tab is headed What plays <manual> and lists the entries that feed the manual, one row each, described as Any device ch any keys C2 (36) to C7 (96) with any transposition, no velocity, short octave and debounce appended. A manual can have several entries. A keyboard split across two manuals is two entries (one on each manual), and a manual played from two consoles is two entries.

Every edit takes effect at once and is saved with the organ. A new entry listens on every device and every channel until narrowed, so set Console and Channel at once.

Pistons tab

The tab is headed Pistons that bring the <manual> to one of your keyboards. A piston added here makes the keyboard on one MIDI channel play this manual. A console with fewer keyboards than the organ has manuals reaches every manual this way.

To add one, press Add a piston…, play any key on the keyboard that should play this manual (the prompt reads Play any key on the keyboard that should play the <manual>...), then press the piston (Now press the piston (keyboard on channel N)...). The list shows each piston as Note 36 on channel 1 brings the <manual> to the keyboard on channel 2, or No pistons yet.

• Pressing the piston lets go of any notes held on that keyboard first, and keys still down sound on the new manual.
• The same button added on several manuals steps the keyboard through them, one press at a time, in the organ’s own manual order. One button can move several keyboards at once when it was learned for several channels.
• The pistons are saved with the organ. The assignment they change is kept for the piece; the next load starts from the assignment the player set by hand.

The tick box is read when Add a piston… starts the learn, so set it first. General Cancel also puts the keyboards back on their own manuals (MIDI tab) restores the keyboards on General Cancel.

Send tab

The Send tab of a manual sends every key played on the manual as a note to the MIDI output, for a sound module or a second program. One row sends to one channel.

The line at the top reads Sent to <output> or No MIDI output is chosen: choose one in Settings, MIDI. New event adds a row; the X button removes it.

Note-on velocity is the played velocity, at least 1; the note off goes out as a note-off message on the same channel.

MIDI learn for stops, couplers, pistons and shoes

Right-click menus

Right-click a drawn stop, coupler, tremulant or piston on the console. The menu’s section header names the object; the next lines list its current mappings, for example Note 36 ch 3 (toggles).

Right-click a swell shoe, wheel or slider to see MIDI window…, Learn: move a pedal, knob or fader, Closed position: where the pedal is now, Open position: where the pedal is now, Use the pedal’s whole travel and Clear mapping. The two position items set the ends of the pedal’s travel from the pedal’s last position, so move the pedal to the position first. A box reading Move the pedal first appears when Masterpiece has no position yet or both ends would be equal.

Right-click a piston in the Combinations window (generals, divisionals, cancels, the setter and the sequencer buttons) to map it: Learn, MIDI window… and Clear mapping. The setter offers Learn: held while pressed and Learn: toggles in place of Learn. Right-clicking again while a learn is armed cancels it.

The program’s own buttons have no object on the console to right-click. Use the learn buttons of the MIDI tab:

Each of these learns a button that fires on the press and ignores the release. A console may have several buttons for one action (two + and two - thumb pistons): each further learn adds a button. The sequencer’s first, last, ten-back and ten-forward moves, the generals and the setter are mapped from the Combinations window.

The line at the bottom of the MIDI tab reads N binding(s), followed by LEARNING: move a control now while a learn is armed.

Message types

The press threshold is the middle of the binding’s value window (above 63 for the default window of 0 to 127). A console that sends 64 for a press registers. Each distinct system exclusive message is one button; a console that sends its pistons this way maps each piston by learning it.

One message operates one object. Learning a message that another object already uses moves it to the new object. The exceptions are shoes, which share a controller (one pedal can move several swell boxes, and learning the same controller for a second shoe keeps the first), and manual buttons, which share a message to step a keyboard through several manuals. A shoe learns only from controllers; a key pressed while a shoe’s learn is armed plays as usual.

What a stop does with each message

A rocker tab, or a console with separate draw and cancel buttons per stop, is two rows: one Draws it and one Cancels it. Learning Draws it only leaves an existing Cancels it only alone, and the reverse, so both can be taught in turn. Any other learn replaces what the object had.

A new row in the MIDI window starts as Each press toggles for a latching switch and Held while pressed for a momentary one. Pistons and program buttons other than switches start as Fires when pressed. Learning is saved within a moment of the message arriving.

Shoes, wheels and sliders

A shoe is operated by a controller value, or by the velocity of a note (a sequencer can write the swell into the velocities of the notes it plays; the note-off does nothing). The binding maps the incoming range onto the control’s whole travel.

A console’s shoe seldom sends the whole 0 to 127, so set the two ends to the values the pedal actually sends. Values outside the window clamp to its ends. Only the span matters; the order in which the two values are entered has no effect, and Invert reverses the sense. Closed position: where the pedal is now and Open position: where the pedal is now in the right-click menu fill in the values from the pedal’s last position and set Invert when the closed end is the larger value. A program change or system exclusive message arrives with the value 127 and drives the shoe fully open.

The MIDI window for one object

MIDI window… opens a window titled <object> - MIDI with the tabs Receive, Send and Shortcut. The program’s own buttons (the player’s generals, divisionals, cancels, the setter, the sequencer) have no Send tab, because they light nothing on a console. Every edit takes effect at once and is saved with the organ; the program’s own buttons are saved in the console file (see The MIDI map files).

Receive tab

One row per message that operates the object. New event adds a row and starts listening at once. A row whose message is not set yet is skipped.

Add a row for every message that operates the object. A message already used by something else moves here.

Send tab

One row per message that Masterpiece sends to the MIDI output when the object changes. The line at the top reads Sent to <output> or No MIDI output is chosen: choose one in Settings, MIDI.

For a stop, coupler or piston, the message goes out whenever the object comes on or goes off, however it moved: the console, a piston, the crescendo or a click. For a lamp in a drawstop or an LED by a piston. For a shoe, the message goes out whenever the shoe moves. When the list changes, Masterpiece sends the present state of every lamp, which a console needs when it is set up.

New event adds a row. A new row starts from the object’s first receive row (type, number and channel), because a lamp usually answers on the message that operates the stop; a shoe row starts as a controller.

With none in When off, nothing goes out when the stop goes off. A program change has no off: it sends its number when the stop comes on and nothing when it goes off. For a shoe, Program change sends the scaled value as the program number. System exclusive is listed but is received only; a row of that type sends nothing.

Shortcut tab

A key of the computer keyboard that operates the object.

Click the key button (it reads None or the current key), then press the key, with Ctrl, Alt or Shift if wanted. The button reads Press a key… while it waits; Escape leaves the setting as it was. Clear removes the key. The key works while the console window is in front. One key can operate several objects at once. Saved with the organ.

A stored key operates organ switches (stops, couplers, tremulants and the organ’s own pistons) and shoes. The tab also appears for the player’s generals, divisionals, cancels, setter and sequencer buttons; a key stored there has no effect.

Sending to a console

Three things send to the MIDI output: the rows of the Send tabs (lamps, faders, key echo), the echo option of the MIDI tab, and the text displays. All of them need a MIDI output.

Console displays

Many consoles have text displays on the jamb that a system exclusive message drives. The Display tab of General settings (Settings > General settings > Display, heading Console display) describes one display and what it shows.

Each message is F0 <prefix> <display number> <line number> <text> F7: the prefix bytes, one byte for the display, one byte for the line (counting from 0), and the line’s text as ASCII padded with spaces to the line width. The prefix, display number and line width belong to the console hardware, so the tab asks for them.

7D is the manufacturer id that the MIDI specification reserves for non-commercial use; it is the default because a console’s own prefix is not known. Only lines whose text changed are sent, twice a second at most. Letters with accents are written with the accent removed (ä as ae, ß as ss, Kraków as Krakow), because system exclusive carries seven bits per byte and a byte above 7F would end the message. Characters with no Latin equivalent become ?.

Changes in this tab take effect at once. The setup is not saved and starts switched off each time General settings opens. The display is updated while General settings is open, and the MIDI output must be chosen first. The Combination set line currently shows a blank line.

The MIDI map files

A mapping is stored in the player’s data folder, never inside a sample set:

Two files in the midi folder of the data folder hold it:

<organ> is the organ’s name followed by its unique organ id, for example Nancy-12345. An organ that declares no id uses its name and a hash of its path. Renaming or moving the sample set keeps the file.

Every change in a MIDI dialog is saved at once, and a learn is saved within a moment of the message arriving. Save mapping in the MIDI tab writes both files. Clear mapping removes every binding, send and shortcut from memory and keeps the manual entries; the files change at the next save.

When an organ loads, its .mpmidi file is read, then console.mpmidi. An organ with no file starts from the default console and the organ’s own channels. A mapping carries over to another organ or computer by copying the file to the midi folder under the other organ’s file name; devices travel by name.

When an organ loads, Masterpiece repairs a file that names a manual the organ lacks, or lists an identical manual entry twice. It logs midi: repaired the saved mapping and keeps the original beside the new file as <organ>.mpmidi.before-repair.

The files are plain text, one record per line, with # for comments. A binding line has these fields:

<kind> <channel> <number> <target> <id> <latching> <invert> <trigger> <closed> <open> <device> [<identifier>]

Other lines start with manual (a manual entry: manual id, channel, low key, high key, transpose, low velocity, high velocity, ignore velocity, short octave, debounce, device), send (target, id, kind, channel, number, low, high) or shortcut (target, id, step, key). Edit through the dialogs; a line that cannot be read is skipped and the rest loads.