Hauptwerk Custom Organ Design Module User Guide · Custom Organ Design Module User Guide Hauptwerk version 4.2.1

Custom Organ Design Module User Guide Hauptwerk version 4.2.1

© Copyright Milan Digital Audio LLC. 2001-2015 All Rights Reserved. http://www.hauptwerk.com Page 1 of 74

Custom Organ Design Module User Guide for the

Hauptwerk Virtual Pipe Organ

Hauptwerk version 4.2.1

http://www.hauptwerk.com/



Part 1: Overview

What it is and what it’s for Very briefly, the Custom Organ Design Module exists primarily to allow end-users and amateur/hobbyist/semi-professional sample set producers quickly and easily to create high-quality organ definitions that can be loaded into Hauptwerk for personal use or for distribution as part of sample sets, and that can take good advantage of Hauptwerk’s features and give excellent results.

The next three sections give some background and explain why this is useful.

Sample sets and their data Hauptwerk allows different sample sets to be installed and loaded, providing virtual models of many different pipe organs and similar instruments. A good variety of such sample sets are available commercially.

Sample sets are comprised of some or all of the following types of data:

1. Audio samples, usually one or more for each pipe on the organ, plus action noises, effects, etc.

2. Special tremulant waveform samples, usually provided at regular intervals for each pipe rank affected by a tremulant, describing how the pitch, amplitude and harmonic content of the pipe(s) vary with time when the tremulant is active.

3. Images used to display the virtual console and other aspects of the organ and to allow the user to interact with it with a computer screen, such as a touch-screen, or the mouse.

4. The organ definition file.

5. An HTML or PDF file and any associated components, used to display information about the instrument and documentation relevant to it.

The creation of a large professional-quality sample set often involves many months of work, mostly in the preparation of the pipe samples, but a very significant amount still being required for the remaining parts.




Native organ definition files A full native Hauptwerk organ definition file is a text file in XML format, the contents of which define the organ definition database, being a normalized relational database which provides all of the information needed by Hauptwerk to model an organ. For example, each pipe is listed individually, describing such intricate details as how the air flow rate through it varies as the pressure across it changes, how its speech changes in character as flow rates vary, which samples are to be used for it under which conditions, how its characteristics change with each available tremulant and enclosure, and so on.

The full native organ definition format is extremely large and complex, of necessity so that Hauptwerk is able to provide a sufficiently detailed and generic model for (almost) all types of organs and similar instruments that exist. Although often technically possible, it would not normally be feasible to edit a native full organ definition file manually in a standard text editor because of the very large number of related tables, records and their settings, which must be updated to accomplish a given change, as well as its overall size.

Generation of an organ definition using custom-developed third-party software and/or editing it via dedicated XML manipulation software are the methods most commonly used in the production of complex commercial sample sets for Hauptwerk since they give the greatest possible degree of flexibility and control.

However, even with the benefits of such tools, the task of defining an organ definition is still very involved, and it often requires several weeks of work to produce such a definition for even a small or medium-sized complex sample set. A reasonable understanding of pipe organ construction and some of the relevant physics principles involved in the Hauptwerk models is also required in order to configure parts of the organ definition database to best effect, and it often takes several months to master Hauptwerk’s full native organ definition format.

It is thus expected that most users and amateur/hobbyist/semi-professional sample set producers would not have the time or inclination to study the full organ definition format, organ building, physics principles, or to devote to the configuration of the database. Because no user settings are stored within the organ definition database, it is also intended that no user should ever need to examine or edit the organ definition databases in order to use and appreciate any sample set fully within Hauptwerk.

In summary: Hauptwerk’s full native organ definition file format is enormously flexible and powerful but correspondingly complex. It is not aimed at end-users or amateur/hobbyist/semi-professional sample set producers, so very few people would need to understand or use it.




The Custom Organ Design module Despite the complexities of the full organ definition format, many users wish to create their own organ specifications using parts of sample sets that they have installed (where the licensing of those sample sets allows it), tailored to their own particular musical tastes and the physical organ consoles they have available from which to play them. There is thus a need to be able to define and adjust organs simply and quickly. Amateur/hobbyist/semi-professional sample set producers also require a simple organ definition format to work with that provides sufficient flexibility to make a fully-functional organ of reasonable complexity and to cater for functionality commonly found on most types of organs, but that remains quick and easy to learn, manipulate and use.

Hauptwerk's Custom Organ Design Module is intended to provide for those needs.

It provides a simple alternative and parallel organ definition format with which to define an organ easily: the custom organ definition format. The custom organ definition format is another XML text file format, the contents of which are termed the custom organ definition database. The file format is simply referred to as a database because the data within it are organized into tables and fields; it is still just a simple XML/text format, and does not need any third-party database software to edit it.

The format has been very carefully designed so that an absolute minimum of information must be given to define an instrument, whilst still allowing large and relatively complex instruments to be modeled (including both classical and theatre organs), and for

most of Hauptwerk's features to be used very effectively. No understanding of the physics of the models is required, and a minimal understanding of pipe organ building is necessary.

It is also designed in such a way that very few data tables and records are required, so that the files remain small and easily-managed, and so that it is an easy task to configure an instrument using simply a text or XML editor.

When Hauptwerk loads a custom organ definition file, it first 'compiles' the data contained within it to its native full organ definition format, saves the resulting organ definition file, then finally loads that file as normal. During the compilation process the full organ definition is generated using the settings provided within the custom organ definition file, with sensible defaults being calculated automatically for most of the complex settings in the full organ definition (such as the air flow rates within the various parts of the organ), in order to keep the custom organ definition format simple.

The resulting compiled organ definitions can be used in the same way as any other native organ definition files; they can be loaded as normal via the Organ menu in Hauptwerk, or shared with other Hauptwerk users, whether or not those users are familiar with use of the Custom Organ Design module itself. The role of the Custom Organ Design module is thus simply that of a compiler, taking as an input a small and easy, yet powerful and flexible, organ definition format, and producing as output a full native Hauptwerk organ definition file.

The Custom Organ Design Module allows for fully-customizable graphical virtual consoles to be created and has support for most functional features found on both classical and theatre organs. Hence it is an ideal tool with which amateur/hobbyist/semi-professional sample set producers can create organ definition files suitable for public release as part of sample sets, as well as for personal use. Sample set producers that require more flexibility still can use the Custom Organ Design Module to generate an initial organ definition, and then fine-tune the compiled native organ definition further if required. Once a custom organ definition has been loaded/compiled, a sample set producer simply needs to edit the generated native organ definition file to change the unique organ ID in order to make it suitable for distributing publicly as part of a sample set. Please contact us to be assigned the necessary ID if you wish to make a sample set or native organ definition file available publicly, since the values must be unique globally, as covered later in this guide. (There is no charge for the service.)

Please note that the custom organ definition format still uses text/XML files; there is not yet a graphical interface for the organ design process itself. Hence we would generally advise novice computer users to start with simple custom organs and examples first.




Licensing The Custom Organ Design Module is included within the Hauptwerk license in all editions of Hauptwerk. No separate license is required for its use. However, it is only possible to take full advantage of some organ features that can optionally be modeled with the Custom Organ Design Module using the Advanced Edition, such as an organ wind supply model or virtual consoles designed for multiple touchscreen use.

Support Although it is quick and simple to create simple custom organ definitions, it also allows quite complex and sophisticated organ definitions to be created. The design goal has been to keep the format as small and simple as possible, but inevitably some familiarization is required, and there is a certain amount of additional complexity if you wish to take advantage of more advanced features. Hence we would generally advise novice computer users to start with simple custom organ definitions and examples first.

Important note: because of the sophistication possible, and because of the 'DIY' nature of creating or editing organs to taste, it needs to be emphasized that we are sorry that we cannot provide personal tuition, or assistance in creating/editing custom organ definitions, to end-users. This user guide and an extensive set of examples are provided to help. We will usually only be able to provide a small amount of support beyond that. However, you can of course exchange help and advice with other users via our website forum.




Basic operation and getting started A custom organ definition is loaded into Hauptwerk using the Design tools | Load custom organ ... menu function. That’s the only menu function needed to use the Custom Organ Design Module.

Hauptwerk’s installer installs several example custom organs for you to get you started, all of which use samples from the St. Anne’s, Moseley organ sample set installed with Hauptwerk. If you haven’t used the Custom Organ Design Module before, start by loading one of these examples:

• Use Design tools | Load custom ... organ to select the entry named ExampleCustomOrgan2 and click OK.

• The Load Organ Design Options window will appear. Leave all the settings at their defaults and click OK.

• The Custom Organ Design Module will now compile the custom organ definition to a full native organ definition file and load it as normal, presenting you with the Rank Audio/Memory Options and Routing screen as usual the first time that you load an organ. Click OK (or disable some ranks first if you have less than 1 GB of memory).

• Once the organ has loaded, try using and playing it as normal. This should give you an idea of what can be achieved using the module, and is a relatively complex organ intended to serve as an example for various complex features such as Pizzicato couplers and a Thunder piston, and also showing a custom graphical console using some of the control images from the standard library supplied with Hauptwerk.

• When you have finished playing the organ, select Organ | Load organ ... from the menu. You will see that an entry named ExampleCustomOrgan2 now exists. This is the compiled full native organ definition that the Custom Organ Design Module

generated from the custom organ definition when you loaded it via the Design tools menu. If you wish you can now load that organ using the functions on the Organ menu as you would with any other organ. However, if you subsequently made any changes to the custom organ definition then they wouldn’t have any effect until you re-loaded the custom organ definition using Design tools | Load custom organ … again, since only by doing that will the Custom Organ Design Module be invoked to regenerate the native organ definition.

• Now use Design tools | Load custom organ ... to select and load the ExampleCustomOrgan1 entry, clicking OK on the following options screens as before.

• When the organ has loaded try it out and look at the various display page tabs. This organ is a very simple example that just uses the standard virtual console display that the Custom Organ Design Module generates automatically by default. Creating such an organ with a standard display is very quick indeed (probably considerably less than an hour) once you have mastered the custom organ definition format.

• Now use Finder (if you're using Mac OS X) or File Explorer / Windows Explorer (if you're using a Windows PC) to navigate to the CustomOrganDefinitions folder inside the HauptwerkUserData folder. If you performed a default Hauptwerk installation,

that folder will be found inside /Hauptwerk (Mac OS X) or C:\Hauptwerk (Windows).

• Open the file named ExampleCustomOrgan1.CustomOrgan_Hauptwerk_xml inside a text editor, such as Mac OS X’s /Applications/Utilities/TextEdit or Windows’ Notepad. This is the custom organ definition for the organ that you just loaded. Browse around the file and compare its sections (‘tables’) objects (‘records’) and individual settings (‘fields’, ‘attributes’ or ‘parameters’; used interchangeably as terms) with the reference documentation at the end of this guide.

• If you want to try changing it, you need to make a copy of the file, rename the copy, open that copy in your text editor, and change the UniqueOrganID setting near the top of the file to a new unique value above 800010 (so that it doesn’t match any of the example organs). You must always make sure that the organ ID is unique, otherwise settings, voicing and combination files from one organ will overwrite those of another.

• You can then try making changes to your copy and loading it using Design tools | Load custom organ ... to see what happens.

Now that you have a basic understanding of operating the module, try making some custom organs yourself, referring to the rest of this guide for more details, and also to the other example files.




The example files Often the quickest way to learn something is to see examples of it in action. Hence we’ve tried to provide a good selection of example custom organ definition files to get you started and to be used as reference.

A total of six example organ definitions are provided, ranging from a very simple organ with an automatically-generated virtual console to a large complex organ with a custom graphical display, action noises, and demonstrating how to implement many other advanced features, such as pizzicato. Four versions, increasing in sophistication, of the St. Anne's, Moseley organ are included in those examples, both to show the process of building up an organ definition and to allow easy customization of the sample set by users.

All of the files can be found in the CustomOrganDefinitions folder (see the last section for its location), and all custom organ definitions must be stored in that folder in order to be usable in the Custom Organ Design Module. Custom organ definitions have the file extension ....CustomOrgan_Hauptwerk_xml and can be edited in a text editor or XML editor.

The purpose of each example file is as follows:

• ExampleCustomOrgan1: This is a very simple custom organ that demonstrates how easy it is to create a functional organ quickly. It uses the default standard generated virtual console display, rather than a custom graphical virtual console, which makes it very quick to create and edit, with minimal settings to change. It has no action noises and uses stop, coupler and enclosure behavior which is determined by the stop, coupler and enclosure codes. Such behavior is sufficient for the vast majority of classical organs.

• ExampleCustomOrgan2: This is intended to demonstrate as many functional complexities as possible. A custom graphical console is used (see below), but with only one display page tab and screen layout. The organ also has key action noise, stop action noise and blower noise. A multi-rank stop is included (the Sesquialtera) as well as various borrowed/unified ranks. An array of standard divisions and couplers and non-standard divisions are demonstrated, as well as complex custom couplers (Swell Reeds to Choir) and couplers with special actions (Great to Choir Pizzicato coupler). Reversible pistons are demonstrated, as are complex effects pistons (Thunder). Internal couplers that copy their states from others are also included for the Swell division to allow the Swell Reeds to Choir to be implemented whilst the Swell keyboard can play both its reed stops and other stops, even though they are attached to different divisions internally. Most of these features you will probably never need to use. However, this example organ definition does serve one other very important function: the CustomDisplayControlStyle and CustomDisplayKeyboardStyle sections/tables contain a ready-made master library of display styles that you can copy and paste into your own custom organ definitions.

• ExampleCustomOrgan3-StAnnes-Simplified: This is the St. Anne’s organ recreated in the Custom Organ Design Module in the simplest possible way. There are no custom graphical displays, no noises and no additional pistons or other gadgetry.

You would normally start by creating and fine-tuning an organ definition in this way before complicating it with graphics or other ‘frills’.

• ExampleCustomOrgan4-StAnnes-WithBasicGUIConsole: Beginning the process of building up a fully-fledged organ for inclusion in a sample set, this adds a single custom graphical console display page and reversible pistons to example 3.

• ExampleCustomOrgan5-StAnnes-WithBasicGUIAndNoises: Building on example 4, this adds key action noise, stop action noise, tremulant action noise (two types) and blower noises.

• ExampleCustomOrgan6-StAnnes-WithAllFrills: Finally, this adds additional graphical console display pages to example 4, making it suitable for use on dual-touchscreen computers, whilst also retaining the overview console display page for those

that want to use it on single-monitor systems, or who don't have the Advanced Edition of Hauptwerk (only the Advanced Edition supports multiple monitors). It also includes an alternate screen layout for the left and right stop jamb display pages, thus natively supporting both landscape and portrait orientations for touch-screen monitors (Hauptwerk selects the most appropriate one automatically, depending on the size of the window/monitor).

Important note 1: please do not edit any of these example files directly, since you might want to refer to them later, and they will be overwritten next time that you run Hauptwerk’s installer. Instead, make a copy of them, rename them and change the unique organ IDs in the copies, as described in the last section. Then make any edits you wish in those copies.

Important note 2: example custom organ 2 contains a ready-made master style library, ready for you to copy and paste into your own custom organ definitions if you want to use the library of graphical control and keyboard images supplied with Hauptwerk.




An overview of the objects in a custom organ definition and characteristics of organs created with the Custom Organ Design Module Since the intention of the module is to make it as quick and easy as possible to configure functional organs, some aspects of the compiled organ definition are fixed, or calculated automatically according to fixed rules.

The organ overall has a ‘master combination capture’ (setter) switch, a general cancel piston and set of 20 native general combinations. All combinations pistons allow capture.

Any or all of seven standard fixed divisions may be included for general use (six manuals and a pedalboard), and an enclosure (swell box) can optionally be assigned to each. A fixed set of choices exist for the available enclosures; at most one per division, and optionally also a general swell. Each division has its own keyboard, divisional cancel piston, set of 20 divisional combinations and key actions. Stops, couplers and tremulants can be assigned to any of these divisions and are stored and recalled within the divisional combinations for the division to which they are assigned.

For each standard division, a parallel-rise weighted wind reservoir, wind-chest, regulator valves and indicators can optionally be created. Almost all of the wind model is calculated and generated automatically, with just a very small number of the most important parameters being provided to adjust its behavior, and an option to disable it. Any standard division may be used as a source of wind for ranks.

Additional (non-standard) divisions are allowed (up to sixteen in total, including the seven standard divisions), but they would normally only be used for implementing special couplers, such as ‘Choir Reeds to Great’, where an additional division would need to be used for the Choir reeds so that could sound from the Choir or the Great keyboards. These additional divisions do not have their own divisional combinations or wind-chest. Any stops, couplers and tremulants attached to them must also be associated with one of the seven standard divisions to define in which divisional combinations they should be stored and recalled. In the preceding example, stops attached to the special ‘Choir reeds’ division should be associated with the ‘Choir’ division for combinations, so that the main Choir division’s divisional combinations store and recall their states.

A coupler is normally specified by selecting it from a fixed range of choices, determined by its ‘coupler code’, which defines which divisions it links and at what pitch. Those standard codes only allow coupling to/from the seven standard divisions. However, a range of ‘custom coupler’ codes exists to allow for complex coupling, such as pizzicato, or coupling at mutation pitches. The coupler code always defines the division in whose divisional combinations its state will be stored/recalled, which can only be one of the standard seven divisions. To couple to/from other divisions, the source and destination divisions can optionally be overridden to any division, including the remaining non-standard divisions.

Tremulants similarly may be selected from a fixed range of choices. As with couplers, the ‘tremulant code’ defines the division with which it is associated for divisional combination purposes, but has no other effect, since any rank can optionally be associated with any tremulant, regardless of the tremulant’s division.

Pipe samples may be used from any sample set (if the license of the sample set permits it) to form a rank, and tremulant waveform samples from any sample set may be applied to it (also subject to sample set license). One or more ranks, or parts thereof, can be assigned to each stop, allowing unification/borrowing between stops and divisions. There is a many-to-many relationship between ranks and stops, so a stop can cause several ranks to sound at once and/or several parts of ranks and/or a rank may be used by several stops (unification).

The Rank table is by far the most complex in the custom organ definition database, and defines how all of the pipework should be generated - the samples to use, their original pitch, the pitch at which they should sound (when played from a unison-pitch stop), voicing, modulation by the wind model and tremulants (pitch, amplitude and harmonic content), the acoustical effects of any enclosure, which tremulant waveform samples should be applied (if any), and so on. Although the table requires a reasonable amount of configuration, all such complexity is concentrated in a single record for each rank - there is no need to specify values for each pipe - and the options are very much simplified over the full organ definition database, whilst still allowing a great deal of flexibility where it is most needed.

As with couplers, the 'stop code' of a stop defines the division in whose divisional combinations its state is stored/recalled, which can only be one of the seven standard divisions. Its source division (the division to whose key action it will be attached) is also determined by default from that code. However, to allow use of the non-standard divisions it is possible to override the source division, as with couplers.

Various additional options exist for stops, couplers and tremulants to allow special/unusual behavior. For example, they can optionally be non-displayed, non-latching (momentary, e.g. a theatre organ ‘toy counter’ effect), default to engaged (e.g. a blower ‘stop’), not directly accessible to the user via MIDI, and need not appear in divisional or general combinations. Any stop, coupler or tremulant may also be set to track the state of any other. This is useful for ‘internal’ objects that are used to implement complex cases, usually in combination with making the object non-accessible via MIDI, non-displayed and not appearing in combinations. As an example, a visible and accessible coupler could actually trigger two couplers internally to connect a source division to two destination divisions to allow for a ‘Swell Reeds to Choir’ coupler. In that case a ‘Swell Octave’ coupler would need to play both the Swell division and the Swell Reeds division from the Swell keys, requiring two couplers.

The ‘example custom organ 2' example demonstrates most of these complex cases for reference, whilst the ‘example custom organ 1' example demonstrates simple standard cases. For most classical organs these types of special behavior would not be needed.

Reversible and other ‘short-cut’ pistons may also be defined to allow a (reversible) piston to toggle the state of stop, coupler or tremulant or to allow the piston to turn on the target whilst held in. Theatre organ ‘toy counter’ effects could also be implemented in that way.




Object codes, references and object names Most types of object in the custom organ definition format are identified by a code. For example, the Coupler table has a CouplerCode attribute which defines the coupler code of each entry in the table. The code serves several purposes:

• It identifies the object uniquely. No two objects of a given type can have the same code. When you need to refer to the object from a different type of object, you then just need to specify its code. For example the TremulantCode attribute of the ShortcutPiston table refers to the Tremulant table, so to tell the Custom Organ Design Module that the piston should trigger a particular tremulant you need to set that piston’s TremulantCode value to match the corresponding value from the Tremulant table for the tremulant you want it to trigger.

• It defines its primary ‘role’, which Hauptwerk uses to help choose appropriate actions when a user right-clicks on it on the virtual console. For example if an Enclosure object has the code 220 then that tells the Custom Organ Design Module that it is the swell box for the Swell division.

• For some types of objects, such as Stop and Coupler objects, it determines the division(s) to which it will be connected functionally (although it is possible to override the division(s) for special cases).

• For Stop, Coupler and Tremulant objects it also determines the division in whose divisional combinations its state will be stored and recalled.

Most tables also have a Name attribute. The value you specify for the name never has any affect on the functioning or structure of the organ. It is primarily there to help you, as the designer of the custom organ, be able to identify the object in user-friendly way. The Name setting is also usually displayed to the user via the settings screens on the Organ settings menu in Hauptwerk, the contents of which are sorted alphabetically by the object names. Thus you should make sure you use names that will be meaningful to the user of the organ.




The default standard console display By default a standard, fixed virtual console display is generated. Four pages (tabs) are created on the console screen. The 'keyboards' page shows the manuals, pedalboard and any expression pedals for enclosures.

The 'controls' page lists all of the stops, couplers and tremulants on the stop jambs for the standard divisions. A maximum of 38 stops, couplers and tremulants in total can appear for each division. If more exist, then the remaining items will not be shown. The jambs are simply presented as lists with a column for each division, and they are automatically sorted according to the function code (see above) of each object. The twenty divisional combinations and the divisional cancel piston are displayed in a column to the left of each division's jamb. The twenty general combination pistons, along with the general cancel and setter piston, are displayed in a row along the bottom of the screen.

All standard divisions are displayed in columns on the 'wind' page, organized by division.

Non-standard divisions do not appear on the default standard generated ‘keyboards’, ‘controls’, or ‘wind’ display pages.

The 'enclosures' page displays indicators for the positions of the expression pedal and shutters for each enclosure, and optionally also the wind pressure inside the swell box (the wind model can be enabled or disabled for an enclosure).

Generation of the default standard display pages can be enabled or disabled individually as required. Those if using the Custom Organ Design Module to produce sample sets for public release you might want to disable the standard display pages in favor of an aesthetically-pleasing custom display.




The custom display functionality As well as the default standard virtual console display, you can optionally create a fully-customized graphical display using images from a standard library we provide, or using images of your own. Any image file can be used for any virtual control (stop, coupler, tremulant, piston, keyboard, etc.) and image files can be specified freely for the console screen backgrounds. A toolkit of useful ready-made control and background images is included with Hauptwerk, including various styles of draw-knobs, pistons, theatre organ tabs, rocker switches, labels, expression pedals, keyboards and pedal boards. Most are specifically designed to be suitable for touch-screen use. These make it easy to create a graphical console quickly.

Multiple custom display page tabs may be used for compatibility with Hauptwerk's multi-monitor/multi-touchscreen support (available in the Advanced Edition). Any virtual control may be displayed using custom images on up to two page tabs simultaneously. For example a draw-knob could appear on a console overview page and also on a page representing the left stop jamb for use with two touchscreens. The CustomDisplayPage table is used to define the page tabs and their background images.

Images, fonts, keyboard key images and layouts and other display properties are defined as a library of 'styles' so that only a few parameters need to specified for each virtual control. An extensive ready-made style library is supplied in the ‘example custom organ 2' custom organ definition file, ready for you to copy and paste into your own organ definitions and use immediately. The CustomDisplayControlStyle and CustomDisplayKeyboardStyle tables define the style library. To make use of our pre-defined styles and images, simply copy and paste those two tables from our ‘example custom organ 2' custom organ definition into your own custom organ definition file. You can then add more of your own if you wish, or delete those that you don’t want to use (which slightly saves memory and reduces organ loading time).

For each virtual control you then just select the style, specify its X and Y co-ordinates in pixels and the text (if any) to be displayed upon it. The CustomDisplay_... fields of the Stop, Coupler, Tremulant, Enclosure, Division, _General, ShortcutPiston and CustomDisplayLabel tables provide that functionality. In each case there is a set of fields prefixed CustomDisplay1_... and another identical set prefixed CustomDisplay2_... . Either, neither or both may be used, thus allowing any control to appear simultaneously on up to two different custom display pages.

Divisional and general combinations are always displayed in rows by specifying the number that should be displayed and the X and Y co-ordinates of their first and last displayed pistons. The rows need not be horizontal.

The CustomDisplayLabel table allows static (non-functional) image items (usually labels) to be positioned freely on any custom display page.

Several additional CustomDisplay_... fields exist on the _General table that allow the size of the virtual console to be defined, whether the default standard virtual console display pages are enabled, and which custom display page tab should be selected by default when the user loads an organ for the first time. (For subsequent loads the last-selected page is remembered.)

Additionally, an alternate layout may be specified for some or all custom display pages, defined with the ..._AlternateLayout1_... and ..._AltLayout1_... fields on various tables. A separate (global) size may be specified for this layout (within the _General table) and each custom display page must then specify whether it includes the alternate layout or not. This allows an organ to include up to two custom layouts natively laid out optimally for different screen orientations or aspect ratios for any given display page. Typically the main layout would be used for landscape views of the console pages and the alternate layout for a portrait views, to allow for portrait-oriented left and right stop jamb touch-screens. For any display page the user selects Hauptwerk automatically chooses the layout that most closely matches the aspect ratio and/or size of the virtual console window on which it's being displayed. By default it will zoom the chosen page (aspect ratio) to fit as best it can. You can see this in action by loading the ExampleCustomOrgan6-StAnnes-WithAllFrills example custom organ in Hauptwerk, selecting the left or right jamb tab at the top of the virtual console screen, and then dragging the main Hauptwerk window between a wide shape (landscape) and a tall and narrow (portrait) shape. The virtual stop jamb should toggle automatically between landscape and portrait layouts. Note that all controls that appear on any given display page that includes the alternate layout must also appear on the alternate layout for that page. Thus an alternate layout does not allow the controls to be reorganized across display page boundaries.

Using the custom display functionality does increase the time it takes to create a custom organ but allows a very professional-looking virtual organ to be created which could be suitable for release publicly as part of sample set.




Couplers An entry in the Coupler table defines a key action between two divisions, which will be conditional upon the state of the coupler switch.

Most couplers found on a classical organ can be created simply by including an entry in the Coupler table with its coupler code set to the appropriate value. The coupler code defines the source and destination divisions, the coupling pitch, and the division in whose divisional combinations its state will be stored/recalled.

However, for special case, if you want the source division to be other than one of the standard seven divisions, then you must set the OverrideSourceDivisionToSpecifiedDivisionCode field. The division for combinations is always determined by the coupler code, and is not overridden by that setting. You may also override the destination division and couple the destination division’s key action (the default) or keyboard.

Also if you want to couple at a mutation pitch or create a coupler with a special type of action, such as pizzicato, reiterating or theatre organ trap, then you should use one of the ‘custom coupler’ values for the coupler code. The CustomCoupler_... fields may then be used to define the coupling pitch and coupling actions.

Note that a standard unison key action is also generated by default for each division unless a unison-off coupler is specified for that division.




Ranks and audio samples Hauptwerk uses audio samples in Microsoft WAV format (or the custom copy-protected .hbw format) to produce its pipe sounds. Typically, one or more samples is used per pipe, but samples can also be provided at any note interval. Samples may be referenced from any Hauptwerk sample set installed on the computer provided that they adhere to the requirements for compatibility with the Custom Organ Design Module and that the license for the sample set allows it.

The method by which samples are referenced is covered later in this guide.

Hauptwerk’s Rank table defines both the pipes and ranks in a custom organ. Although noises and effects are not strictly pipes, anything that produces a sound in Hauptwerk is considered to be a ‘pipe’ and so must be listed within the Rank table in order to function. To keep the custom organ definition format small and manageable, there is no need to list pipes or samples individually. Instead sample filenames must follow a particular format based on the note number from which they would normally sound. Thus only the sample folders need to be specified in the Rank table. Attributes prefixed Samples_... define the set of sample files and their properties.

The number of ‘pipes’ and the starting note number define the virtual pipes that will exist. A sample is loaded once per virtual pipe, even if the same samples is shared across a range of notes (i.e. if the interval between samples is greater than one). This is necessary because Hauptwerk performs off-line processing on each sample, depending on the pitch and other properties of the pipe using it, in order to give best possible real-time performance. Hence the contents of the Rank table define the virtual pipes,

the samples to be used and also determine the amount of memory that will be used for a sample set. You should thus not create more virtual pipe objects (by way of Rank entries) than are actually needed, otherwise memory would be wasted.

Each entry in the Rank table will appear to the user as an entry on the rank routing options screen, allowing the user to enable/disable and select a particular memory format and audio routing for it.

A rank and its pipes can be either percussive (‘one-shot’) or sustaining. Samples for the former are simply played from start to end when the ‘pipe’ is triggered. The later must have at least one loop and a WAV cue point as a release marker (or the release portion can be in a separate sample file). Whilst the pipe is sounding the sample is played looped, and a phase-aligned cross-fade is performed to the section starting at the release marker when the pipe stops sounding.

Multiple release samples are also supported, by specifying 'short note' and 'medium note' release sample folders and associated maximum note times. When a note is played Hauptwerk will then choose the best release sample, depending on how long the virtual pipe had been sounding, giving improved realism of the virtual acoustic when playing fast.

A range of attributes exist on the Rank table to adjust the amplitude, pitch and harmonic content of the pipes within the rank, and the response of each to the wind supply model and tremulants. Values are specified for note number 36 (the lowest C on a 61-note manual) and 96 (the highest C on a 61-note manual), whether or not the rank actually includes pipes of those note numbers, and the values for each other note number that exists within the rank are projected linearly from those based on the note numbers of the pipes.




The relationship between stops and ranks It is important to understand that there is always a many-to-many relationship between stops and ranks. Creating an entry in either or both of the Stop and Rank tables will not cause any pipes to be playable. You must also have at least one entry in the StopRank table, which links the other two together, i.e. connects the division’s key action to the rank’s pipes dependent upon the state of the stop switch.

Think of the Stop entry as defining the stop switch and the Rank entry as defining the set of pipes. Without the StopRank entry there is no connection between them. StopRank entries define the actions between the division notes/keys and pipes.

Because the StopRank table provides a many-to-many relationship, a rank can optionally be referenced by more than one stop (unification), and a stop can optionally reference more than one rank (e.g. multi-rank stops or stops that borrow bass pipes from another rank).

Each StopRank entry defines the range of division notes/keys that should be connected and the pitch of the action. Special types of action are also allowed, as with couplers, such as pizzicato, reiterators and theatre organ traps. The ActionTypeCode, ActionEffectCode, PipeMIDINoteNum036_PizzOrReitPeriodMs, PipeMIDINoteNum096_PizzOrReitPeriodMs fields make those possible. Note that it is better to use a coupler for a special complex type of action (e.g. pizzicato or reiterating) if it will be required for many stops, since there will be less overheads on the computer’s processor than by duplicating it for a large number of StopRank entries.




Using Hauptwerk’s native tremulant model Hauptwerk’s native tremulant model uses special ‘tremulant waveform’ samples to define the waveform (LFO) shapes used to modulate the amplitude, pitch and harmonic content of its pipes separately in real-time when a tremulant is active. This ensures that the tremulant-affected sound remains perfectly synchronized across all pipes attached to a given tremulant and that tremulants can be started and stopped realistically whilst notes are sounding.

Such tremulant waveform samples are stored in a special Hauptwerk-specific format and are supplied as part of sample sets, organized by rank(s) into folders, with waveforms included at intervals across the compass of the rank (if they are designed for compatibility with the Custom Organ Design Module).

To use Hauptwerk’s native tremulant model in a custom organ definition you just need to include an entry in the Tremulant table, which represents the switch used to turn the tremulant on and off and defines the tremulant rate. The tremulant movement for all ranks attached to a given Tremulant object will be perfectly synchronized. The tremulant code determines the division in whose combinations its state will be stored and recalled.

Then specify the Tremulant object’s tremulant code for Trem_TremulantCode in any given Rank entry to make the rank be affected by that tremulant. Since different ranks often respond differently to a given tremulant, the set of tremulant waveforms is specified separately for each rank, rather than for the Tremulant object. The Trem_... attributes of the Rank table define the set of tremulant waveform samples to use for a given rank, i.e. define the modulation shapes for it.

At most one tremulant can be attached to any given rank within the Custom Organ Design Module.

Using real tremulant-affected samples There is also simple native support for using real tremulant-affected samples (if preferred to Hauptwerk's tremulant model) via the StopRank table. Held notes optionally do not re-trigger.

To implement them for a particular real pipe rank you would need two entries in the Rank table; one for the set of ‘untremmed’ samples and one for the ‘tremmed’.

You then need a Stop entry (not a Tremulant entry) to define the switch that will be used to switch between the untremmed and tremmed ranks, i.e. the switch that the user will see as the virtual tremulant switch, even though it is actually an entry in the Stop table. (You do not need any StopRank entries for that stop directly.)

Finally, for each virtual stop that connects to the rank, the StopRank entry should specify the ‘tremulant switch’ Stop entry for the StopCodeToSwitchToAlternateRank parameter, and specify the untremmed rank for RankID and the tremmed rank AlternateRankID. The key action generated will then connect the keys to the untremmed rank when the ‘tremulant switch’ stop is off, but to the tremmed rank when it is on.

Held notes can optionally re-trigger when switching between the two, dependent upon RetriggerNotesWhenSwitchingBetweenNormalAndAlternateRanks.




Hauptwerk’s swell box model Hauptwerk models the affect of a swell box on each pipe individually by modulating its amplitude and applying a simple low-pass or high-pass filter to it. Because the filter is applied separately to each pipe in real-time, its frequency response is necessarily simple, so that the processor overheads are not excessive.

To implement a swell box, include an entry in the Enclosure table. The entry will then appear to the user on the relevant MIDI settings screen. A standard default shutter inertia and wind supply model can also be enabled for the virtual swell box.

To define which ranks are affected by a given swell box, set the Encl_EnclosureCode attribute for a Rank object to the enclosure’s code. As with the native tremulant model, the effect of a swell box on the sound of the pipes is likely to vary from rank to rank and across the compass of the rank. The Encl_FiltParamWhenClsd... settings specify the shape of the filter’s frequency response when the virtual box is closed and the Encl_FiltParamWhenOpen... for when it is open. Hauptwerk projects the values linearly in between for intermediate stages. As with other Rank settings, the responses are specified for a pipe with note number 36 (lowest C on a 61-note keyboard) and 96 (highest C on a 61-note keyboard), whether or not the rank actually contains pipes of those note numbers, and Hauptwerk projects the values for other notes from those.

The ...OverallAttnDb settings define the amount of amplitude modulation. The ...MaxFreqHz settings specify the frequency that will have the highest amplitude and ...MinFreqHz the lowest. Thus to specify a low-pass filter, the ...MaxFreqHz attribute would

be set to a smaller value than its corresponding ...MinFreqHz attribute. For a high-pass filter the opposite would be true. The ...ExtraAttnAtMinDb settings specify by how the frequencies should be attenuated as a result of the filter, i.e. the extra attenuation at the minimum frequency response relative to that at the maximum (determined by ...OverallAttnDb setting).

There are no hard and fast rules about the best settings since the frequency response of the enclosure filters has to be very simple (because they are applied to each pipe individually in real-time), so it is a case of fine-tuning the frequency response to give a result that sounds like a reasonable approximation for each rank. For example, the values for the St. Anne's, Moseley organ sample set were determined by making reference recordings of several pipes per octave for each rank with the swell box open and then with it closed. The difference in frequency responses were then plotted and an attempt was made to produce an approximate best-fit for the frequency response of Hauptwerk's swell box filters. The results were then further tweaked by ear for each rank until they sounded reasonably similar to the reference recordings.

For a basic low-pass filter, which gives a reasonable result for any rank, and could thus be used as a starting point, you might wish to try:

• Maximum frequency when closed: 200 Hz

• Maximum frequency when open: 100 Hz

• Minimum frequency when closed: 1 kHz

• Minimum frequency when open: 8 kHz

The image on the following page shows an example of the frequency response that would be obtained if the maximum frequency was set to 2 kHz, the minimum to 4 kHz and the extra attenuation at the minimum to 10 decibels.







Action noises, blower noise and sound effects The custom organ definition format has special provision to make it simple to include action noises and sound effects.

To include such sounds, first list them in the Rank table. It is usually advisable to have a separate rank entry for each type of noise/effect so that the user has control over which to enable and to which speakers they should be routed.

Although a noise/effect might not have a well-defined pitch as such, it must still be associated with a note number and Hauptwerk must still be given a pitch for its sample(s). Provided that the pitch of the virtual pipes match those of the samples then no pitch-shifting will occur. For example, to include a single blower sample, you could simply use 060-C.wav for its filename, then set:

• Samples_RankBasePitch64ftHarmNumIfAssumedTunedToConcertPitch to 8 (meaning 8'),

• Pitch_RankBaseOutputPitch64ftHarmonicNum to 8,

• MIDINoteNumberOfFirstPipe to 60,

• NumberOfPipes to 1

Because the sample and output pitches match no pitch-shifting would occur in that case.

Once the appropriate entry exists in the Rank table, you can attach it to any stop, coupler or tremulant using the following attributes on their tables:

• PercussiveEngagingSoundEffect_RankID

• PercussiveEngagingSoundEffect_MIDINoteNumber

• PercussiveDisengagingSoundEffect_RankID

• PercussiveDisengagingSoundEffect_MIDINoteNumber

• SustainingSoundEffect_RankID

• SustainingSoundEffect_MIDINoteNumber

For a blower, you would normally want to create a Stop entry for it so that its switch is accessible to the user and use the stop’s SustainingSoundEffect_... attributes to attach the virtual ‘pipe’ (note number 60 in this example) to that stop. The sample will then sound as long as the stop is turned on. The stop could be made to default to the engaged state.

Theatre organ ‘toy counter’ effects can be implemented in the same way. By setting the Stop’s SwitchIsLatching setting to N, the stop will behave as a momentary button (piston), only staying on whilst it is held in by the user.

A tremulant ‘chuffing’ noise could be implemented similarly, this time just using the SustainingSoundEffect_... attributes for the Tremulant object so that it runs whilst the tremulant switch is on.

For ‘clunks’ as stops, couplers and tremulants engage, use the PercussiveEngagingSoundEffect_... attributes, and the PercussiveDisengagingSoundEffect_... attributes for sounds that should be triggered when they disengage.

If you have more than one noise/sound affect, e.g. a collection of stop action ‘clunks’ all listed as different notes in the same Rank entry, and want to attach a random ‘clunk’ to each stop, coupler and tremulant, simply set the relevant ...SoundEffect_MIDINoteNumber to 0. If the setting is 0, Hauptwerk will choose a random ‘pipe’ (noise sample) from the rank.

Key action noise is implemented by listing one or more sets of key action ‘clunks’ as ranks in the Rank table. If you had separate ‘key-on’ clunks and separate ‘key-off’ clunks, then you would need two ranks; one for each. Then use the following attributes on the Division table to attach them to the division’s keys:

• PercussiveEngagingKeyActionNoise_RankID

• PercussiveEngagingKeyActionNoise_ChooseMIDINoteNumRandomly

• PercussiveDisengagingKeyActionNoise_RankID

• PercussiveDisengagingKeyActionNoise_ChooseMIDINoteNumRandomly

• SustainingKeyActionNoise_RankID

• SustainingKeyActionNoise_ChooseMIDINoteNumberRandomly

If a ..._ChooseMIDINoteNumberRandomly setting is set to Y then each key will be attached to a random ‘pipe’ (noise sample) from the rank, otherwise the key’s MIDI note number will determine the ‘pipe’ to which it is attached.

For some examples of all of these things, see the ExampleCustomOrgan5-StAnnes-WithBasicGUIAndNoises example custom organ definition file.

You can alternatively implement any of these types or noise, or more complex cases, by creating additional entries in the StopRank table with the appropriate action types. However, the above settings are intended to make it as easy as possible to handle common requirements, avoiding the need for an inelegant number of entries in the StopRank table.




Creating your own custom display styles and images A control style is a set of images that can be used to display any stop, coupler, tremulant, piston, label, static image object or swell pedal.

As covered above, a standard ready-made library of styles can be found in the ‘example custom organ 2' custom organ definition, ready to copy and paste into your own custom organ definition file. However it is also possible to use your own images by creating entries in the CustomDisplayControlStyle and/or CustomDisplayKeyboardStyle tables.

Image files can be stored in .png, .bmp, .tiff or .jpg formats and must be located within an installation package folder (see below), from which they can be referenced. All images that will be used to display different states of a given control, need to be listed together as ‘stages’ for the style in the CustomDisplayControlStyle table, and they must all have the same size in pixels. The Image_Stage00_ImageFilename setting defines the image to be used for the ‘off’ state for switches (stops, couplers, pistons, etc.) and expression pedals. Image_Stage01_ImageFilename defines that for the ‘on’ state for switches. For expression pedals, up to sixteen stages can be specified, and Hauptwerk will map the number specified across the full possible range of expression pedal positions. For labels and other static image objects, only the Image_Stage00_ImageFilename setting is used. A mask may optionally be specified for a control style (applying to all stages). In a mask, white indicates transparency, black opacity. (Semi-)transparent PNG files are also supported directly, requiring no separate mask file, and are thus the recommended format.

Sets of keyboard key images may be defined using the CustomDisplayKeyboardStyle table. As with control images, a mask may optionally specified for each key shape.

To use a custom image file for the background of a virtual console display page, its filename and installation package are simply specified directly in its CustomDisplayPage entry.

Please note that all entries in the display style tables cause images to load into memory, and thus it is best to eliminate unnecessary entries when you have finished working on an organ definition in order to save memory and (slightly) minimize organ loading time.

Images files are stored within the sample set data cache (covered later).




Samples and installation packages Any organ definition is dependent upon the samples and other data it uses being installed upon the user's computer, and at the required version. This is particularly important for the Custom Organ Design Module, since it will often be used to combine ranks from various sample sets, and any organ definition files created with it may be distributed to other users who may or may not have all of those sample sets.

Hauptwerk thus considers sample set data (of all types except for the organ definition database itself, i.e. audio samples, tremulant waveform (LFO shape) samples, images and organ information files) to be contained within discrete installation packages, being conceptually bundles of sample set data which are installed and managed as units by Hauptwerk.

Each such installation package has a globally-unique identifier code which is allocated upon request to sample set developers from a central pool, a version, and supplier information, all defined in a file called the package definition file with filename extension .InstallationPackageDefinition_Hauptwerk_xml, located in the root of the folder containing the installation package data, termed the installation package folder.

Each organ definition references data (samples, images, etc.) via its installation package code, and lists the installation packages upon which it is dependent, together with the versions of those packages that are required.

When a user loads an organ definition file, Hauptwerk first checks that the required packages are installed and are at an appropriate version. If they are not, a message is given to the user, detailing the supplier of the package who should be contacted to obtain it (which may be subject to licensing and require purchasing). If all package prerequisites are met, Hauptwerk automatically constructs the full file paths to files according to the installation packages within which they are contained. File paths are always specified relative to the root of the installation package folder.

Hauptwerk handles installation and upgrade of installation packages natively, and any data within installation packages must never be edited manually except during the initial creation of a sample set (which is the subject of the separate guide: Creating Sample Sets for Hauptwerk).

If it is wished that the data within an installation package be edited, and the license from the original creator of the sample set allows it, then a new installation package should first be created, using a unique package identifier from the 'user' range (see below), and any references to the package should be updated accordingly in the organ or custom organ definition file. In this way, should the organ or custom organ definition file be shared with other users, Hauptwerk's installation package management system will continue to work properly, ensuring that the correct data are installed and that the original sample set is not broken for other users of the original sample set.

For your own personal use, please create packages with IDs in the ‘user’ range 800000 to 899999. If you wish to make a sample set available publicly, please contact Milan Digital Audio to be allocated a unique ID for you installation package (there is no charge for the service), and consult the Creating Sample Set for Hauptwerk guide for full details about how to format the package for Hauptwerk’s component installer.

Image files also may only exist in installation packages, and must be treated in the same way as samples with regard to their IDs and packaging for public distribution.




Installation package compatibility with the module Not all sample set samples are necessarily compatible with the Custom Organ Design Module, since some additional requirements are placed upon them. For example, some sample sets may use layered samples, which are not currently supported by the module. Any compatible ranks of pipe samples will usually be listed in the package definition file in the CustomOrganRank table, and sets of tremulant waveform (LFO shape) samples in the CustomOrganTremulantWaveformSet table. Hauptwerk's XML file format is covered later with reference to the custom organ definition file format. The format is the same for both files, except that different tables are allowed and the file has different headers to identify its contents.

The compatibility requirements are covered fully in the separate Creating Sample Sets for Hauptwerk guide. They are summarized here for reference:

• All pipe sample files must have a names of the form 036-C.wav, 037-C#.wav, 038-D.wav, ... (or with .hbw filename extensions) according to the MIDI note number and name of the keyboard key from which they would normally sound when played

at unison pitch (i.e. with no explicit re-pitching). For unified (theatre) organs, the name would normally be set according to the note to which the sample would be attached when played at 8' pitch.

• Sustaining pipe sample files must either have the start of the (primary) release samples identified within the main pipe sample file by a marker (recommended in most cases for simplicity), or the release samples must be stored in separate files with

the same names as the main attack/sustain sample but located in a separate folder.

• All main attack/sustain pipe sample files for a given rank must be contained within the same folder in the relevant installation package folder; one folder should be used for the attack/sustain samples for each rank. If the primary releases are stored in separate samples, then they too must all be located in a single folder for the rank, and it must be within the same installation package as the attack/sustain samples for that rank.

• If additional (multiple) release samples are used, then each set must be located in a separate single folder for the rank, and it must be within the same installation package as the attack/sustain samples for that rank.

• All pipe samples must either have their exact pitches detected and stored in the sampler chunks within the sample files (recommended), or be re-tuned perfectly to concert pitch and equal temperament. The pitch may not be specified 'manually' in

the organ database for a sample.

• Tremulant waveform samples must have names of the form: 060-C-TremulantPitchAndFundamentalAmplitudeWaveform.wav and 060-C-TremulantThirdHarmonicAmplitudeWaveform.wav (or with .hbw filename extensions) according to the MIDI note number of the keyboard key for the pipe which would normally sound when played at unison pitch and to which they are to be assigned.

• Tremulant waveform samples for a given rank must all be located within a single folder (although a rank's tremulant waveform samples can be assigned to more than one pipe rank by the user).

• Tremulant waveform samples must have their exact pitches in Hertz saved in the sampler chunk in the samples, pre-multiplied by 128 (since it is not possible to store a pitch value of less than about 8 Hz in a WAV file).

• All tremulant waveform samples must have at least 10 ms before the start of their loop and the loop must be at least 10 ms in length.

• Although not mandatory, it is recommended that an additional release sample marker is included in the release sample (region) for any ambient ('wet') samples at the point at which the sound starts to decay. This allows Hauptwerk's automatic reverberation tail truncation functionality to work optimally, allowing ambient samples to be played either 'wet' or 'dry' and combined with ranks from different organs, or played at non-unison pitches with the release samples being adjusted automatically to an appropriate length for the playback pitch.

These requirements are made so that the user of the custom organ design module does not need to specify filenames and parameters for every pipe or sample.

Determining the sample settings for pipe and tremulant waveform samples for the Rank table If you are using samples from a third-party sample set in your custom organ definition, you can usually find the values you need for the Samples_... and most of the Trem_... settings on the Rank table by looking in the installation package definition file at the contents of the CustomOrganRank and CustomOrganTremulantWaveform set tables respectively.

For example, to see the settings you would need to use in the Rank table if you wanted to use some samples from the St. Anne’s, Moseley sample set, open the PackageID000010.InstallationPackageDefinition_Hauptwerk_xml file from the 000010 folder in the OrganInstallationPackages folder in the HauptwerkSampleSetsAndComponents folder using a text or XML editor.




Wet and dry samples and the reverb tail truncation functionality In general, pipe samples recorded from different organs can only be combined effectively if they were recorded 'dry' (without room ambience or reverberation), since the differences in room acoustics would otherwise be obvious when they were played together.

However, Hauptwerk also includes a feature whereby release samples containing room ambience can automatically be trimmed and shaped to model the decay of pipes recorded 'dry' (without room ambience). Parameters can be set for each rank in the custom organ definition database controlling its operation and the user is able to override those parameters when adjusting the voicing of a layer. Thus the user is able to select to load all or part of an organ with its full release samples or with those samples truncated to model dry recordings.

A shaped fade-out is used, of a length determined by the layer or voicing parameters, and adjusted automatically for the pipe frequency (since it takes longer for a speaking bass pipe to fall silent than a treble pipe). The fade is designed so that, as far as possible, the initial transients of the release are preserved, whilst the decay is truncated to model the shape of the natural decay of a pipe recorded dry for the appropriate pitch.

This makes it feasible to combine semi-dry ranks from various sample sets fairly effectively, significantly reducing the effects of any differences in acoustics which would otherwise render their combination impossible. Within the Custom Organ Design Module,

it is also possible to assign ranks to be played at pitches other than that at which the samples were recorded without the release samples becoming unnaturally long or short.

Of course simply shaping the releases does not provide a perfect model of real dry recordings, especially since the room acoustics affect the frequency response of the samples themselves, and the shapes of their attacks.




Filenames and paths Note that Hauptwerk is a multi-platform application, and that filenames are handled slightly differently on different platforms. On UNIX-based systems, such as Mac OS X, folder levels are separated by a '/' character, whereas on Windows systems, the separator is a '\' character. Either character may be used in path references in the organ definition database and elsewhere in Hauptwerk; Hauptwerk will perform the translation automatically for the system on which it is running.

However, filenames and paths may be case-sensitive on UNIX-based systems, such as Mac OS X, while Windows systems are not. To ensure compatibility across all supported Hauptwerk platforms, the case of filename and path references in the organ and custom organ definition databases must match that of the files and folders exactly. Hauptwerk does not perform automatic translation in this case.

Also, where the format of file and folder names or file extensions is specified in subsequent sections, the case must match that specified exactly, otherwise an organ might not function on Mac OS X.

Due to the different ways in which the various file systems work you should avoid using any characters in filenames or paths which are not present in the standard 7-bit American ANSI character set. For simplicity, it is strongly recommended that only the following characters be used:'A'-'Z', 'a'-'z', '0'-'9', '-', '_'. The space character is generally best avoided, and the '.' character should only be used in file extensions as specified for each file type. Regional characters, such as those with umlauts or cedillas might prevent an organ from loading on computers in some parts of the world.




Globally-unique organ identifiers and making organ definitions available to others Each organ is identified internally within Hauptwerk by a six digit globally-unique identifier, the organ ID. This identifier is used by Hauptwerk to associate all organs-specific settings and cached sample set data with the organ.

If two organ definition files with the same organ ID were ever to be installed on the sample computer, then the settings and sample data from one would overwrite those of the other, with disastrous results for the user. To avoid this possibility, the organ ID is allocated upon request to Milan Digital Audio from a central list.

However, a special exception is made for the Custom Organ Design Module so that its users are able to create custom specifications for their own personal use with the minimum of fuss. The unique organ ID for any custom organ must lie within the special reserved range of 800000 to 899999.

If you receive a custom organ definition file from another user then you must first open it and ensure that the organ ID within the range 800000 to 899999 is unique amongst those that are present on your computer.

If you use the Custom Organ Design Module to generate a native Hauptwerk organ definition file that you wish to supply publicly as part of a sample set, then you need to open the generated native organ definition file (with an extension .Organ_Hauptwerk_xml) and change the organ ID to a unique value that Milan Digital Audio has allocated to you for it. Please simply contact us to request allocation of such a value if you need it. There is no charge for the service. No other edits are necessary to a generated organ definition file to make it suitable for public distribution as part of a sample set.




The custom organ definition file XML format The custom organ definition files must have filename extensions of .CustomOrgan_Hauptwerk_xml, and be located in the CustomOrganDefinitions folder within the HauptwerkUserData folder, the location of which is determined during the original installation of Hauptwerk.

They may be edited directly in any text editor, such as Windows' Notepad, or UltraEdit (the latter is recommended and is available for a very reasonable cost from http://www.ultraedit.com/), or using a dedicated XML editor program, such as the excellent freeware XML Marker (http://www.symbolclick.com/).

XML is a simple format for storing and exchanging structured data. Data are enclosed within 'tags', which may also contain further 'sub-tags'. An enclosing pair of tags take the following form:

<tag>data</tag>

Here tag is the name of the tag, and data is a set of data enclosed by the tags. A tag may also have attributes. In the following example ObjectList is the tag, ObjectType is an attribute of the ObjectList tag, CustomDisplayPage is its value, and the ellipsis shows the location of the data set enclosed by the ObjectList tag:

<ObjectList ObjectType="CustomDisplayPage">...</ObjectList>

The following example shows how tags are nested within other tags, with the attributes (table fields) belonging to the object (table row) that encloses them, and the object (table row) belonging to the object list (table) that encloses them:

<ObjectList ObjectType="customdisplaypage">

<customdisplaypage>

<DisplayPageID>1</DisplayPageID>

<Name>Console</Name>

<BackgroundImageFilename>HauptwerkStandardImages/SeamlessBackgrounds-WoodPanelling-DarkCherry.png</BackgroundImageFilename>

<BackgroundImageFileInstallationPackageID>1</BackgroundImageFileInstallationPackageID>

</customdisplaypage>

<customdisplaypage>


<Name>Left Jamb</Name>




<customdisplaypage>


<Name>Right Jamb</Name>




</ObjectList>

The custom organ definition file must have the following opening tags immediately at the start of the file:

<?xml version="1.0" encoding="UTF-8"?>

<Hauptwerk FileFormat="CustomOrgan" FileFormatVersion="4.00">

… with the corresponding closing tag immediately at the end:

</Hauptwerk>

All of the data lying between are organized into object lists, objects and object attributes as illustrated in the example above. These object lists, objects and object attributes are generally referred to as tables, table rows and table fields in the remainder of this document, since they can be thought of as being a representation of two-dimensional tables of data. The structure of each table is described later in this guide.

Note that, for attributes which are not mandatory, the absence of a value should be denoted using the following format:




<ObjectList ObjectType="division">

<division>

...

<WindModel_WindchestPressureDropPctAtMaxLoad></WindModel_WindchestPressureDropPctAtMaxLoad>

...

</division>

</ObjectList>

Indentation and other 'white space' is ignored in the file unless it is within a quoted attribute value or field value. Certain 'special' characters, which are used to define the structure of an XML file must be represented by 'escape' sequences when they are used in data or attribute names in XML, as in HTML:

Character Escape sequence

'<' (less than sign) <

'>' (greater than sign) >

'&' (ampersand) &

'"' (double-quote) "

Other characters can be embedded as normal, provided they are encoded correctly within the specified XML character set (for example UTF-8).

As an example, the field value 'GT & PED PISTONS COUPLED' would be represented as follows:

<Name>GT & PED PISTONS COUPLED</Name>

The recommended character encoding (the actual byte values used to store each character) in the file is UTF-8, a 'universal' character encoding which can represent almost all characters from around the world. In general, this is only relevant if any characters other than the standard American (ANSI) characters are used; characters with umlauts, for example. The UltraEdit text edit allows the encoding of a text file to set to UTF-8, so that any characters can be used safely. However, Windows' Notepad is less easy to work with for UTF-8 text files.

Note that dedicated XML editors, such as the freeware XML Marker, can be used to handle character encodings, escape sequences and tags etc. natively. The single biggest benefit of XML as a format is that it is a widely-accepted standard, and there are many existing third-party tools that can read, write and manipulate it.




The sample set data cache When Hauptwerk first loads an organ, all signal processing that does not need to happen in real-time is performed on the audio samples, and the resulting samples are saved into its internal 'sample set data cache'. Image files are also stored within the cache to allow faster subsequent loading. The files within the sample set data cache cannot be edited.

Certain changes to Hauptwerk's user configuration (especially audio routing) require the samples cached for a given organ to be regenerated. Hauptwerk normally handles such regeneration automatically. However, when the design of an organ is adjusted, either within a full organ definition file or a custom organ definition file, it may or may not be necessary for the sample set data cache to be regenerated, depending on the nature of the change. For example, the addition of a pipe rank or a change to an image file would require the sample cache to be regenerated to reflect the change, but the addition of a coupler would not.

By default, Hauptwerk always regenerates the sample set data cache when a custom organ definition file is loaded, since it has no means to know the nature of any changes in its design that may have occurred. Since regenerating the cache is rather slow, an additional option is available when loading the file which allows cache regeneration to be skipped. This option must only be chosen when it is absolutely certain that no changes have been made to the ranks (or usually image files) listed in the custom organ definition. However, a further option allows images to be re-loaded from their source (non-cached) files, even when the sample data are loaded from the cache. This allows for fast testing of image and screen layout changes.




Organ-specific configuration, voicing and combinations Similarly, the organ-specific configuration and user voicing stored for the organ might no longer be valid following a change to the design of a custom organ. By default, any such existing configuration is cleared entirely when a custom organ definition file is loaded (unlike a full organ definition file).

However, further options are available when loading the custom organ to override this behavior, retaining various parts of the organ-specific configuration and user voicing, should it be certain that no changes have been made which affect the relevant parts of the configuration.

When loading a custom organ using the Design tools | Load custom organ … menu option the Load Organ Design Options screen is always shown to you for this purpose, allowing you to tell Hauptwerk when changes have been made in the organ definition that would necessitate resetting its organ-specific voicing or configuration.

The Custom Organ Design Module is designed to preserve existing user voicing if a rank is added or removed, provided that the IDs of the remaining ranks are not changed. It also preserves existing organ-specific MIDI configuration for virtual objects when virtual keyboards, stops, couplers, tremulants, pistons and swell boxes are added or removed, again providing that those that remain are not assigned new IDs (since it identifies each type of object by its ID). General and divisional combinations, as well as

combination stepper frames, stored in combination files also remain valid in these circumstances.




Part 2: Tables in the custom organ definition database

Field data types The data types are as follows:

Data type Description

ID A whole number in the range 1 - 999999 used to identify a record in a table, so that it can be referenced from other tables.

GUID A whole number in the range 1 - 999999 which has been allocated by Hauptwerk's author from a central pool to ensure that it identifies the record or object uniquely across all computers running Hauptwerk.

Function code A whole number in the range 1 - 999999 which can only take specific values, with each of those values defining a fixed object the existence of which is defined by including a record with the function code as its primary key value in the appropriate table. The code also serves as an ID, in that it is used by other tables to refer uniquely to the record.

Fixed code A whole number which can take one of several values from a fixed list, with each value having a distinct fixed meaning.

Integer A whole number, the allowed range of which may vary according to the attribute.

Float A fractional number, the allowed range of which may vary according to the attribute.

Boolean Y or N, representing yes/no or true/false.

String A sequence of text characters, with the range value giving the maximum allowed length. Unless specified otherwise, any characters from anywhere in the world can be used as long as they exist in the 'universal' UTF-8 character set, and the custom organ definition file is saved correctly, encoded with that character encoding.

Filename A sequence of text characters used to define a filename or file path on the user's computer. All filenames and paths are specified relative to a given root point, which Hauptwerk handles provides automatically; never as absolute paths. Filename fields should contain only the characters 'a' - 'z', 'A' - 'Z', '0' - '9', '-' and '_' and are case-sensitive on some operating systems, so their case must be specified correctly, otherwise a custom organ may fail to work on those operating systems.

The Key column in the tables below indicate whether the value must be unique (PK for primary key or UK for unique key). The References column indicates whether a the value must specify another existing object, and which table and attribute it refers to for that object if so. The New column indicates whether the attribute was added for a Hauptwerk version after 2.0.0, and which version number if so. For string and filename attributes, the Range column in the tables below give the maximum length in characters.




Table: RequiredInstallationPackage The RequiredInstallationPackage table lists all installation packages from which audio or tremulant samples (used for ranks), image files (used for custom display control or keyboard styles) or HTML/PDF files (used for the ‘organ information’ function) will be referenced. It is used to ensure that the user has the necessary packages installed, and that they are at appropriate versions. Packages should not be listed unless they are actually required, since they would then add unnecessarily to the prerequisites for a user and very slightly increase organ loading time.

Attribute Type Range Req'd? Key New? References Description

InstallationPackageID GUID 1 - 999999

Y PK The fixed, globally-unique package ID of the installation package whose data are to be referenced. The package would normally have been supplied by a third-party sample set creator, with a fixed, allocated ID. Hauptwerk will validate that the user has the required package installed, giving a message indicating that he or she must install the package if not, and giving the supplier ID as information so that the user can contact the supplier to obtain it.

Name String 64 Y UK The full name of the package. It is used when displaying error messages to the user to indicate that the package is missing or at too low a version. This value can be copied from the package definition file location in the root of the installation package folder.

ShortName String 32 Y UK The short name of the package. It is used when displaying error messages to the user to indicate that the package is missing or at too low a version. This value can be copied from the package definition file location in the root of the installation package folder.

PackageSupplierID GUID 1 - 999999

Y The fixed, globally-unique ID allocated to the supplier of the package, so that they may be contacted if the package is not installed by the user. This value can be copied from the package definition file location in the root of the installation package folder.

SupplierName String 64 Y The name of the supplier. It is used when displaying error messages to the user to indicate that the package is missing or at too low a version. This value can be copied from the package definition file location in the root of the installation package folder.

MinimumPackageVersion Float 0.001 -

9999.9

Y The minimum version of the package that is compatible with the custom organ. Note that upward compatibility is a requirement for installation

packages (if a change is required by the package creator which would render it incompatible with previous versions, then a new distinct package must be created, with a new package ID). Thus it is not necessary to specify a maximum package version.




Table: CustomDisplayPage The CustomDisplayPage table is needed if and only if you wish to create your own graphical interface for the organ. It defines the virtual console’s custom display page tabs, their names and the background images used for them. The four other default standard display pages may optionally be disabled via the _General table.

A maximum of 4 rows can be given for this table.


DisplayPageID ID 1 - 4 Y PK 3.0.0 Uniquely identifies the page number, and also determines the left-right order on which the pages appear on the virtual console.

Name String 16 Y UK 3.0.0 The text that will be shown on the display page’s tab at the top of the virtual console screen.

BackgroundImageFilename Filename 255 Y 3.0.0 The filename and path to the image to be used for the background for the display page, relative to the installation package folder.

BackgroundImageFileInstallationPackageID ID 1 - 999999

Y 3.0.0 RequiredInstallationPackage . InstallationPackageID

The installation package in which the background image file(s) are located.

AlternateLayout1_Include Boolean Y/N Must be specified if and only if _General.CustomDisplay_AlternateLayout1_ConsoleWidthPixels is specified

4.0.0 If the custom organ definition (_General table) specifies dimensions for an alternate layout (orientation/aspect ratio) then this specifies whether the page includes it. If (and only if) so, all controls displayed on this page must also be included on the alternate page layout.

See the 'The custom display functionality' section of this guide for details on the alternate layout functionality.

AlternateLayout1_BackgroundImageFilename Filename 255 Must be specified if and only if AlternateLayout1_Include is set to Y

4.0.0 If this display page includes the alternate layout then this specifies the filename and path to the image to be used for the background for the display page, relative to the installation package folder.




Table: CustomDisplayControlStyle The CustomDisplayControlStyle table is needed if and only if you wish to create your own graphical interface for the organ. It allows you to define a library of visual styles that can be used for your controls (stops, couplers, tremulants, short-cut pistons, swell pedals, combination pistons and labels) on custom display pages. A ready-made standard library of images and styles is supplied with Hauptwerk. To use it simply copy and paste the contents of the CustomDisplayControlStyle table from the ‘example custom organ 2' custom organ definition into your own custom organ definition. You can also add your own if you wish.


ControlStyleID ID 1 - 999999

Y PK 3.0.0 A unique ID to identify the style when referring to it from other tables.

Name String 22 Y UK 3.0.0 A unique name for the style. Does not affect the appearance or behavior of the resulting virtual organ, but exists to help you to identify the style in a user-friendly way.

ImageFileInstallationPackageID ID 1 - 999999


Identifies the installation package in which all of its image files are located.

ClickableAreaPosPixelsRelativeToTopLeftOfControl_LeftX

Integer 0 - 8192

N 3.0.0 Optionally defines a ‘clickable area’ for the style, relative to the top-left of the controls to which it is applied. If these values are specified and the control is other than a static image object, the clicking in the area defined by these parameters will operate the control.

ClickableAreaPosPixelsRelativeToTopLeftOfControl_TopY

Integer 0 - 8192


ClickableAreaPosPixelsRelativeToTopLeftOfControl_RightX

Integer 0 - 8192


ClickableAreaPosPixelsRelativeToTopLeftOfControl_Bottom

Integer 0 - 8192


Image_TransparencyMaskFilename Filename 96 N 3.0.0 The style can optionally have transparency. If so, use this setting to specify the path and filename of an image file (relative to the installation package folder) to use as a mask. White areas represent transparency, black opacity.

Image_NumberOfStages Integer 1 - 16 Y 3.0.0 The number of images that can be used to display different states for controls to which the style is applied. To be applied to switch controls (stops, couplers, tremulants, short-cut pistons and other pistons) the style needs at least 2 stages. Stage 0 will be used for the ‘off’ image, and stage 1 for the ‘on’. To be applied to a static image object or label, the style needs at least one stage, and (only) the stage 0 image will always be used. For styles that will be applied to enclosures, up to 16 stages can be specified and they will be mapped uniformly across the possible range of enclosure positions.

Image_Stage00_ImageFilename Filename 96 Y 3.0.0 The filename/path for this image stage, relative to the installation package folder.

Image_Stage01_ImageFilename Filename 96 N 3.0.0 The filename/path for this image stage, relative to the installation package folder.















Text_HasText Boolean Y/N Y 3.0.0 A style may optionally also be able to display text. If so, any text that is specified for a control that uses the style will be displayed according to these settings and on top of the image.

Text_Font_FaceName String 32 Must be specified if and only if Text_HasText is Y

3.0.0 If the style can display text, the font name. Please make sure that you only use fonts that exist on both Windows and Apple Mac OS X, otherwise some end-users might not see your organ displayed correctly. Arial, Arial Bold, Comic Sans MS, Courier New, Georgia, Trebuchet MS, Verdana and Times New Roman (amongst others) are common to both Windows and OS X.





Text_Font_HeightPixels Integer 6 - 64 Must be specified if and only if Text_HasText is Y

3.0.0 If the style can display text, the height of the font in pixels.

Text_Font_WeightCode Integer 1 - 3 Must be specified if and only if Text_HasText is Y

3.0.0 If the style can display text, the weight of the font:

1. Light.

2. Normal.

3. Bold.

Text_Font_IsItalic Boolean Y/N Must be specified if and only if Text_HasText is Y

3.0.0 If the style can display text, whether the font should be italic.

Text_Font_IsUnderlined Boolean Y/N Must be specified if and only if Text_HasText is Y

3.0.0 If the style can display text, whether the font should be underlined.

Text_RGBColour_Red Integer 0 - 255 Must be specified if and only if Text_HasText is Y

3.0.0 If the style can display text, the RGB color component of the font.

Text_RGBColour_Green Integer 0 - 255 Must be specified if and only if Text_HasText is Y


Text_RGBColour_Blue Integer 0 - 255 Must be specified if and only if Text_HasText is Y


Text_BoundingBoxPosPixelsRelToTopLeftOfImage_LeftX

Integer 0 - 8192

Must be specified if and only if Text_HasText is Y

3.0.0 If the style can display text, the position of its bounding box relative to the top-left of the control to which it will be applied. The control’s text will be centered vertically and horizontally within this box and word-wrapped.

Text_BoundingBoxPosPixelsRelToTopLeftOfImage_TopY

Integer 0 - 8192



Text_BoundingBoxPosPixelsRelToTopLeftOfIm

age_RightX

Integer 0 -

8192

Must be specified if and

only if Text_HasText is Y

3.0.0 If the style can display text, the position of its bounding box relative to the top-left of the control to

which it will be applied. The control’s text will be centered vertically and horizontally within this box and word-wrapped.

Text_BoundingBoxPosPixelsRelToTopLeftOfImage_Bottom

Integer 0 - 8192






Table: CustomDisplayKeyboardStyle The CustomDisplayKeyboardStyle table is needed if and only if you wish to create your own graphical interface for the organ. It allows you to define a library of visual styles that can be used for your virtual keyboards (manuals and pedalboards) on custom display pages. A ready-made standard library of images and styles is supplied with Hauptwerk. To use it simply copy and paste the contents of the CustomDisplayKeyboardStyle table from the ‘example custom organ 2' custom organ definition into your own custom organ definition. You can also add your own if you wish.

An ‘up’ and ‘down’ image file must be specified for each key shape possible on a (modern) keyboard, and a mask image may also optionally be specified for each shape. In a mask image, white areas represent transparency, black opacity.


KeyboardStyleID ID 1 - 999999

Y PK 3.0.0 A unique ID to identify the style when referring to it from other tables.

Name String 16 Y UK 3.0.0 A unique name for the style. Does not affect the appearance or behavior of the resulting virtual organ, but exists to help you to identify the style in a user-friendly way.

ImageFileInstallationPackageID ID 1 - 999999


Identifies the installation package in which all of its image files are located.

KeyShapeImageFilename_CF_KeyDown

Filename 96 Y 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_CF_KeyUp


KeyShapeImageFilename_CF_Mask Filename 96 N 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_D_KeyDown


KeyShapeImageFilename_D_KeyUp Filename 96 Y 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_D_Mask Filename 96 N 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_EB_KeyDown


KeyShapeImageFilename_EB_KeyUp


KeyShapeImageFilename_EB_Mask Filename 96 N 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_G_KeyDown


KeyShapeImageFilename_G_KeyUp Filename 96 Y 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_G_Mask Filename 96 N 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_A_KeyDown


KeyShapeImageFilename_A_KeyUp Filename 96 Y 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_A_Mask Filename 96 N 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_Sharp_KeyDown


KeyShapeImageFilename_Sharp_KeyUp


KeyShapeImageFilename_Sharp_Mask

Filename 96 N 3.0.0 Image filename and path relative to the installation package folder.

KeyShapeImageFilename_WholeNatural_KeyDown


KeyShapeImageFilename_WholeNatural_KeyUp


KeyShapeImageFilename_WholeNatural_Mask


KeyShapeImageFilename_FirstKeyDA_KeyDown


KeyShapeImageFilename_FirstKeyDA_KeyUp


KeyShapeImageFilename_FirstKeyDA_Mask


KeyShapeImageFilename_FirstKeyG Filename 96 Y 3.0.0 Image filename and path relative to the installation package folder.





_KeyDown

KeyShapeImageFilename_FirstKeyG_KeyUp


KeyShapeImageFilename_FirstKeyG_Mask


KeyShapeImageFilename_LastKeyDG_KeyDown


KeyShapeImageFilename_LastKeyDG_KeyUp


KeyShapeImageFilename_LastKeyDG_Mask


KeyShapeImageFilename_LastKeyA_KeyDown


KeyShapeImageFilename_LastKeyA_KeyUp


KeyShapeImageFilename_LastKeyA

_Mask


HorizSpacingPixels_LeftOfNaturalFromLeftOfNatural

Integer 0 - 8192 Y 3.0.0 These settings specify the horizontal distance in pixels from the left of one key shape to the left of the preceding key shape.

HorizSpacingPixels_LeftOfCFSharpFromLeftOfCF


HorizSpacingPixels_LeftOfDASharpFromLeftOfDA


HorizSpacingPixels_LeftOfGSharpFromLeftOfG


HorizSpacingPixels_LeftOfDGFromLeftOfCFSharp


HorizSpacingPixels_LeftOfEBFromLeftOfDASharp


HorizSpacingPixels_LeftOfAFromLeftOfGSharp


ClickableAreaPosPixelsRelativeToTopLeftOfKey_Natural_LeftX

Integer 0 - 8192 Y 3.0.0 These settings specify the rectangular area (if any) that the user will be able to click in to press a natural key. The area is specified in pixels from the top-left of the key.

ClickableAreaPosPixelsRelativeToTopLeftOfKey_Natural_TopY


ClickableAreaPosPixelsRelativeToTopLeftOfKey_Natural_RightX


ClickableAreaPosPixelsRelativeToTopLeftOfKey_Natural_BottomY


ClickableAreaPosPixelsRelativeToTopLeftOfKey_Sharp_LeftX

Integer 0 - 8192 Y 3.0.0 These settings specify the rectangular area (if any) that the user will be able to click in to press a sharp key. The area is specified in pixels from the top-left of the key.

ClickableAreaPosPixelsRelativeToTopLeftOfKey_Sharp_TopY


ClickableAreaPosPixelsRelativeToTopLeftOfKey_Sharp_RightX


ClickableAreaPosPixelsRelativeToTopLeftOfKey_Sharp_BottomY





Table: _General There must be one and only one _General object in the database. Its attributes describe properties of the organ as a whole.


Sys_ObjectID ID 1 - 1 Y PK Used internally by Hauptwerk to guarantee that there is exactly one _General object. Its value must always be 1.

UniqueOrganID GUID 800000 - 899999

Y Identifies the organ uniquely amongst any Hauptwerk installation for any user. See preceding section covering how this value should be set.

Name String 64 Y The name that is displayed in Hauptwerk's title bar for the organ.

ShortName String 16 Y The name that is displayed on Hauptwerk's status LCD panel when the organ is loaded.

OrganDefinitionFilenameExcludingExtension

Filename 64 Y The filename of the full organ definition file that will be generated. It should be globally unique, so that no other organ definition file is overwritten, descriptive, and adhere to the rules for characters allowed in filenames.

CurrentHauptwerkVersion Float >= 3.0 Y The version of Hauptwerk for which the file was created. Hauptwerk uses this value to ensure that a custom organ definition file is compatible with the version of Hauptwerk installed by a user, whether the user needs to upgrade Hauptwerk or to migrate the custom organ definition file to a later format.

SampleRateCode Fixed code

Valid sample rate code

Y The sample rate that will be used by Hauptwerk for all audio output from the organ. It is not necessary that the value corresponds to the sample rate of all samples, since sample rate conversion happens automatically when required, but it should be set to the highest sample rate commonly used by any samples used for the organ, so that the best possible audio quality is obtained. The valid codes are as follows:

1. 22050 Hertz.

2. 44100 Hertz.

3. 48000 Hertz.

4. 96000 Hertz.

VisualAppearanceCode Fixed code

1 - 1 Y Reserved for future use to allow the console screen appearance to selected from a range of styles. Must be set to 1 for now.

CustomOrganInfo_InstallationPackageID

ID 1 - 999999

N 3.0.0 RequiredInstallationPackage . InstallationPackageID

You may optionally specify a custom HTML or PDF file that Hauptwerk will show if the user selects Organ | Show organ information from the menu, as well as a demo MIDI file for the organ. To do either of those things, this value needs to specify the installation package in which the file(s) reside. If you leave these two settings blank Hauptwerk will display a standard generic information page when that menu function is selected and no MIDI demo will be loaded.

CustomOrganInfo_InfoFilename

Filename 255 Must be specified only if CustomOrganInfo_InstallationPackageID is not blank

3.0.0 You may optionally specify a custom HTML or PDF file that Hauptwerk will show if the user selects Organ | Show organ information from the menu. If so, this value gives the filename and path relative to the installation package folder. If you leave these two settings blank Hauptwerk will display a standard generic information page when that menu function is selected.

CustomOrganInfo_MIDIDemoFilename

Filename 255 Can be specified only if CustomOrganInfo_InstallationPackageID is not blank

4.0.0 You may optionally specify a MIDI file that Hauptwerk will load automatically into its native MIDI player as a demo for the organ whenever the user loads the organ. The MIDI file must use exactly the MIDI implementation that the native MIDI recorder/player uses (for example, you could use a MIDI file that you

saved from Hauptwerk's native MIDI recorder) and reside within the package specified by the CustomOrganInfo_InstallationPackageID setting. The MIDI recorder/player's MIDI implementation is fixed and designed so that MIDI files it records will play properly for any other users of the organ, with no dependencies on MIDI settings or combination sets.

CustomDisplay_ConsoleWidthPixels

Integer 1 – 8192 N

3.0.0 You can use these two settings to make the virtual console larger than the standard default size of 1012 x 640 pixels if required.

CustomDisplay_ConsoleHeightPixels

Integer 1 – 8192 N 3.0.0 You can use these two settings to make the virtual console larger than the standard default size of 1012 x 640 pixels if required.

CustomDisplay_AlternateLayout1_ConsoleWidthPixels

Integer 1 – 8192 N 4.0.0 Set this if you want to define an alternate screen layout size/orientation/aspect ratio.


CustomDisplay_AlternateLayout1_ConsoleHeightPixels

Integer 1 – 8192 N 4.0.0 Set this if you want to define an alternate screen layout size/orientation/aspect ratio.

CustomDisplay_EnableStdPages_Controls

Boolean Y/N N 3.0.0 You can use these four settings to disable the default standard generated virtual console display pages if you wish.

CustomDisplay_EnableStdPages_Keyboards






CustomDisplay_EnableStdPages_Wind


CustomDisplay_EnableStdPages_Enclosures


CustomDisplay_DefaultDisplayPageID

ID Valid display page code

N 3.0.0 CustomDisplayPage. DisplayPageID

If you have at least one custom display page you can use this setting to make one the default, which will then be selected the first time that the user loads the organ. Subsequently Hauptwerk remembers the user’s last-selected page.

CustomDisplay1_Generals_DisplayPageID



The CustomDisplay1_Generals_... attributes allow you to show up to 20 general combination pistons on one of your own custom display pages. This specifies the page.

CustomDisplay1_Generals_NumberDisplayed

Integer 0 - 20 Must be specified only if CustomDisplay1_Generals_DisplayPageID is not blank

3.0.0 The CustomDisplay1_Generals_... attributes allow you to show up to 20 general combination pistons on one of your own custom display pages. This specifies the number that you wish to display. 20 generals always exist, but you do not need to display all of them.

CustomDisplay1_Generals_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_Generals_DisplayPageID is not blank

3.0.0 CustomDisplayControlStyle. ControlStyleID

The CustomDisplay1_Generals_... attributes allow you to show up to 20 general combination pistons on one of your own custom display pages. This selects the control’s visual style from your library of control styles.

CustomDisplay1_Generals_FirstDisplayedPistonPos_X


3.0.0 The CustomDisplay1_Generals_... attributes allow you to show up to 20 general combination pistons on one of your own custom display pages. The pistons are displayed in a row (need not be horizontal) between the X, Y position of the first and the X, Y position of the last.

CustomDisplay1_Generals_FirstDisplayedPistonPos_Y



CustomDisplay1_Generals_LastDisplayedPistonPos_X



CustomDisplay1_Generals_LastDisplayedPistonPos_Y



CustomDisplay1_Generals_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_Generals_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay1_Generals_ControlStyleID.

CustomDisplay1_Generals_AltLayout1_FirstDisplayedPistonPos_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_Generals_DisplayPageID is not blank and that display page includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay1_Generals_FirstDisplayedPistonPos_X.

CustomDisplay1_Generals_AltLayout1_FirstDisplayedPistonPos_Y


4.0.0 Alternate layout equivalent of CustomDisplay1_Generals_FirstDisplayedPistonPos_Y.

CustomDisplay1_Generals_AltLayout1_LastDisplayedPistonPos_X


4.0.0 Alternate layout equivalent of CustomDisplay1_Generals_LastDisplayedPistonPos_X.

CustomDisplay1_Generals_AltLayout1_LastDisplayedPistonPos_Y


4.0.0 Alternate layout equivalent of CustomDisplay1_Generals_LastDisplayedPistonPos_Y.

CustomDisplay1_GeneralCancel_DisplayPageID



The CustomDisplay1_GeneralCancel_... attributes allow you to make the general cancel piston visible on one of your own custom display pages. This selects the page if so.

CustomDisplay1_GeneralCancel_Text

String 64 Must be specified only if CustomDisplay1_GeneralCancel_DisplayPageID is not blank

3.0.0 The CustomDisplay1_GeneralCancel_... attributes allow you to make the general cancel piston visible on one of your own custom display pages. This is the text that will be shown on the piston.

CustomDisplay1_GeneralCancel_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_GeneralCancel_DisplayPageID is not blank


The CustomDisplay1_GeneralCancel_... attributes allow you to make the general cancel piston visible on one of your own custom display pages. This selects the control’s visual style from your library of control styles.

CustomDisplay1_GeneralCanc

el_PosPixels_X

Integer 0 - 8192 Must be specified only if

CustomDisplay1_GeneralCancel_Display

3.0.0 The CustomDisplay1_GeneralCancel_... attributes allow you to make the general cancel piston visible on

one of your own custom display pages. This specifies the position.





PageID is not blank

CustomDisplay1_GeneralCancel_PosPixels_Y

Integer 0 - 8192 Must be specified only if CustomDisplay1_GeneralCancel_DisplayPageID is not blank

3.0.0 The CustomDisplay1_GeneralCancel_... attributes allow you to make the general cancel piston visible on one of your own custom display pages. This specifies the position.

CustomDisplay1_GeneralCancel_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_GeneralCancel_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay1_GeneralCancel_ControlStyleID.

CustomDisplay1_GeneralCancel_AltLayout1_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_GeneralCancel_DisplayPageID is not blank and that display page includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay1_GeneralCancel_PosPixels_X.

CustomDisplay1_GeneralCancel_AltLayout1_PosPixels_Y


4.0.0 Alternate layout equivalent of CustomDisplay1_GeneralCancel_PosPixels_Y.

CustomDisplay1_SetterSwitch_DisplayPageID



The CustomDisplay1_SetterSwitch_... attributes allow you to make the combination capture (setter) switch visible on one of your own custom display pages. This selects the page if so.

CustomDisplay1_SetterSwitch_Text

String 64 Must be specified only if CustomDisplay1_SetterSwitch_DisplayPageID is not blank

3.0.0 The CustomDisplay1_SetterSwitch_... attributes allow you to make the combination capture (setter) switch visible on one of your own custom display pages. This is the text that will be shown on the switch.

CustomDisplay1_SetterSwitch_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_SetterSwitch_DisplayPageID is not blank


The CustomDisplay1_SetterSwitch_... attributes allow you to make the combination capture (setter) switch visible on one of your own custom display pages. This selects the control’s visual style from your library of control styles.

CustomDisplay1_SetterSwitch_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_SetterSwitch_DisplayPageID is not blank

3.0.0 The CustomDisplay1_SetterSwitch_... attributes allow you to make the combination capture (setter) switch visible on one of your own custom display pages. This specifies the position.

CustomDisplay1_SetterSwitch_PosPixels_Y


3.0.0 The CustomDisplay1_SetterSwitch_... attributes allow you to make the combination capture (setter) switch visible on one of your own custom display pages. This specifies the position.

CustomDisplay1_SetterSwitch_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_SetterSwitch_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay1_SetterSwitch_ControlStyleID.

CustomDisplay1_SetterSwitch_AltLayout1_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_SetterSwitch_DisplayPageID is not blank and that display page

includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay1_SetterSwitch_PosPixels_X.

CustomDisplay1_SetterSwitch_AltLayout1_PosPixels_Y

Integer 0 - 8192 Must be specified only if CustomDisplay1_SetterSwitch_DisplayPageID is not blank and that display page includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay1_SetterSwitch_PosPixels_Y.

CustomDisplay2_Generals_DisplayPageID



The CustomDisplay2_... attributes perform exactly the same function as their CustomDisplay1_... counterparts (see above for descriptions), but allow objects optionally to appear on another custom display page simultaneously.

CustomDisplay2_Generals_NumberDisplayed


3.0.0 The CustomDisplay2_... attributes perform exactly the same function as their CustomDisplay1_... counterparts (see above for descriptions), but allow objects optionally to appear on another custom display page simultaneously.

CustomDisplay2_Generals_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_Generals_DisplayPageID is not blank



CustomDisplay2_Generals_FirstDisplayedPistonPos_X



CustomDisplay2_Generals_FirstDisplayedPistonPos_Y


3.0.0 The CustomDisplay2_... attributes perform exactly the same function as their CustomDisplay1_... counterparts (see above for descriptions), but allow objects optionally to appear on another custom display simultaneously.

CustomDisplay2_Generals_La

stDisplayedPistonPos_X

Integer 0 - 8192 Must be specified only if

CustomDisplay2_Generals_DisplayPageI

3.0.0 The CustomDisplay2_... attributes perform exactly the same function as their CustomDisplay1_...

counterparts (see above for descriptions), but allow objects optionally to appear on another custom





D is not blank display page simultaneously.

CustomDisplay2_Generals_LastDisplayedPistonPos_Y



CustomDisplay2_Generals_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_Generals_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay2_Generals_ControlStyleID.

CustomDisplay2_Generals_AltLayout1_FirstDisplayedPistonPos_X


4.0.0 Alternate layout equivalent of CustomDisplay2_Generals_FirstDisplayedPistonPos_X.

CustomDisplay2_Generals_AltLayout1_FirstDisplayedPistonPos_Y


4.0.0 Alternate layout equivalent of CustomDisplay2_Generals_FirstDisplayedPistonPos_Y.

CustomDisplay2_Generals_AltLayout1_LastDisplayedPistonPos_X


4.0.0 Alternate layout equivalent of CustomDisplay2_Generals_LastDisplayedPistonPos_X.

CustomDisplay2_Generals_AltLayout1_LastDisplayedPistonPos_Y


4.0.0 Alternate layout equivalent of CustomDisplay2_Generals_LastDisplayedPistonPos_Y.

CustomDisplay2_GeneralCancel_DisplayPageID




CustomDisplay2_GeneralCancel_Text

String 64 Must be specified only if CustomDisplay2_GeneralCancel_DisplayPageID is not blank


CustomDisplay2_GeneralCancel_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_GeneralCancel_DisplayPageID is not blank



CustomDisplay2_GeneralCancel_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay2_GeneralCancel_DisplayPageID is not blank


CustomDisplay2_GeneralCancel_PosPixels_Y

Integer 0 - 8192 Must be specified only if CustomDisplay2_GeneralCancel_Display

PageID is not blank

3.0.0 The CustomDisplay2_... attributes perform exactly the same function as their CustomDisplay1_... counterparts (see above for descriptions), but allow objects optionally to appear on another custom

display page simultaneously.

CustomDisplay2_GeneralCancel_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_GeneralCancel_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay2_GeneralCancel_ControlStyleID.

CustomDisplay2_GeneralCancel_AltLayout1_PosPixels_X


4.0.0 Alternate layout equivalent of CustomDisplay2_GeneralCancel_PosPixels_X.

CustomDisplay2_GeneralCancel_AltLayout1_PosPixels_Y


4.0.0 Alternate layout equivalent of CustomDisplay2_GeneralCancel_PosPixels_Y.

CustomDisplay2_SetterSwitch_DisplayPageID




CustomDisplay2_SetterSwitch_Text

String 64 Must be specified only if CustomDisplay2_SetterSwitch_DisplayPageID is not blank


CustomDisplay2_SetterSwitch_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_SetterSwitch_DisplayPageID is not blank







CustomDisplay2_SetterSwitch_PosPixels_X



CustomDisplay2_SetterSwitch_PosPixels_Y



CustomDisplay2_SetterSwitch_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_SetterSwitch_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay2_SetterSwitch_ControlStyleID.

CustomDisplay2_SetterSwitch_AltLayout1_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay2_SetterSwitch_DisplayPageID is not blank and that display page includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay2_SetterSwitch_PosPixels_X.

CustomDisplay2_SetterSwitch_AltLayout1_PosPixels_Y

Integer 0 - 8192 Must be specified only if CustomDisplay2_SetterSwitch_DisplayP

ageID is not blank and that display page includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay2_SetterSwitch_PosPixels_Y.




Table: Division The Division table is central to the custom organ definition, and fulfills the roles of several tables in the full native organ definition format.

Conceptually a division is considered to be an organ keyboard together with the set of stops that can be played from it, the set of couplers that couple to it (e.g. the Swell to Great coupler belongs to the Great division, playing the Swell division when the keys of the Great manual are played), the set of tremulants that belong logically to it, the set of divisional combination objects storing the states of its stops, couplers and tremulants, and the wind supply system components used for its pipe ranks. A rank is associated with a division only to specify the source of its wind; ranks may be shared between any divisions to allow unification.

This table enumerates the divisions that are present on the organ. Keyboards, stop jambs and optionally wind model components are generated automatically for each listed division on the default standard display, unless that default display is disabled. The list of allowed divisions is fixed, detailed for the DivisionCode attribute below.

Please see the section An overview of the objects in a custom organ definition and characteristics of organs created with the Custom Organ Design Module for information on standard divisions (which have division codes 1 - 7) compared to non-standard divisions (with division codes 8 – 16).


DivisionCode Function code

Valid division code

Y PK The role of the division:

1. Standard division: Pedal.

2. Standard division: Manual 1 - Great, Hauptwerk, Grand Orgue or equivalent.

3. Standard division: Manual 2 - Swell, Schwellwerk, Recit Expressif, Accompaniment or equivalent.

4. Standard division: Manual 3 - Choir or equivalent.

5. Standard division: Manual 4 - Solo or equivalent.

6. Standard division: Manual 5 - Echo or equivalent.

7. Standard division: Manual 6 - miscellaneous. As with other standard divisions, this division may own stops, couplers, tremulants, etc. However, it is different to the other standard divisions in that its objects are not displayed on the standard default console display, due to lack of space.

8. Non-standard division. Has no divisional combinations or wind model components.









Name String 32 Y UK The name that is displayed for the keyboard, stop jambs, wind model and enclosure indicators on the standard default console display (if enabled), and presented to the user when configuring MIDI keyboards

ShortName String 5 Y UK Used to identify the keyboard for display on LCD status panels.

NumberOfKeys Integer 0 - 128 Y The number of keys available on the keyboard for the division.

MIDINoteNumOfFirstKey Integer 12 - 127 N 3.0.0 If specified the MIDI note number of the first key. The default is 36, which is the standard MIDI note number for the lowest C on a 61-note manual or on a modern pedalboard.

NumberOfKeyActionNodesIfDifferentFromNumberOfKeys

Integer 0 - 128 N 3.0.0 The ‘action nodes’ are the set of outputs to the pipe pallets, post-coupling. By default the same number and range of such action nodes are generated as for the keys. However, you can use these two settings to override that. For example you might want to do this if a division had octave or sub-octave couplers that allowed pipes to be played beyond the usual compass of the keys at the ends of the keyboard.

MIDINoteNumOfFirstKeyActionNodeIfDifferentFromFirstKey

Integer 0 - 127 N 3.0.0 The ‘action nodes’ are the set of outputs to the pipe pallets, post-coupling. By default the same number and range of such action nodes are generated as for the keys. However, you can use these two settings to override that. For example you might want to do this if a division had octave or sub-octave couplers that allowed pipes to be played beyond the usual compass of the keys at the ends of the keyboard.

AccessibleForMIDIInputAndOutput Boolean Y/N N 3.0.0 Determines whether the user will be able to connect MIDI keyboards to it, and use it for MIDI output. The default is Y. You would usually want to set this to N for special divisions that you create solely to implement complex internal couplers.

WindModel_EnableWindModel Boolean Y/N Y If Y, a wind weighted, parallel-rise reservoir is generated together with a wind-chest and all necessary connections, continuous controls, regulator valve, and console screen indicators on the standard default display (if enabled). The pressure is normally maintained at 6", with attached pipework causing the pressure to vary as the demand changes. Note that the reservoirs of each division are fed separately from the blower, so they do not interact in the Custom Organ Design Module. If set to N, the wind is supplied to all attached ranks from a constant 6" supply which remains absolutely static at all times.

WindModel_TotalResrvrAndWndchstVolMetresCubed

Float 0.001 - 99999.9

Must be specified if and only if WindModel_EnableWindModel

In general, a larger reservoir can absorb changes in demand with less affect on pressure, thus the volume affects the magnitude of any oscillations in pressure that occur when wind demand changes (due to oscillations of the mass placed on the bellows). About 1 m3 is a good starting point for a medium-sized division. The volume is





is set to Y interpreted as the volume when the reservoir bellows are extended for their normal working volume. 70% of the volume is allocated to the reservoir (with bellows normally extended) and the remainder to the wind-chest.

WindModel_AreaOfReservoirTableMetresSquared

Float 0.001 - 99999.9

Must be specified if and only if WindModel_EnableWindModel is set to Y

The size of the reservoir table (bellows top board) determines its mass (so that exactly 6" of wind is maintained) - decreasing the size of the table will increase the mass that will be added to it automatically by Hauptwerk. The area of the table thus determines it resonant frequency, and the frequency of any oscillations that will be observed in the wind pressure when demand changes. Approximately, the frequency is proportional to the square root of the area, so quadrupling the area would roughly double the resonant frequency. The constant of proportionality is approximately 4.1332907288696, so the resonant frequency in Hertz will be roughly 4.1332907288696 times the square root of this area.

WindModel_ResrvrBellowsPositiveDampingCoeff

Float 0.001 - 99999.9


This value determines the amount of damping applied to the reservoir bellows, and thus how quickly any oscillations in wind pressure will die away following changes in wind demand, and the overall steadiness of the wind supply. Higher values give less oscillations. A value in the range of 5 - 10 usually provides a good starting point, and can be fine-tuned by experiment to give the required effect.

WindModel_WindchestPressureDropPctAtMaxLoad

Float 0.001 - 100.0


This value determines the flow capacity of the generated wind-trunk between the reservoir and the wind-chest, and thus the drop in pressure when then wind demand is high (termed 'wind robbing'). The maximum load is calculated automatically as the air flow rate required to supply all of the attached pipework at its normal operating pressure, and the value specifies the drop in pressure that should occur at this load (i.e. when all attached pipes are sounding), specified as a percentage of the available 6" of wind. The pitch of a typical diapason falls by about 3.3 percent of a semitones when the wind pressure falls by about 6.3%, being proportional to the square root of (100 minus the pressure drop in percent). Increasing this value increases the amount of 'wind robbing' under situations of high wind demand. A value in the range of 1 - 10 usually provides a good starting point, and can be fine-tuned by experiment to give the required effect.

PercussiveEngagingKeyActionNoise_RankID

ID 1 - 1024 N 3.0.0 Rank.RankID Allows key action noises to be attached easily to the division. If not blank, the specified rank’s pipe will be triggered percussively as each key is pressed down.

PercussiveEngagingKeyActionNoise_ChooseMIDINoteNumRandomly

Boolean Y/N May be specified only if PercussiveEngagingKeyActionNoise_RankID is not blank

3.0.0 If PercussiveEngagingKeyActionNoise_RankID is not blank, then this setting determines whether each of the division’s keys will trigger a random ‘pipe’ from that rank (Y) or whether the note number of the pipe triggered will correspond to the note number of the key (N).

PercussiveDisengagingKeyActionNoise_RankID

ID 1 - 1024 N 3.0.0 Rank.RankID Allows key action noises to be attached easily to the division. If not blank, the specified rank’s pipe will be triggered percussively as each key is released.

PercussiveDisengagingKeyActionNoise_ChooseMIDINoteNumRandomly

Boolean Y/N May be specified only if PercussiveDisengagingKeyActionNoise_RankID is not blank

3.0.0 If PercussiveDisengagingKeyActionNoise_RankID is not blank, then this setting determines whether each of the division’s keys will trigger a random ‘pipe’ from that rank (Y) or whether the note number of the pipe triggered will correspond to the note number of the key (N).

SustainingKeyActionNoise_RankID ID 1 - 1024 N 3.0.0 Rank.RankID Allows key action noises to be attached easily to the division. If not blank, the specified rank’s pipe will be played continuously whilst each key is held down by the player.

SustainingKeyActionNoise_ChooseMIDINoteNumberRandomly

Boolean Y/N May be specified only if SustainingKeyActionNoise_RankID is not blank

3.0.0 If SustainingKeyActionNoise_RankID is not blank, then this setting determines whether each of the division’s keys will trigger a random ‘pipe’ from that rank (Y) or whether the note number of the pipe triggered will correspond to the note number of the key (N).

CustomDisplay1_Divisionals_DisplayPageID



The CustomDisplay1_Divisionals_... attributes allow you to show up to 20 divisional combination pistons on one of your own custom display pages. This specifies the page.

CustomDisplay1_Divisionals_NumberDisplayed

Integer 0 - 20 Must be specified only if CustomDisplay1_Divisionals_DisplayPageID is not blank

3.0.0 The CustomDisplay1_Divisionals_... attributes allow you to show up to 20 divisional combination pistons on one of your own custom display pages. This specifies the number that you wish to display. 20 divisional always exist, but you do not need to display all of them.

CustomDisplay1_Divisionals_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_Divisionals_DisplayPageID is not blank


The CustomDisplay1_Divisionals_... attributes allow you to show up to 20 divisional combination pistons on one of your own custom display pages. This selects the control's visual style from your library of control styles.

CustomDisplay1_Divisionals_FirstDisplayedPistonPos_X


3.0.0 The CustomDisplay1_Divisionals_... attributes allow you to show up to 20 divisional combination pistons on one of your own custom display pages. The pistons are displayed in a row (need not be horizontal) between the X, Y position of the first and the X, Y position of the last.

CustomDisplay1_Divisionals_FirstDisplayedPistonPos_Y



CustomDisplay1_Divisionals_LastDisplayedPistonPos_X



CustomDisplay1_Divisionals_LastDisplayedPistonPos_Y



CustomDisplay1_Divisionals_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_Divisionals_DisplayPageID is not blank and that display page includes the


Alternate layout equivalent of CustomDisplay1_Divisionals_ControlStyleID.





alternate layout

CustomDisplay1_Divisionals_AltLayout1_FirstDisplayedPistonPos_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_Divisionals_DisplayPageID is not blank and that display page includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay1_Divisionals_FirstDisplayedPistonPos_X.

CustomDisplay1_Divisionals_AltLayout1_FirstDisplayedPistonPos_Y


4.0.0 Alternate layout equivalent of CustomDisplay1_Divisionals_FirstDisplayedPistonPos_Y.

CustomDisplay1_Divisionals_AltLayout1_LastDisplayedPistonPos_X


4.0.0 Alternate layout equivalent of CustomDisplay1_Divisionals_LastDisplayedPistonPos_X.

CustomDisplay1_Divisionals_AltLayout1_LastDisplayedPistonPos_Y


4.0.0 Alternate layout equivalent of CustomDisplay1_Divisionals_LastDisplayedPistonPos_Y.

CustomDisplay1_DivisionalCancel_DisplayPageID



The CustomDisplay1_DivisionalCancel_... attributes allow you to make the divisional cancel piston visible on one of your own custom display pages. This selects the page if so.

CustomDisplay1_DivisionalCancel_Text

String 64 Must be specified only if CustomDisplay1_DivisionalCancel_DisplayPageID is not blank

3.0.0 The CustomDisplay1_DivisionalCancel_... attributes allow you to make the divisional cancel piston visible on one of your own custom display pages. This is the text that will be shown on the piston.

CustomDisplay1_DivisionalCancel_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_DivisionalCancel_DisplayPageID is not blank


The CustomDisplay1_DivisionalCancel_... attributes allow you to make the divisional cancel piston visible on one of your own custom display pages. This selects the control's visual style from your library of control styles.

CustomDisplay1_DivisionalCancel_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_DivisionalCancel_DisplayPageID is not blank

3.0.0 The CustomDisplay1_DivisionalCancel_... attributes allow you to make the divisional cancel piston visible on one of your own custom display pages. This specifies the position.

CustomDisplay1_DivisionalCancel_PosPixels_Y


3.0.0 The CustomDisplay1_DivisionalCancel_... attributes allow you to make the divisional cancel piston visible on one of your own custom display pages. This specifies the position.

CustomDisplay1_DivisionalCancel_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_DivisionalCancel_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay1_DivisionalCancel_ControlStyleID.

CustomDisplay1_DivisionalCancel_AltLayout1_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_DivisionalCancel_DisplayPageID is not blank and that display page includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay1_DivisionalCancel_PosPixels_X.

CustomDisplay1_DivisionalCancel_AltLayout1_PosPixels_Y


4.0.0 Alternate layout equivalent of CustomDisplay1_DivisionalCancel_PosPixels_Y.

CustomDisplay1_Keyboard_DisplayPageID



The CustomDisplay1_Keyboard_... attributes allow you to make the keyboard visible on one of your own custom display pages. This selects the page if so.

CustomDisplay1_Keyboard_KeyboardStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_Keyboard_DisplayPageID is not blank

3.0.0 CustomDisplayKeyboardStyle. KeyboardStyleID

The CustomDisplay1_Keyboard_... attributes allow you to make the keyboard visible on one of your own custom display pages. This selects the keyboard's visual style from your library of keyboard styles.

CustomDisplay1_Keyboard_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_Keyboard_DisplayPageID is not blank

3.0.0 The CustomDisplay1_Keyboard_... attributes allow you to make the keyboard visible on one of your own custom display pages. This specifies the position.

CustomDisplay1_Keyboard_PosPix Integer 0 - 8192 Must be specified only if 3.0.0 The CustomDisplay1_Keyboard_... attributes allow you to make the keyboard visible on one of your own custom





els_Y CustomDisplay1_Keyboard_DisplayPageID is not blank

display pages. This specifies the position.

CustomDisplay1_Keyboard_AltLayout1_KeyboardStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_Keyboard_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay1_Keyboard_KeyboardStyleID.

CustomDisplay1_Keyboard_AltLayout1_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_Keyboard_DisplayPageID is not blank and that display page includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay1_Keyboard_PosPixels_X.

CustomDisplay1_Keyboard_AltLayout1_PosPixels_Y


4.0.0 Alternate layout equivalent of CustomDisplay1_Keyboard_PosPixels_Y.

CustomDisplay2_Divisionals_DisplayPageID




CustomDisplay2_Divisionals_NumberDisplayed



CustomDisplay2_Divisionals_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_Divisionals_DisplayPageID is not blank



CustomDisplay2_Divisionals_FirstDisplayedPistonPos_X



CustomDisplay2_Divisionals_FirstDisplayedPistonPos_Y



CustomDisplay2_Divisionals_LastDisplayedPistonPos_X



CustomDisplay2_Divisionals_LastDisplayedPistonPos_Y



CustomDisplay2_Divisionals_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_Divisionals_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay2_Divisionals_ControlStyleID.

CustomDisplay2_Divisionals_AltLayout1_FirstDisplayedPistonPos_X


4.0.0 Alternate layout equivalent of CustomDisplay2_Divisionals_FirstDisplayedPistonPos_X.

CustomDisplay2_Divisionals_AltLayout1_FirstDisplayedPistonPos_Y


4.0.0 Alternate layout equivalent of CustomDisplay2_Divisionals_FirstDisplayedPistonPos_Y.

CustomDisplay2_Divisionals_AltLayout1_LastDisplayedPistonPos_X


4.0.0 Alternate layout equivalent of CustomDisplay2_Divisionals_LastDisplayedPistonPos_X.

CustomDisplay2_Divisionals_AltLayout1_LastDisplayedPistonPos_Y

Integer 0 - 8192 Must be specified only if CustomDisplay2_Divisionals_DisplayPageID is not blank and that display page includes the

4.0.0 Alternate layout equivalent of CustomDisplay2_Divisionals_LastDisplayedPistonPos_Y.





alternate layout

CustomDisplay2_DivisionalCancel_DisplayPageID




CustomDisplay2_DivisionalCancel_Text

String 64 Must be specified only if CustomDisplay2_DivisionalCancel_DisplayPageID is not blank


CustomDisplay2_DivisionalCancel_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_DivisionalCancel_DisplayPageID is not blank



CustomDisplay2_DivisionalCancel_PosPixels_X



CustomDisplay2_DivisionalCancel_PosPixels_Y



CustomDisplay2_DivisionalCancel_AltLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_DivisionalCancel_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay2_DivisionalCancel_ControlStyleID.

CustomDisplay2_DivisionalCancel_AltLayout1_PosPixels_X


4.0.0 Alternate layout equivalent of CustomDisplay2_DivisionalCancel_PosPixels_X.

CustomDisplay2_DivisionalCancel_AltLayout1_PosPixels_Y


4.0.0 Alternate layout equivalent of CustomDisplay2_DivisionalCancel_PosPixels_Y.

CustomDisplay2_Keyboard_DisplayPageID




CustomDisplay2_Keyboard_KeyboardStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_Keyboard_DisplayPageID is not blank



CustomDisplay2_Keyboard_PosPixels_X



CustomDisplay2_Keyboard_PosPixels_Y



CustomDisplay2_Keyboard_AltLayout1_KeyboardStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_Keyboard_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay2_Keyboard_KeyboardStyleID.

CustomDisplay2_Keyboard_AltLayout1_PosPixels_X


4.0.0 Alternate layout equivalent of CustomDisplay2_Keyboard_PosPixels_X.

CustomDisplay2_Keyboard_AltLayout1_PosPixels_Y


4.0.0 Alternate layout equivalent of CustomDisplay2_Keyboard_PosPixels_Y.




Core attributes common to tables: Stop, Coupler, Tremulant The following core attributes exist on each of the Stop, Coupler and Tremulant tables.


Name String 32 Y UK An internal name to identify the object uniquely and in a user-friendly way within the organ definition during design. Also shown to the user via the corresponding MIDI settings screens/wizards.

DisplayName String 32 Y Specifies the label for the object on the default standard console screen display (if enabled).

DefaultToEngaged Boolean Y/N N 3.0.0 By default switches are in the off state. Setting this to Y changes that, which might be useful for a blower switch, for example.

SwitchIsLatching Boolean Y/N N 3.0.0 By default switches are latching. If this is set to N, then the switch will only be on whilst it is held in by the user. For example, a theatre organ effects piston could be implemented in this way for a Stop object.

StoreInDivisionalCombinations Boolean Y/N N 3.0.0 By default the switch’s state will be stored in the divisional combinations for the division determined by the object’s object code. Setting this to N prevents that, which might be useful for ‘internal’ objects used to implement special/complex situations.

StoreInGeneralCombinations Boolean Y/N N 3.0.0 By default the switch’s state will be stored in the general combinations. Setting this to N prevents that, which might be useful for ‘internal’ objects used to implement special/complex situations.

AccessibleForMIDIInputAndOutput Boolean Y/N N 3.0.0 By default the switch will be accessible to the user via MIDI. Setting this to N prevents that, which might be useful for ‘internal’ objects used to implement special/complex situations.




Additional action noise/effect attributes common to tables: Stop, Coupler, Tremulant The following attributes exist on each of the Stop, Coupler and Tremulant tables, and provide a simple means to trigger action noises or sound effects from those objects. See the section relating to action noises and affects in earlier in this guide for further details.


PercussiveEngagingSoundEffect_RankID

ID 1 - 1024 N 3.0.0 Rank.RankID If not blank, the specified rank’s pipe will be triggered percussively as the stop/coupler/tremulant is turned on.

PercussiveEngagingSoundEffect_MIDINoteNumber

Integer 0 - 127 May be specified only if PercussiveEngagingSoundEffect_RankID is not blank

3.0.0 If PercussiveEngagingSoundEffect_RankID is not blank, then this setting determines the pipe number that will be triggered. If set to 0, then a random pipe will be triggered from the rank.

PercussiveDisengagingSoundEffect_RankID

ID 1 - 1024 N 3.0.0 Rank.RankID If not blank, the specified rank’s pipe will be triggered percussively as the stop/coupler/tremulant is turned off.

PercussiveDisengagingSoundEffect_MIDINoteNumber

Integer 0 - 127 May be specified only if PercussiveDisengagingSoundEffect_RankID is not blank

3.0.0 If PercussiveDisengagingSoundEffect_RankID is not blank, then this setting determines the pipe number that will be triggered. If set to 0, then a random pipe will be triggered from the rank.

SustainingSoundEffect_RankID ID 1 - 1024 N 3.0.0 Rank.RankID If not blank, the specified rank’s pipe will be played continuously whilst the stop/coupler/tremulant is turned engaged.

SustainingSoundEffect_MIDINoteNumber

Integer 0 - 127 May be specified only if SustainingSoundEffect_RankID is not blank

3.0.0 If SustainingSoundEffect_RankID is not blank, then this setting determines the pipe number that will be triggered. If set to 0, then a random pipe will be triggered from the rank.




Additional custom display attributes common to tables: Stop, Coupler, Tremulant, ShortcutPiston, CustomDisplayLabel, Enclosure The following attributes exist on each of the Stop, Coupler, Tremulant, ShortcutPiston, CustomDisplayLabel and Enclosure tables, and allow you to make the control visible on none, either or both of two of your own custom display pages.

Important exception: the CustomDisplay1_Text and CustomDisplay2_Text attributes are not available on the Enclosure table.


CustomDisplay1_DisplayPageID ID Valid display page code


The CustomDisplay1_... attributes allow you to make the control visible on one of your own custom display pages. This specifies the page.

CustomDisplay1_Text

[N.B. Exception: this attribute is not available on the Enclosure table.]

String 64 Must be specified only if CustomDisplay1_DisplayPageID is not blank

3.0.0 The CustomDisplay1_... attributes allow you to make the control visible on one of your own custom display pages. This is the text that will be shown on the control.

CustomDisplay1_ControlStyleID ID 1 - 999999

Must be specified only if CustomDisplay1_DisplayPageID is not blank


The CustomDisplay1_... attributes allow you to make the control visible on one of your own custom display pages. This selects the control's visual style from your library of control styles.

CustomDisplay1_PosPixels_X Integer 0 - 8192 Must be specified only if CustomDisplay1_DisplayPageID is not blank

3.0.0 The CustomDisplay1_... attributes allow you to make the control visible on one of your own custom display pages. This specifies the position.

CustomDisplay1_PosPixels_Y Integer 0 - 8192 Must be specified only if CustomDisplay1_DisplayPageID is not blank

3.0.0 The CustomDisplay1_... attributes allow you to make the control visible on one of your own custom display pages. This specifies the position.

CustomDisplay1_AlternateLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay1_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay1_ControlStyleID.


CustomDisplay1_AlternateLayout1_PosPixels_X

Integer 0 - 8192 Must be specified only if CustomDisplay1_DisplayPageID is not blank and that display page includes the alternate layout

4.0.0 Alternate layout equivalent of CustomDisplay1_PosPixels_X.

CustomDisplay1_AlternateLayout1_PosPixels_Y


4.0.0 Alternate layout equivalent of CustomDisplay1_PosPixels_Y.

CustomDisplay2_DisplayPageID ID Valid display page code



CustomDisplay2_Text

[N.B. Exception: this attribute is not available on the Enclosure table.]

String 64 Must be specified only if CustomDisplay2_DisplayPageID is not blank


CustomDisplay2_ControlStyleID ID 1 - 999999

Must be specified only if CustomDisplay2_DisplayPageID is not blank



CustomDisplay2_PosPixels_X Integer 0 - 8192 Must be specified only if CustomDisplay2_DisplayPageID is not blank


CustomDisplay2_PosPixels_Y Integer 0 - 8192 Must be specified only if CustomDisplay2_DisplayPageID is not blank


CustomDisplay2_AlternateLayout1_ControlStyleID

ID 1 - 999999

Must be specified only if CustomDisplay2_DisplayPageID is not blank and that display page includes the alternate layout


Alternate layout equivalent of CustomDisplay2_ControlStyleID.

CustomDisplay2_AlternateLayout1_ Integer 0 - 8192 Must be specified only if 4.0.0 Alternate layout equivalent of CustomDisplay2_PosPixels_X.





PosPixels_X CustomDisplay2_DisplayPageID is not blank and that display page includes the alternate layout

CustomDisplay2_AlternateLayout1_PosPixels_Y


4.0.0 Alternate layout equivalent of CustomDisplay2_PosPixels_Y.




Table: Coupler The Coupler table lists the couplers that should be generated for the divisions, with appropriate key actions being generated by default between the source keyboards and destination divisions. If no unison-off coupler is specified for a division, a fixed unison key action is also generated so that the division plays at unison pitch as normal when no couplers are engaged. By default the CouplerCode determines the linked divisions, coupling pitch, and basic key action type (e.g. melody and bass couplers) and can take any of the following values:

1000. Pedal to Pedal 16ft

1001. Pedal to Pedal UnisonOff

1002. Pedal to Pedal 4ft

1003. Pedal to Pedal Bass

1004. Pedal to Pedal Melody

1005. Manual1 to Pedal 16ft



1008. Manual1 to Pedal Bass

1009. Manual1 to Pedal Melody


























1100. Pedal to Manual1 16ft



1103. Pedal to Manual1 Bass

1104. Pedal to Manual1 Melody

1105. Manual1 to Manual1 16ft

1106. Manual1 to Manual1 UnisonOff


1108. Manual1 to Manual1 Bass

1109. Manual1 to Manual1 Melody
























































































































































































































10000. Couplers: custom coupler 1 to Pedal








10010. Couplers: custom coupler 1 to manual 1



















































Custom couplers allow coupling to happen at a user-specified non-standard or mutation pitch and allow for user-specified special types of key actions, such as pizzicato or theatre organ traps. See the Couplers section in part 1 of this guide for more information.


CouplerCode Function code

Valid coupler code

Y PK The code must identify a coupler which belongs to a division whose code is listed in the Division table.

The role of the coupler. See list above. Determines the division in whose divisional combinations the coupler’s state will be stored and recalled. For standard (non-custom) couplers, this also determines the divisions that the coupler will link by default and the coupling pitch.

OverrideSourceDivisionToSpecifie

dDivisionCode

Function

code

Valid

division code

N 3.0.0 Division.

DivsionCode

The coupler’s main coupler code always determines the division in whose divisional combinations its state will be

stored and recalled. However, this setting allows you to override the source division from which the key action will be generated, which might be useful if implementing complex coupling situations using non-standard divisions for internal purposes. Since the main coupler code only covers the 7 standard divisions, you can only couple to/from the non-standard divisions using these two settings.

OverrideDestDivisionToSpecifiedDivisionCode

Function code

Valid division code

Mandatory only if coupler code is a custom coupler, otherwise optional

3.0.0 Division. DivsionCode

The coupler’s main coupler code always determines the division in whose divisional combinations its state will be stored and recalled. However, this setting allows you to override the destination division to which the key action will be generated, which might be useful if implementing complex coupling situations using non-standard divisions for internal purposes. Since the main coupler code only covers the 7 standard divisions, you can only couple to/from the non-standard divisions using these two settings. For coupler codes in the ‘custom coupler’ range this attribute must always be specified.

CoupleDestinationKeyboardRatherThanKeyAction

Boolean Y/N N 3.0.0 By default, coupling happens from the source division’s keyboard to the destination division’s key action (wind-chests). However, you can override that behavior by setting this to Y. This might be useful for implementing tracker-style couplers that couple between keys and for implementing complex coupling situations using non-standard divisions for internal purposes.

CouplerCodeFromWhichToCopyState

Function code

Valid coupler code

N 3.0.0 Coupler. CouplerCode

If you specify another coupler here, that coupler will be linked in such a way that it always also sets this coupler’s state. This can be useful if implementing complex internal couplers, where one user-visible coupler actually needs to control two or more independent key actions. For example if you had both a Swell division and a Swell Reeds division (so that the Swell Reeds could also be coupled to another division) then a Swell Octave coupler would need two key actions: one Swell to Swell and one Swell Reeds to Swell. By using this setting you could control both with a single draw-knob/tab. If this setting is specified, then DefaultToEngaged, StoreInDivisionalCombinations, StoreInGeneralCombinations and AccessibleForMIDIInputAndOutput must all be N and the coupler cannot be displayed on any custom display pages, since it can be used internally only. Note:

as a special case, if this coupler is not a unison-off coupler, whereas the coupler whose state is being copied is a unison-off coupler, then the state will automatically be inverted when copying.

CustomCoupler_MIDINoteNumIncrementFromSourceToDest

Integer -128 to +128

Must be specified if and only if the coupler code is a custom coupler

3.0.0 If the coupler code specifies that this coupler is a ‘custom coupler’, and CustomCoupler_KeyActionTypeCode is a ‘Notes to notes’ type, then this setting sets the coupling pitch. E.g. a value of -12 would give a sub-octave coupler. If the coupler is a custom coupler but CustomCoupler_KeyActionTypeCode is an ‘All notes to one note’ type, then this setting specifies the (single) destination note. For example a value of 60 would indicate that middle C would always be triggered.

CustomCoupler_KeyActionTypeCode

Fixed code

Valid action type code


3.0.0 If the coupler code specifies that this coupler is a ‘custom coupler’, then this setting defines which keys/pallets are linked:

1. Notes to notes: all notes played (normal).

2. Notes to notes: lowest note only (bass).

3. Notes to notes: highest note only (melody).

11. All notes to one note: all notes played.





12. All notes to one note: first/last note only (traps).

CustomCoupler_KeyActionEffectCode

Fixed code

Valid action effect code


3.0.0 If the coupler code specifies that this coupler is a ‘custom coupler’, then this setting defines the way in which each coupler link will behave:

1. Normal (sustain whilst held).

2. Trigger percussively on downbeat.

3. Trigger percussively on backbeat.

4. Reiterate percussively whilst held.

5. Pizzicato.

CustomCoupler_PipeMIDINoteNum036_PizzOrReitPeriodMs

Integer 0 - 99999

Must be specified if and only if the coupler code is a custom coupler and the action effect is pizzicato or reiterating

3.0.0 If the coupler code specifies that this coupler is a ‘custom coupler’, and the action effect code is pizzicato or reiterating, then this setting specifies the maximum time in milliseconds that the coupler link will remain active (pizzicato) or the interval between reiterations (reiterating). Values are specified by these two settings for source note numbers 36 and 96, and are projected linearly for other note numbers.

CustomCoupler_PipeMIDINoteNum096_PizzOrReitPeriodMs

Integer 0 - 99999

Must be specified if and only if the coupler code is a custom coupler and the action effect is pizzicato or reiterating

3.0.0 If the coupler code specifies that this coupler is a ‘custom coupler’, and the action effect code is pizzicato or reiterating, then this setting specifies the maximum time in milliseconds that the coupler link will remain active (pizzicato) or the interval between reiterations (reiterating). Values are specified by these two settings for source note numbers 36 and 96, and are projected linearly for other note numbers.

Important note: there are more attributes that apply to this table and other tables. Please see the preceding sections for them.




Table: Enclosure The table lists the enclosures (swell boxes) to be included in the organ. The EnclosureCode determines the main role of the enclosure and can be any of the following:

100. General Swell

200. Pedal Main

201. Pedal Tibia

202. Pedal Solo Stop1


204. Pedal Stop Group1


210. Manual1 Main

211. Manual1 Tibia

212. Manual1 Solo Stop1


214. Manual1 Stop Group1


220. Manual2 Main

221. Manual2 Tibia





230. Manual3 Main

231. Manual3 Tibia





240. Manual4 Main

241. Manual4 Tibia





250. Manual5 Main

251. Manual5 Tibia





260. Manual6 Main

261. Manual6 Tibia








For each listed enclosure, the necessary virtual continuous control, enclosure and wind model objects are generated automatically, and linked as required to the pipework. The division associated with an enclosure (if it is other than a general swell) only determines how it is positioned on the default standard console display (if enabled) - any enclosure is specified separately for each rank, together with its audible effects. A division can have at most one enclosure in the Custom Organ Design Module in order to fit the required objects onto the default standard console screen display.


EnclosureCode Function code

Valid enclosure code

Y PK The code must identify an enclosure which belongs to a division whose code is listed in the Division table, or it must be the general swell enclosure.

The main role of the enclosure. See list above.

Name String 32 Y UK* Specifies the label for the associated expression pedal on the default standard console display (if enabled).

EnableShutterInertiaModel Boolean Y/N Y When set to Y, the controlling expression is linked to the shutters with the inertia of the shutters being modeled so that the shutters have a slightly delayed response to movements of the pedal. The inertia model parameters are configured automatically.

WindModel_Enable Boolean Y/N Y If set to Y, the wind pressure within the enclosure (swell box) is modeled, with all pipe ranks enclosed by the enclosure feeding their wind output into the box. The shutters allow air to leave the box as it opens (the flow rates are calculated automatically based on the wind demand of the enclosed pipes), and some leakage is allowed from the box when it is closed.

WindModel_BoxPressureRisePctAtMaxLoadWhenClosed

Float 0.001 - 100.0

Must be specified if and only if WindModel_Enable is set to Y

Determines the amount of wind leakage from the box when closed. The maximum wind demand is calculated for all pipes enclosed in the box by summing their flow rates when sounding at their normal operating pressures. The leakage is thus calculated so that the pressure in the box rises to the specified percentage of the available 6" pressure when all enclosed pipes are sounding.

See the WindModel_WindchestPressureDropPctAtMaxLoad attribute of the Division table section above for information on how to estimate the amount of pitch variation that will result from a given wind pressure drop.

Values in the range 1 - 5 may give a good starting point - a very slight, but just discernible detuning when the box is fully closed. Larger values increase the detuning when the box is closed, giving a similar effect to 'wind robbing'.





Table: Tremulant The Tremulant table lists the tremulants to be available on the organ that should use Hauptwerk’s native tremulant model. The TremulantCode determines the primary role of the tremulant:

1690. General Tremulant

1700. Pedal Main

1701. Pedal Tibia





1710. Manual1 Main

1711. Manual1 Tibia





1720. Manual2 Main

1721. Manual2 Tibia





1730. Manual3 Main

1731. Manual3 Tibia





1740. Manual4 Main

1741. Manual4 Tibia





1750. Manual5 Main

1751. Manual5 Tibia





1760. Manual6 Main

1761. Manual6 Tibia








The division with which the tremulant is associated determines the stop jamb upon which it is included on the default standard console display (if enabled), and the division in whose divisional combinations it is stored. However, the acoustical effects of any tremulant, together with the tremulant samples to be used, are specified separately for each pipe rank.

Note that the Tremulant table should not be used if using real tremulant-affected samples instead of Hauptwerk’s native tremulant model (see the sections on tremulants in part 1 of this guide for more information).


TremulantCode Function code

Valid tremulant code

Y PK The code must identify a tremulant which belongs to a division whose code is listed in the Division table, or it must be the general tremulant.

The primary role of the tremulant, determining the division with which it is associated for combinations.

FrequencyHz Float 0.001 - 64.0 Y Frequency of tremulant oscillation in Hertz.

MaxFrequencyRandomisationPct Float 0.0 - 99999.9

Y The frequency of the tremulant is varied constantly in real-time, using a simple randomization model. This setting determines the maximum deviation from the normal frequency that is allowed, specified as a percentage of the normal frequency.

MaxDepthRandomisationPct Float 0.0 - 99999.9

Y Similarly, the depth of the tremulant is randomized, this value specifying the maximum allowed deviation from the normal depth, specified as a percentage of that depth.

TremulantCodeFromWhichToCopyState

Function code


N 3.0.0 Tremulant. TremulantCode If you specify another tremulant here, that tremulant will be linked in such a way that it always also sets this tremulant's state. This can be useful if implementing complex internal tremulants, where one user-visible tremulant actually needs to control two or more independent (non-synchronized) tremulants. If this setting is specified, then DefaultToEngaged, StoreInDivisionalCombinations, StoreInGeneralCombinations and AccessibleForMIDIInputAndOutput must all be N and the tremulant cannot be displayed on any custom display pages, since it can be used internally only.





Table: Rank There Rank table is the central table in the custom organ definition format, and by far the most complex.

(It is used by the Custom Organ Design Module compiler to generate all objects in the pipe, pipe layer, pipe layer attack sample, pipe layer release sample, sample, enclosure pipe, tremulant waveform, tremulant waveform pipe and rank tables in the full organ definition format.)

It describes the set(s) of pipe samples that are to be used for the organ rank (or organ ranks if the samples were recorded with more than one physical pipe rank sounding at once, as is often the case with a mixture stop), how the pipes should be played and modeled, and any effects that should apply to them.

Several custom organ ranks (or parts of them) can be assigned to a given stop and a given rank can be used by several stops, allowing unification. The StopRank table described later provides such functionality, assigning the required parts of ranks to stops.

Pipe and tremulant waveform samples do not need to be specified for every pipe (although it is preferable for best results), and the rank can extend beyond the samples available, with the first or last sample automatically being re-pitched for the remaining pipes. Note that use of less than one sample per virtual pipe does not save memory, since the samples are still loaded separately for each pipe, so that signal processing can be applied to them, where such processing does not need to happen in real-time.

The output pipe pitch of the rank is specified separately from that of the pipe samples that are used for it, so it is possible to play a set of samples at a pitch other than that at which they were recorded, with the necessary re-pitching happening automatically in real-time for the user-selected temperament, and also to 're-voice' ranks by adjusting their pitch, amplitude or harmonic content.

Reverberation tail truncation can be applied to the rank, so that the response of dry pipes is modeled (in a basic way). Although this would normally be used to allow semi-dry ranks from various sample sets to be combined relatively convincingly, it also allows pipes played at pitches other than that at which they were recorded to have their decays shaped appropriately for their playback pitches.

Hauptwerk's native tremulant model works by using special waveform samples which define how the pitch, amplitude and harmonic content of a pipe should vary with time, and any set of such samples can be applied across the rank. The modulation occurs separately for each pipe in real-time. Separate tremulant waveform samples may be used for each rank, or even pipe, if desired, or shared between pipes or ranks. The depth of the pitch, amplitude and harmonic content modulation by any tremulant can be adjusted across the compass of the rank.

Hauptwerk's enclosure model uses specially-designed filters that model the acoustic effects of a swell box on the pipework, whilst being fast enough to be applied separately for each pipe in real-time. The filter has a single 'maximum' (peak) and 'minimum' (trough) in its frequency response and the frequency response is smooth between them. Thus it can behave like a simple high-pass or low-pass filter. The attenuation in decibels can be set at the maximum, and also the attenuation in decibels of the minimum relative to the maximum. The frequency of the maximum and minimum can also be defined. Note that a large relative attenuation between the maximum and minimum with a small frequency separation between them will give rise to a steep curve in the frequency response between them, and stronger filter resonance around the maximum and minimum. Resonance would normally be very low for the relative attenuations that would be used to emulate the effects of a swell box. Attenuation values are specified for the box closed, and they are automatically reduced to zero as the box opens. The maximum and minimum frequencies are specified for both the box open and closed.

In general, Hauptwerk modulates the amplitude, pitch and harmonic content of each pipe separately in real-time. The effects of the wind model, tremulants and any static levels (for example a fixed pitch increment used to make the rank sound as a detuned rank, such as a celeste) are combined to determine the amplitude, pitch and harmonic content of each pipe at any given moment in time. The harmonic content is modulated by specifying the gain of the pipe's third harmonic relative to that of its fundamental. This is achieved using a specially designed 'harmonic shaping' filter. The filter behaves roughly like a high or low-pass filter, with the gain for frequencies above the third harmonic being as nearly as possible the same as for the third harmonic.

Each pipe is identified by a 'MIDI note number', being the MIDI note on/off message note number of the keyboard key to which the pipe would normally be attached when sounding at its normal pitch. If the rank is unified, then it will of course sound at several different pitches, and a 'basic' pitch must simply be chosen arbitrarily. For example, the lowest C of a 61-pipe 8' diapason rank would normally be attached to the lowest C on a 61-key manual, for which the MIDI note number is 36, that of the middle C pipe would be 60, and that of the top C 96. For an 85-pipe theatre organ tibia rank with the lowest pipe sounding at 16' C pitch, the rank could be considered as having a 'basic' pitch of 8', with the MIDI note number of its first pipe being 24 and top pipe being 108, or a basic pitch of 16', with the MIDI note number of its first pipe being 36 and that of its top pipe being 120. Note that MIDI note numbers cannot exceed 127, which may influence the choice of 'basic' rank pitch for unified ranks.

Please see also the relevant sections in part 1 of this guide for more background information on these topics.

Many parameters relating to the pipes that will be generated are specified for a theoretical pipe of MIDI note number 36, and again for a pipe of MIDI note number 96. Values for all other pipes (between or beyond 36 and 96) are then projected linearly. The rank need not necessarily actually include pipes of those note two numbers; they are simply used to define the projection of the parameter values across the compass of the rank.

There are several groups of parameters, identified by the parameter name prefixes:

• The Sample_... parameters define which pipe samples files should be used for the rank and their pitches. The values of most can usually be copied from the installation package definition file.

• The Position_... parameters define where the generated virtual pipes are placed in space, the positions being used when playing mono recordings in stereo or mono/stereo recordings in surround/3D formats, synthesizing the remaining channels as required.

• The WindSupply_... parameters define how the pipes are supplied with wind.

• The Amp_... parameters define the basic output amplitude of the pipework and how strongly it should be modulated by the wind model and any attached tremulant.

• The Pitch_... parameters define the basic output pitch of the pipework, which need not be the same as that of the samples since re-pitching happens automatically in real-time, and how strongly it should be modulated by the wind model and any attached tremulant.

• Likewise, the HarmonicShaping_... parameters control Hauptwerk's harmonic-shaping filters (described above), determining the basic level of the filters (for voicing) and how deeply they are modulated by the wind model and any attached tremulants.

• The Encl_... parameters control the effects of the swell box model across the compass of the rank, and whether the rank is enclosed.

• The Trem_... parameters determine whether a tremulant is applied to the rank and which tremulant waveform sample should be used for each pipe. The values of most can usually be copied from the installation package definition file.

• Finally the ReverbTailTruncation_... parameters allow dry pipe decays to be modeled, as described above.

There are a few further general parameters with no prefix.


RankID ID 1 - 1024

Important: was 1 - 999999 prior to Hauptwerk 3.0.0

Y PK (*) see note

A unique identifier for the rank. Any number can be used.

Important note (*): the range was reduced from 1 - 999999 to 1 - 1024 for Hauptwerk version 3.0.0 and later. This is necessary in order to be able to guarantee that user voicing settings are preserved if ranks are added or removed (provided that the remaining ranks are unaltered). If you previously had ranks with IDs greater than 1024 then you will need to renumber them manually.





Name String 64 Y UK Max length increased 4.0.0

The name of the rank that will be presented to the user when given the option to select ranks to disable, for memory format options, voicing or audio routing.

NumberOfPipes Integer 1 - 128 Y The number of pipes that will be generated for the rank.

MIDINoteNumberOfFirstPipe Integer 0 - 127 Y The pipes are assigned MIDI note numbers from this value upwards.

IsPercussive Boolean Y/N Y If Y, the samples are played as 'one-shot' samples, with no release samples being required or played.

Samples_InstallationPackageID ID 1 - 999999 Y RequiredInstallationPackage . InstallationPackageID

The ID of the organ installation package which contains the pipe samples.

Samples_MainSampleFileFolder Filename 255 N (a null value meaning that the pipe samples are located in the root of the installation package folder)

The folder within the installation package containing the pipe samples, relative to the root of the package folder. For example 'Stereo-StAnnesMoseley-Great-OpenDiapasonLarge8' would be the value that should be specified (being the folder within the 000010 package folder) in order to use the St. Anne's Moseley Great Open Diapason Large 8 samples. The value of this parameter can be copied from the installation package definition file, where it should have been specified correctly by the sample set creator.

Samples_SamplesAreProtected Boolean Y/N N Obsolete 4.0.0+

This setting is obsolete and ignored in Hauptwerk version 4.0.0 and later, for which the information is determined automatically from the sample files.

Samples_ReleaseSamplesStoredInSeparateFilesIfNotPercussive

Boolean Y/N N Obsolete 4.0.0+

This setting is obsolete and ignored in Hauptwerk version 4.0.0 and later, for which the Samples_RelSampleFileFolderIfRelSamplesStoredInSeparateFiles is used directly.

Samples_RelSampleFileFolderIfRelSamplesStoredInSeparateFiles

Filename 255 May be specified only if IsPercussive is set to N

Hauptwerk allows the release sample to be stored in separate physical files, or to be defined by the first sample markers in the main (attack/sustain) sample files. If the rank is non-percussive and the release samples are stored in separate files, then this setting should be used to give the folder in which they are located, relative to the package root folder as for the Samples_MainSampleFileFolder parameter. The value of this parameter can be copied from the installation package definition file, where it should have been specified correctly by the sample set creator.

Samples_ShortNoteReleaseSampleFileFolderIfAny


4.0.0 Hauptwerk allows additional sets of release samples to be specified for short notes for a more realistic virtual acoustic when playing fast. Use this and the following three parameters to specify these additional ranks of release samples if the sample set supports them. The values of these four parameters can be copied from the installation package definition file, if they have been specified there by the sample set creator.

This setting specifies the folder for the short-note (staccato) release samples (all must be in a single folder with filenames of the same format as the main pipe samples).

Samples_MaxNoteTimeMsForShortNoteReleaseSamplesIfAny

Integer 1 - 2000 May be specified only if IsPercussive is set to N. Required if Samples_ShortNoteReleaseSampleFileFolderIfAny set

4.0.0 Hauptwerk will select the short-note release sample if a pipe sounds for less than this number of milliseconds.

Samples_MediumNoteReleaseSampleFileFolderIfAny


4.0.0 This specifies the folder for the medium-note (portamento) release samples (all must be in a single folder with filenames of the same format as the main pipe samples).

Samples_MaxNoteTimeMsForMediumNoteReleaseSamplesIfAny

Integer 1 - 2000 May be specified only if IsPercussive is set to N. Required if Samples_MediumNoteReleaseSampleFileFolderIfAny set

4.0.0 Hauptwerk will select the medium-note release sample if a pipe sounds for less than this number of milliseconds, but more than Samples_MaxNoteTimeMsForShortNoteReleaseSamplesIfAny.

Samples_MIDINoteNumIncrementFromPipesToSamples

Integer -127 to +127 Y Determines which pipe sample files should be used for which pipes. A value of 0 would indicate that a pipe with MIDI note number 36 would use a sample with filename 036-C.wav, 37 would use 037-C#.wav and so forth. A value of 12 would indicate that pipe 36 would use sample 048-C.wav, and -12 would indicate that pipe 36 would use sample 024-C.wav.

If the samples are to be played at approximately their original pitches, then this value should normally be set to 0, but other values can be used to re-pitch or 're-voice' sampled ranks to different pitches.

Samples_SampleMIDINoteNumOfFirstAvailableSample

Integer 0 - 127 N Obsolete 4.0.0+


Samples_SampleMIDINoteNumOfL

astAvailableSample

Integer 0 - 127 N Obsolete

4.0.0+

This setting is obsolete and ignored in Hauptwerk version 4.0.0 and later, for which the

information is determined automatically from the sample files.

Samples_MIDINoteNumIncBetweenSamples



Samples_AssumeTunedToConcertPitchAndEqualTemp

Boolean Y/N N Obsolete 4.0.0+

This setting is obsolete and ignored in Hauptwerk version 4.0.0 and later, for which the Samples_RankBasePitch64ftHarmNumIfAssumedTunedToConcertPitch is used directly.

Samples_RankBasePitch64ftHarmNumIfAssumedTunedToConcertPitch

Integer 01/01/48 N Hauptwerk must know the exact pitch of each sample so that the required amount of re-pitching can be calculated to play the organ with any user-selected temperament. The sample set creator can either have detected the exact pitch of the samples and saved them





into the sample files, or have re-tuned the samples perfectly to concert pitch (A=440 Hz) and equal temperament.

In the former case, this parameter should be set to zero (in which case Hauptwerk will read the sample pitches from the samples themselves). In the latter case (samples tuned to A-440/equal) then this value gives the pitch of the samples by specifying the harmonic number that they represent, relative to the fundamental of a 64' stop. For example, if the samples were recorded from a 4' rank, then the pitch of the samples is considered to be 4', which corresponds to the sixteenth harmonic of a 64' pipe, and thus 16 should be specified for this setting. Even if the samples start in the second octave, their theoretical pitch is still 4', and 16 should still be specified for this setting.

In general, divide 64 by the rank pitch of the samples in feet to give the 64' harmonic number. For example, for a set of samples from a 5 1/3' rank of pipes, this setting should be set to 64 / 5 1/3 = 12.

The following are some common rank pitches, and their corresponding 64' harmonic numbers:

• 32' - 2

• 16' - 4

• 8' - 8

• 5 1/3' - 12

• 4' - 16

• 2 2/3' - 24

• 2' - 32

• 1 3/5' - 40

• 1 1/3' - 48

• 1' - 64

• 1/2' - 128

Note that this setting specifies the rank pitch of the samples. The output pitch of the rank has a separate setting, allowing samples to be played at pitches other than that at which they were recorded. The value of this parameter can be copied from the installation package definition file, where it should have been specified correctly by the sample set creator.

[Note that failing to set the sample pitch parameters correctly can prevent Hauptwerk's release sample phase alignment mechanism from working properly. Also note that when several ranks use the same set of samples, the pitch parameters will be taken from the first rank loaded, thus these values must always be set to the true pitch of the samples, and should not be used as a means to produce special effects.]

Samples_AudioOutOptimalChannelFormatCode

Fixed code Valid channel format code

N Obsolete 4.0.0+


Samples_AudioOutOptimalSampleResolutionCode

Fixed code Valid sample resolution code

N Obsolete 4.0.0+


Position_LayoutOfPipesOnWindchestCode

Fixed code Valid wind-chest layout code

Y Values are as follows:

1. C/C# divided, C pipes left with bass pipes outermost.

2. C/C# divided, C pipes right with bass pipes outermost.

3. C/C# divided, C pipes left with bass pipes innermost.

4. C/C# divided, C pipes right with bass pipes innermost.

5. Linear with bass pipes on the left.

6. Linear with bass pipes on the right.

The generated ranks are always considered to be perpendicular to the listener's line of sight when looking directly at the front of the organ.

This setting determines the virtual output positions of the pipes, which are used when playing mono recordings in stereo or mono/stereo recordings in surround/3D formats, synthesizing the remaining channels as required.

Position_RankDistanceFromListenerMetres

Float -99999.9 to +99999.9

Y The generated ranks are always considered to be perpendicular to the listener's line of sight when looking directly at the front of the organ.

This setting determines the virtual output positions of the pipes, which are used when





playing mono recordings in stereo or mono/stereo recordings in surround/3D formats, synthesizing the remaining channels as required.

WindSupply_DivisionCodeOfWindchest

Function code

Valid division code

Y Division . DivsionCode The division whose wind supply system is used to supply wind to the rank, and which will be influenced by the demand placed upon it when pipes in the rank speak (unless the wind model is disabled for that division).

If the rank is unified across several divisions, then it can have only one supply of wind, but it can still sound from the other divisions, as would be expected.

WindSupply_MaxFlowRandomisationPct

Float 0.0 - 99999.9

Y The flow rate through the pipework can be randomized so that it fluctuates slightly in real-time, imparting movement to the speech of the pipes. This parameter determines the maximum amount by which the flow is allowed to vary, specified as a percentage of the normal flow.

As a guide, for a typical diapason rank, a drop in flow of about 3.2% gives rise to a pitch drop of about 3.3 percent of a semitone.

A setting in the range 1- 5 may be a good starting point. Reed ranks tend to fluctuate more than diapasons.

Amp_PipeMIDINoteNum036_LevelAdjustDecibels

Float -99999.9 to +99999.9

Y Constant basic amplitude level adjustment for the pipes. A value of 0 means that the samples will play at their recorded level, with negative values reducing their output level relative to the recorded level, and positive increasing it. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Amp_PipeMIDINoteNum096_LevelAdjustDecibels

Float -99999.9 to +99999.9

Y Same for pipe 96.

Amp_PipeMIDINoteNum036_WindModelModDepthAdjustDecibels

Float -99999.9 to +99999.9

Y A default amplitude response is generated automatically for the pipes as the air flow rate varies. This setting allows the depth of amplitude modulation by the wind model to be adjusted. A value of 0 means that the amplitude will be modulated by the wind model by precisely the amount determined by the generated wind response. It does NOT mean that no wind model modulation of amplitude will occur. A value of +6 would approximately double the depth of amplitude modulation that would be applied by the wind model, -6 would approximately halve it. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Amp_PipeMIDINoteNum096_WindModelModDepthAdjustDecibels

Float -99999.9 to +99999.9

Y Same for pipe 96.

Amp_PipeMIDINoteNum036_TremulantModDepthAdjustDecibels

Float -99999.9 to +99999.9

Y This setting allows the depth of amplitude modulation by any attached tremulant to be adjusted. A value of 0 means that the amplitude will be modulated by the tremulant by precisely the amount determined by the tremulant waveform. It does NOT mean that no tremulant modulation of amplitude will occur. A value of +6 would approximately double the depth of amplitude modulation that would be applied by the tremulant, -6 would approximately halve it. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Amp_PipeMIDINoteNum096_TremulantModDepthAdjustDecibels

Float -99999.9 to +99999.9

Y Same for pipe 96.

Pitch_RankBaseOutputPitch64ftHarmonicNum

Integer 2048 Y Defines the basic output pitch of the rank. This can differ from the value specified for the pipe samples used; if it does, re-pitching occurs automatically.

In general, divide 64 by the required rank pitch in feet to give the 64' harmonic number. For example, if the pipes should sound as a 5 1/3' rank of pipes, this setting should be set to 64 / 5 1/3 = 12.

The following are some common rank pitches, and their corresponding 64' harmonic numbers:

1. 32' - 2

2. 16' - 4

3. 8' - 8

4. 5 1/3' - 12

5. 4' - 16

6. 2 2/3' - 24

7. 2' - 32

8. 1 3/5' - 40

9. 1 1/3' - 48

10. 1' - 64

11. 1/2' - 128





Pitch_MaxRandomTuningErrorHz Float 0.0 - 999.9 Y Each time that an organ is loaded or activated, Hauptwerk applies a randomized detuning to each pipe, to model slight tuning errors in the organ. Thus setting determines the maximum detuning in Hertz that is allowed for the rank. The probability function is weighted towards perfect tuning, so large tuning errors are fairly unlikely. Often, tuning errors are larger for reed ranks than diapasons.

Pitch_PipeMIDINoteNum036_TuningAdjustPercentSemitones

Float -99999.9 to +99999.9

Y Allows a fixed tuning increment to be applied to the rank to make celeste effects, specified as an increment in percent of a semitone above the user-selected temperament. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Pitch_PipeMIDINoteNum096_TuningAdjustPercentSemitones

Float -99999.9 to +99999.9

Y Same for pipe 96.

Pitch_PipeMIDINoteNum036_WindModelModDepthAdjustPercent

Float -99999.9 to +99999.9

Y By default the wind response of all pipes is set to give 3.3 percent of a semitone drop in pitch for a flow rate 3.2% below the normal flow, typical for a diapason rank, and projected linearly for other flow rates. This setting allows that response to be adjusted, with a setting of 100 giving a 3.3 % of a semitone drop in pitch (the default), 50% giving 1.65%, 200% giving 6.6%, etc. for a 3.2% drop in flow. Note that the value can be negative, causing the pitch to rise as the flow rate falls. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Pitch_PipeMIDINoteNum096_WindModelModDepthAdjustPercent

Float -99999.9 to +99999.9

Y Same for pipe 96.

Pitch_PipeMIDINoteNum036_TremulantModDepthAdjustPercent

Float -99999.9 to +99999.9

Y If set to 100%, the pitch modulation depth by any tremulant is exactly that specified by the level of the tremulant waveform sample at each moment in time. If set to 50%, the depth of pitch modulation (in percent of a semitone) is halved, for 200% it is doubled, etc. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Pitch_PipeMIDINoteNum096_TremulantModDepthAdjustPercent

Float -99999.9 to +99999.9

Y Same for pipe 96.

HarmonicShaping_PipeMIDINoteNum036_3rdAndUpperHarmLvlAdjDb

Float -36.0 to +36.0

Y Constant basic gain for the third and upper harmonics relative to the fundamental, allowing voicing to be adjusted, and specified in decibels. The harmonic-shaping filters are used to effect the required frequency response. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

HarmonicShaping_PipeMIDINoteNum096_3rdAndUpperHarmLvlAdjDb

Float -36.0 to +36.0

Y Same for pipe 96.

HarmonicShaping_PipeMIDINoteNum036_WindModelModDepthAdjDb

Float -99999.9 to +99999.9

Y A default harmonic content response is generated automatically for the pipes as the air flow rate varies, based on analysis of a typical diapason rank. This setting allows the depth of the harmonic content modulation (using the harmonic-shaping filters) by the wind model to be adjusted. A value of 0 means that the harmonic content will be modulated by the wind model by precisely the amount determined by the generated wind response. It does NOT mean that no wind model modulation of harmonic content will occur. A value of +6 would approximately double the depth of modulation that would be applied by the wind model, -6 would approximately halve it. Projected linearly across the compass by specifying

theoretically for pipes 36 and 96.

HarmonicShaping_PipeMIDINoteNum096_WindModelModDepthAdjDb

Float -99999.9 to +99999.9

Y Same for pipe 96.

HarmonicShaping_PipeMIDINoteNum036_TremulantModDepthAdjDb

Float -99999.9 to +99999.9

Y This setting allows the depth of harmonic content modulation (using the harmonic-shaping filters) by any attached tremulant to be adjusted. A value of 0 means that the third and upper harmonics will be modulated by the tremulant by precisely the amount determined by the tremulant waveform. It does NOT mean that no tremulant modulation of harmonic content will occur. A value of +6 would approximately double the depth of modulation that would be applied by the tremulant, -6 would approximately halve it. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

HarmonicShaping_PipeMIDINoteNum096_TremulantModDepthAdjDb

Float -99999.9 to +99999.9

Y Same for pipe 96.

Encl_IsEnclosed Boolean Y/N N Obsolete 4.0.0+

This setting is obsolete and ignored in Hauptwerk version 4.0.0 and later, for which the Encl_EnclosureCode is used directly.

Encl_EnclosureCode Function code

Valid enclosure code

N Enclosure . EnclosureCode The Enclosure object which represents the swell box in which the rank should be enclosed, if any.

Encl_FiltParamWhenClsdForPipeMIDINoteNum036_OverallAttnDb

Float -60.0 to +60.0

Must be specified if and only if Encl_EnclosureCode is non-zero

Overall amplitude attenuation when the box is closed. Attenuation reduces to zero as the box opens. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Encl_FiltParamWhenClsdForPipeMIDINoteNum036_MaxFreqHz

Float 1.0 - 22050.0


Frequency in Hertz of the peak in the frequency response when the box is closed. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Encl_FiltParamWhenClsdForPipeMI Float 1.0 - Must be specified if and only if Frequency in Hertz of the trough in the frequency response when the box is closed.





DINoteNum036_MinFreqHz 22050.0 Encl_EnclosureCode is non-zero Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Encl_FiltParamWhenClsdForPipeMIDINoteNum036_ExtraAttnAtMinDb

Float 0.0 - 60.0 Must be specified if and only if Encl_EnclosureCode is non-zero

Attenuation at the trough in the frequency response relative to that at the peak when the box is closed. Attenuation reduces to zero as the box opens. Projected linearly across the compass by specifying theoretically for pipes 36 and 96.

Encl_FiltParamWhenOpenForPipeMIDINoteNum036_MaxFreqHz

Float 1.0 - 22050.0


Frequency in Hertz of the peak in the frequency response when the box is open. Projected linearly across the compass by specifying theoretically for pipes 36 and 96. Also projected linearly between this value and the equivalent for the box closed as the box closes. Note that the peak and trough are not allowed to cross as the box closes.

Encl_FiltParamWhenOpenForPipeMIDINoteNum036_MinFreqHz

Float 1.0 - 22050.0


Frequency in Hertz of the trough in the frequency response when the box is open. Projected linearly across the compass by specifying theoretically for pipes 36 and 96. Also projected linearly between this value and the equivalent for the box closed as the box closes. Note that the peak and trough are not allowed to cross as the box closes.

Encl_FiltParamWhenClsdForPipeMIDINoteNum096_OverallAttnDb

Float -60.0 to +60.0


As for Encl_FiltParamWhenClsdForPipeMIDINoteNum036_OverallAttnDb for pipe 96.

Encl_FiltParamWhenClsdForPipeMIDINoteNum096_MaxFreqHz

Float 1.0 - 22050.0


As for Encl_FiltParamWhenClsdForPipeMIDINoteNum036_MaxFreqHz for pipe 96.

Encl_FiltParamWhenClsdForPipeMIDINoteNum096_MinFreqHz

Float 1.0 - 22050.0


As for Encl_FiltParamWhenClsdForPipeMIDINoteNum036_MinFreqHz for pipe 96.

Encl_FiltParamWhenClsdForPipeMIDINoteNum096_ExtraAttnAtMinDb

Float 0.0 - 60.0 Must be specified if and only if Encl_EnclosureCode is non-zero

As for Encl_FiltParamWhenClsdForPipeMIDINoteNum036_ExtraAttnAtMinDb for pipe 96.

Encl_FiltParamWhenOpenForPipeMIDINoteNum096_MaxFreqHz

Float 1.0 - 22050.0


As for Encl_FiltParamWhenOpenForPipeMIDINoteNum036_MaxFreqHz for pipe 96.

Encl_FiltParamWhenOpenForPipeMIDINoteNum096_MinFreqHz

Float 1.0 - 22050.0


As for Encl_FiltParamWhenOpenForPipeMIDINoteNum036_MinFreqHz for pipe 96.

Encl_MIDINoteNumOfFirstEnclosedPipeIfWholeRankNotEnclosed

Integer 0 - 127 Must be specified if and only if Encl_EnclosureCode is non-zero

3.2.0 If this value is non-zero, then no pipes with MIDI note numbers less than this value will be enclosed in the box. Thus this setting optionally allows you to specify that the bottom part of the rank should be unenclosed.

Encl_MIDINoteNumOfLastEnclosedPipeIfWholeRankNotEnclosed

Integer 0 - 127 Must be specified if and only if Encl_EnclosureCode is non-zero

3.2.0 If this value is non-zero, then no pipes with MIDI note numbers greater than this value will be enclosed in the box. Thus this setting optionally allows you to specify that the top part of the rank should be unenclosed.

Trem_HasTremulant Boolean Y/N N Obsolete 4.0.0+

This setting is obsolete and ignored in Hauptwerk version 4.0.0 and later, for which the Trem_TremulantCode is used directly.

Trem_TremulantCode Function code


N Tremulant . TremulantCode The tremulant which applies to the rank, if any.

Trem_SampleInstallationPackageID ID 1 - 999999 Must be specified if and only if Trem_TremulantCode is non-zero

RequiredInstallationPackage . InstallationPackageID

The installation package ID of the installation package which contains the tremulant waveform samples to be used for the tremulant.

Trem_WaveformSampleFileFolder Filename 255 May be specified only if Trem_TremulantCode s non-zero (in

that case, a null value means that the samples are located in the root of the installation package folder)

The folder containing the set of tremulant waveform samples to be applied to the rank, relative to the installation package root folder (similar to the Samples_MainSampleFileFolder

setting). The value of this parameter can be copied from the installation package definition file, where it should have been specified correctly by the sample set creator.

Trem_SamplesAreProtected Boolean Y/N N Obsolete 4.0.0+


Trem_MIDINoteNumIncrementFromPipesToTremSamples

Integer -127 to +127 Must be specified if and only if Trem_TremulantCode is non-zero

Equivalent to Samples_MIDINoteNumIncrementFromPipesToSamples for tremulant waveform samples.

Trem_SampleMIDINoteNumberOfFirstAvailableTremSample



Trem_SampleMIDINoteNumberOfLastAvailableTremSample



Trem_MIDINoteNumIncBetweenTremSamples



Trem_MaxDepthRandomisationPct Float 0.0 - 99999.9

Must be specified if and only if Trem_TremulantCode is non-zero

The overall depth of the tremulant (amplitude, pitch and harmonic content modulation) can fluctuate in real-time using a further randomization model. This setting specifies the maximum amount by which the depth is randomized, relative to the normal modulation depth. Thus a value of 10 would indicate that the depths of the tremulant modulations could fluctuate between 90 and 110% of their normal values.

Trem_MIDINoteNumOfFirstTremmedPipeIfWholeRankNotTremmed

Integer 0 - 127 N 3.2.0 If this value is non-zero, then no pipes with MIDI note numbers less than this value will be affected by the tremulant. Thus this setting optionally allows you to specify that the bottom part of the rank should be untremmed.





Trem_MIDINoteNumOfLastTremmedPipeIfWholeRankNotTremmed

Integer 0 - 127 N 3.2.0 If this value is non-zero, then no pipes with MIDI note numbers greater than this value will be affected by the tremulant. Thus this setting optionally allows you to specify that the top part of the rank should be untremmed.

ReverbTailTruncation_ModeCode Fixed code Valid reverb tail truncation mode

Y Valid codes are:

1. No truncation (play with full ambient release).

2. Half-sinusoid fade from start of release sample.

3. Half-sinusoid fade from first marker within release sample, if such a marker is present, otherwise the start of the release sample.

ReverbTailTruncation_DecayLengthAsMsForMiddleCOn8FtStop

Float 1.0 - 99999.9

Must be specified if and only if ReverbTailTruncation_Mode is not 1

When reverb tail truncation is to be applied, this setting gives the desired length of the decay in milliseconds for a middle C pipe in an 8' rank. The values for all pipes of other pitches are projects appropriately. Please note, adjustment for ranks of other pitches is automatic, thus the value should still be specified for an 8' rank even if the pitch of this rank was 4'.

Values in the range 130 - 180 are often effective.




Table: ExternalRank The ExternalRank table allows ranks to be defined which will produce no sound within Hauptwerk, require no samples, and exist only to control real external pipework or external voice expanders. Inevitably such ranks are fairly system-specific, but they must be included in the custom organ definition if they will be used so that they can be controlled natively by Hauptwerk as part of the organ’s ‘virtual relay’.


ExternalRankID ID 1 - 999999

Y PK Any unique number to identify the external rank.

Name String 32 Y UK The name that is presented to the user when configuring MIDI settings for the virtual external rank.

NumberOfPipes Integer 1 – 128 Y The number of external physical pipes or notes available on the voice expander.

MIDINoteNumberOfFirstPipe Integer 0 - 127 Y The MIDI note number to which the first external pipe or note responds. Usually 36 for ranks which start at bottom C.




Table: Stop The Stop table lists the stops that are to be available for each division and shown on the controls tab on the default standard console display (if enabled). A stop may be comprised of one or more than one rank or external rank. Its composition is defined by the separate StopRank table, described below.


StopCode Function code

Valid stop code

Y PK The code must identify a stop which belongs to a division whose code is listed in the Division table.

The StopCode uniquely identifies the stop, defines the division to whose key actions it is attached by default and in whose divisional combinations its state will be stored and recalled. Valid values are:

2001. Pedal division stop 01.

...

2099. Pedal division stop 99.

2101. Manual1 division stop 01.

...



...



...



...



...



...


OverrideSourceDivisionToSpecifiedDivisionCode

Function code

Valid division code

N 3.0.0 Division. DivisionCode The stop's main stop code always determines the division in whose divisional combinations its state will be stored and recalled. However, this setting allows you to override the division from whose key actions it will play, which might be useful if implementing complex coupling situations using non-standard divisions for internal purposes. Since the main stop code only covers the 7 standard divisions, you can only attach a stop to the non-standard divisions' key actions using this setting.

StopCodeFromWhichToCopyState Function code

Valid stop code

N 3.0.0 Stop.StopCode If you specify another stop here, that stop will be linked in such a way that it always also sets this stop's state. This might be useful if implementing complex internal coupling situations, where one user-visible stop actually needs to control two or more independent stops, each connected to a different division's key actions. If this setting is specified, then DefaultToEngaged, StoreInDivisionalCombinations, StoreInGeneralCombinations and AccessibleForMIDIInputAndOutput must all be N and the stop cannot be displayed on any custom display pages, since it can be used internally only.





Table: StopRank The StopRank table defines the composition of each stop, allowing (internal) ranks and external ranks. One or more ranks can be used for each stop and a rank can be used in multiple stops. Portions of ranks may be used to compose mixtures or achieve unification/borrowing at the required pitches, etc. See the notes in part 1 of this guide for more details.


Name String 32 Y UK An internal name to identify the stop-rank uniquely in a user-friendly way in the organ definition. Not displayed to the user.


Valid stop code

Y Stop . StopCode Refers to a stop listed in the Stop table. The stop defines the division from whose key actions the rank will play.

RankTypeCode Fixed code Valid rank type code

Y Valid values are:

1. (Internal) rank.

2. External rank.

RankID ID 1 - 1024 Must be specified if and only if RankType is 1

Rank . RankID If the RankType is set to 1, this gives the RankID of the rank that will (normally) sound when the stop is engaged.

ExternalRankID ID 1 - 999999

Must be specified if and only if RankType is 2

ExternalRank . ExternalRankID

If the RankType is 2, this gives the ExternalRankID of the external rank that (normally) will be played when the stop is engaged.

MIDINoteNumIncrementFromDivisi

onToRank

Integer -128 to

+128

Y If ActionTypeCode is a ‘Notes to notes’ type, then this sets the pitch increment. For example, if 0 then the pipe with the

same MIDI note number as that of the division's key will sound when the key is pressed. If 12, then the pipe an octave higher will sound, -12 an octave below and so forth. If instead ActionTypeCode is a ‘... to one note’ type, then this setting specifies the (single) destination note. For example a value of 60 would indicate that middle C would always be triggered.

MIDINoteNumOfFirstMappedDivisionKey

Integer 0 to 127 Y Determines the part of the division's keyboard which will be linked to the rank. Usually this should be the same as the MIDI note number of the first key for the stop's division, but different values allow for parts of ranks to be used to make up stops, as would be required for a mixture, for example.

NumberOfMappedDivisionKeys Integer 1 to 128 Y Also defines the mapped key range.

ActionTypeCode Fixed code Valid action type

N 3.0.0 This setting defines which pipes are linked from the key action:

1. Notes to notes: all notes played (normal).

2. Notes to notes: lowest note only (bass).

3. Notes to notes: highest note only (melody).

11. All notes to one note: all notes played.

12. All notes to one note: first/last note only (traps).

21. Stop switch action to one note (stop action noise/effect).

If the value is not specified, type 1 is used as the default.

ActionEffectCode Fixed code Valid action effect

N 3.0.0 This setting defines the way in which each pipe will be linked to its key action node:

1. Normal (sustain whilst held).

2. Trigger percussively on downbeat.

3. Trigger percussively on backbeat.

4. Reiterate percussively whilst held.

5. Pizzicato.

If the value is not specified, type 1 is used as the default.

PipeMIDINoteNum036_PizzOrReitPeriodMs

Integer 0 - 99999

Must be specified only if action effect is pizzicato or reiterating

3.0.0 If the action effect code is pizzicato or reiterating, then this setting specifies the maximum time in milliseconds that the pipe will sound (pizzicato) or the interval between reiterations (reiterating). Values are specified by these two settings for pipe note numbers 36 and 96, and are projected linearly for other note numbers.

PipeMIDINoteNum096_PizzOrReitPeriodMs

Integer 0 - 99999

Must be specified only if action effect is pizzicato or reiterating

3.0.0 If the action effect code is pizzicato or reiterating, then this setting specifies the maximum time in milliseconds that the pipe will sound (pizzicato) or the interval between reiterations (reiterating). Values are specified by these two settings for pipe note numbers 36 and 96, and are projected linearly for other note numbers.

StopCodeToSwitchToAlternateRank Function code

Valid stop code

N 3.0.0 Stop.StopCode This setting exists mainly to allow real ‘tremmed’ samples to be used. See part 1 of this guide for more details. This setting can optionally specify that a stop switch should select an alternate (tremmed) rank for this stop-rank connection.

RetriggerNotesWhenSwitchingBetweenNormalAndAlternateRanks

Boolean Y/N Can be specified only if StopCodeToSwitchToAlternateRank is not blank

3.0.0 This setting exists mainly to allow real ‘tremmed’ samples to be used. See part 1 of this guide for more details. If StopCodeToSwitchToAlternateRank is non-blank, this setting defines whether held notes should re-trigger when switching between the normal and alternate (tremmed) ranks.

AlternateRankID ID 1 - 1024 Must be specified only if StopCodeToSwitchToAlternateRank is not blank

3.0.0 Rank . RankID This setting exists mainly to allow real ‘tremmed’ samples to be used. See part 1 of this guide for more details. If StopCodeToSwitchToAlternateRank is non-blank, and the rank type is an internal rank, this setting defines alternate (tremmed) rank to use.





and RankType is 1

AlternateExternalRankID ID 1 - 999999

Must be specified only if StopCodeToSwitchToAlternateRank is not blank and RankType is 2

3.0.0 ExternalRank . ExternalRankID

This setting exists mainly to allow real ‘tremmed’ samples to be used. See part 1 of this guide for more details. If StopCodeToSwitchToAlternateRank is non-blank, and the rank type is an external rank, this setting defines alternate (tremmed) rank to use.

[ (*) Note that the Name fields for the following tables must be unique across all of those tables, otherwise the compiled organ definition file will not load successfully: Coupler, Enclosure, Stop and Tremulant.]




Table: ShortcutPiston This table can be used to implement reversible pistons and special effects pistons that temporarily turn on a stop, coupler or tremulant whilst held in.


Name String 20 Y UK 3.0.0 A name used to identify the object in a user-friendly way in the organ definition, and which will be visible to the user on the relevant MIDI settings screen.

ReferencedObjectTypeCode Fixed code

Valid object type code

Y 3.0.0 Determines the type of object this piston will trigger. Can be either:

1. Stop.

2. Coupler.

3. Tremulant.


Valid stop code

Must be specified only if referenced object type is a stop

3.0.0 Stop.StopCode If the referenced object type is a stop, this determines the stop that will be triggered by the piston.

CouplerCode Function code

Valid coupler code

Must be specified only if referenced object type is a coupler

3.0.0 Coupler. CouplerCode

If the referenced object type is a coupler, this determines the coupler that will be triggered by the piston.

TremulantCode Function code


Must be specified only if referenced object type is a tremulant

3.0.0 Tremulant. TremulantCode

If the referenced object type is a tremulant, this determines the tremulant that will be triggered by the piston.

PistonActionTypeCode Fixed code

Valid piston action type code

Y 3.0.0 Determines how the piston will be linked to the target object. Can be either:

1. Reversible piston. The piston will toggle the state of the target object.

2. The piston will turn on the target object only whilst the piston is held in, then release it. Can be useful for effects pistons, e.g. theatre organ ‘toy counter’ effects.





Table: CustomDisplayLabel This table can be used to display static (non-functional) labels or other static image objects on custom display pages on the virtual console.


Name String 32 Y UK 3.0.0 A name used to identify the object in a user-friendly way in the organ definition. Has no functional effect. In particular, does not determine the text (if any) to be shown on a label, which is instead determined by the CustomDisplay_... attributes.



Documents

Hauptwerk Custom Organ Design Module User Guide · Custom Organ Design Module User Guide Hauptwerk version 4.2.1