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
This tutorial walks you through creating a PatchMaster file from scratch. It
assumes you’ve installed PatchMater as a gem, which will also install
related utilities such as
PatchMaster files are Ruby files. Since Ruby files typically use the extension “.rb”, go ahead and create a new file in your favorite editor named “pm_tutorial.rb”.
The PatchMaster file we’ll be creating in this tutorial is verbose. There are short forms of most of the commands and some of the things we include are optional.
Defining Your Instruments
Find your instruments
In a terminal window, type
This command lists all the input and output instruments that are attached to
your Mac, whether physical or virtual. You’ll need to remember the input and
output instrument numbers listed by
Add them to your PatchMaster file
Open a file in your text editor. For each MIDI input output you want to use, add a line like this:
The number is the number you got from the
unimidi list command. “:keys” is
any short name; it’s what you will use to refer to that MIDI input. The name
must begin with the “:” character and can not contain any spaces.
The name for each instrument must be different.
Likewise, for each MIDI output add a line like this:
Output names must be unique, but can be the same as input names. For a MIDI instrument that uses both its input and its output you will probably want to use the same name.
Your First Song
After the instrument inputs and outputs, add an empty song:
Let’s add a patch that connects the input from
:keys to the output
:another on channel 1.
nil tells PatchMaster to pass through any channel message that comes
:keys. The 1 tells it to translate all messages from
channel 1 before sending it to
Now let’s connect
:keys to the same synth on a different channel but
modify the MIDI a bit as it goes through.
Here we’ve connected
:keys to channel 2 of
:another, 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 two octaves
from C4 to B6.
Filters allow you to take complete control over the MIDI that gets sent through a connection. Let’s use a filter to modify the volume of all notes in real time using a software LFO (Low Frequency Oscillator).
NOTE This LFO only sets the velocity of each note. It doesn’t change the overall volume over time (e.g., tremolo). To do that you’d need to create a method that gets called regularly, probably in a separate thread, and that sends volume control change messages.
First, we need to write a method that outputs a value between 0 and 127 and that changes over time. Let’s put this method definition before our song.
Next let’s add a new connection from
:third that uses a filter
to replace the volume of any note message with the current LFO value.
Creating Some Messages
Messages contain arbitrary bytes that can get sent at any time. They are sent to all outputs. Let’s define two messages. The first is a tune request and the second sends individual note off messages to every note on every channel.
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.
Triggers make things happen. Let’s make a trigger that moves to the next patch and one that sends a tune request message.
[TODO: finish this section]
Bonus exercise: Write triggers that move to the next song, the previous patch and the previous song.
A Song List
[TODO: write this section]
The Whole File
The whole file should look something like this. Blank lines don’t matter.