GENPO - User Guide

This guide has been updated for version 0.9.7 .

Installation

You have two options for installing, either Download a pre-built binary package (if one exists for your platform), or download the current source package and compile it on your system.

Binary Install

A small number of binary packages may be available from the Download section, if there is one there that matches your system closely you could try to install and run it. Please do not ask me for other binary packages as I don't have the facilities to build or test them.

The binary package is self-contained, you should simply unpack it under your home directory, eg.

  cd
  tar xzvf genpo_0.8_rh9_bin.tar.gz
	    

Now skip down to the Operation section

Source Build and Install

If you have all the prerequisites installed, then the following steps should be all that is required to unpack and build GENPO...

  cd
  tar xzvf genpo-0.9.7.tar.gz
  cd genpo-0.9.7
  ./build.sh
	    

If you hit a problem please let us know via our mailing list.

Operation

Installing a Sound Font

There are two fundamentally different ways of getting organ sounds out of your computer: using a (hardware) wavetable synthesizer on a sound card, or using a software synthesizer to generate the sounds from the sound font. With modern processors there is little to choose between the two methods. I now tend to use a soft-synth as it provides controllable reverb which makes most organ sound fonts sound a lot more realistic.

Wavetable synthesizer

e.g. 'SoundBlaster' series

This is usually achieved with a command such as

  asfxload ~/sf/english_organ_102.sf2

Asfxload is not the most verbose program, if you get no feedback from the above command then it probably worked.

Software synthesizer

There are several soft-synths around including Timidity++ and FluidSynth, both of these can work well with GENPO.

I start fluidsynth with a command like this

fluidsynth -g 0.15 -C no -K 16 -m alsa_seq music/sf/english_organ_102.sf2

(Brief explanation: set gain quite low to avoid distortion, turn off Chorus, set up 16 channels, use ALSA, and load the specified sound font.)

There are several good graphical front ends to FluidSynth, I use QSynth and it works well.

If you want to use more than 16 simultaneous stops you will need to connect GENPO to two synths (giving up to 32 simultaneous stops). You may need to name the synths Jack Client Name differently in QSynth to be able to run two instances at once if you are using Jack with ALSA. N.B. There is no point trying to run individual soft synths with more than 16 channels with GENPO, that is not supported by standard MIDI.

Starting GENPO

You will have a directory genpo-0.9.7 containing the program and some sample configurations. While developing and testing new organ definitions it is recommended that you run GENPO from a terminal in order that you can see the output. To start the program from a terminal or X window do this...

  cd genpo-0.9.7/src
  ./genpo
	    

Unless you are having problems, there is no reason that you should not run GENPO from a desktop menu, icon or 'shortcut'. Setting this up is left as an exercise for the reader! From version 0.6 onwards, you may pass an organ definition filename to genpo as the first parameter - it will then be loaded automatically on startup.

Command-line Options

GENPO accepts a small number of options:

• --help - obvious!
• --verbose - Be a lot more verbose in the console while genpo is running
• --outport=<client>:<port> - tell GENPO to try to connect to a specific ALSA device to send it's output to. e.g. if FluidSynth is running as ALSA device 129:0 then you could start GENPO with the option "--outport=129:0"
• --singlestop - only permit one stop at a time to be pulled
• *.org - attempt to load the specified organ definition

Connecting to your synthesizer

As mentioned above you will need to have either loaded an organ sound font into your wavetable synthesizer, or have started a soft-synth with an organ font, in order to actually get any sound out of GENPO.

There are many ways of connecting GENPO to your synthesizer. Here are some:

1. Let GENPO try by itself - left to its own devices GENPO makes an attempt to connect to the first (lowest numbered) synthesizer device it can find on your system.
2. Tell GENPO to try to connect to a specific device using the --outport= option (see above)
3. Manually route the connections using a tool such as 'aconnect', 'kacconect' or 'qjackctl' once GENPO has started

Default Key Bindings

There are three special keys which always have the same effect, no matter what organ definition is loaded...

• Ctrl-P - Panic! This sends a note-off command to all channels (kills ciphers!)
• Ctrl-R - Reload. Reloads the current organ definition from file (handy if you are working on a new .org file)
• Spacebar - G.C. (General Cancel) - pushes in all stops

Features

• Up to 32 simultaneous stops/channels - from version 0.9.6 onwards
• Swell Pedal - from version 0.7 onwards MIDI controllers 4,7 and 11 are passed through to the synthesizer. No changes are required in the .org file
• Keyboard Presets/Thumb Pistons - from version 0.7 onward MIDI Program Change messages will trigger the corresponding Preset/Piston on the division. N.B. MIDI programs/preset start at number zero - so it may be clearer if you label your first piston '0' rather than '1'.
• Toe Pistons - from version 0.9.5 onwards you can specify whole-organ (combination) pistons intended to be triggered from a MIDI foot controller

Problems

No Sound

You did pull a stop didn't you...

I suggest checking things in the following order...

1. GENPO is connected either to your wavetable or soft synthesizer
2. SoundFont loaded? (if using wavetable synthesis)
3. Volume turned up on mixer?
4. Volume physically turned up?
5. Keyboard sending on right channel?

Organ Definition Files

One of the features of GENPO is that you can edit or create your own organ definitions to suit your own purposes. Here's how...

The organ definition (.org) files are XML text and conform to a DTD supplied with the software (the organ.dtd file). If this all sounds daunting, don't worry - you can just copy one of the supplied files and try editing it. Below is a sample file which uses all of the features available in the current version and explanatory notes.

Here is what it looks like when loaded...

And here is the definition, with a commentary on the right...

<?xml version="1.0" ?>                          This line is compulsory
<!DOCTYPE organ SYSTEM "organ.dtd">             Here we define the document type (just copy this!)

<!-- This is just a demo file -->               Yes - you can insert comments as you please

<organ>                                         OK, this is the 1st real line: we are defining an organ!

  <header>                                      The header contains general info about the instrument
     <organName>Sample Organ</organName>        The name of the Organ - it appears on the screen
     <soundFont>Jeux14.SF2</soundFont>          The name of the sound font to be used
     <description>Organ for demo</description>
     <acceleratorStyle>Qwerty</acceleratorStyle> Set to None to turn off, other values have no effect
  </header>

  <body>                                        This contains the 'guts' of the organ
    <division> Must define at least one 'division'...
      <divisionLabel>Pedal</divisionLabel> ...But this one is actually the pedal board!
      <divisionName lang="en">Pedal Organ</divisionName>	
      <midiChannel>3</midiChannel>	         This is the unique MIDI channel assigned to this division
	      Make sure the keyboard is transmitting on this channel
      <stop>                                    Now we define a number of stops
	<stopLabel>SubBass16</stopLabel> A unique internal label
        <stopName lang="en">Subbass 16'</stopName> The name that will appear for this stop
        <midiBank>0</midiBank>                  The MIDI bank containing the voice/patch  - usually 0
        <midiVoice>111</midiVoice>              The number of the MIDI voice/patch corresponding to this stop
        <stopColour>red</stopColour>             Colour this stop, divisionColour is also available
      </stop>                                   The end of this stop definition
       <stop>
	<stopLabel>Trombone16</stopLabel>
        <stopName lang="en">Trombone 16'</stopName>
        <midiBank>0</midiBank>
        <midiVoice>118</midiVoice>
        <velocity>100</velocity>                Override the default velocity (64) to boost this stop </stop>
    </division>

    <division> Another division
      <divisionLabel>Great</divisionLabel>
      <divisionName lang="en">Great Organ</divisionName>
      <midiChannel>1</midiChannel>	         A different MIDI channel
      <stop>
	<stopLabel>DoubleDiapason16</stopLabel>
        <stopName>Double Diapason 16'</stopName>
        <midiBank>1</midiBank>
        <midiVoice>61</midiVoice>
      </stop>
      <stop>
	<stopLabel>OpenDiapason8</stopLabel>
        <stopName>Open Diapason 8'</stopName>
        <midiBank>1</midiBank>
        <midiVoice>63</midiVoice>
      </stop>
      <stop>
	<stopLabel>OpenDiapason4</stopLabel>
        <stopName>Open Diapason 4'</stopName>
        <midiBank>1</midiBank>
        <midiVoice>3</midiVoice>
      </stop>

      <piston>                                  A piston
	<pistonLabel>0</pistonLabel>
        <pistonName>0</pistonName>      Piston will be invoked via Program Change 0 on this division
        <pistonStop>
          <pistonStopLabel>DoubleDiapasion16</pistonStopLabel> Must match another stop label in the definition
        </pistonStop>
        <pistonStop>
          <pistonStopLabel>OpenDiapason8</pistonStopLabel>
        </pistonStop>
        <pistonStop>
          <pistonStopLabel>OpenDiapason4</pistonStopLabel>
        </pistonStop>
      </piston>

      <coupler>                                 A coupler
	<couplerLabel>PedalToGreat</couplerLabel>
	<couplerName>Pedal to Great</couplerName>
        <coupleTo>Pedal</coupleTo>              Must match another division label in the definition 
      </coupler>

    </division>
    
    <toePiston> A Toe Piston (combination)   
            
 <pistonLabel>forte</pistonLabel>          
      <pistonName>0</pistonName>
      <midiChannel>2</midiChannel> Must specify a non-division MIDI channel for toe pistons
      <pistonStop>                            
	<pistonStopLabel>Trombone16</pistonStopLabel>  
      </pistonStop>
      <pistonStop>
	<pistonStopLabel>OpenDiapason8</pistonStopLabel>
      </pistonStop>
      <pistonStop>
	<pistonStopLabel>OpenDiapason4</pistonStopLabel>
      </pistonStop>
    </toePiston>
    
  </body>
</organ>
	   

Notes:

• Elements ending in "label" are used internally for cross-referencing, they should be short and unique within the .org file
• Elements ending in "name" contain the text that will appear on the organ console
• The order in which 'divisions' appear in the file dictates the order they are laid out on the GENPO display
• Stops, pistons and couplers also appear in the order given in the file

The current version of GENPO does not handle badly formed .org files particularly elegantly - it simply stops reading the file when it encounters an error - unpredictable behaviour may follow! You can get a good idea of where the error occurred as the program prints out the name of each division/stop/piston/coupler as it reads it. Look in your file for the last element that was printed out - the error will probably be in the next line. Here is the output from loading the above definition...

Manual Pedal Organ loading
        Stop: Subbass 16'
        Stop: Trombone 16'
Manual Great Organ loading
        Stop: Double Diapason 16'
        Stop: Open Diapason 8'
        Stop: Open Diapason 4'
        Preset: Full Organ
        Coupler: Pedal to Great
Coupling 1 to 0
Organ parsed
	    

If you do not see the final "Organ parsed" line, you definitely have an error in your definition as GENPO did not get to the end of your .org file.