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

This tutorial walks you through creating a KeyMaster project from scratch using the GUI.

Start KeyMaster

Launch KeyMaster from the Finder or with make run. If no project file is loaded, KeyMaster scans your system for all attached MIDI devices and creates a set of starter songs that link them together in various combinations. The main window opens.

The Main Window

The main window is divided into panels:

• Upper left: the songs in the current set list
• Upper middle: the patches in the current song
• Upper right: the MIDI clock controls and the current song's notes
• Middle: the connections in the current patch
• Bottom left: all set lists
• Bottom middle: all named messages
• Bottom right: all triggers

Click a song in the Songs panel to make it the current song. Click a patch in the Patches panel to make it the current patch. The connections for the current patch appear in the Connections table.

Your First Song

Select New Song from the Edit menu. A dialog prompts you for a name. Type a name and click OK.

Your song appears in the Songs panel. A default empty patch named "Unnamed Patch" appears in the Patches panel.

Editing a Song

Double-click a song in the Songs panel to open the Song Editor. Here you can change the song's name, set its tempo (BPM), choose whether the master clock should start when the song becomes active, and add free-form notes.

Editing a Patch

Double-click a patch in the Patches panel to open the Patch Editor. Here you can:

• Rename the patch
• Choose an optional start named message (sent to all outputs when the patch is entered)
• Choose an optional stop named message (sent to all outputs when the patch is exited)
• Add program changes to send to specific output instruments when the patch starts — each row specifies an output, a channel, and optional bank MSB, bank LSB, and program number

Adding a Connection

Select New Connection from the Edit menu. The Connection Editor opens. Here you can configure:

• Input instrument and channel (or "all channels")
• Output instrument and channel (or "all channels")
• Zone: the low and high key limits; notes outside this range are filtered out
• Transpose: semitones to shift all notes (positive or negative)
• Velocity Curve: how to transform note velocities
• Message Filter: toggle which MIDI message types pass through
• Controller Mappings: per-CC filtering, translation, and range scaling; click Add to add a mapping for a specific CC number

Click OK. The new connection appears in the Connections table on the main screen.

Double-click any row in the Connections table to reopen the Connection Editor for that connection.

Navigating Songs and Patches

Use the Go menu (or keyboard shortcuts) to navigate:

• Next Song / Prev Song — move to the adjacent song in the current set list
• Next Patch / Prev Patch — move to the next or previous patch within the current song
• Find Song / Find Set List — jump to a song or set list whose name matches a (case-insensitive) regular expression

Named Messages

A named message is a stored sequence of raw MIDI bytes that can be sent on demand. To create one, select New Message from the Edit menu, then double-click the new entry in the Messages panel. In the Message Editor, enter the bytes as space-separated hex values (e.g. F0 7E 7F 09 01 F7). Click OK.

Named messages can be assigned to a patch's start or stop message, or to a trigger action.

Triggers

A trigger fires an action when a key is pressed or a specific MIDI message arrives. To create one, select New Trigger from the Edit menu, then double-click the entry in the Triggers panel.

In the Trigger Editor:

1. Click Set Key and press the key you want to use, or click Learn next to the MIDI message field and send a MIDI message from your instrument. Use the Clear buttons to remove either.
2. Choose an Action: Next Song, Prev Song, Next Patch, Prev Patch, Toggle Clock, Panic, Super Panic, or Message.
3. If the action is Message, choose which named message to send.

Click OK.

Set Lists

A set list is an ordered list of songs. To create one, select New Set List from the Edit menu, then double-click it in the Set Lists panel. In the Set List Editor, drag songs from the "All Songs" column on the left into the "Set List" column on the right to populate it.

One set list called "All Songs" always exists and contains every song in alphabetical order. It cannot be deleted or reordered.

Saving Your Project

Use File → Save (or File → Save As) to save your project as a .kmst file. Use File → Open or the recent-files menu to reload it later.