You are on page 1of 202

OpenMusic Tutorial

by Carlos AGON, Grard 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 Grard Assayag and Carlos Agon. Patchwork was conceived and programmed by Mikael Laurson, Camilo Rueda, Jacques Duthen, Grard 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

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 quantication .............................................101 Topics ......................................................................................................101 Key Modules Used ..................................................................................101 The Concept:...........................................................................................102 The Patch: ...............................................................................................102 9. Playing MIDI II ......................................................................................................107 Tutorial 28: Working with MIDI les I................................................................107 Topics ......................................................................................................107 Key Modules Used ..................................................................................107 The Concept:...........................................................................................107 The Patch: ...............................................................................................107 Tutorial 29: Working with MIDI les 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 rst 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

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. Well 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.

Ircam documentation

Chapter 1. Using Musical Objects I

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 rst 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. Minivisualization 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:

Ircam documentation

Chapter 1. Using Musical Objects I

The chord changes to display its notes in the order they were entered (which is not necessarily an ascending arpeggio, although this happens to be the case here:

Ircam documentation

Chapter 1. Using Musical Objects I

To add notes in the Chord editor, hold option and click where youd 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:

Ircam documentation

Chapter 1. Using Musical Objects I

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 wont see the transposed notes. Now evalute the patch by clicking once on the lower Chord object and hitting v. Youll 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 conrm this, set the input of om+ to 50, which will transpose the notes up by a quarter tone. Evaluate the lower Chord box. You wont see and quarter tones. In order to turn on quarter-tone visualization, use the pull-down menu in the Chord editor:

Ircam documentation

Chapter 1. Using Musical Objects I

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:
Well take two pitches from two different Note objects. Well add their difference to the rst one, reversing the direction of the interval, and combine them into a list with x-append. The results will form a Chord.

Ircam documentation

Chapter 1. Using Musical Objects I

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, dont forget to make sure the boxes are locked (with the b key) before continuing. Here are the notes by default:

Ircam documentation

Chapter 1. Using Musical Objects I

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 rst 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 rst Notes 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 dene. In this case, well use it to dene a scale (which is, after all, a set of relative intervals) which we can then build on any note.

Ircam documentation

Chapter 1. Using Musical Objects I

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 weve 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

Ircam documentation

Chapter 1. Using Musical Objects I

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 nds the distances between elements of a series, and its sister function dx->x converts relative values to absolute values, given some starting point.

10

Ircam documentation

Chapter 1. Using Musical Objects I

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. Its negative because 6000 is con-

Ircam documentation

11

Chapter 1. Using Musical Objects I

sidered to be the rst 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 rst, 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 rst note, 6000. To do this, we use the lisp function first, which, you guessed it, takes the rst element of a list, to extract 6000 from the list (6000 4900). That value is passed to the rst 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. Well transpose it in the process.

Key Modules Used


Chord, Chord-seq, om+, reverse

The Concept:
Here, well take the lmidic output of the Chord factory. You can check to see whats coming out of the factory at this output by option-clicking this output. If you havent changed the notes, youll 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.

12

Ircam documentation

Chapter 1. Using Musical Objects I

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)

Ircam documentation

13

Chapter 1. Using Musical Objects I

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


Topics
This tutorial applies what weve 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 material, in this case from Boulezs Structures. They are: transposition, retrograde, inversion and retrograde of the inversion.

14

Ircam documentation

Chapter 1. Using Musical Objects I

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 (its less cluttered than a big fat chord).

Ircam documentation

15

Chapter 1. Using Musical Objects I

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

16

Ircam documentation

Chapter 1. Using Musical Objects I

intervals. Multiplying these by -1 (G) changes their direction. With dx->x, (I) we will rebuild the list starting from the rst element, which we extract with first (H). The result (L):

And nally, its 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 well 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.

Ircam documentation

17

Chapter 1. Using Musical Objects I

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 rst note. The multiplcation factor (C) can be any number. Entering numbers smaller than 1 but

18

Ircam documentation

Chapter 1. Using Musical Objects I

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 rst 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:

Youll 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 youll probably see some more notes change to the more exact 8th-tone temperament.

Ircam documentation

19

Chapter 1. Using Musical Objects I

Tutorial 8: Construction of a harmonic series


Topics
Well 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 youre not yet in high school, bless your precocious little heart) the integer multiples of a given frequency (the fundamental) represent a harmonic series present in all pitched tones. We can construct a musical object with the same structure. To do this, we rst 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)

20

Ircam documentation

Chapter 1. Using Musical Objects I

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, were going to use an whats 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: rstly, abstractions are because they only exist

Ircam documentation

21

Chapter 1. Using Musical Objects I

within the current patch. The blue patches, in contrast, represent a master copy of that patchwhen 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 dont 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. Its 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, lets create the abstraction rst, 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.

22

Ircam documentation

Chapter 1. Using Musical Objects I

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:

Ircam documentation

23

Chapter 1. Using Musical Objects I

The inputs weve added are gateways to the outside world. Well 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. Well also need a list of integers representing the pitch ratios of the series. For this well 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 nish 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-

24

Ircam documentation

Chapter 1. Using Musical Objects I

ser dont 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 youre building a patch, youll usually need to test it before youre nished. When youre 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.

Lets 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, its easy to forget whats what when your screen is lled with icons.

If youve 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.

Ircam documentation

25

Chapter 1. Using Musical Objects I

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.

26

Ircam documentation

Chapter 1. Using Musical Objects I

Now, drag a connection from the list of integers to this second input of Note and evaluate. Youll get an error like this:

This is because a list is a different data type than a real. real is LISPs term for any kind of number.
first, on the other hand, only accepts lists as input, since it takes the rst element of a list. Give the oat to first as input and youll get a similar error. oat is LISPs 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 nd 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 youll see the notes in the mini-view. Now, take the rst output of the top Note object, self. self exists for many classes, and outputs the entire object. Evaluate self and youll see something like #<note #x9327B36> in the Listener. This is the Note object, and it is a data type like list and oat. Plug this into the rst 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- its 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 oat. 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

Ircam documentation

27

Chapter 1. Using Musical Objects I

object. The note appears in the Chord. What gives? Youve 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.

28

Ircam documentation

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 youve installed and congured Midishare- if you havent see the chapter on Installing Midishare Even if you have no MIDI equipment, you can still use Apples built-in QuickTime Musical Instruments synthesizer (which responds to MIDI messages just like any other MIDI instrument) to listen to your work. If youre working in 24- or 48-tone octaves, youll need to recongure 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 well send the notes of a Chord-seq out over 12 difference MIDI channels:

Ircam documentation

29

Chapter 2. Playing MIDI I

Well use the two lists, (A) and (B) as program changes and MIDI channels, respecively. Notice weve 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.

30

Ircam documentation

Chapter 2. Playing MIDI I

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, well use arithm-ser to create a list of midics running from 0 to 200 by increments

Ircam documentation

31

Chapter 2. Playing MIDI I

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 dont 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 One eighth-tone One quarter-tone Three eighth-tones Sent on MIDI channel 2 3 4

Well send a pitchwheel message to each of channels 2, 3, and 4, detuning the entire channel 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 pitchwheel 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 pitchwheel resets the other channels to normal tuning.

32

Ircam documentation

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 rst 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. Well 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 fth, 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.

Ircam documentation

33

Chapter 3. Using Aleatoric Elements

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

34

Ircam documentation

Chapter 3. Using Aleatoric Elements

called a tree. The second and fourth inputs to x-append are passed through om+ (H & I) for a transposition. 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 pitchwheel function in the upper-right in order that the microtones play back correctly. (See Tutorial 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.

Ircam documentation

35

Chapter 3. Using Aleatoric Elements

The Patch:

36

Ircam documentation

Chapter 3. Using Aleatoric Elements

First of all we will generate midicent notes by using om-random. This function takes as arguments two numbers (integer or oat). The two arguments represent the range of numbers 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, weve connected these to repeat-n, allowing us to obtain a series of 5 random midics in a list:

Now lets compare the outputs of (B) and (C). The output of the B patch is a list of ve different values each time it is evaluated, while the ouput of C patch is a list of ve 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 owchart 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, weve 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

Ircam documentation

37

Chapter 3. Using Aleatoric Elements

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 rst input of the Chordseq 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 rst 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, weve entered a at list with no sublists, 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 dene 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 durations of the notes.

38

Ircam documentation

Chapter 3. Using Aleatoric Elements

The Patch:

We will use the same patch as in tutorial 10. om-random will be back in its normal mode, because here we dont 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 between 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. Theres another problem. Durations are simply the durations of the notes once struck. Off-

Ircam documentation

39

Chapter 3. Using Aleatoric Elements

sets, on the other hand, are measured from the beginning of the sequence. This means we cant 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 Midile class in the patch and evaluate it. A dialog window comes up. Look for the le INV6.MID in the exampleFiles/Midi folder, in the main OM folder. This is a MIDI le of the 6th two-part invention by J.S. Bach. Once evaluated, lock the box. Opening the Midile brings up a piano-roll style editor where you can see the two channels of the MIDI le, color coded for clarity:

The Chord-seq class can take a MIDI le as input to its self input, and it will be transcribed:

40

Ircam documentation

Chapter 3. Using Aleatoric Elements

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.

Ircam documentation

41

Chapter 3. Using Aleatoric Elements

Note velocity is MIDIs 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.

42

Ircam documentation

Chapter 3. Using Aleatoric Elements

OM turns the velocities into traditional dynamic marks using a table you set up in the Preferences 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).

Ircam documentation

43

Chapter 3. Using Aleatoric Elements

44

Ircam documentation

Chapter 4. Flow Control I: Predicates


Tutorial 14: Random construction of a sequence
Topics
The idea of ow 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.

Ircam documentation

45

Chapter 4. Flow Control I: Predicates

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 ow. The ow of a program or an OM patch determines what will be done and in what order.

46

Ircam documentation

Chapter 4. Flow Control I: Predicates

OM patches are owcharts which graphically represent this ow. Mastering ow 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 ow. 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 rst 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.

Ircam documentation

47

Chapter 4. Flow Control I: Predicates

48

Ircam documentation

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 ltered 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 Chordseq module.

The Patch:

Ircam documentation

49

Chapter 5. Flow Control II: Loops

This patch contains two different sections: Section A, whose task is to send MIDI messages, 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 simultaneously. The rst sends the program change 56 to channel one, while the second module sends program change 1 to channel two.

At (B), weve created an abtraction (red patch). Remember these? Look back to Tutorial 8 if you dont remember. Heres 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 evalonce 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:

50

Ircam documentation

Chapter 5. Flow Control II: Loops

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 specic 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 rst 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:

Ircam documentation

51

Chapter 5. Flow Control II: Loops

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.
collects rst output is connected to eachTime, which triggers the repetitions of the loop, and the second to finally, which carries the results of the naly 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.

52

Ircam documentation

Chapter 5. Flow Control II: Loops

Now lets 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.

Ircam documentation

53

Chapter 5. Flow Control II: Loops

The Patch:

Edit your series in the Chord object (A) after setting it to order mode.

54

Ircam documentation

Chapter 5. Flow Control II: Loops

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).

Ircam documentation

55

Chapter 5. Flow Control II: Loops

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:

56

Ircam documentation

Chapter 5. Flow Control II: Loops

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 rst 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 omloops output.

Ircam documentation

57

Chapter 5. Flow Control II: Loops

58

Ircam documentation

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).

Ircam documentation

59

Chapter 6. Using Musical Objects II

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.

60

Ircam documentation

Chapter 6. Using Musical Objects II

x-append (D) will concatenate these results in harmonic order (i.e rst we will have 4 randomly choosen notes from the rst reservoir, then 4 from the second one etc...).

In order to have this whole harmonic sequence repeat twice, we will again use the repeatn 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. Youll 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 atten 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 Colombian 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 interpolation between two seed chords we choose. The rst 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.

Ircam documentation

61

Chapter 6. Using Musical Objects II

The Patch:

We have choosen two chords of same density (i.e same number of notes) in Chord (A) and Chord (B).

62

Ircam documentation

Chapter 6. Using Musical Objects II

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 denes 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 specied 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.

Ircam documentation

63

Chapter 6. Using Musical Objects II

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-randoms output to a repeat-n module will repeat this n times on each chord. Notice that repeat-ns 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 omloops 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 atten the list with the function flat.

64

Ircam documentation

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).

Ircam documentation

65

Chapter 7. Breakpoint Functions

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 notation. 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.

66

Ircam documentation

Chapter 7. Breakpoint Functions

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 converting it back to values, we can take more or fewer samples than the original sequence, creating a "smoother" melody.

Ircam documentation

67

Chapter 7. Breakpoint Functions

The Patch:

Enter a sequence of notes in "order" mode in the Chord and lock it:

68

Ircam documentation

Chapter 7. Breakpoint Functions

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 specied 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 theyll 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 t within a given interval

Ircam documentation

69

Chapter 7. Breakpoint Functions

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 bpfsample to create a contour with n elements (in this case, 13). These points are then scaled with om-scale to occur within the interval specied 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.

70

Ircam documentation

Chapter 7. Breakpoint Functions

The Patch:

Open the BPF:

Ircam documentation

71

Chapter 7. Breakpoint Functions

Heres 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 (rst 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 prole. Open the Chord box (F) and enter one note. The note you enter will be the highest note of your melodic prole. 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 rst (and only) element of these lists. These midic values are passed to om-scale, which adjusts the list at its rst 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 superuous; 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

72

Ircam documentation

Chapter 7. Breakpoint Functions

function with the output of om-round.

Ircam documentation

73

Chapter 7. Breakpoint Functions

74

Ircam documentation

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 dont tell the whole story, however. The duration alone is not sufcient 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 xed 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:

Lets take the following list of durations:

Ircam documentation

75

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 before 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:

76

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

Rather than calculate the durations, we can x 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 x all the durations of the sequence, as weve 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.

Ircam documentation

77

Chapter 8. OM Music objects Chord-seq and Voice

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 concerned 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 durations 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:

78

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

Heres 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

Ircam documentation

79

Chapter 8. OM Music objects Chord-seq and Voice

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 lters: If an element of our list is less than 0 (meaning it is a rest), both omifs will return nil. If not, the rst omif will return the onset time, the other the duration. All thats 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:

80

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

(? (((4 8) ((4 (1 1 1 1)))) ((4 8) ((4 (1 1 1 1)))) ((4 8) ((4 (1 1 1 1))))))

While difcult to look at, the structure is actually quite logical: The rhythmic structure

The rst 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. Its 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 proportions, representing the way the duration represented by that time signature is divided.

The rst 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.

Ircam documentation

81

Chapter 8. OM Music objects Chord-seq and Voice

The structure is again a list of lists where the rst 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 oats (decimals) as follows:
(? ( ((4 8) ((4 ( 1 -2 1)))) ((3 4) ((3 (1.0 2)))) ) )

represents:

82

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

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 ve 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)))) ))

Ircam documentation

83

Chapter 8. OM Music objects Chord-seq and Voice

The Patch:

Here well just try to build a simple sequence of three measures of 4/8 with a pattern of repeated eighth notes. Well reverse engineer the rhythm tree. Since the tree is a nested list, well build the indi-

84

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

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 rst element, the question mark. Note that in the ow 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 rst 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 rst two lists will dene the time signature of each measure (the rst 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.

Ircam documentation

85

Chapter 8. OM Music objects Chord-seq and Voice

The Patch:
Heres the interior of the abstraction:

86

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

Inside this patch three omloops will construct the leaves of our rhythm tree. The rst omloop will produce time signature:

Ircam documentation

87

Chapter 8. OM Music objects Chord-seq and Voice

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, except that it pairs the measure lengths (time signature numerators) with the lists of rhythmic structure.

88

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

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.

Ircam documentation

89

Chapter 8. OM Music objects Chord-seq and Voice

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:

90

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

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 Hh sei Ehr from J.S. Bachs 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 OMs import and export capabilites to move objects back and forth between OM and Finale, since Finales editing interface remains slightly more uid. See the Function References 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, lets look at the Voice editor window:

Ircam documentation

91

Chapter 8. OM Music objects Chord-seq and Voice

As with all editors, there are a series of buttons which control which what level were 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 simultaneously 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.

92

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

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 elds 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:

Ircam documentation

93

Chapter 8. OM Music objects Chord-seq and Voice

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:

94

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

This menu lists the available commands. Some have not yet been implemented. In addition, some of the commands are only applicable when you are in edit mode (represented 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 nished rhythmic structure:

Ircam documentation

95

Chapter 8. OM Music objects Chord-seq and Voice

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, youre 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 rst rest of the rst measure. You enter edit mode and the red cursor appears:

96

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

Youll also notice three radio buttons appear on the palette. These buttons control the behavior 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, well start with a hypothetical measure of 3/4 containing 3 quarter notes:

We will put the red cursor in front of the rst 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 t in the measure. This usually results in the creation of a tuplet of some kind:

For our purposes, we want the rst 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:

Ircam documentation

97

Chapter 8. OM Music objects Chord-seq and Voice

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 rst quarter note into a rest. Use to move the green cursor back to it:

98

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

...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 rst 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 rst 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

Ircam documentation

99

Chapter 8. OM Music objects Chord-seq and Voice

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 rst 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:

100

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

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 dont 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 quantication


Topics
Converting lists of durations into traditional rhythmic notation; passing data between Chord-seq nad Voice.

Ircam documentation

101

Chapter 8. OM Music objects Chord-seq and 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 ush 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 ush 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:

102

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

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 ush 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 rst 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:

Ircam documentation

103

Chapter 8. OM Music objects Chord-seq and Voice

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:

104

Ircam documentation

Chapter 8. OM Music objects Chord-seq and Voice

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:

Youll 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 fth and the seventh optional inputs of omquantify. The fth input, forbid is a list of forbidden subdivisions of the pulse (here quintuplets, sextuplets and septuplets are forbidden). The

Ircam documentation

105

Chapter 8. OM Music objects Chord-seq and Voice

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 dont 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:

106

Ircam documentation

Chapter 9. Playing MIDI II


Tutorial 28: Working with MIDI les I
Topics
Converting a Midile into a Chord-seq after transposing its notes.

Key Modules Used


mf-info, mat-trans, omloop, save-as-midi

The Concept:
Converting a Midile into a Chord-seq can be done immediately by patching the self output of the le into the self input of the Chord-seq. Indeed, the Chord-seq class will inherit all its elements from the Midile, which will be converted into appropriate data by the internal of the Chord-seq . For instance, standard MIDI notes from the Midile 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 Midile so that you can work with its elements. mf-info takes a Midile and returns a tree where each channel is a list of notes, and each note is itself a list of ve 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.

Ircam documentation

107

Chapter 9. Playing MIDI II

The Patch:

A MIDI le is dragged onto a patch. This will create a Midile 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 le. 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

108

Ircam documentation

Chapter 9. Playing MIDI II

data from a particular track (instead of the whole le. The rst track is numbered zero. The track is a list of lists, each containing the ve 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 le. We separate these parameter lists with the LISP functions first, second, and so on. The rst sublist is a list of all the rst 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 le:

with omloop structured as follows:

Ircam documentation

109

Chapter 9. Playing MIDI II

Inside omloop we have reproduced the main patch as it was shown earlier adding an iterative 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 repetition when this value equals a certain threshhold.
forloop is setup to run from zero to the number of tracks-1 (since the rst track is called

zero). The iterator itself outputs the current value of the variable. It will thus output 0 on the rst repetition and 1 on the second and last. This value is used in mf-info to isolate a particular track for the transposition process.

110

Ircam documentation

Chapter 9. Playing MIDI II

Tutorial 29: Working with MIDI les II


Topics
Converting a standard Midile into a Chord-seq with correct microintervals.

Key Modules Used


Midile, omloop, omif, repeat-n

The Concept:
Most commercial MIDI sequencers dont 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 les into a Chord-seq which will play correct microintervals.

Ircam documentation

111

Chapter 9. Playing MIDI II

The Patch:

In our example we have created a simple multitrack MIDIle. It represents a chromatical segment of a quarter-tone scale starting from C3. The rst 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 reect the detuning of the other channels in the MIDI le.

112

Ircam documentation

Chapter 9. Playing MIDI II

At (A) the MIDIle is opened (or dragged into an OpenMusic patch).

Each color represents a different MIDI channel. (Here blue is channel 1 and green is channel 2) Now if we open the Chord-seq (B) editor and check the chan popup menu, we can see each notes channel.

Ircam documentation

113

Chapter 9. Playing MIDI II

In the rst 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.

114

Ircam documentation

Chapter 9. Playing MIDI II

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:

Ircam documentation

115

Chapter 9. Playing MIDI II

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

116

Ircam documentation

Chapter 9. Playing MIDI II

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

Ircam documentation

117

Chapter 9. Playing MIDI II

118

Ircam documentation

Chapter 10. Using Musical Objects I


Tutorial 30: Working with lists I
Topics
Creating rhythm from arithmetic series and "lling" 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).

Ircam documentation

119

Chapter 10. Using Musical Objects I

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 afterwards). Lets say that we want to build our rhythms with the sixteenth as the smallest unit. Well 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.

120

Ircam documentation

Chapter 10. Using Musical Objects I

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 rst 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.

Ircam documentation

121

Chapter 10. Using Musical Objects I

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.

122

Ircam documentation

Chapter 10. Using Musical Objects I

The Patch:

Heres a schematic of the patch:

Ircam documentation

123

Chapter 10. Using Musical Objects I

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 weve 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, omscale/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 gure in the BPF editor.

124

Ircam documentation

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 Maquette can contain any musical object, but can also contain a special object called Temporalbox. These boxes can contain other patches and Maquettes. A Maquette looks like this:

Youll 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 eld, 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

Ircam documentation

125

Chapter 11. The Maquette

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. Heres 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.

126

Ircam documentation

Chapter 11. The Maquette

The rst 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 boxs position and shape to modify the

Ircam documentation

127

Chapter 11. The Maquette

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 FileNewNew Maquette. Open it by doubleclicking 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 dont 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.

128

Ircam documentation

Chapter 11. The Maquette

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.

Ircam documentation

129

Chapter 11. The Maquette

Once youve 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 random 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-

130

Ircam documentation

Chapter 11. The Maquette

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 evaluation. We can see that one Temporalbox depends on another here. In order to accomplish this, well need to pass data about the series from the one to the other in order that the complement can be constructed.

The Patch:

Lets look inside the rst Temporalbox:

Ircam documentation

131

Chapter 11. The Maquette

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

132

Ircam documentation

Chapter 11. The Maquette

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 remainder) a number or list. The quotient is returned at the rst 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

Ircam documentation

133

Chapter 11. The Maquette

the list of elements present in the rst 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 permutrandom 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 rst box via an input specially added:

...and the interior of the omloop:

134

Ircam documentation

Chapter 11. The Maquette

...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 theyll 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 ll the Maquette with random notes and chords:

Ircam documentation

135

Chapter 11. The Maquette

136

Ircam documentation

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 well 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 lets look at our examples.

Ircam documentation

137

Chapter 12. Lambda Functions

The Patch:
The rst example

The mapcar function takes as a rst argument another function and applies that function it to its other arguments. This called function at the rst 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. Youll notice that weve typed the function name, list, into the box given as rst 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:

138

Ircam documentation

Chapter 12. Lambda Functions

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))

Ircam documentation

139

Chapter 12. Lambda Functions

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

140

Ircam documentation

Chapter 12. Lambda Functions

with omloop. Its 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:

Ircam documentation

141

Chapter 12. Lambda Functions

We drag the patch Tutorial_30 into a new patch and make an abstraction of it with a so that we dont 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 rst input of a Chord-seq (B). We build a red patch which takes an integer and adds a random value between -200 and 300:

142

Ircam documentation

Chapter 12. Lambda Functions

We need to convert these durations into onsets with dx->x, but dx->x only takes at 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.

Ircam documentation

143

Chapter 12. Lambda Functions

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 rst 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

144

Ircam documentation

Chapter 12. Lambda Functions

procedure of Tutorial 18, which will interpolate a series of notes between this Chord and another. Lets look at the loop at (D).

Inside is an abstraction of the patch from Tutorial 14, with an input and an output added:

Ircam documentation

145

Chapter 12. Lambda Functions

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:

146

Ircam documentation

Chapter 12. Lambda Functions

...modied 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 rst input.) The abstraction has two inputs! But funcall will only pass data to the rst 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.

Ircam documentation

147

Chapter 12. Lambda Functions

148

Ircam documentation

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:

Well do two variants on the factorial procedure. In the rst, well just go for the nal result. In the second, well program omloop to return a list with the products of the intermediary operations. The rst loop looks like this:

Ircam documentation

149

Chapter 13. Flow Control III: More Loops!

The acum collector takes three arguments. The second input (B) is an initializer, which sets the internal state of the accumulator before the rst 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 rst input (A) and 2) the internal state of the accumulator. In our case well use om* since were 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 output Value of the rst input of accumulator Value of the second input of accumulator 1 / / / / Internal state (buffer) Binary function om* output

0 1 2 3 4

1 2 3 4 5

1 2 3 4 5

1 1 2 6 24 120

1 2 6 24 120

150

Ircam documentation

Chapter 13. Flow Control III: More Loops!

The nal state of the accumulator is available at the second output and passed to finally. As congured, the loop will output the nal factorial when evaluated:
? OM->120

If we want to see the intermediary steps, we need to record the internal state of the accumulator at each repetition of the loop. This is done by adding a collect function and connecting it to the rst 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)

Ircam documentation

151

Chapter 13. Flow Control III: More Loops!

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 dened but their direction (up or down) will be random (i.e ascending or descending depending on om-randoms output). In order to do so we will use an accumulative proceedure using omloops acum collector. We will also demonstrate the sequence function by simultaneously visualizing our new melodic gure using a BPF factory.

152

Ircam documentation

Chapter 13. Flow Control III: More Loops!

The Patch:

The transformation of the sequence into a new one will be done in omloop (C). This transformation 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 lets look inside omloop.

Ircam documentation

153

Chapter 13. Flow Control III: More Loops!

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 rst use flat since the lmidic output of the Chord-seq is a listand x->dx needs a at 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. Heres the lambda patch:

154

Ircam documentation

Chapter 13. Flow Control III: More Loops!

The lambda patch (G) will take the initial note (H) and will add to it the rst interval (I). This interval will have been rst 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 rst 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 rst output of acum, as we did in the

Ircam documentation

155

Chapter 13. Flow Control III: More Loops!

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 rst 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.

156

Ircam documentation

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 benet 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 nding 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. Without a termination test, the function continues to call itself on into innity, 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.

Ircam documentation

157

Chapter 14. Flow Control IV: Recursive Functions

Lets look at a recursive patch in OM which will calculate the factorial of whatever number we give it:

The Patch:

On the rst 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 nally, n is zero. At this point, omif (the termination test at B) will return 1 instead of evaluating factorial. 1 is passed to

158

Ircam documentation

Chapter 14. Flow Control IV: Recursive Functions

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 whats called a rhythm tree. The rhythm tree is a series of lists in the form (D S) where D is

Ircam documentation

159

Chapter 14. Flow Control IV: Recursive Functions

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 rst element ? must always gure in the beginning of the list and therefore must be left as is. Measure signatures must also gure 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 wont 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.

160

Ircam documentation

Chapter 14. Flow Control IV: Recursive Functions

The Patch:

Here it is. The actual reversal of elements is accomplished by (E) and (G), which split the (D S) structure into its rst 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 satised and we begin to work back out of the levels of recursion, 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 didnt 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, lets look at the incorrect results of a simple non-recursive function which splits the D and S elements apart and reverses the S elements.

Ircam documentation

161

Chapter 14. Flow Control IV: Recursive Functions

This patch has two problems. The rst 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 dont 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:

162

Ircam documentation

Chapter 14. Flow Control IV: Recursive Functions

Ircam documentation

163

Chapter 14. Flow Control IV: Recursive Functions

164

Ircam documentation

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 le.

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, Chordseqs and Voice objects in Maquettes. After that, we will save our musical sketch in the form of a Midile. 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:

Ircam documentation

165

Chapter 15. The Maquette II

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 dont 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 rst 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 youve congured these patches to play in a Maquette - see Tutorial 32). These objects are placed within the Maquette at the onset times specied at the rst input. In this patch we will take a series of objects created in previous tutorials and combine them in a Maquette. The rst 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 rmus" 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.

166

Ircam documentation

Chapter 15. The Maquette II

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 rmus 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 rst object is our cantus rmus 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, modied so that the Chord-seq it generates is connected to an output (necessary so it can play through the Maquette.):

Ircam documentation

167

Chapter 15. The Maquette II

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 efcient 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 rst input of the Maquette (L) we connect a the list of onsets coming from the Chordseq (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 Its important to remember that evaluating a Maquettes icon is not the same as entering the Maquette itself and clicking the Eval button on the palette. The Eval button only causes

168

Ircam documentation

Chapter 15. The Maquette II

items already within the Maquette to be evaluated. Connections made to the Maquettes inputs in the patch window are not evaluated. In building this tutorial from scratch, for example, 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 rst 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 le of the output. That le can then be transferred to other programs, or

Ircam documentation

169

Chapter 15. The Maquette II

reopened in OM by using a Midile 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.

170

Ircam documentation

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 specic 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 nd 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 rst open a patch. Then, in the patch window, select FileNew Generic Function.

Ircam documentation

171

Chapter 16. Classes and Inheritance

A dialog box opens:

Give your function the name myplus, and add a remark about what it does. This documentation 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 le WSPL.rsrc le in the current workspace folder.

172

Ircam documentation

Chapter 16. Classes and Inheritance

Be careful editing these resources. Always work with a copy! After editing the name and icon and hitting OK, the functions 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 youve not seen before appears:

Ircam documentation

173

Chapter 16. Classes and Inheritance

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. Lets start by dening a method for adding two integers. We need two inputs, if you havent 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 nd 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:

174

Ircam documentation

Chapter 16. Classes and Inheritance

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:

Ircam documentation

175

Chapter 16. Classes and Inheritance

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).

176

Ircam documentation

Chapter 16. Classes and Inheritance

myplus doesnt know how to deal with lists, however. Lets add a method allowing myplus to handle an integer as its rst argument and a list as its second.

Once youve used myplus in a patch window, double click it to open its methods window:

Notice that our rst method has icons representing the data types it accepts. While in this window we add a new method with FileNew Method:

A new editing window will appear with some extra radio buttons in its upper part. Dont 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.

Ircam documentation

177

Chapter 16. Classes and Inheritance

Drag two classes from the LISP package, but this time make them one integer and one list:

Create an omloop and congure it:

178

Ircam documentation

Chapter 16. Classes and Inheritance

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. Its 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:

Ircam documentation

179

Chapter 16. Classes and Inheritance

We now have 4 methods in our myplus function:

We can now accomplish all four types of addition, as presented in the Tutorial patch:

180

Ircam documentation

Chapter 16. Classes and Inheritance

User-created generic function denitions are stored in the Workspace folder, in the subfolder 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

Ircam documentation

181

Chapter 16. Classes and Inheritance

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 functions 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, dened in the previous tutorial, allowing it to add Chords and Notes by adding additional methods.

Adding New Methods


We will dene 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 FileNew 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:

182

Ircam documentation

Chapter 16. Classes and Inheritance

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 dont 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 wont 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

Ircam documentation

183

Chapter 16. Classes and Inheritance

pass the entire object to the output (via the self output).

We may use our newly edited function:

184

Ircam documentation

Chapter 16. Classes and Inheritance

Using two Notes, we connect them to myplus and get back a Chord:

Now lets 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 were ready to put our ltered, sorted list of midics into the lmidic input of a Chord object, and on to the output.

Ircam documentation

185

Chapter 16. Classes and Inheritance

We can now use the new method: A Chord

186

Ircam documentation

Chapter 16. Classes and Inheritance

and second Chord:

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

Ircam documentation

187

Chapter 16. Classes and Inheritance

The resulting chord, viewed in order mode:

188

Ircam documentation

Chapter 17. Classes and Inheritance


Tutorial 44
This tutorial has not been written as of printing. We expect to add it shortly.

Tutorial 45
This tutorial has not been written as of printing. We expect to add it shortly.

Ircam documentation

189

Chapter 17. Classes and Inheritance

190

Ircam documentation