Open Music Tutorial

OpenMusic Tutorial
by Carlos AGON, Gérard ASSAYAG, Jaccobo BABONI, Karim HADDAD, Matthew LIMA, and Mikhail
MALT
OpenMusic Tutorial
Edited by Karim Haddad
Published Date: 2003/11/05 13:10:44
This manual can not be copied, in whole or part, without the written consent of IRCAM.
This manual was produced under the editorial responsibility of Karim Haddad, Marketing and Communication Dept. , IRCAM.
OpenMusic was conceived and programmed by Gérard Assayag and Carlos Agon.
Patchwork was conceived and programmed by Mikael Laurson, Camilo Rueda, Jacques Duthen, Gérard Assayag and Carlos
Agon.
This documentation corresponds to version 4.6 or higher of OpenMusic.
OpenMusic™ is a trademark of IRCAM.
Patchwork™ is a trademark of IRCAM.
MidiShare™ is a trademark of GRAME.
Macintosh Common Lisp™ is a trademark of DIGITOOL, Inc.
Apple Macintosh™ is a trademark of Apple Computer, Inc.
Acknowledgments:
Markus Buser.
Copyright © 2003 by IRCAM. All rights reserved.
The use of this software and its documentation is restricted to members of the IRCAM software users’ group. For any
supplementary information, contact:
Marketing and Communication Dept.,

IRCAM
1 place Igor-Stravinsky
F-75004,Paris
FRANCE
Phone:(33) (1) 44 78 49 62
Fax: (33) (1) 42 77 29 47
Email: palumbo@ircam.fr
Send comments or suggestions to the editor:
Karim Haddad
Marketing and Communication Dept.,
IRCAM
1 place Igor-Stravinsky
F-75004,Paris
FRANCE
Phone:(33) (1) 44 78 16 05
Email: haddad@ircam.fr
For more information:

http://www.forumnet.ircam.fr
Table of Contents
I. Tutorials ...........................................................................................................................xi
1. Using Musical Objects I ............................................................................................1
Tutorial 1: Transposing pitches.............................................................................1
Topics ..........................................................................................................1
Key Modules Used ......................................................................................1
The Concept:...............................................................................................1
The Patch: ...................................................................................................1
Tutorial 2: Inverting an interval .............................................................................6
Topics ..........................................................................................................6
Key Modules Used ......................................................................................6
The Concept:...............................................................................................6
The Patch: ...................................................................................................6
Tutorial 3: Building a scale ...................................................................................8
Topics ..........................................................................................................8
Key Modules Used ......................................................................................8
The Concept:...............................................................................................8
The Patch: ...................................................................................................8
Tutorial 4: Inverting an interval II ..........................................................................9
Topics ..........................................................................................................9
Key Modules Used ......................................................................................9
The Concept:.............................................................................................10
The Patch: .................................................................................................10
Tutorial 5: Retrograde ........................................................................................12
Topics ........................................................................................................12
Key Modules Used ....................................................................................12
The Concept:.............................................................................................12
The Patch: .................................................................................................12
Tutorial 6: Four basic operations on a 12-tone row ............................................13
Topics ........................................................................................................14
Key Modules Used ....................................................................................14
The Concept:.............................................................................................14
The Patch: .................................................................................................14
Tutorial 7: Changing melodic contour.................................................................17
Topics ........................................................................................................17
Key Modules Used ....................................................................................17
The Concept:.............................................................................................17
The Patch: .................................................................................................17
Tutorial 8: Construction of a harmonic series.....................................................19
Topics ........................................................................................................20
Key Modules Used ....................................................................................20
The Concept:.............................................................................................20
The Patch: .................................................................................................20
Tutorial 9: Dealing with data types .....................................................................25
Topics ........................................................................................................26
Key Modules Used ....................................................................................26
The Concept:.............................................................................................26
The Patch: .................................................................................................26
2. Playing MIDI I .........................................................................................................29
Tutorial 10: Playing MIDI ....................................................................................29
Ircam documentation v
Topics ........................................................................................................29
Key Modules Used ....................................................................................29

The Concept:.............................................................................................29
The Patch: .................................................................................................29
Changing MIDI instruments ..............................................................29
Playing microtones using MIDI .........................................................31
3. Using Aleatoric Elements .......................................................................................33
Tutorial 11: Constructing a Chord with random notes from a harmonic spectrum
33
Topics ........................................................................................................33
Key Modules Used ....................................................................................33
The Concept:.............................................................................................33
The Patch: .................................................................................................33
Tutorial 12: Building a sequence of random notes: om-random..........................35
Topics ........................................................................................................35
Key Modules Used ....................................................................................35
The Concept:.............................................................................................35
The Patch: .................................................................................................35
Tutorial 13: Another random sequence ..............................................................38
Topics ........................................................................................................38
Key Modules Used ....................................................................................38
The Concept:.............................................................................................38
The Patch: .................................................................................................38
4. Flow Control I: Predicates ......................................................................................45
Tutorial 14: Random construction of a sequence...............................................45
Topics ........................................................................................................45
Key Modules Used ....................................................................................45
The Concept:.............................................................................................45
The Patch: .................................................................................................45
5. Flow Control II: Loops.............................................................................................49
Tutorial 15: Introduction to omloop I ...................................................................49
Topics ........................................................................................................49
Key Modules Used ....................................................................................49
The Concept:.............................................................................................49
The Patch: .................................................................................................49
Tutorial 16: Introduction to omloop II ..................................................................53
Topics ........................................................................................................53
Key Modules Used ....................................................................................53
The Concept:.............................................................................................53
The Patch: .................................................................................................53
6. Using Musical Objects II .........................................................................................59
Tutorial 17: Generation of a melodic sequence from harmonic reservoirs.........59
Topics ........................................................................................................59
Key Modules Used ....................................................................................59
The Concept:.............................................................................................59
The Patch: .................................................................................................59
Tutorial 18: Generation of a note sequence by interpolation between two chords
61
Topics ........................................................................................................61
Key Modules Used ....................................................................................61
The Concept:.............................................................................................61
vi Ircam documentation
The Patch: .................................................................................................61
7. Breakpoint Functions..............................................................................................65
Tutorial 19: Using BPFs I; Graphic representation of a series of notes .............65
Topics ........................................................................................................65
Key Modules Used ....................................................................................65
The Concept:.............................................................................................65
The Patch: .................................................................................................65
Tutorial 20: Using BPFs II: Sampling a sequence of notes................................66
Topics ........................................................................................................67
Key Modules Used ....................................................................................67
The Concept:.............................................................................................67
The Patch: .................................................................................................67
Tutorial 21: Using BPFs III: Scaling a melodic contour ......................................69
Topics ........................................................................................................69
Key Modules Used ....................................................................................69
The Concept:.............................................................................................70
The Patch: .................................................................................................70
8. OM Music objects Chord-seq and Voice...............................................................75
Tutorial 22: Chord-seq: Onsets and durations I ................................................75
Topics ........................................................................................................75
Key Modules Used ....................................................................................75
The Concept:.............................................................................................75
The Patch: .................................................................................................75
Tutorial 23: Chord-seq: Onsets and durations II ...............................................77
Topics ........................................................................................................77
Key Modules Used ....................................................................................77
The Concept:.............................................................................................78
The Patch: .................................................................................................78
Tutorial 24: Voice I .............................................................................................80
Topics ........................................................................................................80
Key Modules Used ....................................................................................80
The Concept:.............................................................................................80
The rhythmic structure ......................................................................81
Rests.................................................................................................82
Ties ...................................................................................................82
Irrationals (tuplets) ............................................................................83
The Patch: .................................................................................................83
Tutorial 25: Voice II ............................................................................................85
Topics ........................................................................................................85
Key Modules Used ....................................................................................85
The Concept:.............................................................................................85
The Patch: .................................................................................................86
Tutorial 26: Editing rhythm with the Voice graphic editor ...................................90
Topics ........................................................................................................91
Key Modules Used ....................................................................................91
The Concept:.............................................................................................91
The Patch: .................................................................................................91
The time signature ............................................................................93
Adding new measures ......................................................................94
Creating the basic rhythmic structure ...............................................95
First Measure ...........................................................................98
Ircam documentation vii

Second Measure ......................................................................99
Subdividing the structure ..................................................................99

Entering pitches..............................................................................100
Tutorial 27: Introduction to rhythm quantification .............................................101
Topics ......................................................................................................101
Key Modules Used ..................................................................................101
The Concept:...........................................................................................102
The Patch: ...............................................................................................102
9. Playing MIDI II ......................................................................................................107
Tutorial 28: Working with MIDI files I................................................................107
Topics ......................................................................................................107
Key Modules Used ..................................................................................107
The Concept:...........................................................................................107
The Patch: ...............................................................................................107
Tutorial 29: Working with MIDI files II...............................................................111
Topics ......................................................................................................111
Key Modules Used ..................................................................................111
The Concept:...........................................................................................111
The Patch: ...............................................................................................111
10. Using Musical Objects I ......................................................................................119
Tutorial 30: Working with lists I.........................................................................119
Topics ......................................................................................................119
Key Modules Used ..................................................................................119
The Concept:...........................................................................................119
The Patch: ...............................................................................................119
Tutorial 31: Working with lists II........................................................................121
Topics ......................................................................................................121
Key Modules Used ..................................................................................121
The Concept:...........................................................................................122
The Patch: ...............................................................................................122
11. The Maquette .....................................................................................................125
Tutorial 32: Introduction to the Maquette I.......................................................125
Topics ......................................................................................................125
Key Modules Used ..................................................................................125
The Concept:...........................................................................................125
The Patch: ...............................................................................................128
Tutorial 33: Introduction to the Maquette II......................................................130
Topics ......................................................................................................130
Key Modules Used ..................................................................................130
The Concept:...........................................................................................130
The Patch: ...............................................................................................131
12. Lambda Functions ..............................................................................................137
Tutorial 34: Introduction to Lambda Functions .................................................137
Topics ......................................................................................................137
Key Modules Used ..................................................................................137
The Concept:...........................................................................................137
The Patch: ...............................................................................................137
The first example ............................................................................138
The Second Example .....................................................................139
Tutorial 35: funcall with Lambda Functions...................................................143
Topics ......................................................................................................143
viii Ircam documentation

Key Modules Used ..................................................................................143
The Concept:...........................................................................................144
The Patch: ...............................................................................................144
13. Flow Control III: More Loops! .............................................................................149
Tutorial 36: Accumulation.................................................................................149
Topics ......................................................................................................149
Key Modules Used ..................................................................................149
The Concept:...........................................................................................149
The Patch: ...............................................................................................149
Tutorial 37: Accumulation with musical objects................................................151
Topics ......................................................................................................152
Key Modules Used ..................................................................................152
The Concept:...........................................................................................152
The Patch: ...............................................................................................152
14. Flow Control IV: Recursive Functions.................................................................157
Tutorial 38: Recursive patch I...........................................................................157
Topics ......................................................................................................157
Key Modules Used ..................................................................................157
The Concept:...........................................................................................157
The Patch: ...............................................................................................158
Tutorial 39: Recursive patch II..........................................................................159
Topics ......................................................................................................159
Key Modules Used ..................................................................................159
The Concept:...........................................................................................159
The Patch: ...............................................................................................160
15. The Maquette II ..................................................................................................165
Tutorial 40: More Advanced Maquettes and MIDI ............................................165
Topics ......................................................................................................165
Key Modules Used ..................................................................................165
The Concept:...........................................................................................165
The Patch: ...............................................................................................166
The onsets ......................................................................................168
Evaluating Maquettes .....................................................................168
Tutorial 41 ........................................................................................................170
16. Classes and Inheritance .....................................................................................171
Tutorial 42: Creating a Generic Function I .......................................................171
Topics ......................................................................................................171
Key Modules Used ..................................................................................171
The Concept:...........................................................................................171
Creating the Function ..............................................................................171
Tutorial 43: Creating a Generic Function II ......................................................181
Topics ......................................................................................................181
Key Modules Used ..................................................................................181
The Concept:...........................................................................................182
Adding New Methods ..............................................................................182
17. Classes and Inheritance .....................................................................................189
Tutorial 44 ........................................................................................................189
Tutorial 45 ........................................................................................................189
Ircam documentation ix
x Ircam documentation
I. Tutorials
Chapter 1. Using Musical Objects I
Tutorial 1: Transposing pitches
Topics
Using an arithmetic function to transpose pitches
Key Modules Used

Chord, om+
The Concept:
Pitches in OM are expressed in , or midics. Midics are values (60 corresponding to middle
C on the piano) multiplied by 100. 100 midicents = 1 semitone.
Transposing a note is thus equivalent to adding or subtracting from its midic value. We’ll do
this with a simple arithmetic operator om+.
The notes to transpose are found in a Chord object but we could take any midic output for
the operation.
We will also learn how to lock modules so their contents are retained.
1
Ircam documentation
The Patch:
This patch transposes the notes in Chord box (A) by adding (C) the value you have entered
at the second input to om+ (B) to every note. The midics are then reentered into a Chord
object so we can see the results.
Double-click the first Chord box (A) to open the graphic editor. The chord is displayed on
four staves, as indicated by the pulldown menu reading ’GGFF’. The top treble and bottom
bass clef are an octave below and above sounding pitch. This is convenient if your musical
object has lots of ledger lines.
The mini-view: These Chords are already in mini-view, allowing you to see their contents. Mini-
visualization is turned on and off with the m key (with the box selected). Using option-↑/↓ allows
you to move the miniview.
Choose order from the pull-down view menu in the Chord box:
2 Ircam documentation
The chord changes to display its notes in the order they were entered (which is not neces-
sarily an ascending arpeggio, although this happens to be the case here:
Ircam documentation 3
To add notes in the Chord editor, hold option and click where you’d like to insert the new
note. Then close the chord box.
When you evaluate the Chord box, it takes data from its inputs. If nothing is connected,
this will effectively reset the Chord to its default state since it will read the default settings of
the inputs. In order to preserve the notes we add, as well as the notes already present, we
must lock the Chord, if it is not locked already. Here is an unlocked Chord:
By clicking on the box to select it and hitting b, we lock the box, which is shown by an X in
the upper left-hand corner of the box:
A locked box retains its value(s) and always outputs them when evaluated. It does not take
data from its inputs. Make sure your upper Chord box is locked. Also make sure the lower
Chord box is not locked or else you won’t see the transposed notes.
Now evalute the patch by clicking once on the lower Chord object and hitting v. You’ll see
the newly transposed notes.
Now, enter another transposition value in the box connected to the right input of the om+
box. To transpose by a semitone you have to enter the value 100. A quarter-tone corresponds
to a value of 50 and a eighth of a tone to 25. (Notice that both quarter- and eighth-tone
pitches can be expressed in whole numbers- the advantage of midics.) If you enter a positive
number, the original notes will be transposed up, otherwise they will be transposed down.
The OM music object editors automatically ’round off’ pitches for display. By default, they
display pitches in a twelve-tone octave, even if the midics are not multiples of 100. To confirm
this, set the input of om+ to 50, which will transpose the notes up by a quarter tone. Evaluate
the lower Chord box. You won’t see and quarter tones. In order to turn on quarter-tone
visualization, use the pull-down menu in the Chord editor:
Now you should see quarter tones.
Tutorial 2: Inverting an interval
Topics
Changing the direction of an interval using arithmetic functions.
Key Modules Used

om+, om-, x-append
The Concept:
We’ll take two pitches from two different Note objects. We’ll add their difference to the first
one, reversing the direction of the interval, and combine them into a list with x-append. The
results will form a Chord.
The Patch:
First, open the two Note box editors, and change the note, if you want. You can do this either
by dragging the note with the mouse, or by clicking on it with the mouse so it is selected and
using the cursor keys. Holding shift while using the cursor keys moves the object by octaves.
Deleting notes is done by selecting them and hitting delete. Whatever notes you choose,
don’t forget to make sure the boxes are locked (with the b key) before continuing. Here are
the notes by default:
With these values,

Note (A) outputs 6000 as its midic. Note (B) outputs 7100. The om- function (C) takes
the difference of the two: -1100. This is the number that must be added to the first Note to
reverse the direction of the interval, with om+ (D).
We need to combine these notes into a Chord object. The online documentation (see
Quick Tour) tells us that the second input on a Chord object takes a list of midics. So, we
combine the original first Note’s pitch, 6000, and the result of our calculation, 4900, into a
list with the x-append function, which takes any inputs and combines them into a single list.
The resulting pitch is displayed below.
Tutorial 3: Building a scale
Topics
Constructing a scale using the dx->x function.
Key Modules Used

Note, Chord-seq, dx->x
The Concept:
Here we use dx->x to build a scale. dx->x takes a list of relative quantities and changes
them into absolute quantities starting from a point we define. In this case, we’ll use it to
define a scale (which is, after all, a set of relative intervals) which we can then build on any
note.
The Patch:
Open the NOTE box (A) and pick the note from which you would like your scale to begin.
Then lock it.
Enter a list of intervals in this box in order to construct a scale. Remember that an interval
of 100 is equal to a semitone. In the example we’ve entered a major scale.
In the example, the Note outputs 6000 as its midic. The dx->x function starts with 6000
and adds, sequentially, the elements at its second input. This list of midics is put into the
lmidic input of the Chord-seq object. Remember, you can see the names of the inputs by
command-clicking on the inputs themselves.
Evaluate the Chord-seq box to see your scale starting on your note.
Tutorial 4: Inverting an interval II
Topics
Inverting pitches using series functions
Key Modules Used

Chord, x->dx, dx->x, om*, first
The Concept:
Here we revisit tutorial 2 with an alternate solution. We will invert the interval, this time by
converting it into a relative interval with the x->dx function, and by multiplying this relative
interval by -1 to reverse its direction. We use the complementary function dx->x to convert
back to absolute pitch. x->dx finds the distances between elements of a series, and its sister
function dx->x converts relative values to absolute values, given some starting point.
The Patch:
OK, so we start with our Chord-seq object. We take the lmidic output, which produces
(6000 4900) in our example. On the right, we send that list of values to x->dx, which converts
them into a a relative distance. The output of x->dx will always have one less element than
the list, since it measures distances between elements.
In this case, the difference between the two is -1100. It’s negative because 6000 is con-
sidered to be the first value and the interval is thus downward. Remember that the order of
notes in a Chord object is determined by the order they were entered in. Had the other note
been entered first, it would be taken as the starting point instead of 6000. We multiply this by
-1 with om*. Which gives us 1100, the inversion of the interval. Now, we need to make that
1100 relative to the first note, 6000.
To do this, we use the lisp function first, which, you guessed it, takes the first element
of a list, to extract 6000 from the list (6000 4900). That value is passed to the first input of
dx->x, which uses it as a ’jumpin off’ point for the interval 1100 and arrives at the next note,
7100. These two notes are passed to the Chord object, which renders the inverted interval.
Tutorial 5: Retrograde
Topics
Here we perform the basic musical operation of retrograde on a group of notes. We’ll
transpose it in the process.
Key Modules Used

Chord, Chord-seq, om+, reverse
The Concept:
Here, we’ll take the lmidic output of the Chord factory. You can check to see what’s
coming out of the factory at this output by option-clicking this output. If you haven’t changed
the notes, you’ll see this in the Listener window:
? OM->(6000 5600 6400 7800 7200 7100)
Remember that the order of notes here just represents the order they were entered in. This
list of midics will be passed to om+ for a transposition and then retrograded with reverse.
The Patch:
The midics are passed to om+. Notice that om+ can accept both a list and a single number
as inputs. In this case, it adds the single number to all the elements of the list.
The resulting transposed list is reversed with reverse, which does just what it says it does.
The new sequence of notes is plugged into the second input of a Chord-seq object. We
could have plugged it into a Chord object, but the retrograde would not have been visible
since the notes would have been stacked one on top of the other. (Unless we went into the
editor and used the order selection from the pull-down menu)
Tutorial 6: Four basic operations on a 12-tone row
Topics
This tutorial applies what we’ve learned in the previous four to transformations of a 12-tone
row.
Key Modules Used

Chord dx->x, first, om*, om+, reverse, x->dx
The Concept:
Here we perform the operations of the preceding four tutorials on a single bit of mate-
rial, in this case from Boulez’s Structures. They are: transposition, retrograde, inversion and
retrograde of the inversion.
The Patch:
The original row from Structures is in the Chord box at the top. You may keep these or
change them around in the editor. Select the order option for the view (it’s less cluttered than
a big fat chord).
The four Chord objects will also need to be viewed in order mode. They can be evaluated
individually.
Evaluate Chord (C) and the notes are transposed:
The retrograde is accomplished by the reverse function. Evalute Chord (E):
The inversion is a little more complicated. The x->dx function (F) converts the notes into
intervals. Multiplying these by -1 (G) changes their direction. With dx->x, (I) we will rebuild
the list starting from the first element, which we extract with first (H). The result (L):
And finally, it’s easy to take the retrograde of this last row with the reverse function:
Tutorial 7: Changing melodic contour
Topics
A melody form is compressed or expanded vertically by a set amount.
Key Modules Used

Chord, Chord-seq, dx->x, x->dx, first, om*, om-round
The Concept:
Here we’ll take a group of notes ordered in time as a melodic contour that we want to play
around with. The midic values of the notes are taken from the Chord object, converted into
relative intervals with x->dx, and multiplied by a scaling factor. The result is converted back
into absolute values and passed back to a Chord-seq module.
The Patch:
The ’trick’ in this patch is the use of x->dx and dx->x to convert back and forth between
absolute pitch and relative intervals. x->dx (B) converts the midics of the Chord to intervals,
which are multiplied (D) by a scaling factor (C). The result is reconstructed with the help of
first and dx->x to start on the original first note.
The multiplcation factor (C) can be any number. Entering numbers smaller than 1 but
greater than zero will make the intervals smaller. Entering numbers larger than 1 will make
the intervals larger. Entering values smaller than zero will, as we saw in the last tutorials,
invert the interval sequence.
The first box takes the midic of the first note of the Chord, which is not necessarily the
lowest- remember, the Chord returns notes in the order they were entered, not the order in
which they occur in the chord.
The om-round function rounds any number to the nearest whole number. To check this,
change the multiplier at (C) to something with lots of decimals, .7654321 for example. The
midics that it returns will have lots of decimals. om-round changes them into integers (whole
numbers) before transmission to the Chord-seq object. This is unecessary. As mentioned
earlier, the music object editors have an automatic ’rounding function’ for display purposes.
Try this: Drag a connection from the output of the dx->x function directly to the second input
of the Chord-seq. Evaluate (by option-clicking) the output of dx->x to make sure the results
have lots of decimals. Evaluate the second output of the Chord-seq object. The decimals
are still there, right? Even though your midics were not multiples of 100, the Chord-seq
object displays notes as if they were rounded off- this is only for display and does not affect
the data itself.
Now, open the Chord-seq editor. From the pull-down menu, select 1/4 from the list:
You’ll notice some of the notes changing because their original midics were closer to
quarter-tones than to semi-tones. Change it to 1/8 and you’ll probably see some more notes
change to the more exact 8th-tone temperament.
Tutorial 8: Construction of a harmonic series
Topics
We’ll use the functions arithm-ser and om* to generate a harmonic series based on a
fundamental we supply. This patch is built for you in this tutorial but try building it yourself
from scratch.
Key Modules Used

Note, mc->f, f->mc, arithm-ser.
The Concept:
As many of you will remember from high school physics, (if you’re not yet in high school,
bless your precocious little heart) the integer multiples of a given frequency (the fundamen-
tal) represent a harmonic series present in all pitched tones. We can construct a musical
object with the same structure.
To do this, we first need to establish the frequency of our fundamental. Then we need to
multiply it by a series of increasing integers. Then the results need to be converted from
frequencies into notes (midics).
We introduce the abstraction (red patch)
The Patch:
The default note is a low C, two ledger lines below the staff. For very low notes such as
this, the mini-visualization may change to an octava clef (the bass octava clef in this view
displays notes two octaves above their true pitch):
In this patch, we’re going to use an what’s called an abtraction, better known as a red patch.
The fact that this patch is red indicates that it exists only within this patch. You can drag it to
another patch or make copies of it, but those copies exist separately and making changes in
one does not affect the other.
Abstractions: Abstractions have two advantages: firstly, abstractions are because they only exist
within the current patch. The blue patches, in contrast, represent a master copy of that patch-
when you drag a blue patch from the workspace into a patch window, you create a reference
to that patch. This means that the same patch can be used over and over in various contexts,
but if you make any changes to the patch, those changes also occur wherever else the patch is
referenced. Sometimes this is great; if you don’t want this, however, you must abstract a patch
from the blue patch- creating a local copy that you can manipulate with impunity.
We, on the other hand, are interested in a second, more mundane advantage of the red patch.
It’s a handy housekeeping device. You can put a bunch of functions which accomplish a certain
task within your function in an abstraction and give it an evocative name- it helps a lot once your
patches get big, and can save loads of time when troubleshooting.
So, let’s create the abstraction first, to hold the part of our patch which calculates the series.
Command-click somewhere in the patch window. the usual box appears:
Type patch.
The abstraction apppears.
We can now rename the patch ’harmonic series’ by double-clicking on the name ’mypatch’.
Open the patch by double-clicking on its icon. You will notice in the upper left corner two
buttons just like the two in the upper left of the patch window. They represent outputs and
inputs which can be added to the patch to allow it to communicate with the outside world.
Clicking the left-hand button adds an output, and clicking the right-hand button adds an input.
Once added, you can rename an output or an input just like you did the red patch.
Click to add four inputs and one output. If you add too many select them and hit delete.
Now rename them as shown and add the rest of the modules:
The inputs we’ve added are gateways to the outside world. We’ll pass data to these inputs
from outside the patch box.
To generate a harmonic spectrum we must multiply the frequency of the fundame ntal note
by the its place in the harmonic series (for example, we must multiply a fundamental at 60
Hz, by 1,2,3 etc...)
First, we need to convert the fundamental pitch from a midic into a frequency, which will
be done with the mc->f function. We’ll also need a list of integers representing the pitch
ratios of the series. For this we’ll use arithm-ser, which will generate an arithmetic series
beginning at begin, and adding step each time until end is reached. These amounts, like
the fundamental, will be set from outside the patch. Using 1 as step will return a list of
consecutive numbers (1 2 3...) and will thus return the entire harmonic series. If we wanted
to get the odd harmonics only, however, we could use 2 as step, generating the series (1 3
5 7...). Whatever we choose, the fundamental frequency will be multiplied by these numbers
to produce the series. The resulting frequencies will then be converted back into notes by
the module f->mc.
When you finish making the connections, evaluate the f->mc box. Why? This is because
the inputs that we added are producing the value nil, and the functions mc->f and arithm-
ser don’t know what to do with that value. They are expecting numbers. We must change
the inputs so that they return a different value by default.
Default Values at Inputs: When you’re building a patch, you’ll usually need to test it before
you’re finished. When you’re inside a patch, the inputs produce their default values, even when
connected to other stuff outside the patch. This can cause problems when evaluating your
work halfway through. Luckily, you can set the default value produced by an input. Choosing a
goood default value allows you to test the patch before you close the window. On the outside, this
default value is replaced by whatever you connect to the input. If you connect nothing, however,
the patch behaves as if you used this default input. In this way you can set the ’default behavior’
for a patch.
Let’s change the default values for our inputs by double-clicking the arrow icons inside the
patch window. For each one, a window like this comes up:
Here you can set the default value of the inputs, as well as add a bit of information about
what they do. Naming them is done by clicking on their names in the patch window.
Input and Output Names: Remeber the pop-up help you get Command-clicking on inputs and
outputs? That pop-up help also appears for your own custom-built patches, and the names that
you give your inputs and ouputs within the patch are the names that pop up in the bubbles when
command-clicked from the outside.
Giving your inputs and outputs names is a good habit to get into, it’s easy to forget what’s what
when your screen is filled with icons.
If you’ve been using the pre-made patch in the Tutorials folder, the default values have
already been set. Try rebuilding the patch from scratch to see what we mean.
Tutorial 9: Dealing with data types
Topics
Introduces the concept of data type.
Key Modules Used

Note, first, om*, Chord
The Concept:
This postlude will demonstrate what is meant by data type.
The Patch:
In LISP, inputs to functions and classes are typed, which is to say they expect a certain
kind of data. To see what we mean, bring up the online documentation for the Note object by
selecting it and hitting d. The inputs are listed, and we see that the second, midic, expects
a number.
Now, drag a connection from the list of integers to this second input of Note and evaluate.
You’ll get an error like this:
This is because a list is a different data type than a real. real is LISP’s term for any kind of
number.
first, on the other hand, only accepts lists as input, since it takes the first element of a
list. Give the float to first as input and you’ll get a similar error. float is LISP’s term for a
number with decimals.
Now, plug the list of integers into first. first has what it wants; evaluating gives the
answer 6900. You can take this 6900 at the output of first and plug it into the second input
midic of the Note object. It too, now has what it wants. You can find out the data types
accepted by any function by looking it up in the Function Reference.
Take the list of integers and plug it into the second input lmidic of the Chord object. This
input expects a list, and you’ll see the notes in the mini-view.
Now, take the first output of the top Note object, self. self exists for many classes, and
outputs the entire object. Evaluate self and you’ll see something like #<note #x9327B36>
in the Listener. This is the Note object, and it is a data type like list and float. Plug this into
the first input of the lower Note object. Evaluating effectively duplicates the Note because it
passes itself to the self input of the other note.
Plug the self output of the Note into one of the inputs of om*. Error. This is because the
Note object is not just a midic- it’s the collection of attributes of that Note, including volume,
duration, and MIDI channel. The self output of the Note contains all the information from
the other inputs. As seen earlier, if you want to take just the midic of the Note, you must take
it from the midic output. Do this now and plug it into om*. At the second input you may use
either a integer or a list or a float. None of these cause errors. Why not?
OM functions are what is called a generic or polymorphic function. This means that they
can be programmed to perfom differently depending on the data type they are given as input.
This will be discussed in more detail later.
Now take the self output of the Note object and plug it into the self input of the Chord
object. The note appears in the Chord. What gives?
You’ve just witnessed a concept called . Inheritance will be explained in more detail later,
but for now, you should know that all classes in LISP, but particularly the music objects, can
’inherit’ information from simpler objects. A Chord is collection of Notes; it can therefore
inherit from the Note class.
Play around with the functions and objects in this patch to get your mind around the concept
of data type.
Chapter 2. Playing MIDI I
Tutorial 10: Playing MIDI
Topics
MIDI output with OM via Midishare and the QuickTime GM Synth
Key Modules Used

pitchwheel, pgmout, repeat-n, Chord-seq
The Concept:
This tutorial covers how to output MIDI from OM via Midishare. It assumes you’ve installed
and configured Midishare- if you haven’t see the chapter on Installing Midishare Even if you
have no MIDI equipment, you can still use Apple’s built-in QuickTime Musical Instruments
synthesizer (which responds to MIDI messages just like any other MIDI instrument) to listen
to your work. If you’re working in 24- or 48-tone octaves, you’ll need to reconfigure QuickTime
to play quarter and eighth tones. This is covered in the second half of this Tutorial.
The Patch:
Changing MIDI instruments

In the top half of this patch we’ll send the notes of a Chord-seq out over 12 difference
MIDI channels:
29
Ircam documentation
We’ll use the two lists, (A) and (B) as program changes and MIDI channels, respecively.
Notice we’ve left out channel 10 as that channel is reserved for percussion instruments on
the General MIDI standard.
Evaluating pgmout will send these program changes on the MIDI port designated at its
third input (D). This function always returns nil in the Listener- the MIDI messages are sent
anyway. Evaluate this box now.
Now enter some midicents in the list (E). Keep the list limited to 12 elements. Connect list
(B) to the seventh input lchan of the Chord-seq (F). The numbers in this list represent MIDI
channels to which consecutive notes will be assigned, and is why we wanted the lists to be
the same length. Evaluate the Chord-seq object and open its editor.
Set the display options pop-up to channel. A color-coded numebr representing the MIDI
channel appears next to each note. If you play it, each note will sound on a different channel,
with a different timbre as a result of the pgmout command we issued.
To reassign a piano sound to all the channels, use the pgmout module at (G), which issues
a program change back to 1 on all channels.
Playing microtones using MIDI

Now let us build a simple patch that will play microtones using Chord-seq.
First, we’ll use arithm-ser to create a list of midics running from 0 to 200 by increments
of 25, representing eighth-tones.
We add 600 to each element using om+ so that the list starts on 6000. The result is (6000
6025 6050 6075 6100 6125 6150 6175 6200) Evaluate the Chord-seq.
In the editor, you must select 1/8 from the temperament pop-up menu in order to see
the eighth-tones displayed. However, they don’t play back correctly. This is because the
MIDI standard does not directly incorporate intervals smaller than a semitone. To get around
this, we take advantage of the fact that OM automatically sends microtones on other MIDI
channels. Normal semitones are sent on channel 1. Microtones are sent on other channels
based on how much higher they are:
Sharp by Sent on MIDI channel
One eighth-tone 2
One quarter-tone 3
Three eighth-tones 4
We’ll send a pitchwheel message to each of channels 2, 3, and 4, detuning the entire chan-
nel so that its notes will play back corectly. The upper pitchwheel box sends the following
messages:
• 0 to channel 1 which stands for no pitch bend

• 1024 to channel 2 which stands for one eighth-tone up
• 2048 to channel 3 which stands for one quarter-tone up
• 3072 to channel 4 which stands for three-quarters of a tone up.
8190 is the highest possible value for pitchwheel. It represents a full tone on most MIDI
instruments. This can be changed, however, and some MIDI instruments map the pitch-
wheel differently, taking 8190 to be only a semitone. In this case you need to evaluate the
second pitchwheel function.
Once you evaluate pitchwheel, the eighth-tones play back correctly. The lowest pitch-
wheel resets the other channels to normal tuning.
Chapter 3. Using Aleatoric Elements
Tutorial 11: Constructing a Chord with random notes from a

harmonic spectrum
Topics
Using a random functions to choose elements from a harmonic series which are then built
into Chords
Key Modules Used

pitchwheel, x-append, om-random, nth-random, repeat-n, om+, Chord-seq
The Concept:
The repeat-n box evaluates the function at its first input a number of times (indicated
at the second input) and returns the result as a list. The om-random box returns a random
number between its two inputs. We start with the harmonic spectrum chord generated in
Tutorial 8. We’ll build 5 groups of random chords from its elements, then transpose the
second of the groups up by a fourth and the fourth of the groups up by a fifth, creating a sort
of demented I-IV-I-V-I progression.
If you built a different harmonic series in Tutorial 8 and want to use it here, hold option and
drag it into the Tutorial 11 window- this will create a copy of your original object. Note that
this works with any object or group of objects.
33
Ircam documentation
The Patch:
nth-random (C) chooses a random note from the chord (A). This is repeated by repeat-n
(E) a random number of times set by om-random (D). This will yield a list of random midics of
a random length. This entire operation is itself carried out 5 times by the second repeat-n
box (F). Each time it is evaluated it returns a group of 5 chords (in midics) with between 3
and 10 members.
x-append creates a list with all its inputs. In this case, all the inputs come from repeat-n.
Since repeat-n produces itself produces a list, x-append will create a list of lists- what is
called a tree.
The second and fourth inputs to x-append are passed through om+ (H & I) for a transposi-
tion. The others are untouched. Note that x-append has 5 inputs here- each of those inputs
causes repeat-n to be evaluated anew. This means that each group of 5 chords will be
different, randomly generated.
The result of x-append is a list of lists. Remember the discussion of data type in Tutorial 9?
Well, the lmidic input of the Chord-seq object can take either a list of integers, in which
case it assumes they are individual notes to be taken in order, or a list of lists, a tree, in
which case it assumes each sublist represents a chord. That is what happens here.
When you are done, you can play the Chord-seq. You may need to evaluate the pitch-
wheel function in the upper-right in order that the microtones play back correctly. (See Tuto-
rial 10 for more info).
Tutorial 12: Building a sequence of random notes: om-random
Topics
Using om-random and repeat-n to build sequences of repeated notes.
The ’eval-once’ mode for modules.
Key Modules Used

om-random, repeat-n, Chord-seq, x-append
The Concept:
This example shows the use of om-random for generating random repeated notes. We
will use this function in two different ways: generating pitch and generating the number of
repeated notes. om-random will be used in both normal and ’eval-once’ modes.
The Patch:
First of all we will generate midicent notes by using om-random. This function takes as
arguments two numbers (integer or float). The two arguments represent the range of num-
bers that om-random will produce, inclusive. For our example, we will use MIDI notes and
then multiply the output by 100 to obtain midics. On the right, we’ve connected these to
repeat-n, allowing us to obtain a series of 5 random midics in a list:
Now let’s compare the outputs of (B) and (C). The output of the B patch is a list of five
different values each time it is evaluated, while the ouput of C patch is a list of five identical
values. Why? The difference is the state of the om-random patch. Notice the little "1" in the
upper-left corner of the om-random on the right? That means the function is in ’eval-once’
mode, and will only evaluate once for each time the flowchart is evaluated. This means that
it will return the same value each subsequent time it is called by repeat-n. In contrast, the
other om-random generates a new random midic each time.
To put a patch into ’eval-once’ mode, select it and hit b this brings up the little "X", which
means the function is locked. The lock is one of four special modes which can be applied
to boxes. Clicking one on the "X" changes it into a 1, which indicates ’eval-once’ mode. You
can return the box to normal by hitting b a second time.
On the left, we’ve copied B and C, replacing the input 5 with another om-randomto generate
the integers for the number of repeated notes. Notice that we have used one om-random
module instead of three. That is because (D) is in normal mode, and will be evaluated three
times because its output is connected to three other inputs.
Connecting the outputs of the three repeat-n modules to x-append (E) will result in one
big list.
We will use a Chord-seq editor to collect our resulting notes. The first input of the Chord-
seq editor is self, the object itself, as with all editors and classes. The second input is
the midic input. Remember the idea of inheritance from Tutorial 9? The Chord-seq class
inherits from the Chord object.. This means that you can pass a list of Chord objects to the
first input self of a Chord-seq to obtain a sequence of chords.
Alternatively, as described in the last tutorial, the lmidic input can accept a tree of midics,
where each sublist is interpreted as a chord. However, we’ve entered a flat list with no sub-
lists, so Chord-seq will interpret this to mean a series of notes- a series of one-note chords,
actually. Try evaluating the second output of the Chord-seq and compare with the output of
x-append (E).
The third input of the Chord-seq object is a list of onsets times, i.e. chord positions in the
sequence in elapsed milliseconds. The elements of this list are paired up with the elements
of lmidic to determine where the chords are. By the same token, the fourth is a list of
durations, also in milliseconds. In the example above we have changed the default values
(0 1000) and (1000) to shorter durations so that the thing will play faster. If we enter just
two values for the onsets then Chord-seq assumes that these two values define the interval
between chords. This is what happens here; Chord-seq puts the notes 100ms apart.
The same is true of the duration input, ldur. A single value causes Chord-seq to assume
that the duration is global and applies to all notes. If you enter more than one duration but not
enough to pair off with every chord, the last value entered is used for all remaining chords.
The same is true of the onsets.
Tutorial 13: Another random sequence
Topics
The inputs ldur, lvel, and legato.
Key Modules Used

om-random, Chord-seq, repeat-n, dx->x
The Concept:
We use a similar structure here, extending our random procedure to the onsets and dura-
tions of the notes.
The Patch:
We will use the same patch as in tutorial 10. om-random will be back in its normal mode,
because here we don’t need repeated notes.
At (B), we will use patch we used for durations with slightly different parameters to produce
lists of numbers appropriate to onsets and durations. om-random will generate values be-
tween 100ms to 500ms. (Durations and onsets in OM music editors are always expressed
in milliseconds.)
We want to create a sequence with no gaps between the notes. This means that the onsets
and the durations have to match up. We make sure that the same sequence is used by
setting repeat-n to ’eval-once’ mode.
There’s another problem. Durations are simply the durations of the notes once struck. Off-
sets, on the other hand, are measured from the beginning of the sequence. This means we
can’t use the same list for both lonset and ldur inputs. Using dx->x, we turn the list of
durations (the time between notes) into a list of onsets relative to the starting time, 0.
As we just learned, notes in a Chord-seq can overlap. The Chord-seq object can thus
accept polyphonic input. For example, place a Midifile class in the patch and evaluate it.
A dialog window comes up. Look for the file INV6.MID in the exampleFiles/Midi folder,
in the main OM folder. This is a MIDI file of the 6th two-part invention by J.S. Bach. Once
evaluated, lock the box.
Opening the Midifile brings up a piano-roll style editor where you can see the two channels
of the MIDI file, color coded for clarity:
The Chord-seq class can take a MIDI file as input to its self input, and it will be tran-
scribed:
Opening the resulting Chord-seq and selecting dur from the view options pop-up menu will
show the durations of the notes represented as colored bars:
Returning to our patch, giving a single number to all 3 second inputs of the repeat-n box
causes each element to be evaluated 3 times, producing lists of the same length for our
midics, onsets, durations, and note velocities.
Note velocity is MIDI’s way of indicating how hard a note is struck. You can visualize the
velocity by selecting dyn from the view options pop-up in the editor. Here is an example in
page mode, which is turned on using the page view button, circled in red.
OM turns the velocities into traditional dynamic marks using a table you set up in the Prefer-
ences panel. Now look at the far right-hand input, legato. Setting this to 0 leaves durations
as they are. Any other number, however, will override the ldur input, and set the durations
to a percentage based on 100 being perfect legato- each note lasting exactly as long as it
needs to. Smaller numbers will result in gaps in the sequence, longer numbers in overlaps
(you need to set the view to dur).
Chapter 4. Flow Control I: Predicates
Tutorial 14: Random construction of a sequence
Topics
The idea of flow control; introduction to conditional functions and predicates.
Key Modules Used

omif and om=
The Concept:
This patch uses the omif module to choose between two possible evaluations based on
the outcome of the predicate module om=. The structure for generating the random notes is
otherwise similar to the previous two tutorials’.
45
Ircam documentation
The Patch:
At (A), we will use om-random as a ’coin toss’ generating 0 or 1.

om= is what is called a predicate. Predicates perform some kind of test and then return
true or false. "True" in OM is represented by a special data type called the truth value, t.
"False" is usually represented by the empty set, nil, although most conditional controls will
take anything not t as a "false" value.
Predicates are usually used as tests which feed into other modules controlling program
flow. The flow of a program or an OM patch determines what will be done and in what order.
OM patches are flowcharts which graphically represent this flow. Mastering flow control is
an important part of learning to program because without it patches will always act the same
way.
om= (B) tests the output of om-random against its second argument, 0. If om-random outputs
a zero, the test will be true and will return the truth value t. If the output of om-random is 1,
om= will return nil for false.
omif is a module used to control program flow. It is modeled on the simple if - then -
else syntax you may be familiar with from other programming languages. Its function can be
summarized:
If it receives t at its first input, it evaluates whatever is connected to its second input. If not,
it outputs nil. There is a third, optional input which can be added by selecting the function
and hitting option-→. If this third input is present, omif evaluates it instead of returning nil
when the predicate at the test input is false.
So, repeat-n (E) calls omif (C) 20 times. Each time, the predicate om= is evaluated against
the random result of om-random. If the test is true, omif passes 6000. If it is false, the other
branch of the patch is evaluated producing a random middic between 4200 and 8200. The
results are collected in a Chord-seq.
Chapter 5. Flow Control II: Loops
Tutorial 15: Introduction to omloop I
Topics
Basic enumeration of a list with omloop
Key Modules Used

pgmout, omloop, om<
The Concept:
In this example notes are generated and are filtered onto two midi channels depending
on their pitch. All notes above 6000 midicents (inclusive) will be played on channel one.
Other notes falling under 6000 midics will be played on channel 2, which will have a different
instrument sound. In this way the melody will be split between two instruments in the Chord-
seq module.
The Patch:
49
Ircam documentation
This patch contains two different sections: Section A, whose task is to send MIDI mes-
sages, and sections B-C-D which generate the notes.
pgmout is a MIDI function which sends program change messages to internal or external
MIDI devices, such as the Quicktime synthesizer. As you know, this function always returns
nil value in the listener. x-append is used as a "trick" to evaluate both pgmouts simulta-
neously. The first sends the program change 56 to channel one, while the second module
sends program change 1 to channel two.
At (B), we’ve created an abtraction (red patch). Remember these? Look back to Tutorial 8
if you don’t remember. Here’s what it looks like on the inside:
In this patch we have reproduced the random pitch generation patch (A) found from tutorial
13. You could just option-drag the elements you need from that Tutorial into this one. Notice
that we have added an input for the times argument of repeat-n in order to be able to
control this parameter from within the main patch. Notice that note generator (B) is in eval-
once mode. This is because its output is connected to two modules (Chord-seq and omloop)
. If our patch note generator was in its normal mode it would have yielded different results in
the Chord-seq module and the omloop resulting in a mismatching of elements (notes and
channels).
We need to create a list of channel assignments based on the pitches of the generated
notes. We will use omloop in one of its most common roles- to go through the elements of a
list, one by one, and collect some sort of data.
When you create an omloop module, it looks like this on the inside:
By default, it has no inputs. Inputs are added to the function by clicking on it outside in the
patch window and using option-→, just like for x-append.
Opening it, we distinguish three groups of modules: the iterators, the accumulators and
the outputs. (For further information about these, please consult the Function Reference.)
.These modules are specific to omloop and can only be accessed within this module. When
omloop is in its editing mode (i.e opened), nothing connected to these special functions can
be evaluated. This is because these special functions will have different values each time
the loop is evaluated. One must first close the module and evaluate its output as with any
other function.
Let us now examine our loop patch. We will use omloop to test each member of the list
output from our note generator patch. As we can see, the patch is divided into four functional
parts:
First we will use the listloop iterator (B), which will ’ticks off’ each member of a list. On
each repetition of the loop, the next member of the list is passed by listloop to (C). At
(C), the enumerated element could be processed in any way. Here a midicent will be tested
using omif using the predicate om<. If the midicent is smaller than 6000, omif will output 2,
and if not, it outputs 1, our channel assignments. This result will be collected by the collect
module. The collect module simply accumulates the results from each repetition of the
loop into a list.
collect’s first output is connected to eachTime, which triggers the repetitions of the loop,
and the second to finally, which carries the results of the finaly repetition of the loop to the
output. Whatever is connected to finally gets passed to the output of the loop in the main
patch window. This is the usual way to connect collectors and is valid 90% of the time.
Now let’s verify our result in the Chord-seq editor, choosing in channel from the view
options menu:
Tutorial 16: Introduction to omloop II
Topics
Another example of using omloop with listloop
Key Modules Used

omloop, list, om+, om-
The Concept:
Using the omloop module, we will add an upper and a lower harmony note to each note
of a melody at a set interval.
The Patch:
Edit your series in the Chord object (A) after setting it to order mode.
Choose an interval to use for the harmonizing. 1100 midics represents a major seventh.
Add two inputs to omloop before opening its editing window (with option-→. Then omloop
and name these inputs as shown below. (Again, naming inputs is not necessary, but it is
practical, especially when using complicated patches with many variables. Documenting
your patches by naming inputs and adding documentation in the input boxes is a good way
to keep track of data and patch functionality).
In order to enumerate each element of the list coming from the Chord, we use listloop
(A). Now create a red patch (B). Notice that whenever a patch is created within a patch, this
patch appears as a red patch. Open it, add inputs and an output:
Coming into pivot, we will have an different enumerated note from the melody at each
repetition of the loop, while ’interval’ is the interval we chose, in midicents (in our example
we chose 1100 midics). The list function creates a new list by grouping its inputs together
and slapping on a new pair of parentheses. This is different than x-append, which merges
two lists into one. Compare the two. list will create a list with three midics, the first and last
being a major seventh above and below the middle.
The results will be collected using collect and sent to the output finally (D). The output
of omloop will thus be a list of chords (a list of lists of midics, i.e. a tree of midics) You can
listen to the result in the Chord-seq which is connected to omloop’s output.
Chapter 6. Using Musical Objects II
Tutorial 17: Generation of a melodic sequence from harmonic

reservoirs
Topics
Generating a melodic sequence with elements of predetermined chords.
The idea of .
Key Modules Used

nth-random, x-append, flat
The Concept:
We will generate a note sequence using four Chord objects as harmonic reservoirs. Each
Chord contain a traditional harmonic chord structure. We will use nth-random to randomly
choose notes from each reservoir, sequentially. We will concatenate (put together!) the result
with x-append, preserving the harmonic order of the reservoirs (I-IV-V-I).
59
Ircam documentation
The Patch:
Enter the desired harmonic sequence in the Chords (A). In this example we used the tonal
sequence I-IV-V-I in C major scale.
Each nth-random (B) will randomly pick a note in the Chord reservoirs.
We will ’iterate’ (repeat) this procedure 4 times using repeat-n.
x-append (D) will concatenate these results in harmonic order (i.e first we will have 4
randomly choosen notes from the first reservoir, then 4 from the second one etc...).
In order to have this whole harmonic sequence repeat twice, we will again use the repeat-
n function (E). Notice that all these iterations yield different results due to the fact that we are
using nth-random function which is evaluated anew at each iteration (on the C and D levels)
and therefore returns different results each time.
Try this: evaluate the output of the repeat-n at (E). You should get something like:
? OM->((6400 6700 6700 6700 7200 6000 6500 6500 5900 5900 6500 6700 6000
6000 7200 6000) (6700 6400 6700 7200 6900 7200 6000 6900 6500 5900 6500
5900 6000 6000 7200 7200))
Notice that this is a list of two lists. Plug this directly into the lmidic input of the Chord-seq
object. You’ll get two huge chords. This is because the list has multiple levels. When a list
has other lists as its elements, we say it is nested. A tree is a nested list. When Chord-seq
encounters a nested list, it assumes the sublists are chords. In order to display this as a
string of ordered notes, we must ’flatten’ the list. This is accomplished with the LISP function
flat, which removes nesting. Reconnect the output of flat to the Chord-seq and evaluate.
A note from Mikhail Malt: The old version of this patch (in a patchwork version) was a gift to
Camilo Rueda when he was at Ircam as a Patchwork developper. Just in order not to break the
Colombian tradition, this OM version is dedicated to Carlos Augusto Agon, another nice Colom-
bian guy working on Computer aided composition environments.
Tutorial 18: Generation of a note sequence by interpolation

between two chords
Topics
Using random elements and interpolation to generate a sequence of notes between two
harmonic areas.
Key Modules Used

interpolation, omloop, repeat-n, flat, Chord, Chord-seq
The Concept:
In this tutorial as in previous ones, we will use randomly generated notes from particular
chords to construct a sequence. This time, however, these chords are the result of an inter-
polation between two seed chords we choose. The first chord is in the lower register, and the
second is in the upper register. The result of the interpolation will be an ascending sequence
of chords and so will be the general tendancy of our generated note sequence.
The Patch:
We have choosen two chords of same density (i.e same number of notes) in Chord (A)
and Chord (B).
The module interpolation (C) will interpolate between these two chords using n steps. In
our example above we have chosen to create 12 steps (chords A and B included). The last
argument of interpolation defines a curve for the calculation. A curve of 1 is linear, meaning
that the arithmetic midpoint of the interpolation will fall exactly 50% of the way through the
steps. In a non-linear interpolation specified by values smaller than 1 (but greater than 0)
or greater than 1, that midpoint will be displaced towards the front or back of the sequence.
This is easier to understand if you can see it. Open the Chord-seq at (D) and check out the
interpolation with curve of 1.0:
Now, replace the curve argument of interpolation with .3 and evaluate. Notice that
the intervals between chords are greater at the beginning of the sequence. Now replace
curve with 1.7 and reevaluate. Notice how the large intervals are now towards the end of
the sequence. Reset curve to 1.0.
In order to apply the same process as in Tutorial 16, (picking n random samples from each
chord of the interpolation) we will use omloop (E):
In listloop will enumerate the elements of our interpolation one by one for each repetition
of the loop. nth-random will randomly choose one note of each of these chords. Connecting
nth-random’s output to a repeat-n module will repeat this n times on each chord. Notice that
repeat-n’s second input is getting data from an additional input that we named n-samples
in order to choose the number of times we want to sample each chord from outside omloop’s
editor window (in our example it is 4 notes per chord, see the general patch). All results will
be collected by collect and ouput by finally.
As in the last tutorial, the output of omloop will be a list of lists equivalent to a list of chords
when plugged into Chord-seq. In order to have a sequence of notes instead of chords, we
have to flatten the list with the function flat.
Chapter 7. Breakpoint Functions
Tutorial 19: Using BPFs I; Graphic representation of a series of

notes
Topics
Using a BPF (Breakpoint function) to analyze melodic contour.
Key Modules Used

BPF, Chord, Chord-seq
The Concept:
In this patch a series of values is used to produce a graphic representation of a melody
and a melody itself. The list of midics is passed to the lmidic input of a Chord-seq object
to view it as a melody, as usual, but also to the y-points input of a BPF object, where it is
converted into a graph (a contour).
65
Ircam documentation
The Patch:
Enter some values in midicents here at (A). Remember that in midicent-notation C3 is equal
to 6000, C]3 is equal to 6100, and so forth.
The Chord box can visualise these values either as a chord or as a sequence ("order"
mode). Evaluate the box and see the different types of musical notation.
The Chord-seq box receives these midicent-values and translates them into musical nota-
tion. Evaluate this box to see the musical result.
The BPF box translates the midicents into a break-point function. On a grid with x and y
axes, the graph of a break-point function is a continuous line. (A break-point function can
have at most one y value for each x value. In graphic terms this means that a given vertical
line can only intersect the graph once. Evaluate the box to see the graphic representation of
your sequence of notes.
Tutorial 20: Using BPFs II: Sampling a sequence of notes
Topics
Sampling a melodic contour to produce a sequence of notes.
Key Modules Used

Chord, Chord-seq, BPF, bpf-sample, list-max
The Concept:
Here we sort of reverse the last tutorial: we take a melody, turn it into a graphic melodic
contour, then use bpf-sample to take that shape and turn it back into values. When con-
verting it back to values, we can take more or fewer samples than the original sequence,
creating a "smoother" melody.
The Patch:
Enter a sequence of notes in "order" mode in the Chord and lock it:
The BPF box converts the midicents coming out of the Chord box (A) into a break-point
function, a melodic contour.
The bpf-sample takes a number of ’pictures’ of the height of the graph between the x-axis
values specified at the inputs xmin and xmax and returns them as a list. In our example,
there are 13 elements in the chord. We tell bpf-sample to sample the BPF 13 times, so the
values we get back will be the same ones we put in. However, we are sampling the height of
the graph. If we enter a number other than 13, we will take that many samples of the graph,
and they’ll no longer line up with the original elements. This will create a new melody starting
in the same place and having the same shape but with a different number of elements. Try
replacing the 13 with 26.
Tutorial 21: Using BPFs III: Scaling a melodic contour
Topics
Scaling a melody to fit within a given interval
Key Modules Used

BPF, bpf-sample, first, om-scale, om-round
The Concept:
Here we start with a BPF object. We sample it at as many points as we like with the bpf-
sample to create a contour with n elements (in this case, 13). These points are then scaled
with om-scale to occur within the interval specified at its minout and maxout outputs. We
set these numbers using midic outputs of Chord objects; the result is that the melodic form
occurs between the two extremes.
The Patch:
Open the BPF:
Here’s a graphic editor for BPF objects. You add new points to the graph by using the Add
Points Tool:
...and clicking on the graph. If you make a mistake, use the Select Points Tool (first on
palette) and select the points by clicking or dragging, then hit delete.
Open the Chord box (D) and enter one note. The note you enter will be the lowest note of
your melodic profile.
Open the Chord box (F) and enter one note. The note you enter will be the highest note of
your melodic profile.
The midic outputs of the Chord objects give a list of midics. Even though they only contain
one note, they still return that midic in parentheses, a list of one element. To isolate this
(single element) of the list, we use first, which takes the first (and only) element of these
lists. These midic values are passed to om-scale, which adjusts the list at its first input
such that the relative distance between elements stays the same but the highest and lowest
values come out to be the inputs minout and maxout.
Note that the om-round box is technically superfluous; we could have entered the result of
om-scale directly into the Chord-seq, which rounds pitches off for display anyway. It does,
however, make the pitches easier to read for humans. Compare the output of the om-scale
function with the output of om-round.
Chapter 8. OM Music objects Chord-seq and
Voice
Tutorial 22: Chord-seq: Onsets and durations I
Topics
Managing durations in the Chord-seq editor
Key Modules Used

Chord-seq, dx->x, x->dx
The Concept:
In traditional music notation rhythm is represented as a single value (quarter note, eighth
note, etc...). These values don’t tell the whole story, however. The duration alone is not
sufficient information when trying to place notes in time. One also needs to know when in
time these values happen. Metric information consists then of two quantities:
Onsets are the ’time addresses’ of events. An onset represents the absolute location of
the beginning of a note measured from a fixed point, the beginning of the sequence. In OM,
onsets are always measured in milliseconds.
Durations are the lengths of these events. A duration represents the absolute length of
note measured from the onset. In OM, durations are always measured in milliseconds.
The Patch:
Let’s take the following list of durations:
75
Ircam documentation
Chapter 8. OM Music objects Chord-seq and Voice
(1000 2000 500 500 500 250 250 1000)
Which, if transcribed, could be represented by the following:
We will take this list of durations and connect it to the ldur input of a Chord-seq. These
durations have to be converted into onsets relative to the beginning of the sequence be-
fore they are given to the lonset input. For this we use dx->x, which requires us to tell it
the absolute starting point, which in this case is 0ms, the beginning of the sequence. This
produces
(0 1000 3000 3500 4000 4500 4750 5000 6000)
which we pass to the Chord-seq.
In example 2,
we will use this same list of onsets (C) as produced by dx->x. We will not specify anything
at the duration input. This will result in ’wrong’ duration values, i.e all notes defaulting to a
length of 1000 milliseconds. The sequence will thus have gaps or overlaps, as you can verify
in the editor:
Rather than calculate the durations, we can fix this by using the legato input. The legato
input overrides the default durations. It is a value representing a percentage of the perfect
legato, with every note ending exactly as the next note starts. If we enter 100 here we fix all
the durations of the sequence, as we’ve done in example 3:
Alternately, we could use the function x->dx to turn the list of onsets into a list of durations.
Tutorial 23: Chord-seq: Onsets and durations II
Topics
Using rests in a list of durations for Chord-seq.
Key Modules Used

Chord-seq, omloop, omif, dx->x, remove
The Concept:
In the last tutorial we learned more about the use of onset and duration lists. These con-
cerned only actual note durations. What if we wanted to use rests or offset our entire rhythmic
sequence by a certain amount? In this tutorial we will demonstrate a practical way to deal
with rest and note durations in milliseconds, and this by using only one list of consecutive
durations and rests. All the programing will be done inside an omloop method which will
return correct onsets and durations for use in a Chord-seq
Chord-seq does not recognize negative numbers as rest. The omloop will turn all the dura-
tions into offsets (including the negative ones), and then remove the elements corresponding
to the negative durations so that only real notes will remain in the lists.
The Patch:
We take a list of durations with negative numbers, which we will take to represent rests.
They are processed in an omloop module which will output two lists for use at the ldur and
lonset inputs of the Chord-seq object.
The interior of our omloop looks like this:
Here’s whats going on. This loop has two outputs (you add an output to omloop by adding
an input to the eachTime and finally functions. Stuff on the left is processing onsets, stuff
on the right is processing durations.
At (A), we use listloop to enumerate the elements of the list of durations we gave the
loop.
The om-abs function at (B) returns the absolute value of a number or list. It basically strips
negative signs from numbers if they have them. We put the list through this module before
passing it to dx->x so that the rests can be incorporated correctly (they still last a positive
amount of milliseconds).
We will use two omif boxes (D), one for onsets, the other for durations. These will be used
as filters: If an element of our list is less than 0 (meaning it is a rest), both omifs will return
nil. If not, the first omif will return the onset time, the other the duration.
All that’s left to do is post-process both lists in order to remove the nil elements, otherwise
we cause an error. We do this with the remove function, which simply deletes all occurences
of something from a list. We tell it to delete all the nil elements.
The results are plugged into the ldurs and lonset inputs of the Chord-seq. We have
two 2000ms notes separated by rests of 1000ms:
Tutorial 24: Voice I
Topics
Introduces the concept of the rhythm tree.
Key Modules Used

Voice
The Concept:
The Voice object incorporates traditional rhythmic notation. Instead of working with onsets
and durations, the rhythmic information in a Voice object is carried by a special type of
tree called a rhythm tree. Our goal in this patch is just to construct a simple rhythm tree
from scratch that will be acceptable to the Voice box. An entire chapter is devoted to the
concept of rhythm trees in the Main Section.
Consider the following example of a rhythm tree:
(? (((4 8) ((4 (1 1 1 1)))) ((4 8) ((4 (1 1 1 1)))) ((4 8) ((4 (1 1 1 1))))))
While difficult to look at, the structure is actually quite logical:
The rhythmic structure
• The first element of the tree is a question mark ’?’, which is a placeholder for a certain
number of measures. Rhythm trees get very complicated. The question mark tells OM to
calculate the number of measures from the rest of the tree and replace the question mark
with this value. It’s a timesaver.
• The second element of the tree is the rhythmic structure, in the form of a list of measures.
• Each measure is itself a list containing two elements, a time signature and a list of pro-
portions, representing the way the duration represented by that time signature is divided.
• The first list, the time signature, can be represented in two different ways:
• As a list (4 4) (meaning standard 4/4 time)

• Or as a double-slashed fraction: 4//4
• The second list, the list of proportions, determines the rythmic structure within the time
signature.
The structure is again a list of lists where the first element is the number of pulses
contained in the measure followed by its subdivision. In the example above, we have
four equal pulses. We could have written
(4 (3 1))
which represents a dotted half-note followed by a quarter note in a 4//4 measure.
Rests
In the lists representing the subdivisions of the pulses, rests are represented by negative
numbers. For example,
(? ( ((4 8) ((4 ( 1 -2 1)))) ) )
will output:
Ties
By the same token, ties are represented by floats (decimals) as follows:
(? ( ((4 8) ((4 ( 1 -2 1)))) ((3 4) ((3 (1.0 2)))) ) )
represents:
Irrationals (tuplets)
Irrationals such as triplets, quintiplets etc. are quite easilt represented by subdividing a
pulse by an odd number. For instance, if we subdivide a pulse into five beats (instead of
four) we will obtain a quintuplet. Here is a pulse divided into 4: the result is sixteenths:
(?(((1 4) ((1 (1 1 1 1)))) ))
And the same pulse, this time divided into 5:
(?(((1 4) ((1 (1 1 1 1 1)))) ))
The Patch:
Here we’ll just try to build a simple sequence of three measures of 4/8 with a pattern of
repeated eighth notes.
We’ll ’reverse engineer’ the rhythm tree. Since the tree is a nested list, we’ll build the indi-
vidual elements using the list function (and repeat-n, where necessary) and pass those
elements to other list functions, making them sublists of a tree. So, reading from the bottom
up:
At (A) we add the first element, the question mark. Note that in the flow this is actually the
last thing we do.
At (B) is a repeat-n set to evaluate everything above it 3 times. These three lists thus
created are our measures.
At (C) we construct the time signature as a list (4 8). It will be taken three times by repeat-n
as the first element of the measure.
At (D) another repeat-n producing
(1 1 1 1)
is paired with a list function to great a group
(4 (1 1 1 1))
. This group is passed to a further list function since it is the only group in the measure
(the measure in this case is a list of a single group). This yields
((4 (1 1 1 1)))
, which is put with the time signature to compose the measures.

Evaluate the output at each point in the chain to see how the measures are constructed.
Tutorial 25: Voice II
Topics
Generating more complicated rhythm trees.
Key Modules Used

Voice, list, x-append, omloop
The Concept:
In this example, we will generate rhythm trees using an abstraction (red patch) which we
will call ’Rtm constrct’. This patch will take three arguments, all of them lists. The first two
lists will define the time signature of each measure (the first being a list of numerators and
the second of denominators), and the third list will be the rhythmic structures contained in
these measures in the form of a list of lists.
The Patch:
Here’s the interior of the abstraction:
Inside this patch three omloops will construct the ’leaves’ of our rhythm tree.
The first omloop will produce time signature:
Each output will be enumerated using listloop (D). Each beat number will be appended
to a list with its corresponding beat duration using list (E). The results will be collected by
collect (F) and then passed to the output.
At (B), ’proprts’ will return measures. (This loop is the same as ’measure-sign’ loop, ex-
cept that it pairs the measure lengths (time signature numerators) with the lists of rhythmic
structure.
At (C), another omloop will take the elements of the lists produced by the other omloops
and pair them off to form the measures. Note that we must put each of the measure lists
into another set of parentheses with list because each measure must be a list of
groups and we only have one group per measure.
Outside of the omloops at (G) we add the obligatory question mark, which we append to
the list with x-append.
After connecting our abstraction to the second input of the Voice, we will obtain this rhythm:
Tutorial 26: Editing rhythm with the Voice graphic editor
Topics
In this tutorial we will use an excerpt from the Chorale Allein Gott in der Höh’ sei Ehr’ from
J.S. Bach’s German Organ Mass to learn how to enter rhythm when working in the Voice
editor, a new addition to OM 4.4, developed by Carlos Agon.
Key Modules Used

Voice
The Concept:
If you work in Finale®: While it is possible to edit musical objects in OM, if you are a Finale user,
it is often faster to use OM’s import and export capabilites to move objects back and forth between
OM and Finale, since Finale’s editing interface remains slightly more fluid. See the Function Ref-
erences on finale-export and finale-import.
The goal is to recreate the following 5 measures from the Chorala:
We will create both staves separately in two different Voice editors and then combine the
results into a Poly object. A Poly object is quite simply a stack of Voice objects. Its second
input takes a list of Voice objects, which can then be played and edited together.
The Patch:
First, let’s look at the Voice editor window:
As with all editors, there are a series of buttons which control which what level we’re editing
on:
• Note mode - used to edit individual notes of the sequence.
• Chord mode - used to edit the Chords of the sequence.
• Group mode - used to edit rhythmic groups within measures of the sequence.
• Measure mode - used to edit entire measures of the sequence.
• Voice mode - used edit the whole Voice at once.
• Poly mode - This button is only present in Poly editors, and allows you to simulta-
neously edit the stack of Voices all at once.
These editing levels respect the natural heirarchy of OM objects, following a pattern of
inheritance mentioned in the previous tutorials. When creating rhythms from scratch in OM,
its best to use a strategy which respects this heirarchy:
• First, change the time signature.
• Second, create new measures.
• Third, enter notes representing the basic rhythmic groups.

• Fourth, subdivide those notes as necessary
• Lastly, change pitches.
The time signature

In order to change the time signature we must select the measure mode as shown above.
When this is done, two fields are shown in the palette, the numerator and denominator of
the time signature:
You enter the time signature by clicking on the numbers and dragging up or down. Then
click set:
Adding new measures

Adding new items in general is done by holding option and clicking, and measures are
no exception. With the measure tool still selected, option-click four times to the right of the
existing measure to add new blank ones.
You may get a pop-up help screen at any time by hitting h:
This menu lists the available commands. Some have not yet been implemented. In ad-
dition, some of the commands are only applicable when you are in edit mode (rep-
resented by a green or red box cursor - more on this below). Eventually someone will
update this help screen.
Creating the basic rhythmic structure

Next, we create a basic rhythmic structure representing the note groupings of the measure,
which we will then subdivide to create the appropriate number and type of notes. For the
upper voice of the Chorale, the basic rhythmic structure will be:
...whose notes we will then subdivide to create the finished rhythmic structure:
In addition to the various editing modes chosen with the tool buttons of the palette, there
are two different cursor modes when editing. The default is the selection mode, which is
available in all the tools. When in selection mode, objects that you click on or drag to enclose
are highlighted in blue. The second mode is the edit mode, which is available only in the Note,
Chord, and Group tools. You enter edit mode by option-clicking on or in between notes. A
cursor appears, surrounded by a red box (if you are between notes, going to enter new ones)
or a green box (if you clicked on a note, you’re going to change the note)
When in the edit mode, the cursor keys move you to the next/previous object, (with a green
cursor) and the tab key moves you to the space between the current object and the next one
(with a red cursor).
Click the Chord tool and option-click before the first rest of the first measure. You enter edit
mode and the red cursor appears:
You’ll also notice three radio buttons appear on the palette. These buttons control the be-
havior of the measure when you enter new notes. They are, from top to bottom, Replace
Notes, Extend Measure, and Keep Proportional Lengths.
To demonstrate how these work, we’ll start with a hypothetical measure of 3/4 containing 3
quarter notes:
We will put the red cursor in front of the first note and type 6, which will normally inserts a
half-note.
In Replace Notes mode, the half note pushes the last two quarter notes out of the measure,
deleting them. The measure length stays the same and the half note is entered:
In extend measure mode, the half note is added and the time signature is adjusted in order
to accomodate the new note. The result is a bar of 5/4:
In Keep Proportional Lengths mode, no notes are deleted but the time signature does not
change either. The proportions of the notes are kept the same relative to each other but they
are adjusted as a group to fit in the measure. This usually results in the creation of a tuplet
of some kind:
For our purposes, we want the first mode, Replace Notes.

When in edit mode, the notes of the keypad correspond to durations. They will add notes if
you are between notes (red cursor) or change durations of notes if you are on a note (green
cursor). They work as follows:
First Measure
In edit mode, use 5 to enter a quarter note.
Hit tab (not the arrow keys) to move to the next insert point.
Insert a second quarter note.
Hit tab again to get to a new position
Insert a third quarter note.
Now, we need to change the first quarter note into a rest. Use ← to move the green cursor
back to it:
...then hit screen lock on the keypad. Powerbook users can use function-clear (function-6).
Second Measure
Move the cursor to the last note of measure 1 with →. Then hit tab to get it to the space
before the beginning of measure 2.
Using tab between notes again, enter a quarter note and three eighth notes using 5 4 4 4.
Our measure now looks like:
Use ← to move the cursor back to the first note. Hit . (period) to add a dot.
Subdividing the structure

Now we need to subdivide these notes into the groupings of the Chorale. Come out of
edit mode by clicking anywhere else in the window. Then click on the first eighth note. The
note turns blue (you are in selection mode) Hit 2. When you hit a number key in selection
mode, you subdivide the selected note(s) evenly. Hitting 2 on an eighth note changes it
into two sixteenths. Click on the next eighth, then shift-click on the last eighth. They are both
blue. Hit 3 to turn them both into triplet sixteenths.
The opposite of this operation is performed with +. Select the notes you want to "put back
together" and hit + to regroup them.
Ties are added in selection mode by hitting = with the two notes selected, or in edit mode
with the first note of the tie in the green cursor.
Entering pitches
Pitches are entered by dragging notes or groups of notes with the mouse or selecting them
and using the cursor keys. Holding shift while using the cursor keys moves them by octaves.
You can control how enharmonics are spelled in the Preferences pane:
Double-click the 1/2 button to bring up the enharmonic alterations editor:

This is where you choose how you want OM to display certain midic values. Select the A]
and type o. The scale editor window opens. Select the [ from the list. The A] becomes an
A[. Select it and hit the ↑ key so that it becomes a B[. After closing this panel don’t forget to
hit OK in the main Pane.
Now all A]s will be notated as B[s
Using the same procedure, enter the lower voice in the other Voice box. When you are
done, make sure they are both locked, and evaluate the Poly. You will create a two-voice
object containing both Voices.
Tutorial 27: Introduction to rhythm quantification
Topics
Converting lists of durations into traditional rhythmic notation; passing data between
Chord-seq nad Voice.

Key Modules Used

om-quantify, Voice, flat
The Concept:
The omquantify function converts a list of durations, in milliseconds, into a rhythm tree
(treating positive integers as durations and negative integers as rests). In this example we
will quantify a Chord-seq (A) from Tutorial 13 using two different settings. Remember that
Chord-seq does not recognize negative integers as rests; its ldur output is simply the
durations of the notes, without regard for where they fall. The omquantify function treates
the duration list as consecutive durations that are ’flush’ with each other. If ther are gaps in
the original Chord-seq, then, the transcription will not be accurate.
As described further down, there is another way to transmit data from a Chord-seq to a
Voice; this is to plug the self output of the Chord-seqinto the self input of the Voice. This
method has the advantage of preserving the real start times (onsets) of all notes regardless
of whether they are ’flush’ with their neighbors. However, each note is transcribed to last until
the onset of the next; i.e. the transcription will not have any rests.
The Patch:

In order to quantify from a Chord-seq, we will use the list of durations that we get evaluating
its fourth output, ldur. Each of these durations corresponds to a note in the Chord-seq. In
some cases there might be rests in the sequence. As mentioned above, using this method
(using only the ldur output of Chord-seq) we will get an inaccurate result. Therefore we
will check the Chord-seq (A) in its editor and select the dur item from the pop-up menu.
We verify that all notes fall one after another (are ’flush’ with each other) forming a monodic
sequence without rests:
We will then connect the fourth output ldur of the Chord-seq (A) to flat (B) in order to
get a simple list of durations.
flat (B) is connected to the first input of omquantify (C). At the second input we will enter
60 indicating a tempo for the transciption. The third input is for the time signature. The fourth
input is the maximum limit (exclusive) of for subdividing the pulse, in this case, by 8, or into
32nd notes.
As mentioned above, you can connect a Chord-seq directly to a Voice via the self input:

In this case, an omquantify is automatically performed on the material. The settings for
this automatic omquantify are in the Preferences Pane. Click the icon:
and then the quantify icon:

A preferences panel appears where you can edit the default settings:
If we connect our Chord-seq directly to the self input of the Voice:
We get the following transcription with the defaults:

In the bottom half of the patch window, we clean up the transcription by adjusting some
settings with the additional inputs (added with option-→) of omquantify:
You’ll often have to fool around with tempo and time signature settings before you get a
decent transcription out of omquantify. In the example above we have used the fifth and
the seventh optional inputs of omquantify. The fifth input, forbid is a list of forbidden
subdivisions of the pulse (here quintuplets, sextuplets and septuplets are forbidden). The

seventh input, precis, is a level of precision, which is a value between 0 and 1, inclusive. 1
is the highest level of precision, with accurate but complicated results. 0 is the least precise,
yielding simple but less accurate results. In our case, we changed the time signature to (4
8). We did this so that the unit of the pulse would be the 8th note and the smallest permitted
division (which is 8) is thus equal to a 64th note. If your settings don’t allow room for the
smallest note values of the original, omquantify may drop some notes, but it always lets
you know in the Listener:
? Warning: with the given constraints, 5 notes are lost while quantizing
Our new transcription is:

Chapter 9. Playing MIDI II
Tutorial 28: Working with MIDI files I
Topics
Converting a Midifile into a Chord-seq after transposing its notes.
Key Modules Used

mf-info, mat-trans, omloop, save-as-midi
The Concept:
Converting a Midifile into a Chord-seq can be done immediately by patching the self
output of the file into the self input of the Chord-seq. Indeed, the Chord-seq class will
inherit all its elements from the Midifile, which will be converted into appropriate data by
the internal of the Chord-seq . For instance, standard MIDI notes from the Midifile will be
multiplied by 100 in order to be handled correctly by a Chord-seq. However, if you want
to modify this data before transcription, you must use the mf-info function to analyze the
Midifile so that you can work with its elements. mf-info takes a Midifile and returns a
tree where each channel is a list of notes, and each note is itself a list of five values: midi
note number, onset, duration, velocity, and MIDI channel. You notice these are the same
quantities used by Chord-seq to keep track of its notes.
107
Ircam documentation
The Patch:
A MIDI file is dragged onto a patch. This will create a Midifile factory. Connect its output to
mf-info.
In order to work on a particular track, we must know the exact number of tracks in the MIDI
file. Since each track is a sublist of the master list, evaluating with length will return the
number of tracks (here 2). Opening the optional input of mf-info, we can choose to gather

data from a particular track (instead of the whole file. The first track is numbered zero.
The track is a list of lists, each containing the five parameters describing a note. We use
the mat-trans function to transform this list of lists such that the new lists are groupings of
the nth element of the old lists. See the Reference for more information. The result of this will
be a new list of lists, except that each list now represents a single parameter, with values for
all the notes of the file.
We separate these parameter lists with the LISP functions first, second, and so on. The
first sublist is a list of all the first elements of the old tree (i.e. all the MIDI note numbers.) In
order to convert MIDI notes to midicents, one must multiply them by 100 using om* at (E). We
transpose them up 200 midicents at (F), and pass the result along with the other parameter
lists to Chord-seq at (G)
We can write a loop that will do this for all the elements of a file:
with omloop structured as follows:

Inside omloop we have reproduced the main patch as it was shown earlier adding an itera-
tive procedure using the forloop (D) iterator. forloop controls the loop by using a variable
which is augmented by a certain amount at each repetition of the loop. forloop stops repe-
tition when this value equals a certain threshhold.
forloop is setup to run from zero to the number of tracks-1 (since the first track is called
zero). The iterator itself outputs the current value of the variable. It will thus output 0 on
the first repetition and 1 on the second and last. This value is used in mf-info to isolate a
particular track for the transposition process.

Tutorial 29: Working with MIDI files II
Topics
Converting a standard Midifile into a Chord-seq with correct microintervals.
Key Modules Used

Midifile, omloop, omif, repeat-n
The Concept:
Most commercial MIDI sequencers don’t support microintervals. When working with these
environnments, one must use a multichannel setup in order to simulate microintervals, by
"pitchbending" certain channels as is done automatically in Openmusic. In this tutorial we
will show how to convert one of these MIDI files into a Chord-seq which will play correct
microintervals.

The Patch:
In our example we have created a simple multitrack MIDIfile. It represents a chromatical

segment of a quarter-tone scale starting from C3. The first MIDI track is on channel 1 which
is the normally tuned track; The second is on the channel 2, which shouold be tuned 1
quartertone higher. We need to get these notes back onto a single channel and adjust their
midics to reflect the detuning of the other channels in the MIDI file.

At (A) the MIDIfile is opened (or dragged into an OpenMusic patch).
Each color represents a different MIDI channel. (Here blue is channel 1 and green is chan-
nel 2)
Now if we open the Chord-seq (B) editor and check the chan popup menu, we can see
each note’s channel.

In the first omloop (C) we will use omif to ’correct’ each note, and turn it into the right pitch,
by checking to see whether the channel equals 2. Note that we use two listloop boxes to
enumerate the MIDI notes and the channel assignments simultaneously.

In this case our line is of single notes. If there had been chords we would have needed to
process the onset times and assign the same onset time to every note of the chord. This is
done with the omloop below:

The ldur output is a list of lists. Each integer is a duration of a single note, so all we have
to do is flatten the list using flat.
All this results in the following:

Each note is correctly parsed to the right channel according to its tuning.


Tutorial 30: Working with lists I
Topics
Creating rhythm from arithmetic series and "filling" it with notes from a chord.
Key Modules Used

arithm-ser, group-list, flat, length, om-round, om-scale, omquantify
The Concept:
This example creates a list of notes (L) containing the same number of elements as a list
of durations (I) which are derived from an arithmetical series (A).
119
Ircam documentation
The Patch:
The arithm-ser box (A) creates an arithmetical series going from 10 to 200 by steps of
20.
The values you enter at (C) and (D) will correspond to the shortest and longest durations
in your rhythmic sequence (They are of course arbitrary numbers which will be scaled after-
wards).
Lets say that we want to build our rhythms with the sixteenth as the smallest unit. We’ll
generate a scaled series and multiply it by 250, which will be a sixteenth note at the quarter
note=60 tempo of the transcription. The module om-scale (E) scales the values coming out
of the arithm-ser box (A) so that the series runs between the values entered in inputs (C)
and (D). In order to round off the result we will use om-round. This way we are sure to have
integers going from 1 to 12. These integers are multiplied by 250 to yield a list of durations
which are passed to omquantify.

Our harmonic material is in the form of a chord:
Obviously we need to reuse notes if we want to create a list as long as the elements of
our rhythmic series. Here we use a trick to get a list of exactly the right length. The module
group-list puts the elements of a series into groups according to its second input. The
third input is a little pull-down menu where you an set the mode to linear or circular. In
linear mode, the function stops when it runs out of notes. However, if we set it to circular,
it will start again at the beginning of the list as many times as necessary. We give it the list
of midics at the first input. It expects a list of group lengths at the second input. We take the
length of the rhythmic series and make a list of one element out of it. In this way, group-list
will generate a list of exactly the right length to accompany our rhythm. We need to flatten
it before passing to the Voice.
Try changing the values of the original arithm-ser and evaluate the results.
Tutorial 31: Working with lists II
Topics
Using group-list to create chords based on a density contour.

Key Modules Used

BPF, bpf-sample, group-list, om-round, om-scale/sum
The Concept:
Here we use bpf-sample as we did in Tutorial 21 to transform a BPF into values. This
time, however, the values of the BPF will represent the density of chords, not the notes. We
use the group-list function, demonstrated in the previous tutorial, to break down a master
Chord object into a list of Chords following the density contour of the BPF.

The Patch:
Here’s a schematic of the patch:

The input (D) will decide how many child Chords we want to create. In the example, we take
7 samples of the BPF in the range of x-axis values between 10 and 100. We will ultimately
use group-list to split the master Chord apart. The problem is that the values of the
samples of the BPF total many more notes than are available in the Chord. We need to
scale this list of samples, but not as we’ve scaled things in the past, because it is not the
bounds of the series we are concerned with but the sum. We use a different function, om-
scale/sum, which adjusts the series of samples so that their sum is equal to the number of
elements in the master Chord.
The next problem is that group-list needs a list of whole numbers to determine how many
notes it will put in each group. We solve this by rounding the list off with om-round. The result
is that the master Chord is broken up into a series of elements with densities based on the
BPF, which you can verify by drawing a new figure in the BPF editor.

Chapter 11. The Maquette
Tutorial 32: Introduction to the Maquette I
Topics
The Maquette and Temporalbox objects. The difference between red and blue patches.
Key Modules Used

Maquette, Temporalbox, red and blue patches.
The Concept:
The Maquette is a special container object which incorporates a time element. A Ma-
quette can contain any musical object, but can also contain a special object called Tem-
poralbox. These boxes can contain other patches and Maquettes. A Maquette looks like
this:
You’ll notice the axes are numbered. The x-axis is a time dimension, labelled in seconds.
The y-axis is an arbitrary value which can be used to control the Temporalbox objects in
various ways. The other objects themselves, including the Temporalboxes are the colored
boxes in the field, which can be stretched and moved around at will in all directions. Playable
OM objects can be dropped directly into a Maquette, and are edited with their graphic editors
125
Ircam documentation
as usual. Temporal box objects are created when a patch is dropped into a Maquette. They
look like this when opened:
Looks like a patch, right? Except for the self object and the tempout object, of course.
The basic idea of a Maquette is this: objects in the Maquette are placed in time, along the
x-axis, and are played in that order. If they are a Temporalbox object, whatever is connected
to the tempout output is played when the play pointer crosses the left edge of the box in the
Maquette. Here’s the cool thing: a patch within a Temporalbox in a Maquette has access
to information about its placement and shape within the frame of the Maquette, and these
quantities can thus be used to change the way the patch behaves. This information comes
into the Temporalbox through the outputs of the self object. In addition, you can create
your own inputs and outputs between Temporalboxes which can carry other data between
them.
Consider the following Maquette, where two objects have been placed: a Chord, and a
Temporalbox containing a Chord.

The first is a Chord. The second is a Temporalbox, which has the same Chord on the
inside, attached to the tempout:
As they stand, both of these objects will behave the same way. Connecting the Chord
to tempout just means the Chord gets played. The advantage to having the chord in the
Temporalbox is that we can use the data about the box’s position and shape to modify the

Chord, for example, transposing it based on the height of the box in the frame.
OK, now lets see how this Maquette was created.
The Patch:
First, we create a Maquette by selecting File−→New−→New Maquette. Open it by double-
clicking its icon.
Now, we drop the patches for Tutorial 8 and Tutorial 12 into the framce. Notice that when
we drop patches, unlink musical objects, they are automatically put within a Temporalbox:
Now, we need to connect this patch to the tempout so that it will be evaluated. The problem
is that the patch has no outputs. The blue patch represents a reference to the master copy
of the patch in the Workspace. Changes to this patch are made directly to the master. We
don’t want to modify the original master of Tutorial 9, so we need to make a copy, to make
an abstraction this patch. We do this by selecting the patch and hitting a.
The patch is now abstracted. It is no longer connected with the master copy and exists as
its own separate entity. Now you can go in, add an output, and connect it to the self output
of the Chord.

Then close it and connect the output to tempout.

Do the same thing with the other patch in the other Temporalbox.
Now you can position both boxes within the frame of the Maquette. The mini-visualization
also functions here. Turn it on by selecting a Temporalbox and hitting m.

Once you’ve positioned them to your liking, you can play the Maquette buy clicking the play
button, but before you do, you must evaluate the entire Maquette object by clicking Eval.
Notice that each time you evaluate the Maquette the objects change because of the ran-
dom function in the second patch.
Tutorial 33: Introduction to the Maquette II
Topics
Passing data between Temporalbox objects in a Maquette.
Key Modules Used

Maquette, Temporalbox, om//, permut-random, x-diff, omloop
The Concept:
In this tutorial we will use two Temporalboxes, one representing a six-note series ran-

domly permuted at each evaluation, the other representing a Chord. This Chord will be the
chromatic complement of our series, and will be put into a random register at each evalua-
tion.
We can see that one Temporalbox depends on another here. In order to accomplish this,
we’ll need to pass data about the series from the one to the other in order that the comple-
ment can be constructed.
The Patch:
Let’s look inside the first Temporalbox:

The Chord at (A) represents our series, entered in the usual way in order mode:

Note that the order of the series here is not important due to the fact that we will randomly
permute it.
In order to get the chromatic complement of our Chord (A), we build a chromatic scale that
from which the notes of (A) will be subtracted. In (B) we have constructed the total chromatic
scale using arithm-ser (C) which outputs the list (0 1 2 3 4 5 6 8 9 10 11), which is multiplied
by 100 to get midics. These intervals will all be added to 6000 (middle C), returning (6000
6100 6200 etc... ) at (E).
The problem now is that our scale (B) going from 6000 to 7100 midics covers only one
octave. The C is represented only by the midic 6000. If we compare it to a C in any other
octave, our patch will fail to recognize it as the same note in a different register because they
have different midics.
To get around this, we use om//, which performs euclidian division (i.e. division with re-
mainder) a number or list. The quotient is returned at the first input and the remainder at the
second. We will divide everything by the octave in midics, 1200. In other words, we will use
a modulo 1200 on our scale by taking only the remainder of the note when divided by 1200.
All Cs are multiples of 1200. They will divide with a remainder of 0. All Ds are 200 midics
above a multiple of 1200 and will divide with a remainder of 200. In this way we reduce both
our chromatic scale and the series to raw pitch class. (F)
The outputs of the two om// boxes will be compared by the x-diff funtion which returns

the list of elements present in the first input but not in the second, therefore returning the
notes of the chromatic scale not found in our series, i.e. the complement. This result will go
out through an output added especially for this purpose at (J).
What actually gets played is a Chord-seq generated from our series with the permut-
random function at (H). It is passed to tempout so that it will play.
In the second Temporalbox, we will add a random multiple of 1200 to all the pitches
retrieved from the first box via an input specially added:
...and the interior of the omloop:

...is pretty straightforward. The notes of the complementary chord are enumerated one by
one by listloop. Each time, om-random generates a number between 3 and 7 which is
multiplied by 1200 and added to the pitch, putting it in effect in a random octave. The results
are collected by collect and output by finally.
The output of the loop needs to be put into a playable musical object and connected to the
tempout. We chose a Chord, so they’ll be played simultaneously, but you can (and should)
replace them with Chord-seq objects.
Remember to click Eval before playing the Maquette. Remember also that you can copy
boxes by option-dragging them. In this way you can fill the Maquette with random notes and
chords:


Chapter 12. Lambda Functions
Tutorial 34: Introduction to Lambda Functions
Topics
The lambda mode for function boxes.
Key Modules Used

mapcar, om-random, repeat-n, arithm-ser, dx->x
The Concept:
Patches and functions in OM have different states. We have already seen two of them (the
’lock’ state in Tutorial_1 and the ’eval once’ state in Tutorial 12 There are two others; here
we introduce the lambda state (λ). Any OM patch or function can be put in lambda mode.
This state is used whenever a function calls another function as an argument, in order to
apply this second function to some data. These are generally standard LISP functions such
as funcall or mapcar. In this tutorial we’ll look at two instances of their use.
To put a patch in lambda state, bring up the ’lock’ mark (an X) by selecting it and hitting b.
Then click the X representing the lock twice. The X becomes a 1 and then a letter lambda,
λ:
Now let’s look at our examples.
137
Ircam documentation
The Patch:
The first example
The mapcar function takes as a first argument another function and applies that function it to
its other arguments. This called function at the first argument can have any number of inputs.
Since mapcar passes the elements of its inputs as arguments to this called function, mapcar
must have as many additional inputs as there are arguments of the called function. These
inputs must themselves take lists. mapcar takes one element from each list and passes the
group to the elements of the called function. It does this with each successive element of all
the lists until the shortest list is exhausted, collecting the results in a list.
You’ll notice that we’ve typed the function name, list, into the box given as first input to
mapcar. This works only for LISP functions (functions whose icons are the word LISP). This
is a shortcut; we could have added a list box, put it in lambda mode, and attached it.
In this patch we will construct a chromatic scale from C3 to G3 and add a C pedal to it as
shown below:

In terms of the patch, this pedal is added by putting each midic of the scale into a list with
the midic 6000 with the list function. It would be tedious to perform the list function 7
times. It would be more work to write an omloop to do this. mapcar does it all in one step.
We give it a list of chromatic midics and list of 6000s of the same length and tell it to apply
the list function to the pairs.
We use an arithm-ser to create the scale and repeat-n to create the list of 6000s. The
results of the mapcar function are:
? OM->((6000 6100) (6000 6200) (6000 6300) (6000 6400) (6000 6500) (6000
6600) (6000 6700))

The Second Example
Here we use the output of an abstraction of the patch from Tutorial 30 and modify it. We will
add some ’noise’ to the onsets of the notes, in the form of a small random quantity added
to or subtracted from each duration, and turned into a new onset. Again, this could be done

with omloop. It’s faster, however, to do it with mapcar. In this case, we want to add a random
value to each element of the ldur output of the Chord-seq.
So, we write a patch that will do this to a single number, and then send the patch in lambda
mode to mapcar, secure in the knowledge that mapcar will apply it once to each element of
the list at its other input(s). In this case we only need one input since we are modifying the
elements of just one list.
In Tutorial 30, an arithmetic series was turned into a list of durations. This series is graphed
here using a BPF:
Notice the more or less linear movement upward. (The roughness is a result of the small
number of data points.) What if we messed around with the values just a little bit in a random
way, generating a shape that, while still moving up, is les linear:

We drag the patch Tutorial_30 into a new patch and make an abstraction of it with a so
that we don’t screw up the original patch. We open it and add an output, connecting it to the
self output of the Voice factory.
In order to access durations from a Voice object one must use a Chord-seq. Therefore,
we will connect the output of the Tutorial_30 patch to the first input of a Chord-seq (B).
We build a red patch which takes an integer and adds a random value between -200 and
300:

We need to convert these durations into onsets with dx->x, but dx->x only takes flat lists
as input. So we use flat to make it acceptable to dx->x and pass it to the lonset input of
the Chord-seq, using the legato argument to make sure things sound goooood.
Evaluating this patch varies the onsets of the notes in a small random way each time. Try
evaluating it several times, listening to the results.
Tutorial 35: funcall with Lambda Functions
Topics
Calling a random function using funcall.

Key Modules Used

funcall, omif, om-random, omloop
The Concept:
funcall is like a single-shot version of mapcar; it takes the lambda function at its first
input and passes it whatever comes in at the other inputs. Like mapcar, it usually should
have as many optional inputs as the lambda function it is calling. funcall allows you to
call a function as you would evaluate any other data. Here, we use an omif function with a
random outcome (thanks to om-random and the predicate om=) to send oneo of two lambda
functions to funcall. Whichever one we choose, funcall will apply it to the Chord at (G).
The Patch:
So, starting with Chord (G), we will perform one of two procedures on it. Either we will use it
as a reservoir to construct a random sequence of notes as in Tutorial 14 or the interpolation

procedure of Tutorial 18, which will interpolate a series of notes between this Chord and
another.
Let’s look at the loop at (D).
Inside is an abstraction of the patch from Tutorial 14, with an input and an output added:

The result will be that the Tutorial 14 process is carried out for each note of the chord.
The other possible function is an abstraction of the patch from Tutorial 18:

...modified to accept two Chords as input and perform the interpolation process on them
as outlined in Tutorial 18.
Note: Note that the second Chord for the interpolation is coming in from outside the patch. This
demonstrates that the functions in lambda mode can still take data at their inputs, provided that
the inputs are not going to be acted upon by the funcall or whatever is calling them. Remember
how we said that funcall usually has to have as many optional inputs as the function it is calling?
Well, here is the exception. Our funcall here has one optional input. (In addition to the mandatory
first input.) The abstraction has two inputs! But funcall will only pass data to the first one since
it was only given one argument at its additional inputs. The leaves the second argument of the
abstration free; in fact, we must pass something to it in order for it to function correctly in lambda
mode. Try disconnecting the second input and see the error.


Chapter 13. Flow Control III: More Loops!
Tutorial 36: Accumulation
Topics
Using acum in the omloop module.
Key Modules Used

omloop
The Concept:
In this tutorial, we will examine a simple accumulative computation., that of the factorial.
The factorial operation is equivalent to taking the product of an arithmetic series of integers
ending at a given number. If is indicated with an exclamation point. The factorial operation
on a number is:
5! (5 factorial) = 1*2*3*4*5 = 120
In order to multiply the elements of the arithmetic series one after the other, we need to
hold the result of each multiplication somewhere until we can use it in the next one. This
is accomplished with acum, which acts like a warehouse where you can store a variable
between iterations of a loop.
The Patch:
We’ll do two variants on the factorial procedure. In the first, we’ll just go for the final result.
In the second, we’ll program omloop to return a list with the products of the intermediary
operations.
The first loop looks like this:
149
Ircam documentation
The acum collector takes three arguments. The second input (B) is an initializer, which sets
the internal state of the accumulator before the first repetition of the loop. The third input (C)
is a lambda function (with two inputs) to which will be passed 1) whatever is coming into the
first input (A) and 2) the internal state of the accumulator. In our case we’ll use om* since
we’re interested in the product. The result becomes the internal state of the accumulator for
the next pass. The three outputs on the bottom work just like the other collectors.
The state of the loop through its repetitions is summarized:
Step Listloop Value of the Value of the Internal Binary

output first input of second state function om*
accumulator input of (buffer) output
accumulator
0 1 1 1 1 1
1 2 2 / 1 2
2 3 3 / 2 6
3 4 4 / 6 24
4 5 5 / 24 120
120

The final state of the accumulator is available at the second output and passed to finally.
As configured, the loop will output the final factorial when evaluated:
? OM->120
If we want to see the intermediary steps, we need to record the internal state of the ac-
cumulator at each repetition of the loop. This is done by adding a collect function and
connecting it to the first input of the accumulator, which returns the current internal state
each time, which is recorded in a list by collect.
The result:
? OM->(1 2 6 64 120)

Tutorial 37: Accumulation with musical objects
Topics
Given a starting note and a melodic sequence, construct a random sequence of notes
with the same intervals as the melodic sequence but random directions of motion. Use of a
lambda patch within omloop with acum.
Key Modules Used

omloop, Note, Chord-seq, x->dx, om-random, om=, omif
The Concept:
Given a sequence of intervals (B) we will construct a musical sequence starting from a
given note (A). The intervals will be ordered as defined but their direction (up or down) will
be random (i.e ascending or descending depending on om-random’s output). In order to do
so we will use an accumulative proceedure using omloop’s acum collector.
We will also demonstrate the sequence function by simultaneously visualizing our new
melodic figure using a BPF factory.

The Patch:
The transformation of the sequence into a new one will be done in omloop (C). This trans-
formation is a transformation of pitch only, so omloop (C) is connected to the second input
of Chord-seq (O). To get the rhythmic data we take the ldur and lonset outputs of the
Chord-seq (B) and copy them directly.
omloop as shown above is in ’eval-once’ mode. This is because omloop is connected to
two objects but contains a random function. We want to make sure the same information is
given to both the Chord-seq and the BPF, which will not happen unless we ’freeze’ it after
one evaluation.
Now let’s look inside omloop.

First of all we must convert the list of midics we will be receiving through the intervals
input into a list of relative intervals. This is done, as usual, using x->dx. We must first use
flat since the lmidic output of the Chord-seq is a listand x->dx needs a flat list.
Each interval of the Chord-seq will thus be enumerated individually and passed to our
lambda patch (G) along with the results of the previous calculation.
Here’s the lambda patch:

The lambda patch (G) will take the initial note (H) and will add to it the first interval (I). This
interval will have been first multiplied either by 1 (which will leave it as is) or by -1 (which will
invert the interval.)
In order to randomly invert the intervals we have used om-random. As we know, om-random
returns random numbers between limits set at its inputs. In our case we had to use a different
strategy because we are only interested in having -1 and 1. Simply using om-random could
have returned some zeroes. This is where omif comes in handy. We used om-random with
0 and 1 as arguments and connected it to the predicate om=in order to transform each zero
into a -1. If om-random returns a zero, om= will return t and omif, in turn, will return -1. If not,
1 is returned.
Once we have added our first interval (using om+) to the initial note, the result will be a new
note which will take the place of the old as the internal state of our acum collector. In order
to record each note we use collect, connected to the first output of acum, as we did in the

previous tutorial.
Lastly, in order to have both factories (the BPF and the Chord-seq) evaluated in a single
evaluation we will use sequence. sequence evaluates all its arguments sequentially, but you
will only see one in the Listener. For instance, if we evaluate the first output of sequence
we will obtain the BPF object in the listener. Evaluating the second output will return the
Chord-seq object. Both will be evaluated in the patch window, however.

Chapter 14. Flow Control IV: Recursive
Functions
Tutorial 38: Recursive patch I
Topics
Introduces the concept of
Key Modules Used

omif, omloop, om=, om-
The Concept:
As we have seen, OM patches can contain calls to functions, factories, etc., nested to
any level we like. It is even possible to put a call to itself within a function! A function which
contains itself (created by dragging the patch from the Workspace into the patch window
itself) is called a recursive function. Recursion is actually extremely useful and a powerful
part of
Some computations require recursive functions, while others benefit from the clarity or
speed of recursion, though they may be possible other ways. For example, the factorial
procedure performed in Tutorial 36 can be performed more elegantly (and more quickly, it
turns out) using a recursive function.
The scheme of the recursive function for finding 5! (5 factorial, that is the product 1*2*3*4*5)
for example, can be summarized:
• First, we reverse our list: 5*4*3*2*1

• 4 can be represented as (5-1). This means we start by mutiplying 5*(5-1).
• 3 can be represented as ((5-1) -1 ). So we multiply 5*(5-1)*((5-1) -1)Get the idea?.
• The next level of recursion would be (((5-1) -1 ) -1), and so on, until we reach 1.
We can imagine a function that multiplies 5 by a value taken from its last repetition and
passes that to itself along with the value to multiply by (minus one). And here we run into a
problem- since recursive functions call themselves, they must have a built in ’brake’ in the
form of a termination test. Only if the termination test fails should they call themselves. With-
out a termination test, the function continues to call itself on into infinity, eventually saturating
the available memory and causing an error:
> Error: Stack overflow on control stack.

> To globally increase stack space,
> increase *minimum-stack-overflow-size*
> While executing: "Unknown"
> Type Command-/ to continue, Command-. to abort.
> If continued: Continue with a larger stack
See the Restarts menu item for further choices.
157
Ircam documentation
Chapter 14. Flow Control IV: Recursive Functions
Let’s look at a recursive patch in OM which will calculate the factorial of whatever number
we give it:
The Patch:
On the first repetition, n is equal to 5 (in our example.) If n is not equal to zero, which it is
not, om* is called to multiply n and the result of the recursion into the patch factorial. The
trick is that we subtract 1 from n before passing it to factorial. Before om* can complete, it
must evaluate factorial. So factorial is evaluated using 4 for n. This recursion continues,
going one level deeper each time (like Russian dolls), until finally, n is zero. At this point,
omif (the termination test at B) will return 1 instead of evaluating factorial. 1 is passed to

the output, which (remember the Russian dolls?) is going to be coming into the om* function
in the level of recursion just above. In that level, n was equal to 1. 1 times 1 is 1, which is
passed to the output, which is itself the second input to om* on the next level. n is 2 on this
level, and 2 times 1 is 2. Two is passed up out of that recursion to the next level where n is
3. The product, 6, is passed, and we continue to work back up, layer by layer, until we reach
the top, where the product of 1*2*3*4*5, 120, is passed to the output.
To see this patch in action, drag it into any other patch.
Evaluate it with different numbers. Notice how it takes a longer time for big numbers (since
more levels of recursion are being created).
Tutorial 39: Recursive patch II
Topics
Using a recursive patch to reverse the output of a rhythm tree.
Key Modules Used

omif, Voice, standard LISP functions
The Concept:
As we saw in Tutorial 24, traditional rhythmic notation in the Voice object is formalized in
what’s called a rhythm tree. The rhythm tree is a series of lists in the form (D S) where D is

the duration and S is the structure of that duration, and S may contain additional lists in the
form (D S). Notice that this form is itself recursive, containing the same element on many
different structural levels. Taking a retrograde of such a structure is not equivalent to taking
the retrograde of the rhythm it represents.
Consider this rhythm:
represented by the rhythm tree:
(? (((4 4) (1 (1 (1 -2 1 1)) 1 1)) ((4 8) (3 -1))))
If we go through the list from beginning to end we will notice that in order to obtain a correct
retrograge rhythm some expressions must be reversed and others not. For example, the
first element ’?’ must always figure in the beginning of the list and therefore must be left as
is. Measure signatures must also figure in the beginning of each measure-list. In general,
all elements in ’D’ position of a rhythm tree must be left alone. Only ’S’ elements must be
reversed, such as the (1 -2 1 1), it being a low level rhtyhm structure representing a quintolet.
The correct retrograde form is thus:
(? (((4 8) (-1 3)) ((4 4) (1 1 (1 (1 1 -2 1)) 1))))
Representing the notation:
Notice that this is not what we get by putting the original tree through the LISP function
reverse.
A rhythm tree can have unlimited levels of nesting. In addition, not all measures need have
the same number of levels, so a simple omloop won’t do the trick. We must create a recursive
function which calls itself as many times as necessary to descend the levels of recursion in
the rhythm tree. For each element (D S), we will reverse S but leave D untouched.

The Patch:
Here it is. The actual reversal of elements is accomplished by (E) and (G), which split the
(D S) structure into its first and second elements and reverse the second.
The termination test is performed by omif using a special LISP , atom, which returns t only
if its input is not a list. Recursion will thus stop when we reach the "bottom" of the rhythm
tree.
mapcar is used to call the recursive part of the patch. mapcar takes our treereverse and
applies it to all sublists of the ’S’ portion of the current level of the tree.
Once the termination test is satisfied and we begin to work back out of the levels of re-
cursion, the reversed portions of the lists (the ’S’ portion’) representing the distribution of
rhythmic values will be put back together with the ’D’ portions (the time signatures, which we
didn’t touch) with the list function.
The result is the correct retrograde of the rhythm. To further prove our point about the
necessity of the recursive function, let’s look at the incorrect results of a simple non-recursive
function which splits the D and S elements apart and reverses the S elements.

This patch has two problems. The first is that it only reverses elements down to two levels
of rhythm-tree sublists. If we had smaller rhythmic values as groups within beats of the
measures, they would not have been reversed.We don’t so this is not a problem. The second
problem, and this one shows up, is that the order of time signatures is not reversed. See for
yourself:



Chapter 15. The Maquette II
Tutorial 40: More Advanced Maquettes and MIDI
Topics
Loading a Maquette with objects via its icon; saving Maquette output as a MIDI file.
Key Modules Used

Maquette, Voice, Chord-seq, list, save-as-midi
The Concept:
The Maquette is the ideal object for arranging musical events and processes in time. Here
we will examine a simple way of placing a range of objects such as other Maquettes, Chord-
seqs and Voice objects in Maquettes. After that, we will save our musical sketch in the form
of a Midifile.
First, we create a new patch and a new Maquette:
Now we open the patch window and drag the Maquette into it. Whenever you drag a
Maquette from the Workspace into a patch window, the following icon appears to represent
it:

As is the case with patches, this icon is a reference to the original; any changes we make
to it will be made directly to the original object. If we don’t want to change the original, we
must abstract it in the same way as we do a patch, by selecting it and hitting a.
The first input is a list of onset times, in milliseconds. The onset times correspond to the
elements of a list passed to the second input. (They have the same number of elements.)
The elements of this list can be any playable object or another Maquette or patch (provided
that you’ve configured these patches to play in a Maquette - see Tutorial 32). These objects
are placed within the Maquette at the onset times specified at the first input.
In this patch we will take a series of objects created in previous tutorials and combine them
in a Maquette. The first of these is a Voice object, at (A). We will use the rhythm of this
Voice to trigger the entrances of the other objects in the Maquette.
The Patch:
At (A) we will create a Voice facrtory and edit both the rhythm tree and the notes. We will
use this Voice as a type of "cantus firmus" for our musical sequence, meaning that the other
events (objects) that we place inside our Maquette will be syncronized, entering with the
notes of the Voice.

We have decided to put seven events in the Maquette , including Voice (A) which will be
the starting event. The rhythm tree (B)
(? (((4 4) (1 (2 ((2 (1.0 4)) 1)) 1.0)) ((4 4) ((2 (-3 2)) (1 (2.0 2 1)) (1 (1.0 6))))))
...will therefore have seven attacks.

The notes of this cantus firmus Voice are taken from a Chord-seq connected to the third
input, chords of the Voice factory.
The combination of the two yields:
At (J) we use list to collect the seven objects that will be placed in the Maquette.
The first object is our cantus firmus Voice.
Objects (D), (F), and (G) are different random results of the patch demonstrated in Tutorial
12.
The Maquette at (E) is an abstraction (remember, we have to do this to preserve the
original object) of the Maquette built in Tutorial 33. Remember how we ahave to evaluate
a Maquette before playing it? Well, the same holds true for sub-patches and abstractions
of Maquettes. You must open the abstraction and evaluate it before playing the master
Maquette.
(H) is an interpolation between two chords, as computed in Tutorial 18.
(I) is an abstraction of the patch from Tutorial 13, modified so that the Chord-seq it gener-
ates is connected to an output (necessary so it can play through the Maquette.):

The onsets
In order to get our onsets in the form of a list in milliseconds, we will have to connect our
Voice object to a Chord-seq (K). Via their respective self inputs and output. This is an
efficient way to transcribing traditional rhythmic notation into simple numerical data. (This is
done through . The Chord-seq will inherit data from the Voice object using appropriate ).
At the first input of the Maquette (L) we connect a the list of onsets coming from the Chord-
seq (K) . These onsets are the ’temporal coordinates’ of each object of our list (J), which is
connected to the second input of the Maquette (L).
Evaluating Maquettes
It’s important to remember that evaluating a Maquette’s icon is not the same as entering
the Maquette itself and clicking the Eval button on the palette. The Eval button only causes

items already within the Maquette to be evaluated. Connections made to the Maquette’s
inputs in the patch window are not evaluated. In building this tutorial from scratch, for ex-
ample, you must evaluate the Maquette icon in order to add the objects, then click the Eval
button within the Maquette in order to evaluate the individual objects.
When we evaluate the Maquette, the objects are placed within it at the onsets given at
the first input. They are arranged in a rising vertical order automatically for ease of viewing.
Selecting them and turning on the mini-view with m gives something like this:
Contextual Menus in Maquettes: If you changed the MIDI port settings for any of your objects,
you may have to set the general Maquette MIDI output port withing the Maquette itself so that
they all play back automatically.. This is done in a contextual menu brought up by ctrl-clicking in
the Maquette window. This can also be accomplished with the right mouse button of a two-button
mouse, if you have one installed. The contextual menu choice Midi Ports brings up a mini-dialog
where you can change the master input and output ports for your Maquette.
Lastly, the real-time output of any Maquette can be directly connected to the input of the
save-as-midi function. Evaluating this brings up a dialog box where you can choose where
to save a MIDI file of the output. That file can then be transferred to other programs, or

reopened in OM by using a Midifile object. The output from this Maquette might look like
this (it will change because of the random elements):
Tutorial 41
This tutorial has not been written as of printing. We expect to add it shortly.

Chapter 16. Classes and Inheritance
Tutorial 42: Creating a Generic Function I
Topics
Creating your own generic functions in OM
Key Modules Used

The LISP function +, omloop
The Concept:
Here you will learn how to create your own generic functions. What is a generic function?
There are many different data types in the OM environment. As you have seen, certain
functions in OM can respond to more than one data type. Take om+, for example. When you
give it a number and a list, it adds the number to all the elements of the list. However, you
can also give it two numbers, in which case it simply adds them. How does it know what to
do?
It turns out that within the function om+ are a series of sub-functions called . A method is
a set of instructions for processig a specific combination of data types in a function. When
you use om+ with a list and a number, om+ automatically calls a method for adding a list and
a number. You can see the methods of a function by opening its box with a double-click. If
the function cannot find a method appropriate to the data types you are trying to give it, it
generates an error.
A function composed of methods for different data types is called a generic function. All
OM functions are generic functions. The advantage of working with generic functions is
that operations which are conceptually similar but apply to widely differing data types can be
organized into a single function with a single name, which is much more logical for humans.
You can write your own generic functions in OM. We will create a single function called
myplus and then add methods to it so that it can deal with a variety of different data types,
in the same way as om+.
Creating the Function

In order to create a generic function, one must first open a patch. Then, in the patch
window, select File−→New Generic Function.
171
Ircam documentation
A dialog box opens:
Give your function the name myplus, and add a remark about what it does. This documen-
tation will be used in the pop-up bubble help you get with command-click. To change the
icon, click on it. This window will appear:
Icons on the right are standard OM icons. Icons on the left are user-customizable icons.
You may customize the icons using a resource editor such as ResEdit and adding these
icons to the file WSPL.rsrc file in the current workspace folder.

Be careful editing these resources. Always work with a copy!

After editing the name and icon and hitting OK, the function’s editing window will appear:
This looks and acts a lot like a normal patch window. We can add inputs and outputs and
combine other functions and patches in any way we like. The difference is that we must ’type’
our inputs. When you add inputs to a patch, they are a universal type (in fact, they are the
LISP type t) which can apply to any data type. Click the button to add an input. A type of
input you’ve not seen before appears:

Remember how we said function inputs have data types? Well, this input is of type t. For
know, you should know that t (its our old friend, the truth value used in LISP ) is effectively a
universal data type. Any type of input can pass through a t input. For this reason, a method
for type t will always be called if a more appropriate one cannot be found. You could leave it
like this, but that would defeat the purpose of creating methods for different data types. We
want to create a different type of method, however.
Let’s start by defining a method for adding two integers. We need two inputs, if you haven’t
already added them.
In order to type our inputs, we drag an icon representing the data type we want to handle
onto the input. These are all found in the Packages folder. We find all our functions and
classes in this folder. In fact, any class is a data type when used as a function input. integer
is a class (data type) that is part of the LISP kernel of OM. Go into the Packages folder and
open the kernel:lisp package:

We see a list of all the basic LISP classes (data types). Drag the icon for integer to the two
input icons in your patch window. The icons change to represent the new typing. Now add
the function + by command-clicking in the window and typing +. Connect the two inputs and
add an output:

Close the window. Our function is now in the Functions menu:
This function adds two integers, just like the LISP function +. It is equivalent to the LISP
expression (+ 5 3).

myplus doesn’t know how to deal with lists, however. Let’s add a method allowing myplus
to handle an integer as its first argument and a list as its second.
Once you’ve used myplus in a patch window, double click it to open its methods window:
Notice that our first method has icons representing the data types it accepts. While in this
window we add a new method with File−→New Method:
A new editing window will appear with some extra radio buttons in its upper part. Don’t
worry about them for now. Here we edit a second method for our function. Notice that the
two inputs are already present. Methods ALWAYS have the same number of inputs, so they
are added automatically, and cannot be removed.

Drag two classes from the LISP package, but this time make them one integer and one list:
Create an omloop and configure it:

Close the patch window. You now see another method in the window with the appropriate
data type icons.
Add another method, this time with the data types list and integer. It’s just like the one we
just added, except that you have to reverse the inputs.
Add a third method for two lists. The omloop function will look like this:

We now have 4 methods in our myplus function:
We can now accomplish all four types of addition, as presented in the Tutorial patch:

User-created generic function definitions are stored in the Workspace folder, in the sub-
folder user:
If you want to use them in other workspaces, you must copy them to the user folder in the
other Workspace folder.
Tutorial 43: Creating a Generic Function II
Topics
Using musical classes as data types for

Key Modules Used

x-append, sort., remove-dup, Note, Chord
The Concept:
As we saw in the previous tutorial, a function may contain any number of determining its
behavior. Each method corresponds to a set of data types at the function’s inputs, and is
automatically called when these data types are present. Any class can be used as a data
type, it turns out. In this tutorial we will add functionality to our myplus function, defined in
the previous tutorial, allowing it to ’add’ Chords and Notes by adding additional methods.
Adding New Methods

We will define the addition operation for the NOTE class as adding two notes to produce
a diad. Two notes will form an interval. In order to do this we will again use classes from
the Packages folder in the Workspace. This time, however, we will open the Music:Score
package:
Open up myplus and select File−→New Method. The usual method editor window comes
up. This time, drag the Note class icon twice from the Packages folder. Notice these inputs
have many outputs:

Each of these outputs refers to a of the class. They give us access not only to the self
output of the Note, but to its constituent slots midic, vel, dur, and chan.
If we open the Note class in the Packages folder, we see these slots:
Notice that the self slot is not shown- this is because it is always present most classes.
(The Note icon could be taken to represent the self slot, in fact. You also see extra slots
that don’t appear in the graphic representation of the class when the class is used in the
patch: tie and symb-info. These slots are used when the Note becomes part of a larger
object; we won’t need to manipulate them directly.
So, in order to combine the pitches of the two notes, we will create a list with x-append. We
could simply pass this list to the output, but it would make more sense for myplus to return a
musical object in this case, so we give the values to the midic input of a Chord object, and

pass the entire object to the output (via the self output).
We may use our newly edited function:

Using two Notes, we connect them to myplus and get back a Chord:
Now let’s create a method for two Chord objects. This method will combine them into a
single object, without any repretition of pitches, and will sort all notes from lowest to highest.
First, we create the new method and drag the Chord classes from the Packages folder to
the inputs. We connect the lmidic output of both to the x-append function, which combines
the midics into a single list. Then we connect that to sort. (note the period at the end of
the name) which will arrange them, by default, in ascending order. Next, they are passed to
remove-dup, which, by default, removes duplicate elements from the list. Now we’re ready
to put our filtered, sorted list of midics into the lmidic input of a Chord object, and on to
the output.

We can now use the new method: A Chord

and second Chord:
...are connected to myplus and the output passed to a third Chord object:

The resulting chord, viewed in order mode:

Tutorial 44
Tutorial 45


Open Music Tutorial

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Open Music Tutorial

Uploaded by

Copyright:

Available Formats

OpenMusic Tutorial

Edited by Karim Haddad

Published Date: 2003/11/05 13:10:44

Copyright © 2003 by IRCAM. All rights reserved.

Marketing and Communication Dept.,

Send comments or suggestions to the editor:

For more information:

Key Modules Used ....................................................................................29

Ircam documentation vii

Subdividing the structure ..................................................................99

viii Ircam documentation

Tutorial 1: Transposing pitches

Key Modules Used

Now you should see quarter tones.

Tutorial 2: Inverting an interval

Key Modules Used

With these values,

Tutorial 3: Building a scale

Key Modules Used

Tutorial 4: Inverting an interval II

Key Modules Used

Key Modules Used

Tutorial 6: Four basic operations on a 12-tone row

Key Modules Used

The retrograde is accomplished by the reverse function. Evalute Chord (E):

Tutorial 7: Changing melodic contour

Key Modules Used

Tutorial 8: Construction of a harmonic series

Key Modules Used

The abstraction apppears.

Tutorial 9: Dealing with data types

Key Modules Used

object. The note appears in the Chord. What gives?

Tutorial 10: Playing MIDI

Key Modules Used

Changing MIDI instruments

Playing microtones using MIDI

of 25, representing eighth-tones.

Sharp by Sent on MIDI channel

• 0 to channel 1 which stands for no pitch bend

Tutorial 11: Constructing a Chord with random notes from a

Key Modules Used

Tutorial 12: Building a sequence of random notes: om-random

Key Modules Used

times because its output is connected to three other inputs.

Tutorial 13: Another random sequence

Key Modules Used

Tutorial 14: Random construction of a sequence

Key Modules Used

At (A), we will use om-random as a ’coin toss’ generating 0 or 1.

Tutorial 15: Introduction to omloop I

Key Modules Used

Tutorial 16: Introduction to omloop II

Key Modules Used

Tutorial 17: Generation of a melodic sequence from harmonic

Key Modules Used

Tutorial 18: Generation of a note sequence by interpolation

Key Modules Used

Tutorial 19: Using BPFs I; Graphic representation of a series of

Key Modules Used

Tutorial 20: Using BPFs II: Sampling a sequence of notes

Key Modules Used

Tutorial 21: Using BPFs III: Scaling a melodic contour

Key Modules Used