XGL(1)

NAME
xgl - patch editor and librarian for synthesizers

SYNOPSIS
xgl [ patch-directory ]

DESCRIPTION
Xgl is an Xview version of glib, a screen-oriented librarian and patch editor for electronic synthesizers. It is structured in an attempt to make it easy to add support for new synthesizers.

Give the directory where you keep patch files after "xgl" on the command line, if that is different from the default that was selected at compilation. Say "xgl ." to use the current directory. When xgl starts up, you will see the librarian screen. Probably, the first thing you will want to do is load in a file of patches by selecting one of the command buttons at the top of the screen after "patch files". Once you have done that, you can select a patch with the left mouse button and hear how it sounds by pressing keys on the computer keyboard. When you've made some changes and want to hear the new voices in a midi tune, you can iconize xgl to make it release the output device for use by another program.

Xgl presents two types of menu screens: patch librarian, and patch editor. Depending on choices made when xgl was compiled, the patch librarian screen may provide a selection among several synthesizers, or perhaps among different sub-parts of a single synth. If so, the first thing to do when xgl starts up is to choose one, either by selecting one of the buttons at the top of the librarian screen to load a patch library file, or by selecting one of the numbered boxes after "Synth". Once you have made a selection, you will see two voice (i.e., "patch") banks at the lower left and right, each with scroll bars. If you have loaded a file of patches, the library bank, at the right, should display the names of the first 16 patches that were read in from the file.

The librarian part of the program manipulates 1 synth bank of voices (which can be uploaded to or downloaded from the synth), and 3 banks of library voices (which can be read/written to disk). The synth bank is displayed at the left, and one of the library banks at the right. You can change which library bank to display by selecting one of the boxes "bank 1", "bank 2", "bank3". Each synth has its own bank and three corresponding library banks, and when you select a different synth, its banks are displayed. However, the contents of the previous synth bank, its library banks and other settings (e.g. midi channel) are retained in memory, so you can go back to them.

From the librarian screen you can call up the patch editor to change or create an individual patch for a given synthesizer. (Choose "edit" from the menu you get by pressing the right mouse button in the area of one of the voice banks.) Details about using the librarian and the patch editor are given below.

The full glib distribution includes support files for various PCs -- IBM, Atari ST, Macintosh, Amiga, and for a number of synthesizers. Xgl is implemented only for Unix (Linux, actually) and X Windows. The current version of xgl, version 2.0, supports only the Soundblaster or opl3 fm cards, the Gravis Ultrasound, and the Kawaii K1 synths, and requires Hannu Savolainen's sound driver for Linux.

Using xgl - The librarian
The patch librarian is for moving patches around between files, uploading them to, or downloading them from, a synthesizer, and playing notes to hear how the patches sound. The librarian screen shows the synth bank of patches on the left, and the current (1 of 3) library bank on the right. The button(s) at the top of the screen labeled with the name of the synthesizer(s) are use to load patch files into the current library bank. One patch (at most) from one of the displayed banks is selected at a time -- it is shown shaded. To choose a different patch, position the mouse pointer over its name in a voice bank and click the left button. You can also use the arrow keys to go from voice to voice in a bank, or switch banks, and shift plus arrow goes up or down by eight.

Here are the controls available on the librarian screen:

quit -
    Click the left button on this control to exit from xgl.

patch files -
    Along the top of the screen are menu buttons for each of the available synthesizers. Use the right mouse button over one of these to see a menu of the patch files available for that synthesiser. This operation also selects that synthesizer as the current one, and the display of voice banks will change accordingly. Now you can choose a file with the left mouse button to load into the current library bank (the one at the right), or move the mouse away and click somewhere else if you don't wish to read a file in. The first time you look at the menu, it has to be constructed first, and that takes a few seconds, so please be patient. The file menus are only constructed once, and will not reflect any new files you have created after first using the menu (this is a bug).

-   Alternatively, clicking the left mouse button over one of these controls reads in the default patch file for that synth. Depress and hold down the left button to see what the default is, instead of clicking it, and then if you don't want to load that file, move the pointer away from the control before releasing the left button.

-   Each synthesizer is associated with a particular file suffix, e.g., ".sb" for the SoundBlaster, ".o3" for PAS16 or other opl3 cards, ".ks1" for Kawaii K1 single patches, ".gus" for the Ultrasound. Only files with the appropriate suffix are shown on the menu, but the suffix itself is not displayed. The default patch file for a synthesizer is the one named "std" followed by the the suffix (e.g. "std.sb" for the SoundBlaster), if there is such a file, or if not, the alphabetically first of the available files. The default is shown circled on the menu you get with the right mouse button. You can change the default by depressing the control key with the mouse pointer over some other choice on the menu, which then becomes the new default.

Library
    Click the left mouse button over "bank 1", "bank 2" or "bank 3" to select which library bank of voices to use.

Synth
    Click on one of the numbered boxes to choose a synthesizer. The numbers correspond in order to the synth buttons at the top of the screen. (If xgl was compiled to support only one synth, you will not see this item on the screen.)

Synth bank
    The scrollbar to the right of the 16 voices listed can be dragged or clicked to make other voices in the bank visible. Each voice name is preceded by a "number", generally consisting of a letter and a digit, but this can vary idiosyncratically with the synthesizer. Select a voice by clicking the left mouse button over it.

-   The right mouse button gives a menu of operations to perform on the selected voice, but DON'T USE THESE. Xview 3.2 has a bug that makes it impossible to get rid of this menu. Instead of using this menu, use the "lib operations" menu in the middle of the screen.

-   The selected voice may be in the library bank, instead of the synth bank. The operations are: "edit", which calls up the edit screen, "put", which replaces the voice with the current contents of the yank buffer (see below), and "swap", which exchanges the selected voice with the contents of the yank buffer. The "put" operation overwrites the selected patch, whose information is then lost.

Library bank
    This works like the synth bank.

save
    Click here to save the voices in the currently displayed library bank to the file named just below. Also, the name of the file which will be saved to can be seen by pressing and holding down the left mouse button -- then move the mouse away before releasing the button if you decide not to save to this file.

file
    The name of the file which was last read is displayed here, and this is also the default for saves. You can change this name by click in this area and typing in a new name, ending with a carriage return.

lib operations
    Click the right button here for a menu of operations to perform on the selected voice in either the synth bank or the library bank (see above).

note symbol
    This provides a visual indication of notes being played on the keyboard. That's all it's for. Once a voice is selected, you can "play" the keyboard. Notes begin when you press a key and end when you release it. Several notes can be played at once. The middle two rows of keys are the white keys, with sharps and flats in the top and bottom rows. The shift key shifts up an octave. Here is the way the keys and notes correspond:
        ` 1 2 3 4 5 6
     C#-1 D#-1 F-1 F#-1 G#-1 A#-1 C1
                          7 8 9 0 - =
                          C#1 D#1 F1 F#1 G#1 A#1
       TAB q w e r t y u
       D-1 E-1 F-1 G-1 A-1 B-1 C1 D1
                          i o p [ ] CR
                          E1 F1 G1 A1 B1 C2
       CTL a s d f g h j
             A-3 B-3 C-2 D-2 E-2 F-2 G-2
                            k l ; '
                            A-2 B-2 C-1 D-1
       LSH z x c v b n m ,
              A#-3 C-2 C#-2 D#-2 F-2 F#-2 G#-2 A#-2
                            . / RSH \
                            C-1 C#-1 D#-1

-   The spacebar also plays a note, but its value and duration are controlled by choices made on the edit screen.

yank buffer
    Click in the area enclosed by square brackets, just below the note symbol, transfers the currently selected voice in the synth bank or library bank into a temporary buffer. From there it can be moved to some other position in one of the banks with the "put" or "swap" menu options. This gives a means of moving individual patches around.

arrows
    The controls with an arrow image copy all voices from one of the displayed voice banks to the other. The left arrow transfers from the current library bank to the synth bank. The right arrow transfers the other way. Voices at the destination are overwritten, and their information is lost (so be careful).

upload one
    Click here to upload the selected voice/patch to the synthesizer. The patch's number in the synth will be the same as the number in the bank. You can also store a single patch into a file by following this procedure: click after file: on the screen and type in the name of the output file followed by carriage return, then click after file: again, so that the little caret becomes visible; then click on upload one to save the selected voice to the file. Finally, hit carriage return again.

upload all
    Click here to upload all voices/patches in the synth bank to the synthesizer. The patches can be saved to a file, instead, by following the method described above for the upload one operation. The difference between saving patches to a file in the ordinary way and saving them through the upload all operation is that in the latter case, the synthesizer's dump format is used, which may be different from glib file format. (For the SoundBlaster, there is no difference; for the Kawaii K1, there is.)

controllers
    There are five vertical sliders to control the sound, so one can better judge how things will sound in a midi song. From left to right these are: (V) midi main volume, (E) midi expression, (C) midi chorus depth, (R) midi reverberation, (T) GUS tuning. (None of these are currently implemented for external synths, and midi expression is only implemented for the GUS.)

Using xgl - The editor
An editor screen is called up by choosing the "edit" option on the menu you get by depressing the right mouse button with the mouse pointer inside one of the voice banks. There is a different screen for each synthesizer. At the top of the screen at the left is the name of the currently selected voice to be edited, and to the right is a note symbol just like the one on the librarian screen followed by a "quit edit" control. In the middle of the screen are the names and current values of the various parameters of the voice patch. Below these are the values for the note played when you press the space bar. At the bottom may be one to four graphs of wave envelopes for the oscillators.

N:  Click here at the upper left and type in a name followed by carriage return to change the name of the voice.

note symbol
    This is a visual indication of the notes you play on the keys.

quit edit
    Click here to remove the editor screen from the display. You don't need to end the edit session to edit some different patch, necessarily. You can click on some new voice on the librarian screen in a voice bank, and the editor screen will be updated with the new information. You can also use the arrow keys to select a different patch, as when using the librarian. However, it would be best not to click on an already selected voice, which deselects it, without selecting some new voice, since when no voice is selected, the editor does not know where to store any changes you make to the parameters (and so changes are discarded).

parameters
    The current parameter values, which may be either numeric or not, are displayed in a small fixed font after the parameter names, and the value is followed by a little triangle symbol. Depress the right mouse button over the triangle to see a menu of the six possible changes and click the left button over your choice. That changes the parameter value immediately to the left. (Don't worry about the flashing of the display to the right -- it seems to be an Xview bug.) You can increment the parameter by one, "+", decrement by one, "-", increment by four, "+4", decrement by four, "-4", set to the maximum, "max", or set to the minimum for this particular parameter, "min". Clicking the left button over the triangle symbol performs the default change, which is to increment by one, unless you have changed the default by depressing the control key while the mouse pointer is over some different choice on the menu.

note parameters
    The note played when you hit the spacebar, and its duration and loudness can be changed in the same way as the voice parameters.

wave envelopes
    At the bottom of the screen are from zero to four graphs of wave envelopes. For the SoundBlaster there are two, for Kawaii K1 single patches there are four, and for Kawaii K1 multi patches there are none. Each graph displays the attack time, decay time, sustain level, and release time for one of the synth's oscillators. Whenever you make a change in one of these parameters in the upper portion if the editor screen, the change is reflected in the graph. These four parameters may also be changed by manipulating the graph with the "grip" that is visible as a light colored square somewhere in the lower portion of the screen. You drag the grip around by putting the mouse pointer over it and pressing and holding down the left mouse button while moving the mouse. When the grip is brought close to a part of a wave envelope that can be changed, it catches hold of the graph and pulls in into a new position as you move the mouse. When you release the left button, the new values of the envelope parameters are shown in the appropriate places in the edit screen above. If the grip has caught hold of a part of the graph that you do not wish to change further, you can get it to let go by dragging the grip away using the middle mouse button, rather than the left button.

-   The grip can be used to move the peak of the envelope horizontally, the peak being the highest part of the graph, after the attack and before the decay. Such a horizontal movement affects both the attack time and the release time. The movements of the graph are constrained so as to keep the parameter values within their permissible ranges, so some changes to the attack time may require a separate adjustment to the decay inflection point (see below).

-   Move the grip close to the inflection point between the decay of the envelope and the beginning of the level sustain part in order to change the decay time. This inflection point can only be moved horizontally.

-   In the vicinity of the horizontal sustain line, but to the right of the decay inflection point, the grip will move the sustain line up and down, thus changing the sustain level. The minimum and maximum sustain levels are a fourth of the way and 3-fourths of the way up from the base line (so that all the inflection points will remain visible), and so the sustain line can't be moved below or above these levels.

-   The inflection point going from the level sustain line to the downward slanting release line is invariable, and can't be moved horizontally. The far end of the release line, where it meets the base of the graph, can be moved horizontally to change the release time.

Synthesizers
Here is a list of the sample patch files for each synthesizer in the current release of xgl, together with occasional notes on the current implementation.

Kawaii K1
    Sample patches: std.k1s

    Voices are not sent to the K1's edit buffer (because I don't know how to do that). Instead, they are stored as voice A1, which means that the true voice A1 (Ac. Grand Piano for single patches) has to be restored before the end of a xgl session.
    For Kawai K1 multi patches, names of single patches referred to are displayed when they can be found in the synth voice bank of the single patches module. The names are updated whenever a new bank of voices is transferred into this bank.

SoundBlaster
    Sample patches: std.sb, drums.sb (supplied with Adagio)

    SoundBlaster patches have private data which is not uploaded to the driver but instead is available to be used by an fm playing program (and in fact, is used by "mp" and "ad"). There are seven items given on the edit screen after "META":

(1) "fixed key"
    this note will always be played, regardless of what note is requested in the file being played;

(2) "fixed dur"
    this duration will always be used, regardless if what duration is specified in the file being played;

(3) "transpose"
    the pitch requested will be changed by this number of semitones;

(4) "other voice"
    another note using this other voice will be played simultaneously.

(5) "chorus"
    changes the pitch spread between the two notes played simultaneously to simulate midi chorus depth.

(6) "echo dly"
    varies the delay before a second echo note is played to simulate midi reverberation.

(7) "echo atten"
    controls the loudness of the reverberation echo note.

(1) and (2) are intended for percussion voices. (The 0.4t version of Adagio implements (6) and (7), but earlier version do not.)

Opl3
    Sample patches: std.o3, drums.o3 (supplied with Adagio)

    The 4-op patches for the opl3 fm boards are like SoundBlaster patches, except for having two extra operators.

Ultrasound
    Sample patches: std.gus, drums.gus (supplied with Adagio)

GUS patches are not edited at all. Instead, glib helps maintain a library of information about the patches which is used by mp to supplement or override what is in the patch files themselves.

voice volume
    This changes the balance among gus patches.

chorus spread
    Like "chorus" for fm.

echo delay
    Like "echo dly" for fm.

echo atten
    Like the same item for fm.

fixed key
    Like the same item for fm.

fixed dur
    Like the same item for fm.

transpose
    Like the same item for fm.

fine tune
    Bends pitch up or down. This is not currently useful, because the value is not used by mp.

The "base+rate" and "offset" values are the volume envelope parameters for the first sample in the patch (I couldn't find room on the screen for all the samples). These are editable, but only the second and third sets of values are used by mp. These particular values are used for all the samples in a patch -- not just the first.

The wave-data for the patch is not shown, and is not even kept in the patch library, but is read from a disk file when it is needed to play a note. The disk files containing wave data must be either the standard Gravis GM patches or patches in the same format and must be either in the directory /dos/ultrasnd/midi or /dos/ultrasnd/midi2 (unless other standard locations were specified when xgl was compiled). New patch data can be added to glib-libraries using the utility program pat2gl.

The operation of uploading to the synth is not implemented (except for the automatic upload that takes places before playing notes).

See also
glib(1), pat2gl(1), xmp(1), ad(1), mp(1), setfm(1)

AUTHORS

original version: Tim Thompson, ...twitch!glimmer!tjt

K1 support and menu construction utility, SoundBlaster and GUS support, Linux i/o, Xview front end: Greg Lee, lee@uhunix.uhcc.hawaii.edu

Scott Snyder added cmd line args to menutoc and fixed a bug

Some of the code was originally written by Steve Frysinger (moss!spf), John Helton, and James Gosling. A number of others have contributed to the full distribution (see notes in glib(1) man page).