# GrandOrgue Help

## Welcome

Welcome to the manual for GrandOrgue.

- Click the Contents tab to display a list of important topics about the program.

- Click the Index tab to display an alphabetical listing of topics.

- Click the Search tab to search for a specific word in the help system.

## Getting Started

### Introduction

GrandOrgue allows the user to load and play virtual pipe organs. Using sample sets, GrandOrgue is able to combine the individual pipe sounds and organ behaviors to simulate a variety of pipe organs.

### Sample Sets

GrandOrgue is capable of loading and faithfully reproducing a variety of sample sets. The sample set format is described later in this manual. The format is backward compatible to Hauptwerk™ version 1 sample sets. As such, you won't be able to do anything at all with GrandOrgue without at least one sample set. Sample sets generally come packaged or with installers. By default, the software loads organs from "Organs" in your documents folder, but you may store sample sets wherever is convenient and space permits. Please look at https://github.com/GrandOrgue/grandorgue/wiki/Sample-Sets for more information.

Some Hauptwerk™ Organ Definition File keywords are not used by GrandOrgue and are reported in a pop-up window. These warning messages can be safely ignored

### Organ Packages

An organ package is a self-contained archive file that can be opened directly by GrandOrgue. It does not need to be formally installed on disk. It can contain more than one sample set.

The software knows about a dedicated folder (by default: "Organ Packages" in your documents folder) where organ packages can be dropped. Packages dropped in that directory are automatically registered by GrandOrgue.

See The GrandOrgue organ package format for a detailed description of the organ package file format.

### Features

- High definition output with supporting hardware

- High precision internal processing for optimal sound quality

- Integrated software reverberation

- Polyphony management to avoid CPU overload

- Low latency output with proper hardware support

- Quick and easy MIDI setup, including "Listen for Event" and "Complex MIDI Event detection"

- Lossless compression reduces RAM requirements by up to 40%

- Release sample enhancements for realistic sound

- All features and enhancements configurable

- High speed loading and caching of sample sets

- Save settings per sample set or export to settings files

- Shipped with a small demo organ which is automatically loaded on the very first run of GrandOrgue after installation

### Requirements

#### All Platforms

- SSE3 capable processor

  NOTE: A newer, faster processor will permit a higher polyphony

- Sufficient RAM to fully load the largest sample set you wish to use. A 64 bit OS is recommended to support larger sample set sizes.

  A 32 bit GrandOrgue is limited to less than 3 GB of loaded sample data and depending on your operation system, loading more than 1.5 to 2 GB will inhibit some features.

- A hard disk (or other storage) with enough free space to store sample sets. The use of the cache increases the necessary disk space.

## User Interface

The user interface has a menu bar, a tool bar and a console section where the organ console is displayed.

### GrandOrgue User Interface

### Menu bar

The menu bar has 4 menus:

- File: file operations, exit

- Audio/MIDI: manage settings

- Panel: manage additional panels

- Help: display on-line help

#### File Menu

The File menu contains commands for dealing with the loading and saving of sample sets.

##### Load

###### Known organs list

Open and load a sample set from the known organs list which is updated whenever a new sample set is successfully loaded.

Select an organ in the list, then click OK.

The known organs list is managed in the Organs Settings tab.

##### Favorites

This submenu displays the top ten organs in the known organs list. Organs display order is managed in the Organs Settings tab.

Choosing an organ in this menu opens and loads its sample set.

##### Open

Open and load a sample set stored in a definition file. The location will be remembered for the next open operation. The most recently used sample sets are also remembered and available in the "Load", "Open Recent" and "Favorites" menu items. Loading sample sets takes some time; a progress window will display indicating estimated time remaining and other indicators.

When the sample set loads successfully, it registers in the configuration file, thus automatically feeding the known organs list.

##### Open Recent

This submenu displays the ten last used organs from the known organs list. Organs in this menu are ordered by last used date from newest down to oldest.

Choosing an organ in this menu opens and loads its sample set.

##### Install Organ Package

Opens a file chooser to navigate to a GrandOrgue organ package file (.orgue). The package path is registered, and all organ definition files found within the package are added to the known organs list.

An information popup is displayed when the operation completes.

##### Organ Properties

Open a window which displays various characteristics of the loaded sample set as provided by the sample set producer. If available, there is also a link to "More Information" which will display additional information in another application.

##### Preset

Select the saved settings number. A single sample set can create and use up to 11 different saved settings.

Selecting the preset number triggers a reload of the sample set, using the presets stored at the selected number. If no saved settings exist for that number, the sample set is reloaded from the organ definition file as provided by the sample set creator.

A new saved settings set is created whenever the Save menu item is selected. The file is stored in the directory currently designated by the Settings Store parameter in the Options tab, and the file name is meaningless (as in: not related to the sample set/organ/church name) for the user.

##### Save

Save to the preset number currently in use; create a new file if none in use. The settings consist of the stop and piston MIDI messages; stop engaged states; divisional, general, and program combinations; volume spinner value; temperament setting; fine tuning data. Note that this is completely reversible using the Reset to Defaults option, and is the recommended method for most users.

The size and the screen position of all organ GUI panels are saved as well. When this organ is loaded again, all panels appear at the same screen positions and with the same size as they were saved.

Restoring the panel size and position may work not correctly on Linux with wayland windows system. If you need this feature, start your linux session with x11 windows system before launching GrandOrgue.

##### Update Cache

Save the loaded and processed samples to hard disk. Doing so decreases loading time at the expense of hard disk space.

The cache file is stored in the directory currently designated by the Organ cache parameter in the Options tab, and the file name is meaningless (as in: not related to the sample set/organ/church name) for the user.

Creating or updating the cache takes some time; a progress window will display indicating estimated time remaining and other indicators.

Note that each different preset uses its own cache. The Manage cache system option manages automatic creation/update of the current cache.

##### Delete Cache

Delete the current cache from hard disk.

##### Reload

Reload the currently loaded sample set from disk. This may be used to quickly restore a sample set to its saved status. The currently selected preset file is reapplied if it exists on disk.

##### Reset to Defaults

Reset the currently loaded sample set to the settings as originally supplied by the sample set provider. You will be asked to verify that you wish to discard your modifications. Note that the file containing saved settings currently in use is deleted.

##### Import Combinations

This menu item opens the file selection dialog that allows the user to select either a yaml-file, created with Export Combinations, or a .cmb-file, created with Export Settings. In the second case apply only the combination part of settings from a previously exported settings file to the currently loaded sample set. All other settings that might have previously been changed are preserved.

Note The file selection dialog is opened at the directory where exported combination are stored, not where the settings files are. For selecting a .cmb file you have to navigate to the Export/import directory that is named Settings by default.

A settings file matches a sample set when the ChurchName property of the settings file matches the ChurchName property of the definition file.

##### Export Combinations

Saves current combination settings to a text file in YAML format. The user can view this file and can import it later with Import Combinations

##### Import Settings

Apply a previously exported settings file to the currently loaded sample set. All current settings and combinations are overwritten.

Note that settings may only be applied to a matching sample set, and you will receive a warning if you try to do otherwise. The location where the settings were imported from will be remembered for the next time.

A settings file matches a sample set when the ChurchName property of the settings file matches the ChurchName property of the definition file.

##### Export Settings

Save a settings file including the stop and piston MIDI messages; stop engaged states; divisional, general, and program combinations; volume spinner value; temperament setting; fine tuning data.

Export Settings allows the user to choose a specific file name and folder. The latest location where settings were exported to will be remembered for the next time.

##### Settings...

Displays a tabbed dialog containing the various settings. See Program Settings for detailed information on this topic.

##### Close

Close the currently loaded sample set. If you have made any settings changes, you will be asked if you would like to save them before the sample set closes. Note that this will also unload the sample set and free the RAM it required.

##### Exit

Closes and exits the GrandOrgue app.

Exit can also be fired by a MIDI message, see Audio/MIDI menu, MIDI Objects (look for type Button, element Exit).

#### Audio/MIDI Menu

The Audio/MIDI menu contains commands for dealing with loaded organs and associated settings.

##### Temperament

Opens a bunch of menus and sub menus allowing to select a new tuning temperament.

###### Temperaments

The first menu item is always Original temperament, which allows the user to return to the tuning provided by the sample set creator, including whatever pitch adjustments the user has done via the Organ Settings dialog.

The samples are retuned on the fly when playing. No additional disk storage is required.

User temperaments that are added in the Temperaments tab are dynamically displayed at the end of this menu

##### Organ Settings

Displays a dialog which allows to set audio settings (amplitude, gain, tuning, etc.) at every level of the sample set from the whole organ level down to the individual pipe. See Organ Settings for detailed information on this topic.

##### MIDI Objects

Opens a window displaying all GrandOrgue objects which can have a MIDI event assigned to them.

The Configure button opens the MIDI event editor dialog for this element.

Double-clicking on the element in the list opens the MIDI event editor as well.

The Export button opens a file selection dialog for selecting a file where current MIDI settings will be saved.

The Import button opens a file selection dialog for selecting a file to load previous saved MIDI settings from. Both MIDI settings files (*.yaml) and organ preset files (*.cmb) are supported.

The To initial button copies the MIDI settings of selected objects to the Initial MIDI settings. When the user loads another organ that contains MIDI objects with the same path as the selected ones, they will inherit the MIDI settings from here unless they are not overriden in that organ preset. In the future the user can alter the initial MIDI settings at Initial MIDI.

##### Stops

Opens a window displaying all stops and switches. Unlike GUI Panels, it uses standard checkboxes instead of bitmap images, so it can be used with a screen reader software.

Checking or unchecking a stop or a switch causes engaging or disengaging the object in the organ

##### Sound Output State

This popup tries to display actual latency. Note that the estimate can be based on numbers provided by the audio hardware and drivers and that it may vary. The RtAudio backend is more likely to display too low numbers.

##### Panic

The effect of the panic menu item is to reset the sound, stopping all sound and turning off all notes. It may also be quickly accessed on the toolbar or via the Escape key on the computer keyboard. This should be generally unnecessary, although it may be useful if you need to quickly stop the sound output, or if the sound is breaking up due to CPU overload.

Panic button can also be fired by a MIDI message, see Audio/MIDI menu, MIDI Objects (look for type Button, element Panic).

##### Memory Set

Enters memory set mode until the Memory Set menu option or toolbar button is selected again. While the memory set is engaged, whenever you push a divisional or general piston or activate a program change, the organ will store the current settings to that piston or program change rather than recalling them. For example, engaging a divisional piston 1 during memory set will store the state of stops for that manual into piston 1, which could then be pushed later (after memory set has been disengaged) to recall those stops. A checkmark appears next to the menu item, and the toolbar button remains pushed, to indicate when memory set is active.

##### Load MIDI

Opens a file chooser to select a recorded MIDI file. The location chosen in this dialog will be remembered for the next time. The player starts as soon as a file is selected.

GrandOrgue stores MIDI data using a specific internal format that makes the file unsuitable for usage with a regular MIDI sequencer.

When a recorded MIDI file is played in another sample set than the sample set used for recording, all recorded stop changes are silently ignored, thus preventing unexpected rendition.

##### Log MIDI events

Enables a MIDI monitor which displays all incoming and outgoing MIDI events to the message log.

#### Panel Menu

GrandOrgue provides additional panels. Some are predefined and contain fixed functions (crescendo, couplers, generals and divisionals). The organ definition can also ship organ specific panels.

#### Help Menu

##### Index

Opens this help document. Pressing F1 at other locations in the program will jump directly to the appropriate topic.

##### About

Displays the splash screen.

##### Check for updates

Check if a newer version of GrandOrgue is available. If there is one, GrandOrgue will show you what changed in the new version.

#### Update available!

That menu appears only if update checking at startup is enabled and a new update is available.

##### Show changelog

Opens a window that shows what changed between the installed version and the newest one.

##### Download

Opens the GrandOrgue releases page in the browser.

### Tool bar

The tool bar provides a number of controls which can be accessed easily while playing the organ.

#### Memory Set

This "button" is a shortcut to Memory Set in the Audio/MIDI menu.

The Shift key on the computer keyboard is a fugitive shortcut to this button: when the user clicks on a piston while holding the Shift key, the currently pulled drawstops are stored in the piston memory.

#### Program Changes

The spinner sets the current program number. This might be termed a "sequencer" on modern computerized organs. It is possible to store up to 1000 organ states and access them sequentially via the predefined MIDI events, or access any setting directly through the spinner. You may also use the left and right keys on the computer keyboard to scroll through the programs, and down to reactivate the current program (if you have changed the stops since last activating it, for example). Note also that when memory set is engaged, the target program will be stored to, i.e. if you push Shift + Right then the program would be advanced and the current settings would be saved to this same next program.

More options are available on the Combination Setter panel.

#### Volume Control

The volume control sets the volume control in dB. Left and right audio monitors are displayed next to the spinner. The clip indicator at the far right will turn red if clipping occurs, and will stay red until the volume is adjusted.

#### Release Tail Length

The release tail length control sets the duration the sound engine uses to play the release section of the sample. The values are: Max, and a range from 50 ms to 3000 ms by increments of 50 ms.

The Max value makes the sound engine play the complete release section as provided by the sample set creator.

The other values are used by the sound engine as the fade out duration of the sample release section.

#### Transposer

The transposer control shifts the notes up or down by semitone steps. The allowed range is {-11, +11} semitones.

Note that the samples are not retuned. This transposer works like the mechanical transposer on genuine pipe organs or reed organs: the keyboard is shifted up or down, and if the targeted note is missing (i.e. no sample) there is no sound.

#### Polyphony Control

The polyphony control sets the maximum polyphony before GrandOrgue will refuse to play any additional samples. To oversimplify, polyphony is the number of pipes that may sound simultaneously; but polyphony may also be consumed when a key is released. It is recommended to experiment with this setting initially, but leave it once you find an acceptable setting. Your setting should balance between too little polyphony (where you might not be able to play many notes on large sample sets) and too much polyphony (where the CPU will overload and artifacts will appear in the sound). Note that "wet" sample sets (those with considerable reverberation) will consume polyphony many seconds after the note is actually released. The default setting of 2048 should provide a reasonable starting point on a 1GHz CPU. The polyphony monitor is displayed next to the spinner. The clip indicator at the far right will turn red if the polyphony limit has been reached, and will stay red until the polyphony is adjusted.

#### Panic Button

The effect of the panic button is to reset the sound, stopping all sound and turning off all notes. It may also be quickly accessed on the toolbar or via the Escape key. This should be generally unnecessary, although it may be useful if you need to quickly stop the sound output, or if the sound is breaking up due to CPU overload.

Panic button can also be fired by a MIDI message, see Audio/MIDI menu, MIDI Objects (look for type Button, element Panic).

### Console Section

The console section displays the organ console and all its bells and whistles as provided by the sample set creator.

Note: the figure above shows the "classical" church organ disposition. It is possible to design any kind of disposition, since all display elements are freely placeable anywhere on the console panel.

#### Manuals

Each manual as well as the pedalboard is displayed in the center of the screen. The keys are outlined when messages are received, and can be engaged by clicking the mouse. Right clicking on a manual will open its corresponding MIDI Event Editor.

#### Expression Shoes

Expression shoes are displayed directly above the pedalboard, sometimes referred to as "swell pedals", although they may control any of the manuals (Great, Swell, Wonderful, etc). On a pipe organ, swell shutters dampen the sound, and this is simulated in GrandOrgue by adjusting the volume of the enclosed pipes. While the mouse is over a pedal, you may

- use the mouse wheel to adjust its position,

- left click and drag the shoe to the desired position

- right click to open its corresponding MIDI Event Editor.

The sample set creator can also provide a crescendo shoe.

#### Drawstops

The drawstops engage or disengage various components of the organ when clicked - generally new ranks of pipes which are applied to each manual. Other drawstops may perform actions such as coupling one manual to another. This deals with the functionality of pipe organs and is beyond the scope of this documentation. Right clicking on a drawstop will open its corresponding MIDI Event Editor. Any changes made there may be saved or exported into a settings file.

Note: Keep the left button pressed and sweep the mouse over the stop jamb to pull or push multiple drawstops in a single movement.

Note: The "sweep" feature is usable on all clickable display elements, and should be very useful with touch screens.

#### Pistons

Pistons generally perform an action when clicked and do not have an on/off toggle, although some pistons may toggle in this way. Pistons often recall drawstop combinations, and when used in combination with the Memory Set, you can store your own combinations in the pistons. Right clicking on a piston will open its corresponding MIDI Event Editor. Any changes made there may be saved or exported into a settings file.

#### Panels

GrandOrgue provides additional panels. These panels work as console extensions and are not displayed by default. They can be accessed via the Panels menu.

### Message log

Whenever GrandOrgue needs to display a message, it opens a pop-up window. Messages are displayed in reverse chronological order : newest on top of the window.

Messages are displayed with a rating icon.

Warning message

Serious message

Right-clicking anywhere in this window displays a small menu which copies the window's content to the clipboard. When pasted to a file, the messages are displayed in chronological order: oldest on the first line.

## MIDI Event Editor

Every console element, including those defined on panels, is configurable with this editor. The MIDI Event Editor is invoked by right-clicking on the element.

### Receive

#### MIDI received event

This tab configures which MIDI events will drive the console element.

The overall layout is the same for all elements. Depending on the element being configured, the fields circled in red will be disabled or relabeled.

It is possible to define several received events for the same GUI control. Any of them received at any time will trigger the control.

Event-No

- Event identifier. If the event is associated to a specific MIDI device, the device name is part of the identifier.

Device

- The dropdown displays every MIDI input device that was ever known to GrandOrgue. If a device is selected in the dropdown, GrandOrgue listens only for that event coming from that device. If no device is selected, GrandOrgue listens for that event coming from any selected input device (in the MIDI Devices Tab) connected to the computer.

Event

- The dropdown displays the list of allowed events for the control.

Channel

- MIDI channel for this event (1-16 or Any). If set to "Any channel", GrandOrgue listens for that event on any channel.

New

- This button allows to add a new event to the list of received events. A blank form is displayed with an incremented event number.

Delete

- This button allows to delete the currently selected event. It is enabled only when there are at least 2 events in the list.

  An event can also be marked for deletion by setting its Event dropdown to None. It is effectively deleted when the OK button is pressed.

  It is the only way to delete the last event and blank out the list

Listen for Event

- Triggers listening mode. GrandOrgue waits for a MIDI event, then fills the dialog with the event's data.

  This legacy configuration technique is useful only for very simple settings. The preferred way to configure MIDI is to use the Detect Complex MIDI Setup functionality.

Detect complex MIDI Setup

- Triggers listening mode. GrandOrgue asks for two MIDI event sequences which define the operating range for the control. More information is available for each console element in the next section. Suitable instructions are displayed in the space above the OK / Cancel buttons.

### Send

#### MIDI send event

This tab configures which MIDI events are sent from the console element.

The overall layout is the same for all elements. Depending on the element being configured, some fields will be disabled or relabeled.

It is possible to define several sent events for the same GUI control. All of them will be sent whenever the control is triggered.

Event-No

- Event identifier. If the event is associated to a specific MIDI device, the device name is part of the identifier.

Device

- The dropdown displays every MIDI output device that was ever known to GrandOrgue. If a device is selected in the dropdown, GrandOrgue outputs that event only to that device. If no device is selected, GrandOrgue outputs that event to all selected output devices ( in the MIDI Devices Tab) connected to the computer.

Event

- The dropdown displays the list of allowed events for the control.

Channel

- MIDI channel for this event (1-16, defaults to 1).

Use Note Off (0x8X)

- For MIDI note events the state of this checkbox will decide if the note off message is sent as a Note Off (0x8X) or as a Note On (0x9X) with velocity 0.

New

- This button allows to add a new event to the list of sent events. A blank form is displayed with an incremented event number.

Delete

- This button allows to delete the currently selected event. It is enabled only when there are at least 2 events in the list.

  An event can also be marked for deletion by setting its Event dropdown to None. It is effectively deleted when the OK button is pressed.

  It is the only way to delete the last event and blank out the list

Copy current receive event

- This button copies the values of the current Receive event selected on the Receive page to the current event on the Send page.

  If the receive event contains a correct input device specified, then GrandOrgue takes the output device set to this input device with the MIDI-Output-Device button on the MIDI Devices Tab of the Program Settings window.

  If an output device has not been set for this input device then GrandOrgue sets "Any Device" value. The user have to select an output device manually.

### Keyboard shortcut

This tab is displayed only for enclosures, drawstops and buttons.

Shortcut

- This dropdown lists all usable key values.

  According to the platform running GrandOrgue, some keys will be unusable.

Listen for Event

- Triggers listening mode. GrandOrgue waits for a key to be depressed on the computer keyboard, then sets the dropdown to that key.

### Editor by console element

#### Keyboard

##### Receive

Event

- The available events are:

  9x Note

- Receive NoteOn / NoteOff with velocity. The velocity value is used to select the "best" attack sample and alter sound rendering (e.g. piano plays loud/soft according to velocity).

  This setting honors the key mapping that can be defined in the Organ Definition File (Manual999, optional MIDIKey999 entries).

9x Note without Velocity

- Same as 9x Note. The velocity value, if any, is always translated to On = 127, Off = 0.

9x Note short octave at low key

- Same as 9x Note plus hardcoded short octave processing in the lowest octave.

  The lowest octave is that of the lowest C on a full compass keyboard. Lowest key field value needs to match the actual lowest C MIDI key number.

  The hardcoded processing matches E key to C note, F key to F note, F# key to D note, G key to G note, G# key to E note, and from A upwards, the key on the keyboard matches the same note.

  The main usage of this setting is to quickly convert a full compass keyboard to short octave. See appendix A.

9x Note without map

- Ignore the key mapping defined in the Organ Definition File (Manual999, optional MIDIKey999 entries).

  The main usage of this setting is to quickly convert a short octave keyboard to full compass. See appendix A.

Transpose

- This spinner sets a permanent transposition in semitones. Positive values transpose up, negative values transpose down.

Lowest Key

Highest Key

- These spinners set the key number range which GrandOrgue will acknowledge when listening for MIDI events. Any key number outside the range will be ignored. The lowest key value designates the lowest octave (where short octave processing takes place).

Lowest velocity

Highest velocity

- These spinners set the velocity range which GrandOrgue will acknowledge when listening for MIDI events.

  - All events with velocity > "highest velocity" are ignored.

  - All events with velocity < "lowest velocity" are translated to NoteOff.

  - Velocity values between "lowest velocity" and "highest velocity" are rescaled to 0-127

  Lowest velocity must be at least 1, otherwise all key releases will be missed.

Debounce time

- This spinner is always disabled for a keyboard.

Detect complex MIDI Setup

- Asks to press the lowest and highest keys available on the keyboard. GrandOrgue uses the values it reads to determine the channel, lowest key number, highest key number, lowest velocity value. Highest velocity value is always set to 127. Event is set to

  - 9x Note short octave at low key if the lowest E is hit

  - 9x Note if any other key in the lowest octave is hit

##### Send

This tab controls how the input state of the manual keys is mirrored to an external MIDI device

Event

- The available events are:

  9x Note

- Send NoteOn / NoteOff. Velocity is sent, rescaled to the range defined in the Off Value and On Value fields.

9x Note without Velocity

- Send NoteOn / NoteOff. The velocity value is always set to On = value of On Value field, Off = value of Off Value field.

CTRL/PGM

- This spinner is always disabled for a keyboard.

Off Value

- This spinner sets the velocity value sent when a key is released on the keyboard.

On Value

- This spinner sets the velocity value sent when a key is depressed on the keyboard.

Off value must be set to zero (0) if NoteOff is wished.

##### Send Division Output

This tab controls how the state after coupler processing of the division is sent to an external MIDI device.

Event

- The available events are:

  9x Note

- Send NoteOn / NoteOff. Velocity is sent, rescaled to the range defined in the Off Value and On Value fields.

9x Note without Velocity

- Send NoteOn / NoteOff. The velocity value is always set to On = value of On Value field, Off = value of Off Value field.

CTRL/PGM

- This spinner is always disabled for a keyboard.

Off Value

- This spinner sets the velocity value sent when a key is released on the keyboard.

On Value

- This spinner sets the velocity value sent when a key is depressed on the keyboard.

Off value must be set to zero (0) if NoteOff is wished.

#### Rank

This setting allows to send NoteOn / NoteOff data only when a rank has been activated by pulling the stop it belongs to. This setting is loosely related to the Manual's Send settings. The following table summarizes the main use cases for each setting.

Manual: Send | Mirrors the keyboard input state. The configured MIDI event is sent whenever the key is physically depressed. Couplers defined in GrandOrgue are ignored | Can be used for recording keyboard action to an external MIDI device
Manual: Send Division Output | Sends the division state after all couplers have been processed. Even if the key is displayed as depressed in GrandOrgue GUI, the event tied to the manual is not sent | Can be used to control an external windchest having a single valve per note
Rank: Send | Sends the individual pipe state | Can be used to control an external windchest having a valve per pipe

Event

- The available events are:

  9x Note

- Send NoteOn / NoteOff. Velocity is sent, rescaled to the range defined in the Off Value and On Value fields.

9x Note without Velocity

- Send NoteOn / NoteOff. The velocity value is always set to On = value of On Value field, Off = value of Off Value field.

CTRL/PGM

- This spinner is always disabled for a rank.

Off Value

- This spinner sets the velocity value sent when a pipe is muted.

On Value

- This spinner sets the velocity value sent when a pipe starts playing.

Rank MIDI configuration can be accessed only via the MIDI Objects list.

#### Enclosure

##### Receive

Event

- The available events are:

  Bx controller

- Receive Control Change messages.

  GrandOrgue expects this message sequence: Bn controller# MSB; controller value.

RPN

- Receive RPN (Registered Parameter Number) messages.

  GrandOrgue supports: Parameter number MSByte, Parameter number LSByte and only Data Entry MSByte (0x06).

  GrandOrgue expects this message sequence: Bn 0x65 parameter# MSB; [Bn 0x64 parameter# LSB;] Bn 0x06 parameter value

NRPN

- Receive NRPN (Non Registered Parameter Number) messages.

  GrandOrgue supports: Parameter number MSByte, Parameter number LSByte and only Data Entry MSByte (0x06).

  GrandOrgue expects this message sequence: Bn 0x63 parameter# MSB; [Bn 0x62 parameter# LSB;] Bn 0x06 parameter value

Cx Program Change Range

- Receive Bank Select and Program Change when the enclosure opens or closes.

  - The fields Lower limit and Upper limit are relabeled to Lower PGM number and Upper PGM number.

  - GrandOrgue moves the enclosure when receiving program numbers in the range {lower PGM number, upper PGM number} evenly divided in 127 positions.

  - GrandOrgue expects this message sequence: Bn 0x00 <data1>; Bn 0x20 <data2>; Cn prog#. The bank select controllers enable GrandOrgue to use program numbers higher than 127. Range is [0, 2097152].

  - When receiving Bank Select + Program Change, if the MIDI device sends Bn 0x00 <data1>; Bn 0x20 <data2>; Cn prog#, the program number will be computed as the value of data1 shifted left 14 bits ORed (bitwise) with data2 shifted left 7 bits ORed (bitwise) with prog# + 1 [ math: ((data1 << 14) | (data2 << 7) | prog#) + 1 ]. If the result falls in the range {lower PGM number, upper PGM number}, the enclosure moves to that value's position.

Data

- Sets the controller (Bx) or parameter (RPN/NRPN) number.

  When receiving RPN, if the MIDI device sends Bn 0x65 <data1>; Bn 0x64 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2. Range is [0, 16383]..

  E.g.: Bn 0x65 1; Bn 0x64 2 will display 130.

  The behavior is identical for NRPN.

  The label of this field changes according to the event type:

  Bx Controller | => | Controller-No
  RPN or NRPN | => | Parameter-No

Lowest Key

Highest Key

- These spinners are always disabled for an enclosure.

Lower limit

Upper limit

- These spinners set the controller values range which defines a full open/closed enclosure. The value is rescaled to the full range (0-127) for that controller. Values outside the range are translated to their limit values: value < lower limit yields 0, value > upper limit yields 127.

Debounce time

- This spinner is always disabled for an enclosure.

Detect complex MIDI Setup

- Asks to move the physical device (usually a shoe) to fully open and close the enclosure. GrandOrgue uses the values it reads to determine the channel, controller type and number and the limits of the usable range.

##### Send

Event

- The available events are:

  Bx controller

- Send Control Change messages.

  GrandOrgue sends this message sequence: Bn controller# MSB; controller value.

RPN

- Send RPN (Registered Parameter Number) messages.

  GrandOrgue supports: Parameter number MSByte, Parameter number LSByte and only Data Entry MSByte (0x06).

  GrandOrgue sends this message sequence: Bn 0x65 parameter# MSB; Bn 0x64 parameter# LSB; Bn 0x06 parameter value

NRPN

- Send NRPN (Non Registered Parameter Number) messages.

  GrandOrgue supports: Parameter number MSByte, Parameter number LSByte and only Data Entry MSByte (0x06).

  GrandOrgue sends this message sequence: Bn 0x63 parameter# MSB; Bn 0x62 parameter# LSB; Bn 0x06 parameter value

Cx Program Change Range

- Send Bank Select and Program Change when the enclosure opens or closes.

  - The fields Off Value and On Value are relabeled to Lower PGM number and Upper PGM number.

  - GrandOrgue sends program numbers in the range {lower PGM number, upper PGM number} evenly spread in 127 chunks.

  - GrandOrgue always sends Bn 0x00 <data1>; Bn 0x20 <data2>; Cn prog#. The bank select controllers enable GrandOrgue to use program numbers higher than 127. Range is [0, 2097152].

  - <data1> is the value of the 7 leftmost bits of the program number (math: ((value -1) >> 14) & 0x7F).

  - <data2> is the value of the 7 middle bits of the program number (math: ((value -1) >> 7) & 0x7F).

  - prog# is the value of the 7 rightmost bits of the program number (math: ((value -1) >> 0) & 0x7F).

CTRL/PGM

- For a Bx controller, this spinner sets the controller number (range 0-127).

  For RPN or NRPN, this value is in the range 0-16383. GrandOrgue will automatically split this parameter number into its most significant byte and least significant byte to send Bn 0x65 <data1>; Bn 0x64 <data2> where data1 is computed as "ParameterNo right shifted 7 bits AND 0x7F" and data2 is computed as "ParameterNo AND 0x7F"

  The label of this field changes according to the event type:

  Bx Controller | => | Controller-No
  RPN or NRPN | => | Parameter-No

Off Value

On Value

- Define the values for sending a fully open/closed enclosure. Values will be rescaled to the range defined by these limits.

##### Shortcut

###### Keyboard shortcut for Enclosure

An enclosure needs to define 2 different shortcuts: one to "open" and another to "close" the virtual shades

Plus-Shortcut | Defines the key used to "open" the virtual shades
Minus-Shortcut | Defines the key used to "close" the virtual shades

On both frames, the Listen for Event button, when depressed, triggers listening mode. GrandOrgue waits for a key to be depressed on the computer keyboard, then sets the dropdown to that key.

#### Drawstop and Pushbutton

##### Receive

###### 9x Note

Receive NoteOn / NoteOff.

Data | Key number
Lower limit | Maximum velocity value that toggles the button or drawstop off
Upper limit | Minimum velocity value that toggles the button or drawstop on All velocity values between lower and upper limit are ignored
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### 9x Note On Toggle

Receive NoteOn messages only. Two successive NoteOn messages on the same key number will toggle the state of the button/drawstop.

Data | Key number
Upper limit | Minimum velocity value that toggles the button or drawstop
Debounce time | Minimum time in milliseconds that must elapse between two successive NoteOn messages for the drawstop/button to toggle its state.
Lower limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### 9x Note Off Toggle

Receive NoteOff messages only. Two successive NoteOff messages on the same key number will toggle the state of the button/drawstop.

Data | Key number
Lower limit | Maximum velocity value that toggles the button or drawstop
Debounce time | Minimum time in milliseconds that must elapse between two successive NoteOff messages for the drawstop/button to toggle its state.
Upper limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### 9x Note On/Off Toggle

Receive NoteOn or NoteOff messages. This control is designed for momentary buttons which send a NoteOn message when first pressed and a NoteOff message when pressed a second time or the reverse.

An alternative to this setting would be to define two events for that button: one NoteOn Toggle and one NoteOff Toggle.

Data | Key number
Lower limit | Maximum velocity value that toggles the button or drawstop state
Upper limit | Minimum velocity value that toggles the button or drawstop state All velocity values between lower and upper limit are ignored
Debounce time | Minimum time in milliseconds that must elapse between two successive Note messages for the drawstop/button to toggle its state.
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### Bx Controller

Receive Control Change messages. GrandOrgue expects this message sequence: Bn controller# MSB; controller value.

Controller-No | Controller number. Range is [0, 127] Bank Select, RPN, NRPN and Data Entry controllers are reserved by GrandOrgue and can NOT be used for normal matching. Namely:

0x00 (0) | Bank Select MSB
0x20 (32) | Bank Select LSB
0x06 (6) | Data entry LSB
0x62 (98) | NRPN LSB
0x63 (99) | NRPN MSB
0x64 (100) | RPN LSB
0x65 (101) | RPN MSB

Lower Limit | Maximum data value that toggles the button or drawstop off. Range is [0, 127]
Upper Limit | Minimum data value that toggles the button or drawstop on. Range is [0, 127] All data values between lower and upper limit are ignored
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### Bx Controller On Toggle

Receive Control Change messages. GrandOrgue expects this message sequence: Bn controller# MSB; controller value.

The button or drawstop toggles its state whenever two successive "identical" messages are received.

Controller-No | Controller number. Range is [0, 127]. See above for exclusions.
Upper Limit | Minimum data value that toggles the button or drawstop state. Range is [0, 127]. "Identical" means that two successive controller values are above this limit.
Debounce time | Minimum time in milliseconds that must elapse between two successive "identical" messages for the drawstop/button to toggle its state.
Lower Limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### Bx Controller Off Toggle

Receive Control Change messages. GrandOrgue expects this message sequence: Bn controller# MSB; controller value.

The button or drawstop toggles its state whenever two successive "identical" messages are received.

Controller-No | Controller number. Range is [0, 127]. See above for exclusions.
Lower Limit | Maximum data value that toggles the button or drawstop state. Range is [0, 127]. "Identical" means that two successive controller values are below this limit.
Debounce time | Minimum time in milliseconds that must elapse between two successive "identical" messages for the drawstop/button to toggle its state.
Upper Limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### Bx Controller On/Off Toggle

Receive Control Change messages. GrandOrgue expects this message sequence: Bn controller# MSB; controller value.

This control is designed for momentary buttons which send a Controller value when first pressed and another Controller value when pressed a second time.

An alternative to this setting would be to define two events for that button: one Bx Controller On Toggle and one Bx Controller Off Toggle.

Controller-No | Controller number. Range is [0, 127]
Lower Limit | Maximum data value that toggles the button or drawstop off. Range is [0, 127]
Upper Limit | Minimum data value that toggles the button or drawstop on. Range is [0, 127] All data values between lower and upper limit are ignored
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### Cx Program Change

Receive Program Change messages. GrandOrgue expects this message sequence: [Bn 0x00 bank# MSB;][Bn 0x20 bank# LSB;] Cn prog#.

The optional bank select controllers enable GrandOrgue to manage more than 128 drawstops or buttons on a single channel with Program Change messages.

This control is a toggle: two successive messages changing the same program will toggle the state of the drawstop/button.

Data | Program number. Range is [0, 127] when bank select messages are not used, [0, 2097152] otherwise. When receiving Bank Select + Program Change, if the MIDI device sends Bn 0x00 <data1>; Bn 0x20 <data2>; Cn prog#, the program number will be displayed as the value of data1 shifted left 14 bits ORed (bitwise) with data2 shifted left 7 bits ORed (bitwise) with prog# + 1 [ math: ((data1 << 14) | (data2 << 7) | prog#) + 1 ].
Debounce time | Minimum time in milliseconds that must elapse between two successive messages changing to the same program for the drawstop/button to toggle its state.
Lower Limit | Unused by this setting
Upper Limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### RPN

Receive RPN (Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x65 parameter# MSB; [Bn 0x64 parameter# LSB;] Bn 0x06 parameter value.

Parameter-No | Parameter number. If the MIDI device sends Bn 0x65 <data1>; Bn 0x64 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Lower Limit | Maximum parameter value that toggles the button or drawstop off. Range is [0, 127]
Upper Limit | Minimum parameter value that toggles the button or drawstop on. Range is [0, 127]
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### NRPN

Receive NRPN (Non Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x63 parameter# MSB; [Bn 0x62 parameter# LSB;] Bn 0x06 parameter value.

Parameter-No | Parameter number. If the MIDI device sends Bn 0x63 <data1>; Bn 0x62 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Lower Limit | Maximum parameter value that toggles the button or drawstop off. Range is [0, 127]
Upper Limit | Minimum parameter value that toggles the button or drawstop on. Range is [0, 127]
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### Cx Program Change Range

Receive Program Change messages. GrandOrgue expects this message sequence: [Bn 0x00 bank# MSB;][Bn 0x20 bank# LSB;] Cn prog#.

This control uses 2 different program numbers: one to pull and the other to push the drawstop or button.

The optional bank select controllers enable GrandOrgue to manage more than 64 drawstops or buttons on a single channel with Program Change messages.

Lower PGM number | Program number to push the drawstop or button. Range is [1, 128] when bank select messages are not used, [0, 2097152] otherwise. When receiving Bank Select + Program Change, if the MIDI device sends Bn 0x00 <data1>; Bn 0x20 <data2>; Cn prog#, the program number will be displayed as the value of data1 shifted left 14 bits ORed (bitwise) with data2 shifted left 7 bits ORed (bitwise) with prog# + 1 [ math: ((data1 << 14) | (data2 << 7) | prog#) + 1 ].
Upper PGM number | Program number to pull the drawstop or button. Range is [1, 128] when bank select messages are not used, [0, 2097152] otherwise. When receiving Bank Select + Program Change, if the MIDI device sends Bn 0x00 <data1>; Bn 0x20 <data2>; Cn prog#, the program number will be displayed as the value of data1 shifted left 14 bits ORed (bitwise) with data2 shifted left 7 bits ORed (bitwise) with prog# + 1 [ math: ((data1 << 14) | (data2 << 7) | prog#) + 1 ].
Data | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Minimum time in milliseconds that must elapse between two successive messages changing to the same program for the drawstop/button to toggle its state.

###### RPN On Toggle

Receive RPN (Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x65 parameter# MSB; [Bn 0x64 parameter# LSB;] Bn 0x06 parameter value.

The button or drawstop toggles its state whenever two successive "identical" messages are received.

Parameter-No | Parameter number. If the MIDI device sends Bn 0x65 <data1>; Bn 0x64 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Upper Limit | Minimum parameter value that toggles the button or drawstop state. Range is [0, 127]. "Identical" means that two successive parameter values are above this limit.
Debounce time | Minimum time in milliseconds that must elapse between two successive RPN messages for the drawstop/button to toggle its state.
Lower Limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### RPN Off Toggle

Receive RPN (Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x65 parameter# MSB; [Bn 0x64 parameter# LSB;] Bn 0x06 parameter value.

The button or drawstop toggles its state whenever two successive "identical" messages are received.

Parameter-No | Parameter number. If the MIDI device sends Bn 0x65 <data1>; Bn 0x64 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Lower Limit | Maximum parameter value that toggles the button or drawstop state. Range is [0, 127]. "Identical" means that two successive parameter values are below this limit.
Debounce time | Minimum time in milliseconds that must elapse between two successive RPN messages for the drawstop/button to toggle its state.
Upper Limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### RPN On/Off Toggle

Receive RPN (Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x65 parameter# MSB; [Bn 0x64 parameter# LSB;] Bn 0x06 parameter value.

This control is designed for momentary buttons which send a RPN value when first pressed and another RPN value when pressed a second time.

An alternative to this setting would be to define two events for that button: one RPN On Toggle and one RPN Off Toggle.

Parameter-No | Parameter number. If the MIDI device sends Bn 0x65 <data1>; Bn 0x64 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Lower Limit | Maximum parameter value that toggles the button or drawstop off. Range is [0, 127]
Upper Limit | Minimum parameter value that toggles the button or drawstop on. Range is [0, 127]
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Minimum time in milliseconds that must elapse between two successive RPN messages for the drawstop/button to toggle its state.

###### NRPN On Toggle

Receive NRPN (Non Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x63 parameter# MSB; [Bn 0x62 parameter# LSB;] Bn 0x06 parameter value.

The button or drawstop toggles its state whenever two successive "identical" messages are received.

Parameter-No | Parameter number. If the MIDI device sends Bn 0x63 <data1>; Bn 0x62 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Upper Limit | Minimum parameter value that toggles the button or drawstop state. Range is [0, 127]. "Identical" means that two successive parameter values are above this limit.
Debounce time | Minimum time in milliseconds that must elapse between two successive NRPN messages for the drawstop/button to toggle its state.
Lower Limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### NRPN Off Toggle

Receive NRPN (Non Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x63 parameter# MSB; [Bn 0x62 parameter# LSB;] Bn 0x06 parameter value.

The button or drawstop toggles its state whenever two successive "identical" messages are received.

Parameter-No | Parameter number. If the MIDI device sends Bn 0x63 <data1>; Bn 0x62 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Lower Limit | Maximum parameter value that toggles the button or drawstop state. Range is [0, 127]. "Identical" means that two successive parameter values are below this limit.
Debounce time | Minimum time in milliseconds that must elapse between two successive NRPN messages for the drawstop/button to toggle its state.
Upper Limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### NRPN On/Off Toggle

Receive NRPN (Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x63 parameter# MSB; [Bn 0x62 parameter# LSB;] Bn 0x06 parameter value.

This control is designed for momentary buttons which send a NRPN value when first pressed and another NRPN value when pressed a second time.

An alternative to this setting would be to define two events for that button: one NRPN On Toggle and one NRPN Off Toggle.

Parameter-No | Parameter number. If the MIDI device sends Bn 0x63 <data1>; Bn 0x62 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Lower Limit | Maximum parameter value that toggles the button or drawstop off. Range is [0, 127]
Upper Limit | Minimum parameter value that toggles the button or drawstop on. Range is [0, 127]
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Minimum time in milliseconds that must elapse between two successive RPN messages for the drawstop/button to toggle its state.

###### RPN Range

Receive RPN (Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x65 parameter# MSB; [Bn 0x64 parameter# LSB;] Bn 0x06 parameter value.

This control uses 2 different parameter numbers: one to pull and the other to push the drawstop or button. The parameter value MUST be the same for both (pull and push) messages.

Value | Parameter value. Range is [0, 127].
Off RPN number | Parameter number to push the drawstop or button. Range is [0, 127]. If the MIDI device sends Bn 0x65 <data1>; Bn 0x64 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
On RPN number | Parameter number to pull the drawstop or button. Range is [0, 127]. If the MIDI device sends Bn 0x65 <data1>; Bn 0x64 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### NRPN Range

Receive NRPN (Registered Parameter Number) messages. GrandOrgue expects this message sequence: Bn 0x63 parameter# MSB; [Bn 0x62 parameter# LSB;] Bn 0x06 parameter value.

This control uses 2 different parameter numbers: one to pull and the other to push the drawstop or button. The parameter value MUST be the same for both (pull and push) messages.

Value | Parameter value. Range is [0, 127].
Off NRPN number | Parameter number to push the drawstop or button. Range is [0, 127]. If the MIDI device sends Bn 0x63 <data1>; Bn 0x62 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
On NRPN number | Parameter number to pull the drawstop or button. Range is [0, 127]. If the MIDI device sends Bn 0x63 <data1>; Bn 0x62 <data2>, the parameter number will be displayed as the value of data1 shifted left 7 bits ORed (bitwise) with data2 [ math: (data1 << 7) | data2 ].
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### Ctrl Change Bitfield

This setting is used by some Content™ digital organs. Up to 7 stops are packed in a single controller value where each bit controls a single stop.

Controller-No | Controller number. Range is [0, 127]
Bit number | Bit number which state controls the stop. Range is [0, 6]
Upper Limit | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### Bx Ctrl Change Fixed Value

This setting is used by some Alhborn™ digital organs. GrandOrgue detects bit patterns like Stop on = 01xx xxxx ; Stop Off = 00xx xxxx.

Controller-No | Controller number. Range is [0, 127]. Refer to the organ MIDI chart for the actual controller number(s).
Off value | Data value that toggles the button or drawstop off. Range is [0, 63]
On value | Data value that toggles the button or drawstop on. Range is [64, 127]. Always off value + 64.
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### Bx Ctrl Change Fixed On Value Toggle

This setting is used by some Alhborn™ digital organs. GrandOrgue toggles the drawstop or button state when detecting bit patterns like 01xx xxxx.

Controller-No | Controller number. Range is [0, 127]. Refer to the organ MIDI chart for the actual controller number.
On value | Data value that toggles the button or drawstop state. Range is [64, 127].
Debounce time | Minimum time in milliseconds that must elapse between two successive identical control change messages for the drawstop/button to toggle its state.
Off value | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### Bx Ctrl Change Fixed Off Value Toggle

This setting is used by some Alhborn™ digital organs. GrandOrgue toggles the drawstop or button state when detecting bit patterns like 00xx xxxx.

Controller-No | Controller number. Range is [0, 127]. Refer to the organ MIDI chart for the actual controller number.
Off value | Data value that toggles the button or drawstop state. Range is [0, 63]
Debounce time | Minimum time in milliseconds that must elapse between two successive identical control change messages for the drawstop/button to toggle its state.
On value | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### Bx Ctrl Change Fixed On/Off Value Toggle

This setting is used by some Alhborn™ digital organs. GrandOrgue toggles the drawstop or button state when detecting bit patterns like 00xx xxxx.

This control is designed for momentary buttons which send a bit pattern when first pressed and another bit pattern when pressed a second time.

An alternative to this setting would be to define two events for that button: one Bx Ctrl Change Fixed On Value Toggle and one Bx Ctrl Change Fixed Off Value Toggle.

Controller-No | Controller number. Range is [0, 127]. Refer to the organ MIDI chart for the actual controller number.
On value | Data value that toggles the button or drawstop state. Range is [64, 127]
Off value | Data value that toggles the button or drawstop state. Range is [0, 63]
Debounce time | Minimum time in milliseconds that must elapse between two successive identical control change messages for the drawstop/button to toggle its state.
Lowest key | Unused by this setting
Highest key | Unused by this setting

###### Sys Ex Johannus

This setting is used by Johannus™ digital organs. The button or drawstop toggles its state whenever two successive identical messages are received.

Data | Data value that toggles the button or drawstop state. Range is [0, 127]
Debounce time | Minimum time in milliseconds that must elapse between two successive identical SysEx messages for the drawstop/button to toggle its state.
Lowest key | Unused by this setting
Highest key | Unused by this setting
Lower limit | Unused by this setting
Upper limit | Unused by this setting

###### Sys Ex Viscount

This setting is used by Viscount™ digital organs.

Off value | Data value that toggles the button or drawstop state off. Range is [0, 2097152].
On value | Data value that toggles the button or drawstop state on. Range is [0, 2097152].
Data | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting
Debounce time | Unused by this setting

###### Sys Ex Viscount Toggle

This setting is used by Viscount™ digital organs. The button or drawstop toggles its state whenever two successive identical messages are received.

Value | Data value that toggles the button or drawstop state. Range is [0, 2097152].
Debounce time | Minimum time in milliseconds that must elapse between two successive identical SysEx messages for the drawstop/button to toggle its state.
Data | Unused by this setting
Lowest key | Unused by this setting
Highest key | Unused by this setting
Upper limit | Unused by this setting

###### Detect complex MIDI Setup

Asks to toggle the drawstop or pushbutton On then Off. GrandOrgue uses the values it reads to determine the MIDI event and all associated settings.

##### Send

###### 9x Note

Send NoteOn when the drawstop/button toggles to On state. Send "NoteOff" when the drawstop/button toggles to Off state.

CTRL/PGM | Key number.
Off Value | Velocity value when drawstop/button goes to Off state. Off value must be set to zero (0) if a genuine NoteOff is wished.
On Value | Velocity value when drawstop/button goes to On state.

###### 9x Note On

Send NoteOn only when the drawstop/button goes to On state.

CTRL/PGM | Key number.
Off Value | Unused by this setting.
On Value | Velocity value when drawstop/button goes to On state.

###### 9x Note Off

Send "NoteOff" only when the drawstop/button goes to Off state.

CTRL/PGM | Key number.
Off Value | Velocity value when drawstop/button goes to Off state. Off value must be set to zero (0) if a genuine NoteOff is wished.
On Value | Unused by this setting.

###### Bx Controller

Send controller values when the drawstop/button changes state. The message sequence is Bn Controller# <value>

Controller-No | Controller number. Range is [0,127].
Off Value | Controller value when drawstop/button goes to Off state.
On Value | Controller value when drawstop/button goes to On state.

###### Bx Controller On

Send controller value only when the drawstop/button goes to On state.

Controller-No | Controller number. Range is [0,127].
Off Value | Unused by this setting.
On Value | Controller value when drawstop/button goes to On state.

###### Bx Controller Off

Send controller value only when the drawstop/button goes to Off state.

Controller-No | Controller number. Range is [0,127].
Off Value | Controller value when drawstop/button goes to Off state.
On Value | Unused by this setting.

###### Cx Program Change On

Send Bank Select and Program Change only when the drawstop/button goes to On state. The message sequence is: Bn 0x00 bank# MSB ; Bn 0x20 bank# LSB ; Cn prog#.

CTRL/PGM | Program number and optional Bank Select MIDI messages. Range is [0, 2097152] GrandOrgue always sends Bn 0x00 <data1>; Bn 0x20 <data2>; Cn prog#. This field value is the result of data1 shifted left 14 bits ORed (bitwise) with data2 shifted left 7 bits ORed (bitwise) with prog# + 1 [ math: ((data1 << 14) | (data2 << 7) | prog#) + 1 ].
Off Value | Unused by this setting.
On Value | Unused by this setting.

###### Cx Program Change Off

Send Bank Select and Program Change only when the drawstop/button goes to Off state. The message sequence is: Bn 0x00 bank# MSB ; Bn 0x20 bank# LSB ; Cn prog#.

CTRL/PGM | Program number and optional Bank Select MIDI messages. Range is [0, 2097152] GrandOrgue always sends Bn 0x00 <data1>; Bn 0x20 <data2>; Cn prog#. This field value is the result of data1 shifted left 14 bits ORed (bitwise) with data2 shifted left 7 bits ORed (bitwise) with prog# + 1 [ math: ((data1 << 14) | (data2 << 7) | prog#) + 1 ].
Off Value | Unused by this setting.
On Value | Unused by this setting.

###### RPN

Send RPN values when the drawstop/button changes state. The message sequence is Bn 0x65 parameter# MSB; Bn 0x64 parameter# LSB; Bn 0x06 parameter value.

Parameter-No | Parameter number. Range is [0,16383]. The parameter number displays the result of parameter# MSB shifted left 7 bits ORed (bitwise) with parameter# LSB [ math: (parameter# MSB << 7) | parameter# LSB ].
Off Value | Parameter value when drawstop/button goes to Off state.
On Value | Parameter value when drawstop/button goes to On state.

###### NRPN

Send NRPN values when the drawstop/button changes state. The message sequence is Bn 0x63 parameter# MSB; Bn 0x62 parameter# LSB; Bn 0x06 parameter value.

Parameter-No | Parameter number. Range is [0,16383]. The parameter number displays the result of parameter# MSB shifted left 7 bits ORed (bitwise) with parameter# LSB [ math: (parameter# MSB << 7) | parameter# LSB ].
Off Value | Parameter value when drawstop/button goes to Off state.
On Value | Parameter value when drawstop/button goes to On state.

###### Cx Program Change Range

Send Bank Select and Program Change when the drawstop/button changes state.

GrandOrgue always sends Bn 0x00 <data1>; Bn 0x20 <data2>; Cn prog#. This field value is the result of data1 shifted left 14 bits ORed (bitwise) with data2 shifted left 7 bits ORed (bitwise) with prog# + 1 [ math: ((data1 << 14) | (data2 << 7) | prog#) + 1 ].

Lower PGM number | Program number and optional Bank Select MIDI messages sent when the drawstop/button goes to Off state. Range is [0, 2097152]
Upper PGM number | Program number and optional Bank Select MIDI messages sent when the drawstop/button goes to On state. Range is [0, 2097152]
CTRL/PGM | Unused by this setting.

###### RPN On

Send RPN value only when the drawstop/button changes to On state. The message sequence is Bn 0x65 parameter# MSB; Bn 0x64 parameter# LSB; Bn 0x06 parameter value.

Parameter-No | Parameter number. Range is [0,16383]. The parameter number displays the result of parameter# MSB shifted left 7 bits ORed (bitwise) with parameter# LSB [ math: (parameter# MSB << 7) | parameter# LSB ].
Off Value | Unused by this setting
On Value | Parameter value when drawstop/button goes to On state.

###### RPN Off

Send RPN value only when the drawstop/button changes to Off state. The message sequence is Bn 0x65 parameter# MSB; Bn 0x64 parameter# LSB; Bn 0x06 parameter value.

Parameter-No | Parameter number. Range is [0,16383]. The parameter number displays the result of parameter# MSB shifted left 7 bits ORed (bitwise) with parameter# LSB [ math: (parameter# MSB << 7) | parameter# LSB ].
Off Value | Parameter value when drawstop/button goes to Off state.
On Value | Unused by this setting

###### NRPN On

Send NRPN value only when the drawstop/button changes to On state. The message sequence is Bn 0x63 parameter# MSB; Bn 0x62 parameter# LSB; Bn 0x06 parameter value.

Parameter-No | Parameter number. Range is [0,16383]. The parameter number displays the result of parameter# MSB shifted left 7 bits ORed (bitwise) with parameter# LSB [ math: (parameter# MSB << 7) | parameter# LSB ].
Off Value | Unused by this setting
On Value | Parameter value when drawstop/button goes to On state.

###### NRPN Off

Send NRPN value only when the drawstop/button changes to Off state. The message sequence is Bn 0x63 parameter# MSB; Bn 0x62 parameter# LSB; Bn 0x06 parameter value.

Parameter-No | Parameter number. Range is [0,16383]. The parameter number displays the result of parameter# MSB shifted left 7 bits ORed (bitwise) with parameter# LSB [ math: (parameter# MSB << 7) | parameter# LSB ].
Off Value | Parameter value when drawstop/button goes to Off state.
On Value | Unused by this setting

###### RPN Range

Send RPN when the drawstop/button changes state.

GrandOrgue always sends Bn 0x65 parameter# MSB; Bn 0x64 parameter# LSB; Bn 0x06 parameter value. The parameter number displays the result of parameter# MSB shifted left 7 bits ORed (bitwise) with parameter# LSB [ math: (parameter# MSB << 7) | parameter# LSB ].

Off RPN number | RPN number MIDI messages sent when the drawstop/button goes to Off state. Range is [0, 16383]
On RPN number | RPN number MIDI messages sent when the drawstop/button goes to On state. Range is [0, 16383]
Value | Parameter value. Range is [0, 127]

###### NRPN Range

Send NRPN when the drawstop/button changes state.

GrandOrgue always sends Bn 0x63 parameter# MSB; Bn 0x62 parameter# LSB; Bn 0x06 parameter value. The parameter number displays the result of parameter# MSB shifted left 7 bits ORed (bitwise) with parameter# LSB [ math: (parameter# MSB << 7) | parameter# LSB ].

Off NRPN number | NRPN number MIDI messages sent when the drawstop/button goes to Off state. Range is [0, 16383]
On NRPN number | NRPN number MIDI messages sent when the drawstop/button goes to On state. Range is [0, 16383]
Value | Parameter value. Range is [0, 127]

#### Label

GrandOrgue supports "active" labels. These are labels which display variable contents, such as the step number in the Crescendo panel, the temperament name in the Master Controls panel and many others. Labels can be configured only for sending data to a MIDI LCD device. GrandOrgue sends the label contents following the Hauptwerk™ standards.

##### Hauptwerk SYSEX 32 byte LCD

This setting drives a Hauptwerk™ compatible LCD display, including the RGB LED color. Up to 32 characters are sent to the LCD display.

Channel

- Always disabled, since SYSEX is independent of any channel.

ID

- Sets the display's ID number. Range is [0, 127].

Color

- Sets the LED's color. Range is [0, 127].

##### Hauptwerk SYSEX 16 byte string

This setting sends character strings to a Hauptwerk™ compatible LCD display. The RGB LED (if any) color is ignored. Up to 16 characters are sent to the LCD display.

Channel

- Always disabled, since SYSEX is independent of any channel.

ID

- Sets the display's ID number. Range is [0, 127].

The "To initial" button copies the MIDI settings from the all tabs to the Initial MIDI settings. When the user loads another organ that contains a MIDI object with the same path as this one, it will inherit the MIDI settings from here unless they are not overriden in tat organ preset. In the future the user can alter the initial MIDI settings at Initial MIDI.

## Audio and Organ settings overview

### Audio & Organ settings overview

This schema describes the close relations that exist between the real-world audio hardware capabilities and the sample set disposition as provided by the sample set designer. For illustration, the free sample set of Bureå Church is customized to build a totally different spatial disposition. Here are the assumptions:

- The organ has a main case and a separate choir (RückPositiv) case in the organist's back

- The console is embedded facing the main case, therefore the main case sounds "front" and the choir case sounds "rear"

- The organ has 2 pedal turrets on the far left and right sides of the main case

- The organ has an echo keyboard in the basement of the main case

- The computer's audio device is 4.0 surround (front left and right speakers, rear left and right speakers)

Settings in the Settings... tab describe the physical environment, while settings in the Organ settings dialog describe how the different parts of the virtual organ map to the real-world audio outputs.

Channel: | a real-world channel of the audio device (e.g. left and right for a stereo board). GrandOrgue channel names are always Channel 1 to Channel n, n being the number of channels available on the audio device (stereo:2, surround 4.0:4, and so on). Only trial and error can determine which GrandOrgue channel is linked to which audio device physical channel.
Audio group: | a name holder used to design logical blocks within the audio system (e.g. "front speakers", "rear speakers", "subwoofer", ...). It is possible to create as many audio groups as needed. If an audio group is not used in the loaded sample set, it does add processing overhead, thus reducing polyphony, so adding unnecessary audio groups is not recommended.

In this example, the decision was made to

- sound the Choir (Svällverk) through the rear speakers, full volume

- sound the Great (Huvudverk) through the front speakers, full volume

- sound the Echo (Bröstverk) through the front speakers, softened volume

- sound the C side of the Pedal through the left front speaker

- sound the C# side of the Pedal through the right front speaker

This is done by linking audio groups to channels in the Settings... dialog and spreading pipes over the audio groups in the Organ Settings dialog.

## Program Settings

This tabbed dialog is displayed when the Settings... menu item is chosen in the File menu.

It manages "system-wide" GrandOrgue options. In other terms, these options apply to any loaded sample set.

These options are located at different places according to the platform.

Windows: | registry key HKEY_CURRENT_USER\Software\Our Organ\GrandOrgue and %APPDATA%\GrandOrgueConfig file
Linux: | $HOME/.GrandOrgue and $HOME/GrandOrgueConfig
macOS: | $HOME/Library/Preferences/GrandOrgue

When launched with an instance name (GrandOrgue -i instanceName), the name GrandOrgue becomes GrandOrgue-instanceName, the name GrandOrgueConfig becomes GrandOrgueConfig-instanceName

The user can reset settings to default values by deleting the "options files" according to the platform.

### Options tab

#### Options

#### Language frame

Select the language to use. A change requires a restart of the app. Also note that some dialogs might use the language set systemwide.

#### Enhancements frame

##### Active polyphony management

When polyphony reaches 3/4 of the current maximum value, release samples (reverberation tails) are faded out in order to conserve polyphony.

Memory

- No impact

Polyphony

- Conserved

Load time

- No impact

##### Release Sample Scaling

For those sample sets with long reverberation tails ("wet"), enabling this option will fade out the release sample if the note is played staccato. It will have little to no effect on "dry" sample sets.

Memory

- No impact

Polyphony

- No impact

Load time

- No impact

##### Randomize Pipe Speaking

This will apply a very small random detuning before each pipe begins to speak. The detuning is small enough so that the ear can't appreciate the tuning difference and large enough so that it approximates the tiny interferences (due to physical location) that occur when playing multiple real pipes in an organ.

Memory

- No impact

Polyphony

- No impact

Load time

- No impact

##### New Bas/Mel coupler behaviour

With this option checked an alternate algorithm will be used for Bas/Mel couplers that will reduce the number of missed notes at the expense of possibly having slightly more un-intended jumps between voices, depending on playing style.

Memory

- No impact

Polyphony

- No impact

Load time

- No impact

##### Load last file at startup

This will trigger the automatic load of the last used sample set.

Memory

- No impact

Polyphony

- No impact

Load time

- No impact

#### Sound engine frame

##### Interpolation

This dropdown controls the method used to interpolate the waveform when resampling the samples.

Polyphase

- This method gives better audio results at the expense of higher CPU load.

Linear

- This method lowers CPU load at he expense of audio quality.

The assertions about audio quality should be used as guidelines only. As a rule of thumb, polyphase gets better treble, linear gets better bass, and this is most noticeable in sample sets that use interpolation extensively (e.g. retuning a detuned organ). Audio quality is highly subjective, so the user is strongly encouraged to listen for himself and retain the setting that suits him better.

Memory

- No impact

Polyphony

- Linear gives more polyphony

Load time

- No impact

##### Number of CPU cores

This number states how many threads GrandOrgue creates to spread the load. Cores number is the recommended choice for computers without Hyper-threading. Less doesn't use the whole computer. More wastes resources while managing overhead.

With Hyper-threading enabled, the CPU load seems more evenly spread among virtual cores.

Memory

- No impact

Polyphony

- Raising the number of cores raises the polyphony attained before the sound starts to break.

Load time

- No impact

##### Workload distribution

This setting has the same role as Number of CPU cores, and is dedicated to splitting the workload. The same value as the number of CPU cores is recommended.

Memory

- Same as concurrency

Polyphony

- Same as concurrency

Load time

- Same as concurrency

##### Cores used at load time

This number states how many threads GrandOrgue creates to load samples in memory. It has NO effect when loading samples from cache.

Higher speed-up loading while reducing the available memory for samples. A zero (0) value means classic load.

##### Recorder WAV Format

This selects the format used by the Audio recorder. The supported formats are: 8 bit, 16 bit, 24 bit PCM and 32 bit IEEE float.

Memory

- No impact

Polyphony

- No impact

Load time

- No impact

##### Record stereo downmix

This text box enables GrandOrgue to record multi-channel audio in simple stereo. This option is disabled by default, as it increases CPU usage even if the audio recorder is off.

When stereo downmix is disabled, all audio channels are recorded in the WAV file.

Memory

- No impact

Polyphony

- Slightly - like an additional audio interface

Load time

- No impact

#### Volume

This spinner provides the default volume value. Initialized to -15 on the very first run of a GrandOrgue instance. This value is saved to settings files.

#### Sample loading frame

##### Lossless compression

Uses a lossless algorithm (i.e. the original samples can be perfectly reconstructed) so that RAM requirements are lessened. Particularly useful for large sample sets.

Memory

- Variable savings up to 40%

Polyphony

- Approx. 10% lower

Load time

- Approx. 20% slower. Only affects load without cache - as the compressed data is cached.

##### Load stereo samples

Selects whether stereo samples are loaded in Mono or Stereo

If set to Mono, all samples are loaded in Mono. When compression is disabled, this will save 50%, but when compression is enabled, much less will be saved because the compression is much less effective on monaural inputs.

This setting can be set to don't load, if you want GrandOrgue to avoid loading any samples. Via Organ Settings, it is still possible to load only specific parts of the organ.

Memory

- Variable savings up to 50%

Polyphony

- Slight impact, as loading in Mono saves a few calculations per sample.

Load time

- No impact

##### Sample size

Selects whether the samples are loaded with 8 or 12 or 16 or 24 bits precision.

Memory

- High impact

Polyphony

- The polyphony will increase with lower bit sizes and decrease with higher bit sizes.

Load time

- Slight impact

##### Loop loading

Selects which loop(s) are loaded if the samples have multiple loops.

First loop

- Load only the first loop.

Longest loop

- Load only the longest loop found in the sample. Longer loops usually feel more lively.

All loops

- Load all loops found in the sample. While playing, the loops are cycled using a round-robin scheme.

Memory

- First loop less than Longest loop less than All loops

Load time

- Increases with the amount of data loaded

Polyphony

- No impact

##### Attack loading

The sample set creator can provide multiple separate attack files.This selects which attack(s) are loaded.

All

- Load all attack files.

Single attack

- Load only the "best" provided file.

Memory

- Single attack less than All

Polyphony

- No impact

Load time

- Increases with the amount of data loaded

##### Release loading

The sample set creator can provide multiple separate release files.This selects which release(s) are loaded.

All

- Load all release files. The sound engine selects which release to play according to how much time the sustain sample was held. For example, it usually selects the shortest release sample while playing staccato.

Single release

- Load only the "best" provided release file.

Memory

- Same as Attack loading

Polyphony

- No impact

Load time

- Same as Attack loading

##### Memory limit

Chooses the size of the memory cache where samples are loaded. This is especially useful when running the 32 bits Windows build on 64 bits platforms to avoid a crash while loading a big sample set.

If this parameter is set to zero, it tries to load as much data as possible.

In this case, GrandOrgue keeps loading until the OS fails to provide memory. It can provide large amounts of swap space with expectable adverse impact on performances.

#### Cache frame

##### Compress cache

Selects whether the disk cache must be compressed when created or updated.

Memory

- No impact

Polyphony

- No impact

Load time

- Loading from an uncompressed cache is I/O bound, while loading from a compressed cache requires more CPU. With a slow disk + fast CPU, compressed might be better.

  This feature is closely related to the hardware capacities, so the user is encouraged to test for himself and retain the best setting for his computer.

##### Automatically manage cache

Selects whether the cache must be automatically created or updated when the sample set is loaded.

#### Perform strict ODF

Organ Definition File (ODF) syntax has much changed since the days of Hauptwerk™ version 1. Some Hauptwerk™ 1 keywords are not used by GrandOrgue and are reported as warning in the pop-up message window.

Introducing ODF warnings to GrandOrgue is a two-step development process:

1. A new warning is added to the ODF parsing utilities. It is displayed only in strict ODF mode, to give sample sets designers time to remove the new warning from their Organ Definition Files, without disturbing users.

2. After a suitable number of months has elapsed, the warning is moved to normal mode and is always displayed.

This checkbox enables strict ODF mode.

Sample set designers are strongly encouraged to update their Organ Definition Files in order to remove warnings and improve user experience.

Likewise, GrandOrgue users are strongly encouraged to report new warnings to the sample set designer.

#### Check ODF for HW1-compatibility

This checkbox enables warnings when some ODF keys are not compatible with the Hauptwerk 1. For example, when file names contains the '/' separator.

#### Metronome

These spinners provide default values for the number of beats per minute (BPM) and the number of beats per bar in the metronome panel. Initialized to 80 beats per minute and 4 beats per bar on the very first run of a GrandOrgue instance. They are saved to settings files.

### Paths tab

These text boxes provide default paths for various storage areas. They are initialized to paths in the GrandOrgue relative to the user's home folder, and their names are localized. The ... button located besides each text box allows to change the value.

The location of the GrandOrgue directory depends on the operating system:

Linux | $HOME/GrandOrgue/Organs
Windows | %HOMEDRIVE%\%HOMEDIR%\Documents\GrandOrgue
macOS | $HOME/Documents/GrandOrgue

#### Path usage

Sample sets | This is the folder where GrandOrgue looks for sample sets. It is opened when the File > Open menu item is selected. | Default: Organs
Organ packages | This is the folder where GrandOrgue looks for organ package files. Any organ package file dropped in this folder will be automatically searched for Organ Definition Files on next GrandOrgue run and any ODF found in the package file will be added to the known organs list.
Organ cache | This selects the directory where cache files are stored. | Default: Cache
Organ settings | This selects the directory where preset files are stored. | Default: Data
Combinations | This is the folder where GrandOrgue stores or looks for combinations files in YAML format. Combinations for different organs are stored in subfolders of this folder. The names of the subfolders equal to the organ names. The subfolder of the current loaded organ is opened when one of the File > Import Combinations , File > Export Combinations menu items is selected. | Default: Settings
Export/Import | This is the folder where GrandOrgue stores or looks for settings files. It is opened when one of the File > Import Settings , File > Export Settings menu items is selected. This folder is usually different from the folder where GrandOrgue stores preset files. | Default: Settings
Audio recording | This is the folder where GrandOrgue stores audio recording files. It is opened when the Audio Recorder STOP button is depressed. | Default: Audio recording
MIDI recording | This is the folder where GrandOrgue stores MIDI recording files. It is opened when the MIDI Recorder STOP button is depressed. | Default: MIDI recording
MIDI player | This is the folder where GrandOrgue looks for MIDI recording files. It is opened when the Audio/MIDI > Load MIDI menu item is selected. | Default: MIDI player

### Audio tab

This dialog selects the audio output device and defines which channels and audio groups the audio output is dispatched to, as well as audio stream parameters in the Sound output frame and the selection of shown devices/drivers in the Sound port frame.

Channel: | a real-world channel of the audio device (e.g. left and right for a stereo board). GrandOrgue channel names are always Channel 1 to Channel n, n being the number of channels available on the audio device (stereo:2, surround 4.0: 4, and so on). Only trial and error can determine which GrandOrgue channel is linked to which audio device physical channel.
Audio group: | a name holder used to fine tune the routing of audio output from the individual pipe to a particular channel of the audio device. See Organ Settings for more information.

#### Audio groups frame

This frame allows to manage audio groups. As said above, audio groups are name holders that are used to map the audio output of the individual pipe to definite parts of the audio system.

The system requires at least one audio group, and is initialized with a default audio group named Default audio group.

The Default audio group is always the first audio group in the list, so the Default audio group name can be changed at any time.

##### Add

The Add button opens a dialog where one can type the new audio group name.

If an audio group is not used in the loaded sample set, it does add processing overhead, thus reducing polyphony, so adding unnecessary audio groups is not recommended.

##### Delete

This feature is available when an audio group name is selected in the list. The Delete button is active. Push the button, the selected audio group is deleted.

If the deleted audio group is assigned to an organ element (Organ Settings dialog), all pipes routed to this audio group will be automatically routed to the default audio group.

##### Rename

This feature is available when an audio group name is selected in the list. The Rename button is active. It opens the same dialog as in Add, where the audio group's name can be changed.

If the renamed audio group is assigned to an organ element (Organ Settings dialog), all pipes routed to this audio group will be automatically routed to the default audio group.

#### Sound output frame

##### Sample rate

Selects the output sample rate. Allowed values are 44100, 48000, 96000 and 192000 Hz.

The sample rate should match both the configured sample rate in the audio interface and the sample rate of the recorded samples to avoid resampling. If not, resampling can occur in all layers of the audio stack, and audio quality can suffer.

##### Samples per buffer

Allowed values range from 16 to 2048 by increment of 16.

This parameter sets the output buffer size. Larger values usually reduce sound artifacts at the expense of latency.

#### Sound ports frame

##### Sound ports

By checking or unchecking the devices/drivers it's possible to filter the list of devices shown in the device picking dialog.

#### Managing Devices

##### Add device

This feature is available when the <Audio Output> node is selected. The Add button is active. This node is the place where it is technically possible to add multiple audio devices.

Multiple audio devices are currently NOT supported. Setting multiple audio devices leads to unpredictable results. A warning is displayed and if acknowledged, a new audio device is set in the list.

The Add button opens a pick list with all audio devices found in the system.

Each audio device is prefixed by its sound port and the API type (ASIO, DirectSound, ALSA, JACK, etc.)

Select the desired audio device. The devices list is updated with the new device which is initialized with a single channel.

The new device needs further configuration to be usable. See Managing Channels for more information.

###### Reminder

Multi-device configuration is NOT supported.

##### Change device

This feature is available when a Device: node is selected in the tree. The Change button is active. It opens the same pick list as for adding a device.

Select the desired device. The devices list is updated with the new device, while the channel configuration is retained.

##### Delete device

This feature is available when a Device: node is selected in the tree. The Delete button is active only if there are at least two devices in the tree.

Select the device to delete. Push the Delete button.The device is removed from the tree.

##### Device properties

The Properties button becomes active when an audio device is selected in the tree. It opens a dialog which allows to set a requested latency.

This feature is closely related to the samples per buffer setting in the Options tab. Its behavior differs according to the chosen backend.

###### Audio driver selection

GrandOrgue feature two audio backends:

RtAudio | selects the number of buffers based on the desired latency setting. The "samples per buffer" and sample rate setting must be supported by the sound card/driver, otherwise sound rendering will break.
PortAudio | uses the desired latency setting, the "samples per buffer" setting and the capabilities of the sound card/driver to determine the operational buffering it will use. Such drivers are marked with (PA) in its name.

Audio/Sound Output State tries to displays actual latency. Note that the estimate can be based on numbers provided by the hardware and the drivers and may vary. RtAudio is more likely to display to low numbers.

###### Windows

WDM/KS

- This driver allows direct access to the Windows kernel driver

  ASIO4ALL also uses that interface

  . This is the recommended driver if there is no other software which blocks access to the kernel audio streams. It is supported only via PortAudio.

WASAPI

- WASAPI support started with Window Vista. Use it if WDM/KS does not work for you. It is supported only via PortAudio.

  The sample rate of GrandOrgue must match the sample rate of the audio subsystem. So if WASAPI does not work, try a different sample rate in GrandOrgue.

DirectSound

- Use it if WDM/KS and WASAPI does not work for you. It is supported via PortAudio and RtAudio.

WMME

- This a classic, not low-latency audio API. Use it as last fallback. It is supported only via PortAudio.

ASIO

- GrandOrgue can be compiled with ASIO support. It is supported via PortAudio and RtAudio.

  ASIO loads third party code into the GO process, so a bad ASIO driver can cause GO hangs.

  There is no reason to use ASIO4ALL, because it acts as a pass-through to the native kernel streaming APIs (e.g. WDM/KS) that GrandOrgue can use directly.

Jack

- GrandOrgue can also be compiled with Jack Support on Windows. See the Linux Jack usage notes.

###### macOS

CoreAudio

- You can use the macOS native audio API CoreAudio via RtAudio as well as PulseAudio.

Jack

- GrandOrgue can also be compiled with Jack Support on macOS. See the Linux Jack usage notes.

###### Linux

ALSA

- You can use the Linux native sound output either via RtAudio as well as via PortAudio. To allow direct hardware access, your Linux user account needs access to the sound card

  that means being member of the audio group on many Linux distributions

  .

  ALSA also provides "virtual" sound card entries. "default" routes the audio to the current default sound card and allows shared access. If the active sample rate on the hardware does not match the GrandOrgue sample rate, ALSA will start resampling, which will increase the CPU usage.

  Distributions often route the default audio via the PulseAudio daemon. If you don't want to use PulseAudio, you can start GrandOrgue via via pasuspender(1).

Jack

- You can connect to a Jack audio server either via RtAudio as well as PulseAudio. GrandOrgue also includes jack MIDI support, so will likely see MIDI devices twice (via jack as well as via the native OS APIs).

  GrandOrgue has support for the native audio APIs and jack adds complexity to the sound output stack. Therefore avoid running jack, unless you want to use GrandOrgue together with other jack applications.

##### Matching

This feature is available when a Device: node is selected in the tree.

This button allows to define matching rules for devices whose name may be altered across reboots. See Device Matching for details

##### Revert to default

This button discards all audio configuration settings and creates a stereo configuration for the current device:

Channel 1: | one 'left' entry for each defined audio group, gain set to 0 db
Channel 2: | one 'right' entry for each defined audio group, gain set to 0 db

#### Managing Channels

##### Add channel

This feature is available when a Device: node is selected in the tree. The Add button becomes active only if the number of channels currently defined for that device is less than the device's maximum number of channels.

The Add button adds a new channel which is numbered with the next channel number. The new channel needs further configuration (audio groups) to be usable. See Managing Audio Groups for further information on that topic.

Only trial and error can determine which GrandOrgue channel is linked to each real-world audio channel.

##### Delete channel

This feature is available when a Channel n node is selected in the tree. The Delete button is active only if there are at least two channels defined for the device. Push the Delete button. The selected channel is deleted with its configuration.

### Device Matching

#### Device matching properties

This dialog allows to define matching rules for audio/MIDI device names

Physical device name

- This is the name of a Audio/MIDI device as it is reported by the Sound/MIDI port. A user cannot alter it, and this name may be not persistent across reboots

Logical device name

- This is the name of Audio/MIDI device as it is presented to the user. By default it is the same name as the physical name, but the user is capable to set some another name

  The logical device name must be unique

  If the user alters the logical name, a regex pattern must be provided so that GrandOrgue can find this device by its physical name.

  Specify the most common part among the different physical names that the device can have across reboots

Physical name regex pattern

- This is a pattern that allows GrandOrgue to find this Audio/MIDI device with it's physical device name.

  The simplest pattern would be the most common part of the physical device name that is always present and kept across reboots. More advanced regular expressions are also supported, look at https://en.wikibooks.org/wiki/Regular_Expressions/POSIX_Basic_Regular_Expressions for the full syntax.

  By default the regex pattern is empty so the device can be found only if it's physical name is equal to it's logical name

### MIDI Devices tab

#### MIDI devices options

This tab shows all available MIDI devices.

Auto add new devices

- This checkbox controls whether any new input devices will be enabled automatically when GrandOrgue starts.

Check on startup

- This checkbox controls whether to open the Program Settings dialog when GrandOrgue starts if no active MIDI devices can be found.

MIDI ports

- By checking or unchecking the MIDI ports it's possible to filter the list of MIDI devices used by GrandOrgue.

MIDI input devices

- This checklist shows all available MIDI input interfaces. Selecting a device means that GrandOrgue will listen for incoming MIDI messages through that interface. This allows to listen to more than one device at a time; for example, to listen to both a controller and a sequencer or loopback device.

  The
  Advanced button is grayed out unless an input channel is selected. It opens a dialog to set advanced properties of the selected input channel.

  #### MIDI input channel advanced properties

  This allows the setting of a channel offset. A channel offset allows the use of two MIDI interfaces with conflicting MIDI channels. For example, applying a channel offset of 8 to one of the MIDI interfaces would cause that interface's channel 1 to appear as channel 9, channel 2 to appear as channel 10, and so on. This may be useful if you have multiple keyboards that are configured to use the same channel.

  GrandOrgue is capable of matching the MIDI interface and this is configured by the MIDI detection by default. Therefore it is possible to use the same MIDI channel on multiple interfaces without configuring any channel offset.

  The MIDI-Output-Device button allows to select an output device where GrandOrgue will send MIDI all events received from this input device

  The Matching button allows to change the way Grandorgue recognizes the MIDI device. See Device Matching for details

MIDI output devices

- This checklist shows all available MIDI output interfaces. Selecting a device means that GrandOrgue will write MIDI information to external hardware. Possible uses are SAM or LED drivers for stop control feedback, or physical pipes drivers when digitally expanding a genuine pipe organ.

Send MIDI Recorder Output Stream

- The dropdown labeled Send MIDI Recorder Output Stream to allows the user to pick a target output MIDI device to receive all Recorder-generated output. The selected device must be activated in the MIDI output devices frame.

  When an output device is selected in that dropdown, the recorder output is generated even if no MIDI file is being recorded.

The devices list is refreshed whenever the Settings dialog is displayed.

GrandOrgue requires a MIDI input/output port to connect to. MIDI (sequencer) software, that just tries to connect to existing MIDI ports, is not compatible with GrandOrgue. If you want to use such software, create a virtual MIDI port

For linux, use sudo modprobe snd-seq-dummy ports=9

and let GrandOrgue as well as the other MIDI software connect to it. The name of the port must not contain "GrandOrgue".

### Initial MIDI tab

This screen displays default MIDI settings which enable the user to store some physical console MIDI settings.

When a sample set is loaded for the first time OR without customization, these default settings are used to initialize the MIDI Event dialogs that are accessible by right-clicking a control in the GUI (e.g. manual, stop, enclosure, piston, etc.).

Customizations done by the user always supersede the matching initial setting. If customizations of some MIDI objects are saved to a preset number, all subsequent loads will ignore the initial MIDI settings for these objects and all further updates to the sample set's MIDI configuration will be done by right-clicking on the elements in the user interface.

There are two parts of initial MIDI objects: built-in ones and user-added ones. The built-in objects have different groups and they are matched with ODF by MIDIInputNumber. The user-added objects have "user-added" as their group and they are matched by their path.

A user can add more Initial MIDI objects from the right-click MIDI event editor or from the MIDI Objects dialog. The user-added Initial MIDI settings take precedence over the built-in objects settings.

When a loaded sample set is reset to default, the preset file is deleted and the initial MIDI settings are used again to initialize the MIDI configuration.

The sample set creator must define proper MIDIInputNumber values in the Organ Definition File to make manual mapping and enclosure mapping to the initial MIDI settings work properly.

The "Group" column shows which group the element is filed under. The "Type column shows the MIDI object type. The "Name" column identifies the object. The "Matching" column shows the value a particular MIDI object in the loaded organ is matched by. The "Configured" column shows if the object is associated to MIDI event(s).

The MIDI Event Editor can be displayed by selecting an element and pushing the "Properties" button, or by double-clicking on the element's entry.

The available initial setting are those that are tied to the physical hardware and have no reason to change across dispositions:

Manuals Group

- MIDI setting for pedal (always Manual 0) and up to 5 manuals. Manuals are ordered bottom (Manual 1) to top (Manual 5).

Enclosures Group

- MIDI setting for up to 6 enclosures. Enclosures are ordered left (Enclosure 1) to right (Enclosure 6).

Sequencer Group

- MIDI setting for various useful controls from the combination setter.

  Previous Memory, Next Memory

- Navigate the memory banks.

Memory Set

- Store a combination in a memory slot.

Current

- Recalls the current combination.

G.C.

- General Cancel.

-10, +10

- Navigate 10 slots backwards or forward in the current memory bank without recalling the combination (prepare it).

__0 .. __9

- Navigate to slot xx0 to xx9 and recall the combination, the first two digits being set by the +/-10 controls.

Master Controls Group

- MIDI setting for various useful controls from the main control panel.

  -1 Cent, +1 Cent, -100 Cent, +100 Cent

- These controls drive the amount of tuning for the whole organ.

Prev Temperament, Next Temperament

- Navigate the temperaments list.

Transpose -, Transpose +

- Transpose down, transpose up, one semitone at a time.

User-added Group

- MIDI settings for any MIDI objects. If a MIDI object exists in any loaded organ with the path equal to the value in the Matching column then it inherits the MIDI settings from here unless they are not oveddiden in the organ preset.

The "Delete" button allows to delete the selected MIDI obects from the list. Only user-added initial MIDI objects may be deleted.

### Organs tab

This tab manages the known organs list.

All organs successfully loaded via the File/Open menu item are automatically registered in this list.

Additional information about each organ is shown on the bottom part of this tab when the user selects it in the list.

Organs can be registered in multiple ways. When a user opens an .organ file first time, the organ is registered. When the user installs an organ package (.orgue) file, all organs present in the package are registered. Also .orgue packages placed in the packages directory are read upon GrandOrgue startup and all their organs are also registered.

This list provides for the lists displayed in the File/Load, File/Open Recent and File/Favorites menu items.

The buttons are grayed out until at least one line is selected in the list.

The organs order on this tab is reproduced as is in the File/Load menu whereas only the 10 first entries are displayed in the File/Favorites menu.

##### Name

The name of the organ from its ODF.

##### MIDI

Yes - some MIDI event has been assigned to this organ.

No - no MIDI events have been assigned to this organ.

##### Path

For the packaged organs - the filesystem path to the its .orgue file.

For the not packaged organs - the filesystem path to the its ODF file.

##### Builder, Recording

The contents of the corresponding fields from the ODF.

##### Organ hash

A calculated string used for composing the cache and preset filenames.

##### Package id

Only for packaged organs. A special string used for matching between organs and organ packages.

##### Package name

Only for packaged organs. The name of the organ package. It is often equals to the name of the packaged organ, but may differ from it.

##### Path in package

Only for packaged organs. The relative path to the ODF in the package. One package may contain several organs with different ODF paths.

##### Package hash

Only for packaged organs. The calculated string used for composing the name of the index file in the Cache directory.

##### Package info

Only for packaged organs. Additional information about the organ package.

##### Down

This button moves the selected entry/entries down one position. It is grayed out if the selected line is last in the list.

##### Up

This button moves the selected entry/entries up one position. It is grayed out if the selected line is first in the list.

##### Top

This button moves the selected entry/entries to the first position in the list. It is grayed out if a selected line is first in the list.

##### MIDI...

This button opens the MIDI Event Editor to manage the MIDI event(s) which enable GrandOrgue to load a sample set when received.

A use case of this feature can be: use a rotary selector that sends MIDI Program Change messages to easily switch between sample sets.

##### Relocate

This button opens a file choosing dialog for specifying the new path to the file the organ was opened from. It is useful after moving the organ files to another directory, and the original path is no longer valid.

##### Delete Cache

This button removes all cache files for the selected organ(s). The cache files are deleted only when the user saves the settings. The cache may be recreated later automatically or with the "Update Cache" menu entry.

##### Delete Presets

This button removes all setting files for the selected organ(s) that were saved with the Save menu entry. All the user settings for the organ will be lost. The cache files are deleted only when the user saves the settings.

##### Delete

This button removes a line from the list. GrandOrgue deregisters this organ.

If a cache or presets were saved and/or the samples were cached, the files are ALSO deleted from disk.

The sample set files of the package .orgue file are NOT deleted from disk.

### Reverb tab

#### Reverberation options

This tab manages settings for an embedded Convolution Reverberation engine.

Convolution reverberation uses the mathematical model of a room response to alter an audio wave so it sounds as if it had been produced in that room. The room response is triggered by a bang (starter pistol, balloon pop, hands clap, ...) which is closest to a pulse covering all frequencies. The room response is made of the volume and decay of sound reflection on walls, floor, ceiling, and the delay introduced by the room size. The bang record is fed to the convolution engine to produce the reverberated wave.

The reverberated wave is usually mixed with the direct dry sound to better simulate what the auditor would hear if he were in the physical room.

Enable Convolution Reverb

- This checkbox enables the feature.

Browse Impulse Response

- This button opens a file chooser which allows to choose and load an impulse response file. GrandOrgue currently supports only Wave (.wav) or WavPack (.wpk) files.

  A response file is required when the reverberation is enabled.

  GrandOrgue wiki displays a page linking to sites where IR files can be downloaded.

Delay

- This spinner sets the delay in ms before the reverberated signal quicks in. This setting is additive to the delay that can be generated by the IR file itself.

Start Offset

- This spinner sets the number of samples to skip from the beginning of the impulse response file.

Length

- This spinner sets the number of samples to use in the impulse response file (starting from the offset).

Channel

- This dropdown sets the channel to use in an impulse response file. Depending on the recording method, an IR file can have many channels. GrandOrgue current reverberation engine uses only one channel.

Gain

- This spinner sets the gain to apply to the reverberated signal. Use low values (< 0.1) to avoid artifacts by overloading the sound system.

Direct Sound

- This checkbox enables mixing the direct and reverberated signals.

  The reverberated sound, when fed alone to the audio system, usually sounds a bit muffled and a bit garbled by the alterations introduced by the room response (delays, multiple echos, etc.). Adding the direct sound is the only way to get a clear sound, so this box should be checked at all times.

  Set the release tail length to a low value if you want to use the convolution reverberation alone, ie. without the recorded release tail of wet samples.

### Temperaments tab

#### User-defined Temperaments

This tab enables the user to add his own custom temperaments. User-defined temperaments are displayed in dynamic submenus in the Audio/MIDI > Temperaments menu.

The Add button adds a new "empty" line.

The Delete button deletes the selected line.

Group

- Defines the submenu label in the Audio/MIDI > Temperaments menu. The submenus are dynamically added as soon as this screen has entries. Entries having the same Group attribute are grouped in the same submenu.

Name

- Defines the menu item label.

c, c# ... b

- A column for each note of the scale defines the deviation in cents from equal temperament for that note.

To modify any value in the grid, double-click in the cell. Updated values are stored as soon as the OK button is depressed.

Temperaments are stored in the system-wide configuration file.

### Metronome tab

#### Metronome

This tab allows to specify the internal GrandOrgue Metronome paramets.

The metronome is available in the metronome panel.

#### BPM

These spinners provide default values for the number of beats per minute.

#### Ticks per Measure

These spinners provide default values for the number of beats per bar.

Initialized to 80 beats per minute and 4 beats per bar on the very first run of a GrandOrgue instance. They are saved to settings files.

#### Metronome Sound Type

These radiobuttons allow to choose between different metronome sounds.

Bell and Click are some sounds provided by GrandOrgue.

Custom requires a user to specify the path to wave files containing the metronome sound in the next two fields.

#### Custom Sound Wave Paths

These fields for specifying the path to wave files for Custom sound. They are ignored if Custom is not selected.

Lots of different free metronome sound files may be downloaded from https://www.reddit.com/r/audioengineering/comments/kg8gth/free_click_track_sound_archive .

#### First Beat

A sound file path with the first beat of a measure.

#### Beat

A sound file path with all other beats of a measure.

A current loaded organ should be reloaded for changing the metronome sound.

## Organ settings

This dialog allows to customize settings for the currently loaded sample set.

Initial values come from the current preset number or imported settings file or from the organ definition file if the settings file does not exist.

Modified settings are saved in the current preset number. They also can be exported to a settings file.

### Pipes

#### Organ Settings dialog, Pipes tab

In its left box, this dialog displays all ranks found in the definition file grouped by windchest. The tree can unfold down to the individual pipe level. Within windchests, the ranks are ordered as found in the definition file.

When the tree is unfolded down to the pipe level, the dialog displays the MIDI number assigned to the sample file, along with the file's path.

The right frames display controls which allow to fine set features at the rank or pipe level.

Settings can be modified at the organ, windchest, rank and individual pipe level.

Some setting are cumulative from the organ level down to the pipe level: the effective setting value applied to the individual pipe is calculated from values at all levels.

For the other (non cumulative) settings, the effective setting value is applied to the individual pipe using these precedence rules:

- If a pipe-level value is defined, use it

- Else if a rank-level value is defined, use it

- Else if a windchest-level value is defined, use it

- Else if an organ-level value is defined, use it

- Else use the value defined in the Program Settings dialog Options tab if any.

Select the element you wish to customize. The right frames are populated with values picked from the organ definition file or the current preset number if the latter was saved.

It is possible to select multiple elements at once, to e.g. update one setting of multiple elements to the same value in a single operation.

To the sample set designer: Fine customizations to the sample set, when made in the Organ Settings dialog, are NOT copied to the organ definition file. If they were designed to be integral part of the sample set, these customizations need to be manually merged from the settings file to the organ definition file. It is however possible to export the settings to a file with the same name as the ODF file, except that the suffix must be .cmb instead of .organ (eg. TheOrgan.organ becomes TheOrgan.cmb as name for the exported settings file). When that settings file is put in the same directory as it's companion .organ file, it will be used as default settings for that organ.

#### Settings frame

##### Amplitude

Linear amplitude scale factor applied to the element. The allowed range is {0, +1000}. Amplitude is cumulative from organ level down to pipe level.

Note: A 100 value means that this setting value has no effect on the effective amplitude.

##### Gain

Amplitude scale factor in dB applied to the selected element. The allowed range is {-120, +40}. Gain is cumulative from organ level down to pipe level.

Note: A 0 value means that this setting value has no effect on the effective gain.

##### ManualTuning

This spinner allows to fine tune the pitch of the element. The unit is 1/100th of a semitone, and the allowed range is {-1800, +1800}. Tuning is cumulative from organ level down to pipe level. This value is used only with the original temperament.

Note: A 0 value means that this setting value has no effect on the effective tuning.

##### AutoTuningCorrection

This spinner allows to fine tune the pitch of the element. The unit is 1/100th of a semitone, and the allowed range is {-1800, +1800}. Tuning is cumulative from organ level down to pipe level. This value is used only with the non-original temperaments.

Note: A 0 value means that this setting value has no effect on the effective tuning.

##### Tracker

This spinner allows to define a delay in ms. This delay simulates the time spent by the tracker system to open the valve after a key is depressed.

Tracker delay is cumulative from organ level down to pipe level.

##### Release Length

The release tail length control limits the duration the sound engine uses to play the release section of the sample. The values are: Max or a range from 50 ms to 3000 ms by increments of 50 ms. Max means playing the full release section without a limit.

The organ-wide limit can be set also on the GrandOrgan toolbar. The limits of the lower levels may only decrease the limit of the upper levels.

##### Tone balance

This setting adjusts the bass/treble harmonics balance of the pipes. The value is a converted to a cutoff frequency for a filter where a negative number means less high frequencies and a positive number means less low frequencies. Allowed range is {-100, +100}. A tone balance value which is not zero on a child level will override a value set at any parent level.

Note: A 0 value means that this setting value has no effect on the effective tone balance. Using this setting on the individual pipe level usually gives the best results.

##### Audio Group

This dropdown selects which audio group the sound from the selected element is routed to

Note: A blank value means that this setting value is fetched from the upper level. If the effective audio group is still blank, the pipe is routed to the default audio group.

##### Ignore pitch info in organ samples wav files

This feature is closely related to the temperament feature which assumes, when the samples are dynamically retuned after a new temperament is applied, that pitch information was embedded in each sample file or in the pipe entry within the Organ Definition File. If the sample set designer has NOT embedded pitch information, the result is weird and unpredictable.

When checked, this box instructs GrandOrgue to ignore any pitch information found is sample files while retuning the organ to another temperament than the original. This way the retuned sample set behaves as expected. In this case, GrandOrgue assumes that the samples are tuned to equal temperament.

#### Sample loading frame

##### Sample size

This dropdown list allows to overwrite its counterpart at the parent level.

The Parent default value means that the value is fetched from the parent level.

See Sample size in the Program Settings dialog for further detail on this topic.

##### Lossless Compression

This dropdown list allows to overwrite its counterpart at the parent level. The allowed values are:

Parent default

- Means that the value is fetched from the parent level.

Enabled

- Enables lossless compression at that level

Disabled

- Disables lossless compression at that level

See Lossless compression in the Program Settings dialog for further detail on this topic.

##### Sample channels

This dropdown list allows to overwrite its counterpart at the parent level. The allowed values are:

Parent default

- Means that the value is fetched from the parent level.

Don't load

- Don't load the samples at that level.

Mono

- Load stereo samples in mono.

Stereo

- Load stereo samples in stereo.

See Load stereo samples in the Program Settings dialog for further detail on this topic.

##### Loop loading

This dropdown list allows to overwrite its counterpart at the parent level. The allowed values are:

Parent default

- Means that the value is fetched from the parent level.

First loop

- Load the first loop found in the sample file.

Longest loop

- Load the longest loop found in the sample file.

All loops

- Load all loops found in the sample file.

See Loop loading in the Program Settings dialog for further detail on this topic.

##### Attack loading

This dropdown list allows to overwrite its counterpart at the parent level. The allowed values are:

Parent default

- Means that the value is fetched from the parent level.

Single attack

- Loads only the "best" provided attack sample file.

All

- Loads all attack sample files

See Attack loading in the Program Settings dialog for further detail on this topic.

##### Release loading

This dropdown list allows to overwrite its counterpart at the parent level. The allowed values are:

Parent default

- Means that the value is fetched from the parent level.

Single release

- Loads only the "best" provided release sample file.

All

- Loads all release sample files

See Release loading in the Program Settings dialog for further detail on this topic.

### Enclosures

#### Organ Settings dialog, Enclosures tab

In its left box, this dialog displays all enclosures: both added internally by GrandOrgue and the ones found in the definition file. Only the enclosures added internally are allowed to be changed.

Select the element you wish to customize. The right controls are populated with values picked from the organ definition file or the current preset number if the latter was saved.

It is possible to select multiple elements at once, to e.g. update one setting of multiple elements to the same value in a single operation.

#### Affected windchests

The list of windchest the enclosure affects.

#### Minimum amplitude level

Linear sound amplitude scale factor when the enclosure is closed. The allowed range is 0, 100.

0 means complete silence. 100 means the enclosure does not affect the windchest volume at all.

### Buttons row

These buttons are used to drive the dialog and always act on the selected element.

Help

- This button opens the help window.

Distribute audio groups

- This button allows to spread the selected elements over selected audio groups. The elements are spread over audio groups using a round-robin scheme.

  Select the elements to spread, click the button. A dialog opens where the desired audio groups can be selected by checking their box. Push the OK button. The modification is applied.

  The round-robin scheme is applied to the audio groups in their display order in the selector dialog. They appear in that dialog in the same order they were created. Therefore, when elements need to be spread over a list of audio groups, these audio groups must be created in the order of the round-robin scheme.

Default

- This button restores the setting values for the selected elements from the organ definition.

  Because the audio group cannot be specified in the ODF, the Default button does not affect the Audio group setting. For resetting an audio group for the selected elements the user has to select the empty value in the Audio Group field and press to the Apply button.

  This action can not be undone with the Discard button.

  If any of selected elements has a subelement then a confirmation box will appear.

  Pushing No causes restoring the values only for the selected elements but not for their subelements.

  Pushing Yes causes restoring the values for the selected and for all their subelements recursivelly.

  Pushing Cancel causing not changing anything.

Discard

- This button is grayed out until any value is modified. It restores all previously changed values that have not yet been applied.

Apply

- This button applies all modified values to the selected element. Changes MUST be applied or discarded before proceeding to another element modification or closing the dialog with the Close button.

Close

- This button closes the Organ Settings window.

  If some changes have not yet been applied then GrandOrgue rejects closing the window and asks the user to press either Apply or Discard button before.

## Panels

This menu controls control panels. Menu items starting at Coupler down to Recorder are standard menu items (i.e. present whatever sample set is loaded).

All other menu items (above Coupler) are defined within the loaded sample set and should be documented in the sample set's specific user manual (if any). They usually are referred to as Custom Panels.

Custom Panel menu items can be organized in submenus as shown in this screen shot taken from Piteå Music School sample set.

### Coupler

GrandOrgue provides a default set of couplers for each keyboard or pedal board found in the Organ Definition File, plus a coupler set for each of the default coupler manuals. This enables the user to take advantage of "modern" accessories even when the sample set doesn't provide them.

The menu items display the master keyboards, i.e. the keyboard that "pulls" the coupled keyboards.

The coupler panel displays a line of controls for every target keyboard or pedal board found in the Organ Definition file.

The coupling manuals are not designed to be the target of a coupler.

#### Coupler <keyboard name> Layout

16 | Sub-octave coupler. The target key/pedal board is "pulled" 1 octave lower than the note played on the "master" key/pedal board.
8 | "Normal" coupler. The target key/pedal board is "pulled" at the same octave as the note played on the "master" key/pedal board.
U.O. | Unison Off. When engaged, this coupler mutes the pipes at the played note pitch on the "master" key/pedal board. There are many use cases like using the octave/sub-octave couplers alone, turning the keyboard into a coupling keyboard, etc.
4 | Octave coupler. The target key/pedal board is "pulled" 1 octave over the note played on the "master" key/pedal board.
BAS | "Bass" coupler. The lowest note in any chord played on the "master" keyboard is "pulled" on the target key/pedal board.
MEL | "Melody" coupler. The upper note in any chord played on the "master" keyboard is "pulled" on the target key/pedal board.
Couple Through | When it is engaged, any source manual key pressing is transfering to all engaged target manual further couplers for all couplers in this row

In multi-part polyphony, the BASS coupler tries to enforce the rests found in the lowest line. This is not 100% safe, so unwanted jumps to the next upper line may occur. The same applies for the MEL coupler and the highest line.

### Regular, Scope and Scoped, Full

These features are shared by the Crescendo, Divisionals, Generals and Combination Setter panels and are documented once here.

#### Regular

Regular enables to control all stops and pistons as allowed by the Organ Definition file (see Full below). When Regular is on while setting, the current state of all stops and couplers is stored. The scope is set to "all elements". This is the default behavior.

#### Scope

When Scope is on while setting, the combination data store is configured for its storing only the currently turned on elements. Never forget to push all buttons intended to drive that scope.

#### Scoped

When Scoped is on while setting, the current state of the elements stored with scope is saved.

##### Typical working sequence of operations:

1. Turn on some stops and couplers

2. Turn on Scope

3. Turn on Set

4. Push all buttons intended to use that scope

5. Turn on Scoped

6. Turn on the stops and couplers wished for the fist button

7. Push the button (make sure that Set is turned on)

8. Repeat 6-7 for all buttons

Once the scope is defined and assigned to a piston, there is no need to redefine it (steps 1-4) if the saved state of the elements in scope is changed (steps 5-6-7).

#### Full

Full allows to store all stops and couplers in a combination, regardless of restrictions that may have been defined in the Organ Definition File. See StoreInDivisional, StoreInGeneral, DivisionalsStoreIntermanualCouplers, DivisionalsStoreIntramanualCouplers, DivisionalsStoreTremulants, GeneralsStoreDivisionalCouplers and CombinationsStoreNonDisplayedDrawstops for more information.

### Crescendo Pedal

GrandOrgue automatically adds 4 crescendo banks of 32 steps each. This enables the user to take advantage of "modern" accessories even when the sample set doesn't provide them.

Label on top

- Displays the current step. It is an "active" label, and as such supports a MIDI send configuration

Set

- Shortcut to Memory Set

Regular

Scope

Scoped

Full

- See Regular, Scope and Scoped, Full

A

B

C

D

- Select the crescendo bank to use. The current bank is highlighted

Override

- Switches the crescendo operational mode between the Override and the Add one.

  The mode determines how the crescendo enables/disables stops when the crescendo level is changed.

  In the Override mode all stops enabled by the user are forgotten and only the stops defined for the crescendo level are enabled.

  In the Add mode the stops enabled by the user are remains unchanged. Only the new stops defined for the crescendo level are enabled or disabled/

<

- Move to the previous step. While setting, store the state of drawstops and couplers (according to regular or scope/scoped) into the previous step.

Current

- While setting, store the state of drawstops and couplers (according to regular or scope/scoped) into the current crescendo step, otherwise recall the current step's state.

>

- Move to the next step. While setting, store the state of drawstops and couplers (according to regular or scope/scoped) into the next step.

Crescendo shoe

- This shoe controls the crescendo. It behaves like an expression shoe. If the physical console has a dedicated MIDI controller, the 32 steps are evenly spread across the range of values set in the MIDI event editor

### Divisionals

GrandOrgue automatically adds a set of 20 banks of 10 divisional combination stores to each keyboard or pedal board found in the Organ Definition file. This enables the user to take advantage of "modern" accessories even when the sample set doesn't provide them.

Set

- Shortcut to Memory Set

Regular

Scope

Scoped

Full

- See Regular, Scope and Scoped, Full

1

2

3

4

5

6

7

8

9

10

- Enable the N-combination stored in the current bank.

Label in between

- Displays the current bank for the division. Values are letters from A to T. It is an "active" label, and as such supports a MIDI send configuration

-

+

- Switch current bank for the division to the previous and to the next

#### Notes

- A division button changes it's state after pressing only if there is combination stored to it or the Set button is active.

- All buttons in this panel are enabled for a MIDI Event configuration.

- All configuration done on this panel can be saved to the current preset number. If not, GrandOrgue always asks to save on sample set unloading.

### Generals

GrandOrgue automatically adds 4 banks of 50 general combination stores to any loaded sample set. This enables the user to take advantage of "modern" accessories even when the sample set doesn't provide them.

Prev

- Switch to the previous generals bank

Label in between

- Displays the current bank. Values are A, B, C, D. It is an "active" label, and as such supports a MIDI send configuration

Next

- Switch to the next generals bank

Set

- Shortcut to Memory Set

Regular

Scope

Scoped

Full

- See Regular, Scope and Scoped, Full

#### Notes

- All buttons in this panel are enabled for a MIDI Event configuration.

- All configuration done on this panel can be saved to the current preset number. If not, GrandOrgue always asks to save on sample set unloading.

### Combination Setter

GrandOrgue automatically adds a 1000-slot combination setter to any loaded sample set. This enables the user to take advantage of "modern" accessories even when the sample set doesn't provide them.

Label on top

- Displays the current slot. It is an "active" label, and as such supports a MIDI send configuration

Second line

- This line has elements for working with yaml combination files in the current combinations directory. By default it is a subdirectory with the same name as the current loaded organ name in the Combinations directory. But after importing a yaml combination file with the Import Combinations menu item, the current combinations directory becomes the directory where the combination file has been loaded from.

Large label on the second line

- Displays a yaml combination file name. It may be either the file that is loaded or another file the current combinations directory when the user navigates over them. It is an "active" label, and as such supports a MIDI send configuration.

Refresh files

- Reload the list of combination files the current combinations directory.

Prev file

- Navigate to a previous (in alphabetical order) combinations file in the directory.

Next file

- Navigate to a next (in alphabetical order) combinations file in the directory.

Load file

- Load the combination file displayed in the label. The lighting of the button shows whether the currently displayed file is loaded (dark) or not loaded (light). After loading the combination file with this button, the 000 slot is activated automatically.

Save file

- Save the current combinations file to the file whrere they were previously been loaded from. This button works only if the label is navigated to this file (the Save button is dark). Lighting of this button shows whether the combinations set has been changed (light) or not (dark) since it was loaded.

  This button allows to save the combinations to the same file where they have been loaded from. For saving combinations to another file or for creating a new one use the Export Combinations menu item.

Current

- While setting, store the state of drawstops and couplers (according to regular or scope/scoped) into the current slot, otherwise recall the current slot's state.

-100

+100

- Navigate 100 slots backwards or forward without recalling the combination (prepare it)

-10

+10

- Navigate 10 slots backwards or forward without recalling the combination (prepare it)

-1

+1

- Navigate 1 slot backwards or forward without recalling the combination (prepare it)

Next

- While setting, store the state of drawstops and couplers (according to regular or scope/scoped) into the next slot, otherwise recall the next slot's state.

Previous

- While setting, store the state of drawstops and couplers (according to regular or scope/scoped) into the previous slot, otherwise recall the previous slot's state.

__0 .. __9

- While setting, navigate to slot xx0 to xx9 and store the state of drawstops and couplers (according to regular or scope/scoped), otherwise navigate to slot xx0 to xx9 and recall the combination. The first two digits were previously set by the +/-100 and +/-10 controls.

Set

- Shortcut to Memory Set

N

- Activate the Numeric setter mode.

  While this mode is active, the user may press three numeric buttons in the fourth line to switch to a combination with this three-digit number, for example, 007, 143 etc. The numeric mode is deactivated as soon as three numbers are entered.

  Pressing N second time deactivates the numeric mode.

Regular

Scope

Scoped

Full

- See Regular, Scope and Scoped, Full

G.C.

- General cancel. Resets the state to "all pushed"

Insert

- Shifts right all slots following the current slot. The behavior changes depending on the state of the Set button.

  Set ON

- the state of drawstops and couplers (according to regular or scope/scoped) is stored in the current slot

Set OFF

- the state of the current slot (including scope) is kept unmodified

The combination stored in the last slot (#999) is lost

Delete

- Shifts left all slots following the current slot. The state of the Set button does not change the behavior.

  The combination stored in the current slot is lost. The combination stored in slot #999 is reset to "empty".

Hidden buttons

- There are two hidden buttons, Panic and Exit GO, that serve as MIDI receivers only, not visible in this panel for mouse interaction. To configure them, go to Audio/MIDI menu, MIDI Objects and look for type Button, elements Panic resp. Exit to assign MIDI events that will fire the two functions.

### Coupler Manuals and Volume

This panel displays a III/P fictional console with swell shoes. The keyboards are coupler manuals. This fictional console is independent of the actual layout of the sample set.

#### Coupler manuals

A coupler manual is mute, as it is not connected to a division. By design, any keyboard (including pedal) can be coupled to a coupler manual (see Couplers>).

A set of 4 coupler manuals is added to each loaded sample set, whatever the actual number of manuals and/or pedal boards. The coupler manuals are numbered bottom to top. The coupler manual number 0 is displayed as pedal.

The displayed compass is derived from the lowest and highest MIDI key number found in the organ definition file. Each coupler manual is fit with 10 divisional pistons.

#### Expression shoes

An enclosure expression shoe is added to each windchest found in the Organ Definition File, plus another designed to control the whole virtual organ volume.

The embedded metronome is managed using its own separate windchest.

These enclosure settings are NOT replicated anywhere in the user interface.

These enclosure settings are saved in the current settings file only when the File > Save menu item is used.

### Metronome

This panel controls the embedded metronome.

#### ON

This is the On / Off button. Starts or stops the metronome.

#### Bar length settings

This section manages the number of metronome beats per bar. The first beat of each bar is emphasized using a different sound. The initial value when the panel is first opened is 4.

If the number of beats per bar is set to 0, the "other beat" tick sound is used.

If the number of beats per bar is set to 1, the "first beat" tick sound is used.

-1 | Decreases the number of beats per bar by 1.
+1 | Increases the number of beats per bar by 1.
Label in between | This label displays the current beats per bar number. It is an active label, meaning that it can be configured to send MIDI messages.

#### Beat per minute settings

This section manages the number of metronome beats per minute. The initial value when the panel is first opened is 80.

-10 | Decreases the number of beats per minute by 10.
-1 | Decreases the number of beats per minute by 1.
+1 | Increases the number of beats per minute by 1.
+10 | Increases the number of beats per minute by 10.
Label in between | This label displays the current beats per minute number. It is an active label, meaning that it can be configured to send MIDI messages.

The metronome settings can be saved in the current settings file and remembered the next time the sample set is loaded. Use the File > Save menu item, as there is no warning to save when the sample set is closed with changed metronome settings.

### Updates

#### Check for updates at startup

Check the checkbox here if you would like GrandOrgue to notify you when a new version of GrandOrgue is available. If there is one, GrandOrgue will create a new menu Update available!.

### Master Controls

This panel groups at the same place some controls that are used while playing. Each displayed element can be associated to a MIDI event and thus linked to a physical control on the console. This enables the user to ignore the computer and concentrate on his playing.

Master controls are specific to the console hardware. As such, their MIDI configuration can also be defined in the Program settings, Initial MIDI tab.

#### Tuning

The first row controls the ability to tune the whole organ. All tuning done from the master controls panel is mirrored in the Organ Settings, Settings frame, Tuning (Cent) spinner and will be saved in the current preset file.

-100, -10, -1 buttons | Tune down by amount of 100, 10, 1 cent(s) respectively
+100, +10, +1 buttons | Tune up by amount of 100, 10, 1 cent(s) respectively
Label in between | This label displays the current tuning amount. It is an "active" label, and as such supports a MIDI send configuration

##### Reminder

The tuning unit is 1/100th of a semitone. The allowed range is {-1800, +1800 }, i.e. {-1, +1} octave. A semitone is 100 tuning units.

#### Temperament

The second row controls the ability to navigate the temperaments list. The temperament selection in the master controls panels is mirrored in the Temperament menu item of the Audio/MIDI menu.

< button | Go to the previous temperament in the list
> button | Go to the next temperament in the list
Label in between | This label displays the current temperament name. It is an "active" label, and as such supports a MIDI send configuration

#### Save

The Save button in the middle row saves the current sample set customization in the current preset file. It has the same usage as the Save menu item in the File menu.

#### Transposer

The third row controls the transposer. The transposer state is mirrored in the transposer spinner in the toolbar.

< button | Shift all keyboards down one semitone
> button | Shift all keyboards up one semitone
Label in between | This label displays the current transposer state. It is an "active" label, and as such supports a MIDI send configuration

#### Readiness indicators

The fourth row displays readiness indicators which change state when the sample set finishes loading

ON "LED" | This "LED" is rendered as a lighted button and as such supports a MIDI send configuration
Label | This label displays the organ name. It is an "active" label, and as such supports a MIDI send configuration

### Recorder

This panel controls the MIDI recorder and the Audio recorder.

Both recorders behave identically

REC | This button starts recording a file, using a default file name that cannot be changed. See below for the file name syntax.The button stays highlighted until STOP is pressed.
STOP | This button stops the current recording. If The recording was started with REC, the file is silently saved under the default file name. If the recording was started with REC File, a file chooser is displayed, allowing the user to rename the file from its default name.
REC File | This button starts recording a file while enabling the user to rename the file when the recording stops.
Right-side Label | This label displays the recording duration while the recorder is active.

This paneled recorder enables the user to tie both recorders to MIDI events. This way, recording can be easily started and stopped on the fly from console buttons or computer keyboard shortcuts.

#### Notes

- Pressing REC while recording will silently switch to a new file.

- Pressing REC File while recording will switch to a new file. A new file chooser is displayed each time this button is pressed, thus "stacking" the renaming request. This way, all actual renaming is postponed to after the recording session is finished.

- The default file name is a timestamp. It is written as YYYY-MM-dd-HH-mm-ss.SSS with an extension of .mid for the MIDI files and .wav for the audio files.

  - YYYY stands for Year (including century),

  - MM stands for Month (01..12),

  - dd stands for Day (01..31),

  - HH stands for Hours (00..24),

  - mm stands for Minutes (00..59),

  - ss stands for Seconds (00..59),

  - SSS stands for Milliseconds (000..999).

GrandOrgue stores MIDI data using a specific internal format that makes the file unsuitable for usage with a regular MIDI sequencer.

When a recorded MIDI file is played in another sample set than the sample set used for recording, all recorded stop changes are silently ignored, thus preventing unexpected rendition.

## Frequently Asked Questions

This section will be populated once questions become frequently asked.

## The GrandOrgue file format

### General information

It is a text file in ISO-8859-1 encoding. The standard extension is .organ. As an alternative, the file might be encoded in UTF-8, if it starts with an appropriate byte order marker.

Comments are any text from ; to the end of line. Empty lines or lines containing only comments are ignored. Thus it's not possible to include ; in any string

Various settings are grouped in blocks. Each block is started with a line starting with [, followed by the section name and ended with ]. Each block consists of list of name-values pairs separated by =. Each setting may only occur once. The content is case sensitive. No other elements are allowed in the file.

File paths in this format are relative to the location of the organ file. The directory separator in these paths may be \ or /. The paths should be considered case sensitive, even if this is not enforced on all platforms.

Hauptwerk only supports \ as a directory separator. So use / only if you do not intend the ODF to be HW1-compatible.

Boolean values are represented as Y for "true" and N for "false".

A color can be one of the following colors (not case sensitive): BLACK, BLUE, DARK BLUE, GREEN, DARK GREEN, CYAN, DARK CYAN, RED, DARK RED, MAGENTA, DARK MAGENTA, YELLOW, DARK YELLOW, LIGHT GREY, DARK GREY, WHITE, BROWN. Additionally, the HTML syntax #RRGGBB is supported.

A font size can be one of the following values: SMALL, NORMAL, LARGE or an integer number between 1 and 50.

A panel size can be one of the following values: SMALL, MEDIUM, MEDIUM LARGE, LARGE or an integer number between 100 and 32000.

The following image formats are supported: bmp, gif, jpg, ico, png

A bitmap number is a value between 1 and 64. It refers to a predefined (wood) background. An odd number and the following even number represent the same type of wood. The odd number has vertical grain, while the odd has horizontal grain.

Floating point numbers use the following format: -?[0-9]+(.[0-9]*)? That means: a optional minus sign, followed by at least one digit. The decimal separator is a period.

The unit "samples" counts the number of samples from the start of the WAV file. On sample includes the values of all channels, eg: for a stereo WAV file at 48 kHz, 1 second is equivalent to 48000 samples.

#### background bitmaps 1 to 30

#### background bitmaps 31 to 64

Objects in GrandOrgue are e.g. Manuals, Stops, Generals, ... . Each object can consist of a backend part representing the object, and its configuration (eg. list of sample file names) and multiple GUI representations.

The main section is called Organ. It defines the main panel. Objects like stops only displayed on a non-main panel need an invisible definition for the backend part on the main panel too.

### Sample format

The samples are stored as WAV files according to the WAV file specification. The supported formats are: 8 bit, 16 bit and 24 bit PCM or 32 bit IEEE float, either mono or stereo. The preferred sample rates are 44100 or 48000 Hz - GO supports any sample rate between 22000 and 192000 Hz. GO only supports a single data chunk. To play looped samples, they must include cue points (cue chunk) and loops (smpl chunk). If there are multiple loops, each loop should overlap another loop. Attack samples include the attack phase and the loops - they may contain a release too. If release samples include a cue point, the release is loaded starting with this position, else the whole file is loaded. dwMIDIUnityNote and dwMIDIPitchFraction of the smpl chunk are used for retuning an organ to other temperaments.

If multiple sample files are specified for one pipe, they must match each other in regards to pitch, amplitude and other things. GrandOrgue only allows adjustments at pipe level.

The samples in the format above may also be packed with WavPack http://www.wavpack.com/. GO supports both the WavPack 4 and WavPack 5 formats, without hybrid compression and it must include all metadata. A good starting point for the WavPack compression options is -x6

### Shortcut keys

The following key codes for shortcut keys are supported by GO:

8

- Backspace key

48

- 0 key

49

- 1 key

50

- 2 key

51

- 3 key

52

- 4 key

53

- 5 key

54

- 5 key

55

- 6 key

56

- 8 key

57

- 9 key

65

- A key

66

- B key

67

- C key

68

- D key

69

- E key

70

- F key

71

- G key

72

- H key

73

- I key

74

- J key

75

- K key

76

- L key

77

- M key

78

- N key

79

- O key

80

- P key

81

- Q key

82

- R key

83

- S key

84

- T key

85

- U key

86

- V key

87

- W key

88

- X key

89

- Y key

90

- Z key

112

- F1 key

113

- F2 key

114

- F3 key

115

- F4 key

116

- F5 key

117

- F6 key

118

- F7 key

119

- F8 key

120

- F9 key

121

- F10 key

122

- F11 key

123

- F12 key

### Organ section

This section describes the whole organ. For the old panel format, it includes the main panel, therefore the section includes all display metrics attributes. The new panel format separates the display metrics of the main panel into a section named Panel000. Additionally it includes the following attributes:

ChurchName

- (string, required) Name of the organ/church. This string should be unique, as setting files for organs with the same ChurchName are considered compatible. GrandOrgue will not load a settings file if the ChurchName does not match.

ChurchAddress

- (string, required) informational text displayed in the property dialog

OrganBuilder

- (string, required) informational text displayed in the property dialog

OrganBuildDate

- (string, required) informational text displayed in the property dialog

OrganComments

- (string, required) informational text displayed in the property dialog

RecordingDetails

- (string, required) informational text displayed in the property dialog

InfoFilename

- (string, not required) relative path to an html file with more information about the organ. This setting is currently not supported for organ packages.

NumberOfManuals

- (integer 1 - 16, required) number of manuals. It does not include the pedal keyboard. The manual information for each manual is available in sections called Manual999. 999 is a number defining each manual, starting with 001.

HasPedals

- (boolean, required) Determines if the pedal, which is defined as section Manual000, is present.

NumberOfEnclosures

- (integer 0 - 999 required) number of enclosures. The details of each enclosure are contained in a section called Enclosure999

NumberOfTremulants

- (integer 0 - 999, required) number of tremulants. The details of each tremulant are contained in a section called Tremulant999

NumberOfWindchestGroups

- (integer 1 - 999, required) number of windchests. The details of each windchest are in a section called WindchestGroup999.

NumberOfReversiblePistons

- (integer 0 - 32, required) number of reversible pistons. The details of each reversible piston are in a section called ReversiblePiston999.

NumberOfGenerals

- (integer 0 - 99, required) number of generals. The details are in a section called General999.

NumberOfDivisionalCouplers

- (integer 0 - 8, required) number of divisional couplers. The details are in a section called DivisionalCoupler999.

NumberOfPanels

- (integer 0 - 100, default: 0) number of additional panels. The details are in a section called Panel999.

NumberOfSwitches

- (integer 0 - 999, default: 0) number of switches. The details are in a section called Switch999.

NumberOfRanks

- (integer 0 - 999, default: 0) number of additional ranks. The details are in a section called Rank999.

DivisionalsStoreIntermanualCouplers

- (boolean, required) determines if divisionals store/change the state of associated intermanual couplers.

DivisionalsStoreIntramanualCouplers

- (boolean, required) determines if divisionals store/change the state of associated intramanual couplers.

DivisionalsStoreTremulants

- (boolean, required) determines if divisionals store/change the state of associated tremulants.

GeneralsStoreDivisionalCouplers

- (boolean, required) determines if divisionals store/change the state of divisional couplers.

CombinationsStoreNonDisplayedDrawstops

- (boolean, default: false) determines, if the state of read-only objects (that is calculated based on the state of another objects) is stored in divisionals, generals and the setter.

NumberOfImages

- (integer 0 - 999, default: 0) Number of images on the panel. The section of the image GUI definitions are called Image999. This setting is not supported for the new panel format.

NumberOfSetterElements

- (integer 0 - 999, default: 0) Number of setter elements on the panel. The section of the GUI definitions are called SetterElement999. This setting is not supported for the new panel format.

NumberOfLabels

- (integer 0 - 999, required) Number of labels on the panel. The section for each label GUI definition is called Label999. This setting is not supported for the new panel format.

AmplitudeLevel

- (float 0 - 1000, default: 100) Linear amplitude scale factor applied to the whole organ. 100 means no change.

Gain

- (float -120 - 40, default: 0) Amplitude scale factor in dB applied to the whole organ. 0 means no change.

PitchTuning

- (float -1800 - 1800, default: 0) Retune the whole organ the specified number of cents.

PitchCorrection

- (float -1800 - 1800, default: 0) Correction factor in cent for the pitch of the whole organ. This setting is used for retuning to other temperaments.

TrackerDelay

- (integer 0 - 10000, default: 0) Delay introduced by the tracker applied to the whole organ.

Percussive

- (boolean, default false) If true, the samples are played as is (without any loop/release handling).

HasIndependentRelease

- (boolean, default false). If true, releases are played independently of the attacks.

  If HasIndependentRelease is true then Percussive must also be set to true.

### Setter elements

It is possible to display various setter elements on the panels. The Type attribute describes the function - the other attributes depend on the function:

Swell

- Represents the crescendo swell. The section must contain the GUI attributes of an enclosure, eg the images for each position of the swell pedal, etc.

CrescendoLabel

- Represents a label with crescendo state (ie the current step that the crescendo pedal is at, from 1 to 32.) The section must contain the GUI attributes of a label.

SetterXXXDivisionalYYY

- Represents a divisional button YYY (000 means 1, 001 - 2 etc) for the manual XXX (000 - Pedal, 001 - the first manual, etc). The section must contain the GUI attributes of a button (displayed as piston per default).

SetterXXXDivisionalPrevBank, SetterXXXDivisionalNextBank

- Represents a button switching the current bank of divisionals for the manual XXX (000 - Pedal, 001 - the first manual, etc). The section must contain the GUI attributes of a button (displayed as piston per default).

SetterXXXDivisionalBank

- Represents a label showing the current bank of divisionals for the manual XXX (000 - Pedal, 001 - the first manual, etc). The section must contain the GUI attributes of a label.

Label

- Represents the current number of the setter. The section must contain the GUI attributes of a label - only available for old format panels.

SequencerLabel

- Represents the current number of the setter. The section must contain the GUI attributes of a label.

CurrFileName

- Represents the current combinations file name of the setter. The section must contain the GUI attributes of a label.

RefreshFiles, PrevFile, NextFile, LoadFile, SaveFile

- Refresh files/Prev file/Next file/Load file/Save file buttons of the setter. The section must contain the GUI attributes of a button (displayed as drawstop per default).

Prev, Next, Set

- Prev/next/set button of the setter. The section must contain the GUI attributes of a button (displayed as drawstop per default).

M100, M10, M1, P1, P10, P100

- +/- 1/10/100 button of the setter. The section must contain the GUI attributes of a button (displayed as drawstop per default).

Home

- Move to 000 button of the setter. The section must contain the GUI attributes of a button (displayed as drawstop per default).

Current

- Recall current number button of the setter. The section must contain the GUI attributes of a button (displayed as drawstop per default).

GC

- General cancel button of the setter. The section must contain the GUI attributes of a button (displayed as drawstop per default).

L0, L1, L2, L3, L4, L5, L6, L7, L8, L9

- Recall combination with the specified digit as last digit button of the setter. The section must contain the GUI attributes of a button (displayed as drawstop per default).

SetterN

- Activate or deactivate the numeric setter mode as described on the Combination Setter chapter. The section must contain the GUI attributes of a button (displayed as drawstop per default).

Regular, Scope, Scoped

- Button to switch between the various setter modes. The section must contain the GUI attributes of a button (displayed as drawstop per default).

Full

- Button to enable storing all elements in the setter (restrictions from the ODF are ignored). The section must contain the GUI attributes of a button (displayed as drawstop per default).

Insert, Delete

- Buttons to insert/remove a combination. The section must contain the GUI attributes of a button (displayed as drawstop per default).

General01 - General50

- Buttons for the setter generals. The section must contain the GUI attributes of a button (displayed as piston per default).

GeneralPrev, GeneralNext

- Buttons for switching banks of the setter generals. The section must contain the GUI attributes of a button (displayed as drawstop per default).

GeneralLabel

- Represents a label with the general bank number. The section must contain the GUI attributes of a label.

CescendoA, CrescendoB, CrescendoC, CrescendoD

- Buttons to switch between the various crescendo modes. The section must contain the GUI attributes of a button (displayed as drawstop per default).

CrescendoPrev, CrescendoNext, CrescendoCurrent

- Buttons for controlling the crescendo combinations. The section must contain the GUI attributes of a button (displayed as drawstop per default).

PitchP1, PitchP10, PitchP100, PitchM1, PitchM10, PitchM100

- Buttons for controlling the organ pitch (+1, +10, +100, -1, -10, -100 cent).

PitchLabel

- Label displaying the current pitch shift of the organ.

TemperamentPrev, TemperamentNext

- Buttons for switching temperaments.

TemperamentLabel

- Label displaying the current temperament of the organ.

TransposeDown, TransposeUp

- Buttons for transposing.

TransposeLabel

- Label displaying the current transpose setting.

Save

- Save button.

### Display metrics

The layout of any panel is described by a layout model. The available space is split vertically into three columns: The left and the right column contain drawstops laid out via a mesh. The middle row is vertically divided:

At the bottom, the pedal and its buttons are placed (if present). Above, an extra row of buttons may follow. The next row contains the enclosures. Then all manuals with their associated buttons follow. The two rows are a block of buttons and pistons. The exact order can be specified via an attribute.

#### background regions

Has the following attributes:

DispScreenSizeHoriz

- (panel size, required) Width of the panel.

DispScreenSizeVert

- (panel size, required) Height of the panel.

DispDrawstopBackgroundImageNum

- (bitmap number, required) shown as 01 in the above image.

DispConsoleBackgroundImageNum

- (bitmap number, required) shown as 05 in the above image.

DispKeyHorizBackgroundImageNum

- (bitmap number, required) shown as 13 in the above image

DispKeyVertBackgroundImageNum

- (bitmap number, required) shown as 20 in the above image

DispDrawstopInsetBackgroundImageNum

- (bitmap number, required)

DispControlLabelFont

- (string, required) Name of the font for button labels.

DispShortcutKeyLabelFont

- (string, required) Name of the font for shortcut labels - provided just for HW1 compatibility. DEPRECATED.

DispShortcutKeyLabelColour

- (color, required) Color for shortcut labels - provided just for HW1 compatibility. DEPRECATED.

DispGroupLabelFont

- (string, required) font name for labels

DispDrawstopCols

- (integer 2 - 12, required) number of drawstop columns. Must be even. NOTE: If you want more than 12 drawstop columns, you must use absolute positioning.

DispDrawstopRows

- (integer 1 - 20, required) Number of drawstop rows. NOTE: If you want more than 20 drawstop rows you must use absolute positioning.

DispDrawstopColsOffset

- (boolean, required) If true, each second row of drawstops on the left/right is displayed vertically shifted.

DispDrawstopOuterColOffsetUp

- (boolean, required if DispDrawstopColsOffset is true) Determines if second row is shifted up or down.

DispPairDrawstopCols

- (boolean, required) group two drawstop rows together. Number of drawstop rows must be divisible by 4.

DispExtraDrawstopRows

- (integer 0 - 99, required) number of drawstop rows in the center block. The row numbers start with 100.

DispExtraDrawstopCols

- (integer 0 - 40, required) number of drawstop cols in the center block

DispButtonCols

- (integer 1 - 32, required) Number of columns for displaying pistons in the center block

DispExtraButtonRows

- (integer 0 - 99, required) number of rows for displaying extra pistons in the center block. The row numbers start with 100.

DispExtraPedalButtonRow

- (boolean, required) display an extra piston row with row number 9.

DispExtraPedalButtonRowOffset

- (boolean, required if DispExtraPedalButtonRow is true) move extra pistons row slightly to the left.

DispExtraPedalButtonRowOffsetRight

- (boolean, required if DispExtraPedalButtonRow is true) move extra pistons row slightly to the right.

DispButtonsAboveManuals

- (boolean, required) Display the pistons associated with the manual above (true) or below (false) the manual.

DispTrimAboveManuals

- (boolean, required)

DispTrimBelowManuals

- (boolean, required)

DispTrimAboveExtraRows

- (boolean, required)

DispExtraDrawstopRowsAboveExtraButtonRows

- (boolean, required) Display extra drawstop block above or below the extra piston block.

DispDrawstopWidth

- (integer 1 - 150, default: 78) Drawstop width used for layout calculation

DispDrawstopHeight

- (integer 1 - 150, default: 69) Drawstop height used for layout calculation

DispPistonWidth

- (integer 1 - 150, default: 44) Piston width used for layout calculation

DispPistonHeight

- (integer 1 - 150, default: 40) Piston height used for layout calculation

DispEnclosureWidth

- (integer 1 - 150, default: 52) Enclosure width used for layout calculation

DispEnclosureHeight

- (integer 1 - 150, default: 63) Enclosure height used for layout calculation

DispPedalHeight

- (integer 1 - 500, default: 40) Pedal height used for layout calculation

DispPedalKeyWidth

- (integer 1 - 500, default: 7) Width of one pedal key used for layout calculation

DispManualHeight

- (integer 1 - 500, default: 32) Manual height used for layout calculation

DispManualKeyWidth

- (integer 1 - 500, default: 12) Width of one manual key used for layout calculation

### Enclosure objects

An enclosure represents a swell pedal. It consists of non-GUI attributes describing its function. If it is displayed, it contains additional GUI attributes. Best practice is to specify enclosures in natural layout order (leftmost first) and give them incremental values of MIDIInputNumber to make initial configurations easy for the user.

Name

- (string, required) Name of the control

AmpMinimumLevel

- (integer 0 - 100, required) Minimum volume, if the enclosure is closed.

MIDIInputNumber

- (integer 0 - 200, default: 0) This number is used while building the initial MIDI configuration to map the enclosure object to one MIDI device the user can specify for the respective enclosure. A value of 0 means no association, 1 means enclosure 1, 2 is enclosure 2 etc. Please note, that the GUI only allows the association of the first few enclosures.

Displayed

- (boolean, default: false for the new panel format, otherwise true) If true, the enclosure is visible on the main panel.

If the enclosure is displayed, it contains the following GUI attributes:

DispLabelColour

- (color, default: White) Color for the label text.

DispLabelFontSize

- (font size, default: 7) Size of the label font

DispLabelFontName

- (string, default: empty) Font for the text. Empty means use the default font.

DispLabelText

- (string, default: Name of the enclosure) Content of the text label. You should edit it if you need to display a shorter string.

EnclosureStyle

- (integer 1 - 4, default: implementation dependent) Select a built-in enclosure style.

BitmapCount

- (integer 1 - 127, default: implementation dependent) Number of bitmaps/steps.

Bitmap999

- (string, default: use internal bitmap) Specify the file name of an image to use as on bitmap for position 999. If the bitmap contains a mask for transparency, it will be used. All bitmaps must have the same size.

Mask999

- (string, default: empty) File name for a external mask for bitmap 999. If empty, no mask is added.

PositionX

- (integer 0 - panel width, default: according to layout model) Allow to override X position for enclosure.

PositionY

- (integer 0 - panel height, default: according to layout model) Allow to override Y position for enclosure.

Width

- (integer 0 - panel width, default: bitmap width) Width of the enclosure. If larger than the bitmap, the bitmap is tiled.

Height

- (integer 0 - panel height, default: bitmap height) Height of the enclosure. If larger than the bitmap, the bitmap is tiled.

TileOffsetX

- (integer 0 - bitmap width, default: 0) X position on the bitmap of the left pixel of the enclosure

TileOffsetY

- (integer 0 - bitmap width, default: 0) Y position on the bitmap of the top pixel of the enclosure

MouseRectLeft

- (integer 0 - Width, default: 0) relative X of left border of the mouse rectangle

MouseRectTop

- (integer 0 - Height, default: implementation dependent) relative Y of top border of the mouse rectangle

MouseRectWidth

- (integer 0 - Width, default: Width) width of the mouse rectangle

MouseRectHeight

- (integer 0 - Height, default: implementation dependent) height of the mouse rectangle

MouseAxisStart

- (integer 0 - MouseRectHeight, default: implementation dependent) top Y coordinate of the axis

MouseAxisEnd

- (integer MouseAxisStart - MouseRectHeight, default: implementation dependent) bottom Y coordinate of the axis

TextRectLeft

- (integer 0 - Width, default: 0) relative X of left border of the text rectangle

TextRectTop

- (integer 0 - Height, default: implementation dependent) relative Y of top border of the text rectangle

TextRectWidth

- (integer 0 - Width, default: Width) width of the text rectangle

TextRectHeight

- (integer 0 - Height, default: implementation dependent) height of the text rectangle

TextBreakWidth

- (integer 0 - text rectangle width, default: TextWidth) If 0, no text is displayed. Otherwise the value specifies the maximum line width used for text breaking.

### Combination data store

This object is used to store one combination It has the following attributes:

Protected

- (boolean, default: false) If true, the stored combination cannot be changed.

NumberOfStops

- (integer 0 - number of stops defined in the ODF, required) Number of stop states stored in this combination. The entries are called StopNumber999 and StopManual999.

NumberOfCouplers

- (integer 0 - number of coupler defined in the ODF, required) Number of coupler states stored in this combination. The entries are called CouplerNumber999 and CouplerManual999.

NumberOfTremulants

- (integer 0 - tremulant count, required) Number of tremulant states stored in this combination. The entries are called TremulantNumber999.

NumberOfSwitches

- (integer 0 - switch count, default: 0) Number of switch states stored in this combination. The entries are called SwitchNumber999.

NumberOfDivisionalCouplers

- (integer 0 - divisional coupler count, required if storing of divisional coupler in the generals is enabled) Number of divisional coupler state stored in this combination. The entries are called DivisionalCouplerNumber999.

StopNumber999

- (integer -manual stop count - manual stop count, required) Number of the stop on the manual. If the value is negative, it is turned off, else turned on.

StopManual999

- (integer manual number, required) Number of the manual, which contains the stop.

CouplerNumber999

- (integer -999 - 999, required) Number of the coupler on the manual. If the value is negative, it is turned off, else it is turned on.

CouplerManual999

- (integer manual number, required) Number of the manual, which contains the coupler.

TremulantNumber999

- (integer -tremulant count - tremulant count, required) Number of the tremulant. If the value is negative, it is turned off, else turned on.

SwitchNumber999

- (integer -switch count - switch count, required) Number of the switch. If the value is negative, it is turned off, else it is turned on.

DivisionalCouplerNumber999

- (integer -divisional coupler count -divisional coupler count, required) Number of the divisional coupler. If the value is negative, it is turned off, else it is turned on.

### General object

A general object consists of a push button and a combination data store.

### Divisional coupler objects

A divisional coupler is a drawstop object. If enabled, activating a divisional on one controlled manual will activate the corresponding divisional on all other manuals. Additionally, it has the following attributes:

BiDirectionalCoupling

- (boolean, required) If false, the coupler only couples upward in the manual list of the coupler, else upward and downward.

NumberOfManuals

- (integer 1 - manual count, required) Number of manuals affected by this coupler. The list entries are stored in Manual999 setting.

Manual999

- (integer manual number, required) Manual affected by the coupler

### Divisional objects

A divisional is a pushbutton object. Additionally, it has the following attributes:

Protected

- (boolean, default: false) If true, the stored combination cannot be changed.

NumberOfStops

- (integer 0 - stop count of the manual, required) Number of stop states stored in this combination. The entries are called Stop999.

NumberOfCouplers

- (integer 0 - coupler count of the manual, required) Number of coupler states stored in this combination. The entries are called Coupler999.

NumberOfTremulants

- (integer 0 - tremulant count of the manual, required) Number of tremulant states stored in this combination. The entries are called Tremulant999.

NumberOfSwitches

- (integer 0 - switch count of the manual, default: 0) Number of switch states stored in this combination. The entries are called Switch999.

Stop999

- (integer -manual stop count - manual stop count, required) Number of the stop. If the value is negative, it is turned off, else turned on.

Coupler999

- (integer -999 - 999, required) Number of the coupler. If the value is negative, it is turned off, else turned on.

Tremulant999

- (integer -manual tremulant count - manual tremulant count, required) Number of the tremulant. If the value is negative, it is turned off, else it is turned on.

Switch999

- (integer -manual switch count - manual switch count, required) Number of the switch. If the value is negative, it is turned off, else it is turned on.

### Manual objects

A manual is associated with a number of stops, tremulants, divisionals and couplers. The accessible range can be played via MIDI, the rest of the logical keys can only be triggered by (octave) couplers. Best practice is to specify the visible manuals in the order of appearance, lowest first. Invisible manuals and those used for special effects should be specified after the visible ones. Manual objects contain the following non-GUI attributes:

Name

- (string, required) Name of the manual

NumberOfLogicalKeys

- (integer 1 - 192, required) Number of keys on this manual (including non-playable ones).

FirstAccessibleKeyLogicalKeyNumber

- (integer 1 - NumberOfLogicalKeys, required) number of the first usable key

FirstAccessibleKeyMIDINoteNumber

- (integer 0 - 127, required) MIDI note number of the first MIDI accessible key.

NumberOfAccessibleKeys

- (integer 0 - 85, required) number of MIDI accessible keys.

MIDIInputNumber

- (integer 0 - 200, default: 0) This number is used while building the initial MIDI configuration to map the manual object to what MIDI device the the user has set for the respective pedal/manual. 0 means no association. 1 maps to pedal, 2 to first manual, 3 to second manual etc. NOTE: the GUI only allows the association of the first few manuals. Second touch manuals can be set to the same number as the main manual as the user then only has to configure the low velocity to make it work.

Displayed

- (boolean, default: false) If true, the manual is visible on the main panel.

NumberOfStops

- (integer 0 - 999, required) Number of stops associated with this manual. Starting with 1, for each stop, there is a Stop999 setting.

Stop999

- (integer, required) Number of the Stop999 section containing the stop details.

NumberOfCouplers

- (integer 0 - 999, default: 0) Number of couplers associated with this manual. Starting with 1, for each coupler, there is a Coupler999 setting.

Coupler999

- (integer, required) Number of the Coupler999 section containing the coupler details.

NumberOfDivisionals

- (integer 0 - 999, default: 0) Number of divisionals associated with this manual. Starting with 1, for each divisional, there is a Divisional999 setting.

Divisional999

- (integer, required) Number of the Divisional999 section containing the coupler details.

NumberOfTremulants

- (integer 0 - number of tremulants, default: 0) Number of tremulants associated with this manual. Starting with 1, for each tremulant, there is a Tremulant999 setting.

Tremulant999

- (integer, required) Number of the Tremulant999 section containing the tremulant details.

NumberOfSwitches

- (integer 0 - number of switches, default: 0) Number of switches associated with this manual. Starting with 1, for each switch, there is a Switch999 setting.

Switch999

- (integer, required) Number of the Switch999 section containing the switch details.

MIDIKey000 - MIDIKey127

- (integer 0 - 127, default: same MIDI key number) Allows to map the MIDI note in MIDIKey999 to a different number. This mapping is used by the default manual MIDI matching type - others may or may not use this mapping table.

The various GUI manual attributes are specified for the different key types. They are named: C, Cis, D, Dis, E, F, Fis, G, Gis, A, Ais, B. If it is the first key on the manual, it is prefixed with First. If it is the last key on the manual, it is prefixed with Last. So valid values are eg. Gis, FirstDis, LastAis. In the following, these values will be marked as KEYTYPE.

If the manual is displayed, it contains the following GUI attributes:

PositionX

- (integer 0 - panel width, default: according to layout model) Allow to override X position for manual.

PositionY

- (integer 0 - panel height, default: according to layout model) Allow to override Y position for manual.

ImageOn_KEYTYPE

- (string, default: implementation dependent bitmap) Bitmap for the specified key type, if the key is pressed. The bitmap may contain a mask.

ImageOff_KEYTYPE

- (string, default: implementation dependent bitmap) Bitmap for the specified key type, if the key is not pressed. The bitmap may contain a mask.

MaskOn_KEYTYPE

- (string, default: empty string) Mask for the corresponding On bitmap. If empty, no external mask is loaded.

MaskOff_KEYTYPE

- (string, default: corresponding on mask) Mask for the corresponding Off bitmap. If empty, no external mask is loaded.

Width_KEYTYPE

- (integer 0 - 500, default: implementation dependent) This value is added to the x position of the current key to determine the position of the next key.

Offset_KEYTYPE

- (integer -500 - 500, default: implementation dependent) This value can be used to adjust the display of the current key, eg. to place a sharp key overlapped with the previous key.

YOffset_KEYTYPE

- (integer -500 - 500, default: 0) This value is can be used to adjust the Y coordinate of the current key.

Key999ImageOn

- (string, default: corresponding ImageOn_KEYTYPE) Allows to set the on bitmap for the 999 key.

Key999ImageOff

- (string, default: corresponding ImageOff_KEYTYPE) Allows to set the off bitmap for the 999 key.

Key999MaskOn

- (string, default: corresponding MaskOn_KEYTYPE) Allows to set the on mask for the 999 key.

Key999MaskOff

- (string, default: corresponding MaskOff_KEYTYPE) Allows to set the off mask for the 999 key.

Key999Width

- (integer 0 - 500, default: corresponding Width_KEYTYPE) Allows to set the width of the 999 key.

Key999Offset

- (integer -500 - 500, default: corresponding Offset_KEYTYPE) This value is can be used to adjust the display of the 999 key, eg. to place a sharp key overlapped with the previous 999 key.

Key999YOffset

- (integer -500 - 500, default: corresponding YOffset_KEYTYPE) This value is can be used to adjust the Y coordinate of the 999 key.

Key999MouseRectLeft

- (integer 0 - key bitmap width - 1 , default: 0) relative X of left border of the mouse rectangle

Key999MouseRectTop

- (integer 0 - key bitmap height - 1, default: 0) relative Y of top border of the mouse rectangle

Key999MouseRectWidth

- (integer 0 - key bitmap width, default: key bitmap width) width of the mouse rectangle

Key999MouseRectHeight

- (integer 0 - key bitmap height, default: key bitmap height) height of the mouse rectangle

DispKeyColourInverted

- (boolean, default: false) True means, the black keys are drawn in a light color while the white keys are drawn in a dark color.

DispKeyColourWooden

- (boolean, default: false) True means, that a wood background is used for the keys.

DispImageNum

- (integer 1 - 2, default: 1) determines which set of builtin bitmaps is used for displaying the keys.

DisplayFirstNote

- (integer 0 - 127, default: FirstAccessibleKeyMIDINoteNumber) Display the first key as the following note.

DisplayKeys

- (integer 1 - NumberOfAccessibleKeys, default: NumberOfAccessibleKeys) number of keys to display.

DisplayKey999

- (integer 0 - 127, default: FirstAccessibleKeyMIDINoteNumber + 999) The number in the key (999) is between 1 and DisplayKeys. It contains the MIDI number of the backend key, that is connected to this GUI key.

DisplayKey999Note

- (integer 0 - 127, default: FirstAccessibleKeyMIDINoteNumber + 999) The number in the key (999) is between 1 and DisplayKeys. It contains the MIDI number of the displayed frontend GUI key.

### Label objects

Label object allows to display a text label. The background is an image. It is tiled, if the image is smaller than the label area. A label has the following attributes:

FreeXPlacement

- (boolean, default: true) True means that the X position is determined by DispXpos, else by DispDrawstopCol and DispSpanDrawstopColToRight.

FreeYPlacement

- (boolean, default: true) True means that the Y position is determined by DispYpos, else by DispAtTopOfDrawstopCol.

DispXpos

- (integer 0 - panel width, default: 0) absolute X position

DispYpos

- (integer 0 - panel height, default: 0) absolute Y position

DispAtTopOfDrawstopCol

- (boolean, required if FreeYPlacement is false) If true, the label is displayed above the drawstop, else below.

DispDrawstopCol

- (integer 1 - number of drawstop columns, required if FreeXPlacement is false) Position label at the specified drawstop column.

DispSpanDrawstopColToRight

- (boolean, required if FreeXPlacement is false) If true, move label half of the drawstop to the right.

DispLabelColour

- (color, default: Black) Color for the label text.

DispLabelFontSize

- (font size, default: normal) Size of the label font

DispLabelFontName

- (string, default: empty) Font for the text. Empty means use the group label font of the panel.

Name

- (string, default: empty) The text to display on this object

DispImageNum

- (integer 0 - 15, default: 1) Builtin bitmap set to use. 0 means that the label does not have a background image.

Image

- (string, default: use internal bitmap according to DispImageNum) Specify the file name of an image to use as bitmap. If the bitmap contains a mask for transparency, it will be used.

Mask

- (string, default: empty) File name for a external mask for the bitmap. If empty, no mask is added.

PositionX

- (integer 0 - panel width, default: according to the definitions above) Allow to override X position for label

PositionY

- (integer 0 - panel height, default: according to definitions above) Allow to override Y position for label

Width

- (integer 0 - panel width, default: bitmap width) Width of the label. If larger than the bitmap, the bitmap is tiled.

Height

- (integer 0 - panel height, default: bitmap height) Height of the label. If larger than the bitmap, the bitmap is tiled.

TileOffsetX

- (integer 0 - bitmap width, default: 0) X position on the bitmap of the left pixel of the label

TileOffsetY

- (integer 0 - bitmap width, default: 0) Y position on the bitmap of the top pixel of the label

TextRectLeft

- (integer 0 - Width, default: 0) relative X of left border of the text rectangle

TextRectTop

- (integer 0 - Height, default: 0) relative Y of top border of the text rectangle

TextRectWidth

- (integer 0 - Width, default: Width) width of the text rectangle

TextRectHeight

- (integer 0 - Height, default: Height) height of the text rectangle

TextBreakWidth

- (integer 0 - text rectangle width, default: TextWidth) If 0, no text is displayed. Otherwise the value specifies the maximum line width used for text breaking.

### Image objects

Image objects allow to display an image on a panel. They tile the images, if it is bigger then image size. It has the following attributes:

Image

- (string, required) Specifies the file name of an image to use as a bitmap. If the bitmap contains a mask for transparency, it will be used.

Mask

- (string, default: empty) File name for a external mask for the bitmap. If empty, no mask is added.

PositionX

- (integer 0 - panel width, default: 0) X coordinate of the left side. to override X position for button

PositionY

- (integer 0 - panel height, default: 0) Y coordinate of the left side.

Width

- (integer 0 - panel width, default: bitmap width) Width of the button. If larger than the bitmap, the bitmap is tiled.

Height

- (integer 0 - panel height, default: bitmap height) Height of the button. If larger than the bitmap, the bitmap is tiled.

TileOffsetX

- (integer 0 - bitmap width, default: 0) X position on the bitmap of the left pixel of the image

TileOffsetY

- (integer 0 - bitmap height, default: 0) Y position on the bitmap of the top pixel of the image

### Button objects

Button objects are defined on the main panel. Their section name is based on their function. They share the following common properties:

Name

- (string, required) Name of the object. The name may be presented to the user in lists too, therefore it should be descriptive. If a GUI representation requires a shorter name, please override this value locally.

Displayed

- (boolean, default: false) If true, the section also includes the GUI properties for the main panel. Otherwise it is not displayed on the main panel.

DisplayInInvertedState

- (boolean, default: false) If true, off is displayed as on and on as off.

StopControlMIDIKeyNumber

- (integer 0 - 127, default: no MIDI event specified) Only used for building the initial configuration during the first load - provided just for HW1 compatibility. DEPRECATED.

MIDIProgramChangeNumber

- (integer 1 - 128, default: no MIDI event specified) Only used for building the initial configuration during the first load - provided just for HW1 compatibility. DEPRECATED.

ShortcutKey

- (integer 0 - 255, default: 0) 0 means no shortcut, else it specifies the key code of the shortcut key.

The GUI properties of button objects are:

DisplayAsPiston

- (boolean, default: true for divisionals, generals and pistons, else false) True means to display as piston, false as drawstop

DispLabelColour

- (color, default: Dark Red) Color for the label text.

DispLabelFontSize

- (font size, default: normal) Size of the label font

DispLabelFontName

- (string, default: empty) Font for the text. Empty means use the control label font of the panel.

DispLabelText

- (string, default: Name of the button) Content of the text label. You should edit it, if you need to display a shorter string on the label.

DispKeyLabelOnLeft

- (boolean, default: true) If displayed as a piston and this attribute is false, move it a little bit left. Otherwise ignored.

DispImageNum

- (integer 1 - type dependent, default: see below) Builtin bitmap set to use. GrandOrgue has 7 for drawstops and 5 for pistons. The default is 3 (piston) or 4 (drawstops) for read-only buttons, otherwise the default is 1.

DispButtonRow

- (button row, default: 1) If displayed as piston, it contains the button row according to the layout model. Otherwise ignored.

DispButtonCol

- (button column, default: 1) If displayed as piston, it contains the button column according to the layout model. Otherwise ignored.

DispDrawstopRow

- (drawstop row, default: 1) If displayed as drawstop, it contains the drawstop row according to the layout model. Otherwise ignored.

DispDrawstopCol

- (drawstop column, default: 1) If displayed as drawstop, it contains the drawstop column according to the layout model. Otherwise ignored.

ImageOn

- (string, default: use internal bitmap according to DispImageNum) Specify the file name of an image to use as on bitmap. If the bitmap contains a mask for transparency, it will be used.

ImageOff

- (string, default: use internal bitmap according to DispImageNum) Specify the file name of an image to use as off bitmap. If the bitmap contains a mask for transparency, it will be used. The size must match the on bitmap.

MaskOn

- (string, default: empty) File name for a external mask for the on bitmap. If empty, no mask is added.

MaskOff

- (string, default: value of MaskOn) File name for a external mask for the off bitmap. If empty, no mask is added.

PositionX

- (integer 0 - panel width, default: according to layout model) Allow to override X position for button

PositionY

- (integer 0 - panel height, default: according to layout model) Allow to override Y position for button

Width

- (integer 0 - panel width, default: bitmap width) Width of the button. If larger than the bitmap, the bitmap is tiled.

Height

- (integer 0 - panel height, default: bitmap height) Height of the button. If larger than the bitmap, the bitmap is tiled.

TileOffsetX

- (integer 0 - bitmap width, default: 0) X position on the bitmap of the left pixel of the button

TileOffsetY

- (integer 0 - bitmap width, default: 0) Y position on the bitmap of the top pixel of the button

MouseRectLeft

- (integer 0 - Width, default: 0) relative X of left border of the mouse rectangle

MouseRectTop

- (integer 0 - Height, default: 0) relative Y of top border of the mouse rectangle

MouseRectWidth

- (integer 0 - Width, default: Width) width of the mouse rectangle

MouseRectHeight

- (integer 0 - Height, default: Height) height of the mouse rectangle

MouseRadius

- (integer 0 - max(MouseRectHeight, MouseRectWidth), default: min(MouseRectHeight, MouseRectWidth) / 2) If 0, the mouse events are captured inside the mouse rectangle. Otherwise they must be inside a circle of the specified size too.

TextRectLeft

- (integer 0 - Height, default: 1) relative X of left border of the text rectangle

TextRectTop

- (integer 0 - Height, default: 1) relative Y of top border of the text rectangle

TextRectWidth

- (integer 0 - Width, default: Width) width of the text rectangle

TextRectHeight

- (integer 0 - Height, default: Height) height of the text rectangle

TextBreakWidth

- (integer 0 - text rectangle width, default: slightly smaller than TextWidth) If 0, no text is displayed. Otherwise the value specifies the maximum line width used for text breaking.

Inside the button, the on/off bitmap (depending on the button state) is tiled. If a text width is set, a text label is displayed on it. Mouse events are only captured inside the mouse rectangle.

### Drawstop objects

Drawstop objects are buttons with toggle functions. They contain these additional non-GUI properties:

Function

- (enumeration, default: Input) Logical function of the drawstop. If the value is Input, it is a normal user controllable drawstop and has no input switches. Not has one only input and negates the state of the input switch. And, Xor, Nand, Nor as well as Or has a variable number of inputs.

SwitchCount

- (integer 1 - switch count, required if the logical function allows a variable number number of inputs) Contains the number of input ports. Switch999 contains the referenced switches.

Switch999

- (integer 1 - switch count, required) Lists the input switches of the logical function of the drawstop. If the drawstop is a switch, it can only reference switches with a lower number. The number of this settings depends on the function.

DefaultToEngaged

- (boolean, required if Function is Input or not defined, else ignored) State of the button after loading.

GCState

- (integer -1 - 1, default: implementation defined) State of the button after pressing GC. -1 means no change, 0 off and 1 on.

StoreInDivisional

- (boolean, default: dependent on various settings) Determines, if the button should be stored in divisionals without FULL.

StoreInGeneral

- (boolean, default: dependent on various settings) Determines, if the button should be stored in generals without FULL.

### Coupler objects

Couplers are drawstop objects. They forward key presses from one manual to other manuals/keys. They have the following additional attributes:

UnisonOff

- (boolean, required) If true, this coupler decouples the manual from the stops (turn it into a floating manual).

DestinationManual

- (integer manual number, required if not a unison off coupler) manual to forward key presses to.

DestinationKeyshift

- (integer -24 - 24, required if not a unison off coupler) specifies the keyboard shift between source and destination manual in terms of absolute MIDI note numbers

CoupleToSubsequentUnisonIntermanualCouplers

- (boolean, required if not a unison off/melody/bass coupler) Triggers further inter-manual coupler with a destination key shift of zero.

CoupleToSubsequentUpwardIntermanualCouplers

- (boolean, required if not a unison off/melody/bass coupler) Triggers further inter-manual coupler with a destination key shift greater than zero.

CoupleToSubsequentDownwardIntermanualCouplers

- (boolean, required if not a unison off/melody/bass coupler) Triggers further inter-manual coupler with a destination key shift less than zero.

CoupleToSubsequentUpwardIntramanualCouplers

- (boolean, required if not a unison off/melody/bass coupler) Triggers further intra-manual coupler with a destination key shift greater than zero.

CoupleToSubsequentDownwardIntramanualCouplers

- (boolean, required if not a unison off/melody/bass coupler) Triggers further intra-manual coupler with a destination key shift less than zero.

CouplerType

- (enumeration, default: Normal) Type of the coupler: Normal, Bass or Melody.

FirstMIDINoteNumber

- (integer 0 - 127, default: 0) first MIDI note number to forward

NumberOfKeys

- (integer 0 - 127, default: 0) number of keys to forward starting with FirstMIDINoteNumber.

### Switch objects

A switch object is a drawstop objects without any additional attributes. It can be used, for example, to trigger stop action noises and key action noises. See the Demo organ and the Kalvtrask organ for examples of its use.

### Rank objects

A rank represents a row of pipes. It can be either be part of a stop section or appear in its own section.

Name

- (string, required) Name of the rank. The name may be presented to the user in lists too, therefore it should be descriptive.

FirstMidiNoteNumber

- (integer 0 - 256, if the rank is part of a stop section, the default value is derived from the associated manuals. Otherwise required) MIDI note number of the first pipe

NumberOfLogicalPipes

- (integer 1 - 192, required) Number of pipes in this rank

AmplitudeLevel

- (float 0 - 1000, default: 100) Linear amplitude scale factor applied to the whole rank. 100 means no change.

Gain

- (float -120 - 40, default: 0) Amplitude scale factor in dB applied to the whole rank. 0 means no change.

PitchTuning

- (float -1800 - 1800, default: 0) Retune the rank by the specified number of cents.

TrackerDelay

- (integer 0 - 10000, default: 0) Delay introduced by the tracker for that rank.

HarmonicNumber

- (float 1 - 1024, default: 8) Harmonic number (= 64 / rank size), eg. 2 2/3 => 64 / (2 2/3) = 24. The harmonic number is used determining alternative tunings.

PitchCorrection

- (float -1800 - 1800, default: 0) Correction factor in cent for the pitch of the rank. This setting is used for retuning to other temperaments.

WindchestGroup

- (integer 1 - number of windchests, required) specify the windchest on which the pipes of the are placed.

Percussive

- (boolean, default inherited from the Windchest section) If true, the samples are played as is (without any loop/release handling).

HasIndependentRelease

- (boolean, default inherited from the Windchest section). If true, releases are played independently of the attacks.

  If HasIndependentRelease is true then Percussive must also be set to true.

MinVelocityVolume

- (float 0 - 1000, default: 100) Linear amplitude scale factor at low velocity applied to the whole rank. 100 means no change.

MaxVelocityVolume

- (float 0 - 1000, default: 100) Linear amplitude scale factor at high velocity applied to the whole rank. 100 means no change.

AcceptsRetuning

- (boolean, default: true) Determines if the rank will be retuned according to the current temperament. Retuning should be only disabled for sound effects.

A rank section contains the attributes of each of its pipes too. The attributes of each pipe are prefixed with Pipe999 (number starting with 1). The supported attributes are:

Pipe999

- (string, required) Relative path to the sample WAV file of the first attack. It may be listed as REF:aa:bb:cc too. In that case, it means that this pipe is borrowed from manual aa, first rank of stop bb, the pipe cc. It may contain DUMMY, which defines a non-sounding placeholder.

Pipe999Percussive

- (boolean, default: rank Percussive setting) If true, the samples are played as is (without any loop/release handling)

Pipe999HasIndependentRelease

- (boolean, default: rank HasIndependentRelease setting). If true, releases are played independently of attacks in this pipe.

  If HasIndependentRelease is true then Pipe999Percussive must be also true and Pipe999ReleaseCount must be greater than 0.

Pipe999AmplitudeLevel

- (float 0 - 1000, default: 100) Linear amplitude scale factor applied to the pipe (in addition to the organ/windchest/rank factor). 100 means no change.

Pipe999Gain

- (float -120 - 40, default: 0) Amplitude scale factor in dB applied to the pipe (in addition to the organ/windchest/rank factor). 0 means no change.

Pipe999PitchTuning

- (float -1800 - 1800, default: 0) Retune this pipe the specified number of cents (in addition to the organ/windchest/rank factor).

Pipe999TrackerDelay

- (integer 0 - 10000, default: 0) Delay introduced by the tracker for that pipe.

Pipe999LoadRelease

- (boolean, default: reverse of percussive setting) If true, the release part is loaded from the first attack sample.

Pipe999AttackVelocity

- (integer 0 - 127, default: 0) minimum velocity to use this attack sample.

Pipe999MaxTimeSinceLastRelease

- (integer -1 - 100000, default: -1) maximum time since the last release of the key to be able to use that attack. -1 means infinite.

Pipe999IsTremulant

- (integer -1 - 1, default: -1) 1 means, that it is played, if the associated wave-based tremulant is on. 0 means, that it is played, if the associated wave-based tremulant is off. -1 means, that it is not affected by a wave-based tremulant.

Pipe999MaxKeyPressTime

- (integer -1 - 100000, default: -1) Up to this time value in ms, the release sample is chosen. -1 means infinite.

Pipe999AttackStart

- (integer 0 - 158760000, default: 0) Allows to override the start of the sample. This option is specified in samples.

Pipe999CuePoint

- (integer -1 - 158760000, default: -1) Allows to override the cue point for the release. -1 means use from the wave file. This option is specified in samples.

Pipe999ReleaseEnd

- (integer -1 - 158760000, default: -1) Allows to override the end of the release. -1 means play till the end of the wav. This option is specified in samples.

Pipe999LoopCount

- (integer 0 - 100, default: 0) Allows to override the loops in the WAV file. 0 means use loops from the wave file.

Pipe999Loop999Start

- (integer 0 - 158760000, default: 0) Start sample of the loop. The value must be within the WAV file. This option is specified in samples.

Pipe999Loop999End

- (integer Pipe999Loop999Start + 1 - 158760000, required if Pipe999LoopCount is not zero) End sample of the loop. The value must be within the WAV file. This option is specified in samples.

Pipe999HarmonicNumber

- (float 1 - 1024, default: rank harmonic number) Harmonic number (= 64 / rank size), eg. 2 2/3 => 64 / (2 2/3) = 24.

Pipe999MIDIKeyNumber

- (integer -1 - 127, default: -1) If -1, use pitch information from the Pipe999 sample, else override the information in the sample with this MIDI note number (Pipe999MIDIPitchFraction is used for specifying the fraction). Specifying the MIDI note number also resets the pitch fraction in the sample to 0 unless Pipe999MIDIPitchFraction is also specified.

Pipe999MIDIPitchFraction

- (float 0 - 100, default: -1) If -1, use pitch information from the Pipe999 sample, else override the information in the sample with this value. Describes the actual existing pitch fraction in cent over the normal (440hz equal) tone of the MIDI key specified in the sample or in the Pipe999MIDIKeyNumber. This setting (together with Pipe999MIDIKeyNumber) is used when retuning to other temperaments.

Pipe999PitchCorrection

- (float -1800 - 1800, default: 0) Correction factor in cent for the pitch specified in the sample in addition to PitchCorrection of the whole organ, of the windchest and of the rank. This setting is used to adjust tuning while in other temperaments (than original). A positive value raise the pitch, a negative value lowers the pitch.

Pipe999AcceptsRetuning

- (boolean, default: rank setting) Determines if the pipe will be retuned according to the current temperament. Retuning should be only disabled for sound effects.

Pipe999WindchestGroup

- (integer 1 - number of windchests, default: rank windchest) specify the windchest, on which this pipe is placed.

Pipe999MinVelocityVolume

- (float 0 - 1000, default: corresponding rank setting) Linear amplitude scale factor at low velocity applied to the pipe. 100 means no change.

Pipe999MaxVelocityVolume

- (float 0 - 1000, default: corresponding rank setting) Linear amplitude scale factor at high velocity applied to the pipe. 100 means no change.

Pipe999AttackCount

- (integer 0 - 100, default: 0) Number of additional attack samples

Pipe999Attack999

- (string, required) Relative path to the sample WAV file.

Pipe999Attack999LoadRelease

- (boolean, default: reverse of percussive setting) If true, the release part is loaded.

Pipe999Attack999AttackVelocity

- (integer 0 - 127, default: 0) minimum velocity to use this attack sample.

Pipe999Attack999MaxTimeSinceLastRelease

- (integer -1 - 100000, default: -1) maximum time since the last release of the key to be able to use that attack. -1 means infinite.

Pipe999Attack999IsTremulant

- (integer -1 - 1, default: -1) 1 means, that it is played, if the associated wave-based tremulant is on. 0 means, that it is played, if the associated wave-based tremulant is off. -1 means, that it not affected by a wave-based tremulant.

Pipe999Attack999MaxKeyPressTime

- (integer -1 - 100000, default: -1) Up to this time value in ms, the release sample is chosen. -1 means infinite.

Pipe999Attack999AttackStart

- (integer 0 - 158760000, default: 0) Allows to override the start of the sample. This option is specified in samples.

Pipe999Attack999CuePoint

- (integer -1 - 158760000, default: -1) Allows to override the cue point for the release. -1 means use from the wave file. This option is specified in samples.

Pipe999Attack999ReleaseEnd

- (integer -1 - 158760000, default: -1) Allows to override the end of the release. -1 means play till the end of the wav. This option is specified in samples.

Pipe999Attack999LoopCount

- (integer 0 - 100, default: 0) Allows to override the loops in the WAV file. 0 means use loops from the wave file.

Pipe999Attack999Loop999Start

- (integer 0 - 158760000, default: 0) Start sample of the loop. The value must be within the WAV file. This option is specified in samples.

Pipe999Attack999Loop999End

- (integer Pipe999Loop999Start + 1 - 158760000, required if Pipe999LoopCount is not zero) End sample of the loop. The value must be within the WAV file. This option is specified in samples.

Pipe999ReleaseCount

- (integer 0 - 100, default: 0) Number of additional release samples

Pipe999Release999

- (string, required) Relative path to the sample WAV file.

Pipe999Release999IsTremulant

- (integer -1 - 1, default: -1) 1 means, that it is played, if the associated wave-based tremulant is on. 0 means, that it is played, if the associated wave-based tremulant is off. -1 means, that it not affected by a wave-based tremulant.

Pipe999Release999MaxKeyPressTime

- (integer -1 - 100000, default: -1) Up to this time value in ms, the release sample is chosen. -1 means infinite.

Pipe999Release999CuePoint

- (integer -1 - 158760000, default: -1) Allows to override the cue point for the release. -1 means use from the wave file.

Pipe999Release999ReleaseEnd

- (integer -1 - 158760000, default: -1) Allows to override the end of the release. -1 means play till the end of the wav. This option is specified in samples.

Pipe999LoopCrossfadeLength

- (integer 0 - 3000, default: 0) Crossfade length in ms between loop end and loop start for all loops loaded from the file specified in the Pipe999 parameter. A cross fade requires enough samples before the start of the loop.

  This parameter is not inherited by loops loaded from additional attack files specified in the Pipe999Attack999 parameters

Pipe999Attack999LoopCrossfadeLength

- (integer 0 - 3000, default: 0) Crossfade length in ms between loop end and loop start for all loops loaded from the file Pipe999Attack999. A cross fade requires enough samples before the start of the loop.

Pipe999ReleaseCrossfadeLength

- (integer 0 - 3000, default: 0). 0 means automatic selection.

  Crossfade length in ms between loop and the release loaded from the file specified in the Pipe999 parameter or between different attack samples if Pipe999AttackCount > 0.

  This parameter is not inherited by the releases loaded from additional attack and release files specified in the Pipe999Attack999 and Pipe999Release999 parameters that should be specified with the Pipe999Attack999ReleaseCrossfadeLength and Pipe999Release999ReleaseCrossfadeLength parameters.

Pipe999Attack999ReleaseCrossfadeLength

- (integer 0 - 3000, default: 0). 0 means automatic selection.

  Crossfade length in ms between loop and the release loaded from the file specified in the Pipe999Attack999 parameter.

Pipe999Release999ReleaseCrossfadeLength

- (integer 0 - 3000, default: 0). 0 means automatic selection.

  Crossfade length in ms between loop and the release loaded from the file specified in the Pipe999Release999 parameter.

### Stop objects

Stop objects are drawstop objects. A stop consists of a number of ranks. If the number of ranks is set to zero, the stop contains one rank, which is defined in the stop section - else it references a list of ranks. Only the accessible pipes can be triggered from the manual. A stop has the following additions attributes:

NumberOfRanks

- (integer 0 - 999, default: 0) Number of referenced ranks. If zero, one rank definition is included in the stop section. The lists of references is specified via the Rank999... settings.

FirstAccessiblePipeLogicalKeyNumber

- (integer 1 - 128, required) The key number on the manual of the first accessible pipe.

NumberOfAccessiblePipes

- (integer 1 - 192, required) Number of pipes, that are playable from the manual starting from the first accessible pipe.

FirstAccessiblePipeLogicalPipeNumber

- (integer 1 - 192, required if NumberOfRanks=0) The number of the first pipe accessible from the manual. If NumberOfRanks is not 0, this setting is not necessary.

Rank999

- (integer 0 - rank count specified in the organ section, required) Reference to a rank from the organ section.

Rank999FirstPipeNumber

- (integer 1 - number of pipes in the rank, default: 1) Number of first mapped pipe from the rank

Rank999PipeCount

- (integer 0 - remaining number of pipes in the rank, default: remaining number of pipes in the rank) Number of pipes mapped from the rank.

Rank999FirstAccessibleKeyNumber

- (integer 1 - NumberOfAccessiblePipes, default: 1) Key number offset (starting with FirstAccessiblePipeLogicalKeyNumber) for the pipe referenced by Rank999FirstPipeNumber.

### Pushbutton objects

Pushbuttons are buttons without any state. It is displayed as a piston.

### Piston objects

A piston is a pushbutton which triggers other elements. It contains the following additional attributes:

ObjectType

- (string, required) Type of the element to trigger. Value can be STOP, COUPLER, SWITCH or TREMULANT.

ManualNumber

- (integer first manual index - last manual index, required for stops and coupler) The manual, to which the referenced object belongs.

ObjectNumber

- (integer, required) Determines the number of the object. Depending on the object it must be a valid stop/coupler/switch number on the referenced manual or a valid global tremulant number.

### Tremulant objects

Tremulants are drawstop objects with the following additional attributes:

TremulantType

- (enumeration, default: Synth) Type of the tremulant. Valid values are: Synth (synthesized tremulant) and Wave (tremulant based on different wave samples).

Synthesized tremulants have the following attributes:

Period

- (integer 32 - 441000, required) Period of the tremulant in ms

StartRate

- (integer 1 - 100, required) Determines the startup time of the tremulant.

StopRate

- (integer 1 - 100, required) Determines the stop time of the tremulant.

AmpModDepth

- (integer 1 - 100, required) Determines, how much the volume will be changed.

### Windchest objects

Windchest objects represent a windchest on which pipes of ranks are placed. It has the following attributes:

Name

- (string, default: implementation dependent) Display name of this windchest

NumberOfEnclosures

- (integer 0 - enclosure count, required) Number of enclosures, which influence this windchest. The list is specified by the Enclosure999 entries in the windchest section.

NumberOfTremulants

- (integer 0 - tremulant count, required) Number of tremulants, which influence this windchest. The list is specified by the Tremulant999 entries in the windchest section.

Enclosure999

- (integer 1 - enclosure count, required) Number of an enclosure, which influences this windchest.

Tremulant999

- (integer 1 - tremulant count, required) Number of a tremulant, which influences this windchest.

AmplitudeLevel

- (float 0 - 1000, default: 100) Linear amplitude scale factor in percents applied to the windchest. It is multilied to the AmplitudeLevel value of the Organ section. 100 means no change.

Gain

- (float -120 - 40, default: 0) Amplitude scale factor in dB applied to the windchest. It is added to the Gain value of the Organ section. 0 means no change.

PitchTuning

- (float -1800 - 1800, default: 0) Retune the windchest by the specified number of cents. It is added to the PitchTuning value of the Organ section. 0 means no change. This setting is used only for the original temperament.

PitchCorrection

- (float -1800 - 1800, default: 0) Correction factor in cent for the pitch of the windchest. It is added to the PitchTuning value of the Organ section. 0 means no change. This setting is used for retuning to other temperaments.

TrackerDelay

- (integer 0 - 10000, default: 0) Delay in miliseconds introduced by the tracker applied to the windchest. It is added to the TrackerDelay value of the Organ section.

Percussive

- (boolean, default inherited from the Organ section) If true, the samples are played as is (without any loop/release handling).

HasIndependentRelease

- (boolean, default inherited from the Organ section). If true, releases are played independently of the attacks.

  If HasIndependentRelease is true then Percussive must also be set to true.

### Crescendo objects

Crescendo objects represent a crescendo bank. The number of crescendo banks are always 4: from 0 to 3

OverrideMode

- (boolean, default: true) The crescendo mode: how the crescendo operates with stops enabled by the user.

  true - Override mode

  true - Add mode

  The difference between these modes are described at Crescendo operational modes

### Additional panels (old format)

It is possible to define additional panels. The section is called Panel999 with a number starting from 001. All panels use the same layout engine as the main panel, therefore the section includes all display metrics attributes. Additionally it includes the following attributes:

Name

- (string, required) Name of the panel

Group

- (string, default: empty) If not empty, place it in the submenu with the specified name, else directly in the panel menu.

NumberOfManuals

- (integer 1 - number of defined manuals) number of manuals to display on this panel

HasPedals

- (boolean, required) Includes a manual displayed as pedal

NumberOfSetterElements

- (integer 0 - 999, default: 0) Number of setter elements on the panel. The section of the GUI definitions are called Panel999SetterElement999.

NumberOfEnclosures

- (integer 0 - number of defined enclosures, required) Number of enclosures on the panel. The section of the enclosures GUI definitions are called Panel999Enclosure999.

Enclosure999

- (valid enclosure number, required) Reference to the enclosure on the main panel.

NumberOfTremulants

- (integer 0 - number of defined tremulants, required) Number of tremulant on the panel. The section of the tremulants GUI definitions are called Panel999Tremulant999.

Tremulant999

- (valid tremulant number, required) Reference to the tremulant on the main panel.

NumberOfReversiblePistons

- (integer 0 - number of defined reversible pistons, required) Number of reversible pistons on the panel. The section of the reversible pistons GUI definitions are called Panel999ReversiblePiston999.

ReversiblePiston999

- (valid reversible piston number, required) Reference to the reversible piston on the main panel.

NumberOfSwitches

- (integer 0 - number of defined switches, default: 0) Number of switches on the panel. The section of the switches GUI definitions are called Panel999Switchn999.

Switch999

- (valid switch number, required) Reference to the switch on the main panel.

NumberOfGenerals

- (integer 0 - number of defined generals, required) Number of generals on the panel. The section of the generals GUI definitions are called Panel999General999.

General999

- (valid general number, required) Reference to the general on the main panel.

NumberOfDivisionalCouplers

- (integer 0 - number of defined divisional couplers, required) Number of divisional couplers on the panel. The section of the divisional coupler GUI definitions are called Panel999DivisionalCoupler999.

DivisionalCoupler999

- (valid divisional coupler number, required) Reference to the divisional coupler on the main panel.

Manual999

- (valid manual number, required) Number of the manual to use a specified manual on the panel.

NumberOfStops

- (integer 0 - 999, required) Number of stops on the panel. The section of the stops GUI definitions are called Panel999Stop999.

Stop999Manual

- (valid manual number, required) Reference to the manual of the stop on the main panel.

Stop999

- (valid stop number, required) Reference to the stop on the main panel.

NumberOfCouplers

- (integer 0 - 999, required) Number of couplers on the panel. The section of the couplers GUI definitions are called Panel999Coupler999.

Coupler999Manual

- (valid manual number, required) Reference to the manual of the coupler on the main panel.

Divisional999

- (valid coupler number, required) Reference to the divisional on the main panel.

NumberOfDivisionals

- (integer 0 - 999, required) Number of divisionals on the panel. The section of the divisionals GUI definitions are called Panel999Divisional999.

Divisional999Manual

- (valid manual number, required) Reference to the manual of the divisional on the main panel.

Divisional999

- (valid divisional number, required) Reference to the divisional on the main panel.

NumberOfLabels

- (integer 0 - 999, required) Number of labels on the panel. The section of the label GUI definitions are called Panel999Label999.

NumberOfImages

- (integer 0 - 999, default: 0) Number of images on the panel. The section of the image GUI definitions are called Panel999Image999.

### Panels (new format)

The section is called Panel999. Panel000 is the main panel. Additional panels start with number 001. The section includes the display metrics. Additionally it includes the following attributes:

Name

- (string, required for non-main panels) Name of the panel

Group

- (string, default: empty, only for non-main panels) If not empty, place it in the submenu with the specified name, else directly in the panel menu.

HasPedals

- (boolean, required) Includes a manual displayed as pedal

NumberOfImages

- (integer 0 - 999, default: 0) Number of images on the panel. The section of the image GUI definitions are called Panel999Image999.

NumberOfGUIElements

- (integer 0 - 999, required for the main panel, default 0 for any other panel) Number of elements on the panel. The section of the GUI elements are called Panel999Element999.

### GUI elements

The attribute Type can be one of the following values:

Divisional

- The section contains the GUI attributes of a divisional. Additionally it includes the following attributes:

  Manual

- (valid manual number, required) Number of the manual.

Divisional

- (valid divisional number, required) Number of the divisional on the manual.

Coupler

- The section contains the GUI attributes of a coupler. Additionally it includes the following attributes:

  Manual

- (valid manual number, required) Number of the manual.

Coupler

- (valid coupler number, required) Number of the coupler on the manual.

Stop

- The section contains the GUI attributes of a stop. Additionally it includes the following attributes:

  Manual

- (valid manual number, required) Number of the manual.

Stop

- (valid stop number, required) Number of the stop on the manual.

Enclosure

- The section contains the GUI attributes of an enclosure. Additionally it includes the following attributes:

  Enclosure

- (valid enclosure number, required) Number of the enclosure.

Tremulant

- The section contains the GUI attributes of a tremulant. Additionally it includes the following attributes:

  Tremulant

- (valid tremulant number, required) Number of the tremulant.

DivisionalCoupler

- The section contains the GUI attributes of a divisional coupler. Additionally it includes the following attributes:

  DivisionalCoupler

- (valid divisional coupler number, required) Number of the divisional coupler.

General

- The section contains the GUI attributes of a general. Additionally it includes the following attributes:

  General

- (valid general number, required) Number of the general.

ReversiblePiston

- The section contains the GUI attributes of a reversible piston. Additionally it includes the following attributes:

  ReversiblePiston

- (valid reversible piston number, required) Number of the reversible piston.

Switch

- The section contains the GUI attributes of a switch. Additionally it includes the following attributes:

  Switch

- (valid switch number, required) Number of the switch.

Label

- The section contains the GUI attributes of a label.

Manual

- The section contains the GUI attributes of a manual. Additionally it includes the following attributes:

  Manual

- (valid manual number, required) Number of the manual.

Any setter element type

- See the setter element section for further description.

## The GrandOrgue organ package format

### General information

An organ package is a ZIP file using only the STORED compression [= compression level 0] with the extension orgue. It may use the ZIP64 extensions - no other extensions are allowed. It is possible to store file names containing directories.

The ID of an organ package is its SHA1 sum with all letter converted to upper case.

Each organ package must contain an index file named organindex.ini. This file lists all contained organs as well as any other organ package they might depend on.

Referenced files are only loaded from the organ package - not from the file system. If a file is missing in the main organ package, it will search Dependency001, then Dependency002 and so on.

Use wavpack to compress samples. Use PNG for lossless compression of images.

### Index file specification

It has the same syntax rules as an organ definition file. The General section has the following elements:

Title

- (string, required) Name of the organ package

OrganCount

- (integer 0 - 100, required) Number of organs installed by this package. The organs are defined in a section named Organ999.

DepenencyCount

- (integer 0 - 100, default: 0) Number of organs packages required by this organ package. The dependencies are defined in a section named Dependency999.

### Dependency section

The section has the following elements:

PackageID

- (string, required) ID of the package file, that should be searched for missing files.

Title

- (string, required) Name of the package file.

### Organ section

This section has the following elements:

Filename

- (string, required) Filename of organ definition file in the organ package.

ChurchName

- (string, required) Name of the organ/church. This setting must match the organ definition file.

OrganBuilder

- (string, required) informational text displayed in the property dialog. This setting must match the organ definition file.

RecordingDetails

- (string, required) informational text displayed in the property dialog. This setting must match the organ definition file.

## Technical Support

GrandOrgue is an open source project distributed under the GNU General Public License. For information, comments, questions, or problems, please visit the project pages on GitHub.

## History

GrandOrgue is a project based on a previous GNU GPL project with a very similar name that that has been discontinued.

## Short octave

GrandOrgue can use three different methods to make a short octave keyboard:

- Tie samples to keys

  This is the build scheme:

  - The keyboard defines e.g. 45 keys (full compass: 49)

  - The first accessible key on the physical keyboard is low E

  - The first sample (Pipe001) refers to low C (read: press low E, hear low C)

  - The second sample (Pipe002) refers to low F (read: press low F, hear low F)

  - The third sample (Pipe003) refers to low D (read: press low F#, hear low D)

  - The fourth sample (Pipe004) refers to low G (read: press low G, hear low G)

  - The fifth sample (Pipe005) refers to low E (read: press low G#, hear low E)

  - From the sixth sample and upwards, the keyboard layout is "normal"

  The pipe layout to the keys being hardwired, many useful features which expect 12-note octaves are broken in the low octave:

  - Octave and suboctave couplers (Even if this feature is unlikely when reproducing old organs)

  - Bass and melody couplers

  - Tuning to other temperaments

  This method should be considered as legacy and used only for backward compatibility with Hauptwerk™ version 1 sample sets. The preferred method for designing a short octave keyboard is through a key mapping (see MIDIKey999) and below.

- MIDI setting: 9x Note short octave at low key

  Use this setting to simulate a short octave keyboard when the Organ Definition File only provides a full compass keyboard. GrandOrgue renders sound as if the keyboard were fitted with a short octave, but the visual feedback is that of a full compass keyboard (e.g. press low E and the keyboard image in the GUI displays a depressed low C).

- MIDI mapping on full compass

  This is the build scheme:

  - The keyboard defines e.g. 49 keys, full compass

  - The first accessible key on the physical keyboard is low C

  - Pipe999 entries refer to all pipes starting a low C, as usual

  - Configure the GUI:

    DisplayKeys=45 | Display only 45 keys
    DisplayFirstNote=40 | The fist displayed key is low E

  - Add MIDIKey999 entries.

    MIDIKey036=0 | Disable low C
    MIDIKey037=0 | Disable low C#
    MIDIKey038=0 | Disable low D
    MIDIKey039=0 | Disable low D#
    MIDIKey040=36 | Map physical low E to sound low C
    MIDIKey041=41 | Map physical low F to sound low F
    MIDIKey042=38 | Map physical low F# to sound low D
    MIDIKey043=43 | Map physical low G to sound low G
    MIDIKey044=40 | Map physical low G# to sound low E
    MIDIKey045=45 | Map physical low A to sound low A. From this key up to the top end of the keyboard, the mapping is usual and can be omitted.

  - Add DisplayKey999 entries to tie GUI keys to MIDI note numbers:

    DisplayKey001=36 | 1st Key is depressed in the GUI when MIDI note 36 (low C) is received
    DisplayKey002=41 | 2nd Key is depressed in the GUI when MIDI note 41 (low F) is received
    DisplayKey003=38 | 3rd Key is depressed in the GUI when MIDI note 38 (low D) is received
    DisplayKey004=43 | 4th Key is depressed in the GUI when MIDI note 43 (low G) is received
    DisplayKey005=40 | 5th Key is depressed in the GUI when MIDI note 40 (low E) is received
    DisplayKey006=45 | 6th Key is depressed in the GUI when MIDI note 45 (low A) is received. From this key up to the top end of the keyboard, the mapping is usual and can be omitted.

  When sampling a real-world organ, missing samples in the low octave need to be generated to get a complete low octave. If this is not done, holes will appear in the low octave if the keyboard is converted to full compass using the 9x Note without map MIDI setting.