KeyKit Use and Programming FAQ

Please send suggestions for additions to tjt@nosuch.com.
  1. What is this thing?

    KeyKit is both a programming language and a complete graphical environment containing a large variety of tools for both normal "sequencing" tasks as well as "algorithmic composition" tasks. More details (from a programmer's perspective) can be found here. The KeyKit download site can be found here.

  2. Do I need to do any programming to use it?

    The graphical environment is complete enough to be easily used without doing any programming at all, and can be used to do a large variety of manipulations in a MIDI environment. The system, however, is designed very much from a programmer's perspective. It is designed to make it easy to add new tools and features, often with only a few lines of KeyKit code. For example, adding a new editing operation to the Group tool (the multi-track sequencer) can be done with 4 lines of code. See below for how to do this.

  3. I've lost my password for the download site, what do I do?

    Just register again with your same email address, and the new password you will be sent will override the old one.

  4. How do I get started?

    You should read the documentation that comes with the system, in the doc directory. The tutorial should be the first thing you read.

  5. How can I have the most fun with the smallest amount of effort?

    The Mouse Matrix tool is the simplest tool that you can have immediate (though perhaps brief) fun with. The Kboom tool is a drum pattern editor that is both a lot of fun and *very* deep in capability.

  6. What is the "Snarf"?

    Snarf is a single global variable that many tools can set and/or get, much like the clipboard on Windows. If you see a "Snarf" menu item in a tool, selecting that menu item will save the current contents of the tool in the Snarf variable. You can then go to another tool, and use "Load->Snarf" (or whatever menu item the tool provides for reading the Snarf). For example, the Group tool has a "File->Read->Snarf" menu item.

    Besides being able to Snarf midi phrases and use them between tools, you can also Snarf an entire tool and its contents (with Window->Snarf Tool) and then create any number of copies of that tool (with Window->Paste Tool). Besides the obvious use, this can be useful to copy a tool to a new page.

  7. How can I write a MIDI file?

    The Group tool has a "File->Write->Standard MIDI File" menu item. So, typically, you copy things to a Group tool in order to write them out as a MIDI file. However, you can also write a MIDI file from the console, or in a script, using the writemf function like this: writemf(Snarf,"file.mid");

  8. What is the "console" for?

    After starting KeyKit, you can type statements in the "console", but this is typically only used for:

  9. How can I write and execute my own programs in KeyKit?

    The usual way of writing KeyKit code is to use the text editor of your choice on a file in the liblocal directory (say, "foo.k"), and when you want to execute that code (or load the function it defines) you type

         #include foo.k
    
    in the KeyKit console. Typically such a file will just define a function, and you can then execute it interactively from the console. For example, if the foo.k file defines functions foo1() and foo2(), you could then type statements like this at the console:

         foo1()
         Snarf = foo1()
         Snarf = foo2() + foo1()
    

    The first statement will actually schedule and play the return value of foo1(), assuming that the return value of foo1() is a phrase. The second and third statements will assign values to the global Snarf variable, which is used as a conventional mechanism for transferring values between the GUI tools. For example, you could use "File->Read->Snarf" in the Group tool (the multi-track editor) to view and play the results of your foo1() function.

  10. How can I use KeyKit for sysex dumps?

    There is no GUI tool for this, but sample code for this can be found in lib/realutil.k - the getsysexdump() function is well-commented. The txpatches() and txperfs() functions use getsysexdump() for getting patch and performance dumps from a Yamaha TX81Z.

  11. How do I add a new editing operation to the Group tool?

    Let's say you want to add an editing operation that will shift the currently-picked notes up one octave in pitch. You would add 1 line to the lib/mkmenus.k file, in the mkmenu_edit() function, like this:

         o.menucmd("Octave Up ->",po,"edit","cmd_octaveup")
    
    and then add a cmd_octaveup() function to the lib/cmds.k file like this:
         function cmd_octaveup(p) {
              p.pitch += 12
         }
    
    That's it! And you can do this while KeyKit is running!. Just make the additions described above, then type these statements in the console:
         #include cmds.k
         #include mkmenus.k
    
    The Group tools on your screen will immediately have access to the new editing operation. Obviously if you want sub-menus and other things, it isn't quite that simple, but you can use the existing commands as samples of what to do for more complex new commands.

  12. How well does it work on Linux?

    KeyKit works on Linux, with external MIDI devices using the /dev/midi device driver, and (according to recent reports) with internal synths, using both ALSA and JACK.

  13. How do you use KeyKit in CGI and other scripts?

    "lowkey" is a version of the KeyKit interpreter that does not have graphics support, suitable for use from CGI and other scripts. Here's an example of using lowkey in a CGI script. Write the KeyKit code you want to execute, and put it into a file, defined as a function. For example, put this in "foo.k":

         function foogen(n) {
              # Repeat C chord n times, as an example
              p = repeat('c e g',n)
              # Write the result as a standard midi file, in foo.mid
              writemf(p,"foo.mid")
         }
    
    Then execute lowkey like this:
         lowkey foo.k -c "foogen(4)"
    
    This lets you write the function once and call it in different ways from your CGI script. When you invoke lowkey, you either need to be in the bin directory, or you need to set the KEYROOT environment variable to the directory in which you've installed keykit.

  14. I can't figure out how to...

    Questions can be sent to the KeyKit Google Group and answers will usually be provided.