 
OrganDoc.txt
------------
 
Organ.exe v. 1.2  by O. P. Martin
 
0. Introduction and overview
 
Welcome to the free program Organ version 1.2 .
 
The Organ program does not present fancy screen eye candy or allow you to play
the organ with a mouse. So, the resource footprint is small.  But, it does take
input from as many midi input devices as you have so you can play organ in real
time. It allows layering sounds from different soundfonts in the same preset.
It stays on until you turn it off. And, when you turn it back on, it reloads
all the defined soundfonts. Each program-select button on the music keyboard
translates into a general preset in my Organ software program. That is, the
registration for both manuals and pedal are all instantly changed at the press
of a button. The list of presets is defined in a control file that can be
edited with a text editor, and multiple control files can be switched in (one
at a time) with the File / Open command of the Organ program. Also provided is
the control file I personally use, which can be customized by the user if
desired. 
 
1. Installation
 
To install, unzip all contents of both the Organ12.zip and the OrganSF12.zip
files into the same directory, preferably "C:\Program Files\Organ12" .  You can
create a shortcut to Organ.exe on your desktop and/or Start menu.  You may like
to place such a shortcut in your StartUp folder.  The Organ program
automatically remembers the last control file that was loaded and whether the
organ was left on or off, and the program window starts minimized.
 
Please see the file "readme.txt" for a list of all the files and what they are.
 
2. Getting started
 
To get started, you will need to find out what devices are on your computer,
and perhaps edit a control file, such as the one I provided, Presets12.txt .
 
First, after starting the Organ program, restore the window and click on the
menu under Organ / Info.  This will prompt you for the name of a file to save
to.  This file will contain the list of midi input and output devices on your
computer.  I recommend you use the default name, ORGANmididev.txt .  You can
view this file with a standard text editor such as NotePad.
 
Now that you know the device numbers, you can edit a control file, such as the
example file Presets12.txt , to use these devices.  You must use a text editor
such as Notepad.  On my computer, there is one midi input device, 0, and
several midi output devices - I use Midi Mapper (MM) and Soundfont device (SF =
2).  For more on output devices, see section 3.2, below.  Note that each midi
device has 16 midi channels that can be used.  On the midi input device, the
sample file assumes the great will be set to channel 0, the swell to ch. 1, and
the pedal to ch. 3.  Note that these numbers, as with all numbers in Organ and
its control files, are zero-relative.  All the registration presets in the
sample control file are activated by hitting a program change button on the
great keyboard - device 0, channel 0.  These can, of course, be changed with a
little editing.
 
The supplied control file makes the above assumptions about device and channel
numbers and program folder and has been tested with a Sound Blaster PCI 512
sound card.  If your setup is similar, you may be able to start the Organ
program and play immediately without any changes.
 
For further details on editing the control file, see section 3, below.
 
Now that you have a control file ready, you can open it using the File / Open
menu on the Organ program.  Note that every time you make changes to a control
file, you must re-load it using File / Open in order for the changes to take
effect.  You can have as many different control files as you want, but only one
can be loaded at a time.
 
If the Organ is not On, you can turn it on using the Organ / On menu.  It will
stay on even if the window is minimized.  You can turn it off using Organ /
Off, in which case it will release the midi resources in case you want to use
another program which requires them, such as a sequencer or a soundfont editor.
 
I also recommend you set your sound card's reverb setting to "concert hall".
 
That's it!  Load the control file, turn the organ on, hit a program change
button on your keyboard, and you should be ready to play.
 
3.  Control file syntax
 
Besides white space characters, there are five types of non-white-space text
that can be in a control file.  They are comments, and Define, SFLoad, Control,
and Prog statements.  Case is sensitive so be sure to capitalize all keywords
properly.  All numbers are zero-relative.  Examples of all can be seen in the
file Presets12.txt .
 
3.1  Comments
 
Comments are C++ style and start with // and go to the end of the line.
 
3.2  Define statements
 
Define(  identifier,  devnumber ) .
 
You would think it would be nice to be able to define general-purpose
variables.  Such is not the case.  Sorry.  There are only two pre-defined
identifiers, MM for midi mapper device number, and SF for soundfont device
number.  You can only change the SF variable.  If left undefined, the symbols
can still be used and will default to the best available devices on your
system.  These two symbols can then only be used in the parameter of a Prog or
SFLoad statement (see sections 3.3 and 3.5, below) that calls for a midi output
device number.  Maybe in a future version of the program we can have more
variables, if the Lord is willing.
 
As for what number to use for devnumber, you can generate a text report of your
system's midi device numbers by using the Organ / Info menu command.  On my
system, I use device 2 for SF.
 
3.3  SFLoad statements
 
SFLoad(  devnum,  banknum,  "sf_filepath" ) .
 
This statement loads a soundfont file specified by "sf_filepath" into bank
banknum of midi output device devnum.  The devnum parameter can be the
identifier SF or any decimal number of a soundfont device.  As ever, you can
see examples in the file Presets12.txt .
 
3.4  Control statements
 
Control( devnum, chan, controlnum, initval ) = control_clause [ ,
control_clause ... ] .
control_clause:  Control( devnum, chan, controlnum, rangelo, rangehi  ) 
 
If there are one or more Control statements, each one can redirect and filter
incoming controller data and distribute them to one or more input channels. 
This is useful for implementing an "all swells to swell" function, as I have
done in the example file.  The range parameters are currently ignored.
 
3.5  Prog statements
 
Prog( dev, chan, patch ) : In_clause [ ; In_clause ... ] .
In_clause:  In( dev, chan, rangelo, rangehi ) = Prog_clause [ , Prog_clause ...
]
Prog_clause:  short_clause | long_clause
short_clause:  Prog( dev, chan, bank, patch, keyoffset, mute )
long_clause:  Prog( dev, chan, bank, patch, keyoffset, mute,  volume, pan,
finetune )
 
This is the heart and soul of the Organ program.  The first clause specifies an
input event, namely, pressing a program-change button on one of the music
keyboards.  This is followed by one or more In keywords, each of which can have
one or more Prog clauses.  The In clause directs a particular input channel to
play on one or more output channels.
 
Example:
 
Prog( 0, 0, 54 ) :                                // (7,7)
        In( 0, 0, 0, 127 ) =
                Prog( SF, 0, 0, 52, 0, 0 ,
                        111, 32,  -492  ) ,        // Choir Ah
                Prog( MM, 4, 0, 52, 0, 0 ,
                        125, 97, 492 ) ,        // Choir Ah mm
                Prog( SF, 5, 0, 91, 0, 0 ,
                        86, 64,  0   ) ;        // Space Choir 
        In( 0, 3, 0, 127 ) =
                Prog( SF, 3, 17, 14, 0, 0 ) ,        // Pedal Soft
                Prog( SF, 6, 20, 1, 0, 0 ,
                        92, 64, 0   ) .                // Bright Piano
 
In this example, when the user presses the program-change button on the great
(channel 0) for patch number 54, the organ program will direct the great to
layer 3 different choir sounds, and the pedal (channel 3) to layer a piano
sound and an organ sound.
 
4.  License
 
The Organ program, version 1.2, is being provided free on an as-is basis.  It
is copyrighted (c) by O. Philip. Martin, 2003 - 2005.  You may share only
complete, unmodified copies including all documentation with others, but you
may not charge money.  By downloading and/or using the program, you agree that
the author, O. Philip Martin, is held free from any liability, except as
provided by law.
 
5.  Donations
 
If you find the program useful, you are encouraged to donate.  This may help
the author to provide improved versions of the program.  You will be given the
opportunity to provide comments when you donate on-line with your credit card
through PayPal.  The suggested donation amount is $5.  To donate, go to:
 
        http://www.opmartin.com/
 
and scroll down to where it says "donate".
 
6.  Support
 
Since the program is being provided at no charge, and the suggested donation is
very small, there is no support available from the author at this time.
 
