Modalys Documentation PDF

Modalys
Guide Map
Welcome to Modalys!
Modalys
Summary This new version of the documentation covers the basic use of the Modalys physical modeling
An Introduction to Modalys synthesis software and is a first step at creating an even more comprehensive user's manual for the
Getting Started future. Although much of it has been redesigned and rewritten, many parts of it nonetheless are based
Objects
on the original Morrison/Waxman documentation (either verbatim or paraphrased). It corresponds to
Modalys 3.3.1, as of April 2013.
Accesses
Connections With Modalys you will enjoy creating mind-blowing virtual musical instruments based on physical
Controllers models!
The Modalys Workspace
Finite Elements
Appendix
Index
Please visit www.forumnet.ircam.fr and stay tuned for IRCAM technologies, and can get some help
from our Modalys Discussion Group.
Operating Sytem and Computer Requirements
Modalys works for :
Mac OS 10.5 and later (including Mountain Lion)
Intel Mac with a minimum of 2 Gigs of RAM.
Environment
Modalys is primarily a framework that can be used under various environments:
As a stand-alone application, ModaLisp, powered by LISP language.
As a Max/MSP set of objects for realtime use (MLYS and modalys~ objects). Compatible with
Max 5 and 6.
As an OpenMusic library.
As a MatLab set of objects for scientific applications.
See also ©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/[28/05/13 14:34:59]
Modalys
Getting Started
An Introduction to Modalys
NB : this documentation can be accessed either from ModaLisp Help menu or directly from
/Applications/Modalys.
http://support.ircam.fr/docs/Modalys/current/[28/05/13 14:34:59]
Modalys - Map
Guide Map
Map
Modalys
Summary
Getting Started
Objects
Object Properties
Common Parameters and Properties for Modal Objects
Material Properties for Strings, Plates and Membranes
Material Properties for Wooden Bars
Object Reference
One-Mass - Mono-directional (Harmonic Oscillator)
Two-Mass - Mono-directional
Two-Mass - Bi-directional
String (or Rod) - Mono-directional
String (or Rod) - Bi-directional
Tube - open/open
Tube - closed/open
Tube - closed/closed
Rectangular Membrane - Fixed
Circular Membrane - Fixed
Rectangular Plate - Fixed
Circular Plate - Clamped
Circular Plate - Free
Rectangular Free Bar
Violin Bridge
Cello Bridge
Jet Object
Single Point Object
Radiator Object
Clone Object
Save Modal Object
Read Modal Object
Resonance Model Object
Piano Soundboard
Finite Element
Object Utilities ©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/publication-web_1.html[28/05/13 14:35:20]
Modalys - Map
Set Object Pitch

Set Mode Freq
Set Mode Loss
Attach Mode Controllers
Set Frequency (of All Modes)
Set Loss (of All Modes)
Set Amplitude (of All Modes)
Get Object Info
Freeze Object
Unfreeze Object
Save Modal Object
Hybrid Objects
Melt-Hybrid Object
Mix-Hybrid Object
Tri-Hybrid Object
Accesses
Standard Accesses
Using Compiled Accesses
Hybrid Accesses
Tri-Hybrid Accesses
Get Access Info
Connections
Force Connection
Speed Connection
Position Connection
Acoustic Hole Connection
Adhere Connection
Strike Connection
Pluck Connection
Spring Connection
Reed Connection
Felt Hammer Connection
Mono-Fingerboard Connection
Normalised Valve Connection
Normalised Leaky Valve Connection
Bow Connection
Bi-Fingerboard Connection
Valve Connection
Leaky Valve Connection
Induction Connection
Labium Connection
Destroy Connection
Get Connection Info
Modalys - Map
Controllers
Constant Controller
Envelope Controller
Access Speed Controller
Access Position Controller
Access Force Controller
Connection State Controller
Last Sample Controller
Sound File Controller
MIDI File Controller
Dynamic Controller
Send Message
Set Breakpoint
Signal Controller
Scale Controller
Arithmetic Controller
Expression Controller
Foreign-Call Controller
Sine Controller
Random Controller
Band-Limited Noise Controller
Noise (Band-Limited Impulse) Controller
Delay Controller
Bilinear (First Order IIR) Filter
Biquadratic (Second Order IIR) Filter
Constant Second Order (Bandpass) Filter
Variable Second Order (Bandpass) Filter
Dimension-Mapping Controller
Sum Controller
Spread Controller
Get Controller Info
New Workspace
Run Synthesis
Play Sound
Set Message Level
Set Precision
Run Synthesis in Real-Time
Listen to IP Port
Set Angle Mode
Get Version
Stop
Quit Modalys
Point Output
Modalys - Map
Point Input
Save AIFF Sound File
Save Floating-Point Sound File
Set Sample Rate
Set Bit Depth
Set Number of Channels
Get Workspace Info
Get Angle Mode
Make Plot
Plot Value
Plot
Load Modalys Script
Load Modalys Component
Save Mlys Script File
MIDI to Frequency
Frequency to MIDI
Finite Elements
Appendix
Index
Modalys - Summary
Guide Map
Modalys Summary
Summary
Welcome to Modalys!
Getting Started
Objects This documentation is organized into the following sections:
Accesses
Introduction - an overview and history of the program
Connections
Getting Started - practical information about installing Modalys
Controllers Objects - the basic sound-producing structures in Modalys
The Modalys Workspace Accesses - points of communication between Modalys objects
Finite Elements Connections - physical interactions between Modalys objects
Appendix Controllers - managing Modalys parameters in time
Index Workspace - the Modalys working environment and its options
Finite Elements - [forthcoming] creating modal objects based on 3D meshes
Appendix - Supplementary Information
Index - an alphabetical index of Modalys functions
Modalys Documentation v. 3.3.1.rc2
Written by Richard Dudas - ©IRCAM 2013.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/ModalysDocumentation.html[28/05/13 14:36:01]
Modalys
Guide Map
Welcome to Modalys!
Modalys
Summary This new version of the documentation covers the basic use of the Modalys physical modeling
An Introduction to Modalys synthesis software and is a first step at creating an even more comprehensive user's manual for the
Getting Started future. Although much of it has been redesigned and rewritten, many parts of it nonetheless are based
Objects
on the original Morrison/Waxman documentation (either verbatim or paraphrased). It corresponds to
Modalys 3.3.1, as of April 2013.
Accesses
Connections With Modalys you will enjoy creating mind-blowing virtual musical instruments based on physical
Controllers models!
Finite Elements
Appendix
Index
Please visit www.forumnet.ircam.fr and stay tuned for IRCAM technologies, and can get some help
from our Modalys Discussion Group.
Operating Sytem and Computer Requirements
Modalys works for :
Mac OS 10.5 and later (including Mountain Lion)
Intel Mac with a minimum of 2 Gigs of RAM.
Environment
Modalys is primarily a framework that can be used under various environments:
As a stand-alone application, ModaLisp, powered by LISP language.
As a Max/MSP set of objects for realtime use (MLYS and modalys~ objects). Compatible with
Max 5 and 6.
As an OpenMusic library.
As a MatLab set of objects for scientific applications.
See also ©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/publication-web.html[28/05/13 14:36:50]
Modalys
Getting Started
NB : this documentation can be accessed either from ModaLisp Help menu or directly from
/Applications/Modalys.
http://support.ircam.fr/docs/Modalys/current/co/publication-web.html[28/05/13 14:36:50]
Modalys - An Introduction to Modalys
Guide Map
Modalys An Introduction to Modalys

Summary
An Introduction to Modalys Foreword
Getting Started
Nearly a quarter of a century has passed since the very first version of Modalys (originally named
Objects
Mosaic) was developed at IRCAM. The program was initially created by Jean-Marie Adrien for his
Accesses
doctoral thesis in Physics and subsequently redesigned by Joseph Morrison coded in C++, but using
Connections
an interactive text-based user interface in the Scheme programming language (a cousin of Lisp) as a
Controllers control mechanism. As processor speeds increased in the decades that followed, Modalys was
The Modalys Workspace extended and improved by a host of other developers: Gerhard Eckel, Francisco Iovino, Nicolas
Finite Elements Misdariis, Christophe Vergez, Nicholas Ellis, Joël Bensoam and Robert Piéchaud. Since then, the
Appendix original user manuals and reference, written by Joseph Morrison and David Waxman (with some later
Index updates and editing by Gerhard Eckel, Francisco Iovino and Marc Battier) had become horribly out of
date and due to changes, improvements and additions to the program, and consequently the
documentation was both missing important descriptions of new features and contained descriptions of
existing features which no longer reflected their actual syntax.
For the moment this new manual refers mainly to the syntax of the current Lisp interface, ModaLisp.
Since other interfaces to the Modalys synthesis engine (i.e. the Open Music (OM) Modalys interface,
as well as the modalys~ and MLYS interfaces for Max/MSP) follow more or less the same paradigm, it
seemed to make sense to focus initially on the Lisp interface, since it serves as a common
denominator for all flavors of Modalys.
In addition to the above-mentioned people, special thanks also go to René Caussé, Mikhail Malt, Jean
Lochard, Manuel Poletti, Hans Peter Stubbe Teglbjærg and Karim Haddad, who helped to provide
examples as well as to unearth long-lost Modalys-related documentation and other materials from their
archives.
Richard Dudas, 2013
Center for Research in Electro-Acoustic Music and Audio Technology (CREAMA), Hanyang University
School of Music, Seoul
Overview
Modalys is a physical modeling synthesis program. In computer music, physical modeling synthesis
methods have been a good way of obtaining qualities of sound which are not easy to produce with
standard sound synthesis methods such as additive, subtractive or frequency modulation.
A sound wave is the result of a mechanical or acoustical vibration of a body. The vibration results from
an external source which injects energy into the body, for instance a hammer striking a membrane or
the flow of air perturbing a pipe. Usually the object source of energy is referred to as the “exciter” and
the vibrating object is called the “resonator.” The type of coupling between the two objects is known as
an “interaction.”
Most types of sound can be decomposed into two opposing categories: transient sounds whose
perceptual characteristics evolve quickly in time, and stationary sounds whose perceptual
characteristics evolve slowly in time. Sounds in the latter category are easy to reproduce with the
computer since the Fourier theory gives us powerful methods to decompose and generate static
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/Introduction.html[28/05/13 14:37:36]
periodic signals. Traditional synthesis methods are related to the Fourier theory and are thus
appropriate for generating stationary sounds. Unfortunately, the Fourier theory has some limitations
when dealing with transient sounds, so alternative methods (filtered noise and other non-periodic
synthesis methods) have been proposed as computational tools for generating sounds in this domain.
Physical modeling programs generate sounds which are the result of a numerical simulation of
vibrating structures represented inside the machine. In particular the program can simulate simple
structures such as strings, pipes and plates, but also complex ones such as a cello body or a clarinet
mouthpiece. Classical physical modeling techniques rely on space discretization - in other words, in
order to simulate a certain structure the computer represents it as a set of masses distributed uniformly
in the space. The principal problem with this approach is that the representation is always dependent
on the spatial properties of the structure and thus each structure needs an individual type of
representation.
The means by which the Modalys program generates the sound is called modal synthesis. Modal
synthesis is a musical application of modal theory which arises from the aircraft and bridge-building
industry, where precise simulation of vibrating structures submitted to external forces is needed. The
basic result of Modal theory is that the way a structure will react to a given external excitation can be
predicted by knowing which are the basic modes of vibration of the structure. A mode of vibration is
defined as a particular shape the structure assumes when it is excited by a periodic force at a certain
frequency and all its points resonate at that frequency. One of the fundamental principles of acoustics
states that any vibration of a structure can be decomposed as a superposition of its basic modes of
vibration. Modal theory has also developed experimental methods for measuring the modes of
vibration of a given musical instrument. Compared with the existing physical modeling synthesis
methods, modal synthesis offers two advantages:
• representation is independent of the spatial properties of the structure. This is especially useful since
continuous transition from one instrument into another reduces the transition of modal parameters.
• representation is directly related to the aural characteristics of the structure. The resonating
frequencies of a mode are the spectral components of the sound produced when exciting the structure
with an impulse.
Basic Concepts of Synthesis with Modalys
To understand the idea of Modalys synthesis, imagine yourself as an instrument maker (luthier), sitting
at a large empty workbench. In the drawers of the bench, there is an unlimited supply of objects which
you can put upon the table and assemble into instruments. Objects, in most cases, can be thought of
as real physical entities which can be glued together, struck, plucked, bowed, or otherwise excited in
order to produce vibrations, and in turn, sounds. They include strings, air columns, two-mass models
(which act as hammers, picks or fingers depending on their sizes), metal plates, membranes, violin
bridges, and cello bridges.
Suppose that we would like to make a simple instrument which has one string. Our first difficulty arises
when we open the workbench drawer labeled “Strings.” Unlike the real-world instrument maker, who
might have a small drawer containing 20 different kinds of strings varying in size, material, length, and
thickness, we have a very large drawer. It is, in fact, an infinitely large drawer from which we can take a
string of any material and dimension. When choosing our string, then, we must be very specific about
its parameters. Later in this manual, we will go into more detail on this subject; for the moment, imagine
that we know exactly which string to take from the drawer and we put it on the table. String objects in
Modalys come with their ends fastened securely against virtual “walls,” so we don't have to worry about
making a body for the instrument. We can add one later if we want.
To play the string, we must first make several choices: what object do we use to excite the string (a
finger, a pick, a reed, or a sledgehammer, to name a few possibilities), and how do we excite it. The
possible answers to our first question are numerous; in fact, a Modalys object can be excited using any
other Modalys object. Most of the the types of objects which one normally uses to excite a string are
variations of the two mass model (i.e., fingers, picks, hammers, bows, etc.), but one can also use other
objects such as air columns, and metal plates. Let us, for now, open the drawer labeled “Two-Mass
Models” and pull out a guitar pick. We now face the second question of what to do with the pick.
Modalys permits several interactions, called connections, between objects. Connections can be thought
of as black boxes which go between objects specifying a certain relationship between them. For
example, two objects may be “glued” together, one object may bow another, pluck another, strike
another, or push another. All of these interactions: glue, bow, pluck, strike, and push are connection
types (the complete list of possible connection types will be presented below). Each connection can be
piloted using controllers, which can be conceptualized as knobs which specify exactly how the
connection will be executed. A bow connection must be told, for example, how much rosin is on the
bow, how fast to move the bow across the string, etc. Controllers can either be told to maintain a
constant value, or can be changed dynamically during the synthesis.
Returning to our workbench surface, we see a string, a pick, and a black box with a few knobs on it
and the label “pluck.” To finally connect them together we must specify where the objects will
physically interact. For instance, do we want to pluck the middle of the string or near the end? Do we
want to pluck with the small end of the pick or the large end? To specify a physical location on a
Modalys object so that it can interact with other objects, we make what is called an access. The above
instrument will require four accesses: one at the point on the string where we want to pluck, one on the
part of the pick which will touch the string, one on the part of the pick which we will move with our
“hand,” and another at the point in the string where we will put our microphone (Modalys instruments,
for the time being, can only be listened to using “contact microphones,” i.e., one can put one’s ear
anywhere on the instrument, but not in the air).
Imagine, having specified the last bit of information about our instrument, that we send it off to the
manufacturing department. It comes back as a large black box labeled “Plucked string instrument” with
a speaker, and several knobs which correspond to all of the controllers which we specified (“constant”
controllers can be thought of as knobs that are glued in one place). Hence we have built a basic
instrument, and made some basic choices about how it is to be played. Now we are left with the task
of actually making music with it. To play this particular instrument, we need to move the pick across the
string so that the two objects make contact. This can be achieved by turning the knob that moves the
large end of the pick (i.e., the part that one normally holds). The method by which the knob is turned
depends on the type of Modalys controller we used to make the knob. There are controller types which
can read MIDI data from a file, follow breakpoint envelopes, etc. (Modalys has an extremely powerful
control system; we will look at some complex control setups later.) Once we have specified all the
control information, we now have a complete Modalys synthesis: the instrument, the “instrumentalist,”
and the “performance.” Let us look more closely at the specific components of a Modalys synthesis.
Modalys and Its Interfaces
Connecting Modalys with various environments: Lisp, Max/MSP, Open Music and MatLab.
Modalys itself has always been a computation engine connected to an interface that allows the user a
flexible and high-level control of the instrument-building and designing environment. Initially, Modalys
used a text-based interface using the Scheme programming language. This allowed the programming
language itself to be used for useful mathematical calculations as well as more complex programming
routines, according to the user's needs, for a particular synthesis. Today, there are a variety of
interfaces you can use to access the Modalys computation engine: the text-based Lisp and MatLab
interfaces, as well as the graphical (box and connection) interfaces available using Open Music and
Max/MSP.
For the moment, this document concentrates on the Lisp interface, and will be expanded in the near
future to include information about its use with other interfaces.
Lisp Interface
This text-based interface is the successor to the original Scheme interface, albeit using the Lisp
programming language (a cousin of Scheme). To use this interface you simply need to run the
ModaLisp application and, using its built-in text editor, evaluate a Lisp-based Modalys script. Synthesis
of a script can optionally be run in real-time (depending on the complexity of the instrument), since the
program can receive external OSC messages via a user-defined IP port.
Max/MSP Interface
This interface lets you run a Modalys instrument in real-time using the modalys~ object in Max/MSP.
There are two ways that you can do this:
One way is to load a .mlys-format file describing the instrument into the modalys~ object. Mlys
files (with the extension .mlys) are text-files that can be generated by ModaLisp specifically for
this purpose, using the "Export as mlys..." command from the File menu. (Mlys files are text-
based and human-readable, so you could always tweak them by hand or use some other
method of generating them, if you really wanted to.) Generally Mlys files use dynamic
controllers instead of envelope controllers, so the synthesis can be controlled by Max messages
in real-time, taking advantage of the real-time message-processing capabilites of Max/MSP.
The other, somewhat more user-friendly, way to create Modalys instruments in Max/MSP is to
use a set of MLYS objects (whose name starts with "mlys.") connected to a mlys.script object
which itself is connected to the modalys~ object. These various higher-level objects graphically
describe the instrument and connections in an intuitive way and the mlys.script object
generates script commands for the modalys~ object which can synthesize the instrument.
Open Music Library
The Modalys Library for Open Music lets you use IRCAM's OM environment to design and synthesize
Modalys instruments. Since OM is based on Lisp, you can interact with Modalys in much the same way
that you can using the ModaLisp interface, albeit graphically, but also allowing you to use OM's
powerful computer-assisted composition tools for synthesis control.
MatLab Interface
The MatLab interface to Modalys is a set of MatLab objects that lets you write text-based Modalys
scripts within the MatLab numerical computing environment. The text-based format uses a C-like
syntax, and is comprised of the same Modalys functions that are available in the Lisp version. The
MatLab interface is particularly useful for researchers who would like to have access to the Modalys
engine directly within their computation working environment for scientific applications.
Modalys Documentation v. 3.3.1.rc2
Written by Richard Dudas - ©IRCAM 2013.
Modalys - Getting Started
Guide Map
Modalys Getting Started

Summary
An Introduction to Modalys Installing and Setting up Modalys on Your Computer
Getting Started
This section deals with helping you install Modalys on your computer, so you can access it in your
Objects
preferred interface environment.
Accesses
Connections Download the latest version of Modalys for Mac (.dmg archive) from IRCAM Forum.
Controllers Launch the installation package. Selecting the "Standard" installation is recommended.
Finite Elements
If you already have an /Applications/Modalys folder, don't worry, it will be renamed and backed-
up.
Appendix
Index For use with Max/MSP, OpenMusic or even with MatLab, follow the relevant instructions below.
Modalys components for these various environments are all found in

/Applications/Modalys/Components/.
NB: if you have some older setup for these environments, back up and then remove the corresponding
files before installing the new ones!
Authorizing Modalys
If this is the first time you are using Modalys, or if

you are upgrading from version 3.2 or older, you
will need to authorize Modalys with the activation
code sent by the IRCAM Forum server:
If not already done so, go to the Modalys

Download Page on the Forum website and
request your authorization key. You should
receive it by email almost instantly.
Launch the Modalys Authorization Tool from

/Applications/Modalys/ and then copy and
paste the authorization key (it’s a long,
cryptic text...)
That’s all folks !
ModaLisp
The ModaLisp application, found in /Applications/Modalys, is Modalys’s text-based Lisp interface.
ModaLisp is the primarily interface for learning Modalys and all examples in this documentation are
written in Lisp.
ModaLisp is based on LispWorks’ implementation of Common Lisp.

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/Getting_Started.html[28/05/13 14:38:21]
Modalys - Getting Started
You can find great resources on the web to learn Lisp, such as LispWorks’ Lisp Documentation and
Tutorials.
To get started, open and study the examples from /Applications/Modalys/Examples/Lisp.
Max/MSP Interface
To install the Max/MSP modalys~ object and MLYS instrument construction objects, you need to make
sure that they have been added to Max's search path.
Modalys objects for Max work with Max 5 and 6.
From the Components/Max folder, the simplest way to setup Modalys for Max is to copy the modalys
folder to {Max Application Folder}/Cycling '74/.
Alternatively, you can add this modalys folder manually to Max's search path, without copying/pasting.
A great place to get started with MLYS is Manuel Poletti’s free Forum Max Apps which include a great
deal of well-designed Modalys examples. And yes it is free !
Some further documentation about Max Modalys objects will soon be added, for instance as
comprehensive Max help files.
Open Music Library
To install the Modalys Library for Open Music, copy the Components/OpenMusic/Modalys 3.31/ folder
to {Open Music Application Folder}/libraries/.
Create a dedicated Modalys workspace and get started with the numerous and great Modalys
examples found in the Open Music tutorials.
MatLab Interface
Modalys for MatLab, obviously, is used for scientific research.
To install Modalys for MatLab, open MatLab and go to File Menu > Set Path, choose Add Folder and
then locate the MatLab folder inside Components. That’s it !
You can find a couple of MatLab examples in the Examples folder.
http://support.ircam.fr/docs/Modalys/current/co/Getting_Started.html[28/05/13 14:38:21]
Modalys - Objects
Guide Map
Modalys Objects
Summary
An Introduction to Modalys Objects - The Building Blocks of Modalys
Getting Started
An object is a simulated vibrating body which serves as the basic sound producing element in Modalys.
Objects
1. Object Properties Objects are internally described using a set of modal data (a set of frequencies, loss coefficients and
2. Object Reference modeshape description for each frequency). They therefore have a linear response to excitation – this
3. Object Utilities
means that if a string behaves a certain way when plucked 10 cm, then it will do the same thing,
exactly 100,000 times more, if you pluck it by 10 kilometers. Fortunately, Modalys objects are
4. Hybrid Objects
unbreakable, and need not be insured when taken on tour! (One can, however, obtain interesting
Accesses
nonlinear effects in Modalys using connections, which will be discussed later.) Objects are created in
Connections
slightly different ways, depending on the interface being used (Lisp, OM, Max/MSP, etc...), but the
Controllers
basic Modalys command that is used (in a text-based environment) is “make-object” followed by the
object type and a list of parameters.
Finite Elements
Appendix
Index (make-object object_type list_of_parameters)
As far as the user is concerned, an object can be considered to be the physical body which it
represents, even though there a few essential differences to be taken into consideration:
Modalys objects are linear models. Thus, for example, a rectangular plate object cannot be
broken no matter how hard it is struck.
Modalys objects only vibrate (or otherwise change position) in a limited number of
predetermined axes (either one, two or three, depending on the object type).
Some Modalys objects have “ideal” parameters which cannot exist in reality. The membrane
objects, for example, are just surfaces with tension, size and mass; their thickness is zero and
their density is infinity.
The physical parameters of Modalys objects are only used to calculate their vibrations. Thus,
two objects cannot collide or otherwise interact unless they are specifically told to do by the
user via the use of a connection.
The remainder of this section is devoted to the types of objects that Modalys can create (given a list of
physical parameters such as density, tension, etc...) Many objects share general parameters, but
specific information about each object's parameters, accesses, etc... is provided on the documentation
page for that object.
Objects interact with other Modalys items (such as controllers and connections) through accesses,
described in detail in the next section. For now, it is enough to know that an access is a point on a
Modalys object that allows it to communicate with other Modalys objects, and that different objects
have different access types, depending on how the objects vibrate. For example, a bi-string object can
be accessed in the 'trans0 (horizontal) and 'trans1 (vertical) directions, while an air column must be
accessed in the 'long (meaning longitudinal - across the length of the tube) direction. The available
access types for each object are also described in the following object description pages.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/Objects.html[28/05/13 14:39:09]
Modalys - Objects
We have subdivided this section into the following categories:
Object Properties
Object Reference
Object Utilities
Hybrid Objects
We suggest you first read the section on object properties in order to better understand some of the
object options presented in the subsequent reference section.
http://support.ircam.fr/docs/Modalys/current/co/Objects.html[28/05/13 14:39:09]
Modalys - Accesses
Guide Map
Modalys Accesses
Summary
An Introduction to Modalys Accesses - Points of Communication between Modalys Objects
Getting Started
Accesses in Modalys are the “ports” through which objects communicate with each other and with the
Objects
outside world. Every situation wherein information must be passed to or taken from an object requires
Accesses
an access. For example, if two objects are to be joined together by an 'adhere connection (connections
1. Standard Accesses will be discussed below), it is necessary to have one access on each object to be adhered to. An
2. Using Compiled Accesses important point in the understanding of Modalys accesses is that they have both a “physical” location
3. Hybrid Accesses on the object, and a direction, or axis, of movement. A 'bi-string object, for example, can be accessed
4. Tri-Hybrid Accesses in either of two transverse directions: 'trans0 and 'trans1. You can think of these as horizontal and
5. Get Access Info vertical, if it helps you mentally envision them. If we create an access near the midpoint of a 'bi-string,
Connections with a 'trans0 (horizontal) direction of movement, a diagram of the string and its access would look
Controllers something like the this:
Finite Elements
Appendix
Index
If we then create a second access at another point on the string with a 'trans1 (vertical) direction of
movement, our diagram becomes:
As the two accesses have different directions, they are completely independent and cannot in any way
effect each other. If, for example, we pluck the 'trans0 access and attach a speaker to the 'trans1
access, we will hear nothing (because there are no vibrations in the vertical direction), even though the
string is vibrating from side to side. In order to pluck a string and listen to the effect, we need two
accesses with the same direction: one for the interaction with the pick object, and one for the speaker:
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/Accesses.html[28/05/13 14:39:57]
Modalys - Accesses
Some interactions, like the 'bow interaction, require using both access directions; these kinds of bi-
directional interactions would cause the string to vibrate in both 'trans0 and 'trans1 directions. (For this
reason, we usually use a simpler 'mono-string model for 'pluck or 'strike interactions.)
Creating Accesses
Standard accesses are created by the function (make-access ... ) which takes the following Lisp
syntax:
(make-access object_reference location_on_object

direction_of_access)
The location of the access on the object is specified by a controller. This can be either a one
dimensional controller as in the case of a string; or it could be a two dimensional controller, specifying
an (x, y) location, as in the case of a rectangular plate. Objects that vibrate in three directions would
obviously need a three-dimensional controller (x,y,z).
The possible directions of access depend on the object being used. For example, a bi-string object can
be accessed in the 'trans0 (horizontal) and 'trans1 (vertical) directions, while an air column must be
accessed in the 'long (meaning longitudinal - across the length of the tube) direction. Specific
information about which accesses can be used for a given object can be found on the individual
Modalys objects' reference pages.
Accesses fall into the following topical categories:
Standard Accesses - details about the most commonly used generic “plain vanilla” access
Compiled Accesses - computation-saving accesses that are specific to plates and membranes
Hybrid Accesses - creating accesses specific to hybrid objects
Tri-Hybrid Accesses - creating accesses specific to tri-hybrid objects
Access Utilities
Get Access Info - obtaining access-specific data using the standard (get-info ... ) function.
http://support.ircam.fr/docs/Modalys/current/co/Accesses.html[28/05/13 14:39:57]
Modalys - Connections
Guide Map
Modalys Connections
Summary
An Introduction to Modalys Connections - Creating Interactions between Modalys Objects
Getting Started
Connections define interactions between Modalys objects. If you think of objects and their accesses as
Objects
nouns in Modalys grammar, connections are the verbs, since they create actions involving one or more
Accesses
accesses. Each connection performs a very specific task. An 'adhere connection, for example, assures
Connections
that two accesses always have the same speed.
1. Force Connection
Imagine the scenario of an access on a string adhered to an access on a bridge: as soon as the
2. Speed Connection
connection is made between the two objects, if the string is excited (presuming it vibrates in the same
3. Position Connection
direction as the access) the access will have a speed, which is immediately transferred to the bridge
4. Acoustic Hole Connection
access so that its speed becomes the same. Note that the 'adhere connection does not ensure that two
5. Adhere Connection
accesses will have the same position. If, for example, we told the string access that its position was
6. Strike Connection
suddenly 10 meters away, the 'adhere connection would not know the difference and thus would not
7. Pluck Connection
change the bridge’s position.
8. Spring Connection
9. Reed Connection Connections are created using the function make-connection which takes the following text-based (Lisp
10. Felt Hammer Connection
environment) syntax:
11. Mono-Fingerboard Connection

12. Normalised Valve Connection (make-connection connection-name access1 initial_position1
13. Normalised Leaky Valve ... controllers ... weight)
Connection
14. Bow Connection
15. Bi-Fingerboard Connection The number of accesses can vary – most connections take one or two accesses and their initial
16. Valve Connection positions; more complex interactions such as the bow interaction, may require more accesses and
17. Leaky Valve Connection positions as arguments. The number of controllers controlling the parameters of the interactions also
18. Induction Connection varies greatly among the connections - some connections do not require any controllers, others require
19. Labium Connection several controllers, or a multi-dimensional controller.
20. Destroy Connection
Modalys connections have an optional weight controller as a final argument. This allows the interaction
21. Get Connection Info to be “faded-in” or be allowed to interact only at some percentage of its normal “weight” (capacity). If a
Controllers weight controller is not provided as an argument, the weight defaults to 1, meaning the interaction will
The Modalys Workspace be weighted at 100%.
Finite Elements
Many Modalys connections (such as 'adhere, 'position, and 'force) are rather simple actions, However,
Appendix
there are connections which act as “black boxes” for more complicated interactions such as the that
Index
between a reed and an air column. Also, it is often through the connections that Modalys compensates
for non-linear interactions which are computationally too expensive or difficult to calculate. Things like
key noise for an acoustic tube are sometimes “faked” in isolation by a controller rather than actually
being calculated as a physical result of other stimuli.
Connections can be destroyed using (destroy-connection ... ).
The following pages contain the individual Modalys connection reference pages. The connections are
organized in categories ranging from basic to complex instead of being ordered alphabetically.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/Connections.html[28/05/13 14:41:32]
Modalys - Connections
Basic Unilateral Connections
These connections only affect one access/object:
Force Connection
Speed Connection
Position Connection
Acoustic Hole Connection
Strike Connection (this connection has a unilateral option)
Bilateral Connections
These connections take two accesses/objects to perform simple interactions:
Adhere Connection
Strike Connection
Pluck Connection
Spring Connection
Reed Connection
Felt Hammer Connection
Mono-Fingerboard Connection
Normalised Valve Connection
Normalised Leaky Valve Connection
Valve Connection (this connection has a bilateral option)
Leaky Valve Connection (this connection has a bilateral option)
Induction Connection
Complex Connections
These connections take multiple accesses/objects to perform complex interactions:
Bow Connection
Bi-Fingerboard Connection
Valve Connection
Leaky Valve Connection
Labium Connection
Connection Utilities
(destroy-connection ... )
(get-info 'connection ... )
http://support.ircam.fr/docs/Modalys/current/co/Connections.html[28/05/13 14:41:32]
Modalys - Controllers
Guide Map
Accesses Controllers
Connections
Controllers Controllers - Managing Modalys Objects, Accesses and Connections in Time
1. Constant Controller Any information in a Modalys synthesis which can be changed over time by the user is specified by
2. Envelope Controller controllers. This is very important to the modular construction of Modalys because, after having created
3. Access Speed Controller a complicated instrument, one can put the majority of detailed information in a “black box” and simply
4. Access Position Controller turn the knobs of certain controllers in order to make a sound. Controllers vary in dimension and
5. Access Force Controller “intelligence.” Single-dimension controllers are used to control a single value, whereas multi-
6. Connection State Controller dimensional controllers are needed to control more complex parameters, such as the (x, y) location of
7. Last Sample Controller an access on a plate, just to give one practical example.
8. Sound File Controller
There are two general categories of controllers in Modalys: constant and dynamic.
9. MIDI File Controller
10. Dynamic Controller Constant controllers are the simplest type of controller. They represent a “knob” or “slider” (or an array
11. Send Message of them) which remains in one fixed position (a constant value) throughout an entire synthesis. In some
12. Set Breakpoint
cases constant controllers can be replaced with single numerical values as arguments. Generally,
though, if a Modalys function calls for a controller, it is best to use a constant controller to set a fixed
13. Signal Controller
value for that controller. Some examples are shown on the constant controller's reference page.
14. Scale Controller
15. Arithmetic Controller Constant controllers are usually created with the following shorthand syntax:
16. Expression Controller
17. Foreign-Call Controller
(const value1 [value2 value3 ...])
18. Sine Controller
19. Random Controller
20. Band-Limited Noise Controller Dynamic controllers are those whose values change over time. They can be as basic as an envelope
21. Noise (Band-Limited Impulse) defining a breakpoint function whose (time, value) pairs are expressed as a list of lists, and more
Controller complex controllers can be those which read MIDI files, outputting several values (dimensions) at a
22. Delay Controller
time. Some controllers can also themselves be composed of (programming code) functions which look
23. Bilinear (First Order IIR) Filter at what is happening in the synthesis and make decisions about how its values should change.
24. Biquadratic (Second Order IIR)
Filter All controllers have the following (text-based) syntax in common:
25. Constant Second Order
(Bandpass) Filter
26. Variable Second Order (make-controller controller_type dimension ... )
(Bandpass) Filter
27. Dimension-Mapping Controller
28. Sum Controller The dimension value must be provided by the user, even if its value seems obvious. Specific
29. Spread Controller information on the subsequent arguments and parameters for each controller type is found on the
30. Get Controller Info controllers' reference pages, themselves.
Finite Elements
The following pages contain the individual Modalys controller reference pages. The controllers are
Appendix organized thematically in categories ranging roughly from basic to complex instead of being ordered
Index alphabetically.
Basic Controllers
The following are the most

©IRCAM basic and commonly used controllers:
2013
http://support.ircam.fr/docs/Modalys/current/co/Controllers.html[28/05/13 14:42:06]
Constant Controller
Envelope Controller
Modalys Environment Controllers
The following controllers get information from an access, interaction or other point from the Modalys
synthesis environment:
Access Speed Controller

Access Position Controller
Access Force Controller
Connection State Controller
Last Sample Controller (appears to be broken - does not cause errors, but outputs zero)
Controllers from Files

Run-Time and Real-Time Controllers

Dynamic Controller
Send Message (used with the Dynamic Controller)
Set Breakpoint (used with the Dynamic Controller) (semi-deprecated)
Signal Controller
Math and Programming Controllers

Scale Controller
Foreign Call Controller (only available in the Lisp interface to Modalys)
Signal Generator Controllers

Sine Controller
Random Controller (i.e. White Noise Controller)
Band-Limited Noise Controller
Noise Controller (i.e. Band-Limited Impulse Controller)
Delay and Filtering Controllers

Delay Controller
Bilinear Filter (First Order IIR Filter)
Biquadratic Filter (Second Order IIR FIlter)
Constant Bandpass Filter Controller (appears to be broken...)
Variable Bandpass Filter Controller
Managing Multi-Dimensional Controllers

Dimension-Mapping Controller
Sum Controller
Spread Controller
Controller Utilities
(get-info 'value ... ) - obtain the current value of a controller
Modalys - The Modalys Workspace
Guide Map
Modalys
Summary
Other Commands in the Modalys Workspace
Getting Started
Objects The Modalys Workspace is the environment in which Objects, Accesses, Connections and Controllers
Accesses are created. The workspace contains other important tools, such as those for getting audio in and out
Connections of the Modalys environment, running synthesis (when not using Modalys in a real-time environment
Controllers such as Max/MSP), and getting and setting other Modalys settings and options.
The most important tools in this category are probably the “make-point-output” and “make-point-input”
1. New Workspace functions. The former lets you acquire vibrations from an access in order to either output it in real-time,
2. Run Synthesis play it after non-real-time calculation or save it to disk as a sound file. The latter lets you send
3. Play Sound vibrations to an access via an input sound file or real-time input.
4. Set Message Level
Other workspace options include setting the sampling rate and bits of precision for the calculation,
5. Set Precision
setting the number of input and output channels (although this is by default done automatically
6. Run Synthesis in Real-Time
depending on the number of point-inputs and point-outputs), getting information from objects,
7. Listen to IP Port
accesses and connections within the workspace, setting the verbosity of messages Modalys reports
8. Set Angle Mode back to the user, and clearing the Modalys workspace to a default (empty) state.
9. Get Version
10. Stop Modalys Workspace Commands
11. Quit Modalys
The following are the basic and general-purpose workspace commands:
12. Point Output
13. Point Input New
14. Save AIFF Sound File Run Synthesis
15. Save Floating-Point Sound File Play
16. Set Sample Rate Set Message Level
17. Set Bit Depth Set Precision
18. Set Number of Channels Set Angle Mode
19. Get Workspace Info Get Version
20. Get Angle Mode
Stop
Quit
21. Make Plot
22. Plot Value
23. Plot Sound Related Commands
24. Load Modalys Script The following are commands relating to sound generation, input and output:
25. Load Modalys Component
Point Output
26. Save Mlys Script File
Point Input
27. MIDI to Frequency
Save AIFF FIle
28. Frequency to MIDI
Save Floating-Point File
Finite Elements
Set Sample Rate
Appendix
Set Bit Depth
Index Set Number of Channels
Real-Time Commands
The following commands are specific to running Modalys in real-time:

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/Workspace.html[28/05/13 14:42:41]
Modalys - The Modalys Workspace
Run in Real-Time
Listen to IP Port
Get Environment Information
The Get Info command is a basic function with a variety of commands that allow you to retrieve a vast
amount of information about all sorts of things in the workspace. The commands themselves do not
require their own individual pages, however, as they can each be explained simply. We have divided
the get-info command up into separate sections with items grouped according to category (object,
access, connection, controller, workspace). The workspace-related commands are explained here,
alongside other workspace-related information-obtaining commands.
Get Info
Get Angle Mode
Graphing Data with the Plot Command
The following commands can be used to plot controller data to a graph in an external window. This can
be useful to debug problematic syntheses, in addition to helping visualize parameters and their results.
(As an example, all of the graphs in the controllers section were plotted using this feature.)
Make Plot
Plot Value
Plot
Other Modalys File Functions
The following are commands relating to Modalys file input and output:
Load Modalys Script

Load Component
Save Mlys Script
General Utilities
These are other useful tools that are integrated into the environment:
MIDI to Frequency
Frequency to MIDI
http://support.ircam.fr/docs/Modalys/current/co/Workspace.html[28/05/13 14:42:41]
Modalys - Finite Elements
Guide Map
Modalys Finite Elements See also

Finite Element
Summary
An Introduction to Modalys Introduction
Getting Started
The Finite Elements object allows the definition of three-
Objects
dimensional objects in Modalys, using a mesh, which is then
Accesses
converted to modal data with the help of numerical methods.
Connections
Controllers Although the instantiation of the 'finite-element object itself is
The Modalys Workspace documented within the Object Reference, this section of the
Finite Elements
documentation will eventually be expanded to include the family
of functions that assist in the creation of these objects.
Appendix
Index For the moment, until the forthcoming update of the Modalys
documentation, we suggest you take a look at the Finite
Elements .pdf documentation from 2003, along with the various
examples which are included in the Modalys distribution.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/Finite_Elements.html[28/05/13 14:43:16]
Modalys - Appendix
Guide Map
Modalys Appendix
Summary
An Introduction to Modalys Obsolete Commands
Getting Started
Often new and improved features in Modalys make older features obsolete or redundant. This section
Objects
documents some older Modalys commands you might encounter in older Modalys text files. We do not
Accesses
suggest using these features, but rather these additional reference pages are provided to help you be
Connections
able to update old files to the new syntax, as appropriate.
Controllers
The Modalys Workspace Actually, I decided to document the obsolete commands in the relevant item's current page, since the
Finite Elements
commands themselves will be indexed.
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/Appendix.html[28/05/13 14:44:03]
Modalys - Index
Guide Map
Modalys Index
Summary
An Introduction to Modalys Function Index
Getting Started
An alphabetical index of Modalys functions. This list includes obsolete and deprecated functions which
Objects
have been linked to their current counterparts, as an aid to updating older scripts.
Accesses
Connections
A
Controllers
The Modalys Workspace (attach-mode-controllers ... )
Finite Elements
Appendix C
Index (const ... )
(freeze-object ... )
(freq-to-midi ... )
(get-angle-mode)
(get-info 'admittance ... )
(get-info 'energy ... )
(get-info 'force ... )
(get-info 'max-sample)
(get-info 'mode-frequency ... )
(get-info 'mode-loss ... )
(get-info 'mode-shape ... )
(get-info 'num-modes ... )
(get-info 'num-points ... )
(get-info 'num-outputs)
(get-info 'physical ... )
(get-info 'position ... )

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/Index.html[28/05/13 14:44:36]
Modalys - Index
(get-info 'sample-period)
(get-info 'sample-rate)
(get-info 'speed ... )
(get-info 'time)
(get-info 'value ... )
(get-version)
(listen-ip-port ... )
(load ... )
(load-component ... )
(make-access ... )
(make-connection 'adhere ... )
(make-connection 'bi-fingerboard ... )
(make-connection 'bow ... )
(make-connection 'felt ... )
(make-connection 'force ... )
(make-connection 'hole ... )
(make-connection 'labium ... )
(make-connection 'leaky-valve ... )
(make-connection 'mono-fingerboard ... )
(make-connection 'normalised-valve ... )
(make-connection 'normalised-leaky-valve ... )
(make-connection 'pluck ... )
(make-connection 'position ... )
(make-connection 'reed ... )
(make-connection 'speed ... )
(make-connection 'spring ... )
(make-connection 'strike ... )
(make-connection 'valve ... )
(make-controller 'access-force ... )
(make-controller 'access-position ... )
(make-controller 'access-speed ... )
(make-controller 'arithmetic ... )
(make-controller 'bandlimited-noise ... )
Modalys - Index
(make-controller 'bilinear-filter ... )
(make-controller 'biquadratic-filter ... )
(make-controller 'connection-state ... )
(make-controller 'constant ... )
(make-controller 'constant-second-order-filter ... )
(make-controller 'delay ... )
(make-controller 'dimension-mapping ... )
(make-controller 'dynamic ... )
(make-controller 'envelope ... )
(make-controller 'expression ... )
(make-controller 'foreign-call ... )
(make-controller 'last-sample ... )
(make-controller 'midi ... ) (obsolete older version of 'midi-file controller)
(make-controller 'midi-file ... )
(make-controller 'noise ... )
(make-controller 'osc ... )
(make-controller 'random ... )
(make-controller 'scale ... )
(make-controller 'scheme ... )
(make-controller 'signal ... )
(make-controller 'sine ... )
(make-controller 'sound-file ... )
(make-controller 'spread ... )
(make-controller 'sum ... )
(make-controller 'variable-second-order-filter ... )
(make-hybrid-access ... )
(make-object 'bi-string ... )
(make-object 'bi-two-mass ... )
(make-object 'cello-bridge ... )
(make-object 'circ-membrane ... )
(make-object 'clamped-circ-plate ... )
(make-object 'clone ... )
(make-object 'closed-closed-tube ... )
(make-object 'closed-open-tube ... )
(make-object 'finite-element ... )
(make-object 'free-circ-plate ... )
Modalys - Index
(make-object 'harmonic-oscillator ... )
(make-object 'jet ... )
(make-object 'mono-string ... )
(make-object 'mono-two-mass ... )
(make-object 'melt-hybrid ... )
(make-object 'mix-hybrid ... )
(make-object 'open-open-tube ... )
(make-object 'radiator ... )
(make-object 'read-from-file ... )
(make-object 'rect-free-bar ... )
(make-object 'rect-membrane ... )
(make-object 'rect-plate ... )
(make-object 'reson-model ... )
(make-object 'single-point ... )
(make-object 'tri-hybrid ... )
(make-object 'violin-bridge ... )
(make-plot)
(make-point-input ... )
(make-point-output ... )
(make-tri-hybrid-access ... )
(midi-to-freq ... )
(new)
Piano Soundboard
(play)
(plot ... )
(plot-value ... )
(quit)
(run ... )
(run-real-time ... )
Modalys - Index
(save-aiff ... )
(save-float ... )
(save-object ... )
(send-message ... )
(set-amplitude ... )
(set-angle-mode ... )
(set-bit-depth ... )
(set-breakpoint ... )
(set-frequency ... )
(set-loss ... )
(set-message-level ... )
(set-mode-freq ... )
(set-mode-freq! ... )
(set-mode-loss ... )
(set-mode-loss! ... )
(set-number-of-channels ... )
(set-pitch ... )
(set-precision ... )
(set-sample-rate ... )
(stop)
(unfreeze-object ... )
(vget ... )
(vset ... )
(with-compiled-accesses ... )
(with-pitch-adjustment ... )
Modalys - Object Properties
Guide Map
Modalys Object Properties

Summary
An Introduction to Modalys Introduction
Getting Started
Modalys objects are a collection of Mode Frequencies and Loss Coefficients for those frequencies, as
Objects
well as a collection of modeshape (deformation) data for those frequencies. All objects share this
1. Object Properties common internal data structure, even though their physical descriptions from a user's point of view
a. Common Parameters and may be vastly different. As far as the user is concerned, Modalys objects are defined using a
Properties for Modal Objects
combination of physical measurements, material parameters and modal parameters, all of which can
b. Material Properties for
vary depending on the object being created. Many Modalys objects share common parameters, which
Strings, Plates and
Membranes we will describe here in order to avoid repetition in the individual objects’ reference pages. Remember
c. Material Properties for that not all parameters apply to every object; the individual object reference pages will indicate which
Wooden Bars measurements and parameters can be used for that particular object.
2. Object Reference
3. Object Utilities
4. Hybrid Objects This section includes:
Accesses Common Parameters and Properties for Modal Objects
Connections Material Properties for Strings, Plates and Membranes
Controllers Material Properties for Wooden Bars
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/ObjectProperties.html[28/05/13 14:45:09]
Modalys - Common Parameters and Properties for Modal Objects
Guide Map
Modalys Common Parameters and Properties for Modal

Summary Objects
Getting Started Sommaire
Objects 1. Parameters and Properties
1. Object Properties 2. Modal Properties
a. Common Parameters and 3. Material Properties
Properties for Modal Objects 4. Physical Measurements
Strings, Plates and
Membranes
c. Material Properties for
Parameters and Properties
Wooden Bars
2. Object Reference Overview
3. Object Utilities Many Modalys objects share common parameters. Some objects may have parameters that
4. Hybrid Objects others do not (for example, plates have a thickness parameter, whereas membranes do not), and
Accesses some objects have parameters that are specific to the type of object that is being modeled (for
Connections example air-elasticity is specific to air columns in tubes, and will not be found in strings,
Controllers membranes and other objects).
The values of all physical parameters are controllers (either dynamic or constant). In the Lisp
Finite Elements
interface numerical values may be given as parameter values; these will be automatically
Appendix
converted into constant controllers by Modalys. If a given parameter is not supplied when using
Index
the Lisp syntax, the default parameter value will be used.
For the purposes of discussion, we are grouping the parameters into three general categories:
Modal Properties and Material Properties and Physical Measurements. Although all the physical
parameters of an object are used together to calculate a model which operates on a modal basis,
we are separating the parameters into these groups because, with very few exceptions, the modal
properties are common to all Modalys objects, whereas the physical properties and
measurements will vary greatly depending on the type and size of object being modeled.
Modal Properties
modes
This value determines the number of modes of vibration calculated in the simulation of the object.
As the number of modes is increased, higher partials are added to the resultant sound. Thus if
ten modes are used, the lowest ten frequencies produced by the vibration of the object are
computed. Maximum detail is obtained when the number of modes is high enough so that all
frequencies below the Nyquist frequency are accounted for. Most objects will have have a user-
definable number of modes, but some objects (such as the bi-two-mass) have a fixed number of
modes, in which case this option is not settable.
freq-loss and const-loss
These are©IRCAM
coefficients
2013which describe how the object loses energy. Freq-loss describes the
http://support.ircam.fr/docs/Modalys/current/co/object_properties_general.html[28/05/13 14:45:40]
decay of the sound proportionally to the square of the frequencies, whereas const-loss describes
the overall decay of all the object’s frequencies.
More specifically, each mode of the object loses energy in proportion to the following equation,
where ƒ is the frequency of the mode:
const-loss + freq-loss (ƒ/1000)2
If the two values are both zero, the object will resonate forever. If const-loss is non-zero and freq-
loss is zero, all modes will lose energy at the same rate. If freq-loss is non-zero, higher frequency
modes will lose energy more rapidly than lower ones. When saving modal data to a file (and
when reading it again), these two coefficients are combined as above to compute a specific loss
value for each mode. These two loss parameters are also part of the definition of the material
being modeled, as different materials lose energy at different rates. (Think of the difference
between a marimba, a vibraphone, and a lithophone - wood, metal and stone will have different
freq-loss and const-loss parameters to model how these different materials lose energy.)
Some objects (such as the bi-two-mass object) have separate freq-loss and const-loss
parameters for each of the object's vibrational directions.
In the simplest terms, const-loss affects overall decay/damping of the sound (whether it is
sustained or staccato), whereas freq-loss affects the perceived brightness of the resonating
sound as it decays.
Material Properties
density
The density of a material is measured in kg/m^3, and corresponds to mass per unit volume.
See chart of material properties for appropriate values.
young
The Young's modulus of a material (also sometimes referred to as tensile modulus or elastic
modulus) is measured in Pascals (N/m^2). It is a measure of the elasticity of a given material.
Higher values imply more stiffness (less elasticity) in the material, resulting in objects whose
mode frequencies have a more inharmonic relationship to one another. Some materials, such as
wood, will have a different Young's modulus on different axes (i.e. along the grain, radially to the
grain, and tangentially to the grain). Often, Young's modulus is measured in gigapascals (GPa),
where 1 GPa = 1.0e9 N/m^2. See the tables of material properties for appropriate values.
poisson
Poisson coefficient (or Poisson's ratio) represents the ratio of the change in physical volume
between two vibrating directions, in other words the degree to which a material bulges as it
shortens.
The coefficient is a value in the range of 0 to 0.5 for most common materials. Metals generally
have a Poisson's Ratio of around 0.3, and rocks and minerals around 0.25, wood in the range of
0.35 to 0.4, and fibers generally around 0.4. Incompressible materials (liquids, for example) are
considered to have a poisson's ratio of 0.5. Rubber generally has a high poisson's ratio,
approaching 0.5, and Cork is at the other end of the spectrum - around zero. See the tables of
material properties for appropriate values. Not all Modalys objects take this parameter into
consideration.
air-density
Density of the air in kg/m^3. On the planet earth at room temperature at sea level this is normally
1.2 See table of air properties at different temperatures (at sea level).
Density of Air at Sea Level
Temperature (deg. C) Air Density (kg/m^3)
-150 2.793
-100 1.980
-50 1.534
0 1.293
20 1.205
40 1.127
60 1.067
80 1.000
100 0.946
150 0.835
200 0.746
250 0.675
rho
This is another term for density or air-density that is used by some objects, and consequently
also given in kg/m^3. In Modalys it usually refers to the density of air or another sound
propagation medium, as opposed to the density parameter that describes the physical properties
of material.
air-elasticity
Elasticity of the air in m^2/kg. On the planet earth at room temperature at sea level this is
normally around 7.14e-6 to 7.21e-6. Modalys actually uses the very finely detailed measurement
7.2087658592848905e-6 as a default value, although this is simply given as 7.21e-6 in the object
reference pages.
celerity
This is another term for air-speed or the speed of sound in air that is used by some objects, given
in m/s. The speed of sound in air on earth at room temperature at sea level is usually around 340
m/s.
Physical Measurements
length, width, thickness, radius, tension, stiffness
The use of these parameters will vary from object to object. They are fairly self-explanitory and
are used to describe the physical dimensions and other measurements of the objects. Tension
usually will refer to strings and membranes, and stiffness to springs.
Length, width, thickness and radius are measured in meters, tension is measured in Newtons,
and stiffness (for springs) is measured in N/m.
Modalys - Material Properties for Strings, Plates and Membranes
Guide Map
Modalys Material Properties for Strings, Plates and

Summary Membranes
Getting Started Overview
Objects
This page provides a table of approximate density, Young's modulus and Poisson's ratio for some
1. Object Properties common natural and synthetic materials (solids, liquids, fibers) at room temperature, at sea level. Note
a. Common Parameters and that these values may vary depending on various factors such as temperature, atmospheric pressure,
alloy composition, etc...
Strings, Plates and Value ranges are given for some materials in cases where their physical composition may vary either
Membranes
due to variance in the natural formation of compounds or (as in the case of alloys and synthetic
Wooden Bars materials) due to their base ingredients being mixed in different proportions. Woods (which have their
2. Object Reference own page) and natural fibers, especially, can have physical properties which vary greatly depending on
3. Object Utilities the environmental conditions in their area of origin.
4. Hybrid Objects For definitions of density, Young's modulus and the poisson coefficient see the object properties page.
Accesses
Connections
Controllers Tables of Material Properties
Finite Elements Metals
Appendix Material Properties of Metals
Index
Material Density kg/m^3 Young N/m^2 poisson
Aluminium 2700 7.0e10 0.35
Bismuth 9780 3.2e10 0.38
Brass 8500 1.0e11 - 1.25e11 0.33
Bronze 7400 - 8900 9.6e10 - 1.2e11 0.34
Cesium 1930 1.7e9 0.3
Copper 8940 1.1e11 - 1.28e11 0.35
Gold 19300 7.9e10 0.43
Iridium 22560 5.2e11 0.26
Iron 7870 1.9e11 - 2.11e11 0.30
Lead 11340 1.6e10 0.43
Lithium 534 4.9e9 0.36

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_properties_material.html[28/05/13 14:46:15]
Magnesium 1740 4.3e10 0.29
Mercury 13600 2.85e10 (0.5)*
Nickel 8900 2.1e11 0.30
Osmium 22570 5.5e11 0.25
Platinum 21450 1.68e11 0.39
Silver 10500 8.3e10 0.37
Steel 7700 2.0e11 0.31
Tin 7310 4.7e10 0.35
Titanium 4540 1.2e11 0.34
Tungsten 19250 4.11e11 0.28
Zinc 7100 1.08e11 0.25
* incompressible materials such as liquids are considered to have a poisson ratio of 0.5
Minerals and Stone

Material Properties of Minerals and Stone
Arsenic 5700 8.0e9 -*
Diamond 3500 1.22e12 0.2
Granite 2700 1.0e10 - 7.0e10 0.1 - 0.3
Graphite 1400 - 2250 1.7e11 - 3.4e11 0.13
Limestone 2700 1.5e10 - 5.5e10 0.18 - 0.33
Marble 2560 - 2760 5.0e10 - 7.0e10 0.1 - 0.22
Quartz 2650 7.6e10 - 9.7e10 0.17
Sandstone 2000 1.0e9 - 2.0e10 0.21 - 0.38
Sapphire 3980 3.45e11 0.25 - 0.28
Shale 2500 1.0e9 - 7.0e10 0.2 - 0.4
Silicon 2330 1.3e11 - 1.88e11 0.36
Uranium 19100 2.08e11 0.23
*arsenic has a highly variable poisson ratio depending on the direction of stress
Fibers
Material Properties of Natural and Synthetic Fibers
Carbon Fiber 1400 8.9e11 - 1.3e12 0.25
Catgut 1300 5.5e9 - 6.5e9 -*
Flax Fiber 1450 5.0e10 - 7.0e10 0.4
Hemp Fiber 1480 3.0e10 - 8.0e10 0.4
Horse Hair 1200 - 1400 4.9e9 - 7.0e9 -*
Nylon 1150 - 1200 4.5e9 - 5.5e9 0.4
Silkworm Silk 1300 - 1380 5.0e9 - 6.0e9 0.4
Spider Silk 1300 2.0e9 - 5.0e9 0.4
* natural fibers without a measured poisson coefficient can be considered to have a value of 0.4
for this parameter
Other Materials
Material Properties of Other Natural and Synthetic Materials
Bone 1900 9.0e9 - 1.8e10 0.15
Carrot 1140 1.36e6 0.15 - 0.35
Concrete 1680 - 3000 3.0e10 - 5.0e10 0.1 - 0.2
Cork 200 - 250 2.0e7 0*
Glass 2300 6.2e10 - 8.1e10 0.2

(Borosilicate)
Glass (Soda-Lime) 2500 7.2e10 - 7.4e10 0.23
Ice 920 1.2e10 0.33
Marshmallow 370 2.9e4 -**
Olive Oil 920 1.35e9 (0.5)***
Rubber (hard) 1100 - 1200 1.0e7 - 2.3e9 0.48 - 0.5
Rubber (soft) 950 3.0e6 - 5.0e6 0.48 - 0.5
Seawater 1020 2.34e9 (0.5)***
Tooth Enamel 2900 8.3e10 0.28
Water 1000 2.15e9 (0.5)***
* cork can often have a negative poisson value
** no data available for marshmallow - we suggest a value near zero, similar to cork.
*** incompressible materials such as liquids are considered to have a poisson ratio of 0.5
Modalys - Material Properties for Wooden Bars
Guide Map
Modalys Material Properties for Wooden Bars

Summary
An Introduction to Modalys Overview
Getting Started
This page provides a table of material properties for different kinds of wood. Measurements for
Objects
Young's modulus along the grain, radially (perpendicular to the grain), and tangentially (depth) are
1. Object Properties given. Generally, the tangential measurement is not used for Modalys objects, but provided here out of
a. Common Parameters and interest. Many woods have a radial Young's modulus that is approximately a power of ten less than the
Young's modulus along the grain. Therefore, where a radial Young's modulus is not given, you can
approximate it by lowering the exponent one value and comparing it with measurements of similar
Strings, Plates and
Membranes woods.
Wooden Bars Water ice also has a different Young's modulus perpendicular to the crystallization, so its material
2. Object Reference properties are also provided in this list, even though it is not a wood!
3. Object Utilities The list of appropriate freq-loss and const-loss values for different types of wood will hopefully be
4. Hybrid Objects enlarged in the future. Although this is not a material property, it is an important factor in the way
Accesses certain types of wood behave when used as musical objects.
Connections
For definitions of density, Young's modulus and the loss coefficients see the object properties page.
Controllers
Finite Elements
Table of Material Properties for Wood
Appendix
Index Wood
Material Properties for Wood
density young young young

Wood freq-loss const-loss
kg/m^3 N/m^2 Radial Tangential
Ash 710 1.6e10 1.6e9 9.0e8 - -
Balsa 160 6.0e9 3.0e8 1.0e8 - -
Bamboo 300 - 400 1.4e10 - - - -
Beech 700 1.4e10 2.2e9 1.1e9 - -
Birch 670 1.6e10 1.1e9 6.0e8 - -
Cocobolo 1070 1.3e10 - - - -
Ebony 1010 1.8e10 - - - - -

1.9e10
Douglas Fir 530 1.6e10 1.1e9 8.0e8 - -
©IRCAM920
Ice (i.e. 2013 1.2e10 8.6e9 - - -
http://support.ircam.fr/docs/Modalys/current/co/object_properties_wood.html[28/05/13 14:46:50]
water)
Larch 590 1.2e10 - - - -
Mahogany 500 - 850 1.2e10 1.1e9 6.0e8 - -
African 540 - 550 1.2e10 9.3e8 - - - -

Mahogany 1.2e9
Maple 800 1.7e10 1.5e9 7.3e8 - -
European 640 1.0e10 2.2e9 - - -

Maple
Oak 600 - 900 1.1e10 - - - -
African 650 - 790 9.54e9 - - - 8.22e-6 6.22

Padouk 1.4e10
(Pterocarpus)
Pernambuco 970 - 2.0e10 - - - - -

1000 2.2e10
Pine 350 - 500 9.0e9 - - - -
Scots Pine 510 1.6e10 1.1e9 6.0e8 - -
Redwood 380 9.5e9 9.6e8 - - -
Rosewood 820 - 2.13e10 - 2.3e9 1.15e9 - -

1080 2.3e10
Brazilian 830 - 850 1.6e10 2.8e9 - 4.7e-6 25.79

Rosewood
(Pallisandre)
Indian 730 - 740 1.2e10 1.7e9 - - - -

Rosewood 2.2e9
Spruce 400 - 700 1.0e10 - 4.0e8 - 4.0e8 - - -

1.6e10 9.0e8 6.0e8
Canadian 450 1.1e10 - - - -

Spruce
Norway Spruce 460 1.5e10 9.3e8 - - -
Sitka Spruce 460 - 470 1.3e10 8.9e8 - - - -

1.3e9
Teak 650 - 980 1.3e10 - - - -
Walnut 490 - 630 1.1e10 1.2e9 6.0e8 - -
Modalys - Object Reference
Guide Map
Objects Object Reference

1. Object Properties
2. Object Reference
The following pages contain the individual Modalys object reference pages. The objects are organized
a. One-Mass - Mono-directional in categories ranging from basic to complex instead of being ordered alphabetically.
(Harmonic Oscillator)
b. Two-Mass - Mono-directional
Simple Mass-Spring Objects
c. Two-Mass - Bi-directional
d. String (or Rod) - Mono- These very basic general-purpose objects are commonly used as hammers, plectra, lips, bows, etc...
directional
e. String (or Rod) - Bi- Harmonic Oscillator - (a mono-directional One-Mass)
directional Two-Mass (mono-directional)
f. Tube - open/open Two-Mass (bi-directional)
g. Tube - closed/open
h. Tube - closed/closed
Strings and Rods
i. Rectangular Membrane -
String or Rod (mono-directional)
Fixed
j. Circular Membrane - Fixed String or Rod (bi-directional)
k. Rectangular Plate - Fixed

l. Circular Plate - Clamped Tubes (Air Columns)
m. Circular Plate - Free Open/Open Tube
n. Rectangular Free Bar Closed/Open Tube
o. Violin Bridge Closed/Closed Tube
p. Cello Bridge
q. Jet Object Membranes
r. Single Point Object Rectangular Membrane (fixed at the edges)
s. Radiator Object Circular Membrane (fixed at the edges)
t. Clone Object
u. Save Modal Object Plates
v. Read Modal Object Rectangular Plate (fixed at the edges)
w. Resonance Model Object Clamped Circular Plate (fixed at the edges)
x. Piano Soundboard Free Circular Plate (freely vibrating)
y. Finite Element
3. Object Utilities Bars (Wooden)
4. Hybrid Objects Free Rectangular Bar
Accesses
Connections String Instrument Bridge Models
Controllers Violin Bridge
The Modalys Workspace Cello Bridge
Finite Elements
Appendix
Nonlinear Models
Index
These are special objects that integrate nonlinear waveguide models into the Modalys environment.
They may use different physical parameters to describe them.
Jet
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/ObjectReference.html[28/05/13 14:47:23]
Modalys - Object Reference
Other Objects
These objects are not created using physical properties, but can be used as objects in the Modalys
environment.
Single-Point
Radiator
Clone
External Data Objects and FIle I/O
Object data can additionally be read from a data file created in Modalys or externally.
Save Object (not an object per se, but a utility for saving an object’s modal data to disk, this
also appears in the object utilities section)
Read From File
Resonance Model Object [this might seems to be a bit buggy]
Piano Soundboard (provided as a data file)
Finite Element Object
Modal objects can also be calculated from a user-defined 3-dimensional mesh.
Finite Element Object (a dedicated section to creating finite element objects is forthcoming)
http://support.ircam.fr/docs/Modalys/current/co/ObjectReference.html[28/05/13 14:47:23]
Modalys - One-Mass - Mono-directional (Harmonic Oscillator)
Guide Map
Objects One-Mass - Mono-directional See also
1. Object Properties (Harmonic Oscillator) Two-Mass - Mono-

directional
2. Object Reference
Two-Mass - Bi-
a. One-Mass - Mono-directional Description
directional
A simple and inexpensive mass and spring model that can
b. Two-Mass - Mono-directional Reed Connection
serve as lips, among other things. The harmonic oscillator
c. Two-Mass - Bi-directional Valve Connection
models a mass attached to a spring of a given stiffness, fixed at
d. String (or Rod) - Mono-
one end. The frequency of resonance of the object is given by Normalised Valve
directional
the formula 1/(2 pi) sqrt(stiffness / mass). Connection
e. String (or Rod) - Bi-
directional Leaky Valve
f. Tube - open/open Connection
Normalised Leaky
h. Tube - closed/closed Valve Connection
Fixed
j. Circular Membrane - Fixed
l. Circular Plate - Clamped
m. Circular Plate - Free
n. Rectangular Free Bar
o. Violin Bridge
(make-object 'harmonic-oscillator ... )
p. Cello Bridge
Lisp Syntax and Default Values
q. Jet Object
r. Single Point Object A 'harmonic-oscillator can be created using the following
s. Radiator Object Lisp syntax (the default values are shown for each of the
t. Clone Object physical parameters):
u. Save Modal Object
v. Read Modal Object (make-object 'harmonic-oscillator
w. Resonance Model Object
(mass .01)
x. Piano Soundboard
y. Finite Element (stiffness 15000)
3. Object Utilities
(freq-loss 100)
4. Hybrid Objects
Accesses (const-loss 10))
Connections
Controllers Parameters
All physical parameters can be numerical values or
Finite Elements
controllers.
Appendix
Index mass: The mass of the small mass in kg.
stiffness: The stiffness of the spring in the 'normal
direction.
freq-loss: The usual frequency loss parameter.
See the General
©IRCAM 2013Object Information for more info.
http://support.ircam.fr/docs/Modalys/current/co/object_mass_one_mono.html[28/05/13 14:47:55]
Modalys - One-Mass - Mono-directional (Harmonic Oscillator)
const-loss: The usual constant loss parameter.

See the General Object Information for more info..
As usual, the freq-loss and const-loss parameters control

the rate of decay of the sound. The higher they are, the
more damped the sound is.
Accesses
The 'harmonic-oscillator can be accessed in only one

direction: 'normal:
(make-access my-harmonic-
oscillator my-controller 'normal)
Options
Tuning
A harmonic-oscillator can be tuned to a specific pitch,

using the (set-pitch ... ) function, by adjusting one of the
following physical parameters:
'stiffness
'mass
For example:
(setq my-lips (make-object

'harmonic-oscillator
(mass 5e-3)
(stiffness 10)
(freq-loss 10)
(const-loss 1) ))
(set-pitch my-lips 'stiffness 220)
http://support.ircam.fr/docs/Modalys/current/co/object_mass_one_mono.html[28/05/13 14:47:55]
Modalys - Two-Mass - Mono-directional
Guide Map
Objects Two-Mass - Mono-directional See also

One-Mass - Mono-
directional (Harmonic
2. Object Reference Description Oscillator)
a. One-Mass - Mono-directional A simple bi-directional two-mass model that can serve as a Two-Mass - Bi-
hammer, plectrum, finger, etc. Generally the two-mass model directional
has a small mass and a large mass; the small one will be Strike Connection
"connected" to the object being excited, and the large one will
d. String (or Rod) - Mono- Pluck Connection
directional be manipulated by the user. This is similar to the bi-two-mass,
except that it only vibrates in the trans0 direction. It is therefore Reed Connection
directional more computationally efficient for single-direction interactions Bow Connection
f. Tube - open/open like plucking and striking objects.
Fixed
o. Violin Bridge
p. Cello Bridge
q. Jet Object (make-object 'mono-two-mass ... )
r. Single Point Object
s. Radiator Object Lisp Syntax and Default Values
t. Clone Object A 'mono-two-mass can be created using the following
u. Save Modal Object Lisp syntax (the default values are shown for each of the
v. Read Modal Object physical parameters):
x. Piano Soundboard
(make-object 'mono-two-mass
y. Finite Element
3. Object Utilities (small-mass .01)
4. Hybrid Objects
(large-mass .01)
Accesses
Connections (stiffness0 15000)
Controllers
(freq-loss0 100)
Finite Elements (const-loss0 0))
Appendix
Index Parameters

controllers.
small-mass: The mass of the small mass in kg.

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_mass_two_mono.html[28/05/13 14:48:27]
Modalys - Two-Mass - Mono-directional
large-mass: The mass of the large mass in kg.

stiffness0: The stiffness of the spring in the
'trans0 (horizontal) direction.
freq-loss0: The usual frequency loss parameter.
See the General Object Information for more info.
const-loss0: The usual constant loss parameter.
See the General Object Information for more info..
As always, the term horizontal used above is provided for

simplification.
Accesses
A 'bi-two-mass can be accessed only in its sole vibrational

direction: trans0.
(make-access my-mono-two-mass my-

controller 'trans0)
If the value of my-controller is 1, the access is on the

small mass. If my-controller is 0, the access is on the
large mass. (A value in-between takes a weighted
combination of the two points.)
Options
There are no special options for the mono-two-mass.
http://support.ircam.fr/docs/Modalys/current/co/object_mass_two_mono.html[28/05/13 14:48:27]
Modalys - Two-Mass - Bi-directional
Guide Map
Objects Two-Mass - Bi-directional See also

One-Mass - Mono-
2. Object Reference Description Oscillator)
a. One-Mass - Mono-directional A simple bi-directional two-mass model that can serve as a Two-Mass - Mono-
hammer, plectrum, finger, etc. Generally the two-mass model directional
has a small mass and a large mass; the small one will be Strike Connection
"connected" to the object being excited, and the large one will
d. String (or Rod) - Mono- Pluck Connection
directional be manipulated by the user. The two masses are connected by
a spring. Visualize a large coin on a table, with a small coin on Reed Connection
directional top, and a spring between them. The large coin can be moved Bow Connection
f. Tube - open/open in two directions ('trans0 and 'trans1), and the spring will cause
g. Tube - closed/open the small coin to follow.
Fixed
o. Violin Bridge
p. Cello Bridge
q. Jet Object
r. Single Point Object (make-object 'bi-two-mass ... )
s. Radiator Object
t. Clone Object Lisp Syntax and Default Values
u. Save Modal Object A 'bi-two-mass can be created using the following Lisp
v. Read Modal Object syntax (the default values are shown for each of the
w. Resonance Model Object physical parameters):
x. Piano Soundboard
y. Finite Element
(make-object 'bi-two-mass
3. Object Utilities
4. Hybrid Objects (small-mass .01)
Accesses
(large-mass .01)
Connections
Controllers (stiffness0 15000)
The Modalys Workspace (stiffness1 15000)
Finite Elements
(freq-loss0 100)
Appendix
Index (freq-loss1 100)
(const-loss0 0)
(const-loss1 0))
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_mass_two_bi.html[28/05/13 14:49:06]
Parameters

controllers.
small-mass: The mass of the small mass in kg.

large-mass: The mass of the large mass in kg.
'trans0 (horizontal) direction.
'trans1 (vertical) direction.
freq-loss0: The usual frequency loss parameter,
but this loss only affects the trans0 (horizontal)
direction of vibration.
freq-loss1: The usual frequency loss parameter,
but this loss only affects the trans1 (vertical)
const-loss0: The usual constant loss parameter,
but this loss only affects the trans0 (horizontal)
const-loss1:The usual constant loss parameter,
but this loss only affects the trans1 (vertical)
As always, the terms horizontal and vertical used above

are provided for simplification. This object has separate
const-loss and freq-loss parameters for each direction of
vibration. See the General Object Information section for a
discussion of these parameters.
Accesses
A 'bi-two-mass can be accessed in either of its two

directions: trans0 or trans1.
(make-access my-bi-two-mass my-

controller 'trans0)
If the value of my-controller is 1, the access is on the

small mass. If my-controller is 0, the access is on the
large mass. (A value in-between takes a weighted
combination of the two points.)
Options
Tuning
A bi-two-mass can be tuned to a specific pitch [in each of

its two vibrational directions], using the (set-pitch ...)
function, by adjusting one of the following physical
parameters:
'stiffness0
'stiffness1
'small-mass0
'small-mass1
'large-mass0
'large-mass1
For example:
(setq my-mass (make-object 'bi-

two-mass))
(set-pitch my-mass 'stiffness0

220)
Modalys - String (or Rod) - Mono-directional
Guide Map
Objects String (or Rod) - Mono- See also
1. Object Properties directional Common Parameters

and Properties for
2. Object Reference Modal Objects
Material Properties for
Any string or rod, fixed at its endpoints, that vibrates in one Strings, Plates and
transverse (side-to-side) direction. Membranes
String (or Rod) - Bi-
directional directional
e. String (or Rod) - Bi- Two-Mass - Mono-
f. Tube - open/open
Pluck Connection
h. Tube - closed/closed Envelope Controller
(make-object 'mono-string ... )
Fixed
l. Circular Plate - Clamped A 'mono-string can be created using the following Lisp
m. Circular Plate - Free syntax (the default values are shown for each of the
n. Rectangular Free Bar physical parameters):
o. Violin Bridge
p. Cello Bridge (make-object 'mono-string
q. Jet Object
(modes 40)
s. Radiator Object (length 1)

t. Clone Object
(tension 100)
v. Read Modal Object (density 1000)
(radius .001)
x. Piano Soundboard
y. Finite Element (young 1e9)
3. Object Utilities (freq-loss 1)
4. Hybrid Objects
(const-loss 1))
Accesses
Connections
The Modalys Workspace The arguments for the physical parameters can be either
Finite Elements numerical values or Modalys controllers (either dynamic or
Appendix constant). If a given parameter is not supplied when using
Index the Lisp syntax, the default parameter value will be used.
modes: number of modes.

length: in meters.
tension: in Newtons.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_string_mono.html[28/05/13 14:49:39]
density: in kg/m^3. See chart of material

properties for appropriate values.
radius: in meters.
young: Young's modulus, in N/m^2. See chart of
material properties for appropriate values.
freq-loss, const-loss: loss coefficients. See
General object information.
Accesses
A mono-string can be accessed in one dimension - the

trans0 dimension:
(make-access my-string my-

controller 'trans0)
This makes a side-to-side access at a point along the

length of my-string, specified by my-controller. The value
of my-controller must be between zero and one. (As the
string is "fixed" at its endpoints, the actual values 0 and 1
cannot be used.) For reasons of simplicity, we can
consider trans0 to be the horizontal direction, but this
side-to-side vibrational direction of the mono-string could
be connected to a different direction on another object
(such as the up-and-down direction of a bi-string), so the
trans0 label is a handy way of referring to this without
specifying an actual real-world spatial direction of
movement.
Mono-directional strings are, naturally, intended to be

used for interactions that have only one direction of
vibration, such as 'pluck, 'strike, 'felt, etc.... Although you
generally want to use a bi-string for a 'bow interaction,
you could alternately use two mono-strings, one to
represent the "horizontal" direction and the other to
represent the "vertical" direction.
Options
Controllers
The physical parameters can optionally be controllers

instead of numerical values. Therefore, it is possible to
modify the physical characteristics of an object, including
its pitch, during synthesis. The following example creates
a string which varies in length from 1 meter to 50 cm in 2
seconds:
(setq my-ctrl (make-controller

'envelope 1 '((0 1.0) (2 0.5)) ))
(make-object 'mono-string (length

my-ctrl))
Tuning
A mono-string can be tuned to a specific pitch, using the

(set-pitch ...) function, by adjusting one of the following
physical parameters:
'length
'tension
'density
'young
For example:
(setq my-string (make-object

'mono-string))
(set-pitch my-string 'length 330)
You could also use a controller to re-adjust the pitch

dynamically, however this is extremely costly in terms of
CPU usage, since the entire modal object must be re-
computed for every sample. The following example makes
a glissando from 220Hz to 440Hz over 2 seconds:

'mono-string))
(set-pitch my-string 'length

(make-controller 'envelope 1 '((0
220.) (2 440.)) ))
Because of the intense amount of calculation required to

compute an object based on a given pitch, hybrid objects
can be used as a far more efficient way of making a
continuous pitch change (glissando).
When using Modalys in real-time contexts, you can use

messages to change the pitch of an object, instead of
input signal controllers.
Example
The following example shows a basic use of a mono-

string with a pluck interaction.
;;;-*-Mode: Lisp; Package:

MODALYS -*-
;;; Modalys, simple plucked string

example
;;;----------------------------
-------------------------------
-----------
;;;
;;; clear the instrument-building

workspace :
(new)
;;;
;;; make objects :

'mono-string))
(setq my-plectrum (make-object

'mono-two-mass))
;;;
;;; make pluck connection :
(setq my-string-plk (make-access

my-string (const .6) 'trans0))
(setq my-plectrum-plk (make-

access my-plectrum (const 1)
'trans0))
(make-connection 'pluck my-

string-plk 0 my-plectrum-plk .1
(const 50))
;;;
;;; make position connection to

push plectrum :
(setq my-plectrum-mov (make-

access my-plectrum (const 0)
'trans0))
(make-connection 'position my-

plectrum-mov (make-controller
'envelope 1 '((0 0.1) (1 -1))))
;;;
;;; make listening point (i.e.

another access) on the string :
(setq my-string-out (make-access

(make-point-output my-string-out)
;;;
;;; run the synthesis and play the

sound :
(run 2)
(play)
Modalys - String (or Rod) - Bi-directional
Guide Map
Objects String (or Rod) - Bi- See also
1. Object Properties directional Common Parameters

and Properties for
2. Object Reference Modal Objects
Any string or rod, fixed at its endpoints, that vibrates in two Strings, Plates and
transverse directions (side-to-side, up-and-down). This is Membranes
generally used for bowed interactions. Two-Mass - Bi-
e. String (or Rod) - Bi- String (or Rod) - Mono-
f. Tube - open/open
Bow Connection
h. Tube - closed/closed Envelope Controller
Fixed
(make-object 'bi-string ... )
n. Rectangular Free Bar A 'bi-string can be created using the following Lisp syntax
o. Violin Bridge
(the default values are shown for each of the physical
parameters):
p. Cello Bridge
q. Jet Object
r. Single Point Object (make-object 'bi-string
s. Radiator Object
(modes 40)
t. Clone Object
u. Save Modal Object (length 1)
v. Read Modal Object
(tension 100)
x. Piano Soundboard (density 1000)
y. Finite Element (radius .001)
3. Object Utilities
(young 1e9)
4. Hybrid Objects
Accesses (freq-loss 1)
Connections
(const-loss 1))
Controllers
Parameters
Finite Elements
Appendix The arguments for the physical parameters can be either
Index numerical values or Modalys controllers (either dynamic or
constant). If a given parameter is not supplied when using

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_string_bi.html[28/05/13 14:50:12]
length: in meters.
radius: in meters.
Accesses
The bi-string can be accessed in either of its two

dimensions: 'trans0 (horizontal direction) or 'trans1
(vertical direction).
The following makes a side-to-side access at a point

along the length of my-string specified by my-controller.

controller 'trans0)
The following makes an up-and-down access at a point

along the length of my-string defined by my-controller.

controller 'trans1)
The value of my-controller must be between zero and

one. Note that, because the string is "fixed" at its
endpoints, the actual values 0 and 1 will not actually
access the vibrating part of the string.
The bi-string is intended for physical interactions which

require two directions of vibration: namely the 'bow
connection. The bi-string is basically just a double mono-
string, so you could alternately use two mono-strings, one
to represent the "horizontal" direction and the other to
represent the "vertical" direction. However, for simplicity
and efficiency you will generally want to use a 'bi-string.
Options
Controllers

a string which varies in length from 1 meter to 50 cm in 2
seconds:

'envelope 1 '((0 1.0) (2 0.5)) ))
(make-object 'mono-string (length

my-ctrl))
Tuning
A mono-string can be tuned to a specific pitch, using the

'length
'tension
'density
'young
For example:

'mono-string))
(set-pitch my-string 'length 330)


'mono-string))
(set-pitch my-string 'length

220.) (2 440.)) ))


Example
The following example shows a basic use of a bi-string

with a bow interaction.
;;;-*-Mode: Lisp; Package:
MODALYS -*-
;;; Modalys, simple bowed string

example
;;;----------------------------
-------------------------------
-----------
;;;
;;; clear the instrument-building

workspace :
(new)
;;;
;;; make bi-directional string and

bow :
(setq my-string (make-object 'bi-

string (length 0.5)))
(setq my-bow (make-object 'bi-

two-mass))
;;;
;;; make bowed connection :
(setq my-bow-h-bpt (make-access

my-bow 1 'trans0))
(setq my-bow-v-bpt (make-access

my-bow 1 'trans1))
(setq my-string-h-bpt (make-

access my-string .1 'trans0))
(setq my-string-v-bpt (make-

access my-string .1 'trans1))
(setq bc (make-connection 'bow
my-bow-v-bpt my-bow-h-
bpt .01
my-string-v-bpt my-
string-h-bpt 0
'(2 10 5 4)))
;;;
;;; push the bow (speed and

vertical position) :
(setq my-bow-h-mov (make-access

my-bow (const 0) 'trans0))
(setq my-bow-v-mov (make-access

my-bow (const 0) 'trans1))
(make-connection 'speed my-bow-h-

mov
(make-controller
'envelope 1 '((0 1) (1 2) (2 1))))

bow-v-mov
(make-controller
'envelope 1 '((0.0 0.010) (0.2 -
0.001) (1.5 -0.001) (3 0.010))))
;;;
;;; make output on horizontal

direction of string :
(make-point-output (make-access
;;;
;;; make samples and play sound :
(run 5)
(play)
Modalys - Tube - open/open
Guide Map
Objects Tube - open/open See also

2. Object Reference Description Tube - closed/open
a. One-Mass - Mono-directional Jet Object

A model of a column of air in an acoustic tube (either cylindrical
or conical) which is open at both ends. Acoustic Hole
Connection
Reed Connection
directional Labium Connection
directional
f. Tube - open/open
i. Rectangular Membrane - (make-object 'open-open-tube ... )
Fixed
j. Circular Membrane - Fixed Lisp Syntax and Default Values
A 'open-open-tube can be created using the following Lisp
syntax (the default values are shown for each of the
physical parameters):
o. Violin Bridge
p. Cello Bridge (make-object 'open-open-tube
q. Jet Object (modes 20)
s. Radiator Object
(length 1)
t. Clone Object (air-elasticity

u. Save Modal Object .00000721)
(air-density 1.2)
x. Piano Soundboard (radius0 .01)
y. Finite Element
(radius1 .01)
3. Object Utilities
4. Hybrid Objects (freq-loss 1)
Connections
Finite Elements
The arguments for the physical parameters can be either
numerical values or Modalys controllers (either dynamic or
Appendix
Index

length: in meters.
©IRCAM 2013
air-elasticity: in m^2/kg. On the planet earth at
http://support.ircam.fr/docs/Modalys/current/co/object_tube_open_open.html[28/05/13 14:50:45]
room temperature at sea level this is normally

7.21e-6.
air-density: in kg/m^3. On the planet earth at
room temperature at sea level this is normally 1.2.
radius0: in meters at one end of the tube.
radius1: in meters at the other end of the tube.
Accesses
An acoustic tube can be accessed only in its longitudinal

direction (across the length of the tube):
(make-access my-tube my-

controller 'long)
This makes a longitudinal access on my-tube at a point

along its length specified by my-controller. The value for
my-controller must be between zero and one.
Options
Controllers

a tube which varies in length from 1 meter to 50 cm in 2
seconds:

'envelope 1 '((0 1.0) (2 0.5)) ))
(make-object 'open-open-tube
(length my-ctrl))
Tuning
An acoustic tube can be tuned to a specific pitch, using

the (set-pitch ...) function, by adjusting just one physical
parameter:
'length
For example:
(setq my-tube (make-object 'open-

open-tube))
(set-pitch my-tube 'length 440)

(setq my-tube (make-object 'open-

open-tube))
(set-pitch my-tube 'length (make-

controller 'envelope 1 '((0 220.)
(2 440.)) ))


Modalys - Tube - closed/open
Guide Map
Objects Tube - closed/open See also

2. Object Reference Description Tube - open/open

or conical) which is sealed at one end and open at the other. Acoustic Hole
Connection
Reed Connection
directional
f. Tube - open/open
i. Rectangular Membrane - (make-object 'closed-open-tube ... )
Fixed
A 'closed-open-tube can be created using the following
Lisp syntax (the default values are shown for each of the
o. Violin Bridge
p. Cello Bridge (make-object 'closed-open-tube
s. Radiator Object
(length 1)

(air-density 1.2)
y. Finite Element
(radius1 .01)
3. Object Utilities
Connections
Finite Elements
Appendix
Index

length: in meters.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_tube_closed_open.html[28/05/13 14:51:16]

7.21e-6.
radius0: in meters at the closed end of the tube.
radius1: in meters at the open end of the tube.
Accesses

direction:

controller 'long)

Options
Controllers

seconds:

'envelope 1 '((0 1.0) (2 0.5)) ))
(make-object 'closed-open-tube
(length my-ctrl))
Tuning

parameter:
'length
For example:
(setq my-tube (make-object

'closed-open-tube))


'closed-open-tube))

(2 440.)) ))


Use as a Tone-Hole
A very small closed-open tube can be adhered to another

tube as an alternative to making a tone hole on a wind
instrument:
(modes 4)
(length 2e-3)
(radius0 5e-3)
(radius1 5e-3)
(freq-loss 10) )
This tone hole is adhered to a resonating air column (i.e.

another tube serving as the instrument itself) at the closed
end of the tube. Opening and closing the tone hole is
achieved by modifying the interaction weight of the adhere
connection itself. (A weight of 1 means the hole will be
open, a weight of 0 means it will be closed.
Modalys - Tube - closed/closed
Guide Map
Objects Tube - closed/closed See also

Tube - closed/open
2. Object Reference Description Tube - open/open

or conical) which is sealed at both ends. Acoustic Hole
Connection
Reed Connection
directional
f. Tube - open/open
i. Rectangular Membrane - (make-object 'closed-closed-tube ... )
Fixed
A 'closed-closed-tube can be created using the following
o. Violin Bridge
p. Cello Bridge (make-object 'closed-closed-tube
s. Radiator Object
(length 1)

(air-density 1.2)
y. Finite Element
(radius1 .01)
3. Object Utilities
Connections
Finite Elements
Appendix
Index

length: in meters.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_tube_closed_closed.html[28/05/13 14:51:50]

7.21e-6.
radius0: in meters at one end of the tube.
radius1: in meters at the other end of the tube.
Accesses

direction:

controller 'long)

Options
Controllers

seconds:

'envelope 1 '((0 1.0) (2 0.5)) ))
(make-object 'closed-closed-tube
(length my-ctrl))
Tuning

parameter:
'length
For example:

'closed-closed-tube))


'closed-closed-tube))

(2 440.)) ))


Modalys - Rectangular Membrane - Fixed
Guide Map
Objects Rectangular Membrane - See also
1. Object Properties Fixed Circular Membrane -

Fixed
2. Object Reference
Rectangular Plate -
Fixed
A rectangular membrane with a thickness of zero, fixed at the
b. Two-Mass - Mono-directional Circular Plate -
edges. Clamped
d. String (or Rod) - Mono- Circular Plate - Free
directional
directional Strike Connection
f. Tube - open/open
Felt Hammer
Connection
Fixed
o. Violin Bridge
p. Cello Bridge
q. Jet Object
(make-object 'rect-membrane ... )
s. Radiator Object Lisp Syntax and Default Values
t. Clone Object
A 'rect-membrane can be created using the following Lisp
x. Piano Soundboard
y. Finite Element (make-object 'rect-membrane
3. Object Utilities (modes 80)
4. Hybrid Objects
Accesses
(length0 .5)
Connections (length1 .5)

Controllers
(tension 1000)
Finite Elements (mass .1)
Appendix
(freq-loss 10)
Index
(const-loss 10))
Parameters
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_membrane_rect_fixed.html[28/05/13 14:52:21]


length0: length along the x-axis in meters.
length1: length along the y-axis in meters.
mass or surface-density: surface density in kg.
Note that, unlike other objects, the values for freq-loss

and const-loss default to 10 for this object.
Accesses
A rectangular membrane can be accessed in its z-

direction ('normal) from any point on its surface.
(make-access my-membrane my-2D-

controller 'normal)
This makes an up-and-down access (in the z direction) at

a point on the surface of my-membrane. The point is
defined by my-2D-controller where the first dimension is x
and the second is y (the membrane's corners being the
points (0, 0), (0, 1), (1, 0) and (1, 1)). For example, in
order to access the center of the plate we can say:
(make-access my-membrane (const

0.5 0.5) 'normal)
Options
Tuning
A rect-membrane can be tuned to a specific pitch, using

the (set-pitch ...) function, by adjusting one of the
'size
'tension
'mass
Note that for 'size, both the x and y dimensions are scaled
together proportionally in order to preserve the harmonic
relationships the membrane's mode frequencies.
(setq my-membrane (make-object

'rect-membrane))
(set-pitch my-membrane 'size

(const 110))
Modalys - Circular Membrane - Fixed
Guide Map
Objects Circular Membrane - Fixed See also

Rectangular Membrane
- Fixed
2. Object Reference Description
Circular Plate -
a. One-Mass - Mono-directional A circular membrane with zero thickness, fixed at its edged like Clamped
a drum head.
b. Two-Mass - Mono-directional Circular Plate - Free
c. Two-Mass - Bi-directional Rectangular Plate -
d. String (or Rod) - Mono- Fixed
directional
f. Tube - open/open
Felt Hammer
Connection
Set Angle Mode
Fixed Get Angle Mode
(make-object 'circ-membrane ... )
o. Violin Bridge Lisp Syntax and Default Values
p. Cello Bridge
q. Jet Object
A 'circ-membrane can be created using the following Lisp
s. Radiator Object
t. Clone Object
u. Save Modal Object (make-object 'circ-membrane
(modes 80)
x. Piano Soundboard (radius .5)
y. Finite Element
(tension 1000)
3. Object Utilities
4. Hybrid Objects (mass 0.25)
Accesses (freq-loss 1)
Connections
(const-loss 1))
Controllers
Finite Elements
Parameters
Appendix The arguments for the physical parameters can be either
Index numerical values or Modalys controllers (either dynamic or

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_membrane_circ_fixed.html[28/05/13 14:52:52]
Modalys - Circular Membrane - Fixed
radius: in meters.
mass or surface-density: surface density in
kilograms.
Accesses
A 'circ-membrane can be accessed only in its z-direction

('normal) from any point on its surface.
(make-access my-membrane my-2D-

controller 'normal)
The first dimension of my-2D-controller is a number

between zero and one which describes the distance from
the center of the membrane to the edge (zero is at the
center and 1 is at the edge). The second dimension
describes the angle (in degrees) of the radius in question.
If there is only one access, then, this dimension is of no
importance and can be left at zero. If the membrane has
several accesses, the angle is used to describe the
relationship between them.
(make-access1 my-membrane (const

0.25 0) 'normal)
(make-access2 my-membrane (const

0.75 90) 'normal)
Options
Tuning
A circ-membrane can be tuned to a specific pitch, using

'radius
'tension
'mass
For example:
(setq my-membrane (make-object

'circ-membrane))
(set-pitch my-membrane 'radius 55)
http://support.ircam.fr/docs/Modalys/current/co/object_membrane_circ_fixed.html[28/05/13 14:52:52]
Modalys - Rectangular Plate - Fixed
Guide Map
Objects Rectangular Plate - Fixed See also

Circular Plate -
Clamped
a. One-Mass - Mono-directional A rectangular plate fixed at its edges.
(Harmonic Oscillator) Rectangular Membrane
b. Two-Mass - Mono-directional - Fixed
c. Two-Mass - Bi-directional Circular Membrane -
d. String (or Rod) - Mono- Fixed
directional
f. Tube - open/open
Felt Hammer
Connection
Fixed
o. Violin Bridge
p. Cello Bridge
(make-object 'rect-plate ... )
q. Jet Object
r. Single Point Object Lisp Syntax and Default Values
s. Radiator Object
t. Clone Object
A 'rect-plate can be created using the following Lisp
x. Piano Soundboard (make-object 'rect-plate
y. Finite Element
(modes 80)
3. Object Utilities
4. Hybrid Objects (length0 .5)
Accesses
(length1 .5)
Connections
Controllers (thickness .01)
The Modalys Workspace (density 7800)
Finite Elements
(poisson 0.3)
Appendix
Index (young 2e11)
(freq-loss 10)
(const-loss 10))
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_plate_rect_fixed.html[28/05/13 14:53:24]
Parameters


length0: length along the x-axis in meters.
length1: length along the y-axis in meters.
thickness: in meters.
poisson: Poisson Coeffieient. Usually has a value
of 0.3. See general object information.

and const-loss default to 10 for this object.
Accesses
A rectangular plate can be accessed in its z-direction

(make-access my-plate my-2D-

controller 'normal)

a point on the surface of my-plate. The point is defined by
my-2D-controller where the first dimension is x and the
second is y (the plate's corners being the points (0, 0), (0,
1), (1, 0) and (1, 1)). For example, in order to access the
center of the plate we can say:
(make-access my-plate (const 0.5

0.5) 'normal)
Options
Tuning
A rect-plate can be tuned to a specific pitch, using the

'size
'thickness
'density
'young
relationships the plate's mode frequencies.
(setq my-plate (make-object

'rect-plate))
(set-pitch my-plate 'size (const

440))
Modalys - Circular Plate - Clamped
Guide Map
Objects Circular Plate - Clamped See also

2. Object Reference Description Rectangular Plate -
Fixed
a. One-Mass - Mono-directional A circular plate fixed at its edges.
(Harmonic Oscillator) Circular Membrane -
b. Two-Mass - Mono-directional Fixed
c. Two-Mass - Bi-directional Rectangular Membrane
d. String (or Rod) - Mono- - Fixed
directional
f. Tube - open/open
Felt Hammer
Connection
Set Angle Mode
Fixed Get Angle Mode
m. Circular Plate - Free (make-object 'clamped-circ-plate ... )
o. Violin Bridge
p. Cello Bridge A 'clamped-circ-plate can be created using the following
q. Jet Object Lisp syntax (the default values are shown for each of the
r. Single Point Object physical parameters):
s. Radiator Object
t. Clone Object
(make-object 'clamped-circ-plate
v. Read Modal Object (modes 80)
(radius .5)
x. Piano Soundboard
y. Finite Element (thickness .01)
3. Object Utilities (density 7800)
4. Hybrid Objects
(young 2e11)
Accesses
Connections (poisson 0.3)
Controllers
(freq-loss 1)
Finite Elements (const-loss 1))
Appendix
Index Parameters

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_plate_circ_fixed.html[28/05/13 14:53:57]

radius: in meters.
poisson: poisson ratio. See chart of material
Accesses
A 'clamped-circ-plate can be accessed in one dimension -

perpendicular to the plate (i.e. 'normal):

controller 'normal)

the center of the plate to the edge (zero is at the center
and 1 is at the edge). The second dimension describes
the angle (in degrees) of the radius in question. If there is
only one access, then, this dimension is of no importance
and can be left at zero. If the plate has several accesses,
the angle is used to describe the relationship between
them.
(make-access1 my-plate (const

0.25 0) 'normal)

0.75 90) 'normal)
Options
Tuning
A 'clamped-circ-plate can be tuned to a specific pitch,

using the (set-pitch ...) function, by adjusting one of the
'radius
'thickness
'density
'young
For example:

'clamped-circ-plate))
(set-pitch my-plate 'radius

(const 440))
Modalys - Circular Plate - Free
Guide Map
Objects Circular Plate - Free See also

Circular Plate -
Clamped
Rectangular Plate -
a. One-Mass - Mono-directional A circular plate unattached at its edges. Fixed
b. Two-Mass - Mono-directional Circular Membrane -
c. Two-Mass - Bi-directional Fixed
d. String (or Rod) - Mono- Rectangular Membrane
directional - Fixed
directional Rectangular Free Bar
f. Tube - open/open Strike Connection
Felt Hammer
h. Tube - closed/closed Connection
Set Angle Mode
Fixed
j. Circular Membrane - Fixed Get Angle Mode
m. Circular Plate - Free (make-object 'free-circ-plate ... )
o. Violin Bridge
p. Cello Bridge A 'free-circ-plate can be created using the following Lisp
q. Jet Object syntax (the default values are shown for each of the
s. Radiator Object
t. Clone Object
(make-object 'free-circ-plate
v. Read Modal Object (modes 80)
(radius .5)
x. Piano Soundboard
y. Finite Element (thickness .01)
3. Object Utilities (density 7800)
4. Hybrid Objects
(young 2e11)
Accesses
Connections (poisson .3)
Controllers
(freq-loss 1)
Finite Elements (const-loss 1))
Appendix
Index Parameters

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_plate_circ_free.html[28/05/13 14:54:29]

radius: in meters.
Accesses
A 'free-circ-plate can be accessed in one dimension -

perpendicular to the plate (i.e. 'normal):

controller 'normal)

the center of the plate to the edge (zero is at the center
and 1 is at the edge). The second dimension describes
the angle (in degrees) of the radius in question. If there is
only one access, then, this dimension is of no importance
and can be left at zero. If the plate has several accesses,
the angle is used to describe the relationship between
them.

0.25 0) 'normal)

0.75 90) 'normal)
Options
Tuning
A 'free-circ-plate can be tuned to a specific pitch, using

'radius
'thickness
'density
'young
For example:

'free-circ-plate))
(set-pitch my-plate 'radius

(const 440))
Modalys - Rectangular Free Bar
Guide Map
Objects Rectangular Free Bar See also

Wooden Bars
Rectangular Plate -
a. One-Mass - Mono-directional A model of a wooden rectangular bar unattached at its edges. Fixed
directional
directional
f. Tube - open/open
Fixed
(make-object 'rect-free-bar ... )
o. Violin Bridge Lisp Syntax and Default Values
p. Cello Bridge
A 'rect-free-bar can be created using the following Lisp
q. Jet Object
s. Radiator Object
t. Clone Object
u. Save Modal Object (make-object 'rect-free-bar
(modes 80)
x. Piano Soundboard (length .3)
y. Finite Element (width .05)
3. Object Utilities
4. Hybrid Objects
(thickness .01)
Accesses (density 550)

Connections
(young0 1.2e10)
Controllers
The Modalys Workspace (young1 1.2e10)
Finite Elements
(poisson .25)
Appendix
Index (freq-loss 8.22e-6)
(const-loss 6.22))
Parameters
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_bar_rect_free.html[28/05/13 14:55:01]

Unlike other Modalys objects, this object calculates the
optimal number of modes based on the other parameters,
so a modes parameter does not need to be provided. This
object defaults to 20 points in the x direction and 9 in the
z direction.

length: length along the y-axis in meters.
width: width along the x-axis in meters.
thickness: along the z-axis in meters.
properties for wood for some appropriate values.
young0: Young's modulus for the x direction
(width), in N/m^2. See chart of wood properties for
appropriate values.
young1: Young's modulus for the z direction
(thickness), in N/m^2. See chart of wood
poisson: poisson ratio. See chart of wood

and const-loss default to values corresponding to Padouk
(Pterocarpus) wood.
Accesses
A rectangular bar can be accessed in its z-direction

(make-access my-bar my-2D-

controller 'normal)

a point on the surface of my-plate. The point is defined by
my-2D-controller where the first dimension is x and the
second is y (the plate's corners being the points (0, 0), (0,
1), (1, 0) and (1, 1)). For example, in order to access the
center of the plate we can say:
(make-access my-bar (const 0.5

0.5) 'normal)
Options
Tuning
A rect-free-bar can be tuned to a specific pitch, using the

'length
'thickness
'density
relationships the plate's mode frequencies.
(setq my-bar (make-object 'rect-

free-bar))
(set-pitch my-bar 'length (const

220))
Adjusting the bar width does not greatly affect perceived

pitch, but may change the relative harmonicity of the bar.
Modalys - Violin Bridge
Guide Map
Objects Violin Bridge See also

Cello Bridge
2. Object Reference Description String (or Rod) - Mono-
directional
a. One-Mass - Mono-directional A basic violin bridge model.
(Harmonic Oscillator) String (or Rod) - Bi-
b. Two-Mass - Mono-directional directional
c. Two-Mass - Bi-directional Adhere Connection
directional
directional
f. Tube - open/open
Fixed
o. Violin Bridge
p. Cello Bridge
q. Jet Object (make-object 'violin-bridge ... )
s. Radiator Object
t. Clone Object A 'violin-bridge can be created using the following Lisp
u. Save Modal Object syntax (the default values are shown for each of the
v. Read Modal Object physical parameters):
x. Piano Soundboard
(make-object 'violin-bridge
y. Finite Element
3. Object Utilities (central-mass .00177)
4. Hybrid Objects (feet-mass .00038)
Accesses
Connections
(e-distance .013)
Controllers (a-distance .01625)

(h-distance .021)
Finite Elements
Appendix (b-distance .0065)
Index
(stiffness 1300000)
(freq-loss 10)
(const-loss 10))
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_bridge_violin.html[28/05/13 14:55:32]
Parameters

controllers.
central-mass: central mass of the bridge in kg.

feet-mass: masses at the base/feet of the bridge
in kg.
e-distance: distance from the central mass to the
feet masses in meters.
h-distance: distance from the string to the feet
masses in meters.
a-distance: distance from the center mass to the
edge at the feet in meters.
b-distance: distance from the center to the interior
of the feet in meters.
stiffness: stiffness of the spring between central
mass and feet.
The violin bridge has two axis of possible motion, both of

which are linked to the stiffness value: it can compress
(i.e., the central mass becomes in effect closer to the feet-
masses), and it can rotate from side to side (at right angle
with the strings). The bridge does not, however, move
forwards and backwards (i.e., longitudinally with the
strings).
Accesses
To access the feet of a violin bridge (to adhere it to an

instrument body, or make an output on it, for example),
the special access type 'base is used. -1 refers to the left
foot, and 1 refers to the right. (A number in between will
specify an access somewhere in the middle.)
(make-access my-violin-bridge
(const -1) 'base) ;;; left foot
(const 1) 'base) ;;; right foot
Note that these feet-accesses vibrate vertically. To attach

strings (or plates, if you want), to the top part of the
bridge, the access types 'top-vertical and 'top-horizontal
are used.
(const distance) 'top-horizontal)
(const distance) 'top-vertical)
In the case of a bi-string, one would normally use two

access (both 'trans0 and 'trans1) at a point on the string
attached to the two access directions on the bridge. The
value distance describes the distance (in meters) from the
center of the bridge to the access. Note that the any value
can be given for this variable; one could easily have a
bridge which is twelve kilometers long (attached to a very
large fiddle!).
Options
There are no special options for the Violin Bridge
Modalys - Cello Bridge
Guide Map
Objects Cello Bridge See also

Violin Bridge
2. Object Reference Description String (or Rod) - Mono-
directional
a. One-Mass - Mono-directional A basic cello bridge model.
(Harmonic Oscillator) String (or Rod) - Bi-
b. Two-Mass - Mono-directional directional
c. Two-Mass - Bi-directional Adhere Connection
directional
directional
f. Tube - open/open
Fixed
o. Violin Bridge
p. Cello Bridge
q. Jet Object
s. Radiator Object
t. Clone Object
(make-object 'cello-bridge ... )
x. Piano Soundboard A 'cello-bridge can be created using the following Lisp
y. Finite Element syntax (the default values are shown for each of the
3. Object Utilities
4. Hybrid Objects
Accesses (make-object 'cello-bridge
Connections
(m1-mass .0046)
Controllers
The Modalys Workspace (m2-mass .0059)
Finite Elements
(m12-mass .0024)
Appendix
Index (d-distance .032)
(d20-distance .011)
(h1-distance .052)
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_bridge_cello.html[28/05/13 14:56:04]
(a-distance .035)
(i20-distance .026)
(d2-stiffness 716.8)
(s1-stiffness 360000)
(freq-loss 10)
(const-loss 10))
Parameters

controllers.
m1-mass: central mass of the bridge in kg

m2-mass: masses at the upper part of the bridge
in kg
m12-mass: masses at the base/feet of the bridge
in kg
d-distance: distance from the string to the central
mass in meters
d20-distance: distance from the central mass to
the upper mass in meters
h1-distance: distance from the central mass to
the feet in meters
a-distance: distance from the center to the edge
of the bridge (i.e. half the total bridge width) in
meters
i20-distance: distance from the center to the
upper masses on either side of the bridge in
meters
d2-stiffness: stiffness of the central mass spring
s1-stiffness: stiffness from the central mass to
the feet
Accesses
To access the feet of a cello bridge (to adhere it to an

instrument body, or make an output on it, for example),
the special access type 'base is used. -1 refers to the left
foot, and 1 refers to the right. (A number in-between will
specify an access somewhere in the middle.)
(make-access my-cello-bridge
(const -1) 'base) ;;; left foot
(const 1) 'base) ;;; right foot
Note that these feet are vertically vibrating accesses. To

attach strings (or plates, if you want), to the top part of the
bridge, the access types 'top-vertical and 'top-horizontal
are used.
(const distance) 'top-horizontal)
(const distance) 'top-vertical)
In the case of a bi-string, one would normally use two

access (both 'trans0 and 'trans1) at a point on the string
attached to the two access directions on the bridge. The
value distance describes the distance (in meters) from the
center of the bridge to the access. Note that the any value
can be given for this variable; one could easily have a
bridge which is twelve kilometers long (attached to a very
large cello!).
Options
There are no special options for the Cello Bridge
Modalys - Jet Object
Guide Map
Objects Jet Object See also

Labium Connection
2. Object Reference Description Tube - closed/open
a. One-Mass - Mono-directional Common Parameters

Simulates a wind jet created by a flue in a fipple. It can be used
(Harmonic Oscillator) and Properties for
with the 'labium connection to create an oscillating air vortex
b. Two-Mass - Mono-directional Modal Objects
that excites an air column in a tube to produce a recorder/flute
model.
directional
directional
f. Tube - open/open
Fixed
m. Circular Plate - Free (make-object 'jet ... )
o. Violin Bridge
p. Cello Bridge A 'jet object can be created using the following Lisp
q. Jet Object syntax (the default values are shown for each of the
s. Radiator Object
t. Clone Object
(make-object 'jet
v. Read Modal Object (pressure 1.0)
w. Resonance Model Object (air-density 1.2)
x. Piano Soundboard
(air-speed 340)
y. Finite Element
3. Object Utilities (length 0.03)
4. Hybrid Objects
(width .02)
Accesses
Connections (height .001)
Controllers (flue-labium-distance
The Modalys Workspace .004)
Finite Elements
(labium-position 2e-4)
Appendix
Index (mouth-surface 8e-5))
Parameters
The parameters
©IRCAM for 2013
this object are a little different from
http://support.ircam.fr/docs/Modalys/current/co/object_jet.html[28/05/13 14:56:36]
regular objects:
pressure: pressure controller for the jet.

air-density: medium density of sound radiation in
the propagating medium (kg/m^3).
air-speed / celerity: swiftness/speed of the sound
in the propagating medium (m/s).
length: length of the flue for the jet formation
width: width of the flue
height: height of the flue
flue-labium-distance: distance from the end of
the flue to the labium
labium-position: position of the labium with
respect to the flue
mouth-surface: this is set to 8e-5 by default and
does not need to be changed
To simulate propagation in air (room temperature at sea

level), you should use an air density value of 1.2 kg/m^3
(this parameter is sometimes called rho), and the speed of
sound in air, 340 m/s, for air-speed (celerity can be used
instead of air-speed for this parameter). The final mouth-
surface controller has been documented for completeness
but does not need to be provided.
Discussion
The jet object is a special object in Modalys because it

implements a nonlinear waveguide model, researched
and created by Marc Pierre Verge for his doctoral thesis,
instead of the usual modal description model.
Consequently it is used is a slightly special way in the
Modalys environment.
The fipple is the the mouthpiece of a whistle, recorder or

other simple flute that generates a jet for sound
production. The flue, sometimes also called a duct or
“windway,” focuses a jet of air onto the sharp labium -
also known as a blade or “windcutter.” The labium itself
causes this jet to break into a vortex or whirlpool of air
which oscillates back and forth across the labium. The
image, above, shows the anatomy of a fipple, with several
of its components that relate to this model clearly labeled.
Accesses
The jet is a special object in that it is generally used

directly by the 'labium connection, without an access.
In theory you can create accesses at three places on the

jet object:
'foot
'flue-exit
'labium
However, for the moment we suggest just using the jet
with the 'labium connection, as shown in the simple

example script, below:
(setq breath-env (make-controller

'envelope 1 '((0 0) (0.1 100) (1
100) (1.1 0))))
(setq jet (make-object 'jet

(pressure breath-env)))
(setq tube (make-object 'closed-

open-tube))
(setq tube-acc (make-access tube

(const 0) 'long))
(make-connection 'labium tube-acc

jet (const 0) (const 4.99 .1 1)
(const 0.005))
(setq tube-out (make-access tube

(const .9) 'long))
(make-point-output tube-out)
Options
There are no specific options for this object, other than its
parameters.
Modalys - Single Point Object
Guide Map
Objects Single Point Object See also

Resonance Model
Object
a. One-Mass - Mono-directional A Modalys object without physical properties which can
nonetheless be represented in space and can vibrate in one
dimension.
directional
directional
f. Tube - open/open
Fixed
j. Circular Membrane - Fixed (make-object 'single-point ... )
l. Circular Plate - Clamped Lisp Syntax and Default Values
A 'single-point object can be created using the following
Lisp syntax:
o. Violin Bridge
p. Cello Bridge
q. Jet Object (make-object 'single-point
r. Single Point Object (freqs '(440.))
s. Radiator Object
(bws '(10.))
t. Clone Object
u. Save Modal Object (amps '(1.)))
w. Resonance Model Object Parameters
x. Piano Soundboard
The 'single-point object does not have any physical
y. Finite Element
properties, but takes three parameter lists to set its
3. Object Utilities
frequency data directly:
4. Hybrid Objects
Accesses freqs: A list of frequencies (in Hz) to be assigned
Connections to the modes frequencies.
Controllers bws: A list of bandwidths (in Hz) to be assigned to
The Modalys Workspace the modes loss coefficients.
Finite Elements
amps: A list of amplitudes (in linear scale) to be
assigned to the amplitude of the unique point in
Appendix
the modes shape vector.
Index
Note: The three lists provided for the freq bw and amp
parameters must have the same length. If different
lengths are used, the lists are truncated to the length of
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_point_single.html[28/05/13 14:57:08]
the shortest list. A null list in any parameter will not be

accepted and an error message will be displayed.
Multi-dimensional controllers may also be used in place of

the lists to dynamically control the point's resonance
parameters.
Discussion
As we learned in the "Introduction to the Physics of

Modalys" section found in the introductory part of this
documentation, modal representation is directly related to
the spectral components, and thus also to the human
perception, of the synthesized signal. 'single-point objects
are virtual objects which don't have any physical property
(as mass or density) but have a spatial representation as
a single point which can vibrate in one dimension. 'single-
point objects are defined by their spectral components
(frequency of resonance, bandwidth, amplitude) and are
therefore important for bringing in Modalys a convergence
between signal models and physical models - as 'single-
point behave exactly as any other Modalys physical
object.
It is important for the user to know that the modal loss

coefficient for this object is set directly using the given
resonance bandwidth, thereby giving the modal
representation a straightforward connection between the
signal and physics domains. (Although bandwidths and
modal loss coefficients are not exactly the same thing,
they do function similarly where damping of resonances is
concerned, so the bandwidth parameter can be used
directly in this context.)
Accesses
A 'single-point object can be only accessed in the 'normal

direction:
(make-access my-single-point my-

controller 'normal)
As a 'single-point object does not have spatial

information, my-controller should be a constant between 0
and 1. In fact, any position (even a time-varying) can be
used, but it will not influence the object motion. The
position controller is necessary for keeping compatibility
with other Modalys objects.
Options
Tuning
Since a single-point object is defined directly from
frequency, bandwidth and amplitude data, its pitch is set

automatically based on the frequency data it is given. A
single-point with a 5-partial harmonic spectrum can
therefore be created this way:
(make-object 'single-point
(freqs '(220 440 660 880

1100))
(bws '(8. 4. 2. 1. 0.5))
(amps '(1. 0.866 0.707

0.612 0.5)) )
Modalys - Radiator Object
Guide Map
Objects Radiator Object See also

Single Point Object
a. One-Mass - Mono-directional The radiator object simulates the impedance loss resulting from
the emission of a sound wave out of a pulsating spherical cap.
directional (make-object 'radiator ... )
directional Lisp Syntax and Default Values
f. Tube - open/open
A 'radiator object can be created using the following Lisp
syntax:
Fixed (make-object 'radiator
k. Rectangular Plate - Fixed (radius .01)
l. Circular Plate - Clamped (angle 0)
(rho 1.2)
o. Violin Bridge (celerity 340))

p. Cello Bridge
q. Jet Object Parameters
The parameters for this object are a little different from
s. Radiator Object
regular objects:
t. Clone Object
u. Save Modal Object radius: in meters.
v. Read Modal Object angle: aperture angle in degrees.
w. Resonance Model Object rho: medium density of sound radiation in the
x. Piano Soundboard propagating medium (kg/m^3).
y. Finite Element celerity: swiftness/speed of the sound in the
3. Object Utilities propagating medium (m/s).
4. Hybrid Objects
For this object, you can control the radius of the sphere,
Accesses the aperture angle, the medium density and the celerity of
Connections sound in that propagating medium. To simulate
Controllers propagation in air (room temperature at sea level), you
The Modalys Workspace should use an air density value of 1.2 kg/m^3 for rho, and
Finite Elements the speed of sound in air, 340 m/s, for celerity.
Appendix
Index Accesses
A radiator can be accessed only in the 'normal direction:
©IRCAM 2013 my-radiator (const

(make-access
http://support.ircam.fr/docs/Modalys/current/co/object_radiator.html[28/05/13 14:57:39]
Modalys - Radiator Object
1) 'normal)
As with the single-point object, the access location

controller should be set to a constant value such as 1,
since this object has no spatial properties.
The 'radiator object is designed to be adhered to an

access which will be used as a point-output, and the
radiator's access used instead of the access on the
vibrating object. Here is a basic example:
(setq my-resonator (make-object

'mono-string))
(setq resonator-out (make-access

my-resonator (const .695)
'trans0))
(setq my-radiator (make-object

'radiator (angle 90) (radius 3e-
2)))
(setq radiator-acc (make-access

my-radiator (const 1) 'normal))
(make-connection 'adhere
resonator-out radiator-acc)
(make-point-output radiator-acc)
Options
There are no specific options for this object, other than its
parameters.
http://support.ircam.fr/docs/Modalys/current/co/object_radiator.html[28/05/13 14:57:39]
Modalys - Clone Object
Guide Map
Objects Clone Object

a. One-Mass - Mono-directional Creates a copy of an object which shares that object's modal data.
b. Two-Mass - Mono-directional Clones provide a good way to save memory in situations where several objects are needed with
c. Two-Mass - Bi-directional identical physical characteristics. (They also save the time it takes to compute extra copies of the same
d. String (or Rod) - Mono- modal data, which can be considerable if objects with many modes are involved.)
directional
directional
f. Tube - open/open (make-object 'clone ... )
i. Rectangular Membrane - The 'clone can be created using the following Lisp syntax:
Fixed
k. Rectangular Plate - Fixed (make-object 'clone object_reference)
m. Circular Plate - Free Parameters
The 'clone object does not have any physical parameters, but takes one argument:
o. Violin Bridge
p. Cello Bridge object_reference: name of an object whose modal data will be shared by the clone.
q. Jet Object
Since the clone object must use another object's data, its parameters are fixed to those of the
object. No alterations are possible. Also, note that you cannot clone a hybrid object.
s. Radiator Object
t. Clone Object Accesses
The access direction of a clone (i.e. 'trans0, 'normal, 'long, etc...) will be the same as that of the
parent object that is being cloned.
x. Piano Soundboard
y. Finite Element
3. Object Utilities
Options
4. Hybrid Objects
Accesses There are no special options for this object.
Connections
Controllers See Also
The Modalys Workspace Modalys Tutorial Example [examples coming soon!]
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_clone.html[28/05/13 14:58:10]
Modalys - Save Modal Object
Guide Map
Objects Save Modal Object See also

Read Modal Object
a. One-Mass - Mono-directional Saves an object's modal data in a file.
(save-object ... )
directional
e. String (or Rod) - Bi- Lisp Syntax and Default Values
directional
The (save-object ... ) function can be called using the
f. Tube - open/open
following Lisp syntax:
i. Rectangular Membrane - (save-object name_of_object
Fixed file_name )
Parameters
m. Circular Plate - Free The save-object function takes two arguments:
name_of_object: name of the object whose
o. Violin Bridge
modal data is to be saved.
p. Cello Bridge file_name: name of destination file (in quotes).
q. Jet Object
Discussion
s. Radiator Object
t. Clone Object Almost any object created in Modalys can be saved using
u. Save Modal Object save-object (although note that hybrids cannot be saved).
This can save a lot of time if the object has a lot of modes
because these files take a long time to compute. After an
object is saved, it can be retrieved using (make-object
x. Piano Soundboard
'read-from-file ...) When an object is retrieved, it is treated
y. Finite Element
exactly the same as if it had been freshly calculated.
3. Object Utilities
4. Hybrid Objects
Accesses
Options
Connections
Controllers
There are no special options for this function.
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_file_save.html[28/05/13 14:58:41]
Modalys - Read Modal Object
Guide Map
Objects Read Modal Object See also

Save Modal Object
2. Object Reference Description Piano Soundboard
a. One-Mass - Mono-directional Standard Accesses

Creates an object from modal data stored in a file. This could
be using modal data saved with the Modalys (save-object ...)
function, or to retrieve a modal data file produced by some
other source, such as an analysis or another program.
directional
directional (make-object 'read-from-file ... )
f. Tube - open/open
g. Tube - closed/open Lisp Syntax and Default Values
The 'read-from-file object can be created using the
Fixed
(make-object 'read-from-file
l. Circular Plate - Clamped file_name )
Parameters
o. Violin Bridge
p. Cello Bridge The 'read-from-file object takes one argument:
q. Jet Object file_name: name of modal data file in quotes (i.e.,
r. Single Point Object "my-saved-membrane").
s. Radiator Object
t. Clone Object The 'read-from-file object is generally used to recover
objects which were stored using save-object. In this case,
the object can be accessed exactly as it was before it was
saved. (If, for, example, you saved a mono-string and
then read it back, you would access it with a number
x. Piano Soundboard
between zero and one followed by the symbol 'trans0.)
y. Finite Element
3. Object Utilities
Discussion and Accesses
4. Hybrid Objects
Accesses The other possible reason for using 'read-from-file is to
Connections retrieve a modal data file produced by some other source,
Controllers such as an analysis or another program. In this case,
Modalys generally has no way of knowing what shape the
object is, and thus it is necessary to use 'decoded
Finite Elements
accesses. For example, if there was a modal analysis file
Appendix
for a cello body which had two physical points in the
Index
analysis, you would do:
(setq my-cello (make-object

©IRCAM 2013
'read-from-file "cello-body"))
http://support.ircam.fr/docs/Modalys/current/co/object_file_read.html[28/05/13 14:59:12]
Modalys - Read Modal Object
(setq my-cello-ac1 (make-access

my-cello (const 0 1) 'decoded)
(setq my-cello-ac2 (make-access

my-cello (const 1 0) 'decoded)
For more information on 'decoded accesses, see the entry

for (make access ... ).
Options
There are no special options for this object.
http://support.ircam.fr/docs/Modalys/current/co/object_file_read.html[28/05/13 14:59:12]
Modalys - Resonance Model Object
Guide Map
Objects Resonance Model Object See also

Single Point Object
a. One-Mass - Mono-directional Returns a 'single-point object whose modes frequencies, loss
coefficients and amplitude vector are set to the values of a
model of resonance defined in a plain text file.
directional
e. String (or Rod) - Bi- (make-object 'reson-model ... )
directional
f. Tube - open/open Lisp Syntax and Default Values
A 'reson-model object can be created using the following
Lisp syntax:
Fixed
(make-object 'reson-model
reson_file_name)
Parameters
o. Violin Bridge The 'reson-model object is a single point and
p. Cello Bridge consequently does not have any physical properties, but
q. Jet Object takes a text file from which it reads frequency data
directly:
s. Radiator Object reson_file_name: A character string containing

t. Clone Object the name of a model of resonance file.
To specify the path address of the file, you have to follow
the syntax rules of your operating system. As there is no
default value for the file name, a "wrong number of
x. Piano Soundboard
arguments" error will be displayed if a resonance file
y. Finite Element
name is not provided. Relative file paths (i.e. not absolute
3. Object Utilities
paths, which start with the root directory) are relative to
4. Hybrid Objects
the Modlays application, and must be given as a character
Accesses string - in double quotes as in the following example:
Connections
Controllers
The Modalys Workspace (make-object 'reson-model
Finite Elements
"Examples/analysis/resonance/rclotmi.txt")
Appendix
Index Accesses
A 'reson-model object can be only accessed in the

'normal direction:
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_point_modres.html[28/05/13 14:59:43]
Modalys - Resonance Model Object
(make-access my-reson-model my-

controller 'normal)
Since a 'reson-model object does not have spatial

information, my-controller should be a constant between 0
and 1. In fact, any position (even a time-varying position)
can be used, but it will not influence the object motion.
The position controller is necessary for keeping
compatibility with other Modalys objects.
Options
Resonance Model File Format
The model of resonance file must be a plain text file with

the ".txt" extension and has to be written with one set of
resonance data per line, with values separated by tabs or
spaces, in the following format:
<index> <freq> <amp> <bandwidth>
For example:
1 4.65239 -55.16879 .2261643
2 16.21073 -66.87767 .5535431
3 19.23595 -67.9138 .06310855
4 20.29903 -47.72019 .4553944
5 24.42205 -55.92316 .1438602
The frequencies and bandwidths must be in Hz. The

amplitudes must have a linear scale representation.
As with Modalys scripts, lines beginning with a semi-colon

are used for comments and ignored.
This format is the standard text-based format for IRCAM's

modres analysis. Analyses saved to .sdif files should be
converted to a text file representation.
http://support.ircam.fr/docs/Modalys/current/co/object_point_modres.html[28/05/13 14:59:43]
Modalys - Piano Soundboard
Guide Map
Objects Piano Soundboard See also

Read Modal Object
a. One-Mass - Mono-directional The piano-soundboard object is based on measurements of a
real piano made by Philippe Derogis for his PhD thesis at
IRCAM.
d. String (or Rod) - Mono- The geometrical characteristics of a piano soundboard include:
directional
e. String (or Rod) - Bi- - the mesh of the soundboard itself (13 x 13 points)
directional - trimming rims (creating nodal lines)
f. Tube - open/open - bridges
Fixed
o. Violin Bridge
p. Cello Bridge
q. Jet Object
s. Radiator Object
t. Clone Object
x. Piano Soundboard piano-soundboard.dat / piano-
y. Finite Element soundboard2.dat
3. Object Utilities
4. Hybrid Objects Lisp Syntax and Default Values
Accesses This object is in the form of fixed modal data, and must be
Connections created using the Read from File object (choosing one of
Controllers two available piano soundboard models):
Finite Elements
Appendix
"/mos/mod-anal/piano-
Index
soundboard.dat")
or:
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_soundboard_piano.html[28/05/13 15:00:14]
Modalys - Piano Soundboard
"/mos/mod-anal/piano-
soundboard2.dat")
Parameters
Both the piano-soundboard and piano-soundboard2

objects were created from measurements of actual piano
soundboards. Therefore, it is impossible to modify their
physical parameters.
Accesses
A piano-soundboard object is seen by Modalys as a

specific type of rectangular plate. Therefore, accesses on
a piano-soundboard object must be defined in the 'normal
direction:
(make-access my-sndbrd my-2D-

controller 'normal)
Options
There are no special options for this object.
Examples
See example ex2-piano-soundboard.mos (struck string

attached to the soundboard) and ex2-piano-
soundboard-2.mos (two struck strings attached to the
soundboard and tuned very close to each other) for
further details.
http://support.ircam.fr/docs/Modalys/current/co/object_soundboard_piano.html[28/05/13 15:00:14]
Modalys - Finite Element
Guide Map
Objects Finite Element See also

Finite Elements
a. One-Mass - Mono-directional This function is used to create a finite element object whose
sound properties depend on the user-defined geometry (mesh),
material parameters (density, young's modulus , poisson ration,
loss parameters) and boundary conditions (the fixed part of the
directional mesh). The dynamic behavior of this object is defined using
e. String (or Rod) - Bi- modal theory. The number of modes generated can be
directional specified by the user.
f. Tube - open/open
Finite Element objects will be discussed in their own
(forthcoming) section in this new Modalys documentation. For
the moment, please refer to the existing Finite element .pdf
Fixed documentation from 2003.
o. Violin Bridge
p. Cello Bridge
q. Jet Object
s. Radiator Object
t. Clone Object
x. Piano Soundboard
y. Finite Element
3. Object Utilities
4. Hybrid Objects
Accesses
Connections
Controllers
Finite Elements
Appendix
Index
(make-object 'finite-element ... )

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_finite_element.html[28/05/13 15:00:46]
A 'finite-element object can be created using the following

(make-object 'finite-element
(mesh my-mesh)
(block my-sub-mesh)
(modes 40)
(density 7800)
(young 2e11)
(poisson .3)
(freq-loss 1)
(const-loss 1))
Parameters

Unlike other Modalys objects, this object calculates the
optimal number of modes based on the other parameters,
so a modes parameter does not need to be provided. This
object defaults to 20 points in the x direction and 9 in the
z direction.
mesh: The mesh defining the geometry of the

finite element object.
block: The part of the mesh to be constrained
(fixed).
properties for some appropriate values.
young: Young's modulus in N/m^2. See chart of
The mesh can be obtained using the function (make-

mesh ... ) and the related Modalys mesh tools (duplicate
... ) and (transform ... ). Creating meshes for use with the
finite-element object is discussed in detail in a separate
section.
The block, or constrained part of the mesh, is the part of

the mesh that is fixed (immobile) during sound synthesis.
The dynamic behavior of an object (and thus its sound)
can be completely different depending on the definition of
this fixed topology. (To make an analogy, compare the
vibration and output sounds of the standard Modalys

objects: free-circ-plate and a clamped-circ-plate.
Nonetheless, this sub mesh is also discussed in further
detail in the section dedicated to finite-element objects.
The other parameters relate to standard Modalys material

and modal properties.
Accesses
A finite-element object can be accessed in any of three

directions:
'normal
'trans0
'trans1
You can think of these as corresponding to the z-axis, x-

axis and y-axis, respectively.
This is further discussed in the section on finite element

objects.
Options
All options regarding the finite element objects will be

discussed in their own (forthcoming) section in this
documentation.
Modalys - Object Utilities
Guide Map
Modalys Object Utilities

Summary
The following object-specific utilities are not objects themselves, but are closely related to the object-
Getting Started
creation part of the program.
Objects
1. Object Properties Set Pitch - set an object's to sound at a given pitch
2. Object Reference Set Mode Freq - set a given mode of an object to a specified frequency
3. Object Utilities
Set Mode Loss - set the loss coefficient of a given mode of an object
Attach Mode Controllers - [currently broken, although the individual commands, below are
a. Set Object Pitch
working]
b. Set Mode Freq
Set Frequency - set the frequencies of all of an object's modes
c. Set Mode Loss
Set Loss - set the loss coefficients of all of an object's modes
d. Attach Mode Controllers
Set Amplitude - scale the relative amplitudes of all of an object's modes
e. Set Frequency (of All Modes) Get Object Info - obtain object-specific information using the standard (get-info ... ) function.
f. Set Loss (of All Modes) Freeze Object - freeze an object and cause it to lose all energy
g. Set Amplitude (of All Modes) Unfreeze Object - unfreeze a frozen object
h. Get Object Info Save Object - save an object to a (text format) modal data file
i. Freeze Object
j. Unfreeze Object
k. Save Modal Object
4. Hybrid Objects
Accesses
Connections
Controllers
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/ObjectUtilities.html[28/05/13 15:01:17]
Modalys - Set Object Pitch
Guide Map
Modalys Set Object Pitch See also

Get Object Information
Summary
An Introduction to Modalys Description Set Mode Freq
Getting Started Set Frequency (of All
This allows the pitch of an object to be adjusted by modifying a
Objects Modes)
particular physical parameter.
2. Object Reference
3. Object Utilities (set-pitch ... )
a. Set Object Pitch
b. Set Mode Freq Lisp Syntax and Default Values
c. Set Mode Loss
The (set-pitch ... ) function can be called using the
d. Attach Mode Controllers following Lisp syntax:
e. Set Frequency (of All Modes)
f. Set Loss (of All Modes)
g. Set Amplitude (of All Modes) (set-pitch object_reference
h. Get Object Info
parameter_string value)
i. Freeze Object
j. Unfreeze Object or:
4. Hybrid Objects
Accesses (set-pitch object_reference
Connections
parameter_string controller)
Controllers
The Modalys Workspace Parameters
Finite Elements The (set pitch ... ) function requires the following
Appendix arguments:
Index
object_reference: name of the object on which
the access will be located.
parameter_string: the physical parameter which
will be modified to tune the object.
value, controller: a numerical value or a Modalys
controller used to determine the pitch (in Hz).
Discussion
The parameter string will depend on the object being

modified. Refer to the object's reference page for a list of
which parameters can be adjusted for that object. A list of
some of the commonly used possible parameter strings is
as follows:
'density
'length
'mass
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_pitch_set.html[28/05/13 15:01:48]
Modalys - Set Object Pitch
'radius
'size
'stiffness
'tension
'thickness
'young
Options
Retro-Compatibility
Modalys also has an older syntax for pitch adjustment:
(with-pitch-adjustment
parameter_string value
object_reference)
Although this older syntax is still available for reasons of

compatibility (it basically does the same thing without the
convenience of optionally using a controller), it has been
deprecated and its use is therefore discouraged.
http://support.ircam.fr/docs/Modalys/current/co/object_pitch_set.html[28/05/13 15:01:48]
Modalys - Set Mode Freq
Guide Map
Modalys Set Mode Freq See also

Set Mode Loss
Summary
An Introduction to Modalys Description Set Frequency (of All
Getting Started
Modes)
This allows the pitch of an individual mode to be altered
Objects Set Loss (of All Modes)
dynamically.
1. Object Properties Set Amplitude (of All
2. Object Reference Modes)
3. Object Utilities (set-mode-freq ... ) Attach Mode
a. Set Object Pitch Controllers
b. Set Mode Freq Lisp Syntax and Default Values Set Object Pitch
c. Set Mode Loss Get Object Information
The (set-mode-freq ... ) function can be called using the
g. Set Amplitude (of All Modes) (set-mode-freq object_reference
h. Get Object Info
mode_number value)
i. Freeze Object
4. Hybrid Objects
Accesses (set-mode-freq object_reference
Connections
mode_number controller)
Controllers
Finite Elements The (set-mode-freq ... ) function requires three
Appendix arguments:
Index
object_reference: name of the object whose
specified mode frequency will be controlled.
mode_number: the mode number whose pitch will
be altered (starting from mode 0)
controller used to determine the pitch of the given
mode(in Hz).
The mode-number must lie between zero and the number

of modes in the object minus one.
Discussion
This function is used to set the frequency of a mode to a

new value. The following example shows how you can
use (get-info 'mode-frequency ... ) to obtain the frequency
of a given mode, and then scale it dynamically using (set-
mode-freq©IRCAM
... ): 2013
http://support.ircam.fr/docs/Modalys/current/co/object_mode_freq_setone.html[28/05/13 15:02:20]
Modalys - Set Mode Freq
(setq orig-freq-mode0 (get-info

'mode-frequency my-string 0))
(setq freq-env-mode0 (make-

controller 'envelope 1
(list (list 0 orig-

freq-mode0)
(list 1 (* 1.9
orig-freq-mode0))
(list 2 orig-
freq-mode0))))
(set-mode-freq my-string 0 freq-

env-mode0)
It is also possible to set the mode frequency with (set-info

... ), but in this case the frequency can only be static, not
dynamic, as you can't use a controller for this function:
(set-info 'mode-frequency my-

string 1 800)
This function is not yet implemented for Hybrids; an error

message will be displayed if object is of hybrid type.
Options
Retro-Compatibility
Modalys also has an older syntax for this function:
(set-mode-freq! object_reference
mode_number value)
The older function basically did the same thing without the
convenience of optionally using a controller), so any older
Modalys scripts using it should be updated to use the new
syntax (without the exclamation point).
http://support.ircam.fr/docs/Modalys/current/co/object_mode_freq_setone.html[28/05/13 15:02:20]
Modalys - Set Mode Loss
Guide Map
Modalys Set Mode Loss See also

Set Mode Freq
Summary
An Introduction to Modalys Description Set Frequency (of All
Getting Started
Modes)
This allows the loss coefficient of an individual mode to be
Objects Set Loss (of All Modes)
altered dynamically.
3. Object Utilities (set-mode-loss ... ) Attach Mode
The (set-mode-loss ... ) function can be called using the
g. Set Amplitude (of All Modes) (set-mode-loss object_reference
h. Get Object Info
mode_number value)
i. Freeze Object
4. Hybrid Objects
Accesses (set-mode-loss object_reference
Connections
mode_number controller)
Controllers
Finite Elements The (set-mode-loss ... ) function requires three
Appendix arguments:
Index
specified mode's loss coefficient will be modified.
mode_number: the mode number whose loss
coefficient will be altered (starting from mode 0)
controller used to determine the loss coefficient of
the given mode.

Discussion
This function is used to set the loss coefficient of a mode

to a new value. The following example shows how you
can use (get-info 'mode-loss ... ) to obtain the loss
coefficient of a given mode, and then scale it dynamically
using (set-mode-loss
©IRCAM 2013 ... ):
http://support.ircam.fr/docs/Modalys/current/co/object_mode_loss_setone.html[28/05/13 15:02:51]
Modalys - Set Mode Loss
(setq orig-loss-mode0 (get-info

'mode-loss my-string 0))
(setq loss-env-mode0 (make-

controller 'envelope 1
(list (list 0 orig-

loss-mode0)
(list 1 (* 0.5
orig-loss-mode0))
(list 2 orig-
loss-mode0))))
(set-mode-loss my-string 0 loss-

env-mode0)

Options
Retro-Compatibility
(set-mode-loss! object_reference
mode_number value)
See Also
convenience of optionally using a controller), so any older
Modalys scripts using it should be updated to use the new
syntax (without the exclamation point).
http://support.ircam.fr/docs/Modalys/current/co/object_mode_loss_setone.html[28/05/13 15:02:51]
Modalys - Attach Mode Controllers
Guide Map
Modalys Attach Mode Controllers See also

Set Mode Freq
Summary
An Introduction to Modalys Description Set Mode Loss
This allows the modes of a given object to be dynamically
Objects Modes)
altered in frequency, loss, and amplitude.
1. Object Properties Set Loss (of All Modes)
2. Object Reference [However, this seems to be broken, currently....]
Set Amplitude (of All
3. Object Utilities Modes)
a. Set Object Pitch Set Object Pitch
b. Set Mode Freq
(attach-mode-controllers ... )
c. Set Mode Loss
e. Set Frequency (of All Modes) The (attach-mode-controllers ... ) function can be called
using the following Lisp syntax:
g. Set Amplitude (of All Modes)

h. Get Object Info (attach-mode-controllers object_reference
i. Freeze Object
(list (list mode-number0 freq-cont0 loss-cont0 amp-
j. Unfreeze Object
cont0)
4. Hybrid Objects (list mode-number1 freq-cont1 loss-cont1 amp-
Accesses cont1)
Connections . . . ))
Controllers
Finite Elements
The (attach-mode-controllers ... ) function takes the
Appendix
following arguments:
Index
mode_numberN: the mode number whose loss
coefficient will be altered (starting from mode 0)
freq_contN: frequency controller for mode N
loss_contN: loss coefficient controller for mode N
amp_contN: amplitude controller for mode N

Each mode whose parameters you want to control should

have a list containing the mode number followed by one
to three controllers. All of these lists are grouped into one
single list as the second argument to the function. [If you
don't want to attach a controller to a given parameter you
can use the constant #f instead of a controller.]
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_mode_controllers.html[28/05/13 15:03:23]
Modalys - Attach Mode Controllers
Discussion
This function seems to currently be broken. It causes no

errors, but has no effect on the object.

Options
Retro-Compatibility
(attach-controller ... )
See Also
convenience of the additional amplitude controller), so any
older Modalys scripts using it should be updated to use
the new syntax.
http://support.ircam.fr/docs/Modalys/current/co/object_mode_controllers.html[28/05/13 15:03:23]
Modalys - Set Frequency (of All Modes)
Guide Map
Modalys Set Frequency (of All Modes) See also

Set Mode Freq
Summary
Getting Started Set Loss (of All Modes)
This allows the frequency of all the modes of an object to be
Objects Set Amplitude (of All
altered dynamically.
1. Object Properties Modes)
2. Object Reference Attach Mode
3. Object Utilities (set-frequency ... ) Controllers
c. Set Mode Loss
The (set-frequency ... ) function can be called using the
g. Set Amplitude (of All Modes) (set-frequency object_reference
h. Get Object Info
controller)
i. Freeze Object
j. Unfreeze Object Parameters
k. Save Modal Object The (set-frequency ... ) function requires two arguments:
4. Hybrid Objects
Accesses
mode frequencies will be altered.
Connections
controller: a multi-dimensional controller used to
Controllers
determine the frequency of the object's modes.
Finite Elements The number of dimensions in the controller should
Appendix correspond to the number of modes in the object, or the
Index remaining mode frequencies will be set to zero.
Discussion
This function is used to set all the mode the frequencies

to new values:

'mono-string (modes 4)))
(set-frequency my-string (const

1000 2000 3000 3146))

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_mode_freq_setall.html[28/05/13 15:03:55]
Modalys - Set Frequency (of All Modes)
Options
http://support.ircam.fr/docs/Modalys/current/co/object_mode_freq_setall.html[28/05/13 15:03:55]
Modalys - Set Loss (of All Modes)
Guide Map
Modalys Set Loss (of All Modes) See also

Set Mode Loss
Summary
An Introduction to Modalys Description Set Mode Freq
This allows the loss coefficients of all the modes of an object to
Objects Modes)
be altered dynamically.
3. Object Utilities (set-loss ... ) Attach Mode
The (set-loss ... ) function can be called using the
g. Set Amplitude (of All Modes) (set-loss object_reference
h. Get Object Info
controller)
i. Freeze Object
k. Save Modal Object The (set-loss ... ) function requires two arguments:
4. Hybrid Objects
Accesses
mode loss coefficients will be altered.
Connections
Controllers
Index remaining mode losses will be set to zero.
Discussion

to new values:

(set-loss my-string (const 3 4 1

0.7))
Lower values will cause a mode to resonate longer. You

should probably base the values on those obtained via
(get-info 'mode-loss ... ).
This function is not 2013

©IRCAM yet implemented for Hybrids; an error
http://support.ircam.fr/docs/Modalys/current/co/object_mode_loss_setall.html[28/05/13 15:04:27]
Modalys - Set Loss (of All Modes)
Options
http://support.ircam.fr/docs/Modalys/current/co/object_mode_loss_setall.html[28/05/13 15:04:27]
Modalys - Set Amplitude (of All Modes)
Guide Map
Modalys Set Amplitude (of All Modes) See also

Set Mode Freq
Summary
This allows the relative amplitudes of all the modes of an object
Objects Modes)
to be altered dynamically.
1. Object Properties Set Loss (of All Modes)
2. Object Reference Attach Mode
3. Object Utilities (set-amplitude ... ) Controllers
c. Set Mode Loss
The (set-amplitude ... ) function can be called using the
g. Set Amplitude (of All Modes) (set-amplitude object_reference
h. Get Object Info
controller)
i. Freeze Object
k. Save Modal Object The (set-amplitude ... ) function requires two arguments:
4. Hybrid Objects
Accesses
modes' relative amplitudes will be altered.
Connections
Controllers
Index remaining mode losses will be set to zero.
Discussion

to new values:

(set-amplitude my-string (const

0.2 0.5 0.8 1.0))

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_mode_amp_setall.html[28/05/13 15:04:58]
Modalys - Set Amplitude (of All Modes)
Options
http://support.ircam.fr/docs/Modalys/current/co/object_mode_amp_setall.html[28/05/13 15:04:58]
Modalys - Get Object Info
Guide Map
Modalys Get Object Information See also

Get Access Information
Summary
An Introduction to Modalys Description Get Connection
Getting Started
Information
Get information about the modal and physical properties of an
Objects Get Controller
object, using the standard (get-info ... ) function. Information
2. Object Reference Get Workspace
3. Object Utilities
Information
(get-info ... )
a. Set Object Pitch
c. Set Mode Loss
The generic (get-info ... ) function can be used to obtain
d. Attach Mode Controllers object-specific information using the following Lisp syntax:
g. Set Amplitude (of All Modes) (get-info data_type
h. Get Object Info
object_reference)
i. Freeze Object
4. Hybrid Objects
Accesses (get-info data_type
Connections
object_reference mode_number )
Controllers
The Modalys Workspace or:
Finite Elements
Appendix
Index (get-info data_type
object_reference mode_number
point_number)
or:
(get-info 'physical data_type

object_reference)
Parameters
The (get-info ... ) function requires the following

arguments to get information about an object:
data_type: a string defining the type of data to

request.
object_reference: an object.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_info_get.html[28/05/13 15:05:29]
mode_number: mode whose information is being

queried.
point_number: point whose information is being
queried.
Modal Information
The following types of object-specific data can be

requested using the standard (get-info ...) function, using
just an object reference:
'num-modes
'num-points
The following types of object-specific mode data can be

obtained an object reference and a mode number
(starting from mode 0):
'mode-frequency
'mode-loss
'energy
Mode shape data can be obtained an object reference

followed by a mode number (starting from mode 0), and a
point number (starting fom 0):
'mode-shape
The following are examples of all types:
(get-info 'num-modes my-string)
(get-info 'num-points my-string)
(get-info 'mode-frequency my-

string 0)
(get-info 'mode-loss my-string 0)
(get-info 'mode-shape my-string 0

0)
(get-info 'energy my-string 0)
Physical Information
The following types of object-specific physical parameter

data can be requested using (get-info 'physical ...)
function:
length
width
thickness
radius
tension
stiffness
density
young
poisson
air-density
air-elasticity
rho
celerity
Note that the type of information available for each object

depends on the physical parameters of the object itself.
These are listed in the instantiation syntax on each
object's reference page.
An example:
(get-info 'physical 'length my-

string)
Options
Retro-Compatibility
Older versions of Modalys used a slightly different

ordering for (get-info 'physical ... ):
(get-info 'physical
object_reference data_type)
Some older Modalys scripts may therefore need to be

updated by reversing the object reference and data type
string.
Modalys - Freeze Object
Guide Map
Modalys Freeze Object See also

Unfreeze Object
Summary
An Introduction to Modalys Description Destroy Connection
Getting Started
Causes an object to lose all internal energy, and informs
Objects
Modalys to stop computing the motion of the object.
2. Object Reference
3. Object Utilities (freeze-object ... )
a. Set Object Pitch
c. Set Mode Loss
The (freeze-object ... ) function can be called using the
g. Set Amplitude (of All Modes) (freeze-object object_reference)
h. Get Object Info
i. Freeze Object Parameters
j. Unfreeze Object The (freeze-object ... ) function requires just one
k. Save Modal Object argument:
4. Hybrid Objects
object_reference: an object to be frozen.
Accesses
Connections
Controllers Discussion
The Modalys Workspace This function is often employed in situations where an
Finite Elements object is no longer useful (for example a hammer that has
Appendix finished striking its target). You can save computation
Index time by not calculating the movement of the object, i.e.:
(setq h ...) ; hammer
(setq s ...) ; string
(setq c (make-connection 'strike

s h ...))
...
(run 2) ; we are sure the strike

is finished by now
(destroy-connection c)
(freeze-object h)
(run 2) ; string continues to

vibrate
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_calc_freeze.html[28/05/13 15:06:00]
Modalys - Freeze Object
Another use of freeze-object is to “reset” an object's state

after an event. For instance, imagine that in the above
example, we want to use a force controller to push the
hammer, and that we haven't destroyed the strike
connection and frozen the object yet (i.e., right after the
first run command). Now we might want to do another
strike, but we really haven't got a clue where the hammer
is because it bounced off the string and flew away into
outer space. So we do the following:
(freeze-object my-hammer)
(set-info 'access-position my-

hammer-mov 0.1)
(set-info 'access-position my-

hammer-hit 0.1)
(unfreeze-object my-hammer)
In other words, we freeze the hammer (causing it to lose

all its vibrations and energy). Then we stick numbers in
the position boxes of each access on the hammer in
order to “reset” their positions. Finally we unfreeze the
object so that Modalys starts computing its motion again.
The hammer is now ready to go again! Back in a known
state.
Options
http://support.ircam.fr/docs/Modalys/current/co/object_calc_freeze.html[28/05/13 15:06:00]
Modalys - Unfreeze Object
Guide Map
Modalys Unfreeze Object See also

Freeze Object
Summary
An Introduction to Modalys Description Destroy Connection
Getting Started
Unfreezes an object previously frozen by (freeze-object ... ).
Objects
2. Object Reference
(unfreeze-object ... )
3. Object Utilities
a. Set Object Pitch Lisp Syntax and Default Values
b. Set Mode Freq
The (unfreeze-object ... ) function can be called using the
c. Set Mode Loss
f. Set Loss (of All Modes) (unfreeze-object object_reference)
g. Set Amplitude (of All Modes)
h. Get Object Info Parameters
i. Freeze Object
The (unfreeze-object ... ) function requires just one
j. Unfreeze Object argument:
4. Hybrid Objects
object_reference: an object to be un-frozen.
Accesses
Connections Discussion
Controllers Unfreezes an object previously frozen by (freeze-object ...
The Modalys Workspace ). See that function's reference page for more information.
Finite Elements
Appendix
Index Options
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_calc_unfreeze.html[28/05/13 15:06:31]
Modalys - Save Modal Object
Guide Map
Modalys Save Modal Object See also

Read Modal Object
Summary
An Introduction to Modalys Description
Getting Started
Saves an object's modal data in a file.
Objects
2. Object Reference
(save-object ... )
3. Object Utilities
a. Set Object Pitch Lisp Syntax and Default Values
b. Set Mode Freq
The (save-object ... ) function can be called using the
c. Set Mode Loss
f. Set Loss (of All Modes) (save-object name_of_object
g. Set Amplitude (of All Modes) file_name )
h. Get Object Info
i. Freeze Object Parameters
j. Unfreeze Object The save-object function takes two arguments:
4. Hybrid Objects
name_of_object: name of the object whose
modal data is to be saved.
Accesses
file_name: name of destination file (in quotes).
Connections
Controllers
Discussion
Finite Elements Almost any object created in Modalys can be saved using
Appendix save-object (although note that hybrids cannot be saved).
Index This can save a lot of time if the object has a lot of modes
because these files take a long time to compute. After an
object is saved, it can be retrieved using (make-object
'read-from-file ...) When an object is retrieved, it is treated
exactly the same as if it had been freshly calculated.
Options
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_file_save_1.html[28/05/13 15:07:03]
Modalys - Hybrid Objects
Guide Map
Modalys Hybrid Objects

Summary
In Modalys, a hybrid is an object which is a composite of two other objects (or three objects in the case
Getting Started
of a tri-hybrid). Creating hybrids allows you to smoothly transform from one object to another in several
Objects
different ways. Because Hybrids are not interpolated on a physical level but rather on a modal basis,
1. Object Properties you are not constrained to real-world limitations of objects and can thus create a hybrid that changes
2. Object Reference from a string into an air column. Hybrids are traditionally useful for making efficient glissandi because
3. Object Utilities the physical parameters of the object do not need to be continually re-calculated for each sample.
4. Hybrid Objects (Calculating a modal object from physical parameters can be a relatively computationally expensive
a. Melt-Hybrid Object operation, compared to other types of calculations in Modalys.)
b. Mix-Hybrid Object
Hybrids and the accesses on them must be created in a special order, but after that, the hybrid
c. Tri-Hybrid Object
accesses can be used with Modalys interactions just like the accesses of any other object.
Accesses Nonetheless, hybrids are still special objects and subject to a few restrictions within the Modalys
Connections environment: they can not be saved to a file, nor can you obtain physical or modal information about
Controllers them using the get-info command. (However, you can still use get-info to get information about a hybrid
The Modalys Workspace access, such as the speed, position or connection force.)
Finite Elements
Appendix
Modalys provides the following hybrid objects:
Index
melt-hybrid (useful for making efficient glissandi!)
mix-hybrid
tri-hybrid (a mix-hybrid between three objects)
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/ObjectHybrids.html[28/05/13 15:07:34]
Modalys - Melt-Hybrid Object
Guide Map
Modalys Melt-Hybrid Object See also

Mix-Hybrid Object
Summary
An Introduction to Modalys Description Tri-Hybrid Object
Getting Started Hybrid Accesses
Creates a hybrid of two different objects. One can think of this
Objects
hybrid, as its name implies, as one object that melts into
1. Object Properties another. With it, one can make a string turn into a membrane,
2. Object Reference or have a tube tuned to 220Hz turn into a tube tuned to 440Hz.
3. Object Utilities In both cases the result is like a glissando, as opposed to mix-
4. Hybrid Objects hybrid which does not change the objects themselves, but
a. Melt-Hybrid Object rather the energy that is transmitted to the two components of
b. Mix-Hybrid Object the hybrid.
Accesses
Connections (make-object 'melt-hybrid ... )
Controllers
Finite Elements A 'melt-hybrid object can be created using the following
Appendix Lisp syntax:
Index
(make-object 'melt-hybrid
object_reference1
object_reference2 controller)
Parameters
The 'melt-hybrid object does not have any physical

parameters, but takes three arguments:
object_reference1: the name of one of the two

instruments from which the hybrid is made.
object_reference2: the name of the other object.
controller: one-dimensional controller which
controls the interpolation of the hybrid.
The controller should output a value between zero and

one. Zero creates a hybrid exactly like object1, and one
creates a hybrid exactly like object2. Thus .5 creates a
hybrid which is halfway between the two objects, .6
creates a hybrid which is a little more like object2, etc...
Accesses
A 'melt-hybrid can only be accessed using (make-hybrid-

access ...) However, to do this, you will need to make
accesses on the two objects from which the hybrid is
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_hybrid_melt.html[28/05/13 15:08:06]
derived, before actually creating the hybrid object itself!

(make-hybrid-access ...) will keep track of where the
access actually is.
For example, if we are creating a plucked string glissando,

before creating the hybrid, we need to create accesses
for both objects at both the plucking point and the sound
output point on the string:
(setq my-string1 (make-object

'mono-string))

'mono-string))
(set-pitch my-string1 'length

220.)

440.)
(setq my-str1-acc (make-access

my-string1 (const .315) 'trans0))

(setq my-str1-out (make-access


Now we can safely create the hybrid object and its

accesses (using an envelope controller to make a
glissando between the two strings over two seconds):
(setq my-hybrid (make-object

'melt-hybrid my-string1 my-
string2 (make-controller 'envelope
1 '((0 0.) (2 1.)) )))
(setq my-hybrid-acc (make-hybrid-

access my-hybrid my-str1-acc my-
str2-acc))
(setq my-hybrid-out (make-hybrid-

access my-hybrid my-str1-out my-
str2-out))
The hybrid accesses on our 'melt-hybrid can be used in

any context where a regular access would be used.
Using a 'melt-hybrid this way to perform a glissando is

more efficient than using (set-pitch ...) with an envelope
controller.
Options
There are no special options for this object. However,

note that a 'melt-hybrid can not be saved to a file using
(save-object ...), nor can its physical or modal information
be obtained using the (get-info ...) command.
Modalys - Mix-Hybrid Object
Guide Map
Modalys Mix-Hybrid Object See also

Melt-Hybrid Object
Summary
An Introduction to Modalys Description Hybrid Accesses
Getting Started
Creates a hybrid of two different objects. One can think of this
Objects
hybrid more like a box with the two objects inside; in fact, it's
1. Object Properties sort of like a sound mix of the two objects, except that when
2. Object Reference exciting the hybrid, energy is transmitted to the sub-objects in
3. Object Utilities proportion to the current position of the hybrid. When using a
4. Hybrid Objects 'mix-hybrid with two objects of different pitches, one always
a. Melt-Hybrid Object hears the both distinct pitches (as opposed to the melt-hybrid,
b. Mix-Hybrid Object where you hear one varying pitch).
Accesses
Connections (make-object 'mix-hybrid ... )
Controllers
Finite Elements A 'mix-hybrid object can be created using the following
Appendix Lisp syntax:
Index
(make-object 'mix-hybrid
object_reference1
object_reference2 controller)
Parameters
The 'mix-hybrid object does not have any physical

parameters, but takes three arguments:

object_reference2: the name of the other object.
controller: one-dimensional controller which
The controller should output a value between zero and

one. A value of zero causes the interaction energy to be
transmitted to object1, and a value of one causes the
interaction energy to be transmitted to object2. Thus .5
creates a hybrid in which the interaction energy is sent
equallt to both objects, .6 creates a hybrid in which a little
more of the interaction energy is sent to object2, etc...
Accesses
A 'mix-hybrid can only be accessed using (make-hybrid-

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_hybrid_mix.html[28/05/13 15:08:37]
access ...) However, to do this, you will need to make

accesses on the two objects from which the hybrid is
derived, before actually creating the hybrid object itself!
(make-hybrid-access ...) will keep track of where the
access actually is.
For example, if we are creating a 'mix-hybrid object where

we will be exciting the hybrid string with a force controller,
for both objects at both the excitaation point and the
sound output point on the string:

'mono-string))

'mono-string))

220.)

440.)





accesses (using an envelope controller to allow the
excitation force to cross-fade between the two strings over
two seconds):

'mix-hybrid my-string1 my-string2
0.) (2 1.)) )))

access my-hybrid my-str1-acc my-
str2-acc))
(setq my-hybrid-out (make-hybrid-

access my-hybrid my-str1-out my-
str2-out))
The hybrid accesses on our 'mix-hybrid can be used in

any context where a regular access would be used.
Options

note that a 'mix-hybrid can not be saved to a file using
Modalys - Tri-Hybrid Object
Guide Map
Modalys Tri-Hybrid Object See also

Melt-Hybrid Object
Summary
An Introduction to Modalys Description Mix-Hybrid Object
Getting Started Tri-Hybrid Accesses
Creates a tri-hybrid, which is essentially a mix-hybrid of three
Objects
different objects. When exciting a tri-hybrid, energy is
1. Object Properties transmitted to the sub-objects in proportion to the values of the
2. Object Reference 2-dimensional controller. As with the mix-hybrid, when using a
3. Object Utilities 'tri-hybrid with objects of three different pitches, one always
4. Hybrid Objects hears the three distinct pitches.
a. Melt-Hybrid Object
b. Mix-Hybrid Object
c. Tri-Hybrid Object (make-object 'tri-hybrid ... )
Accesses
Connections
Controllers A 'tri-hybrid object can be created using the following Lisp
The Modalys Workspace syntax:
Finite Elements
Appendix
(make-object 'tri-hybrid
Index
object_reference1
object_reference2
object_reference3 2D-controller)
Parameters
The 'tri-hybrid object does not have any physical

parameters, but takes four arguments:

object_reference2: the name of the second
object.
object_reference3: the name of the third object.
2D-controller: two-dimensional controller which
The controller should be a two-dimensional controller that

outputs two values between zero and one.
Discussion
A tri-hybrid is a special version of the mix-hybrid object.

The two-dimensional controller should contain two values
between 0 and 1. If both values are 0, any interaction
energy will be transmitted to the first object, if the first
value is 1 and the second is 0 energy will be transferred to
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/object_hybrid_tri.html[28/05/13 15:09:08]
the second object, if the first value is 0 and the second

value is 1, energy will be sent to the third object. (Both
values at 1 will send energy to the second and third
objects. To help you visualize this, if you think of the first
object as the center of a circle and the 2nd object as the
circumference of that circle, the first controller controls the
distance between the center and the edge of the circle.
Now imagine the third object as existing along the
circumference of another circle on a plane perpendicular
to it - creating a sphere. The second controller is used to
control the distance from the center of that circle to its
edge.
Accesses
A 'mix-hybrid can only be accessed using (make-tri-

hybrid-access ...) However, to do this, you will need to
first make accesses on the three objects from which the
hybrid is derived, before actually creating the hybrid object
itself! The function (make-tri-hybrid-access ...) will keep
track of where the access actually is.
For example, if we are creating a 'tri-hybrid object where

we will be exciting a hybrid string with a force controller,
for all three objects at both the excitaation point and the
sound output point on the string:

'mono-string))

'mono-string))

'mono-string))

220.)

440.)

660.)






accesses (using an envelope controller to allow the
excitation force to cross-fade between the strings over
three seconds):

'tri-hybrid my-string1 my-string2
my-string3 (make-controller
'envelope 1 '((0 0. 0.) (2 1. 0.)
(3 0. 1.)) )))
(setq my-hybrid-acc (make-tri-

hybrid-access my-hybrid my-str1-
acc my-str2-acc my-str3-acc))
(setq my-hybrid-out (make-tri-

hybrid-access my-hybrid my-str1-
out my-str2-out my-str3-out))
The hybrid accesses on our 'tri-hybrid can be used in any

context where a regular access would be used.
Options

note that a 'tri-hybrid can not be saved to a file using
Modalys - Standard Accesses
Guide Map
Modalys Standard Accesses See also

Point Output
Summary
An Introduction to Modalys Description Using Compiled
Getting Started
Accesses
Creates an access on an object.
Objects Hybrid Accesses
Accesses Tri-Hybrid Accesses
1. Standard Accesses
(make-access ... )
2. Using Compiled Accesses
3. Hybrid Accesses Lisp Syntax and Default Values
4. Tri-Hybrid Accesses
A generic access can be created using the following Lisp
5. Get Access Info
syntax:
Connections
Controllers
The Modalys Workspace (make-access object_reference
Finite Elements controller direction)
Appendix
Index Parameters
the make-access function requires the following

arguments:

controller: describes the location of the access on
the object.
direction: chooses one of the possible directions
of movement of the access.
Controllers
The dimension of the controller provided as an argument

depends on the type of object being accessed. For
example, for a string, the controller should have one
dimension, and be a value between 0 and 1 (representing
the endpoints of the string). For a circular membrane,
however, a two-dimensional controller is necessary; the
first dimension is a distance from the center (0-1), and the
second dimension is an angle in degrees. Details about
the accesses on specific objects can be found in the
object reference page entries themselves.
Directions of Movement
Different objects use different directions of movement.

The following is a list of possible direction types:
©IRCAM
'trans0 - transversal
2013 along the X axis - used for
http://support.ircam.fr/docs/Modalys/current/co/access_regular.html[28/05/13 15:09:39]
mono- and bi-directional strings and masses

'trans1 - transversal along the Y axis - used for bi-
directional strings and masses
'long - longitudinal - used for tubes
'normal - used for 2D surfaces such as plates,
membranes and bars
'top-vertical - specific to the violin and cello
bridges
'top-horizontal - specific to the violin and cello
bridges
'base - specific to the violin and cello bridges
'decoded - direct access to any and all of the
object's points on a modal point-by-point basis.
'xyz - used for finite-element objects. Modalys will
locate the closest point on the mesh relative to the
one defined by the 3 coordinates given in the
controller.
Details about the direction in which an object can be

accessed can be found in the object reference page
entries themselves. For each type of object, a subset of
these directions of movement is appropriate. For example,
a bi-string can have accesses in either the 'trans0 or
'trans1 direction (first and second transverse directions). A
closed-closed-tube or closed-open-tube can only be
accessed in the long (longitudinal) direction. Membranes
and plates are accessed in the normal direction (this is
“normal” in the mathematical sense, i.e. at right angles to
both dimensions of the membrane). The 'decoded
direction is explained in the access options, below.
Options
Decoded Accesses
All objects can additionally be accessed using “decoded”

accesses. To understand these, you need to know that
internally, Modalys discretizes objects in space. Imagine a
membrane covered with discrete points. Modalys can
really only compute accesses on a per-point basis. When
you say you'd like an access at (0.3 0.4) on a membrane,
this location is probably not exactly on a point, so Modalys
actually takes a weighting of four points to approximate
your access. Using “decoded” accesses permits you to
bypass this “point translation phase” (PTP) and directly
say how much of each point you would like. So if you
want to access the middle of a mono-dimensional string
with 10 modes and 9 points, you could write either of
these two statements:
(make-access my-string (const .5)

'trans0)
or:
(make-access my-string (const 0 0

0 0 1 0 0 0 0) 'decoded)
As you can see, using a decoded accesses allows you to

do some slightly weird things, like being able to “spread”
your access over half of the string by typing:
(make-access my-string (const .2

.2 .2 .2 .2 0 0 0 0) 'decoded)
Unfortunately, the disadvantage to all of this is that in

most cases, you can't know exactly how many points
Modalys used for a given object, and you also can't know
exactly how the points are laid out on the object surface.
So what's the use of this? Well, in two cases you do know
the number of points — when you used compiled
accesses (see the make-compiled-access explanation)
and when you use (make-object 'read-from-file ...) to
create your model.
Shared Accesses
Accesses can be shared - in other words, one access can

be used for multiple connections. Beware though that in
some cases the physical equations might not
subsequently be solvable and error messages will be
issued during synthesis. This is often the case if you try to
impose a certain position at a certain access, with a
'position connection for example, and at the same time
trying to impose a certain speed to the same location, with
a 'strike interaction, for example.
Generally, however, it can be safer (and conceptually

easier, even though slightly more computationally
expensive) to create an access for each use, such as an
access for a point-output at the same location as an input
force, etc....
Modalys - Using Compiled Accesses
Guide Map
Modalys Using Compiled Accesses See also

Standard Accesses
Summary
An Introduction to Modalys Description Circular Membrane -
Getting Started
Fixed
Allows one to create a membrane or plate object with a limited
Objects Rectangular Membrane
number of fixed, immovable accesses. This operation saves
Accesses - Fixed
lots of memory if you are using objects with a lot of modes.
1. Standard Accesses Circular Plate -
Clamped
3. Hybrid Accesses (with-compiled-accesses ... ) Circular Plate - Free

4. Tri-Hybrid Accesses Rectangular Plate -
5. Get Access Info Lisp Syntax and Default Values Fixed
Connections
A compiled access can be created using the following
Controllers
Lisp syntax:
Finite Elements
Appendix (with-compiled-accesses
Index (list (list x-or-
radius y-or-angle)
(list x-or-
radius y-or-angle)
...etc... )
(make-object ... ))
Parameters
the with-compiled-accesses function requires a list of lists

containing 2-dimensional access locations with the
following parameters:
x-or-radius, y-or-angle : 2-dimensional access

locations to be computed at object creation time
This marks the access locations to be computed at the

creation of the object. The units for this parameter depend
on the whether the plate or membrane is square or round.
If it is square, each list element will contain an x and a y .
If it is round, each list element will contain a location along
the radius (between 0 and 1) and an angle. (For more
information about accesses on plates and membranes,
see their specific object reference entries.)
Options
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/access_compiled.html[28/05/13 15:10:10]
Modalys - Using Compiled Accesses
Accessing Compiled Accesses
To make an access on an object which has compiled

accesses, you must use (make-access ... 'decoded). The
access locations stay in the same order as the above list.
Thus, if your list of accesses has three elements, use:
(make-access my-comp-mem (const 1

0 0) 'decoded)
to refer to the first access,
(make-access my-comp-mem (const 0

1 0) 'decoded)
to refer to the second, etc. If you like, you can ask for an
access which is a weighted combination of the three
points by writing:
(make-access my-comp-mem (const

.1 .6 .3) 'decoded)
The reason for using compiled accesses is to save

memory. With normal accesses, the amount of memory
taken by a plate or membrane is roughly the number of
modes squared. With a plate which has 40 or 80 modes,
there is no memory problem. If your plate has a thousand
modes however, memory becomes a very big problem.
Compiled accesses reduce memory consumption to the
number of modes in the list times the total number of
modes. A big difference indeed! (Of course as computers
get faster and have larger amounts of memory this is less
of a concern...)
http://support.ircam.fr/docs/Modalys/current/co/access_compiled.html[28/05/13 15:10:10]
Modalys - Hybrid Accesses
Guide Map
Modalys Hybrid Accesses See also

Standard Accesses
Summary
An Introduction to Modalys Description Tri-Hybrid Accesses
Getting Started Melt-Hybrid Object
Creates an access on a hybrid object.
Objects Mix-Hybrid Object
Accesses
Tri-Hybrid Object
(make-hybrid-access ... )
A hybrid access can be created using the following Lisp
5. Get Access Info
syntax:
Connections
Controllers
The Modalys Workspace (make-hybrid-access
Finite Elements hybrid_object_reference
Appendix access_ref1 access_ref2)
Index
Parameters

arguments:
hybrid_object_reference: name of the hybrid

object on which the hybrid access will be located
access_ref1: name of a standard access on the
the first object in the pair from which the hybrid is
derived
the second object in the pair from which the hybrid
is derived
Discussion
Well, the trick to making a hybrid access is that before you

make the hybrid, you need to make a bunch of accesses
on the individual objects. You need to do this because
when you actually make the hybrid object, the original
objects “evaporate” as far as Modalys is concerned - they
are “used up” as the hybrid is produced, and can no
longer be referenced. Therefore, to specify an access on
the hybrid, you take one each of the accesses on the
component objects (which are now like “ghost” accesses
since they are on evaporated objects) and you call make-
hybrid-access using the ghost accesses you have already
defined.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/access_hybrid.html[28/05/13 15:10:41]
Here is the correct procedure for making a hybrid object

and hybrid accesses. First, make the objects that will
become part of the hybrid:
(setq my-plate (make-object ...))
(setq my-twomass (make-object

...))
Then make the accesses on these original objects that

will turn into “ghosts”:
(setq my-plate-ghost-acc (make-

access my-plate ...))
(setq my-twomass-ghost-acc (make-

access my-twomass ...))
After you have created all the accesses you will need,
you can then create the hybrid object. Doing this will
cause the original two objects to “evaporate”:

'melt-hybrid my-plate my-twomass
(make-controller ...)))
Now you can make an access on the hybrid, by

combining the original two accesses associated with the
hybrid's original two objects:

access my-hybrid my-plate-ghost-
acc my-twomass-ghost-acc))
The hybrid access can be used in any situation where a

normal access can be used.
Options
Considerations
Although you can not use (get-info ... ) to query a hybrid's

physical or modal parameters, you can use (get-info ... )
to get the speed, position and interaction force of a hybrid
access!
Retro-Compatibility
This command used to be called (make-access-hybrid ...)
- this syntax is obsolete and older files should be

converted to use the new syntax.
Modalys - Tri-Hybrid Accesses
Guide Map
Modalys Tri-Hybrid Accesses See also

Standard Accesses
Summary
An Introduction to Modalys Description Hybrid Accesses
Getting Started Melt-Hybrid Object
Creates an access on a tri-hybrid object.
Objects Mix-Hybrid Object
Accesses
Tri-Hybrid Object
(make-tri-hybrid-access ... )
A tri-hybrid access can be created using the following Lisp
5. Get Access Info
syntax:
Connections
Controllers
The Modalys Workspace (make-tri-hybrid-access
Finite Elements hybrid_object_reference
Appendix access_ref1 access_ref2
Index access_ref3)
Parameters

arguments:
hybrid_object_reference: name of the hybrid

object on which the hybrid access will be located
the first object from which the tri-hybrid is derived
the second object from which the tri-hybrid is
derived
the third object from which the tri-hybrid is derived
Discussion
This functions similarly to the hybrid access, except that it

is specific to tri-hybrid objects.
Once created, the tri-hybrid access can be used in any

situation where a normal access can be used.
Options
Considerations
Although you can not

©IRCAM use (get-info ... ) to query a hybrid's
2013
http://support.ircam.fr/docs/Modalys/current/co/access_tri_hybrid.html[28/05/13 15:11:12]
Modalys - Tri-Hybrid Accesses
physical or modal parameters, you can use (get-info ... )

to get the speed, position and interaction force of a hybrid
access!
http://support.ircam.fr/docs/Modalys/current/co/access_tri_hybrid.html[28/05/13 15:11:12]
Modalys - Get Access Info
Guide Map
Modalys Get Access Information See also

Summary
An Introduction to Modalys Description Get Connection
Getting Started
Information
Get information about an access using the standard (get-info ...
Objects Get Controller
) function.
Accesses Information
1. Standard Accesses Get Workspace

Information
(get-info ... )
3. Hybrid Accesses
4. Tri-Hybrid Accesses Lisp Syntax and Default Values
5. Get Access Info
Connections
access-specific information using the following Lisp
Controllers
syntax:
Finite Elements
Appendix (get-info data_type
Index access_reference)
Parameters
The (get-info ... ) function requires the following two

arguments to get information about an access:
data_type: a string defining the type of data to

request.
access_reference: an access on an object.
Controllers
The following types of access-specific data can be

requested using the standard (get-info ...) function:
'speed
'position
'force
'admittance
Note that the access must have a connection connected

to it in order to obtain the connection force value!
Examples of using the above are:
(get-info 'speed foo-acc)
(get-info 'position foo-acc)
(get-info 'force foo-acc) ; must

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/access_info_get.html[28/05/13 15:11:43]
Modalys - Get Access Info
have a connection connected to it!
(get-info 'admittance foo-acc) ;

inverse impedance
Although there already exist built-in functions to get much

of this information and output it as a Modalys controller,
you could also use a 'foreign-call controller to do much
the same thing:
(make-controller 'foreign-call 1
0
(lambda (ins outs)
(vset outs 0
(get-info 'speed access-ref)))
'())
However, obtaining the access speed this way is much

more computationally expensive. Nonetheless, it is the
only way, for the moment, to make a controller from the
access admittance (i.e. inverse impedance) data.
Options
http://support.ircam.fr/docs/Modalys/current/co/access_info_get.html[28/05/13 15:11:43]
Modalys - Force Connection
Guide Map
Modalys Force Connection See also

Speed Connection
Summary
An Introduction to Modalys Description Position Connection
Getting Started Access Force
Applies force to an access.
Objects Controller
Accesses Access Speed
Connections Controller
(make-connection 'force ... )
1. Force Connection Access Position
2. Speed Connection Lisp Syntax and Default Values Controller
3. Position Connection Get Access Information
The 'force connection can be created using the following
Lisp syntax:
7. Pluck Connection (make-connection 'force
8. Spring Connection access_reference force_controller
9. Reed Connection weight)
11. Mono-Fingerboard Connection Parameters
12. Normalised Valve Connection
The 'force connection takes three arguments:
13. Normalised Leaky Valve
Connection access_reference: any access.
14. Bow Connection force_controller: a one-dimensional controller
15. Bi-Fingerboard Connection outputting a value for force in Newtons.
16. Valve Connection weight: (optional) controller weighing the
17. Leaky Valve Connection interaction.
18. Induction Connection
The force controller is a one-dimensional controller which
19. Labium Connection
outputs a value for force in Newtons. The direction of the
force is determined by the sign of the output value (i.e., a
21. Get Connection Info
positive number will apply force in one direction, and a
Controllers
negative number will apply force in the opposite direction).
Finite Elements The weight controller is optional. If not provided, it defaults
Appendix
to 1.
Index
Discussion
Among the connections used for moving objects around,

i.e., 'position, 'speed, and 'force, 'force should be used
whenever possible. Its primary advantage is that it is by
far the least expensive of the three functions in terms of
computation; but also, it is often the most “gentle” way of
doing things. For instance, a sudden change in position or
speed will often result in a harsh and “unnatural” effect,
especially when a change in direction is involved. If,
however, an object 2013
©IRCAM is moving in one direction and one
http://support.ircam.fr/docs/Modalys/current/co/connection_force.html[28/05/13 15:12:14]
Modalys - Force Connection
suddenly pushes it (using 'force) in the other, it will take

time to slow down, making a smooth deceleration before
changing direction. The only disadvantage to 'force is that
it is sometimes a bit tricky to control. It is often helpful to
try a model out using 'position or 'speed, changing 'force
after everything else is working.
Applying a constant force to an object is a good way to

simulate gravity in Modalys.
Options
There are no special options for this connection.
http://support.ircam.fr/docs/Modalys/current/co/connection_force.html[28/05/13 15:12:14]
Modalys - Speed Connection
Guide Map
Modalys Speed Connection See also

Force Connection
Summary
An Introduction to Modalys Description Position Connection
Specifies (sets) the speed of an access over time.
Objects Controller
(make-connection 'speed ... )
The 'speed connection can be created using the following
Lisp syntax:
7. Pluck Connection (make-connection 'speed
8. Spring Connection access_reference speed_controller
The 'speed connection takes three arguments:
14. Bow Connection speed_controller: a one-dimensional controller
15. Bi-Fingerboard Connection outputting a value for speed in m/sec.
The speed controller a one-dimensional controller which
outputs a value for speed. The value is expressed in
m/sec. The direction of the speed is determined by the
sign of the output value (i.e., a positive number will move
Controllers
the access in its positive direction, and a negative number
The Modalys Workspace will give the access speed in the opposite direction).
Finite Elements
Appendix
The weight controller is optional. If not provided, it defaults
to 1.
Index
Discussion
Along with 'position and 'force, the 'speed connection is

one of the most basic connections in Modalys.
Options

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_speed.html[28/05/13 15:12:45]
Modalys - Speed Connection
http://support.ircam.fr/docs/Modalys/current/co/connection_speed.html[28/05/13 15:12:45]
Modalys - Position Connection
Guide Map
Modalys Position Connection See also

Force Connection
Summary
An Introduction to Modalys Description Speed Connection
Sets the position of an access.
Objects Controller
(make-connection 'position ... )
The 'position connection can be created using the
7. Pluck Connection (make-connection 'position
8. Spring Connection access_reference
9. Reed Connection position_controller weight)
The 'position connection takes three arguments:
14. Bow Connection position_controller: a controller specifying the
15. Bi-Fingerboard Connection access position (in meters) over time.
The position controller is a one-dimensional controller that
specifies the access position (in meters) over time.
21. Get Connection Info The weight controller is optional. If not provided, it defaults
Controllers to 1.
Finite Elements Discussion
Appendix Along with 'speed and 'force, 'position is one of the most
Index basic Modalys controllers. It is generally most effectively
used with a mass object of some sort.
The position connection forces an access point to follow a

position — specified by the position_controller — over
time. It is fairly simple, but has a small quirk which must
be clearly understood. When the position connection is
made, it immediately peeks at the starting value of the
controller that it gets. It sticks that number into the
access's position box. Hence, one is guaranteed initially
that the object is not excited in any way. Thereafter, as
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_position.html[28/05/13 15:13:16]
Modalys - Position Connection
the position changes, the access point is “pulled” to follow

the controller's position value (units are in meters).
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_position.html[28/05/13 15:13:16]
Modalys - Acoustic Hole Connection
Guide Map
Modalys Acoustic Hole Connection See also

Tube - closed/open
Summary
An Introduction to Modalys Description Reed Connection
Getting Started
Makes a tone hole of variable diameter along an acoustic tube.
Objects
Accesses This function has been deprecated (see details below).
Connections
1. Force Connection
2. Speed Connection (make-connection 'hole ... )
5. Adhere Connection The 'hole connection can be created using the following
6. Strike Connection Lisp syntax:
7. Pluck Connection
(make-connection 'hole access_ref
9. Reed Connection radius_ctl noise_ctl weight)
Parameters
13. Normalised Leaky Valve The 'hole connection takes four arguments:
Connection
access_ref: any access.
14. Bow Connection
radius_ctl: radius of hole (in meters).
15. Bi-Fingerboard Connection
noise_ctl: hole noise coefficient.
16. Valve Connection
weight: (optional) controller weighing the
17. Leaky Valve Connection
interaction.
19. Labium Connection The weight controller is optional. If not provided, it defaults
20. Destroy Connection to 1.
Controllers Discussion
This interaction internally creates a small closed-open
Finite Elements tube and adheres it to the access you provide. Since the
Appendix hole radius is given by a controller, the hole can be
Index opened and closed dynamically. The noise coefficient is
expected to be between 0 and 1; when it is high, then
opening and closing the hole produces some air
turbulence in the tube (although this has not been tested
much and seems to have very little effect...).
Here is an example of how to open and close a hole over

2 seconds:

©IRCAM 2013
'closed-open-tube (modes 40)
http://support.ircam.fr/docs/Modalys/current/co/connection_hole.html[28/05/13 15:13:47]
(radius0 .01) (radius1 .01)))
(setq hole-radius (make-

controller 'envelope 1 '((0 0.) (1
0.) (1.05 .01) (2 .01) (2.05
0.))))
(setq my-tube-hole (make-access

my-tube (const 0.7937) 'long))
(make-connection 'hole my-tube-

hole hole-radius (const 0.))
Note also that If the hole is too large, the system may
become unstable and will not produce sound.
Options
Other Ways of Making Tone Holes
This connection has been deprecated, but nonetheless

still retained in the Modalys environment. You should now
create a Modalys object (such as a very small closed-
open tube), typically with few modes, to act as a hole and
connect it with an 'adhere connection to your object acting
as a tube. (Which is basically what this connection does,
anyway.) The hole will be made more or less active (more
or less open) by varying the weight controller of that
adhere connection. If you really want to use the hole
connection, please note that the radius is made internally
to .01 m by default, so please adapt your radius
messages accordingly.
A very small closed-open tube like this can be adhered to

another tube as an alternative to making a tone hole on a
wind instrument:
(modes 4)
(length 2e-3)
(radius0 5e-3)
(radius1 5e-3)
(freq-loss 10) )
See Also
This tone hole is adhered to a resonating air column (i.e.

another tube serving as the instrument itself) at the closed
end of the tube. Opening and closing the tone hole is
achieved by modifying the interaction weight of the adhere
connection itself. (A weight of 1 means the hole will be
open, a weight of 0 means it will be closed.
Modalys - Adhere Connection
Guide Map
Modalys Adhere Connection See also

Spring Connection
Summary
An Introduction to Modalys Description Speed Connection
Getting Started Position Connection
Adheres two accesses together, so they have the same speed.
Objects
Accesses
Connections
(make-connection 'adhere ... )
1. Force Connection
2. Speed Connection Lisp Syntax and Default Values
The 'adhere connection can be created using the following
Lisp syntax:
7. Pluck Connection (make-connection 'adhere acc_ref1
8. Spring Connection acc_ref2 weight)
9. Reed Connection
10. Felt Hammer Connection Parameters
The 'adhere connection takes three arguments:
13. Normalised Leaky Valve acc_ref1: any access.
Connection acc_ref2: any access.
14. Bow Connection weight: (optional) controller weighing the
15. Bi-Fingerboard Connection interaction.
to 1.
Discussion
21. Get Connection Info The function (make-connection 'adhere ...) causes two
Controllers access to have the same speed. The accesses need not
The Modalys Workspace have the same position; i.e., if two accesses whose
Finite Elements positions differ by five meters are adhered, and one of the
Appendix accesses is moved, the other will follow by the same
Index
amount. Nor do the accesses need to have the same
direction. If, for example, a 'trans0 access on a string is
adhered to a 'long access on an air column, a change in
speed in the string will result in a change in the pressure
of the air column by the same amount (in the respective
units of each).
Use this connection whenever you want to “glue” two

things together; like a string to a violin bridge, a bridge to
a violin body, etc...
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_adhere.html[28/05/13 15:14:18]
Modalys - Adhere Connection
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_adhere.html[28/05/13 15:14:18]
Modalys - Strike Connection
Guide Map
Modalys Strike Connection See also

Felt Hammer
Summary
Connection
Getting Started
Pluck Connection
A connection where one access strikes another.
Objects Two-Mass - Mono-
Accesses directional
Connections
(make-connection 'strike ... )
1. Force Connection
The 'strike connection can be created using the following
Lisp syntax:
7. Pluck Connection (make-connection 'strike acc_ref1
8. Spring Connection init_pos1 acc_ref2 init_pos2
or:
Connection (make-connection 'strike acc_ref1
14. Bow Connection init_pos1 weight)
Parameters
18. Induction Connection The 'strike connection takes five arguments (or just three
to create a unilateral connection):
20. Destroy Connection acc_ref1: access on striking object.

21. Get Connection Info init_pos1: initial position of the striking object's
Controllers access. (numerical value, not a controller)
The Modalys Workspace acc_ref2: access on object to be struck.
Finite Elements init_pos2: initial position of the struck object's
Appendix access. (numerical value, not a controller)
Index weight: (optional) controller weighing the
interaction.
The two positions must be numerical values, not

controllers. The weight controller is optional. If not
provided, it defaults to 1.
To create a unilateral strike connection, the second

access and its position are not provided.
Discussion
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_strike.html[28/05/13 15:14:49]
Modalys - Strike Connection
As with the pluck connection, strike accesses must be

given an initial location and then moved in order to
produce an interaction. (To move the accesses, it is
necessary to use another controller: either 'position, 'force,
or 'speed.) Note that the strike connection is identical to
the pluck connection, except that there is no “release”
when the “plectrum” (“hammer”) pushes too far.
Options
Unilateral Strike Connection
You can optionally provide only one access, in order to

create a unilateral contact. In this case, contact will be
made with an infinitely rigid “ground surface” situated at
zero. See the Tampura example for an application.
Retro-Compatibility
In older versions of Modalys, the arguments were

provided in a slightly different order:
(make-connection 'strike acc_ref1

acc_ref2 init_pos1 init_pos2)
See Also
You may need to update this connection to the new

syntax if you come across any very old Modalys files.
http://support.ircam.fr/docs/Modalys/current/co/connection_strike.html[28/05/13 15:14:49]
Modalys - Pluck Connection
Guide Map
Modalys Pluck Connection See also

Strike Connection
Summary
An Introduction to Modalys Description Two-Mass - Mono-
Getting Started
directional
A connection where one access plucks another.
Objects
Accesses
Connections
(make-connection 'pluck ... )
1. Force Connection
A 'pluck interaction can be created using the following
Lisp syntax:
7. Pluck Connection (make-connection 'pluck acc_ref1
8. Spring Connection init_pos1 acc_ref2 init_pos2
9. Reed Connection release_ctl weight)
The 'pluck connection takes six arguments:
Connection acc_ref1: access on plucking object.
14. Bow Connection init_pos1: initial position of the plucking object's
15. Bi-Fingerboard Connection access. (numerical value, not a controller)
16. Valve Connection acc_ref2: access on object to be plucked.
17. Leaky Valve Connection init_pos2: initial position of the plucked object's
18. Induction Connection access. (numerical value, not a controller)
19. Labium Connection release_ctl: controller determining the release of
20. Destroy Connection the pluck interaction (force in Newtons).
21. Get Connection Info weight: (optional) controller weighing the
interaction.
Controllers
The Modalys Workspace The two positions must be numerical values, not
Finite Elements controllers. The weight controller is optional. If not
Appendix provided, it defaults to 1.
Index
The release_controller is a one-dimensional controller
describing the limit of force (in Newtons) that the plectrum
can apply to the string before the string "slips" off and the
pluck happens.
Discussion
For the pluck connection, one access, usually on the

small mass of a 'mono-two-mass or 'bi-two-mass object,
pushes another access, usually a string. When a force
threshold,©IRCAM
determined by the value of my-controller, is
2013
http://support.ircam.fr/docs/Modalys/current/co/connection_pluck.html[28/05/13 15:15:21]
attained between the “plectrum” and the “string,” the two

objects detach, snap back, and vibrate. A reasonable
plectrum object is obtained using a 'bi-two-mass object
with the following parameters:
(setq my-plucker (make-object

'mono-two-mass
(small-mass .001)
(large-mass .01)
(stiffness0 100000)
(stiffness1 100000)
(freq-loss0 100)
(freq-loss1 100)
(const-loss0 0)
(const-loss1 0) ))
Having made the pluck connection between two access,

one or both objects must be moved so that the two
accesses interact. The initial positions of the two
accesses in relation to one another is determined by the
values given for init-pos1 and init-pos2. (To move the
plectrum, it is necessary to use another connection;
'position, 'force, or 'speed, for example.)
A pluck sound will be most easily obtained using the

'position controller to move the plectrum. If a 'force
controller is used, the amount of force must exceed the
value given for the 'pluck connection's my-controller,
otherwise the objects will never release from one another,
and no sound will be obtained. In all cases,be careful not
to cross the plectrum over the string too rapidly, otherwise
the interaction may not work properly.
Options
Retro-Compatibility

(make-connection 'pluck acc_ref1

acc_ref2 init_pos1 init_pos2
release_ctl)

Modalys - Spring Connection
Guide Map
Modalys Spring Connection See also

Adhere Connection
Summary
An Introduction to Modalys Description One-Mass - Mono-
Getting Started
This connection allows the energy from one object to be Oscillator)
Objects
transferred to another via a spring which acts as a harmonic
Accesses
oscillator.
Connections
1. Force Connection
2. Speed Connection (make-connection 'spring ... )
4. Acoustic Hole Connection Lisp Syntax and Default Values
The 'spring connection can be created using the following
Lisp syntax:
7. Pluck Connection
9. Reed Connection (make-connection 'spring acc_ref1
10. Felt Hammer Connection acc_ref2 stiffness_ctl freq-loss
const-loss weight)

13. Normalised Leaky Valve Parameters
Connection
The 'spring connection takes six arguments:
14. Bow Connection
15. Bi-Fingerboard Connection acc_ref1: access on the first object.
16. Valve Connection acc_ref2: access on the other object (or on the
17. Leaky Valve Connection same object!).
18. Induction Connection stiffness_ctl: controller defining the stiffness of
19. Labium Connection the spring for the harmonic oscillator.
20. Destroy Connection freq-loss: decay of the sound proportionally to the
21. Get Connection Info square of the frequencies.
const-loss: a common base for the decay of all
Controllers
frequencies.
Finite Elements
interaction.
Appendix
Index Note the two accesses can optionally be on the same
object, instead of different objects!
The parameters for stiffness, freq-loss and const-loss are

all controllers. See the General Object information section
for a discussion of these parameters.

to 1.
Discussion
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_spring.html[28/05/13 15:15:52]
Modalys - Spring Connection
This connection allows the energy from one object to be

transferred to another via matched impedance. It will
create a harmonic oscillator of appropriate weight
between the two accesses. It is an interesting alternative
to the 'adhere connection.
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_spring.html[28/05/13 15:15:52]
Modalys - Reed Connection
Guide Map
Modalys Reed Connection See also

Adhere Connection
Summary
An Introduction to Modalys Description Labium Connection
Getting Started Valve Connection
Makes a reed-tube interaction.
Objects Normalised Valve
Accesses Connection
Connections
(make-connection 'reed ... ) Leaky Valve
1. Force Connection Connection
2. Speed Connection Lisp Syntax and Default Values Normalised Leaky
3. Position Connection Valve Connection
The 'reed connection can be created using the following
Lisp syntax: One-Mass - Mono-
5. Adhere Connection directional (Harmonic
6. Strike Connection Oscillator)
7. Pluck Connection (make-connection 'reed reed_acc
Tube - closed/open
8. Spring Connection reed_pos tube_acc air-pressure
9. Reed Connection air-density reed-area aperture-
10. Felt Hammer Connection length weight)
12. Normalised Valve Connection Parameters
13. Normalised Leaky Valve The 'reed connection takes eight arguments:
Connection
14. Bow Connection reed_acc: the access on the object that will be
15. Bi-Fingerboard Connection used as a reed.
16. Valve Connection reed_pos: the initial position of the reed with
17. Leaky Valve Connection respect to the tube. (a numerical value)
18. Induction Connection tube_acc: the access on the object used as a
19. Labium Connection tube.
20. Destroy Connection air-pressure: breath pressure - the pressure of
21. Get Connection Info the air before exciting the reed.
air-density: a controller for the density of air.
Controllers
reed-area: the surface area of the reed.
aperture-length: the width of the reed.
Finite Elements
Appendix
interaction.
Index
The object used as a reed is commonly a bi-two-mass,
but it could be any other Modalys object.
The initial position of the reed with respect to the tube - it

is typically a small value, around 1 mm. This is provided
as a numerical value, not a controller.
The object used as a tube is commonly a closed-open-

tube, but feel free to experiment!
The remaining parameters are controllers:

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_reed.html[28/05/13 15:16:22]
The breath pressure of the air just before hitting the reed.
Typical values: from 0 to 50000 Pa
For the air density controller, the usual value for the
volumic mass of air is 1.2 kg / m^3, however you might
need to play with this if you wish to blow into Modalys
objects other than air columns (the various tubes).
Typical values for the reed area controller are from 1e-14
to 1e-3 m^2. This value is unrelated whatsoever to the
physical values used when defining the reed object. It is
up to you to match them or not.
The aperture length controller controls the vibrating width

of the reed. A typical value is around 2.76e^-4, although
this may need to be changed when experimenting with
uncommon objects.

to 1.
Discussion
The reed connection simulates most of the mouthpiece of

a typical single-reed instrument. You need an access to
serve as the reed tip, an access to serve as the top of the
acoustic tube, and the reed connection supplies all else,
simulating a “virtual mouthpiece” that the reed can bang
against, simulating the effects of blowing, etc.
Because the 'reed connection cannot access the base of

the reed by itself, you must make a separate position
connection to “clamp” the base of the reed in place; so it
is necessary to make a position connection, with a
position controller fixed at zero. (see example 3).
Options
Appropriate Objects to Use as Reeds
The frequency of oscillation of the reed is calculated

according to the formula:
sqrt(k/m)/2pi
or in Lisp:
(/ (sqrt (/ 200 .000002)) (* 2

pi))
Typical reed frequencies are above 1500 Hz. If we use a

two-mass object as a reed, using a mass (m) value of 2e^-
6 and stiffness (k) of 200 we obtain an appropriate
frequency of 1591.55, so the following two-mass object is
an appropriate starting point for use as a reed:
(setq my-reed (make-object 'mono-

two-mass
(small-mass .000002)
(large-mass .000002)
(stiffness0 200)
(const-loss0 60)
(freq-loss0 260) ))
The access on the reed which will be connected to the

acoustic tube is generally on the large mass, although in
the example above, both masses are of equal size:
(setq my-reed-tip (make-access

my-reed (const 1) 'trans0))
When using a two-mass, you also need to set the other

mass to a fixed position so it does not move away:
(setq my-reed-base (make-access

my-reed (const 0) 'trans0))

reed-base (const 0))
Alternately, you can also use a harmonic oscillator in

place of a two-mass object. Since the harmonic oscillator
(a mono-one-mass) it is already fixed at one end, you do
not need to to use a position connection to fix the other
end of the reed as an immobile point (as we do when
using a two-mass):
(setq my-reed (make-object

'harmonic-oscillator
(mass .000002)
(stiffness 200)
(const-loss 60)
(freq-loss 260)))
And for the access:

my-reed (const 1) 'normal))
Another option would be to use a very small rectangular

plate as a reed. Appropriate values that you can use as a
starting point are:
(setq my-reed (make-object 'rect-

plate
(modes 5)
(length0 .7e-2)
(length1 2e-2)
(thickness 2e-5)
(density 700)
(freq-loss 400)
(const-loss 200) ))
Accesses on this plate will need to be away from the

edges of the plate, which are fixed:

my-reed (const .1 .2) 'normal))
Note that, as with the harmonic oscillator, because the

plate is fixed at its edges, you do not need to secure it
with a position connection as you do the two-mass object.
Retro-Compatibility
When updating old Modalys scripts, the air pressure

controller values used may need to be increased in range,
due to corrections made to this connection.
Modalys - Felt Hammer Connection
Guide Map
Modalys Felt Hammer Connection See also

Strike Connection
Summary
An Introduction to Modalys Description Two-Mass - Mono-
Getting Started
directional
Interaction of a felt hammer against an object. It is very
Objects
convenient in order to soften the excessively brutal attacks
Accesses
inherent in the strike connection. It fully models the hysteresis
Connections
(the lag time of the effect of the interaction in relation to its
1. Force Connection cause), just as real felt behaves, and is based on Stulov's
2. Speed Connection model.
5. Adhere Connection (make-connection 'felt ... )
7. Pluck Connection Lisp Syntax and Default Values
8. Spring Connection The 'felt connection can be created using the following
9. Reed Connection Lisp syntax:
(make-connection 'felt acc_ref1
init-pos1 acc_ref2 init-pos2
Connection thickness F0 alpha epsilon tau
14. Bow Connection weight)
16. Valve Connection Parameters
The 'adhere connection takes ten arguments:
19. Labium Connection acc_ref1: access on striking object.
20. Destroy Connection init-pos1: initial position of the striking object's
21. Get Connection Info access. (numerical value, not a controller)
acc_ref2: access on object to be struck.
Controllers
init-pos2: initial position of the struck object's
access. (numerical value, not a controller)
Finite Elements
thickness: controller representing the thickness of
Appendix
the felt, in meters.
Index
F0: first parameter of Stulov's model. Corresponds
approximately to the strength or hardness of the
felt.
alpha: the exponent for the law relating the force
to the depression.
epsilon: controls the level of the hysteresis, 0 will
block it, 1 will enable it fully.
tau: time constant for the hysteresis.
interaction.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_felt.html[28/05/13 15:16:53]
Modalys - Felt Hammer Connection
The two access positions must be numerical values, not

controllers.
The various parameters for this connection are all

controllers. The thickness controller represents the
thickness of the felt in meters.
The F0 controller, the first parameter of Stulov's model,

corresponds approximately to the strength or hardness of
the felt. Higher values will yield brighter sounds, as if
struck by metal, whereas lower values will sound more
muted, as if struck by rubber. Typical values range from 0
to 1e15.
The alpha controller defines the exponent for the law

relating the force to the depression. Higher values makes
the resulting sound more damp, as if being struck by a
softer material. Typically above 2.
The epsilon controller controls the level of the hysteresis,

0 will block it, 1 will enable it fully. Typical values ranging
from 0 to .9 (Aurally, from the user's point of view, this
seems to relate somewhat to surface fuzziness of the
felt.)
The tau controller provides the time constant for the

hysteresis. Lower values will make the felt recover
quicker. Typical values range from 1e-7 to 1e-5 sec.
(Aurally, from the user's point of view, this seems to relate
somewhat to the surface hardness of the felt.)

to 1.
Discussion
The felt connection is similar to the strike connection.

(...but it sounds a lot better!)
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_felt.html[28/05/13 15:16:53]
Modalys - Mono-Fingerboard Connection
Guide Map
Modalys Mono-Fingerboard See also
Summary Connection Bi-Fingerboard

Connection
Two-Mass - Mono-
Getting Started Description
directional
Objects
Simulates the interaction between a finger and a string with a
Accesses String (or Rod) - Mono-
fingerboard underneath them (mono-directional version). directional
Connections
1. Force Connection
2. Speed Connection (make-connection 'mono-fingerboard ...
3. Position Connection )
5. Adhere Connection Lisp Syntax and Default Values
The 'mono-fingerboard connection can be created using
7. Pluck Connection the following Lisp syntax:
9. Reed Connection
10. Felt Hammer Connection (make-connection 'mono-
fingerboard fgr_acc_V fgr_posV
str_acc_V str_posV position_ctl
weight)
Parameters
The 'mono-fingerboard connection takes six arguments:
fgr_acc_V: the access on the object used as a

“finger”.
fgr_posV: initial position value of the finger
access.
str_acc_V: the access on the object used as a
“string”.
str_posV: initial position value of the string
access.
position_ctl: a controller which specifies the
position of the virtual fingerboard (usually a
constant controller)
interaction.
With this connection the access on the “finger” (its vertical

position with respect to the fingerboard) is used to decide
whether it is clamping the string or not (i.e. moving the
finger up and down in this direction clamps and un-
clamps the string).
The position controller specifies the position of the

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_fingerboard_mono.html[28/05/13 15:27:54]
Modalys - Mono-Fingerboard Connection
fingerboard over time. Generally speaking, one might

make this controller (const 0), then set str_posV to .01
meters, then set fgr_posV to .02 meters. This controller is
almost always constant, but one might want a moving
fingerboard for an esoteric application.

to 1.
Discussion
When simulating string instruments, you frequently want

to change the pitch of the string by putting a finger down
on a fingerboard somehow. Normally in Modalys, you
would have to create some large mass beneath the string,
then make a strike connection between the string and the
large mass, and another strike connection between the
finger and the string. This would be computationally
expensive, as well as a pain in the neck. So instead, you
can make a mono-fingerboard connection between the
finger and the string, giving the connection a controller
saying where the “fingerboard” is.
Note that this is a mono-dimensional connection, so you

must do the fingerboard action along the same axis of the
object that you are exciting and listening to. This may
mean that if the object gets really excited, you may hear it
buzz against the fingerboard, which you may or may not
like. (Use the 'bi-fingerboard version to avoid this.)
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_fingerboard_mono.html[28/05/13 15:27:54]
Modalys - Normalised Valve Connection
Guide Map
Modalys Normalised Valve Connection See also

Valve Connection
Summary
An Introduction to Modalys Description Leaky Valve
Getting Started
Connection
This connection simulates the behavior of a reed or valve. The
Objects Normalised Leaky
normalised valve connection has fewer arguments than the
Accesses Valve Connection
valve connection. This is made possible because there is a
Connections Reed Connection
reference force, that of the complete block of the reed on the
1. Force Connection mouthpiece, to which one can normalise all force. Labium Connection
2. Speed Connection Adhere Connection
One-Mass - Mono-
4. Acoustic Hole Connection (make-connection 'normalised-valve ... ) directional (Harmonic
5. Adhere Connection Oscillator)
6. Strike Connection Lisp Syntax and Default Values
7. Pluck Connection The 'normalised-valve connection can be created using
8. Spring Connection the following Lisp syntax:
9. Reed Connection
(make-connection 'normalised-
valve reed_acc reed_pos res_acc
breath_env air-density zeta
Connection front_angle aperture_length
16. Valve Connection Parameters
The 'normalised-valve connection takes nine arguments:
19. Labium Connection reed_acc: access on the object used as a reed.
20. Destroy Connection reed_pos: initial height of the reed. (numerical
21. Get Connection Info value, not a controller)
res_acc: access on the object used as a
Controllers
resonator.
breath-env: the breath envelope controller.
Finite Elements
Appendix
(kg/m^3)
Index
zeta: the “zeta” parameter which influences the
timbre.
front_angle: a controller defining the angle of the
aperture/opening.
aperture_length: a controller defining the length
of the aperture/opening. (m)
interaction.
The initial reed positions must be a numerical value, not a

controller.©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_valve_normalised.html[28/05/13 15:28:38]
Modalys - Normalised Valve Connection
The breath envelope controller is not a real-world

pressure value and typically ranges in value between .3
and 1.8.
The real-world value for air density is 1.2 kg/m^3, on earth

at sea level at room temperature. You might need to play
with this if you wish to blow in other Modalys objects.
The the “zeta” parameter should be a positive non-zero

value. This parameter dramatically influences the timbre
of the resulting sound. Values between 0 and 1 will
dampen higher harmonics considerably. As the value of
zeta increases from 1, the sound will become brighter and
subjectively “buzzier.” A value of 5 is already quite bright.
Common values range between 0.1 and 3.
The aperture angle is given in the system you selected

with set_angle_mode (degrees or radians), and the
aperture length, given in meters, is used to "scale" the
connections.

to 1.
Discussion
The normalised-valve connection is similar to a reed

connection, but allowing greater, more intuitive control
over the brightness of the oscillation, via the zeta
parameter. As with the reed connection, a two-mass,
harmonic oscillator or very small plate may be used as a
reed.
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_valve_normalised.html[28/05/13 15:28:38]
Modalys - Normalised Leaky Valve Connection
Guide Map
Modalys Normalised Leaky Valve See also
Summary Connection Valve Connection
An Introduction to Modalys Normalised Valve

Connection
Getting Started Description
Objects Leaky Valve
This connection simulates the behavior of a reed or valve. The
Accesses Connection
normalised leaky valve connection has fewer arguments than
the leaky valve connection. This is made possible because
1. Force Connection there is a reference force, that of the complete block of the reed Labium Connection
2. Speed Connection on the mouthpiece, to which one can normalize all force. Adhere Connection
One-Mass - Mono-
5. Adhere Connection (make-connection 'normalised-leaky- Oscillator)
6. Strike Connection valve ... )
7. Pluck Connection
8. Spring Connection Lisp Syntax and Default Values
9. Reed Connection The 'normalised-leaky-valve connection can be created
10. Felt Hammer Connection using the following Lisp syntax:
(make-connection 'normalised-
Connection leaky-valve reed_acc reed_pos
14. Bow Connection resonator_acc breath_env air-
15. Bi-Fingerboard Connection density air-viscosity zeta
16. Valve Connection front_angle aperture_width
17. Leaky Valve Connection canal_length under_area weight)
19. Labium Connection Parameters
20. Destroy Connection The 'normalised-leaky-valve connection takes twelve
21. Get Connection Info arguments:
Controllers
reed_acc: access on the object used as a reed.
reed_pos: initial height of the reed. (numerical
Finite Elements
value, not a controller)
Appendix
resonator_acc: access on the object used as a
Index
resonator.
breath-env: the breath envelope controller.
(kg/m^3)
air-viscosity: a controller for the density of air.
(Pa)
zeta: the “zeta” parameter which influences the
timbre.
front_angle: a controller defining the angle of the
aperture/opening.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_valve_leaky_normalised.html[28/05/13 15:29:27]
Modalys - Normalised Leaky Valve Connection
aperture_width: a controller defining the length of

the aperture/opening. (m)
canal_length: a controller defining the length of
the canal length. (m)
under_area: a controller defining the surface of
the under part of the valve. (m^2)
interaction.
The initial reed positions must be a numerical value, not a

controller.
The breath envelope controller is not a real-world

pressure value and typically ranges in value between .3
and 1.8.
The real-world value for air density is 1.2 kg/m^3, on earth

at sea level at room temperature. You might need to play
with this if you wish to blow in other Modalys objects.
The real-world value for air viscosity is around 1.78e-5

Pa.
The the “zeta” parameter should be a positive non-zero

value. This parameter dramatically influences the timbre
of the resulting sound. Values between 0 and 1 will
dampen higher harmonics considerably. As the value of
zeta increases from 1, the sound will become brighter and
subjectively “buzzier.” A value of 5 is already quite bright.
Common values range between 0.1 and 3.
The aperture angle is given in the system you selected

with set_angle_mode (degrees or radians), and the
aperture length, given in meters, is used to "scale" the
connections.

to 1.
Discussion
The normalised-leaky-valve connection is similar to a

reed connection, but allowing greater, more intuitive
control over the brightness of the oscillation, via the zeta
parameter. As with the reed connection, a two-mass,
harmonic oscillator or very small plate may be used as a
reed.
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_valve_leaky_normalised.html[28/05/13 15:29:27]
Modalys - Bow Connection
Guide Map
Modalys Bow Connection See also

String (or Rod) - Bi-
Summary
directional
Getting Started
Two-Mass - Bi-
Two-dimensional bowed connection between four accesses. directional
Objects
Accesses
Connections
(make-connection 'bow ... )
1. Force Connection
The 'bow connection can be created using the following
Lisp syntax:
7. Pluck Connection (make-connection 'bow bow_acc_V
8. Spring Connection bow_acc_H bow-posV str_acc_V
9. Reed Connection str_acc_H str-posV 4D_ctl weight)
The 'bow connection takes eight arguments:
Connection bow_acc_V: vertical access on object used as a
14. Bow Connection bow.
15. Bi-Fingerboard Connection bow_acc_H: horizontal access on object used as
16. Valve Connection a bow.
17. Leaky Valve Connection bow-posV: initial vertical position of the bowing
18. Induction Connection object's access. (numerical value, not a controller)
19. Labium Connection str_acc_V: vertical access on object to be bowed.
20. Destroy Connection str_acc_H: horizontal access on object to be
21. Get Connection Info bowed.
str-posV: initial vertical position of the plucked
Controllers
object's access. (numerical value, not a controller)
4D_ctl: four-dimensional controller containing
Finite Elements
coefficients which simulate the effect of bow rosin.
Appendix
Index
interaction.
The two initial vertical positions must be numerical values,

not controllers. The weight controller is optional. If not
provided, it defaults to 1.
The 4D_controller is a four-dimensional controller

containing coefficients which simulate the effect of bow
rosin. A constant controller with standard suggested
values is: (const 2 10 5 4). The meaning of these is
discussed below.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_bow.html[28/05/13 15:30:12]
Discussion
The best way to understand this is to read the code for

ex6.mos (Example 6). This connection assumes a bi-
directional bowing object and a bi-directional bowed
object. The “vertical” axis on both objects will be used to
determine the downward pressure of the bow on the
string, and the “horizontal” axis on both objects will be
used to determine the relative speeds of the two objects.
Apart from bowed strings, it can be interesting to bow

other things too. To bow a membrane, one could use a
normal access on the membrane as the “horizontal”
direction, and for the vertical direction, one could use a
totally different object for to be bowed...
This connection is extraordinarily delicate; pushing a bit

too hard or using the wrong kind of string can ruin the
sound. Furthermore, as with real-life bowed objects, the
force and speed needed to excite different kinds of
objects changes drastically from object to object.
The 4D controller that simulates the effect of rosin

contains four coefficients that do not relate to the physical
parameters of rosin, but that are rather used to define a
curve (actually, just three line segments that act as a
simplified curve), for force vs. speed. This simplified curve
is used to determine the stick and slip action of the bow.
We suggest you start out using the four standard values 2
10 5 4 when bowing strings. However, if you want to
experiment, you can refer to the following sets of
parameter values as a guideline:
10 30 17 0.5 - extremely slippery: very light and

airy bow interaction
5 20 10 1
4 15 8 2 - light / airy bow interaction
3 12 6 3
2 10 5 4 - "standard" bow interaction parameters
1.6 8 4 5
1.3 6 3 8 - scratchy / sticky bow interaction
1.0 5 2.5 12
0.5 4 2.25 40 - extremely sticky and harsh: highly
scratchy bow interaction
As you can see, the sets of parameters are organized, top

to bottom, from those which result in a very light and airy
sounding bow interaction, to those which result in a
heavy/harsh and scratchy bow interaction. The unlabeled
parameters are intermediate values. Using a value of 10,
or near 10, for the second parameter in any of the above
will smooth out the slope of the curve (it affects the middle
line segment that approximates the curve).
The values 3 7 6 3 are nice parameters for a slightly

lighter sounding bow interaction than is obtained with the
standard settings.
When bowing objects other than strings, you may need to

make some adjustments to the parameters.
Options
Bowing Mono-Directional Objects
Since the bow interaction is designed to work with bi-

directional objects, if you want to bow a mono-directional
object, you need to create a “dummy” object for the
vertical access. Basically, a bi-string is made up of two
mono strings, one that vibrates in the horizontal direction
and the other in the vertical direction as far as the user is
concerned (even though for Modalys these are just 'trans0
and 'trans1). As an experiment you can try creating two
mono-string objects and using one of them for the vertical
access and the other for the horizontal access. As long as
you listen to the string that is being used as the horizontal
access (this is the one receiving the speed of the bow
interaction), it should sound the same as using a bi-string.
Therefore, when bowing an object such as a membrane

an air-column (which each have only one direction of
possible access), you will need to create a second object,
such as a string, on which to make the vertical access for
the bow interaction.
Retro-Compatibility

(make-connection 'bow bow_acc_V

bow_acc_H str_acc_V str_acc_H bow-
posV str-posV 4D_controller)

Modalys - Bi-Fingerboard Connection
Guide Map
Modalys Bi-Fingerboard Connection See also

Mono-Fingerboard
Summary
Connection
Getting Started
Two-Mass - Bi-
Simulates the interaction between and finger and a string with a directional
Objects
fingerboard underneath them (bidirectional version).
Accesses String (or Rod) - Bi-
directional
Connections
1. Force Connection (make-connection 'bi-fingerboard ... )
2. Speed Connection
3. Position Connection Lisp Syntax and Default Values
The 'bi-fingerboard connection can be created using the
7. Pluck Connection
8. Spring Connection (make-connection 'bi-fingerboard
9. Reed Connection fgr_acc_V fgr_acc_H fgr_posV
10. Felt Hammer Connection str_acc_V str_acc_H str_posV
pos_ctl weight)

Connection
The 'bi-fingerboard connection takes eight arguments:
14. Bow Connection
15. Bi-Fingerboard Connection fgr_acc_V: the vertical access on the object used
16. Valve Connection as a “finger”.
17. Leaky Valve Connection fgr_acc_H: the horizontal access on the object
18. Induction Connection used as a “finger” (in the same location as the
19. Labium Connection vertical access).
20. Destroy Connection fgr_posV: initial vertical position value of the
21. Get Connection Info finger access.
str_acc_V: the vertical access on the object used
Controllers
as a “string”.
str_acc_H: the horizontal access on the object
Finite Elements
used as a “string” (in the same location as the
Appendix
vertical access).
Index
str_posV: initial vertical position value of the
string access.
pos_ctl: a controller which specifies the position
of the virtual fingerboard (usually a constant
controller)
interaction.
With this connection the vertical access on the “finger” (its

vertical position with respect to the fingerboard) is used to
decide whether
©IRCAMit is 2013
clamping the string or not (i.e. moving
http://support.ircam.fr/docs/Modalys/current/co/connection_fingerboard_bi.html[28/05/13 15:30:43]
Modalys - Bi-Fingerboard Connection
the finger up and down in this direction clamps and

unclamps the string). The horizontal axis should be at the
same location on the finger as the vertical axis, but in the
other direction of vibration.
Similarly, the vertical and horizontal accesses on the

string should be at the same location along the string, but
in different axes of vibration.
The position controller specifies the position of the

fingerboard over time. Generally speaking, one might
make this controller (const 0), then set str_posV to .01
meters, then set fgr_posV to .02 meters. This controller is
almost always constant, but one might want a moving
fingerboard for an esoteric application.

to 1.
Discussion
When simulating string instruments, you frequently want

to change the pitch of the string by putting a finger down
on a fingerboard somehow. Normally in Modalys, you
would have to create some large mass beneath the string,
then make a strike connection between the string and the
large mass, and another strike connection between the
finger and the string. This would be computationally
expensive, as well as a pain in the neck. So instead, you
can make a mono-fingerboard connection between the
finger and the string, giving the connection a controller
saying where the “fingerboard” is.
Note that this is a bi-dimensional connection. It checks for

the finger clamping the string against the fingerboard
along one axis (vert); when the clamping occurs, it freezes
the finger and string in both axes (vert and hor). This way,
you can pluck the strings along the horizontal axis without
worrying about banging into the fingerboard, and without
getting annoying artifacts from the fingerboard finger's
contact with the string. (If you don't care about this, or if
your objects don't have two vibration directions, you
should use the 'mono-fingerboard connection.)
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_fingerboard_bi.html[28/05/13 15:30:43]
Modalys - Valve Connection
Guide Map
Modalys Valve Connection See also

Normalised Valve
Summary
Connection
Getting Started
Leaky Valve
This connection simulates the behavior of a valve. It can be Connection
Objects
used as well to imitate vibrating lips. Note that you can make it
Accesses Normalised Leaky
with one or two accesses, plus one for the object playing the Valve Connection
Connections
role of the tube.
Reed Connection
1. Force Connection
2. Speed Connection Labium Connection
3. Position Connection (make-connection 'valve ... ) Adhere Connection
One-Mass - Mono-
5. Adhere Connection Lisp Syntax and Default Values directional (Harmonic
6. Strike Connection Oscillator)
The 'valve connection can be created using the following
7. Pluck Connection Lisp syntax:
9. Reed Connection
10. Felt Hammer Connection (make-connection 'valve acc_ref1
acc_pos1 acc_ref2 acc_pos2
tube_acc breath-pressure air-
density under-area front-area
Connection front-angle aperture-length
or:
19. Labium Connection (make-connection 'valve acc_ref1
20. Destroy Connection acc_pos1 tube_acc breath-pressure
21. Get Connection Info air-density under-area front-area
Controllers front-angle aperture-length
The Modalys Workspace weight)
Finite Elements
Appendix Parameters
Index The 'valve connection takes twelve arguments (or ten if
made with two instead of three accesses):
acc_ref1: first access.

acc_pos1: initial position of the first access with
respect to the valve. (numerical value, not a
controller)
acc_ref2: second access.
acc_pos2: initial position of the second access
with respect to the valve. (numerical value, not a
controller)
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_valve.html[28/05/13 15:31:15]
Modalys - Valve Connection
tube_acc: access on the object used as a tube.

breath-pressure: a controller defining the breath
pressure of the air blowing in the valve. (Pascals)
(kg/m^3)
under-area: a controller defining the surface of
front-area: a controller defining the surface of the
front part of the valve. (m^2)
front-angle: the inclination of the valve. (degrees)
aperture-length: a controller defining the length of
interaction.

not controllers.
Typical values for air-pressure range from 0 to 50000 Pa.
The real-world value for air density is 1.2 kg / m^3, on

earth at sea level at room temperature. You might need to
play with this if you wish to blow in other Modalys objects.
Typical values for the surface area of the under part of the
valve are from 1e-14 to 1e-3 m^2.
Typical values for the surface area of the front part of the
valve are also from 1e-14 to 1e-3 m^2.
For the inclination (angle) of the valve, use whatever

system you selected with set_angle_mode. By default, it
is degrees.

to 1.
You can make this connection with either two or three

accesses: it could have two vibrating “lips” or one vibrating
against a static surface, in addition to the object playing
the role of a tube.
Discussion
The valve connection is similar to a reed connection.
[More information forthcoming...]
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_valve.html[28/05/13 15:31:15]
Modalys - Leaky Valve Connection
Guide Map
Modalys Leaky Valve Connection See also

Valve Connection
Summary
An Introduction to Modalys Description Normalised Valve
Getting Started
Connection
This connection simulates the behavior of a valve. It can be
Objects Normalised Leaky
used as well to imitate vibrating lips. Note that you can make it
Accesses Valve Connection
with one or two accesses, plus one for the object playing the
role of the tube. It is slightly different from the standard valve
1. Force Connection connection. Labium Connection
2. Speed Connection Adhere Connection
One-Mass - Mono-
4. Acoustic Hole Connection (make-connection 'leaky-valve ... ) directional (Harmonic
5. Adhere Connection Oscillator)
6. Strike Connection Lisp Syntax and Default Values
7. Pluck Connection The 'leaky-valve connection can be created using the
8. Spring Connection following Lisp syntax:
9. Reed Connection
(make-connection 'leaky-valve
acc_ref1 acc_pos1 acc_ref2
acc_pos2 tube_acc breath-pressure
Connection air-density air-viscosity under-
14. Bow Connection area front-area front-angle
15. Bi-Fingerboard Connection aperture-length canal-length
16. Valve Connection weight)
or:
21. Get Connection Info (make-connection 'leaky-valve
Controllers acc_ref1 acc_pos1 tube_acc breath-
The Modalys Workspace pressure air-density air-viscosity
Finite Elements
under-area front-area front-angle
aperture-length canal-length
Appendix
weight)
Index
Parameters
The 'valve connection takes fourteen arguments (or

twelve if made with two instead of three accesses):
acc_ref1: first access.

acc_pos1: initial position of the first access with
respect to the valve. (numerical value, not a
controller)
acc_ref2: second access.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_valve_leaky.html[28/05/13 15:31:47]
acc_pos2: initial position of the second access

with respect to the valve. (numerical value, not a
controller)
tube_acc: access on the object used as a tube.
breath-pressure: a controller defining the breath
pressure of the air blowing in the valve. (Pascals)
(kg/m^3)
air-viscosity: a controller for the density of air.
(Pa)
under-area: a controller defining the surface of
front-area: a controller defining the surface of the
front part of the valve. (m^2)
front-angle: the inclination of the valve. (degrees)
aperture-length: a controller defining the length of
canal-length: length of the canal.
interaction.

not controllers.
Typical values for air-pressure range from 0 to 50000 Pa.
The real-world value for air density is 1.2 kg / m^3, on

earth at sea level at room temperature. You might need to
play with this if you wish to blow in other Modalys objects.
The real-world value for air viscosity is around 1.78e-5

Pa.
Typical values for the surface area of the under part of the
valve are from 1e-14 to 1e-3 m^2.
Typical values for the surface area of the front part of the
valve are also from 1e-14 to 1e-3 m^2.
For the inclination (angle) of the valve, use whatever

system you selected with set_angle_mode. By default, it
is degrees.

to 1.
You can make this connection with either two or three

accesses: it could have two vibrating “lips” or one vibrating
against a static surface, in addition to the object playing
the role of a tube.
Discussion
The leaky valve connection is similar to a reed

connection.
[More information forthcoming...]
Options
Modalys - Induction Connection
Guide Map
Modalys Induction Connection See also

Strike Connection
Summary
An Introduction to Modalys Description String (or Rod) - Mono-
Getting Started
directional
This connection simulates the interaction between an electromagnet and an
Objects Two-Mass - Mono-
object. The electromagnet is surrounded by a magnetic field, the polarity of
Accesses directional
which is determined by a signal (represented by a controller). Objects close
Connections
enough the fall are affected by it. Note that unlike in the real world, both the
1. Force Connection electromagnet and the resonating object can be of any material,
2. Speed Connection ferromagnetic or otherwise.
7. Pluck Connection
9. Reed Connection
Connection
14. Bow Connection
Controllers
The Modalys Workspace (make-connection 'induction ... )
Finite Elements
Appendix Lisp Syntax and Default Values
Index
The ‘induction connection can be created using the following Lisp
syntax (the default values are shown for each of the physical
parameters):
(make-connection 'induction string-access

electromagnet-access signal-controller
gap
(const 0.01) ;electromagnet

radius
©IRCAM 2013
(const 0.02) ;electromagnet
length
(const 8.737434e-4) ;string

permeability
http://support.ircam.fr/docs/Modalys/current/co/connection_induction.html[28/05/13 15:32:19]
(const 0.0004)) ;string radius
Parameters
The ‘induction connection takes eight arguments:
string-access: access on resonating object

electromagnet-access: access on object acting as the
electromagnet
signal-controller: a controller determining the polarity of the
magnetic field surrounding the electromagnet
gap: a controller specifying the distance between the
electromagnet and the resonating object, in meters
electromagnet radius: radius of the electromagnet, in meters
electromagnet length: length of the electromagnet, in meters
string permeability: constant representing the permeability of
the resonating object
string radius: radius of the resonating object, in meters
The two positions must be numerical values, not controllers. The

weight controller is optional. If not provided, it defaults to 1.
To create a unilateral strike connection, the second access and its

position are not provided.
Discussion
The default values result in a relatively weak interaction. As a result, it

is often desirable to significantly increase either the amplitude of the
input signal or the permeability of the resonating object. It is interesting
to note the connection that results from such a weak force is very
similar to a ‘force connection. Only when the displacement of the
resonating object is very great does the sound differ significantly.
Also note that the induction connection causes the resonating body to
vibrate at twice the frequency of the input signal, or one octave higher.
And finally – due to the mutual attraction between electromagnet and

resonating body, it is helpful to either use objects that are fixed in
space (such as a Circular Membrane – Fixed), or to actively set the
location of each object.
Here is an example of a string moving towards an electromagnet (fixed

in place) until they contact, then moving away:
(setq my-string (make-object 'mono-

string))
(setq my-string-access (make-access my-

string (const .75) 'trans0))
(setq my-electromagnet (make-object

'mono-two-mass))
(setq my-electromagnet-access (make-

access my-electromagnet (const 1)
'trans0))
(setq electromagnet-handle (make-access

my-electromagnet (const 0) 'trans0))
(make-connection 'position electromagnet-

handle (const 0))
(setq my-sine (make-controller 'sine 1

87.3 45))
(setq my-sine-controller (make-controller

'arithmetic 1 "*" my-sine 50))
(setq gap (make-controller 'envelope 1

(list (list 0.0 0.008)
(list 2 0.001)
(list 5 0.008))))
(make-connection 'induction my-string-

access my-electromagnet-access my-sine-
controller gap)
This new type of connection is the result of an IRCAM Musical

Research Residency conducted by Per Bloland in collaboration with
the Instrumental Acoustics Team, especially Joël Bensoam and Robert
Piéchaud.
It is based on the Electromagnetically-Prepared Piano, a device that

consists of a rack of twelve electromagnets that rests on the frame of
a grand piano. Each individual electromagnet unit is positioned directly
over the two or three strings that constitute a single pitch, and is
controlled by an arbitrary external audio signal.
More information can be found at:
http://magneticpiano.com
http://www.perbloland.com
Modalys - Labium Connection
Guide Map
Modalys Labium Connection See also

Jet Object
Summary
An Introduction to Modalys Description Tube - closed/open
Getting Started
This connection simulates the action of a jet against a labium in
Objects
a fipple, creating an air vortex. (Seriously, those are the correct
Accesses
terms, not typos!!)
Connections
1. Force Connection
2. Speed Connection (make-connection 'labium ... )
4. Acoustic Hole Connection Lisp Syntax and Default Values
The 'labium connection can be created using the following
Lisp syntax:
7. Pluck Connection
9. Reed Connection (make-connection 'labium acc_ref
10. Felt Hammer Connection jet_ref noise_ctl vortex_factor
vortex_transition weight)

Connection
The 'labium connection takes six arguments:
14. Bow Connection
15. Bi-Fingerboard Connection acc_ref: access on the object used as a tube.
16. Valve Connection jet_ref: reference to a jet object (the object itself -
17. Leaky Valve Connection not an access!)
18. Induction Connection noise_ctl: a controller for added breath noise.
19. Labium Connection vortex_factor: 3D-controller for the vortex factor
20. Destroy Connection vortex_transition: vortex transition time
21. Get Connection Info weight: (optional) controller weighing the
interaction.
Controllers
The Modalys Workspace A reference to an actual jet object - not to an access -
Finite Elements must be given as a second argument.
Appendix
A noise controller can be added to provide additional
Index
noisiness (or a constant controller of 0 can be provided
for no noise).
The vortex factor is a 3-dimensional controller for

parameters of the vortex. The first two are parameters
which control the vortex (on either side of the labium), and
the last of the three controls vortex amplitude. A constant
controller with appropriate values is (const 4.99 .1 1).
A controller with an appropriate value for the vortex

transition time is (const 0.005).
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_labium.html[28/05/13 15:32:52]
Modalys - Labium Connection

to 1.
Discussion
The labium connection works with the jet object to make a

vortex, or whirlpool, of air when the jet stream hits the
labium.
Unlike a lot of other connections in Modalys, such as the

reed and various valve connections, the jet object
receives the breath envelope controller as an argument,
and the labium connection uses the jet object as an
argument. A simple example of this is shown, below:
(setq breath-env (make-controller

'envelope 1 '((0 0) (0.1 100) (1
100) (1.1 0))))
(setq jet (make-object 'jet

(pressure breath-env)))
(setq tube (make-object 'closed-

open-tube))
(setq tube-acc (make-access tube

(const 0) 'long))

jet (const 0) (const 4.99 .1 1)
(const 0.005))
(setq tube-out (make-access tube

(const .9) 'long))
(make-point-output tube-out)
Options
Noise Controller
Adding a noise controller to the labium connection adds

realism to the synthesis. A noise controller such as the
following can be used:
(setq noise-ctl (make-controller

'arithmetic 1 '* (list (const 10)
(make-controller 'random 1 1e-
5))))

jet noise-ctl (const 4.99 .1 1)
(const 0.005))
http://support.ircam.fr/docs/Modalys/current/co/connection_labium.html[28/05/13 15:32:52]
Modalys - Destroy Connection
Guide Map
Modalys Destroy Connection See also

Get Connection
Summary
Information
Getting Started
Freeze Object
Destroys a connection.
Objects
Accesses
Connections
1. Force Connection
The (destroy-connection ... ) function can be used via the
7. Pluck Connection (destroy-
8. Spring Connection connection connection_reference )
9. Reed Connection
10. Felt Hammer Connection Parameters
The (destroy-connection ...) function takes one argument:
13. Normalised Leaky Valve connection_reference: any connection.
Connection
14. Bow Connection
Discussion
16. Valve Connection This function should be used with care, as it is tricky to
use. It is useful if you are writing a Modalys component
and you want it to be very efficient, or if you are trying to
make an overly slow synthesis run a bit faster. The idea is
if you make a “pluck” connection between two objects,
they are always “watching” each other. The “watching”
takes a certain amount of computation time, and
Controllers
continues even when you know the objects cannot
possibly touch because the pluck is finished. (Modalys
Finite Elements can never know for sure whether the objects will touch
Appendix again, since the plucker could always return for another
Index pluck...) So you can write:
(define my-connection (make-

connection 'pluck ... ))
...
(run 3) ; we know the pluck

happens during these 3 seconds of
synthesis
©IRCAM 2013
(destroy-connection my-connection)
http://support.ircam.fr/docs/Modalys/current/co/connection_destroy.html[28/05/13 15:33:25]
Modalys - Destroy Connection
(run 1)
This will create 4 seconds of synthesis, and there will be

some speedup after the third second. Note that this
speedup is not enormous, and is often not worth the
trouble. You see, if the pluck has not quite finished by the
third second, you may get a click or something as the
objects are forcibly separated! Any type of connection can
be destroyed this way, except force connections. There is
usually no point to destroying force connections anyway
as they are very inexpensive computationally. Note that a
'force connection with a controller value of zero newtons
has no influence whatsoever on an object.
In some cases, you might want to first test to see if a

connection is currently active or inactive before you
destroy it. To do this you could use:
(get-info 'connection my-

connection 'state)
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_destroy.html[28/05/13 15:33:25]
Modalys - Get Connection Info
Guide Map
Modalys Get Connection Information See also

Summary
An Introduction to Modalys Description Get Access Information
Getting Started Get Controller
Get information about a connection using (get-info ...).
Objects Information
Accesses Get Workspace
Connections Information
1. Force Connection
connection-specific information using the following Lisp
syntax:
7. Pluck Connection
8. Spring Connection (get-info
9. Reed Connection 'connection connection_reference
10. Felt Hammer Connection data_type)
12. Normalised Valve Connection Parameters
13. Normalised Leaky Valve The (get-info 'connection ... ) function takes one
Connection
argument:
14. Bow Connection
15. Bi-Fingerboard Connection connection_reference: any connection.
16. Valve Connection data_type: a symbol defining the type of
17. Leaky Valve Connection connection data we want to obtain.
19. Labium Connection Discussion
Although the (get-info ... ) command is a general-purpose
command used throughout the Modalys environment, we
Controllers
are describing its use specifically as it relates to
connections here.
Finite Elements
Appendix This function allows you to query a connection for
Index
potentially useful information. The following data types
may be used:
'state (returns 1 if currently active/connected, 0 if

inactive/not connected)
'speed
'position
'force
The following data types are used for bi-directional

connections like 'bow
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/connection_info_get.html[28/05/13 15:34:05]
Modalys - Get Connection Info
'speed-horizontal
'speed-vertical
'position-horizontal
'position-vertical
'force-horizontal
'force-vertical
Options
http://support.ircam.fr/docs/Modalys/current/co/connection_info_get.html[28/05/13 15:34:05]
Modalys - Constant Controller
Guide Map
Accesses Constant Controller See also

Envelope Controller
Connections
Controllers Description Dynamic Controller
1. Constant Controller This is a controller which outputs a constant, i.e. unchanging,

2. Envelope Controller value.
3. Access Speed Controller
4. Access Position Controller
5. Access Force Controller (make-controller 'constant ... ) / (const ...
6. Connection State Controller )
7. Last Sample Controller
8. Sound File Controller Lisp Syntax and Default Values
9. MIDI File Controller The 'constant controller can be created using the following
10. Dynamic Controller Lisp syntax:
11. Send Message
12. Set Breakpoint
(make-controller 'constant
dimension value ... )
15. Arithmetic Controller
16. Expression Controller or:
18. Sine Controller
(make-controller 'constant
dimension list )
20. Band-Limited Noise Controller
21. Noise (Band-Limited Impulse)
Controller
or:
23. Bilinear (First Order IIR) Filter
24. Biquadratic (Second Order IIR) (const value ... )
Filter
(Bandpass) Filter
or:
26. Variable Second Order
(Bandpass) Filter
(const list )
28. Sum Controller
29. Spread Controller
Parameters
30. Get Controller Info
The Modalys Workspace The 'constant controller takes the following arguments:
Finite Elements
dimension: number of values the controller will
Appendix
output.
Index value: the value(s) output by the controller at any
given time.
list: a list of value(s) output by the controller at
any given time.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_constant.html[28/05/13 15:34:54]
The constant controller is one of the most commonly-used

controllers in Modalys. It outputs a constant, unchanging,
value in all dimensions.
The number of values given depends on the dimension. If

the number of values exceeds the dimension given, only
the required number of values is used. If the number of
given values is less than the dimension, the remaining
dimensions are filled with controllers whose value is zero.
Although it can be created using the standard (make-

controller ... ) syntax, it has a convenient shorthand
version (const ... ) that is more convenient and thus more
often used.
On occasion, a numerical value may be provided in the

place of a constant controller for some, but not all,
Modalys functions.
Discussion
The controller's constant value(s) may be given as a

series of individual values as arguments, or as a list:
(make-controller 'constant 3 50 60
70)
or:
(make-controller 'constant 3 '(50

60 70))
When using the shorthand version (const ... ) the number

of dimensions is automatically calculated from the number
of arguments given:
(const 50 60 70)
or:
(const '(50 60 70))
The above examples are all equivalent and can be used

to create a 3-dimensional constant controller outputting
50, 60 and 70 in its three dimensions. The third of these
examples is the easiest and therefore is the
recommended way to create a controller.
Most often the (const ... ) function is used to create a

simple one-dimensional controller such as the following
example which outputs the value 0.36 at all times:
(const 0.36)
Options
There are no special options for this controller.
Modalys - Envelope Controller
Guide Map
Accesses Envelope Controller See also

Dynamic Controller
Connections
Controllers Description String (or Rod) - Mono-
directional
1. Constant Controller A break-point envelope controller.
2. Envelope Controller
5. Access Force Controller
6. Connection State Controller
10. Dynamic Controller
11. Send Message
12. Set Breakpoint
(make-controller 'envelope ... )
16. Expression Controller Lisp Syntax and Default Values
An 'envelope controller can be created using the following
18. Sine Controller
Lisp syntax:
21. Noise (Band-Limited Impulse) (make-controller 'envelope
Controller dimension
23. Bilinear (First Order IIR) Filter (list (list time1
24. Biquadratic (Second Order IIR) value value ... )
Filter
(list time2
(Bandpass) Filter value value ... )
(Bandpass) Filter
... ) )
28. Sum Controller Parameters
The 'envelope controller takes the following arguments:
The Modalys Workspace dimension: number of values controlled by the
Finite Elements envelope.
Appendix
time1, time2, etc...: the absolute times of the
breakpoints.
Index
value: the value(s) output by the controller at the
given time.
The number of values given for each associated time will

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_envelope.html[28/05/13 15:35:44]
Modalys - Envelope Controller
depend on the dimension of the controller.
Discussion
The envelope controller follows a predetermined course

from value to value in a given amount of time. Values
which fall between those which are specified in the list are
interpolated. Thus if we specify that at time zero, the value
output by the controller will be one, and at time one, the
value will be zero, the value at time .5 will be .5 and the
value at time .4 will be .6, etc. Note that time1, time2,
time3, etc. are in absolute synthesis time and not relative
time. If, for example, one wants to set a breakpoint every
second for five seconds, the times are 0 1 2 3 4 5, and not
1 1 1 1 1.
Here is an example showing a typical ADSR envelope

over 2 seconds of time (its graph is shown at the top of
this page):
(make-controller 'envelope 1
'( (0 0.0)
(0.2 1.0)
(0.4 0.7)
(1.2 0.7)
(2 0) ) )
Naturally, in Modalys, the envelope controller is used not

for amplitude envelopes but to control other types of
dynamically changing parameters, such as the position of
a hammer, or the location of an access on an object.
Options
http://support.ircam.fr/docs/Modalys/current/co/controller_envelope.html[28/05/13 15:35:44]
Modalys - Access Speed Controller
Guide Map
Accesses Access Speed Controller See also

Access Force
Connections
Controller
Controllers Description
Access Position
1. Constant Controller This is a controller which outputs the speed of vibration of a Controller
2. Envelope Controller given access. Connection State
Controller
Force Connection
6. Connection State Controller Speed Connection
7. Last Sample Controller Position Connection
8. Sound File Controller Get Access Information
11. Send Message
12. Set Breakpoint
(make-controller 'access-speed ... )
17. Foreign-Call Controller Lisp Syntax and Default Values
18. Sine Controller
The 'access-speed controller can be created using the
Controller (make-controller 'access-speed
dimension access_reference)
Filter
Parameters
25. Constant Second Order The 'access-speed controller takes two arguments:
(Bandpass) Filter
26. Variable Second Order dimension: number of dimensions of the
(Bandpass) Filter
controller (in this case, 1).
28. Sum Controller
29. Spread Controller The dimension for this controller should be set to 1.
The Modalys Workspace Discussion
Finite Elements
The Access Speed Controller is an easy way of getting
Appendix
the speed of a given access on an object every sample,
Index and using it as a controller. It is especially useful for
simulating sympathetic vibration of objects, since the
output sound of an object is generated by the object's
speed. Therefore when using a 'force interaction for
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_access_speed.html[28/05/13 15:36:33]
Modalys - Access Speed Controller
sympathetic vibration and resonance, you should use the

access' speed, and this controller makes it easy to do so.
The following example takes the pluck from Modalys

example 1 and uses the access speed of the the string to
excite the plate from Modalys example 2 (instead of using
a strike connection):
(setq force-ctl (make-controller

'access-speed 1 my-string-plk))
(make-connection 'force my-plate-

hit force-ctl)
This results in a very different sound from using an

'access-force or 'access-position controller.
The image at the top of this page shows force, position

and speed controllers obtained from the plucked access
on the string and a position controller from the plucking
access on the plectrum as given in the Modalys plucked
string example.
Options
Retro-Compatibility
In a lot of older Modalys scripts (those made before this

function was added) the (get-info ... ) function was used
with a 'foreign-call controller (formerly called a 'scheme
controller) to create a controller outputting an access'
speed. It is suggested you update such old scripts to use
the new syntax, since the calculation time will be
significantly faster.
This is an example of how this had formerly been

achieved using the 'foreign-call (or, even earlier, 'scheme)
controller:
0
(lambda (ins outs)
(vset outs 0
(get-info 'speed access-ref)))
'())

more computationally expensive.
http://support.ircam.fr/docs/Modalys/current/co/controller_access_speed.html[28/05/13 15:36:33]
Modalys - Access Position Controller
Guide Map
Accesses Access Position Controller See also

Access Force
Connections
Controller
Access Speed
1. Constant Controller This is a controller which outputs the position of a given access. Controller
Connection State
Controller
Force Connection
11. Send Message
12. Set Breakpoint
(make-controller 'access-position ... )
The 'access-position controller can be created using the
18. Sine Controller
21. Noise (Band-Limited Impulse) (make-controller 'access-position
Controller dimension access_reference)
Parameters
Filter The 'access-position controller takes two arguments:
(Bandpass) Filter dimension: number of dimensions of the
26. Variable Second Order controller (in this case, 1).
(Bandpass) Filter
28. Sum Controller The dimension for this controller should be set to 1.
30. Get Controller Info Discussion
The Access Position Controller is an easy way of getting
Finite Elements
the position of a given access on an object every sample,
Appendix
and using it as a controller. When using a 'force
Index connection, you will generally want to use the access'
speed, not its position. Nonetheless, the position could
also be used for a variation in the resulting timbre.
The following example

©IRCAM 2013takes the pluck from Modalys
http://support.ircam.fr/docs/Modalys/current/co/controller_access_position.html[28/05/13 15:37:17]
Modalys - Access Position Controller
example 1 and uses the access position of the the string

to excite the plate from Modalys example 2 (instead of
using a strike connection):

'access-position 1 my-string-
plk))

hit force-ctl)

'access-force or 'access-speed controller.

string example.
Options
Retro-Compatibility
In a lot of older Modalys scripts (those made before this

function was added) the (get-info ... ) function was used
with a 'foreign-call controller (formerly called a 'scheme
controller) to create a controller outputting an access'
position. It is suggested you update such old scripts to
use the new syntax, since the calculation time will be
significantly faster.
This is an example of how this had formerly been

achieved using the 'foreign-call (or, even earlier, 'scheme)
controller:
0
(lambda (ins outs)
(vset outs 0
(get-info 'position access-ref)))
'())

more computationally expensive.
http://support.ircam.fr/docs/Modalys/current/co/controller_access_position.html[28/05/13 15:37:17]
Modalys - Access Force Controller
Guide Map
Accesses Access Force Controller See also

Access Speed
Connections
Controller
Access Position
1. Constant Controller This is a controller which outputs the interaction force of a Controller
2. Envelope Controller connection at an access. Connection State
Controller
Force Connection
11. Send Message
12. Set Breakpoint
(make-controller 'access-force ... )
18. Sine Controller
The 'access-force controller can be created using the
Controller (make-controller 'access-force
dimension access_reference)
Filter
Parameters
25. Constant Second Order The 'access-force controller takes two arguments:
(Bandpass) Filter
26. Variable Second Order dimension: number of dimensions of the
(Bandpass) Filter
controller (in this case, please use 1).
28. Sum Controller
29. Spread Controller The dimension for this controller should be set to 1.
The access referenced must have connection associated
with it.
Finite Elements
Appendix
Discussion
Index
This is a controller which outputs the interaction force of a
connection at an access. It could be used, for example, to
acquire the force exerted by one connection and apply it
to another©IRCAM
object using
2013a 'force controller, as in the
http://support.ircam.fr/docs/Modalys/current/co/controller_access_force.html[28/05/13 15:37:50]
Modalys - Access Force Controller
following example, which takes the pluck from Modalys

example 1 and uses the interaction force from the string to
excite the plate from Modalys example 2 (instead of a
strike connection):

'access-force 1 my-string-plk))

hit force-ctl)

'access-speed or 'access-position controller.

string example.
Options
Retro-Compatibility
This was formerly called (make-controller 'connection-

force ... ) and operated on a connection, instead of an
access. A handful of very ancient Modalys scripts may
need to be updated to use the new syntax.
http://support.ircam.fr/docs/Modalys/current/co/controller_access_force.html[28/05/13 15:37:50]
Modalys - Connection State Controller
Guide Map
Accesses Connection State Controller See also

Access Force
Connections
Controller
Access Speed
1. Constant Controller This is a controller which outputs the active/inactive state of a Controller
2. Envelope Controller connection. Access Position
Controller
Force Connection
11. Send Message
12. Set Breakpoint
(make-controller 'connection-state ... )
18. Sine Controller
The 'connection-state controller can be created using the
Controller (make-controller 'connection-
state dimension
connection_reference)
Filter
25. Constant Second Order Parameters
(Bandpass) Filter
The 'connection-state controller takes two arguments:
(Bandpass) Filter
dimension: number of dimensions of the
controller (in this case, please use 1).
28. Sum Controller
connection_reference: an reference to a
connection.
The Modalys Workspace The dimension for this controller should be set to 1.
Finite Elements
Appendix Discussion
Index
This controller outputs the active/inactive state of a
connection. The controller value is 0 when the connection
is inactive (objects are not interacting), and 1 when the
connection is active (objects are touching/interacting). It
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_connection_state.html[28/05/13 15:38:21]
Modalys - Connection State Controller
could be used, for example, to modify the values of some

parameters based on whether on or not two connected
objects are touching. Obviously to use it, the connection
itself must be given a variable name, as shown in the
following example, which uses the pluck connection in
Modalys example 1, and makes a controller from the
connection state (and shown in the graph, above):
(setq my-connection (make-

connection 'pluck my-string-plk 0
my-plectrum-plk .1 (const 50)))
(setq my-state-ctl (make-

controller 'connection-state 1
my-connection))
Options
http://support.ircam.fr/docs/Modalys/current/co/controller_connection_state.html[28/05/13 15:38:21]
Modalys - Last Sample Controller
Guide Map
Accesses Last Sample Controller See also

Delay Controller
Connections
Controllers Description Signal Controller
1. Constant Controller Sound File Controller

A controller that always returns the last sample output by the
2. Envelope Controller system. (currently appears to be broken)
5. Access Force Controller (make-controller 'last-sample ... )
7. Last Sample Controller Lisp Syntax and Default Values
The 'last-sample controller can be created using the
9. MIDI File Controller following Lisp syntax:
11. Send Message
12. Set Breakpoint (make-controller 'last-sample
dimension)

15. Arithmetic Controller Parameters
16. Expression Controller The 'last-sample controller takes just one argument:
dimension: number of dimensions of the
18. Sine Controller
controller (see note, below).
20. Band-Limited Noise Controller The dimension for this controller must match the number
21. Noise (Band-Limited Impulse) of audio output channels being calculated (see the set-
Controller
number-of-channels command).
Discussion
Filter This controller always returns the last sample(s) that were
25. Constant Second Order output by the system, using the (make-point-output ... )
(Bandpass) Filter
function. The dimension of the controller must be the
(Bandpass) Filter same as the number of output channels. This controller
27. Dimension-Mapping Controller might be useful for writing a 'foreign-call controller to
28. Sum Controller make decisions based on the presence of output sound,
29. Spread Controller or using the output sound in a feedback loop to excite
30. Get Controller Info other objects. In this case the default feedback delay time
would naturally be one sample, unless the controller were
delayed with (make-controller 'delay ... ).
Finite Elements
Appendix To use this controller, you must first define the number of
Index output channels using the (set-number-of-channels ... )
command, even when only synthesizing the default one
channel of sound.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_sample_last.html[28/05/13 15:38:54]
Modalys - Last Sample Controller
Options
http://support.ircam.fr/docs/Modalys/current/co/controller_sample_last.html[28/05/13 15:38:54]
Modalys - Sound File Controller
Guide Map
Accesses Sound File Controller See also

Connections
Controllers Description Signal Controller
1. Constant Controller Outputs the the signal read from a sound file (or portion of a
2. Envelope Controller sound file) as a controller, optionally changing its sampling rate.
11. Send Message
12. Set Breakpoint
(make-controller 'sound-file ... )
18. Sine Controller
The 'sound-file controller can be created using the
Controller (make-controller 'sound-file
dimension period samplerate
filename offset length taps)
Filter
(Bandpass) Filter
The 'sound-file controller takes seven arguments:
(Bandpass) Filter
dimension: number of input and output channels.
period: the time between the controller's value
28. Sum Controller
updates. If zero is given then it updates every
sample.
samplerate: controller specifying the sample rate
The Modalys Workspace in Hz.
Finite Elements filename: pathname of sound file to be read. (in
Appendix quotes.)
Index offset: offset form the beginning of the sound file,
in seconds.
length: length of sound to be read from file, in
seconds
©IRCAM
taps: integer2013
number of taps used in the
http://support.ircam.fr/docs/Modalys/current/co/controller_file_sound.html[28/05/13 15:39:26]
resampling filter (an even integer not less than 4).
The dimension should correspond to the number of

channels in the sound file. This will also also be used as
the number of dimensions of the resulting Modalys
controller.
The period is the time between the updates of the output

of the resampling filter, in synthesis seconds (i.e. seconds
from the point of view of Modalys and the synthesis it is
calculating). As with all periodic controllers in Modalys, if
zero is given then it updates every sample.
The samplerate parameter is a controller corresponding to

the sample rate at which the sound file will be read.
Naturally, if you want to read the sound file at "normal"
speed, you can simply use a constant controller with the
appropriate sampling rate. You can also read the file with
variable playback speed, if you so desire.
The pathname of the soundfile should be provided in

quotes. The path is relative to the Modalys application,
unless it begins with a slash, in which case it is an
absolute path from the root directory of the hard disk. The
syntax for the path follows the syntax rules of your
operating system.
The offset is the point at which we start reading the sound

file, in seconds, with respect to the sample rate of the
sound file (as read from its header). This allows you start
at an arbitrary point in the sound file, instead of always
starting from the beginning.
The length parameter is the length of sound to be read

from the offset point in the file, in seconds, with respect to
the sample rate of the sound file (as read from its header).
The offset and the length parameters can be used to
select a certain region in the sound file. When the sound-
file controller reaches the end of the file it returns sample
values of zero from that point onward. (i.e. it does not
report an error.)
The number of filter taps for the reconstruction of the

resampled sound can be chosen. This parameter has an
effect on the quality of the resampling (but remember that
the computation time increases with the square of taps). A
good value for taps is 30. If you are not not changing the
sampling rate, and the sound file's sampling rate is the
same as the synthesis, then a smaller value can probably
safely be used - down to a minimum of 4.
Discussion
The sound-file controller can be used to read control

samples stored in sound files. This is useful when working
with external excitations or to save computation time by
reusing control data generated once. The sound-file
controller is a periodic controller, i.e. it is only activated

after each period. The samples in sound file between
periods are skipped. Like all periodic controllers the
sound-file controller uses a one sample period if 0 is
passed as period length. This will most often be the case
when using the sound-file controller. Here is a practical
example of using the sound-file controller with a force
connection to excite a string (this one-second sound file
controller is shown in the image at the top of this page):

'mono-string))
(setq my-string-acc (make-access

(setq soundfile-ctl (make-

controller 'sound-file 1 0
(const 44100)
"Examples/sound/fl.taps.aiff"
0 1 30))
(make-connection 'force my-

string-acc soundfile-ctl)
A stereo sound file should be dealt with this way (this also
shows an example of an absolute path):
(make-controller 'sound-file 2 0
(const 44100)
"/my-disk/my-dir/my-
sound.aiff"
0 2 30))
Options
File Pathnames
More informaiton on file paths coming soon.....
Modalys - MIDI File Controller
Guide Map
Accesses MIDI File Controller See also

Dynamic Controller
Connections
Controllers Description Scale Controller
1. Constant Controller Sound File Controller

Imports a Standard (Type 0) MIDI File, parses its data, and
2. Envelope Controller outputs a controller from a list of specified data types.
11. Send Message
12. Set Breakpoint
(make-controller 'midi-file ... )
18. Sine Controller
The 'midi-file controller can be created using the following
Lisp syntax:
Controller (make-controller 'midi-file
dimension filename channel
23. Bilinear (First Order IIR) Filter data_type_list)
Filter
(Bandpass) Filter
The 'midi-file controller takes four arguments:
(Bandpass) Filter
dimension: the number of output dimensions for
the controller.
28. Sum Controller
filename: pathname of MIDI file to be read. (in
quotes.)
30. Get Controller Info channel: the MIDI channel you want to extract
The Modalys Workspace data from (1-16).
Finite Elements data_type_list: a list of symbol and/or numbers
Appendix defining what MIDI data will be used
Index
The pathname of the MIDI file should be provided in
quotes. The path is relative to the Modalys application,
unless it begins with a slash, in which case it is an
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_file_midi.html[28/05/13 15:39:58]

operating system. The MIDI file itself should be a Type 0
(single track) MIDI file - multi-track (Type 1) MIDI files are
not yet supported.
The channel parameter corresponds to the MIDI channel

you want to extract data from. (There is currently no
"omni" mode; to get this effect you'd have to make one
midi controller for each channel, then write a 'foreign-call
controller that merged all the data.)
The number of elements in the list given as the

data_type_list should be the same as the number of
dimensions in the controller. The list may be composed of
MIDI data types, or numerical values, which represent
MIDI continuous controller numbers. (More detailed
information about this is given, below.)
Discussion
The MIDI File Controller allows you to read information

from a Standard (Type 0) MIDI File and output it as a
Modlays controller. A Basic example would be the
following, which reads the Modulation Wheel MIDI
Continuous Controller (MIDI controller 1) data from MIDI
channel 1:
(make-controller 'midi 1 "/my-

disk/my-folder/my-file.mid" 1
(list 1))
And the following example creates a 2-dimensional

controller from MIDI continuous controller 2 (in this case a
WX7 breath controller) and the MIDI note-on velocity data
from the same file (both dimensions are graphed in the
image, shown above):
(setq my-midi-ctl (make-

controller 'midi-file 2
"Examples/midi/wx7-staccato.mid" 1
(list 2 'lastvelocity)))
As you can see, in addition to a numerical value

representing a MIDI controller number, the other MIDI
data tags can be used in the list to read that data from the
file. The complete list of tags is:
'pitchbend
'aftertouch
'noteon
'noteoff
'lastnote
'lastvelocity
Note that 'lastnote and 'lastvelocity are not standard MIDI

data types, but specific to this Modalys controller. The
'lastnote type designates here the last note-on or note-off
that has been activated, and 'lastvelocity is the velocity of
the 'lastnote.
If you want a midi-file controller with 3 dimensions, you

specify the name of the file to read from, then you specify
what MIDI channel you want to read from the file; finally
you specify what 3 kinds of data you want to extract from
the file. You can extract a separate MIDI data stream for
each dimension of this controller, for example:
(make-controller 'midi 3 "my-

file.mid" 1 (list 'pitchbend 13
'aftertouch))
This means a three dimensional controller, reading from

MIDI channel 1, and of the 3 dimensions of the output, the
first is the position of the pitch bend, the second is the
value of continuous controller number 13, and the third is
the value of the aftertouch — all output values are from 0
to 127.
Obviously, you can make several independent 'midi-file

controllers in Modalys by reading the same MIDI file
multiple times - once for each controller. You might do this
if you want to use pitch bend data in one place, and
continuous controller data some other place, etc... This
saves you the hassle of needing to use the 'dimension-
mapping controller to extract individual dimensions from a
multi-dimensional controller.
Options
File Pathnames
More information on file paths coming soon.....
Retro-Compatibility
This controller was formerly called (make-controller 'midi

... ). Older Modalys scripts should be updated accordingly.
Modalys - Dynamic Controller
Guide Map
Accesses Dynamic Controller See also

Send Message
Connections
Controllers Description Set Breakpoint
1. Constant Controller Envelope Controller

A controller whose value can be dynamically changed either in
2. Envelope Controller real-time using OSC (Open Sound Control) messages, or Signal Controller
3. Access Speed Controller between (run) statements at the whim of the user (or a foreign-
4. Access Position Controller call controller!), using (send-message ... ) or (set-breakpoint ...
5. Access Force Controller ) to create a ramp to a given value over a certain amount of
6. Connection State Controller time.
11. Send Message
12. Set Breakpoint
18. Sine Controller
19. Random Controller (make-controller 'dynamic ... )
21. Noise (Band-Limited Impulse) Lisp Syntax and Default Values
Controller
22. Delay Controller The 'dynamic controller can be created using the following
23. Bilinear (First Order IIR) Filter Lisp syntax:
Filter
(make-controller 'dynamic
(Bandpass) Filter dimension period (list
26. Variable Second Order initial_values ... ) message_name)
(Bandpass) Filter
Parameters
28. Sum Controller
29. Spread Controller The 'dynamic controller takes four arguments:
dimension: number of dimensions of the output
The Modalys Workspace controller.
Finite Elements period: sampling period (seconds).
Appendix initial_values: a list of initial (default) values for
Index the controller.
message_name: the OSC or Modalys message
name to listen to, in quotes.
As always,©IRCAM
a sampling
2013period of 0 indicates that the
http://support.ircam.fr/docs/Modalys/current/co/controller_dynamic.html[28/05/13 15:40:29]
controller will be updated every sample. Additionally, you

can provide a value of -1 for the sampling period to
indicate that the controller will be updated only when it
receives a new message (this is more efficient than
forcing the dynamic controller to update every sample).
The number of initial values should correspond to the

number of dimensions.
When using the dynamic controller to receive OSC

messages, the message name should be given as a
string, i.e in quotes: "button1", etc...
Discussion
There are two ways a dynamic controller may be used.

The "traditional" way, from the days before computers
were fast enough to compute samples in real-time, is to
instantiate the controller and then send messages to it,
using (send-message ...) in-between (run) statements.
First the controller is defined, with a message name as a
final argument:
(setq my-dynamic-ctl (make-

controller 'dynamic 1 0 '(0)
"env1"))
Using the message name as a final argument allows the

controller to be typed directly into other Modalys
functions, without needing to use (setq ... ) to create a
reference to it. The following series of runtime statements
will create the breakpoints shown in the graph, above.
(run 0.25) ; run for 250 ms. the

controller will be at the default
value
(send-message "env1" 1 0.5) ; send

a message to move the dynamic
controller to 1 over 500 ms.

controller will begin to ramp
upward to its destination value
(send-message "env1" -1 0.5) ;

controller will be interrupted at
current value and a new ramp
initiated from that point.

controller will ramp downwad to
its destination value
(send-message "env1" 1) ;
controller will jump to a value of
1 immediately (since no ramp time

is provided)

controller will remain at the
value 1
(send-message "env1" -1 0.5) ;

message to move the dynamic
controller to -1 over 500 ms.
(run 0.5)
This "runtime" functionality is still useful when testing out

"instruments" inside the Lisp environment, before
exporting them to a .mlys file to be used in real-time.
Formerly, the (set-breakpoint ...) function was used to set

the ramp, Although this function still exists and can be
used (It is documented below), we recommend using
(send-message ...), instead.
In real-time contexts (such as when using modalys~ in

Max/MSP or when using the (run-real-time) command
within the Lisp implementation of Modalys) can also
receive these messages using OSC (Open Sound
Control). You will need to set the IP port to the same one
on which OSC messages are being sent, such as port
4000, as in this example:
(listen-ip-port 4000)
(run-real-time)
Options
Retro-Compatibility
The set-breakpoint command was formerly used in place

of (send-message ...) Although you may still use it, we
recommend using the new syntax. In the old syntax, the
dynamic controller can optionally be instantiated without a
message name:
(setq my-ctl (make-controller

'dynamic dimension period (list
initial_values ... )))
The set-breakpoint command is then used to change the

controller values. Its syntax is as follows:
(set-breakpoint
name_of_dynamic_controller
(list
time_to_reach_destination value
value ... ))
As an example, the above example would be written like

this:

controller will be at the default
value
(set-breakpoint my-ctl 0.5 1) ;

send a message to move the dynamic
controller to 1 over 500 ms.

controller will begin to ramp
upward to its destination value
(set-breakpoint my-ctl 0.5 -1) ;

controller will be interrupted at
current value and a new ramp
initiated from that point.

controller will ramp downwad to
its destination value
(set-breakpoint my-ctl 0 1) ;
controller will jump to a value of
1 immediately (since ramp time is
set to 0)

controller will remain at the
value 1
(set-breakpoint my-ctl 0.5 -1) ;

message to move the dynamic
controller to -1 over 500 ms.
(run 0.5)
One advantage of using set-breakpoint is that it can easily

control multi-dimensional controllers.
Additionally, there was briefly an 'osc controller using the

same syntax as the dynamic controller. Its functionality
has been merged into the dynamic controller. Old scripts
should therefore be updated to use the dynamic
controller, instead.
Modalys - Send Message
Guide Map
Accesses Send Message See also

Dynamic Controller
Connections
Controllers Description Set Breakpoint

Function that sends a new target value to a dynamic controller.
2. Envelope Controller Signal Controller
4. Access Position Controller (send-message ... )
6. Connection State Controller Lisp Syntax and Default Values
The (send-message ... ) command can be invoked using
the following Lisp syntax:
11. Send Message (send-message message_name
12. Set Breakpoint destination_value ramp_time ))
14. Scale Controller Parameters
15. Arithmetic Controller The (send-message ...) function takes three arguments:
message_name: the OSC or Modalys message
name to listen to, in quotes.
18. Sine Controller
destination_value: new target value for the
dynamic controller.
ramp_time: the time that the dynamic controller
Controller
will take to get from where it is to the new value.
Note that destination value is given before the ramp time,
unlike the older set-breakpoint function, where the ramp
time is given first.
Filter
(Bandpass) Filter Discussion
(Bandpass) Filter The send-message command allows you to change the
27. Dimension-Mapping Controller value of a dynamic controller at synthesis time. This
28. Sum Controller command is discussed in detail in the reference pages for
29. Spread Controller the dynamic controller.
Finite Elements Options
Appendix
Index There are no special options for this function.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_dynamic_message.html[28/05/13 15:41:01]
Modalys - Set Breakpoint
Guide Map
Accesses Set Breakpoint See also

Dynamic Controller
Connections
Controllers Description Send Message

Function that sends new target value(s) to a dynamic controller.
2. Envelope Controller Signal Controller
4. Access Position Controller (set-breakpoint ... )
6. Connection State Controller Lisp Syntax and Default Values
The (set-breakpoint ...) command can be invoked using
the following Lisp syntax:
11. Send Message (set-breakpoint
12. Set Breakpoint controller_reference (list
ramp_time list_of_values ))

16. Expression Controller The (set-breakpoint ...) function takes three arguments:
controller_reference: dynamic controller to which
18. Sine Controller
message is sent.
ramp_time: the time that the dynamic controller
will take to get from where it is to the new value(s).
Controller
list_of_values: new target values for the dynamic
22. Delay Controller controller.
The number of values in the list of values is dependent on
the number of dimensions of the dynamic controller in
Filter
question.
(Bandpass) Filter
26. Variable Second Order Discussion
(Bandpass) Filter
27. Dimension-Mapping Controller The set-breakpoint command was formerly used in place
28. Sum Controller of (send-message ...) to control a dynamic controller.
29. Spread Controller Although you may still use it (it allows you to more easily
30. Get Controller Info control multi-dimensional controllers), we recommend
using the new syntax where possible. The set-breakpoint
command is discussed in the reference pages for the
Finite Elements
dynamic controller.
Appendix
Index
Options
There are ©IRCAM

no special options for this function.
2013
http://support.ircam.fr/docs/Modalys/current/co/controller_dynamic_breakpoint.html[28/05/13 15:41:32]
Modalys - Set Breakpoint
http://support.ircam.fr/docs/Modalys/current/co/controller_dynamic_breakpoint.html[28/05/13 15:41:32]
Modalys - Signal Controller
Guide Map
Accesses Signal Controller See also

Random Controller
Connections
Controllers Description Band-Limited Noise
Controller
1. Constant Controller A controller derived from real-time signal input.
Noise (Band-Limited
Impulse) Controller
4. Access Position Controller Bilinear (First Order IIR)
(make-controller 'signal ... ) Filter
6. Connection State Controller Lisp Syntax and Default Values Biquadratic (Second
Order IIR) Filter
The 'signal controller can be created using the following
8. Sound File Controller Constant Second Order
Lisp syntax:
(Bandpass) Filter
10. Dynamic Controller Variable Second Order

11. Send Message (make-controller 'signal dimension (Bandpass) Filter
12. Set Breakpoint point-input1 point-input2 ... Sine Controller
point-inputN)

16. Expression Controller The 'signal controller takes the following arguments:
18. Sine Controller
controller.
point-inputN: a point-input from a real-time
source.
Controller
The point-inputs should be made from the (make-point-
input ... ) command (this is documented in the workspace
section). The number of point-inputs given as arguments
should correspond to the number of dimensions.
Filter
(Bandpass) Filter Discussion
(Bandpass) Filter To use the signal controller, you will need to use it with a
27. Dimension-Mapping Controller point-input, by first instantiating a point input with an
28. Sum Controller optional scalar controller (here a constant scaling value of
29. Spread Controller 0.707), then using the point input in the signal controller:
The Modalys Workspace (setq my-input (make-point-input
Finite Elements 0 (const 0.707)))
Appendix
(setq my-signal-controller (make-
Index
controller 'signal 1 my-input))
A multi-dimensional controller can be created like this:

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_signal.html[28/05/13 15:42:03]
Modalys - Signal Controller
(setq my-input0 (make-point-input

0))

1))
(setq my-controller (make-

controller 'signal 2 my-input0
my-input1))
Naturally, it must be used in with Modalys in a real-time

context (such as with modalys~ in Max/MSP).
Options
http://support.ircam.fr/docs/Modalys/current/co/controller_signal.html[28/05/13 15:42:03]
Modalys - Scale Controller
Guide Map
Accesses Scale Controller See also

Connections
Controllers Description Expression Controller
1. Constant Controller Foreign-Call Controller

This is a controller which takes a controller as input and scales
2. Envelope Controller it from one range to another.
11. Send Message
12. Set Breakpoint
(make-controller 'scale ... )
18. Sine Controller
The 'scale controller can be created using the following
Lisp syntax:
Controller (make-controller 'scale dimension
in_min in_max out_min out_max
controller)
Filter
(Bandpass) Filter
The 'scale controller takes six arguments:
(Bandpass) Filter
dimension: number of dimensions of the input
and output controllers.
28. Sum Controller
in_min: lower range of input controller values.
in_max: upper range of input controller values.
out_min: lower range of output controller values.
The Modalys Workspace out_max: upper range of output controller values.
Finite Elements controller: controller to be scaled.
Appendix
Index The number of dimensions should be the same as that of
the input controller.
The minimum and maximum values are provided as fixed

values.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_scale.html[28/05/13 15:42:35]
The input and output range is not clipped, therefore any

out-of-range values will still be appropriately scaled,
according to the multiplier derived form the given input
and output ranges.
Discussion
Scaling controllers is a necessary and useful tool. The

following example shows a break-point envelope
controller that is scaled and inverted using the 'scale
controller (a graph of the original and scaled envelopes is
shown in the image, above):
(setq my-env (make-controller

'envelope 1 '((0 0.0) (0.2 1.0)
(0.4 0.7) (1.2 0.7) (2 0))))
(setq my-scale (make-controller

'scale 0 0 1 2 -2 my-env))
One common use is scaling the speed of an access so it

can be used as an input force for another object, such as
this one which scales speed values by a factor of 50:
(setq speed-ctl (make-controller

'access-speed 1 my-string-out))
(setq scaledspeed-ctl (make-

controller 'scale 1 0 1 0 50
speed-ctl))

acc scaledspeed-ctl)
Additionally, MIDI controllers always output values

between 0 and 127, so we generally need to use a scale
controller to apply those values meaningfully in Modalys.
For example, if we wanted to use pitch bend to control the
frequency of a sine wave (controller) between 220Hz and
440Hz, we could do the following:
(setq midi-ctl (make-controller

'midi-file 1 "my-midi-file.mid" 1
(list 'pitchbend)))
(setq scaledmidi-ctl (make-

controller 'scale 1 0 127 220 440
midi-ctl))
(setq sine-ctl (make-controller

'sine 1 scaledmidi-ctl))
Options
Modalys - Arithmetic Controller
Guide Map
Accesses Arithmetic Controller See also

Connections

Controller whose output combines two or more input controllers
2. Envelope Controller using one of the four basic arithmetic operations (+, -, *, /).
3. Access Speed Controller Dimension of the input controllers is limited to 1.
11. Send Message
12. Set Breakpoint
(make-controller 'arithmetic ... )
18. Sine Controller Lisp Syntax and Default Values
The 'arithmetic controller can be created using the
Controller
(make-controller 'arithmetic
dimension operator controller1
24. Biquadratic (Second Order IIR) controller2 ... )
Filter
(Bandpass) Filter
or:
(Bandpass) Filter
(make-controller 'arithmetic
28. Sum Controller
dimension operator (list
controller1 controller2 ... ))
Parameters
Finite Elements
Appendix The 'arithmetic controller takes the following arguments:
Index
and output controllers (should be set to 1).
operator: one of the four symbols +, -, *, / (in
quotes, or preceded by an apostrophe)
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_arithmetic.html[28/05/13 15:43:07]
controller1, controller2, etc...: controllers to

"plug-in" to the math operation.
The number of dimensions of both input controllers and

the resulting output controller must be 1.
Any number of input controllers may be provided (just as

you would do for the Lisp functions +, -, * and /), but they
must all be one-dimensional controllers. The controllers
may be provided as a series of arguments or as a list.
Discussion
Arithmetic controllers are used to realize arithmetic

operations efficiently in controller networks.
A basic example shows two breakpoint envelopes being

multiplied together (as shown in the image at the top of
the page):
(setq my-env1 (make-controller

'envelope 1 '((0 0.0) (0.2 1.0)
(0.4 0.7) (1.2 0.7) (2 0))))
(setq my-env2 (make-controller

'envelope 1 '((0 1.5) (2 0.25)) ))
(setq my-product (make-controller

'arithmetic 1 "*" my-env1 my-
env2))
To provide an example, we could rewrite the fm excitation

of the Modalys example 5 the following way (using Max's
naming convention):
(defun +~ (ctlr0 ctlr1) (make-

controller 'arithmetic 1 '+ (list
ctlr0 ctlr1)))
(defun *~ (ctlr0 ctlr1) (make-

controller 'arithmetic 1 '* (list
ctlr0 ctlr1)))
(defun sin~ (frequency) (make-

controller 'sine 1 frequency))
;;; we assume here that cf, mr, mi

and ae are bound to one-
dimensional controllers
(setq mrcf (*~ mr cf))
(setq fm-output (*~ (sin~ (+~ (*~

mrcf mi (sin~ mrcf)) cf)) ae))
The result is more efficient and more general code
(besides we tried to make it more readable).
Options
Modalys - Expression Controller
Guide Map
Accesses Expression Controller See also

Connections

Controller whose output combines one or more input controllers
2. Envelope Controller using a simple C-language-like expression provided as a string.
11. Send Message
12. Set Breakpoint
(make-controller 'expression ... )
18. Sine Controller
The 'expression controller can be created using the
Controller (make-controller 'expression
dimension period expression_string
controller1 controller2 ... )
Filter
or:
(Bandpass) Filter
(Bandpass) Filter
(make-controller 'expression
dimension period expression_string
28. Sum Controller
(list controller1 controller2 ...
))
Parameters
Finite Elements
Appendix The 'expression controller takes the following arguments:
Index
dimension: number of dimensions for the output
controller.
period: the time between controller updates (in
synthesis seconds).
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_expression.html[28/05/13 15:43:39]
expression_string: a text string representing the

expression to be evaluated. see details, below.
"plug-in" to the math expression.
The output controller can be optionally re-sampled using

the period argument. A period of 0, as always, indicates
the controller will be updated every sample.
The C-like expression string syntax is described in detail,

below.
A variable number of controllers may be provided as a

series of arguments, or as a list.
Discussion
The expression controller is similar to the arithmetic

controller, but with a richer syntax for mathematical
expressions, and support for multi-dimensional
controllers. It is available outside the Lisp environment, so
it should be used, when and where possible, instead of a
'foreign-call controller, which is not only painfully slow, but
also specific just to Modalys in the Lisp environment.
Here is a simple example of the 'expression controller's

use to multiply two controllers (my-ctl1 and my-ctl2):
(make-controller 'expression 1 0
"in(1,1)*in(2,1)" my-ctl1 my-ctl2)
In this case, in(1,1) refers to the first dimension of the first

controller (my-ctl1, in this example), and in(2,1) refers to
the first dimension of the second controller.
The expression also lets you use variables and separate

an expression into multiple subsequent statements using
a semicolon. The above example could be rewritten as:
"a=in(1,1); b=in(2,1); a*b" my-
ctl1 my-ctl2)
Of course the main advantage to the expression controller

is it is well-suited to more complicated mathematical
expressions, such as the following example which creates
a Hanning window from a one-second ramp (a graph of
the original ramp and window resulting from the
expression controller is shown, above):
(setq my-ramp (make-controller

'envelope 1 '((0 0) (1 1))))
(setq my-window (make-controller
'expression 1 0
"0.5+(0.5*cos((in(1,1)+0.5)*pi*2))"
my-ramp))
You can even get information about things in the Modalys

workspace within the expression string. The following
shows an example of using the expression controller to
get info about the first mode of a mono-string object:

'mono-string))
(setq my-ctl (make-controller

'expression 1 0 "get_info('mode-
frequency', in(1), 0)" my-string))
Note that the input controllers and their dimensions are

numbered starting from 1 in the expression, not from 0 as
they are in many other Modalys functions (such as
'dimension-mapping and 'foreign-call).
Options
Operations
The operations in the expression string can be any of the

following:
the four standard arithmetic operators:
+
-
*
/
exponential functions:
sqrt(x)
power(x,n)
exp(x)
log(x,n)
log10(x)
trigonometric functions:
cos(x)
sin(x)
tan(x)
acos(x)
asin(x)
atan(x)
sinh(x)
cosh(x)
tanh(x)
other functions:
abs(x)
min(x,y)
max(x,y)
sign(x)
comparison:
<
>
<=
>=
logical operators:
and
or
conditional statements:
if (condition, if-true, if-false)
constants
pi
local variables (statements separated by a

semicolon):
a = 1; b = a+1;
controllers are indexed by <position-in-inputlist>

<desired-dimension> (numbering starts from 1):
in(1,1)
objects are indexed by <position-in-inputlist> (no

dimension index! and numbering starts from 1)
in(1)
the Modalys (get-info ... ) command can be

accessed using get_info():
get_info('sample-rate')
get_info('mode-frequency', in(1), 0)
multi-dimensional outputs are possible by

separating multiple items with commas inside
square brackets - each corresponds to a different
dimension of the output controller
[ expression_1 , expression_2 ]
Some practical examples to demonstrate the syntax in a

complete expression string:
cosine of an input-controller:
"cos(in(1,1))"
masking = maximum between 2 dimensions of two

input-controllers:
"max(in(1,1),in(1,2))"
clipping a controller to lie between -1,1:
"max(-1,min(1,in(1,1)))"
Also, within the Lisp environment, you could also use the
Lisp (format ...) function to generate expressions for the
expression controller:
(format nil "~{~[~; + ~]~[cos~;sin~](~a*in(~a,1))~}" (list-of-

groups-of-4-numbers))
Modalys - Foreign-Call Controller
Guide Map
Accesses Foreign-Call Controller See also

Connections
Controllers Description Expression Controller
1. Constant Controller Scale Controller

Allows any Lisp (or Scheme) program to be used as a
2. Envelope Controller controller. To take advantage of this function, you should have
3. Access Speed Controller some knowledge of the Lisp (or Scheme) programming
4. Access Position Controller language. The fact that it can replicate Scheme programs is for
5. Access Force Controller backwards-compatibility, since old versions of Modalys used a
6. Connection State Controller Scheme interface instead of a Lisp interface. Generally, we
7. Last Sample Controller suggest that you use the Expression Controller when and
8. Sound File Controller where possible, not only because it is light-years faster, but
9. MIDI File Controller also because the foreign-call controller is only available in the
10. Dynamic Controller Lisp interface to Modalys.
11. Send Message
12. Set Breakpoint
13. Signal Controller (make-controller 'foreign-call ... )
16. Expression Controller The 'foreign-call controller can be created using the
17. Foreign-Call Controller following Lisp syntax:
18. Sine Controller
(make-controller 'foreign-call
20. Band-Limited Noise Controller dimension period foreign_function
21. Noise (Band-Limited Impulse) (list controller1 controller2 ...
Controller
))
Parameters
Filter
The 'foreign-call controller takes the following arguments:
(Bandpass) Filter dimension: number of dimensions for the output
controller.
(Bandpass) Filter
period: the time between controller updates (in
synthesis seconds).
28. Sum Controller
foreign_function: a Lisp or Scheme function
representing the expression to be evaluated. see
details, below.
Finite Elements
"plug-in" to the math expression.
Appendix
Index The output controller can be optionally re-sampled using
the period argument. A period of 0, as always, indicates
the controller will be updated every sample.
The Lisp or Scheme lambda function with no arguments,

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_foreign_call.html[28/05/13 15:44:12]
says how to update the "output latch" from the "input

latches". See description, below, for details.
A variable number of controllers may be provided as a list.
Discussion
Here is a practical example of how to use the 'foreign-call

controller to multiply two controllers (my-ctl1 and my-ctl2):
0
(foreign-callable (lambda
(input output)
(vset output 0
(* (vget input 0 0) (vget input 1
0))) ))
(list my-ctl1 my-ctl2))
That is equivalent to the 'expression controller:
"in(1,1)*in(2,1)" my-ctl1 my-ctl2)
Or the 'arithmetic controller:
(make-controller 'arithmetic 1 "*"

my-ctl1 my-ctl2)
Naturally, apart from simply accepting input controllers,

any Modalys or Lisp programming function may be called
within the lambda function. Here is an example of how the
speed of an access can be obtained using the 'foreign-call
controller:
0
(foreign-callable (lambda
(ins outs)
(vset outs 0
(get-info 'speed access-ref)) ))
'())
Obtaining the access speed this way is considerably more

computationally expensive than using the 'access-speed
controller, however, there may be other esoteric uses of
the 'foreign-call controller to obtain seldom-accessed

Modalys data.
Although we generally recommend using the 'expression,

'arithmetic or other controllers when and where possible
(did we mention that they were a lot faster???!), there
may be some advanced or expert techniques which
require the 'foreign-call controller to do specific tasks, so
the function has been retained in the Modalys
environment.
Options
Lambda Function Syntax
It's worth studying the update function a bit (actually you

need to know how to program a little bit in Lisp, Scheme
or a related programming language in order to really
understand this well). The update function must begin like
this (of course, "inputs" and "output" could be other
variable names like "ins" and "out"):
(foreign-callable (lambda (inputs

output) . . . ))
This is then followed by programming statements that are

used to change the value in the controller's "output box"
by using the function (vset ... ). Therefore, to put the value
31.2 in the first dimension of your output box, you would
write:
(vset output 0 31.2)
Notice that the output dimensions are numbered starting

from zero. Thus, you could change the second dimension
using:
(vset output 1 31.2)
and so forth. Naturally, to know how to update its output,

the function must have access to all the values in the
input controllers. To get the inputs, you use the (vget ... )
function like this:
(vget inputs 0 0)
This gets the first dimension of the first input - both are
numbered starting from 0. So, if you type:
(vget inputs 0 1)
you get the second dimension of the first input, or if you

type:
(vget inputs 1 0)
you get the first dimension of the second input, and so on.
Therefore:
(vget inputs 18 21)
would get the 22nd dimension of the 19th input. So you

can see that the following function:
(foreign-callable (lambda (inputs

output) (vset output 0 (* (vget
inputs 0 0) (vget inputs 1 0)))))
means that the update rule is: "get the first dimension of
the first input controller; then, get the first dimension of the
second input controller. Multiply them together, and stick
the result in the first dimension of my own output box."
This is a useful general-programming-like way of using a

controller, however for most basic math operations you
can use the 'arithmetic controller or for more complex
expressions, the 'expression controller.
Retro-Compatibility
This controller was formerly called (make-controller

'scheme ... ) and had a slightly different syntax where the
number of input controllers had to be explicitly given
before the list containing them:
(make-controller 'scheme dimension

period foreign_function
num_input_ctlrs (list controller1
controller2 ... ))
Additionally, the scheme lambda function syntax was a

tiny bit different. The simple example shown in the
discussion, above, would have looked like this:
(make-controller 'scheme 1 0
(lambda ()
(vset 0 (* (vget
0 0) (vget 1 0))) )
2 (list my-ctl1 my-ctl2))
Any very old Modalys scripts which still use scheme

controllers will need to be updated to use the 'foreign-call
or, preferably, the 'expression controller, instead.
Modalys - Sine Controller
Guide Map
Accesses Sine Controller See also

Random Controller
Connections
Controllers Description Band-Limited Noise
Controller
1. Constant Controller Outputs a sine-wave in each dimension.
Noise (Band-Limited
Impulse) Controller
4. Access Position Controller Bilinear (First Order IIR)
Filter
6. Connection State Controller Biquadratic (Second
Order IIR) Filter
8. Sound File Controller Constant Second Order
(Bandpass) Filter
10. Dynamic Controller Variable Second Order

11. Send Message (Bandpass) Filter
12. Set Breakpoint Signal Controller
(make-controller 'sine ... )
The 'sine controller can be created using the following
18. Sine Controller
Lisp syntax:
21. Noise (Band-Limited Impulse) (make-controller 'sine dimension
Controller freq_controller phase)
Parameters
Filter The 'sine controller takes two arguments:
(Bandpass) Filter dimension: number of dimensions of the output
26. Variable Second Order controller.
(Bandpass) Filter
freq_controller: controller defining the frequency
of the sine wave.
28. Sum Controller
phase: initial phase of the sine wave (in degrees).
30. Get Controller Info The frequency controller determines frequency (or
The Modalys Workspace frequencies) of the output sine-wave(s). The dimension of
Finite Elements this controller must equal the dimension of the sine-wave
Appendix controller whose frequency it determines.
Index The initial phase parameter should be given, even if it is
zero. Naturally, a cosine may be made by providing an
initial phase of 90 degrees. Currently the phase parameter
seems to only apply to the first dimension of the
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_sine.html[28/05/13 15:44:44]
Modalys - Sine Controller
controller. This is a bug.
The sine controller is updated every synthesis sample

period.
Discussion
A basic sine controller (at 440 Hz, for example) may be

created like this:
(setq my-sine (make-controller

'sine 1 (const 440) 0))
Although one-dimensional sine controllers are most often

used, they may have multiple dimensions such as in this
example (whose graph is shown, above, for one second
of time):
(setq my-sine (make-controller

'sine 3 (const 1 2 5) 0))
Sine wave controllers are often useful to add modulation

to other Modalys controllers. For example, if one wanted
to add vibrato to the pitch of a plucked or bowed string
synthesis, one could slightly vary the position of the
access on the string where a finger makes contact with it
using a sine controller.
Sine controllers can also be used to make synthesis, that

can be used to resonate objects, as shown in Example 5.
Options
http://support.ircam.fr/docs/Modalys/current/co/controller_sine.html[28/05/13 15:44:44]
Modalys - Random Controller
Guide Map
Accesses Random Controller See also

Band-Limited Noise
Connections
Controller
Noise (Band-Limited
1. Constant Controller Outputs one or more equally distributed random sequences Impulse) Controller
2. Envelope Controller (white noise). The output values range from -1 to 1. Bilinear (First Order IIR)
Filter
Biquadratic (Second
Order IIR) Filter
Constant Second Order
(Bandpass) Filter
Variable Second Order
(Bandpass) Filter
11. Send Message Sine Controller
12. Set Breakpoint Signal Controller
(make-controller 'random ... )
18. Sine Controller
The 'random controller can be created using the following
Lisp syntax:
Controller (make-controller 'random dimension
period)
Filter Parameters
The 'random controller takes two arguments:
(Bandpass) Filter
26. Variable Second Order dimension: number of dimensions of the output
(Bandpass) Filter
controller.
period: sampling period (seconds).
28. Sum Controller
29. Spread Controller The period is used to define the time between the updates
30. Get Controller Info of the controller. If zero is given then it updates every
The Modalys Workspace sample.
Finite Elements
Appendix Discussion
Index
The Random Controller is basically a white noise
oscillator with an optional sample-and-hold mechanism,
since it outputs values between -1 an 1, and has a user-
defined sampling period. It is fairly simple to use and can
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_noise_random.html[28/05/13 15:45:16]
Modalys - Random Controller
output different random values in multiple dimensions,

such as this example (whose graph is shown above)
which outputs 3 dimensions of random values updated
every 10 milliseconds:
(setq my-rand (make-controller

'random 3 0.01))
A controller with random values has many practical uses

within the Modalys environment - not least of which is to
provide a noise source to use with a force connection:

'mono-string))

(setq my-noise (make-controller

'random 1 0))

'envelope 1 '((0 0) (0.1 5) (0.2
2) (0.3 0)) ))

'arithmetic 1 "*" my-noise my-
env))

string-acc force-ctl)
Options
http://support.ircam.fr/docs/Modalys/current/co/controller_noise_random.html[28/05/13 15:45:16]
Modalys - Band-Limited Noise Controller
Guide Map
Accesses Band-Limited Noise See also
Connections Controller Random Controller
Controllers Noise (Band-Limited

Impulse) Controller
1. Constant Controller Description
Bilinear (First Order IIR)
Outputs bandlimited noise produced by oversampling a noise Filter
3. Access Speed Controller generator. The output values range from -1 to 1.
4. Access Position Controller Biquadratic (Second
Order IIR) Filter
6. Connection State Controller Constant Second Order
(Bandpass) Filter
8. Sound File Controller Variable Second Order
(Bandpass) Filter
10. Dynamic Controller Sine Controller

11. Send Message Signal Controller
12. Set Breakpoint
(make-controller 'bandlimited-noise ... )
The 'bandlimited-noise controller can be created using the
Controller
(make-controller 'bandlimited-
noise dimension period cutoff
24. Biquadratic (Second Order IIR) taps)
Filter
(Bandpass) Filter Parameters
(Bandpass) Filter The 'bandlimited-noise controller takes four arguments:
28. Sum Controller
controller.
period: sampling period (seconds).
cutoff: a controller specifying the cutoff frequency
The Modalys Workspace (in Hz.).
Finite Elements taps: integer number of taps used in the
Appendix smoothing filter (an even integer not less than 4).
Index
The period is used to define the time between the updates
of the controller. If zero is given then it updates every
sample.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_noise_bandlimited.html[28/05/13 15:45:48]
The cutoff frequency is a controller and therefore can be

dynamically variable.
The number of filter taps for the smoothing function can

be chosen. This parameter has an effect on the quality of
the smoothing (but remember that the computation time
increases with the square of taps). A good "clean" value
for taps is 30, but anyway this is noise, so taking it down
to 10 probably would not affect the sound that much for
most uses. The minimum value for this parameter is 4.
Note also that using a higher value for the filter taps
parameter will result in sample values that slightly exceed
the -1 to 1 range. The random values themselves are
within range, but bandlimiting and smoothing process will
cause them to exceed these limits slightly.
Discussion
The band-limited noise controller can output multiple

dimensions each with its own cutoff frequency. A graph of
the following example is also shown in the image, above:
(setq my-rand (make-controller

'bandlimited-noise 3 0 (const 5
12 30) 10))
A controller with random values has many uses - not least

of which is to provide a noise source to use with a force
connection:

'mono-string))


'bandlimited-noise 1 0 (const 880)
10 ))

'envelope 1 '((0 0) (0.1 5) (0.2
2) (0.3 0)) ))

'arithmetic 1 "*" my-noise my-
env))

string-acc force-ctl)
Options
Modalys - Noise (Band-Limited Impulse) Controller
Guide Map
Accesses Noise (Band-Limited Impulse) See also
Connections Controller Random Controller
Controllers Band-Limited Noise

Controller
Bilinear (First Order IIR)
Outputs a random series of band-limited impulses. The cutoff, Filter
3. Access Speed Controller random delay time range and output value range can all be
4. Access Position Controller Biquadratic (Second
dynamically controlled using other controllers.
Order IIR) Filter
6. Connection State Controller Constant Second Order
(Bandpass) Filter
8. Sound File Controller Variable Second Order
(Bandpass) Filter
10. Dynamic Controller Sine Controller

11. Send Message Signal Controller
12. Set Breakpoint
(make-controller 'noise ... )
18. Sine Controller
19. Random Controller Lisp Syntax and Default Values
The 'noise controller can be created using the following
Controller
Lisp syntax:
(make-controller 'noise dimension
24. Biquadratic (Second Order IIR) period (list cutoff delmin delmax
Filter
outmin outmax) taps)
(Bandpass) Filter
26. Variable Second Order Parameters
(Bandpass) Filter
27. Dimension-Mapping Controller The 'noise controller takes four arguments, the third of
28. Sum Controller which is a list of 5 controllers:
controller.
The Modalys Workspace period: sampling period (seconds).
Finite Elements cutoff: a controller specifying the cutoff frequency
Appendix (in Hz.).
Index delmin: controller specifying the minimum entry
delay in seconds.
delmax: controller specifying the maximum entry
delay in seconds.
©IRCAM
outmin: 2013 specifying the minimum output
controller
http://support.ircam.fr/docs/Modalys/current/co/controller_noise_noise.html[28/05/13 15:46:20]
value.
outmax: controller specifying the maximum output
value.
taps: integer number of taps used in the
smoothing filter (an even integer not less than 4).
The period is used to define the time between the updates

of the controller. If zero is given then it updates every
sample.
The list of 5 controllers (cutoff, delmin, delmax, outmin

and outmax) must be provided in list format.
The cutoff frequency is a controller and therefore can be

dynamically variable. For single-sample clicks you can
give a cutoff euqal to the sampling rate.
The delmin and delmax parameters let you choose the

timing between impulses. If these values are the same the
impulses will be generated in a regular rhythm, otherwise
the entries of each impulse will be randomly chosen within
the range provided.
The outmin and outmax parameters let you similarly

control the output range for the amplitude of the impulses.
The number of filter taps for the smoothing function can

be chosen. This parameter has an effect on the quality of
the smoothing (but remember that the computation time
increases with the square of taps). A good "clean" value
for taps is 30, but anyway this is noise, so taking it down
to 10 probably would not affect the sound that much for
most uses. The minimum value for this parameter is 4.
Note also that using a higher value for the filter taps
parameter may sometimes result in controller values that
slightly exceed the -1 to 1 range. The random values
themselves are within range, but bandlimiting and
smoothing process will cause them to exceed these limits
slightly.
Discussion
The Modalys 'noise controller can output a wide variety of

sounds, from metronomic bleeps to white noise. Here are
some practical examples that should help you understand
how it works. The graph shown in the image, above,
outputs a series of impulses which get increasingly farther
apart over 2 seconds:
(make-controller 'noise 1 0
(list (const 1000)
(make-controller
'envelope 1 '((0 0.001) (2 0.1)))
(make-controller
'envelope 1 '((0 0.01) (2 0.5)))
(const -1)
(const 1))
10)
You could use the generator to create white noise like this
(the impulses will be updated every sample since the min
and max delay are zero):
(list (const 44100)
(const 0)
(const 0)
(const -1)
(const 1))
10)
This will create a series of clicks with random amplitude

values which are spaced evenly 100 milliseconds apart:
(list (const 44100)
(const 0.1)
(const 0.1)
(const -1)
(const 1))
10)
This will create a series of slightly-pitched filtered

impulses with uniform amplitude values at unit gain which
are spaced irregularly approximately 20 milliseconds
apart, resulting in a slightly vocal quality (notice we have
increased the filter taps to 30 for a cleaner sound):
(list (const 1760)
(const 0.018)
(const 0.022)
(const 1)
(const 1))
30)
Naturally, such impulses can be dynamically controlled

and used to great effect as sources for excitation using a
'force connection.
Options
Modalys - Delay Controller
Guide Map
Accesses Delay Controller See also

Last Sample Controller
Connections
Controllers Description Bilinear (First Order IIR)
Filter
1. Constant Controller A controller whose output is that of an input controller delayed
Biquadratic (Second
in time. Order IIR) Filter
4. Access Position Controller Constant Second Order
(Bandpass) Filter
6. Connection State Controller Variable Second Order
(Bandpass) Filter
8. Sound File Controller Signal Controller
11. Send Message
12. Set Breakpoint
(make-controller 'delay ... )
18. Sine Controller
The 'delay controller can be created using the following
Lisp syntax:
Controller (make-controller 'delay dimension
delaytime controller)
Filter Parameters
The 'delay controller takes three arguments:
(Bandpass) Filter
26. Variable Second Order dimension: number of dimensions of the input
(Bandpass) Filter
delaytime: a controller (or numerical value)
28. Sum Controller
expressing the delay time in seconds.
controller: controller to be delayed.
The Modalys Workspace The number of dimensions should be the same as that of
Finite Elements the input controller.
Appendix
The delay time can be either a constant or dynamic
Index controller, or else be given as a numerical value.
Discussion
The following shows2013

©IRCAM a very simple example of using the
http://support.ircam.fr/docs/Modalys/current/co/controller_delay.html[28/05/13 15:46:52]
Modalys - Delay Controller
delay controller to delay a simple envelope by half a

second (as shown in the graph, at the top of this page):

'envelope 1 '((0 0.0) (0.2 1.0)
(0.4 0)) ))
(setq my-delay (make-controller

'delay 1 0.5 my-env))
As you can see, this controller allows another controller to

be delayed by a given (optionally dynamically variable)
delay time. It does not alter that controller, but rather
creates a new controller. This can be useful for many
operations, such as delaying a force controller used for
sympathetic resonance. The following example show
precisely that, with a 1/4 second delay applied to the force
controller:
(setq speed-ctl (make-controller

'access-speed 1 my-string-plk))
(setq delay-ctl (make-controller

'delay 1 (const 0.25) speed-ctl))

hit delay-ctl)
Options
http://support.ircam.fr/docs/Modalys/current/co/controller_delay.html[28/05/13 15:46:52]
Modalys - Bilinear (First Order IIR) Filter
Guide Map
Accesses Bilinear (First Order IIR) Filter See also

Biquadratic (Second
Connections
Order IIR) Filter
1. Constant Controller Filters its inputs by a first order IIR filter controlled by a set of (Bandpass) Filter
2. Envelope Controller three coefficients Variable Second Order
(Bandpass) Filter
Random Controller
6. Connection State Controller Band-Limited Noise
Controller
8. Sound File Controller Noise (Band-Limited
Impulse) Controller
10. Dynamic Controller Signal Controller

11. Send Message
12. Set Breakpoint
(make-controller 'bilinear-filter ... )
18. Sine Controller
The 'bilinear-filter controller can be created using the
Controller (make-controller 'bilinear-filter
dimension period coef_controller
23. Bilinear (First Order IIR) Filter input_controller)
Filter
(Bandpass) Filter
The 'bilinear-filter controller takes four arguments:
(Bandpass) Filter
28. Sum Controller
period: the time between the updates of the
controller. If zero is given then it updates every
30. Get Controller Info sample.
The Modalys Workspace coef_controller: a three-dimensional controller
Finite Elements specifying the three bilinear filter coefficients.
Appendix input_controller: filter input (a controller).
Index
The number of dimensions should be the same as that of
The coefficient controller should have 3 dimensions which

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_filter_bilinear.html[28/05/13 15:47:23]
Modalys - Bilinear (First Order IIR) Filter
represent the a0, a1 and b1 coefficients.
Discussion
This filter implements a general first-order (one-pole one-

zero) filter which can be used for a variety of purposes,
including smoothing out envelopes, and filtering sound-
file, signal or other controllers. The following example is
shown in one of the graphs (with a 1 Hz cutoff) in the
above image:
(setq sp (get-info 'sample-

period))

'envelope 1
(list '(0 0.0) '(0.1 0)

(list (+ 0.1 sp) 1) '(1.5 1) (list
(+ 1.5 sp) 0)) ))
(setq cutoff 1)
(setq val (sin (* cutoff 2 pi

sp)))
(setq my-coef-ctl (const (list

val 0 (- val 1))))
(setq my-filtered-env (make-

controller 'bilinear-filter 1 my-
coef-ctl my-env))
You should probably consider using it or the biquadratic-

filter, instead of the older filtering functions. However, you
will need to generate your own sets of coefficients from
higher level parameters such as center/cutoff frequency,
etc....
Options
http://support.ircam.fr/docs/Modalys/current/co/controller_filter_bilinear.html[28/05/13 15:47:23]
Modalys - Biquadratic (Second Order IIR) Filter
Guide Map
Accesses Biquadratic (Second Order See also
Connections IIR) Filter Bilinear (First Order IIR)

Filter
Controllers
(Bandpass) Filter
2. Envelope Controller Filters its inputs by a second order IIR filter controlled by a set Variable Second Order
3. Access Speed Controller of five coefficients (Bandpass) Filter
Random Controller
Controller
Impulse) Controller

11. Send Message
12. Set Breakpoint
(make-controller 'biquadratic-filter ... )
The 'biquadratic-filter controller can be created using the
Controller
(make-controller 'biquadratic-
23. Bilinear (First Order IIR) Filter filter dimension period
24. Biquadratic (Second Order IIR) coef_controller input_controller)
Filter
(Bandpass) Filter Parameters
(Bandpass) Filter The 'biquadratic-filter controller takes four arguments:
28. Sum Controller
30. Get Controller Info controller. If zero is given then it updates every
The Modalys Workspace sample.
Finite Elements coef_controller: a five-dimensional controller
Appendix specifying the three bilinear filter coefficients.
Index input_controller: filter input (a controller).

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_filter_biquadratic.html[28/05/13 15:47:54]
The coefficient controller should have 5 dimensions which

represent the a0, a1, a2, b1 and b2 coefficients.
Discussion
This filter implements a general second-order (two-pole

two-zero) filter which can be used for a variety of
purposes, including smoothing out envelopes, and filtering
sound-file, signal or other controllers. The following
example is shown in one of the graphs (with a 1 Hz cutoff)
in the above image:
(setq sp (get-info 'sample-

period))

'envelope 1
(list '(0 0.0) '(0.1 0)

(list (+ 0.1 sp) 1) '(1.5 1) (list
(+ 1.5 sp) 0)) ))
(setq cutoff 1)
(setq Q 0.707)
(setq w0 (* cutoff 2 pi sp))
(setq alpha (/ (sin w0) (* 2 Q)))
(setq cw (cos w0))
(setq b0 (/ 1 (+ 1 alpha)))
(setq a0 (* b0 (- 1 cw) 0.5))
(setq a1 (* b0 (- 1 cw)))
(setq a2 a0)
(setq b1 (* b0 (* -2 cw)))
(setq b2 (* b0 (- 1 alpha)))

controller 'biquadratic-filter 1
(const a0 a1 a2 b1 b2) my-env))
You should probably consider using it or the biquadratic-

filter, instead of the older filtering functions (because you
can design any type of filter you want). However, you will
first need to generate your own sets of coefficients from
higher level parameters such as center/cutoff frequency,
etc....
Options
Modalys - Constant Second Order (Bandpass) Filter
Guide Map
Accesses Constant Second Order See also
Connections (Bandpass) Filter Bilinear (First Order IIR)

Filter
Controllers
Biquadratic (Second
Order IIR) Filter
2. Envelope Controller Filters its inputs by a second order IIR filter with a constant Variable Second Order
3. Access Speed Controller center frequency, amplitude and bandwidth. (Bandpass) Filter
It currently seems to be broken. Random Controller
Controller
(make-controller 'constant-second- Noise (Band-Limited
order-filter ... ) Impulse) Controller
10. Dynamic Controller Lisp Syntax and Default Values Signal Controller
11. Send Message
The 'constant-second-order-filter controller can be created
12. Set Breakpoint
15. Arithmetic Controller (make-controller 'constant-
16. Expression Controller second-order-filter dimension
17. Foreign-Call Controller period input_controller
18. Sine Controller
(list a1 a2 ... aN)
20. Band-Limited Noise Controller (list cf1 cf2 ... cfN)
21. Noise (Band-Limited Impulse) (list bw1 bw2 ... bwN))
Controller
23. Bilinear (First Order IIR) Filter Parameters
24. Biquadratic (Second Order IIR) The 'constant-second-order-filter controller takes the
Filter
following arguments:
(Bandpass) Filter dimension: number of dimensions of the input
(Bandpass) Filter
controller. If zero is given then it updates every
28. Sum Controller
sample.
input_controller: filter input (a controller).
aN: linear amplitude, N has to correspond to the
given dimension.
Finite Elements
cfN: center frequency in Hertz, N has to
Appendix
correspond to the given dimension.
Index bwN: bandwidth in Hertz, N has to correspond to
the given dimension.
The number of dimensions of the output controller should

be the same as that2013
©IRCAM of the input controller.
http://support.ircam.fr/docs/Modalys/current/co/controller_filter_bp_constant.html[28/05/13 15:48:40]
The amplitude, center frequency and bandwidth

parameters cannot be varied in time.
Discussion
The constant second order (bandpass) filter can be used

for a variety of purposes, but generally is used either to
smooth out envelopes or create resonances from
impulses. Using a low frequency and fairly wide
bandwidth, it can smooth out envelopes:

'envelope 1 '((0 0.0) (0.1 1.0)
(1.4 1) (1.5 0)) ))

controller 'constant-second-
order-filter 1 0 my-env (list 1)
(list 1) (list 5)))
Or it can be used to add a resonance to an impulse or

other noisy sound, by using a specific frequency and a
very narrow bandwidth:

'noise 1 0 (list (const 44100)
(const 0.25) (const 0.25) (const
1) (const 1)) 10))
(setq my-filtered-noise (make-

controller 'constant-second-
order-filter 1 0 my-noise (list
1) (list 440) (list 1)))
We actually recommend using the more general-purpose

'biquadratic-filter controller instead of this older filter.
However, to do so you will need to generate your own
filter coefficients (whereas this filer lets you use higher-
level parameters like frequency, amplitude and
bandwidth).
WARNING:
This is, of course, all purely theoretical because it seems

to be broken...... ;)
Options
Modalys - Variable Second Order (Bandpass) Filter
Guide Map
Accesses Variable Second Order See also
Connections (Bandpass) Filter Bilinear (First Order IIR)

Filter
Controllers
Biquadratic (Second
Order IIR) Filter
2. Envelope Controller Filters its inputs by a second order IIR filter with a variable Constant Second Order
3. Access Speed Controller center frequency and bandwidth. (Bandpass) Filter
Random Controller
Controller
Impulse) Controller

11. Send Message
12. Set Breakpoint
(make-controller 'variable-second-order-
filter ... )
18. Sine Controller
19. Random Controller Lisp Syntax and Default Values
The 'variable-second-order-filter controller can be created
Controller
(make-controller 'variable-
24. Biquadratic (Second Order IIR) second-order-filter dimension
Filter
period input_controller cf-
(Bandpass) Filter controller bw-controller)
(Bandpass) Filter
Parameters
28. Sum Controller The 'variable-second-order-filter controller takes five
29. Spread Controller arguments:
The Modalys Workspace and output controllers.
Finite Elements period: the time between the updates of the
Appendix controller. If zero is given then it updates every
Index sample.
input_controller: filter input (a controller).
cf-controller: controller specifying the center
frequency in Hz.
©IRCAM 2013
bw-controller: controller specifying the bandwidth
http://support.ircam.fr/docs/Modalys/current/co/controller_filter_bp_variable.html[28/05/13 15:49:30]
in Hz.

The center frequency and bandwidth parameters should

both be controllers. Note that there is no amplitude
controller for this filter. Amplitude gain is internally set to
1, but resonances caused by very narrow bandwidths
could result in very high amplitude values.
Discussion
The variable second order (bandpass) filter can be used

for a variety of purposes, but generally is used either to
smooth out envelopes or create resonances from
impulses. Using a low frequency and fairly wide
bandwidth, it can smooth out envelopes (a graph of this
example is shown in the image, above):

'envelope 1 '((0 0.0) (0.1 1.0)
(1.4 1) (1.5 0)) ))

controller 'variable-second-
order-filter 1 0 my-env (const 1)
(const 5)))
Or it can be used to add a resonance to an impulse or

other noisy sound, by using a specific frequency and a
very narrow bandwidth:

'noise 1 0 (list (const 44100)
(const 0.25) (const 0.25) (const
1) (const 1)) 10))
(setq my-filtered-noise (make-

controller 'variable-second-
order-filter 1 0 my-noise (const
440) (const 1)))
We actually recommend using the more general-purpose

'biquadratic-filter controller instead of this older filter.
However, to do so you will need to generate your own
filter coefficients (whereas this filer lets you use higher-
level parameters like frequency and bandwidth).
Options
Modalys - Dimension-Mapping Controller
Guide Map
Accesses Dimension-Mapping See also
Connections Controller Spread Controller
Controllers Sum Controller

2. Envelope Controller Create a (one- or multi-dimensional) controller by mapping
3. Access Speed Controller dimensions to it from the dimensions of other controller(s)
6. Connection State Controller (make-controller 'dimension-mapping ...
7. Last Sample Controller )
9. MIDI File Controller Lisp Syntax and Default Values
10. Dynamic Controller The 'dimension-mapping controller can be created using
11. Send Message the following Lisp syntax:
12. Set Breakpoint
(make-controller 'dimension-
mapping dimension
16. Expression Controller (list (list
17. Foreign-Call Controller controller1 index1 dim11 dim12
18. Sine Controller ...)
(list
20. Band-Limited Noise Controller controller2 index2 dim21 dim22
21. Noise (Band-Limited Impulse) ...)
Controller
22. Delay Controller ... ))
24. Biquadratic (Second Order IIR) Parameters
Filter
25. Constant Second Order The 'dimension-mapping controller takes the following
(Bandpass) Filter arguments:
(Bandpass) Filter dimension: number of dimensions of the output
27. Dimension-Mapping Controller controller.
28. Sum Controller controllerN: input controller N.
29. Spread Controller indexI: index I on input controller N.
30. Get Controller Info dimIJ: series of dimension(s) J on which
The Modalys Workspace controllerN[indexI] will be mapped.
Finite Elements
This function takes a list of mapping lists lists as its final
Appendix
argument. The number of mapping lists lists depends on
Index
the number of output (and input) controllers.
Discussion
The dimension-mapping
©IRCAM 2013 controller accepts a list of
http://support.ircam.fr/docs/Modalys/current/co/controller_dimension_map.html[28/05/13 15:50:20]
dimension mapping lists, each of them containing an input

controller (of arbitrary dimension), a dimension index on
the input controller and a set of mapped output
dimensions. The indexed entry of the input controller will
be then assigned to each of the specified dimensions of
the dimension-mapping controller.
The following is a practical example that uses the

dimension-mapping controller to map the 2 channels of a
stereo sound file into two separate Modalys controllers:
(setq sf-ctl (make-controller

'sound-file 2 0 (const 44100)
"my-sf.aiff" 0 my-sf-length 30 ))
(setq ch1-ctl (make-controller

'dimension-mapping 1 (list (list
sf-ctl 0 0))))
(setq ch2-ctl (make-controller

sf-ctl 1 0))))
Or we could take the input sound file controller and swap

the left and right channels:

(setq swap-ctl (make-controller

'dimension-mapping 2
(list (list sf-ctl 0

1)
(list sf-ctl 1
0))))
We could also similarly use it to map two mono sound

files controllers to the dimensions of a 2-dimensional
controller:
(setq sf-ctl1 (make-controller

"my-sf1.aiff" 0 my-sf-length 30
))
(setq sf-ctl2 (make-controller

"my-sf2.aiff" 0 my-sf-length 30
))
(setq 2d-ctl (make-controller
'dimension-mapping 2
(list (list sf-ctl1 0

0)
(list sf-ctl2 0
1))))
An input controller can also be mapped to multiple

dimensions of the output controller, such as in this
example which mapsa mono sound file controller to all 4
dimensions of a 4-dimensional controller:

(setq 4d-ctl (make-controller

sf-ctl 0 0 1 2 3))))
Naturally, this last example could have be achieved more

efficiently using the spread controller, but it helps show
how the dimension-mapping controller can be a versatile
and handy function for mixing and matching data from
different controllers.
Options
Modalys - Sum Controller
Guide Map
Accesses Sum Controller See also

Spread Controller
Connections
Controllers Description Dimension-Mapping
Controller
1. Constant Controller Outputs a one-dimensional controller which sums up the
2. Envelope Controller dimensions of its input controller.
5. Access Force Controller (make-controller 'sum ... )
The 'sum controller can be created using the following
9. MIDI File Controller Lisp syntax:
11. Send Message
12. Set Breakpoint (make-controller 'sum dimension
period controller)

16. Expression Controller The 'sum controller takes three arguments:
18. Sine Controller
controller (should be set to 1).
period: re-sampling period of the controller (in
seconds).
Controller
controller: multi-dimensional input controller.
The number of dimensions should be set to 1
24. Biquadratic (Second Order IIR) As always, the period defines the time between the
Filter updates of the controller. If zero is given then it updates
25. Constant Second Order every sample.
(Bandpass) Filter
26. Variable Second Order The input controller should be a multi-dimensional
(Bandpass) Filter controller.
28. Sum Controller
Discussion
30. Get Controller Info Note that this does not sum multiple controllers, but rather
sums multiple dimensions within one controller.
Finite Elements
Appendix
Index
Options
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_dimension_sum.html[28/05/13 15:50:51]
Modalys - Sum Controller
http://support.ircam.fr/docs/Modalys/current/co/controller_dimension_sum.html[28/05/13 15:50:51]
Modalys - Spread Controller
Guide Map
Accesses Spread Controller See also

Sum Controller
Connections
Controllers Description Dimension-Mapping
Controller
1. Constant Controller Outputs in all dimensions the value received by a one
2. Envelope Controller dimensional channel input controller.
5. Access Force Controller (make-controller 'spread ... )
The 'spread controller can be created using the following
9. MIDI File Controller Lisp syntax:
11. Send Message
12. Set Breakpoint (make-controller 'spread dimension
period controller)

16. Expression Controller The 'spread controller takes three arguments:
18. Sine Controller
controller.
period: re-sampling period of the controller (in
seconds).
Controller
controller: one-dimensional input controller.
As always, the period defines the time between the
updates of the controller. If zero is given then it updates
every sample.
Filter
25. Constant Second Order The input controller should be a one-dimensional
(Bandpass) Filter
controller.
(Bandpass) Filter
27. Dimension-Mapping Controller Discussion
28. Sum Controller
Note that this does not sum multiple controllers, but rather
29. Spread Controller sums multiple dimensions within one controller.
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_dimension_spread.html[28/05/13 15:51:23]
Modalys - Get Controller Info
Guide Map
Accesses Get Controller Information See also

Connections
Controllers Description Get Access Information
1. Constant Controller Get Connection

Get information about a controller (its current value) using the
Information
standard (get-info ... ) function.
3. Access Speed Controller Get Workspace
4. Access Position Controller Information
5. Access Force Controller (get-info 'value ... )
9. MIDI File Controller controller-specific information (its current value) using the
10. Dynamic Controller following Lisp syntax:
11. Send Message
12. Set Breakpoint
(get-info 'value
controller_reference dimension)
16. Expression Controller Parameters
17. Foreign-Call Controller The (get-info 'value ... ) function requires the following two
18. Sine Controller arguments to get information about an access:
controller_reference: the controller whose value
we want to query.
Controller
dimension: dimension on the controller.
There is only one type of controller-specific data that we
can obtain using the standard (get-info ...) function:
Filter
25. Constant Second Order 'value
(Bandpass) Filter
26. Variable Second Order An example which gets the value from a one-dimensional
(Bandpass) Filter
controller:
28. Sum Controller
29. Spread Controller (get-info 'value my-controller 0)
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/controller_info_get.html[28/05/13 15:51:54]
Modalys - New Workspace
Guide Map
Modalys
Summary
New Workspace See also
Load Modalys Script
Description Run Synthesis
Getting Started
Play Sound
Objects Clears the Modalys workspace, destroys all objects.
Accesses Stop
Connections Quit Modalys
Controllers (new)
1. New Workspace
2. Run Synthesis The (new) function can be created using the following
3. Play Sound Lisp syntax:
5. Set Precision
(new)
Parameters
8. Set Angle Mode
9. Get Version This should generally be the first command you give
10. Stop Modalys at the start of a script. It has no additional
11. Quit Modalys parameters.
12. Point Output
13. Point Input
14. Save AIFF Sound File Options
15. Save Floating-Point Sound File
16. Set Sample Rate There are no special options for this function.
17. Set Bit Depth
18. Set Number of Channels
19. Get Workspace Info
20. Get Angle Mode
21. Make Plot
22. Plot Value
23. Plot
24. Load Modalys Script
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_new.html[28/05/13 15:52:42]
Modalys - Run Synthesis
Guide Map
Modalys
Summary
Run Synthesis See also
Play Sound
Description New Workspace
Getting Started
Stop
Objects Runs the synthesis in the current Modalys workspace.
Accesses Load Modalys Script
Controllers (run ... )
1. New Workspace
2. Run Synthesis The (run ... ) function can be created using the following
5. Set Precision
(run duration)
Parameters
8. Set Angle Mode
9. Get Version The (run ... ) function takes one argument:
10. Stop
duration: the number of seconds of sound
11. Quit Modalys
Modalys will compute.
12. Point Output
13. Point Input
Discussion
14. Save AIFF Sound File
15. Save Floating-Point Sound File Note that if you run several seconds of sound, stop, and
16. Set Sample Rate then type run again, Modalys will continue calculating from
17. Set Bit Depth where you left off rather than starting again. Hence,
18. Set Number of Channels typing:
20. Get Angle Mode (run 2.0)
21. Make Plot
(run 2.5)
22. Plot Value
23. Plot (run 1.5)
will produce a total of six seconds of sound. The
advantage of this is that you could create new objects,
destroy inactive connections, move dynamic controllers,
and other things in-between (run ... ) statements.
Finite Elements
Appendix
Index
Options

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_run.html[28/05/13 15:53:23]
Modalys - Run Synthesis
http://support.ircam.fr/docs/Modalys/current/co/workspace_run.html[28/05/13 15:53:23]
Modalys - Play Sound
Guide Map
Modalys
Summary
Play Sound See also
New Workspace
Description Load Modalys Script
Getting Started
Run Synthesis
Objects Plays the currently calculated sound.
Accesses Stop
Controllers (play)
1. New Workspace
2. Run Synthesis The (play) function can be created using the following
5. Set Precision
(play)
Parameters
8. Set Angle Mode
9. Get Version The (play) function takes no additional arguments.
10. Stop
11. Quit Modalys Discussion
12. Point Output
The (play) function is entirely optional. Although generally
13. Point Input
you will want to play the sound when it is finished
14. Save AIFF Sound File calculating, you may want to write it to a file, instead, or
15. Save Floating-Point Sound File playback the sound manually from the menu. When using
16. Set Sample Rate Modalys in real-time contexts, you do not need to play the
17. Set Bit Depth sound since new samples are constantly being calculated
18. Set Number of Channels and output. Note that when (play) is inside a loop, only
19. Get Workspace Info the (play) command in the last iteration of that loop will
20. Get Angle Mode take effect.
21. Make Plot
22. Plot Value
23. Plot Options
25. Load Modalys Component There are no special options for this function.
27. MIDI to Frequency See Also
Modalys Tutorial Example [examples coming soon!]
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_play.html[28/05/13 15:54:12]
Modalys - Set Message Level
Guide Map
Modalys
Summary
Set Message Level See also
Set Precision
Description Set Sample Rate
Getting Started
Set Bit Depth
Objects Sets the level of messages that should be shown to the user.
Accesses Set Number of
Connections
Channels
Controllers (set-message-level ... ) Set Angle Mode

The Modalys Workspace Get Angle Mode
1. New Workspace Get Version
2. Run Synthesis The (set-message-level ... ) function can be created using
Get Workspace
3. Play Sound the following Lisp syntax: Information
5. Set Precision
(set-message-level message_level)
Parameters
8. Set Angle Mode
9. Get Version The (set-message-level ... ) function takes one argument:
10. Stop
message_level: integer message level, either 0,
11. Quit Modalys
1, 2 or 3.
12. Point Output
13. Point Input The default message level is 1 (warnings only).
15. Save Floating-Point Sound File Discussion
16. Set Sample Rate
If you set the message level to zero, you won't get any
17. Set Bit Depth messages at all. Level 1 prints warnings only. Level 2
18. Set Number of Channels prints warnings, and other interesting "internal" events in
19. Get Workspace Info Modalys. Level 3 prints everything in level 2, plus all the
20. Get Angle Mode gruesome details of the internal computations.
21. Make Plot
You can obtain the current message level by using:
22. Plot Value
23. Plot
24. Load Modalys Script (get-info 'message-level)
27. MIDI to Frequency Options
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_message_level.html[28/05/13 15:54:51]
Modalys - Set Precision
Guide Map
Modalys
Summary
Set Precision See also
Set Sample Rate
Description Set Bit Depth
Getting Started
Set Number of
Objects Sets the calculation precision for computing the system.
Channels
Accesses
Connections
Set Message Level
Controllers (set-precision ... ) Set Angle Mode

1. New Workspace Get Workspace
2. Run Synthesis The (set-precision ... ) function can be created using the Information
3. Play Sound following Lisp syntax: Get Version
5. Set Precision
(set-precision mode)
Parameters
8. Set Angle Mode
9. Get Version The (set-precision ... ) function takes one argument:
10. Stop
mode: either 'float or 'double
11. Quit Modalys
12. Point Output The default precision is 'double (64-bit precision).
13. Point Input
14. Save AIFF Sound File Discussion
You can take advantage of vector processing on your
16. Set Sample Rate
computer by switching to the 'float precision. This can be
17. Set Bit Depth especially useful in real-time contexts. Warning: the
18. Set Number of Channels sound may be slightly different, but the computation is
19. Get Workspace Info about 30% faster. After each (new), the mode is reset to
20. Get Angle Mode 'double.
21. Make Plot
[This was definitey true on PowerPC computers which
22. Plot Value
used the motorola chips' AltiVec vector optimization. In
23. Plot
theory, the same kind of vector optimization also exists on
intel chips as SSE... this should be verified.]
Options
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_precision.html[28/05/13 15:55:40]
Modalys - Run Synthesis in Real-Time
Guide Map
Modalys
Summary
Run Synthesis in Real-Time See also
Run Synthesis
Description Stop
Getting Started
Accesses
Connections
Controllers (run-real-time ... )
1. New Workspace
2. Run Synthesis The (run-real-time ... ) function can be created using the
3. Play Sound following Lisp syntax:
5. Set Precision
(run-real-time duration)
8. Set Angle Mode or:
9. Get Version
10. Stop
(run-real-time)
11. Quit Modalys
12. Point Output
Parameters
13. Point Input
14. Save AIFF Sound File The (run-real-time ... ) function takes one optional
15. Save Floating-Point Sound File argument:
16. Set Sample Rate
duration: the number of seconds of sound
17. Set Bit Depth
Modalys will compute.
Discussion
20. Get Angle Mode
21. Make Plot This command is similar to the (run) command, except
22. Plot Value that it allows Modalys to run in real-time, either indefinitely
23. Plot (in which case the user can stop the synthesis from the
24. Load Modalys Script real-time progress bar displayed by ModaLisp program),
or for a given amount of time.

Options
Finite Elements
Appendix There are no special options for this function.
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_run_realtime.html[28/05/13 15:56:29]
Modalys - Listen to IP Port
Guide Map
Modalys
Summary
Listen to IP Port See also
Run Synthesis in Real-
An Introduction to Modalys Time
Description
Getting Started Send Message
Dynamic Controller
Accesses
Connections
Controllers (listen-ip-port ... )
1. New Workspace
2. Run Synthesis The (listen-ip-port ... ) function can be created using the
5. Set Precision
(listen-ip-port port_number)
Parameters
8. Set Angle Mode
9. Get Version The (listen-ip-port ... ) function takes one argument:
10. Stop
port_number: the number of the IP port to listen
11. Quit Modalys
to for incoming OSC messages.
12. Point Output
13. Point Input
Discussion
15. Save Floating-Point Sound File This command can be used to set an IP port from which
16. Set Sample Rate incoming OSC messages will be sent to dynamic
17. Set Bit Depth controllers when running Modalys in real-time. For
18. Set Number of Channels example to listen to port 4000, you would use:
20. Get Angle Mode (listen-ip-port 4000)
21. Make Plot
(run-real-time)
22. Plot Value
23. Plot
25. Load Modalys Component Options
27. MIDI to Frequency There are no special options for this function.
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_port_ip.html[28/05/13 15:57:18]
Modalys - Set Angle Mode
Guide Map
Modalys
Summary
Set Angle Mode See also
Get Angle Mode
Description Get Workspace
Getting Started Information
Objects Set the kind of numbers you will be using to define angles
Set Message Level
Accesses (degrees or radians).
Connections
Set Precision
Controllers Set Sample Rate

The Modalys Workspace (set-angle-mode ... ) Set Bit Depth
1. New Workspace Set Number of
2. Run Synthesis Channels
3. Play Sound The (set-angle-mode ... ) function can be created using Get Version
4. Set Message Level the following Lisp syntax:
5. Set Precision
(set-angle-mode mode_number)
8. Set Angle Mode
Parameters
9. Get Version
10. Stop The (set-angle-mode ... ) function takes one argument:
11. Quit Modalys
mode _number: mode used for defining angles. 0
12. Point Output
= degrees, 1 = pi-radians.
13. Point Input
14. Save AIFF Sound File The default mode is 0 (degrees: 0-360). This can be used
15. Save Floating-Point Sound File to allow angles to be specified in radians (0-2pi), instead.
16. Set Sample Rate
17. Set Bit Depth Discussion
18. Set Number of Channels This might possibly not affect all angle values in Modalys,
19. Get Workspace Info but it does affect things like the 'leaky-valve connection,
20. Get Angle Mode among others (listed whaere appropriate in the relevant
21. Make Plot object's reference pages. By default, Modalys uses angles
22. Plot Value in degrees.
23. Plot
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_mode_angle_set.html[28/05/13 15:57:59]
Modalys - Get Version
Guide Map
Modalys
Summary
Get Version See also
Set Message Level
Description Set Precision
Getting Started
Set Sample Rate
Objects Obtain the version of Modalys being used.
Accesses Set Bit Depth
Connections Set Number of
Controllers (get-version) Channels
The Modalys Workspace Set Angle Mode
1. New Workspace Get Angle Mode
2. Run Synthesis The (get-version ... ) function can be created using the
Get Workspace
3. Play Sound following Lisp syntax: Information
5. Set Precision
(get-version)
Parameters
8. Set Angle Mode
9. Get Version The (get-version) function takes no additional arguments.
10. Stop
11. Quit Modalys Discussion
12. Point Output
The (get-version) function allows you to obtain the version
13. Point Input
number of Modlays. This could be useful in order to make
14. Save AIFF Sound File sure that a user is running your script with the same
15. Save Floating-Point Sound File version of Modalys, and to optionally behave differently if
16. Set Sample Rate not (for example when a new version of Modalys has a
17. Set Bit Depth function not present in older versions).
20. Get Angle Mode Options
21. Make Plot
22. Plot Value There are no special options for this function.
23. Plot
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_version.html[28/05/13 15:58:37]
Modalys - Stop
Guide Map
Modalys
Summary
Stop See also
Run Synthesis
Description Play Sound
Getting Started
New Workspace
Objects Allows you to stop synthesis, or stop playback of a sound.
Accesses Basically, it causes Modalys to stop doing whatever it is doing. Load Modalys Script
Controllers
The Modalys Workspace (stop)
1. New Workspace
2. Run Synthesis
3. Play Sound The (stop) function can be created using the following
4. Set Message Level Lisp syntax:
5. Set Precision
(stop)
8. Set Angle Mode
Parameters
9. Get Version
10. Stop The (stop) function takes no additional arguments.
11. Quit Modalys
12. Point Output Discussion
13. Point Input
The (stop) function lets you to abort a very long synthesis
14. Save AIFF Sound File part-way through, or stop playback of a sound before it
15. Save Floating-Point Sound File has finished playing. Basically, it is a general tool that
16. Set Sample Rate causes Modalys to stop doing whatever it is doing. It is
17. Set Bit Depth probably something you don't want to type into your
18. Set Number of Channels scripts. Use it with caution.
20. Get Angle Mode
21. Make Plot Options
22. Plot Value
23. Plot There are no special options for this function.
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_stop.html[28/05/13 15:59:22]
Modalys - Quit Modalys
Guide Map
Modalys
Summary
Quit Modalys See also
New Workspace
Description Load Modalys Script
Getting Started
Run Synthesis
Objects Quit the Modalys application (without asking to save changes to
Accesses currently open scripts). Play Sound
Connections Stop
Controllers
The Modalys Workspace (quit)
1. New Workspace
2. Run Synthesis
3. Play Sound The (quit) function can be invoked using the following Lisp
4. Set Message Level syntax:
5. Set Precision
(quit)
8. Set Angle Mode
Parameters
9. Get Version
10. Stop The (quit) function takes no additional arguments.
11. Quit Modalys
13. Point Input
The (quit) function causes Modalys to quit immediately
14. Save AIFF Sound File without asking to save changes to currently open scripts.
15. Save Floating-Point Sound File You will probably generally want to choose quit from the
16. Set Sample Rate menu, instead, but we thought we should mention it so
17. Set Bit Depth you can be careful not to type and evaluate it by accident!
20. Get Angle Mode Options
21. Make Plot
22. Plot Value There are no special options for this function.
23. Plot
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_quit.html[28/05/13 16:00:10]
Modalys - Point Output
Guide Map
Modalys
Summary
Point Output See also
Set Number of
An Introduction to Modalys Channels
Description
Getting Started Point Input
Objects Creates an audio output from the speed of an access or directly
Accesses
Accesses from the value of a controller.
Connections
Controllers
Controllers
The Modalys Workspace (make-point-output ... )
1. New Workspace
2. Run Synthesis
3. Play Sound An audio output from the Modalys workspace can be
4. Set Message Level created using the following Lisp syntax:
5. Set Precision
(make-point-output
access_reference)
8. Set Angle Mode
9. Get Version
10. Stop or:
11. Quit Modalys
12. Point Output
(make-point-output
13. Point Input
access_reference channel scalar
mode_selection)
16. Set Sample Rate
17. Set Bit Depth or:
(make-point-output
20. Get Angle Mode
controller_reference channel
21. Make Plot scalar selected_dimension)
22. Plot Value
23. Plot
Parameters
25. Load Modalys Component The (make-point-output ... ) function takes from one to
26. Save Mlys Script File four arguments:
27. MIDI to Frequency access_reference: the access to which the
28. Frequency to MIDI "loudspeaker" should be attached.
Finite Elements controller_reference: a controller whose value
Appendix will be output, instead of the speed of an access.
Index channel: (optional) which output channel to send
the samples to (default 0, i.e. channel 1).
scalar: (optional) value or controller to scale the
amplitude of the samples (default 1).
©IRCAM 2013 (optional) if provided, it is used
mode_selection:
http://support.ircam.fr/docs/Modalys/current/co/workspace_point_output.html[28/05/13 16:00:59]
to can select an individual mode (or modes) to

output (default 0 = all modes).
selected_dimension: dimension of the controller
which will be output (default 0).
This function lets you output the speed of an access (i.e.

the sound generated by that access), or the value of a
controller.
The channel parameter sets the output channel for this

point-output. The number of output channels is
automatically set using the highest value given for this
parameter, unless overridden by the (set-number-of-
channels ... ) function.
The scalar can either be a value or a controller to set or

dynamically modify the amplitude of the output samples.
The mode selection, when set to 0 outputs the sum of all

modes. To output an individual more, you should provide
a numerical value, where 1 corresponds to the first mode,
2 to the 2nd, etc... You can also provide a list for this
parameter in order to output multiple modes. All output
modes are scaled by the controller as a unit, so if you
want multiple modes with independent amplitude
controllers, you should make multiple point-outputs.
[actually this seems to be bugged - 1 currently outputs the
2nd harmonic, and so forth - it seems there is no way to
output the fundamental by itself...]
The selected dimension corresponds to the dimension of

the controller whose value will be output.
Discussion
Manually setting the number of output channels is

optional. Modalys will automatically determine the number
of output channels based on the channel arguments
provided to the Point Output functions that are used in the
script. (The make-point-output command additionally has
optional arguments to set which channel to direct the
output to.)
Options
Retro-Compatibility
Some very old versions of Modalys used a separate

function to output a controller:
(make-output-from-controller
controller_reference channel
selected_dimension)
This no longer exists, since it has been integrated into the
make-point-output function itself. Old scripts may need to

be updated accordingly.
Modalys - Point Input
Guide Map
Modalys
Summary
Point Input See also
Signal Controller
Description Point Output
Getting Started
Objects Creates an audio input to be used with a signal controller.
Accesses
Connections
Controllers (make-point-input ... )
1. New Workspace
2. Run Synthesis An audio input into the Modalys workspace can be
3. Play Sound created using the following Lisp syntax:
5. Set Precision
(make-point-output channel scalar
)
8. Set Angle Mode
Parameters
9. Get Version
10. Stop The (make-point-input ... ) function takes up to two
11. Quit Modalys arguments:
12. Point Output
channel: input channel number (default 0, i.e.
13. Point Input channel 1).
14. Save AIFF Sound File scalar: (optional) value or controller to scale the
15. Save Floating-Point Sound File amplitude of the samples (default 1).
16. Set Sample Rate
17. Set Bit Depth As with the point-output function, the channels are
numbered starting from 0.
19. Get Workspace Info The scalar can either be a static numerical value or a
20. Get Angle Mode controller, which could be used to vary the volume
21. Make Plot dynamically (i.e. to create a fade-in, fade-out, etc...).
22. Plot Value
23. Plot Discussion
The (make-point-input ...) function should be used with
(make-controller 'signal ...) in order to create a controller
26. Save Mlys Script File that can be used to manipulate parameters in Modalys.
27. MIDI to Frequency For example:
Finite Elements
Appendix
(setq my-input (make-point-input
0))
Index
controller 'signal 1 my-input))
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_point_input.html[28/05/13 16:01:49]
Modalys - Point Input
A multi-dimensional controller can be created like this:

0))

1))

controller 'signal 2 my-input0
my-input1))
Options
There are no additional options for this function.
http://support.ircam.fr/docs/Modalys/current/co/workspace_point_input.html[28/05/13 16:01:49]
Modalys - Save AIFF Sound File
Guide Map
Modalys
Summary
Save AIFF Sound File See also
Save Floating-Point
An Introduction to Modalys Sound File
Description
Getting Started Set Sample Rate
Objects Saves a synthesized sound to the standard cross-platform AIFF
Set Bit Depth
Accesses (Audio Interchange File Format) file. (AIFF-C to be precise.)
Connections
Set Number of
Channels
Controllers
The Modalys Workspace (save-aiff ... )
1. New Workspace
2. Run Synthesis
3. Play Sound The (save-aiff ... ) function can be created using the
4. Set Message Level following Lisp syntax:
5. Set Precision
(save-aiff filename)
8. Set Angle Mode
Parameters
9. Get Version
10. Stop The (save-aiff ... ) function takes one argument:
11. Quit Modalys
filename: pathname of sound file to be saved. (in
12. Point Output
quotes.)
13. Point Input
14. Save AIFF Sound File The pathname of the soundfile should be provided in
15. Save Floating-Point Sound File quotes. The path is relative to the Modalys application,
16. Set Sample Rate unless it begins with a slash, in which case it is an
17. Set Bit Depth absolute path from the root directory of the hard disk. The
operating system. [At one time Modalys had a user-
settable soundfile directory that was used as the default
20. Get Angle Mode
directory.]
21. Make Plot
22. Plot Value The sampling rate and bit depth of the sound file will
23. Plot depend on that set in the Modalys workspace for the
24. Load Modalys Script synthesis.
26. Save Mlys Script File Discussion
27. MIDI to Frequency For individual sounds, it is usually easier to choose the
28. Frequency to MIDI "Save Sound as AIFF..." option from the application's
Finite Elements Script menu. Nonetheless, it is very useful to be able to
Appendix automatically save sound files from within a script, such
Index as in cases where the sound synthesis is run multiple
times with different parameters in a loop.
When saving from a script, remember that the name of

the soundfile should be in quotes. The following command
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_sound_save_aiff.html[28/05/13 16:02:37]
will save the synthesis to an aiff file in the same directory

as the Modalys application:
(save-aiff "mysound.aiff")
Generally, you will probably want to use an absolute path

such as:
(save-aiff "/my-disk/my-
folder/mysound.aiff")
Lisp string formatting commands can also be useful when

calculating a large number of related files, or when
iterating a script in a loop. For example:
(defvar counter)
(setq counter 0)
. . .
(setq counter (+ 1 counter))
(save-aiff (format NIL "mysound-

~S.aiff" counter))
More information about this will be included in a future

tutorial about useful basic Lisp functions.
Note that the number of channels in the AIFF file will the
same as the number of output channels. Although
Modalys can handle multichannel AIFF files, not all audio
software is able to do so! You may have to manually split
multichannel files into individual mono files using your
favorite audio editing application.
The sample rate of the fill will be the same as the sample
rate set in the Modalys environment using (set-sample-
rate ... ). By default this is 44100 Hz.
Modalys also saves the AIFF file with the bit depth set in
the Modalys environment using (set-bit-depth ... ). By
default this is set to 24-bit samples. You can currently
choose either 16, 24 or 32 bit integer samples, for
compatibility with the standard AIFF-C options. Again,
sound files may need to be converted for use with some
audio editing software applications.
Options
Retro-Compatibility
Formerly this function was called (save ... ). Old scripts
should be updated to the new syntax.
Modalys - Save Floating-Point Sound File
Guide Map
Modalys
Summary
Save Floating-Point Sound See also
File Save AIFF Sound File
Set Sample Rate
Getting Started
Description Set Bit Depth
Objects
Accesses Saves the current sound as a raw soundfile in floating-point Set Number of
Connections format. Channels
Controllers
1. New Workspace (save-float ... )
2. Run Synthesis
3. Play Sound
4. Set Message Level The (save-float ... ) function can be created using the
5. Set Precision following Lisp syntax:
(save-float filename)
8. Set Angle Mode
9. Get Version
Parameters
10. Stop
11. Quit Modalys The (save-float ... ) function takes one argument:
12. Point Output
filename: pathname of sound file to be saved. (in
13. Point Input quotes.)
15. Save Floating-Point Sound File The pathname of the soundfile should be provided in
16. Set Sample Rate quotes. The path is relative to the Modalys application,
17. Set Bit Depth unless it begins with a slash, in which case it is an
operating system. [At one time Modalys had a user-
20. Get Angle Mode
settable soundfile directory that was used as the default
21. Make Plot
directory.]
22. Plot Value
23. Plot
Discussion
25. Load Modalys Component For individual sounds, it is usually easier to choose the
26. Save Mlys Script File "Save Sound as AIFF..." option from the application's
27. MIDI to Frequency Script menu. Nonetheless, there may be cases when you
want to save the original (32-bit) floating point data to a
raw data file. Not all applications will be able to play it.
Finite Elements
Appendix
Index
Options

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_sound_save_float.html[28/05/13 16:03:26]
Modalys - Save Floating-Point Sound File
http://support.ircam.fr/docs/Modalys/current/co/workspace_sound_save_float.html[28/05/13 16:03:26]
Modalys - Set Sample Rate
Guide Map
Modalys
Summary
Set Sample Rate See also
Set Bit Depth
Description Set Number of
Getting Started Channels
Objects Sets the current sample rate for the synthesis.
Set Precision
Accesses
Connections
Set Message Level
Controllers (set-sample-rate ... ) Set Angle Mode

1. New Workspace Get Workspace
2. Run Synthesis The (set-sample-rate ... ) function can be created using Information
3. Play Sound the following Lisp syntax: Get Version
5. Set Precision
(set-sample-rate sample_rate)
Parameters
8. Set Angle Mode
9. Get Version The (set-sample-rate ... ) function takes one argument:
10. Stop
sample_rate: A number specifying the sample
11. Quit Modalys
rate (in Hertz).
12. Point Output
13. Point Input The default sample rate is 44100 Hz.
16. Set Sample Rate
Modalys will cheerfully compute a system at any sample
17. Set Bit Depth rate you request. However, the soundfiles that result from
18. Set Number of Channels running Modalys may not necessarily be playable on your
19. Get Workspace Info audio hardware. We suggest sticking to the commonly
20. Get Angle Mode used sample rates: 44100, 48000, 96000, etc...
21. Make Plot
You can obtain the current sample rate by using:
22. Plot Value
23. Plot
24. Load Modalys Script (get-info 'sample-rate)
When using Modalys in real-time contexts, such as the
modalys~ object running in Max/MSP, it will use the
sampling rate set in the audio settings.
Finite Elements
Appendix
Index
Options

©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_sound_samplerate.html[28/05/13 16:04:14]
Modalys - Set Sample Rate
http://support.ircam.fr/docs/Modalys/current/co/workspace_sound_samplerate.html[28/05/13 16:04:14]
Modalys - Set Bit Depth
Guide Map
Modalys
Summary
Set Bit Depth See also
Set Sample Rate
Description Set Number of
Getting Started Channels
Objects Sets the current sample bit depth for the synthesis.
Set Precision
Accesses
Connections
Set Message Level
Controllers (set-bit-depth ... ) Set Angle Mode

1. New Workspace Get Version
2. Run Synthesis The (set-bit-depth ... ) function can be created using the
Get Workspace
3. Play Sound following Lisp syntax: Information
5. Set Precision
(set-bit-depth bit_depth)
Parameters
8. Set Angle Mode
9. Get Version The (set-bit-depth ... ) function takes one argument:
10. Stop
bit_depth: A number specifying the bit depth for
11. Quit Modalys
samples saved in a file.
12. Point Output
13. Point Input The default bit depth is 24.
16. Set Sample Rate
The default bit depth is 24. You should manually change
17. Set Bit Depth this to 16 after the (new) command if you want to save
18. Set Number of Channels sounds as 16-bit AIFF files.
There is presently no way to obtain the current bit depth
20. Get Angle Mode
using the standard (get-info ...) function.
21. Make Plot
22. Plot Value
23. Plot
Options
26. Save Mlys Script File There are no special options for this function.
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_sound_bitdepth.html[28/05/13 16:05:03]
Modalys - Set Number of Channels
Guide Map
Modalys
Summary
Set Number of Channels See also
Point Output
Description Set Sample Rate
Getting Started
Set Bit Depth
Objects Can be optionally used to set the current number of channels
Accesses to use, overriding the automatic calculation based derived from Set Precision
Connections the channel arguments used with the point outputs. Set Message Level
Controllers Set Angle Mode
Get Angle Mode
1. New Workspace (set-number-of-channels ... )
Get Version
2. Run Synthesis
Lisp Syntax and Default Values Get Workspace
3. Play Sound
The (set-number-of-channels ... ) function can be created Information
5. Set Precision using the following Lisp syntax:
(set-number-of-channels value)
8. Set Angle Mode
9. Get Version
Parameters
10. Stop
11. Quit Modalys The (set-number-of-channels ... ) function takes one
12. Point Output argument:
13. Point Input value: number of audio output channels.
15. Save Floating-Point Sound File You can set any number of channels you like. The default
16. Set Sample Rate is 1 channel. If you use more than two channels, you may
17. Set Bit Depth not be able to play the sound.
Discussion
20. Get Angle Mode Manually setting the number of output channels is
21. Make Plot optional. Modalys will automatically determine the number
22. Plot Value of output channels based on the channel arguments
23. Plot provided to the Point Output functions that are used in the
24. Load Modalys Script script. (The make-point-output command additionally has
25. Load Modalys Component optional arguments to set which channel to direct the
26. Save Mlys Script File output to.)
Appendix
Index There are no special options for this function.
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_sound_channels.html[28/05/13 16:05:53]
Modalys - Get Workspace Info
Guide Map
Modalys
Summary
Get Workspace Information See also
Description Get Access Information
Getting Started
Get Connection
Objects Get information about the Modalys workspace using the
Information
Accesses standard (get-info ... ) function.
Connections
Get Controller
Information
Controllers
The Modalys Workspace (get-info ... )
1. New Workspace
2. Run Synthesis
3. Play Sound The generic (get-info ... ) function can be used to obtain
4. Set Message Level workspace-specific information using the following Lisp
5. Set Precision syntax:
(get-info data_type )
8. Set Angle Mode
9. Get Version
Parameters
10. Stop
11. Quit Modalys The (get-info ... ) function requires just one arguments to
12. Point Output get information about the workspace:
13. Point Input data_type: a string defining the type of data to
14. Save AIFF Sound File request.
16. Set Sample Rate
Controllers
17. Set Bit Depth
18. Set Number of Channels The following types of workspace-specific data can be
requested using the standard (get-info ...) function:
20. Get Angle Mode 'sample-rate

21. Make Plot 'sample-period
22. Plot Value 'num-outputs
23. Plot 'max-sample
24. Load Modalys Script 'time (total amount of time synthesized thus far)
Respectively, they let you get the sample rate, sample
period, number of output channels, and the maximum
sample value (absolute value) of the samples calculated
so far.
Finite Elements
Appendix Examples of using these:
Index
(get-info 'sample-rate)
(get-info 'sample-period)
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_info_get.html[28/05/13 16:06:41]
Modalys - Get Workspace Info
(get-info 'num-outputs)
(get-info 'max-sample)
(get-info 'time)
Options
http://support.ircam.fr/docs/Modalys/current/co/workspace_info_get.html[28/05/13 16:06:41]
Modalys - Get Angle Mode
Guide Map
Modalys
Summary
Get Angle Mode See also
Set Angle Mode
Description Get Workspace
Getting Started Information
Objects Get the current state of the angle mode that Modalys is using.
Set Message Level
Accesses
Connections
Set Precision
Controllers (get-angle-mode) Set Sample Rate

The Modalys Workspace Set Bit Depth
1. New Workspace Set Number of
2. Run Synthesis The (get-angle-mode) function can be created using the Channels
3. Play Sound following Lisp syntax: Get Version
5. Set Precision
(get-angle-mode)
Parameters
8. Set Angle Mode
9. Get Version The (get-angle-mode) function has no additional
10. Stop arguments.
11. Quit Modalys
13. Point Input
This function returns 0 if the angle mode has been set to
14. Save AIFF Sound File use degrees, and 1 if set to use radians. By default,
15. Save Floating-Point Sound File Modalys uses angles in degrees.
16. Set Sample Rate
17. Set Bit Depth
18. Set Number of Channels Options
20. Get Angle Mode
21. Make Plot
22. Plot Value
23. Plot
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_mode_angle_get.html[28/05/13 16:07:31]
Modalys - Make Plot
Guide Map
Modalys
Summary
Make Plot See also
Plot Value
Description Plot
Getting Started
Objects Initialize a graph for plotting data obtained from a controller.
Accesses
Connections
Controllers
1. New Workspace
2. Run Synthesis
3. Play Sound
5. Set Precision
8. Set Angle Mode
9. Get Version (make-plot)
10. Stop
11. Quit Modalys Lisp Syntax and Default Values
12. Point Output
The (make-plot) function can be created using the
13. Point Input following Lisp syntax:
16. Set Sample Rate (make-plot)
17. Set Bit Depth
18. Set Number of Channels Parameters
19. Get Workspace Info This command initializes a graph, and returns a reference
20. Get Angle Mode to it. It has no additional parameters.
21. Make Plot
22. Plot Value Discussion
23. Plot
You should use (make-plot) before calling any of the
other plotting functions, since they need the reference to
the graph it creates. Here is a simple example of how to
use this plotting feature (the resulting graph is shown,
above):
Finite Elements
Appendix (setq my-env (make-controller
Index 'envelope 1 '((0 0) (1 1) (2 0))))
(setq graph (make-plot))
(plot-value graph "my-envelope"

my-env)
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_plot_make.html[28/05/13 16:08:21]
Modalys - Make Plot
(run 2)
(plot graph "My Plotted Controller

Data")
Naturally, the (new) command deletes all plots when it

clears the workspace.
Options
Retro-Compatibility
In very old versions of Modalys, the plot feature worked

slightly differently. Older scripts may need to be updated
to the new syntax.
http://support.ircam.fr/docs/Modalys/current/co/workspace_plot_make.html[28/05/13 16:08:21]
Modalys - Plot Value
Guide Map
Modalys
Summary
Plot Value See also
Make Plot
Description Plot
Getting Started
Objects Plots a one curve over time from a controller dimension's value.
Accesses
Connections
Controllers
1. New Workspace
2. Run Synthesis
3. Play Sound
5. Set Precision
8. Set Angle Mode
9. Get Version (plot-value ... )
10. Stop
12. Point Output
The (plot-value) function can be created using the
13. Point Input following Lisp syntax:
16. Set Sample Rate (plot-value plot_reference label
17. Set Bit Depth
controller_reference dimension)

19. Get Workspace Info Parameters
20. Get Angle Mode The (plot-value) function takes three or four arguments:
21. Make Plot
plot_reference: reference to a plot created with
22. Plot Value
(make-plot)
23. Plot
label: a string (in quotes) that will be used as a
label for the graph of this data
controller_reference: a controller whose data will
be plotted.
dimension: (optional) dimension of the controller
28. Frequency to MIDI which will be plotted (defaults to 0)
Finite Elements
Appendix You obviously do not need to provide a dimension for
Index one-dimensional controllers. Dimensions are numbered
starting from 0.
Discussion
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_plot_value.html[28/05/13 16:09:11]
Modalys - Plot Value
For each curve you want plotted, you call the plot-value
command before running the synthesis. The first
argument is a reference to a graph created with (make-
plot). The second argument is a string which will be the
label for that curve. The third argument is a reference to a
controller whose data will be graphed. The fourth
argument is optional, and can be used to specify a
dimension other than the first for multi-dimensional
controllers. Here is a simple example of how to plot the
three dimensions of a 3-dimensional controller (the
resulting graph is shown in the image, above):

'envelope 3
'( (0 0 0.5 1)
(1 1 0 0.25)
(2 0 1 0.75)) ))
(setq graph (make-plot))
(plot-value graph "my-envelope-

dim1" my-env 0)

dim2" my-env 1)

dim3" my-env 2)
(run 2)
(plot graph "My Plotted Controller

Data")
This command must be called after (make-plot) and

before running the synthesis with the (run ...) command.
Options
Retro-Compatibility
In very old versions of Modalys the plot feature worked

slightly differently. The (plot-value ... ) function used a
lambda expression instead of a controller. Older scripts
will need to be updated to the new syntax.
http://support.ircam.fr/docs/Modalys/current/co/workspace_plot_value.html[28/05/13 16:09:11]
Modalys - Plot
Guide Map
Modalys
Summary
Plot See also
Make Plot
Description Plot Value
Getting Started
Objects Plots a graph after synthesis of the system has been run.
Accesses
Connections
Controllers
1. New Workspace
2. Run Synthesis
3. Play Sound
5. Set Precision
8. Set Angle Mode
9. Get Version (plot ... )
10. Stop
12. Point Output The (plot ... ) function can be created using the following
13. Point Input Lisp syntax:
16. Set Sample Rate
(plot plot_reference label type
domain_min domain_max range_min
17. Set Bit Depth
range_max)
20. Get Angle Mode
Parameters
21. Make Plot The (plot ... ) function takes a minimum of two, and up to
22. Plot Value seven arguments:
23. Plot
plot_reference: reference to a plot created with
(make-plot)
label: a string (in quotes) that will be used as a
label in the title-bar for this graph.
27. MIDI to Frequency type: (optional) a value to define the type of plot.
28. Frequency to MIDI (default 0 = plot over time)
Finite Elements domain_min: (optional) minimum value for the x-
Appendix axis graph.
Index domain_max: (optional) maximum value for the x-
axis graph.
range_min: (optional) minimum value for the y-
axis graph.
©IRCAM 2013
range_max: (optional) maximum value for the y-
http://support.ircam.fr/docs/Modalys/current/co/workspace_plot_plot.html[28/05/13 16:10:01]
Modalys - Plot
axis graph.
The type parameter can be set to 0 to plot the specified

controllers, or set to 1 to plot a 2-D x/y graph for the first
two controllers.
If the x and y ranges are not given, then plot uses the
minimum and maximum values of the data to
automatically set the graph's domain and range.
Discussion
The (plot ... ) function should be called after the synthesis

has been calculated using (run), naturally. By default, plot
wil plot the controllers for the entire duration of the
synthesis. However, by adjusting the values for
minimum_x, maximum_x, etc., one can “zoom-in” on the
area of interest in the plot (for example, the exact point in
time when one object is supposed to be striking another).
The above image shows a graph from the 'strike
connection script that zooms in to the data around the 50
millisecond point.
(plot graph "hammered plate

(example 2)" 0 0.0485 .0540 -.0003
.0003)
The plot command itself must be used after running the

synthesis, but the other plot commands should be called
before.
Naturally, you can call the plot function as often as you

want; usually you are interested in a small part of the plot
data, and you zoom in by calling plot with a smaller and
smaller plot area. You can keep making plots until new is
called. The “new” command throws out the plot data.
Options
Retro-Compatibility
In very old versions of Modalys the plot feature worked

slightly differently. The (plot ... ) function used slightly
different arguments. Older scripts will need to be updated
to the new syntax.
http://support.ircam.fr/docs/Modalys/current/co/workspace_plot_plot.html[28/05/13 16:10:01]
Modalys - Load Modalys Script
Guide Map
Modalys
Summary
Load Modalys Script See also
Load Modalys
An Introduction to Modalys Component
Description
Getting Started Save Mlys Script File
Objects Loads a Modalys script file into Modalys.
Accesses
Connections
Controllers (load ... )
1. New Workspace
2. Run Synthesis The (load ... ) function can be created using the following
5. Set Precision
(load filename)
Parameters
8. Set Angle Mode
9. Get Version The (load ... ) function takes one argument:
10. Stop
filename: pathname of Modalys script to be
11. Quit Modalys
loaded. (in quotes.)
12. Point Output
13. Point Input The pathname of the Modalys script should be provided in
14. Save AIFF Sound File quotes. The path is relative to the Modalys application,
15. Save Floating-Point Sound File unless it begins with a slash, in which case it is an
16. Set Sample Rate absolute path from the root directory of the hard disk. The
17. Set Bit Depth syntax for the path follows the syntax rules of your
operating system.

Discussion
20. Get Angle Mode
21. Make Plot The (load) function can be useful when you have a lot of
22. Plot Value Modalys scripts that you want to run in succession. In this
23. Plot case, each script will probably use the (save-aiff ... )
24. Load Modalys Script command to save the calculated sound to disk. The
25. Load Modalys Component following command will load and evaluate the Modalys
26. Save Mlys Script File plucked string example script:
28. Frequency to MIDI (load "Examples/lisp/Ex1.lisp")
Finite Elements
Appendix
Index
Options
Retro-Compatibility
Once upon©IRCAM
a time, the file extension (.mos at that time)
2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_file_load.html[28/05/13 16:10:51]
Modalys - Load Modalys Script
did not need to be given. It is now necessary to include

the extension, so you should make this modification when
updating older Modalys scripts.
http://support.ircam.fr/docs/Modalys/current/co/workspace_file_load.html[28/05/13 16:10:51]
Modalys - Load Modalys Component
Guide Map
Modalys
Summary
Load Modalys Component See also
Load Modalys Script
Description Save Mlys Script File
Getting Started
Objects Loads a Modalys component file into Modalys.
Accesses
Connections
Controllers (load-component ... )
1. New Workspace
2. Run Synthesis The (load-component ... ) function can be created using
3. Play Sound the following Lisp syntax:
5. Set Precision
(load-component filename)
Parameters
8. Set Angle Mode
9. Get Version The (load-component ... ) function takes one argument:
10. Stop
filename: name of Modalys component fileto be
11. Quit Modalys
loaded. (in quotes.)
12. Point Output
13. Point Input The name of the Modalys component file should be
14. Save AIFF Sound File provided in quotes, and include the extension (.lisp). The
15. Save Floating-Point Sound File path used for (load-component ... ) is has already been
16. Set Sample Rate defined in the Modalys workspace as
17. Set Bit Depth Components/runtime/lisp (for the Lisp environment) or
similar path within the Components folder.

Discussion
20. Get Angle Mode
21. Make Plot Components allow you to write Lisp code to define useful
22. Plot Value functions that can be loaded into the Modalys workspace.
23. Plot
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_file_load_component.html[28/05/13 16:25:51]
Modalys - Save Mlys Script File
Guide Map
Modalys
Summary
Save Mlys Script File See also
Load Modalys Script
Description Load Modalys
Getting Started Component
Objects Saves a the contents of the Modalys workspace to a Mlys-
Save AIFF Sound File
Accesses format Modalys script.
Connections
Save Floating-Point
Sound File
Controllers
The Modalys Workspace (save-script ... )
1. New Workspace
2. Run Synthesis
3. Play Sound The (save-script ... ) function can be created using the
4. Set Message Level following Lisp syntax:
5. Set Precision
(save-script filename)
8. Set Angle Mode
Parameters
9. Get Version
10. Stop The (save-script ... ) function takes one argument:
11. Quit Modalys
filename: pathname of Mlys file to be saved. (in
12. Point Output
quotes.)
13. Point Input
14. Save AIFF Sound File The pathname of the Mlys file should be provided in
15. Save Floating-Point Sound File quotes. The path is relative to the Modalys application,
16. Set Sample Rate unless it begins with a slash, in which case it is an
17. Set Bit Depth absolute path from the root directory of the hard disk. The
operating system.
20. Get Angle Mode
Discussion
21. Make Plot
22. Plot Value It is usually easier to choose the "Export as Mlys ..." option
23. Plot from the application's File menu. Nonetheless, it can
24. Load Modalys Script sometimes be useful to be able to automatically save
25. Load Modalys Component Mlys script files from within a Lisp script.
26. Save Mlys Script File When saving from a script, remember that the name of
27. MIDI to Frequency the Mlys file should be in quotes, and we also suggest
28. Frequency to MIDI saving the file with the extension ".mlys" (extensions are
Finite Elements not automatically added to the filename). The following
Appendix command will export a Mlys script to a file in the same
Index directory as the Modalys application:
(save-script "myscript.mlys")
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_file_save_script.html[28/05/13 16:26:32]
Modalys - Save Mlys Script File
Generally, you will probably want to use an absolute path

such as:
(save-script "/my-disk/my-
folder/myscript.mlys")
Options
http://support.ircam.fr/docs/Modalys/current/co/workspace_file_save_script.html[28/05/13 16:26:32]
Modalys - MIDI to Frequency
Guide Map
Modalys
Summary
MIDI to Frequency See also
Frequency to MIDI
Description
Getting Started
Objects Converts MIDI note values to Frequency values in Hz.
Accesses
Connections
Controllers (midi-to-freq ... )
1. New Workspace
2. Run Synthesis The (midi-to-freq ... ) function can be created using the
5. Set Precision
(midi-to-freq value)
Parameters
8. Set Angle Mode
9. Get Version The (midi-to-freq ... ) function takes one argument:
10. Stop
value: a numerical value to convert from a MIDI
11. Quit Modalys
note value to Frequency in Hertz
12. Point Output
13. Point Input The numerical value can be either an integer or a floating-
14. Save AIFF Sound File point number.
16. Set Sample Rate Discussion
17. Set Bit Depth The (midi-to-freq ... ) function is a handy built-in tool to
18. Set Number of Channels convert from MIDI note values (linear octaves, log
19. Get Workspace Info frequency) to Frequency values in Hertz.
20. Get Angle Mode
21. Make Plot
22. Plot Value Options
23. Plot
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_conversion_mtof.html[28/05/13 16:27:22]
Modalys - Frequency to MIDI
Guide Map
Modalys
Summary
Frequency to MIDI See also
MIDI to Frequency
Description
Getting Started
Objects Converts MIDI note values to Frequency values in Hz.
Accesses
Connections
Controllers (freq-to-midi ... )
1. New Workspace
2. Run Synthesis The (freq-to-midi ... ) function can be created using the
5. Set Precision
(freq-to-midi value)
Parameters
8. Set Angle Mode
9. Get Version The (freq-to-midi ... ) function takes one argument:
10. Stop
value: a numerical value to convert from a
11. Quit Modalys
Frequency in Hertz to a MIDI note value
12. Point Output
13. Point Input The numerical value returned may be a floating-point MIDI
14. Save AIFF Sound File value. It is up to you to truncate or round the value as
15. Save Floating-Point Sound File necessary.
16. Set Sample Rate
17. Set Bit Depth Discussion
18. Set Number of Channels The (freq-to-midi ... ) function is a handy built-in tool to
19. Get Workspace Info convert from Frequency values in Hertz to MIDI note
20. Get Angle Mode values (linear octaves, log frequency).
21. Make Plot
22. Plot Value
23. Plot Options
25. Load Modalys Component There are no special options for this function.
Finite Elements
Appendix
Index
©IRCAM 2013
http://support.ircam.fr/docs/Modalys/current/co/workspace_conversion_ftom.html[28/05/13 16:28:13]

Modalys Documentation PDF

Transféré par

Informations du document

Titre original

Copyright

Formats disponibles

Partager ce document

Partager ou intégrer le document

Options de partage

Avez-vous trouvé ce document utile ?

Ce contenu est-il inapproprié ?

Droits d'auteur :

Formats disponibles

Modalys Documentation PDF

Transféré par

Droits d'auteur :

Formats disponibles

Modalys

Operating Sytem and Computer Requirements

Modalys works for :

Mac OS 10.5 and later (including Mountain Lion)

Intel Mac with a minimum of 2 Gigs of RAM.

Modalys is primarily a framework that can be used under various environments:

As a stand-alone application, ModaLisp, powered by LISP language.

As a MatLab set of objects for scientific applications.

See also ©IRCAM 2013

Set Object Pitch

Modalys Documentation v. 3.3.1.rc2

Written by Richard Dudas - ©IRCAM 2013.

Operating Sytem and Computer Requirements

Modalys works for :

Mac OS 10.5 and later (including Mountain Lion)

Intel Mac with a minimum of 2 Gigs of RAM.

Modalys is primarily a framework that can be used under various environments:

As a stand-alone application, ModaLisp, powered by LISP language.

As a MatLab set of objects for scientific applications.

See also ©IRCAM 2013

Modalys An Introduction to Modalys

Richard Dudas, 2013

Basic Concepts of Synthesis with Modalys

Modalys and Its Interfaces

Open Music Library

Modalys Documentation v. 3.3.1.rc2

Written by Richard Dudas - ©IRCAM 2013.

Modalys Getting Started

Modalys components for these various environments are all found in

If this is the first time you are using Modalys, or if

If not already done so, go to the Modalys

Launch the Modalys Authorization Tool from

That’s all folks !

The ModaLisp application, found in /Applications/Modalys, is Modalys’s text-based Lisp interface.

ModaLisp is based on LispWorks’ implementation of Common Lisp.

To get started, open and study the examples from /Applications/Modalys/Examples/Lisp.

Modalys objects for Max work with Max 5 and 6.

Open Music Library

Modalys for MatLab, obviously, is used for scientific research.

You can find a couple of MatLab examples in the Examples folder.

We have subdivided this section into the following categories:

(make-access object_reference location_on_object

Accesses fall into the following topical categories:

11. Mono-Fingerboard Connection

Connections can be destroyed using (destroy-connection ... ).

Basic Unilateral Connections

These connections only affect one access/object:

These connections take two accesses/objects to perform simple interactions:

These connections take multiple accesses/objects to perform complex interactions:

The following are the most

Modalys Environment Controllers

Access Speed Controller

Controllers from Files

Run-Time and Real-Time Controllers

Math and Programming Controllers

Signal Generator Controllers

Delay and Filtering Controllers

Managing Multi-Dimensional Controllers

The following commands are specific to running Modalys in real-time:

Get Environment Information

Graphing Data with the Plot Command

Other Modalys File Functions

Load Modalys Script