-
Notifications
You must be signed in to change notification settings - Fork 0
/
orgdef.html
479 lines (363 loc) · 38.4 KB
/
orgdef.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<meta http-equiv="Content-Style-Type" content="text/css">
<title>Orgdef documentation for insreg</title>
<link rel="stylesheet" href="bsgmiditools.css">
</head>
<body>
<h1>Preparing organs for <tt style="font: 90% Courier;">insreg</tt></h1>
<p>by Bernard Greenberg, December 2017<br> Version of <b>2/3/2019 08:00,</b> <tt>insreg</tt> distro <b>1.0.11</b></p>
<p style="padding-bottom:20px"></p>
<p><b>VPOMIDITools</b> Copyright © 2016-2020 by Bernard Greenberg. GNU General Public License Version 3 applies. Please see <a href="LICENSE">LICENSE</a> for details.</p>
<h2>Introduction</h2>
<p>In order to use a specific VPO sampleset with my tools, such as <a href="insreg.html"><tt>insreg</tt></a> to prepare a MuseScore score for a VPO, an “organ definition file” is needed, for which I have my own simple textual format. Please note that while the VPO apps very reasonably use this very obvious phrase for their own organ definitions, this is not they. My file suffix is (perhaps “also”) <tt>.orgdef</tt>, and I will refer to them as “orgdef (files)”.</p>
<p>Preparing orgdef files is not particularly difficult. My tools support Hauptwerk and Grand Orgue right now, and your orgdef file <a href="#application">has to say</a> which you are using (you need different ones for each application; that may or may not change). The basic task is to <a href="#division">list the stops</a> and other visible instrument controls and <a href="#ascertain">obtain</a> and supply the unique numbers that the organ sampleset vendors supply for each. In the case of Grand Orgue, you will also need to supply a <a href="#prologue">prologue <span class="smc">MIDI</span> file</a> generated by the application.</p>
<p>Orgdef files consist of a small number of <a href="#header">header “statements”</a> followed by <a href="#divisions">definitions of organ divisions</a>, listing their stops and other controls and the numbers assigned to them.</p>
<p><b>NB</b> There are two versions of the orgdef format available, Version 2 and Version 3. The code in this distro (1.0.9) supports both. Version 3 is considerably cleaner and easier to understand and prepare, and upgrade to it is recommended. Version 2 support will be removed when I can determine that there are no more Version 2 orgdefs in existence. This document will mark differences.</p>
<p>A complete example, Piotr Grabowski’s sampleset of the Mascioni organ at Giubiasco, Switzerland, in Grand Orgue, is <a href="#example">at the end</a>, in both new and old formats.</p>
<h3>YAML</h3>
<p>Orgdef files are <span class="smc">YAML</span> files. <span class="smc">YAML</span> (“<span class="smc">YAML</span> ain’t (a) mark-up language”) is a modern text formalism used by much software. While little more than a straightforward and almost obvious way of using indentation, brackets, braces, colons to express structured data, it is nevertheless well-defined and regular. All the control files of this software suite, including organ definitions, are expressed in it. There is an example, and eight simple rules including terminology, as well as pointers to further resources on the web <a href="index.html#yaml">in the “index” document here.</a></p>
<h2>Header statements</h2>
<p>The orgdef file, at top level, is actually a <span class="smc">YAML</span> mapping, so order doesn’t matter (although placing <b>Name</b> and <b>Application</b> at the top, as well as one or more comments describing the Web source/documentation of the instrument, are reasonable). For Grand Orgue, <b>ProloguePath:</b> is <b>required.</b> These keywords <b>must</b> be at the left-hand side, i.e., no indentation, or they will not be recognized as top-level by <span class="smc">YAML</span.</p>.
<h3 id="header">Required header statements</h3>
<dl>
<dt>Name</dt>
<dd><p>This is the “name” of the instrument. Right now (stupidly) it must be the same as the file name of the containing orgdef file, but without the <tt>.orgdef</tt>. In that regard, this is basically for checking that you found the right file. If you have different ones for the same organ for Hauptwerk and GrandOrgue, you must name them differently.</p></dd>
<dt id="application">Application</dt>
<dd><p>This tells our software which VPO application is being used; it must be either <tt>Hauptwerk</tt> or <tt>GrandOrgue</tt>. There are no other choices.</p></dd>
<dt>Version</dt>
<dd><p>Must be <b>2</b> or <b>3</b>. Use Version 3 for new files. Differentiates the current model of these files from the earlier one (and possible models yet to come.) This will affect the kinds of statements and other definitions are required or supported.</p></dd>
<dt>Channels <span style="color:red">Version 2 only—do not supply in 3</span></dt>
<dd><p>This is the most critical element. It s a <span class="smc">YAML</span> “list”, in the required square brackets, of the speaking divisions of the organ, <i>in channel order</i>, thus telling my software what channel is associated with each. Both Hauptwerk and Grand Orgue seem to assign channels for every organ seen so far in bottom-up order, that is, the pedal division is always on 0, the lowest manual 1, and succeeding manuals bottom-to-top successive integers. Thus, the <tt>Channels</tt> statement will be a list of the playable divisions (other than floating divisions) from physical bottom to top. Classic-style Dutch organ example: </p>
<pre>
Channels: [Pedaal, Rugwerk, Hoofdwerk, Borstwerk]
</pre>
</dd>
</dl>
<h3>Optional header statements</h3>
<dl>
<dt>Synonyms <span style="color:red">Version 2 only—do not supply in 3</span></dt>
<dd><p>This optional header item defines possible alternate names for divisions. This can include orthographic differences (<b>Récit</b> vs. <b>Recit</b>, as well as confusing spelling differences, e.g., <b>Positif</b> vs. <b>Positiv</b>). And some organs are insistent on calling their divisions by Roman numerals of the manuals counted from bottom up, which can be annoying. The item is a mapping of the “official names” of the divisions as defined by this file to a bracketed <span class="smc">YAML</span> list of alternate names. The names may include spaces.</p>
<p>I strongly recommend staying within national traditions and eras of organ building. While supplying <b>Pedal</b> for <b>Pedaal</b> or <b>Pédale</b> seems reasonable, <b>Swell</b> for <b>Récit</b>, in my opinion, is not. Lack of restraint here is guaranteed to confuse organists (perhaps including yourself at a later date) who examine your registration files.</p>
<p>Some organs are actually ambiguous in this regard, referring to divisions in Roman numerals on stop knobs even though they have traditional names. This is an ideal use for this item.</p></dd>
<dt id="prologue">ProloguePath</dt>
<dd><p>For Grand Orgue instruments, this is <b>required</b>.
It is the orgdef-relative pathname (usually just a file name, i.e., in the same directory) of a <span class="smc">MIDI</span> file you are required to prepare. Please see <a href="#Initialization">Initialization</a> for detailed instructions.</p></dd>
<dt id="prologuename">PrologueExpectedName</dt>
<dd><p>For Grand Orgue instruments, but optional. Allows checking to make sure the prologue file specified by <b>ProloguePath</b> is the correct one. The value is the name of the instrument as it appears in the first <span class="smc">MIDI</span> event of that file. Please see <a href="#Initialization">Initialization</a> for detailed instructions.</p></dd>
<dt id="controlsdefaulton">ControlsDefaultOn</dt>
<dd><p>For Hauptwerk only, at present. When an <tt>insreg</tt>-generated <span class="smc">MIDI</span> file starts up on Hauptwerk, it resets all the stops and other controls known in the orgdef, except for stops that the score actually calls for at the beginning of the piece, which, instead of being reset, are drawn.</p>
<p>In some cases, this is not correct. Certain controls must be drawn, not reset, without specific mention. For instance, the <i>Calcant</i> (blower) on some instruments (i.e., where it has a visible control), the <i>Copule G.O.</i> on the “G.O.” which allows stops to speak there at all, as well as divisional ventils (<i>Afsluiter</i>), which cut off wind supplies to whole chests. Hauptwerk “General Cancel” knows to leave these controls alone. If the organ you are preparing in fact has such controls, they must be listed here by (any) division in which they appear. Failure to do so will cause them to be reset for each piece prepared, which would be disastrous. Example:</p>
<pre>
ControlsDefaultOn: {Control: Calcant, Grand Orgue: Copule G.O.}
</pre>
<p>If there are no such controls on the instrument, this option should be omitted.</p></dd>
<dt id="DefaultP1">DefaultP1</dt>
<dd><p>Stop addresses in both Hauptwerk and GrandOrgue are pairs of integers each from 0–127, known here as <tt>P1</tt> and <tt>P2</tt>. In Hauptwerk, <tt>P1</tt> is usually 86 (large organs require 85 for some stops); in GrandOrgue, <tt>P1</tt> is usually 0. The orgdef system supplies those defaults:</p>
<pre class="pfm" style="margin-bottom: 0px;padding-top: 0px;">
Hauptwerk: 86
GrandOrgue: 0
</pre>
<p>If you are defining a stop or coupler whose <tt>P1</tt> is these, you need only supply <tt>P2</tt> as address. But if its <tt>P1</tt> is other, you must supply a 2-element list, e.g., <tt>[85, 126]</tt>.</p>
<p>If you are writing an orgdef for an <i>instrument</i> where these defaults are somehow not <i>the appropriate defaults</i>, you may override them with the optional (as of distro <b>1.0.9</b>) <b>DefaultP1</b> header statement, whose value is the needed default. Otherwise, it is not (and should almost never be) necessary.</p>
<p>The header’s <b>DefaultP1</b> (and the orgdef system’s) can, in Version 3, be overridden not only by explicit <tt>P1</tt>’s in stop addresses, but by an optional per-division setting. See <a href="#divdefp1">divisional <b>DefaultP1</b></a>.</p>
</dd>
<dt id="stopmodel">StopModel</dt>
<dd><p>By and large, the stops and couplers for Hauptwerk and Grand Orgue are operated in the same way for each instrument (but differently between those two applications), i.e., <span class="smc">MIDI</span> “SysEx” commands for the former and “Control Change” for the latter. However, some Hauptwerk instruments operate their stops with “Control Change” sequences (but not identically to the way it is done on Grand Orgue). See <a href="#hwaltcc">this section</a> for instructions on discovering whether this is the case for you.</p>
<p>If it is, you must tell the orgdef system so by including this header statement naming the model to be used and the channel to which the commands must be directed (determinable from the experimentation described):</p>
<pre class="pfm" style="margin-bottom: 0px;padding-top: 0px;">
StopModel: {Name: CommonSwitch, Channel: 1}
</pre>
<p>If the channel were 0, which is the default for <b>CommonSwitch</b> (which is used for controls other than instrument-defined stops), but not what has been observed in the instruments manifesting this,</p>
<pre class="pfm" style="margin-bottom: 0px;padding-top: 0px;">
StopModel: CommonSwitch
</pre>
<p>would suffice. If, however, the channel required is channel 1, as is common, the stop model</o>
<pre class="pfm" style="margin-bottom: 0px;padding-top: 0px;">
StopModel: CommonSwitch1
</pre>
<p>may be used.</p>
<p>No other stop model options at this time are relevant.</p>
</dl>
<a name="division"></a>
<h2>Division listing</h2>
<p>The stop-list by division comprises the bulk of the orgdef file, and is usually at the end (as it is a <span class="smc">YAML</span> mapping, it actually need not be). It is a multiline mapping (by “official” division name) of/to multiline mappings of stop (or other control) names to <i>addresses</i> (or, in Version 3, <a href="#stopatts">stop attribute maps</a>). <b>Take care to indent</b> all stops in the division identically. Rules for consistent expression of stop and control names will be given <a href="#conventions">shortly</a>, as will <a href="#ascertain">instructions for ascertaining</a> addresses.</p>
<p>In <b>Version 3</b>, an <b>Attributes</b> “pseudo-stop” <b>must</b> be provided as well (and its absence will be diagnosed). See <a href="#divatts"><b>Division Attributes</b> below.</a></p>
<p>Each stop is given as mapping element of its name to its address. An address is (conceptually) a pair of integers (known as <tt>P1</tt> and <tt>P2</tt>), which can be given as a two-element <span class="smc">YAML</span> list, e.g.,</p>
<pre>
Âne Dotard 8': [86, 25]
</pre>
<p><tt>P1</tt> and the brackets may be omitted if its value is the same as an in-effect default (see <a href="#DefaultP1"><b>DefaultP1</b></a> and <a href="#divdefp1">divisional <b>DefaultP1</b></a>), e.g.,</p>
<pre>
Flûte Cûte 2': 22
</pre>
<p>It is common (but not always needed) to define a pseudo-division named <b>Control</b> or the like (the name <b>General</b> may not be used) containing couplers and controls not associated with any division, in which case, that name must be used in registration files to access them.</p>
<p>Although <span class="smc">YAML</span> ignores the order of mapping pairs, it is conventional in organ building and literature to list stops of a division in a particular order, i.e.,</p>
<ul class="lid">
<li>Non-compound flue stops, from deepest/lowest pitch to highest.</li>
<li>Compound stops (mixtures, cornets, sesquialteras, etc.), from most ranks to fewest.</li>
<li>Reed stops, from deepest pitch to highest.</li>
</ul>
<p>Orgdef stop listings should comply (in particular, to be most useful to organists, do <b>not</b> list by address order). See any <a href="https://en.wikipedia.org/wiki/Organ_of_the_Basilica_of_St._Martin_(Weingarten)">real organ specification</a> for real examples, but here is a fanciful example (of a specification, not in an orgdef):</p>
<pre class="pfm">
Negatif:
Burton 16'
Principal 8'
Asst. Principal 4'
Nasal Flout 2-2/3'
Ocarina 1'
Grand Mixture viii-ix
Humble Mixture iii
Bombardier 16'
Crumpet 8'
Hobo Vagrans 8'
Regal Chivas 4'
</pre>
<a name="divatts"></a>
<h3>Division Attributes — <span style="color: red">Version 3 only</span></h3>
<p>In Version 3 (and hopefully up), each division <b>must</b> include among the “register of its registers” a “pseudo-stop” named <b>Attributes</b> which at very least tells to what <span class="smc">MIDI</span> channel it is routed, or affirms its status as a non-speaking division (e.g., <b>Control</b>). This new feature replaces the former <b>Channels</b> and <b>Synonyms</b> global header statements in a more modular and obvious way. Here is an example from the Walcker organ at the Martinikerk, Doesburg:</p>
<pre class="pfm">
II:
Attributes:
Synonyms: Schwellewerk
Channel: 2
Expression: Yes
</pre>
<p>Here are the known division attributes. Other keywords will be diagnosed as errors. One or the other of <b>Channel</b> or <b>NonSpeaking: Yes</b> is required; others are optional as needed.</p>
<dl>
<dt>Channel</dt>
<dd><p>This is the <span class="smc">MIDI</span> channel to which the VPO should route notes set for this division. In every organ seen so far in both Hauptwerk and Grand Orgue, the pedal is channel 0, and the manuals in bottom-to-top order are 1, 2, 3, etc. Nevertheless, we have no way of knowing which is which unless you specify this properly.</p></dd>
<dt>NonSpeaking: Yes</dt>
<dd><p>The operand/value must be <b>Yes</b>. This is required for “non-speaking” (e.g., <b>Control</b>) divisions such as aggregations of organ-wide controls or couplers, or secondary appearances of couplers, that you so want to aggregate. The requirement to have this is to minimize the chances of forgetting to specify a channel in speaking divisions.</p></dd>
<dt>Expression</dt>
<dd><p>Used for divisions enclosed in swell boxes with operable swell controls in the VPO. The operand is almost always <b>Yes</b> in that case. However, a case has been seen (Hauptwerk Caen Positif) where a division’s expression control is routed to the channel of a different division, in which case the main name of that division is the operand. (That virtual organ cannot be repaired without breaking <span class="smc">MIDI</span> files).</p></dd>
<dt id="divdefp1">DefaultP1</dt>
<dd><p>This item allows the <tt>P1</tt> address number for stops in this division to be defaulted to the number which is its operand. Some instruments, such as the Hauptwerk version of Piotr Grabowski’s Giubiasco digitization, are encoded this way, i.e., with different <tt>P1</tt>’s for each division. See <a href="#DefaultP1"><b>DefaultP1</b></a>.</p></dd>
<dt>Synonyms</dt>
<dd><p>This item defines possible alternate names for the division. This can include orthographic differences (<b>Récit</b> vs. <b>Recit</b>, as well as confusing spelling differences, e.g., <b>Positif</b> vs. <b>Positiv</b>). And some organs are insistent on calling their divisions by Roman numerals of the manuals counted from bottom up, which can be annoying. The item is a mapping of the “official names” of the divisions as defined by this file to a bracketed <span class="smc">YAML</span> list of alternate names (brackets not necessary if there is only one). The names may include spaces.</p>
<p>I strongly recommend staying within national traditions and eras of organ building. While supplying <b>Pedal</b> for <b>Pedaal</b> or <b>Pédale</b> seems reasonable, <b>Swell</b> for <b>Récit</b>, in my opinion, is not. Lack of restraint here is guaranteed to confuse organists (perhaps including yourself at a later date) who examine your registration files.</p>
<p>Some organs are actually ambiguous in this regard, referring to divisions in Roman numerals on stop knobs even though they bear traditional names elsewhere.</p></dd>
</dl>
<h3>Stop multiple appearances (<i>avatars</i>)</h3>
<p>The system allows multiple seeming-definitions for the same stop or control, which are called its <i>avatars</i>. The conventions differ completely between Version 2 and Version 3 orgdefs; inadequacy/ugliness in the Version 2 method was the largest motivation for Version 3. Version 3 will be described first.</p>
<h4 style="padding-left:40px">Stop synonyms and avatars in Version 3</h4>
<p>In Version 3, optional additional names for a stop on a given division, to correct/amplify abbreviations or supply backup for vendor or builder language errors (e.g., <i>viola di gamba</i> for <i>viola da gamba</i> at Doesburg) are supplied via the <b>Synonyms</b> “stop attribute”; see <a href="#stopatts"><b>Stop Attributes</b></a> below.</p>
<p><i>Secondary avatars</i>, appearances of a control (including a stop control) from one division (the <i>primary avatar</i>) in another, are handled straightforwardly as well. Note that a secondary avatar is not the same as a borrowed stop in traditional (<i>a forteriori</i> theatre) organ-building, whereby the keys or pedals of one division can play a stop “borrowed” from another; here, it is simply multiple equivalent “knobs”. A new <a href="#stopatts"><b>stop attribute</b></a>, <b>Refer</b>, defines this relationship clearly and (unlike Version 2) unambiguously.</p>
<p>As before, names of different avatars of the same control in different divisions need not bear any or all identical names.</p>
<h4 style="padding-left:40px">Stop synonyms and avatars in Version 2</h4>
<p>In Version 2, equality of address links stop avatars and synonyms to each other. This makes it impossible to detect and diagnose inadvertent address collision/reuse. Simple synonyms in the same division appear as so:</p>
<pre>
Viola di gamba: 22
Viola da gamba: 22
</pre>
<p>Although the correct Italian name of the alluded-to string instrument is <i>Viola da gamba</i>, the stop-control on the Sonus Paradisi Hauptwerk sampleset of the Walcker instrument at Doesburg, Holland, says <i>Viola di gamba</i>, and the rule that the stop name as it appears must be supported requires that both be supplied. This is also useful to expand and second-guess abbreviations appearing on stop knobs:</p>
<pre>
Gr.-Bourdon: 44 #as it appears
Grand Bourdon: 44
Gross Bourdon: 44 #esszet often given as "ss"
Groß Bourdon: 44
</pre>
<p>Another use of this is to duplicate couplers and other controls between “Control” pseudo-divisions and the divisions to which the they apply (<i>secondary avatars</i>). This is common for controls such as ventils (<i>Afsluiter</i>), which you may want to appear as such on their controlled division and as <i>Afsluiter Borstwerk</i> in your “Control” division. Note that the names of appearances of the same control in different divisions need not be the same.</p>
<a name="stopatts"></a>
<h2>Stop Attributes<span style="color:red">—Version 3 only</h2>
<p><i>Stop attributes</i> are specified by a <span class="smc">YAML</span> “mapping” given their names and values, <i>as the “value” associated with the stop name</i>, instead of an address. The address normally given is the value of the <b>Address</b> stop attribute when attributes are given. Thus, the following three stop definitions are equivalent:</p>
<pre class="pfm">
Lieblich Gedekt 16': 42
Lieblich Gedekt 16': {Address: 42}
Lieblich Gedekt 16':
Address: 42
</pre>
<p>Stop attributes are not to be confused with <a href="#divatts">division attributes</a>. Stop attributes are listed under a stop name; division attributes are listed under the name of the <b>Attributes</b> pseudo-stop in the division involved.</p>
<p>It is not necessary for a stop to have an attribute mapping; if, however, the stop has alternate in-division names, or is itself a “secondary avatar” reference to a stop or control on another division, one must be supplied. If one is supplied, one or the other, and only one, of the two attributes <b>Address</b> or <b>Refer</b> must be supplied. Here are the known attributes:</p>
<dl>
<dt>Address</dt>
<dd><p>The numerical address of the stop in the VPO’s <span class="smc">MIDI</span> space, as either a pair/list (<tt> [85, 92] </tt>) or a single number, the second of the pair, with the first taken from the application default or the <a href="#DefaultP1"><b>DefaultP1</b> header statement</a> or <a href="#divdefp1">divisional <b>DefaultP1</b> attribute</a> if either of the latter is present. (There are other undocumented forms.)</p></dd>
<dt>Refer</dt>
<dd><p>This defines the stop as a secondary avatar, in this division, of the stop it names in another division (the <i>primary avatar</i>). The value of the attribute is a two-element list of the name of the division where the primary avatar resides, and its principal name. Both names must be the exact principal (main) names, in correct case, in order to match— this strictness is required because the resolution of avatars must occur before the name-dictionaries of the instrument are computed. The target cannot be another secondary avatar. Example:</p>
<pre class="pfm">
Control: #division
Afsluiter Rugwerk: [Rugwerk, Afsluiter]
</pre>
</dd>
<dt>Synonyms</dt>
<dd><p>Optional synonym(s) for the stop or control, or avatar, in this division, such as used to address the effects of faulty spellings or abbreviations. If there is more than one synonym given, their comma-separated list must be enclosed in [brackets].</p></dd>
</dl>
<a name="conventions"></a>
<h2>Stop-name consistency conventions/rules</h2>
<p>Although <a href="insreg.html#matching"><tt>insreg</tt>'s stop-name matching</a> is flexible (and you should look at those rules now), conventions have to be followed in stop-name expression to make them work expectably. While, as a last resort, duplicate entries as described above are possible, if these rules are followed, that should rarerly be necessary.</p>
<ul>
<li>The goal is to provide the stop name as closely as possible to the language which appears on the stop-knob or Hauptwerk jamb control, which we will refer to as the <i>prototype</i>.</i>
<li>The capitalization used in the protoype should be duplicated exactly.</li>
<li>Many prototypes are multiple line; the orgdef stop listing must be single-line.</li>
<li>Do not use multiple consecutive spaces, especially accidentally.</li>
<li>Abbreviations should be copied, with periods, if used in the prototype, with a duplicate entry expanding them. Abbreviations for “ranks” etc., are recognized innately and do not necessitate a duplicate entry.</li>
<li>The number of ranks of compound stops must be given as Roman numerals (e.g., ii, iv, etc.), even if the prototype uses Arabic (2, 3) rules. The measure of compound ranks of varying composition are written with a single dash (e.g., <tt>ii-vii</tt>. Upper and lower case are equivalent, but it is preferable to use the case of the prototype. Compound stops given with a pitch designation as well as a rank count, unfortunately, must “lose the pitch designation.”</li>
<li>Characters with diacritical marks are <b>required to be entered accurately</b> in Unicode, e.g., <tt>Flöte, Flûte, Trémolo</tt>.
<li>Gratuitous and arbitrary dashes (<tt>Orch-Flöte</tt> vs. <tt>Orch. Flöte</tt>) should be as in the prototype.</li>
<li>Some prototype controls have stop-numbers, e.g., <tt>14 Flauto Italiano 2'</tt>. The stop number must go, i.e., not be used. This may be fixed some day, although support of these numbers as shorthands for stops in registration control seems ugly.</li>
<li>Apostrophe characters meaning “feet” must be the real ASCII simple single-quote mark—these: ' ' ' (hex 27, octal 47), not balanced Unicode typographical quotes (these: ’ ’ ’, hex 2019, octal 20031). If you routinely use complex keyboards, <b>take note!</b></li>
<li>Fractions are expressed with slash (<b>/</b>). “One and three-fifths” and the like are expressed with ASCII dash, e.g. <tt><b>1-3/5'</b></tt>. </li>
</ul>
<a name="ascertain"></a>
<h2>Ascertaining stop addresses</h2>
<p>There seems to be no easier way to ascertain stop addresses than experimentation. The experiment consists of trying them all, by manipulation, and seeing what <span class="smc">MIDI</span> they generate. If you have some amazing looping <span class="smc">MIDI</span> tool that can display VPO control output as you generate it, and your VPO is so set up as to tell it, well, I don't.</p>
<p>The standard technology here is to conduct one or more <span class="smc">MIDI</span> recording sessions in your VPO, followed by inspecting the output with the <a href="dumpmidi.html">supplied <tt>dumpmidi</tt> tool</a>, or any you might prefer. While you might have a better technology, my technique has been, while recording, to play a single note, and then draw (turn on) a stop, play another, and retire the stop (turn it off), making careful note on paper or in a spreadsheet of which specific note (they should all be different) I play before or after which specific stop. You should write down the notes in <a href="https://en.wikipedia.org/wiki/Scientific_pitch_notation">standard pitch notation</a> (where Middle C is C4, etc.) because that is how <tt>dumpmidi</tt> reports them.</p>
<p>Or, as I have also done, choose one column of an organ or simple jamb display for one recording session, and manipulate each stop, top to bottom, on and off, making no mistakes while recording, and discover the addresses for the controls in that column. Retiring the stops (in addition to drawing them), of course, isn’t strictly necessary, but increases your chances of finding what you want in the output.</p>
<p>When this has been done, you can dump the <span class="smc">MIDI</span> file with <tt>dumpmidi</tt>, perhaps with redirected file output, inspect it with an editor, find each note, and examine and record the stop addresses issued by the VPO app. This is easy. Here are examples for both apps.</p>
<h3>Hauptwerk example (<tt>dumpmidi</tt> output)</h3>
<pre style="padding-left:40px">
0 0 1758 37782 10+1.782 SysEx: data=[11, 125, 57, 114, 16, 0, 0, 86, 109, 0, 0]
0 0 2306 40088 11+11/125 SysEx: data=[11, 125, 57, 114, 16, 0, 0, 86, 98, 0, 0]
0 1 6708 46796 On C 2 12+2.796 v 127
0 1 450 47246 Off C 2 12+3.246
<span style="color:blue">0 0 3786 51032 13+379/125 SysEx: data=[11, 125, 57, 114, <span style="color:green;font-weight:bold;">16</span>, 0, 0, <span style="color:red;font-weight:bold;">86, 60</span>, 0, 0]</span>
</pre>
<p>Here, I have played low C (i.e., C2) on the lowest manual (channel 1), and then drawn the <b>Flötenbass 8'</b> on the Pedal at Doesburg. The two numbers in red, the eighth and ninth positions in the <tt>data</tt> array of the following “SysEx” event, are the <tt>P1</tt> and <tt>P2</tt> of that stop. Had I instead retired this stop, the “16” in the fifth array position would be “17”. All Hauptwerk stop manipulations ... mostly ... will look like this.</p>
<h3 id="hwaltcc">Control-change style Hauptwerk example</h3>
<p>While all Sonus Paradisi Hauptwerk instruments I have seen so far employ “SysEx” events as just shown, at least Piotr Grabowski's Giubiasco instrument for Hauptwerk seems to use “Control Change” <span class="smc">MIDI</span> commands instead (similar but not identical to Grand Orgue). If the dumped record of your Hauptwerk experiment session looks unlike the above but like this,</p>
<pre style="padding-left:40px">
0 1 1720 60396 On F 3 16+0.396 v 33
0 1 418 60814 Off F 3 16+0.814
<span style="color:blue">0 <span style="color:red;font-weight:bold">1</span> 2624 63438 16+3.438 Control Change: NRParm MSB (99) to <span style="color:red;font-weight:bold">16</span>
0 <span style="color:red;font-weight:bold">1</span> 0 63438 16+3.438 Control Change: NRParm LSB (98) to <span style="color:red;font-weight:bold">53</span>
0 <span style="color:red;font-weight:bold">1</span> 0 63438 16+3.438 Control Change: Data Entry MSB (6) to 127
0 <span style="color:red;font-weight:bold">1</span> 0 63438 16+3.438 Control Change: Control (38) to 127
</span></pre>
<p>this must be the case for you. This is the 8' <i>Bordone</i> on the <i>Positivo</i> at Giubiasco being drawn. The red 16 and 53 are its <tt>P1</tt> and <tt>P2</tt>, respectively. The two 127’s signify drawing the stop as opposed to retiring it (in which case they would both be 0). Note the red 1’s in the <i>channel</i> column to the extreme left; the control changes must be directed (in this instrument at least) to <span class="smc">MIDI</span> Channel 1.</p>
<p>If you have a Hauptwerk instrument for which this is the case, you must declare that and the channel so identified in the orgdef. See the <a href="#stopmodel"><b>StopModel</b></a> header statement.</p>
<h3>Grand Orgue example (<tt>dumpmidi</tt> output)</h3>
<pre style="padding-left:40px">
0 1 1231 8124 On D 2 1+0.137 v 65
0 1 97 8221 Off D 2 1+0.139
<span style="color:blue;">0 0 2712 10933 1+0.185 Control Change: NRParm MSB (99) to <span style="color:red;font-weight: bold;">0</span>
0 0 0 10933 1+0.185 Control Change: NRParm LSB (98) to <span style="color:red;font-weight: bold;">18</span>
0 0 0 10933 1+0.185 Control Change: Data Entry MSB (6) to 127</span>
0 1 3380 14313 On E 2 1+0.242 v 61
0 1 118 14431 Off E 2 1+0.244
</pre>
<p>Here, the <b>Viola da Gamba 8'</b> on the <i>Grande Organo</i> was drawn between playing D2 and E2 (the lowest D and E) (on the <i>Positivo</i>, but you needn’t know that) at Giubiasco. <span class="smc">MSB</span> and <span class="smc">LSB</span> are “most significant byte” and “least significant byte”, and <tt>NRParam</tt> “non-registered parameter”. The red numbers, here 0 and 18, are <tt>P1</tt> and <tt>P2</tt> of that stop. The “127” in the next event means “draw (turn on) stop”. Were we retiring the stop, it would be 0. All Grand Orgue stop manipulations will look like this.</p>
<a name="Initialization">
<h2>Organ System initialization</h2>
<p>All of the issues and their motivations and policies are fully described <a href="insreg.html#Initialization">here</a>. What follows is what is incumbent upon orgdef authorship.</p>
<p>See also <a href="#controlsdefaulton"><b>ControlsDefaultOn</b></a> for Hauptwerk.</p>
<h3>Preparing a Grand Orgue prologue file</h3>
<p>For Grand Orgue instruments, my tools require a <b>Prologue file</b>, which is nothing more than a <span class="smc">MIDI</span> file written by Grand Orgue from the instrument being used, whose contents (the first second’s worth) it merely copies into the <span class="smc">MIDI</span> file it itself is writing. The person preparing the organ definition file must provide such a Prologue file, and specify its name in the organ definition.</p>
<p>Because Grand Orgue captures the organ settings at the time it records <span class="smc">MIDI</span> files, you <b>must reset all registrations and other controls</b> before recording it! To make the prologue file, simply so reset all registrations and controls, begin a <span class="smc">MIDI</span> recording sesssion, play a note or two (which should generate no sound because no stops are drawn) and end the recording session. Then give the resulting <tt>.mid</tt> <span class="smc">MIDI</span> file any name you wish (hopefully mentioning the instrument, e.g., <tt>WeingartenGOPrologue.mid</tt>), and copy it (if needed) to the directory where you intend it to stay. (No, the one or two notes won’t be inserted in all pieces using it.)</p>
<p>If you use the <a href="dumpmidi.html"><b>dumpmidi</b> tool</a> to inspect the file you create in this way, you will see as its first <span class="smc">MIDI</span> event an <tt>Instrument Name</tt> event like this:</p>
<pre class="pfm">
0 0 0 1+0 Instrument Name: "Giubiasco"
</pre>
<p>You can then place this name in the <b>orgdef</b> as the value of <a href="#prologuename"><b>PrologueExpectedName</b></a> header statement to double-check that the correct file is obtained when the <b>orgdef</b> is used.</p>
</dd>
<h3>Initialization policy futures</h3>
<p>Note that even were I to come to understand each of the events in what I call the Grand Orgue prologue, that application itself will always remain the more qualified expert on exactly which are necessary, so the current policy is reasonable.</p>
<p>On the Grand Orgue side, a way to omit prologues entirely (as in Hauptwerk) might be useful as an option, but that simply does not work, and it is not clear why, but the implication is that here are “necessary” instructions in them (if they are necessary, why doesn’t Grand Orgue do them by itself before replaying <span class="smc">MIDI</span> files?). Then, as proposed for Hauptwerk, “reset listed controls” could be an option, either per-piece or per-instrument.<p>
<h2>Command-line <tt>organ.py</tt> command</h2>
<p>The system program <tt>organ.py</tt> can be invoked (as a python script) to test an orgdef you are preparing, without the need for a score and registration file. To use, simply</p>
<pre class="pfm">
python organ.py StSulpice.orgdef
</pre>
<p><tt>organ.py</tt> (which is used subroutinally by <tt>insreg</tt>) invoked in this way will attempt to read, parse, and understand the organ defined by your file. In this way, you can test that you got the syntax and semantics correct, all the correct things linked to each other, all the necessary fields supplied. It works for Version 2 or Version 3 orgdefs (it <i>has to</i>). If it succeeds, it will print out an orgdef <span class="smc">YAML</span> recreated from its understanding.</p>
<p>The order in which stops and divisions are listed will not likely be as you gave them; the orderings of <span class="smc">YAML</span> “mappings” and Python “dictionaries” are undefined, and <tt>organ.py</tt> chooses its own orders for divisions and stops.</p>
<a name="example"></a>
<h2>Complete Giubiasco (Grand Orgue) <tt>.orgdef</tt>, Version 2</h2>
<p>Here is the entire, operative <tt>Giubiasco.orgdef</tt> for Piotr Grabowski’s sampleset of the 2008 Mascioni organ at Giubiasco, Switzerland, for Grand Orgue.</p>
<pre style="padding-left: 40px;">
Name: GiubiascoGO
# https://www.piotrgrabowski.pl/giubiasco.html
Application: GrandOrgue
Version: 2
DefaultP1: 0
ProloguePath: GiubiascoGOPrologue.mid
PrologueExpectedName: Giubiasco
Synonyms:
Positivo Tergale: [Positiv, Positivo, Positif, I]
Grande Organo: [Grande, Grand Orgue, Grand, II]
Pedale: Pedal
Channels: [Pedal, Positivo Tergale, Grande Organo]
Divisions:
Positivo Tergale:
Bordone 8: 7
Flauto 4: 8
Quinta 2-2/3: 9
Principale 2: 10
Terza 1-3/5: 11
Larigot 1-1/3: 12
Cimbalo ii file: 13
Regale 8: 14
Tremolo: 15
Grande Organo:
I al II: 16
Principale 8: 17
Viola da Gamba 8: 18
Flauto a camino 8: 19
Voce umana 8: 20
Ottava 4: 21
Flauto conico 4: 22
Quintadecima 2: 23
Cornetto 2-2/3: 24
Ripieno iv: 25
Violoncello 8: 26
Zimbelstern: 28
Pedale:
Subbasso 16: 3
Flauto 8: 4
Ottava 4: 5
Contro Fagotto 16: 6
I al Pedale: 1
II al Pedale: 2
</pre>
<p></p>
<h2>Complete Giubiasco (Grand Orgue) <tt>.orgdef</tt>, Version 3</h2>
<pre style="padding-left: 40px;">
Name: GiubiascoGO
# https://www.piotrgrabowski.pl/giubiasco.html
Application: GrandOrgue
Version: 3
ProloguePath: GiubiascoGOPrologue.mid
PrologueExpectedName: Giubiasco
Divisions:
Positivo Tergale:
Attributes:
Channel: 1
Synonyms: [Positiv, Positivo, Positif, I]
Bordone 8: 7
Flauto 4: 8
Quinta 2-2/3: 9
Principale 2: 10
Terza 1-3/5: 11
Larigot 1-1/3: 12
Cimbalo ii file: 13
Regale 8: 14
Tremolo: 15
Grande Organo:
Attributes:
Channel: 2
Synonyms: [Grande, Grand Orgue, Grand, II]
I al II: 16
Principale 8: 17
Viola da Gamba 8: 18
Flauto a camino 8: 19
Voce umana 8: 20
Ottava 4: 21
Flauto conico 4: 22
Quintadecima 2: 23
Cornetto 2-2/3: 24
Ripieno iv: 25
Violoncello 8: 26
Zimbelstern: 28
Pedale:
Attributes:
Channel: 0
Synonyms: Pedal
Subbasso 16: 3
Flauto 8: 4
Ottava 4: 5
Contro Fagotto 16: 6
I al Pedale: 1
II al Pedale: 2
</pre>
<p></p>
<p>END</p>