GeoMaestro

-- Back --

GeoMaestro is developped and extensively used under Win98 and GNU/Linux (well, not recently), but I never tried it on other systems so please report any trouble, as I can only fix problems that I am aware of...

Installation


GeoMaestro is a remote part of KeyKit (which you can find at Tim Thompson's place), living in a separated downloadable file so that it can be covered by the General Public License.

Unzip the archive in your KeyKit directory: everything should go into the /contrib subdirectory: if it doesn't exist, it should be created, so that the overall folder structure is: 
KeyKit
|__bin
|__contrib
|  |__GeoMaestro
|  |  |__ABDemo
|  |  |__data
|  |  |  |__emptyme
|  |  |__lib
|  |  |__toys
|  |  |__userlib
|  |     |__Courant
|  |__xtra
|__doc
|__lib
|__music

Then set the variable Contribdir to "../contrib" in your keylocal.k file (this is where is coded the keylocal() function which defines the local settings for Keykit).

You may choose another directory for installing GeoMaestro files, as long as Contribdir points to it.

Also add (or uncomment) these lines in keylocal():
    addprerc(global(geoprerc))
    addpostrc(global(geopostrc))


When you're upgrading the system, check that you removed all files from precedent versions, except for the content of the /data and /userlib directories where you're supposed to keep your own files and compositions.

The /toys directory can be left untouched, so that you can safely store your own Toys there. Simply accept any update of previous files from the distribution (I may have improved a Toy).

The /extra folder contains various files that you may use or not. Their usage is documented in the rest of this manual (there's notably a major mode for Emacs).

The /ABDemo folder contains a demonstration set-up. See this page for more.


The first time you use an upgraded version, it is recommended to invoke "Misc -> reread library" in KeyKit root menu, although generally this should not be necessary.


For more information, please have a look at the different read_me.txt files in the distribution.



KeyKit versions and backward compatibility:

GeoMaestro has been developped under KeyKit 6.6c until its version 1.061
From 1.062 to 1.086, it has been developped under KeyKit 7.0 (b, c and f).
From 1.086 to 1.119, it is developped under KeyKit 7.1
From 1.120 on, it is developped under KeyKit 7.2

The installation procedure described in this page only applies to KeyKit 7.1a and newer. If you want to install GeoMaestro with a previous version of KeyKit, please read this deprecated installation page.

Also, there are backwards incompatibility so that a clear split happened:

Supported systems:

Since GeoMaestro is entirely written in the proprietary KeyKit langage (interpreted and specially dedicated to the programming of MIDI applications, with its own graphical features), you just have to check that KeyKit runs on your system, which is notably the case for Macintosh, Windows and Linux. So far I only worked with Windows and Linux, though; so please report any problem.

Most american keyboards don't make it easy to input the £ character. Sorry about that... I'll change it someday (hmmm... I first wrote this a few years ago...). For now, you can use Alt+156 or Alt+0163 to input the £ on a Windows system.

The only important system-specific feature is the Notepad() function, a very useful one indeed, that need to be informed of the way it can call a text editor through the system's shell. The default is configured to use Notepad for Windows (and I highly recommend that you replace your native Notepad with the wonderful and free Metapad from Alexander Davidson, if it's not already done). For other systems, or other editors, just change the NOTEPAD1 and NOTEPAD2 global variables (in file initialisations.k)

IMPORTANT: change the TEMPFILE variable so that it fits your directory structure: it is the name (with a full absolute path) of the temporary file used by the Notepad() and Padnote() functions.




Directories and paths


If you want to change the default directories and paths, see here how to proceed.




Fixing a couple of little annoying problems
KeyKit has this great feature allowing you to pull-off menus and put them where you want, and even to pull-off items from these menus and have them available as buttons.

Only... this is not always correctly handled by the page system: it doesn't work with a specific type of menu button called kvalbutton, unfortunately used a lot by the GeoMaestro GUI. So if you write a page with pull-off menus and/or pull-off buttons coming from the GUI, they will not be restored properly when you read the page in another session.

This can be fixed by installing anywhere in your Keypath (for example in your GeoMaestro/userlib directory) the file kklib_hacks.k which you can find in the Geomaestro/xtra/ folder. It will override a few functions from the KeyKit library; the installation is not performed by default so that you may decide to keep the original KeyKit distribution just as it is.

To have it be taken into account, add the line 
eval("#include kklib_hacks.k")
... in your GeoPostInit() function. Note that this hack only fixes the problem for GeoMaestro's GUI (because its kvalbuttons have been modified), it doesn't fix it for all other kvalbuttons in KeyKit...


Another problem fixed in kklib_hacks.k is the page system read/write limitation: see here for details.


Finally, kklib_hacks.k also makes a few modifications in the Root menu. If you don't like them, just delete the code for mkmenu_... functions. One useful change is a "delete page" entry in the Page menu, which as it name says makes it possible to delete the current page (without any saving procedure, so be careful with this).




Setting up MIDI


You can start right away with what you have now. But there's one setting that you may find useful: the definition of different sets of patchmaps.

By default, KeyKit uses the General MIDI patchmap, that is a set of 128 instruments located in bank 0. GeoMaestro includes hooks to change this behaviour and allow you to use many different user-defined patchmaps where are grouped instruments that can be located in differents banks, as long as you can address these banks with the MSB code only (it simply means that the bank numbers must range from 0 to 127). So now you can use KeyKit with any set of instruments from a potential collection of 128*128=16384 differents instruments.

Patchmaps must be edited in a text file named ACpatchmapn.txt, where n is an positive integer different from 0, located in your GeoMaestro/userlib directory, with the following format (here's an example file): lignes starting with # are ignored, fields must be separated by tabs (and not by space characters only !), and must be in the following order for each line: patch name, MSB number, patch number. That's it.

Now to select this specific set of patches, just set the global variable ACPATCHES to n in your geoprerc() function (this is located in the geomaestro.k file from the KeyKit distribution). Default is ACPATCHES = 0 which means we just go on with the GM set. Much more about this here


Note that a specific syntax allows you to select patches and banks from TiMidity configuration files. If you're using TiMidity as soft synth, look here for details.



Setting up the audio system
GeoMaestro has been designed to interface with a couple of external software. The setting described here are NOT required, only if you want the audio features. Details about this can be found in the TiMidity page and the Audio section in the compositor page.


Temporary *.wav file

Store a file name suitable for temporary use in variable TEMPWAVEFILE


Interfacing with TiMidity

... see the TiMidity page


Interfacing with Csound

Csound is always invoked through the CallCsound() function.

It depends on the following parameters: If for some reason the CSOUNDCOMMANDLINE syntax seems ackward, you may simply hack the CallCsound() function itself so that it fits your system.


Interfacing with a sound editor

The sound editor is invoked through the EditWave() function

It depends on the following string parameters: The system command is built by adding WAVEEDITpath, the *.wav full file name, then WAVEEDIT2

You will also need to construct EDITWAVECOMMAND so that it edits the temporary *.wav file. Do this after all other settings have been done.

A Linux example: 
 WAVEEDITpath = "snd"
 WAVEEDIT2 = " &"
 EDITWAVECOMMAND = WAVEEDITpath+" "+TEMPWAVEFILE+" "+WAVEEDIT2
A Windows example: 
 WAVEEDITpath = "c:\\cool\\cool96.exe"
 WAVEEDIT2 = ""
 EDITWAVECOMMAND = WAVEEDITpath+" "+TEMPWAVEFILE+" "+WAVEEDIT2






OK, that's it for the installation part. Now let me introduce a few general features which are part of the GeoMaestro composition system, but should better be considered as simple utilities to improve the use of KeyKit console.




A few changes in KeyKit's console
As from KeyKit version 6.6b, the console history management has been improved and the following features are available:

typing ! lists the history of the session (that is the content of the Hist array)
typing !! recalls the last command
typing !n recalls command number n
typing !!! erase the history and start another one from scratch
typing a command :whatever is equivalent to typing print whatever
typing :: toggles between a mode where every command is considered as being preceded by print and the usual mode


With GeoMaestro, the console has a few more features: you can use the TAB key to go back into the history and edit a previous command line; and you can use the ESC key to call a text editor which will present you the current command ligne along with the history, so that you can cut & paste and edit your command as you want. This is useful if you're doing complex calculations at the console... if you forgot an opening parenthese at the beginning of a long formula, pressed return and see KeyKit issuing an error message, no trouble: just type twice on TAB and once on ESC and here you have your formula, ready to be corrected or changed.

More precisely:

Pressing TAB once brings along the promp "edit:". At that point, if you type a number n and press RETURN, you will have the command number n in history available for editing changes. If instead you press TAB again, you will have the last command ready to be edited. In both cases, further TAB presses will get you back in history.

Now for the ESC thing: be careful here as it's a bit strange (I couldn't find another way to proceed!). Pressing ESC once opens the text editor through a shell call (see the Notepad() stuff in the first chapter). So now you have an open editor with, in the first line of its text, the command that you were editing, and in following lines, the content of the whole history of the session. Do your thing on the first line, and when it's okay, save the text (don't forget that ! and don't rename it !), check that the focus has come back to the KeyKit window (which for Windows means: click on the KeyKit window to be sure), and then press ESC again. You will not see anything at the prompt, but your command has been evaluated, and you can see it as the last command stored in history.

(If the text editor refuses to save the temporary file, check that MAT is an absolute path (in initialisations.k). By default it's a relative path, since it's the easiest way to distribute the system: just replace the ".." by what it means in your directory structure)



If you think this is a ugly hack, you're right. I have better to propose, but you need to be somewhat familiar with Emacs: it is then possible to have a very powerful KeyKit console within an Emacs buffer (driving KeyKit via TCP/IP). See this page for details...



Linux and Mac OS users:

The ESC thing will not work without a little hack... you need to replace the readedit2() function in file KeyKit/lib/util1.k with the one provided in the distribution file /xtra/readedit2.k





LOG features
In many instances, what you have in your history could be very useful as a part of a function or anywhere else in a KeyKit program. The LOG array is here to help you manage transferts from commands you typed at the console to hard-coded commands in a function call. Here are a couple of functions working on LOG:

First of all, to start from scratch you just have to do a LOG = [] at the console.

HLog() copies part of the history into the LOG array. It appends the commands indexed by its arguments to the current LOG content.
Here's an example:
HLog("35-41",18,22,"1-5")
This will copy history commands 35,36,37,38,39,40,41,18,22,1,2,3,4,5 (in that order) into the LOG array

EvaLog() evaluates the content of the LOG, as if it was a KeyKit function
Exemple: if you have LOG = [1= "a=2", 2= "b=7", 3= "print(a+b)"] then EvaLog() returns "9" at the console
As arguments to EvaLog(), you can give an index for starting and an index for ending the evaluation: EvaLog(n1,n2).

Note that you can easily edit the LOG array, like any array in KeyKit, with the Notepad() function (see next chapter)

ExLog() creates a KeyKit function from the content of the LOG.
It has two string parameters: the first one is the function name, the second one is the name of the file it will be written into. By default, the name is "LastLog" and the file is "log.k" in directory BASE.
On the previous example, if you do a ExLog("AplusB",BASE+"tests.k"), you will find appended to the tests.k file (created if it didn't exist already) the following code:

function AplusB() 
{
	a=2
	b=7
	print(a+b)
}



Notepad() and Padnote()
If AnyArray is an array (what else could it be with such a name ?), the command Notepad(AnyArray) opens the text editor with the structure and content of AnyArray developped in such a way that it is very easy to look at the contents, understand the array structure and edit it.

When editing, be careful to the following points:

1- If you delete an item in the array, delete the whole line containing this item. Moreover, if this item is itself an array (you can tell that because the line starts with an "a"), you must also delete all the following lines (because they contain the content of this array), until you find another "a" followed by a level number inferior or equal to the level of the array you deleted. If the index number is superior, that means we are still in this same array you want to delete. Get it ? The indentation is supposed to make this quite obvious (so, by the way, use a non-proportionnal font in your editor !).

2- If you edit an item value, always leave two space characters between the last "]" and the content. Because two characters will be skipped anyway.

3- If the item you're editing is a string, do not use "", or they will be part of the string. Just use the letter "s".

4- If you add an item, check that the line starts with the correct code. The letter is used to specify the type of the value, and the number is used to give the depth level of the item in the array. The first level is number 1; number 0 is an artefact, don't touch it. You don't need to respect the indentation as long as the code is correct (well, if the indentation is good and the code wrong, guess what ? It's no good).

When you're done, save your text file and use the Padnote() function to get your array back in KeyKit. You can say AnyArray = Padnote() if you want to get it back in the same variable, or AnyOtherArray = Padnote() if you want to copy it elsewhere.

You will soon find this feature unvaluable, as KeyKit makes big use of associated arrays. They're now as easy to edit as plain KeyKit code.

Note: if you simply want to look at the content of an array, a second argument (integer) can be used to set a limit to the depth of the tree structure. Parts of the array whose depth levels are more than the second argument will be hidden. You can not use Padnote() in this case: editing is not possible.




Snarph() and SNARF
The SNARF array is an extension of KeyKit Snarf, a buffer variable used to copy and paste phrases. The easiest way to manage it is to use the Snarph() function, which can handle several types of arguments and behave accordingly:

If Snarph() is given a phrase as argument, it simply return this very phrase. But, in the meantime, the phrase has been added to the SNARF array and a message is issued at the console informing you of the array index (an integer) associated to the phrase. You can also give a second argument to Snarph(): it must be a string, and it will be associated to the phrase, as a comment.

This feature is used, for example, in the "hear ev/seg" and "hear ev/cir" mouse modes of the GUI, if AutoSnarph is set to 1: then everytime you draw a segment or a circle, the rendered phrase is Snarphed, and, as a comment, the coordinates of the support are stored, so that you can use this information for a later composition (by default AutoSnarph is 0)

If Snarph() is given a positive integer argument, it understands it as an index value and returns the corresponding phrase.

If Snarph() is given a string argument, it converts it to an integer (an index value) and store the corresponding phrase in Snarf.

If Snarph() is given no argument, it lists all Snarphed phrases along with their comment lines at the console.

If Snarph() is given a negative integer argument -n, it deletes the phrase whose index is n

If Snarph() is given a negative integer -n1 as first argument, and a positive integer n2 as second argument (with n2>n1), it deletes the phrases from index n1 to index n2.

In the two last cases, indexes are rearranged so there's no "hole" in the SNARF array. You can then only rely on comment lines to keep trace of the origin of the phrase.




-- Back --