Tutorial

Build a man a fire, and he'll be warm for a day. Set a man on fire, and he'll be warm for the rest of his life.

-- Terry Pratchett

Introduction

NOTE Most of this tutorial needs to be rewritten to use (and show off) GUI editing, rather than the older text-based editing. The other pages should still be accurate.

This tutorial walks you through creating a KeyMaster song from scratch. It assumes you have a compiled version of the keymaster command. Start by running keymaster with no arguments. This will first scan your system to find all attached MIDI devices. Next, as a convenience it creates a number of songs that link them together in various combinations.

Start KeyMaster

Run the keymaster command with no arguments. This will first scan your system to find all attached MIDI devices. Next, as a convenience it creates a number of songs that link them together in various combinations. Finally, it opens the main KeyMaster window.

See Your Instruments

Open the Instruments window ("Window" -> "Instruments"). You should see all of your attached MIDI devices. Each will be marked as enabled or disabled.

Click the "Done" button to close this window.

Your First Song

Select "New Song" from the "Edit" menu. A dialog will appear, letting you name your song. Click "OK".

Your song will appear in the Songs panel, and a patch named "Unnamed Patch" will appear in the Patches panel.

Editing the Patch Name

Double-click on the "Unnamed Patch" patch and a dialog box will appear.

A Patch

NOTE The entire remainder of this tutorial needs to be rewritten to use (and show off) GUI editing, rather than the older text-based editing.

Let's add a patch that connects the input from :keys to the output :another on channel 1.

# Songs

...optional notes...

## My First Song

...optional notes...

### First Patch
#### kk, all, kz, all
#### kk, 1, ws, 2

The first all tells KeyMaster to listen to all incoming channels from the input instrument. The second all means we will keep whatever channel(s) get sent from the input and pass those through to the output.

The second line will, for the output ws, ignore everything except input channel 1 on the input kk and send it to channel 2 on the output ws.

Now let's modify the MIDI a bit as it goes through.

# Songs

...optional notes...

## My First Song

...optional notes...

### First Patch
#### kk, all, kz, all
#### kk, 1, ws, 2
- prog_chg 42
- transpose 12
- zone C4, B6
- cc 64 filter

## Another Song
### Another First Patch
#### ws, all, kz, all
#### ws, all, kk, all

Here we've connected kk channel 1 to channel 2 of ws, sent it a program change command, transposed all notes (and polyphonic pressure messages) up an octave, and limited the notes passed through to those in the three octaves from C4 to B6. Finally, we've filtered out all sustain pedal controller messages.

TODO: start and stop bytes

Creating Named Messages

NOTE: rules for entering hex/decimal data

NOTE: more than one message

Named messages contain arbitrary bytes that can get sent at any time. They are sent to all outputs. Let's define a tune request message.

# Messages

## Tune Request

```
0xf6
```

We can bind messages to computer keys. Here we'll bind the tune request message to F1 and the full volume message to F2. The names here must match the names you gave the messages above.

message_key :f1, "Tune Request"
message_key :f2, "Full Volume"

Creating Triggers

NOTE: rules for entering hex/decimal data

Triggers make things happen. They listen for a particular message from an input instrument and, when that message is seen, perform some action. Let's make a few, including one that moves to the next patch and one that sends a tune request message.

The title and separator lines are ignored. Actually, any line where the first column isn't a legal input instrument short name is ignored.

The first column contains the input instrument short name. The second is a one- to three-byte MIDI message that triggers the action or message send.

The third column is one of "next song", "next patch", "prev (or 'previous') song", "prev patch", or "message". "Message" requires a message name.

Note that since the last trigger refers to our "Tune Request" message, it needs to come after the "# Messages" section we defined above.

# Messages
  ...

# Triggers

| input | bytes         | action     | message      |
|-------+---------------+------------+--------------|
| kk    | 0xb0, 50, 127 | next song  |              |
| kk    | 0xb0, 51, 127 | prev song  |              |
| kk    | 0xb0, 52, 127 | next patch |              |
| kk    | 0xb0, 53, 127 | prev patch |              |
| ws    | 0xb0, 50, 127 | message    | Tune Request |

A Set List

Set lists are lists of song names. You can define as many as you like, and use them to hold lists of songs for a performance.

There is always one set list named "All Songs" that contains all of the songs you define in your KeyMaster project, so you don't have to have any song lists at all.

# Set Lists

### Another Song
## My First Song