OpenMusic 6 Documentation 2403

O p e n M u s i c 6U s e r M a n u a l

AUTHOR, EDITOR : CORALIE DIATKINE

TECHNICAL ADVISOR : J E A N BRESSON

D O C U M E N T V E R S I O N # 1

© IRCAM – CENTRE GEORGES POMPIDOU

O p e n M u s i c O p e n M u s i c 66U s e rU s e r M a n u a lM a n u a l

About this Document...

This document is the kernel of the OpenMusic Software user guide. It is composed of the following volumes :

Introduction

Basic concepts, entries to the user manual, additional information and publications.

Volume 1 : System Configuration and Installation

Available versions for Mac and Windows OS. Installation procedures for Mac OSX.

Volume 2 : Going Through an OM Session

Practical information and a few concepts to manage each step of a session.

Volume 3 : The OM Environment

Main features and general settings of the OM environment, as well as managing documents and functionalities of the main windows.

Volume 4 : Visual Programming

This section provides all information about visual programming tools and basic programming concepts.

Volume 5 : Advanced Visual Programming

Advanced programming concepts, including functional abstraction, control of computation and iterative programs.

Volume 6 : OM Objects

Using and manipulating basic objects, such as curves, and score objects, such as chords, rhythms, polyphonies and so on.

Volume 7 : Maquettes

Designing musical sequences and using the graphic and temporal dimensions of maquettes to define specific interactions within programs.

Volume 8 : Errors and Problems

Understanding and handling error messages.

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou 5

Contents

I - Introduction....................................................................................................................... 11

1. OpenMusic Presentation......................................................................................................... 12

2. Additional Supports and Publications.....................................................................................13

II - System Configuration and Installation............................................................................. 15

1. System Configuration............................................................................................................. 16

2. Installing OM on MacOSX.....................................................................................................16

III - Going Through an OM Session.......................................................................................19

1. Launching OM........................................................................................................................ 20

2. Workspace(s) Management.....................................................................................................22

3. Quitting OM and Saving.........................................................................................................25

IV - The OM Environment.....................................................................................................27

1. Windows of the OM Environment..........................................................................................28

2. Workspace...............................................................................................................................30

2.1. The Workspace Window.............................................................................................30

2.2. Getting Information.................................................................................................... 32

2.3. Presentation Options...................................................................................................33

2.4. Import / Export........................................................................................................... 35

3. Library.....................................................................................................................................38

3.1. Packages..................................................................................................................... 38

3.2. User Libraries............................................................................................................. 41

4. Resources................................................................................................................................ 43

5. Preferences.............................................................................................................................. 45

V - Visual Programming........................................................................................................ 48

1. Basic Visual Programming......................................................................................................49

1.1. Introduction to Patch Programming........................................................................... 49

1.2. Adding Boxes Into a Patch......................................................................................... 51

1.3. Boxes Morphology..................................................................................................... 53

1.4. Elementary Manipulations..........................................................................................55

1.5. Setting Box Inputs...................................................................................................... 57

1.6. Connections................................................................................................................ 58


1.7. Evaluation...................................................................................................................59

1.8. Documentation and Info............................................................................................. 60

1.9. Saving / Reloading a Patch.........................................................................................62

1.10. Missing References : Dead Boxes............................................................................62

2. Boxes and Patch Components.................................................................................................64

2.1. Data Boxes..................................................................................................................64

2.2. Objects – Factory Boxes.............................................................................................66

2.3. Function Boxes...........................................................................................................72

2.4. Comments...................................................................................................................81

2.5. Pictures....................................................................................................................... 82

2.6. Other Boxes................................................................................................................ 83

VI - Advanced Visual Programming...................................................................................... 85

1. Abstraction..............................................................................................................................86

1.1. Abstraction Boxes...................................................................................................... 87

1.2. Application................................................................................................................. 91

1.3. Recursive Patches.......................................................................................................95

2. Evaluation Modes................................................................................................................... 99

2.1. Lock Mode..................................................................................................................99

2.2. Evaluate-Once Mode................................................................................................ 100

2.3. Lambda Mode...........................................................................................................101

2.4. Reference Mode........................................................................................................107

3. Control Structures................................................................................................................. 108

3.1. Predicates : Testing Relations and Properties...........................................................108

3.2. Conditional Operators...............................................................................................113

3.3. Logical Operators..................................................................................................... 117

3.4. Sequential Operators................................................................................................ 120

4. Instance Objects.................................................................................................................... 122

4.1. Creation, Import, Export...........................................................................................122

4.2. Instances Editors.......................................................................................................124

4.3. Global Variables....................................................................................................... 126

4.4. Reading and Modifying Instances : Slots.................................................................128

4.5. The Store Object.......................................................................................................131

5. Iterations: OMLOOP............................................................................................................ 133

5.1. General Features.......................................................................................................134

5.2. Evaluators : Eachtime, Finally................................................................................. 136

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou8

Co

nte

nts

5.3. Iterators.....................................................................................................................139

5.4. Accumulators............................................................................................................144

5.5. A Basic Example : Building a Random Series......................................................... 150

6. Creating and Using a Pathname in a Patch........................................................................... 152

VII - OM Objects................................................................................................................. 154

1. OM Score Objects.................................................................................................................155

1.1. Score Classes............................................................................................................ 155

1.2. Score Functions........................................................................................................ 167

1.3. Score Editors............................................................................................................ 174

2. OM Basic Objects................................................................................................................. 200

2.1. Functions Package.................................................................................................... 200

2.2. Array.........................................................................................................................216

2.3. Text File Tools.......................................................................................................... 224

2.4. Dialog Items............................................................................................................. 239

2.5. Graphics....................................................................................................................250

VIII - Maquettes...................................................................................................................255

1. Creating a Maquette.............................................................................................................. 256

2. TemporalBoxes..................................................................................................................... 258

2.1. Adding TemporalBoxes in a Maquette..................................................................... 259

2.2. Elementary Manipulations........................................................................................262

2.3. Temporalboxes Appearance......................................................................................264

2.4. TemporalBoxes Value...............................................................................................265

3. The Maquette Editor............................................................................................................. 270

3.1. Maquette Editor Appearance.................................................................................... 270

3.2. Rulers and Grid.........................................................................................................272

3.3. The Palette................................................................................................................ 275

3.4. Markers and Temporal Anchors................................................................................276

4. Maquette Programming........................................................................................................ 277

4.1. Using TemporalBoxes as Functional Components : Inputs and Outputs.................277

4.2. Evaluation of the Maquette...................................................................................... 280

4.3. An Alternate Evaluation Tool : the Synthesis Patch.................................................282

4.4. Programming with TemporalBoxes..........................................................................288

5. Using Maquettes in Patches.................................................................................................. 294

5.1. Build Mode...............................................................................................................294

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou 9

Co

nte

nts

5.2. Functional Mode.......................................................................................................296

5.3. Reference Mode........................................................................................................300

X - Errors and Problems.......................................................................................................315

1. Warnings............................................................................................................................... 316

2. The Lisp Terminal Window.................................................................................................. 317

Glossary of Terms................................................................................................................ 318


Co

nte

nts

I - Introduction

Main principles, major references and links.


1. OpenMusic Presentation

OpenMusic – OM – is a computer-aided composition environment. It is a musical extension of Common Lisp, a programming language, and CLOS, a subset of Common Lisp dealing with object-oriented programming. Graphic tools and protocols give OM a full visual programming dimension.

The use of a visual interface opens new prospects in the domain of compositional processes formalization, which can influence compositional thought. Graphic representation makes it possible to master the multiple levels of compositional complexity. Last, integrating musical representations within the interface creates a tight relationship between programming, musical structures and symbols, and preserves the musical dimension of composition throughout formalization.

Visual Programs

Programming in OM is mainly done in patches, graphic representations of Lisp functions. Patches are composed of boxes that represent objects or functions, and connections between these boxes.The functions used in OM can be genuine Lisp functions, or specific OM functions that were generally defined in a musical purpose.

List Processing

"Lisp" is an abbreviation for "LISt Processing". Indeed, Lisp is entirely based on the expression of data and functions by the means of list structures. A list is a set of zero, one, or more elements, delimited by two parenthesis. This means, for instance, an empty list : ( ), a list with one element : (FLOWER), a list with several elements : (1 pretty FLOWER), a list of lists : e.g. (7 (2 8.4) (5 1 0) 0.3). Therefore, musical data will also be expressed in OM algorithms and processes express via list structures.

A Functional Language

Common Lisp is a functional programming language, where programming is based upon the use of functions to transform and produce data. Functions receive arguments, or parameters and return data. Some functions, called generic functions, consist of a set of methods, or elementary specialized functions. Methods define behaviour rules that are specifically adapted to a type of argument a generic function is assigned. Musical processes are formalized and designed as graphic programs in OM, then interpreted as functional expressions. Any element of a program, including objects, can be considered a function, but a function can also be assigned as data to a higher-level function.

Programs can have several layers : one can use a program as a single function inside a higher-level program. This is known as functional abstraction, a major and very frequent process used in programming.

Objects and Classes

The various types of objects used in OM, such as musical objects – chords, notes and so on – are classified, categorized via classes, an important concept deriving from object-oriented programming. Classes therefore refer to categories of objects used as patterns that produce items, according to a series of parameters. An object defined from a class is an instance of this class, that is, a specific entity of a class.


I -

Intr

od

uc

tio

n

2. Additional Supports and Publications

OpenMusic website

http://recherche.ircam.fr/equipes/repmus/OpenMusic/

IRCAM Music Representation Research Group page : developer documentation, papers and publications.

Discussion Groups

OpenMusic Users Mailing List

Subscribe on http://listes.ircam.fr

Discussion Forum on IRCAM Forumnet

http://forumnet.ircam.fr/

Contacts

IRCAM forum support

Help and information for IRCAM forum members : [email protected]

Bug reports

[email protected]

The OM Composer's Book

A two volumes collection of essays by composers, dealing with the appropriation of OM in composition, as well as computer-aided composition from a general view.

Editors : C. Agon, G. Assayag, J. Bresson, Collection Musique/Sciences, Editions Delatour France – IRCAM Centre Pompidou.

http://recherche.ircam.fr/equipes/repmus/OMBook/


I -

Intr

od

uc

tio

n

http://recherche.ircam.fr/equipes/repmus/OpenMusic/



mailto:[email protected]



http://forumnet.ircam.fr/

http://listes.ircam.fr/

II - System Confguration and Installation

How to install OpenMusic on your computer, and what should be installed.


1. System Confguration

Mac OS

OM 6 is distributed for Macintosh Intel or PPC computers on Mac OS X systems.

Windows

OM 6 is currently not available on Windows. OM 5 versions are still available for Windows and MacOS systems.

2. Installing OM on MacOSX

Installation Procedure

Double click on the .dmg file to mount the OM installer.

In the installer, double click on the package and follow the directions.

1. Select a destination folder.2. The installer dialogue window offers a custom and a standard installation. Select an installation type.

• Choose [STANDARD INSTALLATINON] for a first installation.• Check the desired items for a custom installation.


II -

Sy

ste

m C

on

fig

ura

tio

n a

nd

In

sta

lla

tio

n

Installed Items

The following items should be installed on your computer.

OM Application

APPLICATIONS / OM-6.X.X APPLICATION DIRECTORY / OM 6.X.X.

Fonts

Musical fonts used by OM score editors.

LIBRARY / FONTS /

• omicron.ttf • omheads.ttf • omextras.ttf • omsign.ttf

Libraries

Libraries are used by OM for sound rendering and processing.

LIBRARY / FRAMEWORK :

• SDIF.framework• LibAudioStream.framework.

Midishare Utilities and Libraries

Midishare is a real time MIDI support used by OM for the rendering and processing of musical objects. They are installed by the MidiShare installer provided with the OM Installer.

APPLICATIONS / MIDISHARE : a set of utilities

SYSTEM / LIBRARY / FRAMEWORKS : dynamic libraries for MIDI.

• MidiShare.framework • Player.framework.

External Tools

• Microplayer.app / bm-microton : a microtonal musical player in Max/MSP.• SDIF-Edit : a 3D editor for SDIF sound description files visualizing.

Uninstallation

The elements mentioned above must be removed by the user :

• select the items and press [CMD] + [BACKSPACE] • drop them in the trash manually.


II -

Sy

ste

m C

on

fig

ura

tio

n a

nd

In

sta

lla

tio

n

III - Going Through an OM Session

This section provides technical information regarding the main procedures of a session, from starting to quitting OM.


1. Launching OM

Start Up

The OM application – OM X.X.X – is located in the OM folder.

• A standard installation LOCATES this folder in the

APPLICATIONS folder – .

• A custom installation allows to locate the OM folder in any desired directory.

OM can also be started from an alias anywhere in the machine hard drive or from the dock.

To start the application, double click on the OM icon.

Creating a Workspace

Every OM session begins with the opening of a workspace*, a working environment which is used at a session.

OM Start Up Dialogue Window

The start up dialogue window opens after starting OM. It offers four options :

INSTALL IRCAM WORKSPACES

The Ircam Workspaces are the OM and Lib workspaces. They contain tutorials, didactic material and other items you might need in the form of patches and maquettes.

You will have to choose a location to store the Ircam workspaces. One of these workspaces can then be open with the next option.

OPEN A WORKSPACE

This workspace must already be located in you hard drive. Any existing workspace can be open with this option. Pick a workspace in the dialogue window.

CREATE A NEW WORKSPACE

Choose a name and location in order to create a workspace, which will then open automatically.

OPEN A PREVIOUS WORKSPACE Refers to the workspace that was open during the last OM session. This option is not available for a first use.


III

- G

oin

g T

hro

ug

h a

n O

M S

es

sio

n

Upgrading OM and Reinstalling Ircam Workspaces

If you choose to install the Ircam Workspaces again when upgrading OM, you will have to either rename, move or delete the former Ircam workspaces, or locate the new Ircam workspaces in a different place. Otherwise, the installer will refuse to overwrite them.

Workspace(s) in the OM Environment, Workspaces Management :

Workspaces Location

Workspaces must be created in the user's home directory or one of its sub folders. Creating a workspace without writing permission can cause important crashes and data loss.

The OM dialogue windows allow to choose, create or install a workspace. For a first use, you can choose to install the Ircam workspaces. If you create a new workspace, it will be empty.


III

- G

oin

g T

hro

ug

h a

n O

M S

es

sio

n

2. Workspace(s) Management

A workspace has two functions :

• It is a virtual desktop in which programs and other associated files are created and organized. • It is also a "real" folder, where most programming material is created and stored.

The workspace therefore both refers to a window in the OM environment, and to a folder located on the user's hard drive. The number of workspaces, their name and location is at the user's discretion : several workspaces can coexist on the same machine, but only one workspace can be open at a session. This chapter provides information about the content of the workspace window and folder, and directions to manage one or several workspaces.

Organizing Workspaces• Several workspaces can be kept on the same machine. Each of them represent a specific project and can

possibly have a personalized environment : in the event of the crash or unexpected disappearing of a

workspace, a user will "only" loose one project, and not a whole composer's life.

• Several projects can be kept in a single workspace, in several folders and sub folders, which can be convenient if they share a lot of common material. It is recommended in this case to gather all the components of a project in a dedicated sub folder.


III

- G

oin

g T

hro

ug

h a

n O

M S

es

sio

n

Workspace Window and Listener

Opening a Workspace

If you open or create a workspace at the beginning of an OM session, you will be asked to select a directory in your hard disk. It is advised to choose the USER home directory , or one of its sub directories.

The Right Folder

Mind selecting the WORKSPACE folder itself and not one of its sub directories when opening a workspace. If you select a sub directory, OM will generate a new workspace out of the sob directory, which will disorganize your folders.

The Listener

Once OM has been launched, the window of the selected workspace appears automatically with another window : the OM Listener .

The Listener is a Lisp communication interface. With the workspace, it is a major element of the OM environment, so that both windows open automatically at the start of a session.

About the Listener

Workspace Folder

Contents

The WORKSPACE folder can contain a number of sub folders. These sub folders enclose the persistant documents* that are available for an OM session.

The elements displayed in the workspace window are actually stored in the ELEMENTS sub directory of the WORKSPACE folder.


III

- G

oin

g T

hro

ug

h a

n O

M S

es

sio

n

The Workspace Sub Folders

• ELEMENTS : programs, that is patches* (.omp files) and maquette* (.omm files), folders to store programs.• IN AND OUT FILES : additional files, such as audio, MIDI, SDIF and text files written or to be read by OM. • GLOBALS : global variables*, that is, specific instances* that have been created in OM in order to be used

subsequently in projects. • RESOURCES : material for the OM graphic interface, such as images and icons. • USER : programming tools created in OM by the user : classes* (.omc), functions* or methods* (both .ome). • ADDITIONAL FILES : preferences.lisp and wsparams.lisp contain the workspace's preferences and parameters.

Full Information about the Workspace

Modifying the Workspace Folder during an OM Session

Modifying these folders can be extremely tricky and should never be done while OM is running.

Importing and Exporting Files at a Session


III

- G

oin

g T

hro

ug

h a

n O

M S

es

sio

n

The Elements folder and the corresponding workspace window.

3. Quitting OM and Saving

Quitting OM

To quit OM :

• choose OM X.X.X / QUIT

• press [CMD] + [Q].

Two dialogue windows will open successively

1. to ask you to confirm quitting : choose [YES],

2. to save the current workspace : choose [YES] or [NO] .

Saving a Workspace and its Content

Saving Files, Folders and Workspaces

To save the content of an item :

• select FILE / SAVE • press [CMD] + [S].

Saving a workspace or a folder triggers the saving of its settings and unsaved content. The saving dialogue window asks if unsaved items have to be saved.

The [APPLY TO ALL] option allows to apply your choice to the whole content of the folder or workspace. All modified items are saved in the corresponding workspace folders.

Full Information About the Workspace

OM always asks if the current workspace must be saved when quitting.


III

- G

oin

g T

hro

ug

h a

n O

M S

es

sio

n

IV - The OM Environment

This sections documents the OpenMusic environment general features. All required directions and information about documents and programs management in OM, setting of general preferences, etc., can be found here.


1. Windows of the OM Environment

The OM interface is declined through a set of windows and editors, which can be accessed through the WINDOWS menu. Among them are three major items :

• the Workspace window• the Lisp Listener window• the Library window.

Workspace Window

The workspace is designed to host all files and folders related with the user's projects. The Ircam workspaces may also contain example and tutorial files provided at the installation.

To open or show the WORKSPACE window :

• press [CMD] + [SHIFT] + [W] • select the WINDOWS / WORKSPACE menu.

The Workspace and the Lisp Listener appear at the start of a session.

Full information about the Workspace :

Reminder

The window of a new workspace always comes empty first. Material must be added there by the user. The Ircam workspaces are installed with their own set of files and folders.

Lisp Listener

The Listener is a Lisp communication interface : results of computations, warnings or error messages are displayed there. It also allows to send commands to OM, in other words, to evaluate Lisp expressions.

User inputs are typed and interpreted in the upper part of the LISTENER window. Output messages are print in the lower part of the window.

To open or show the LISTENER window :

• press [CMD] [SHIFT] + [L] • select the WINDOWS / LISTENER menu.

More Information about the Lisp Listener :


IV -

Th

e O

M E

nv

iro

nm

en

t

Library Window

The LIBRARY window gives access to a set of preexistent programming items that are ready to use, as well as imported or user-defined elements. Items are located and organized within the Library in various packages*.

To open the LIBRARY window :

• go to WINDOWS / LIBRARY

• press [CMD] + [SHIFT] + [P].

Full information about the Library :

Other Windows

Programming items are represented in various window types. The WINDOWS menu shows the name of any open window. Selecting a name brings the corresponding window to the foreground.

Preview : the Lisp Editor

The Lisp Editor allows to edit and evaluate whole programs, which makes it a useful Lisp programming interface.

To open the Lisp Editor, go to WINDOWS / LISP EDITOR.

More Information about the Lisp Editor : WorkspaceWorkspaceReminder


IV -

Th

e O

M E

nv

iro

nm

en

t

2. Workspace

The workspace is both a "real" folder on the user's hard drive and an icon-oriented browser in OM, a window that can be compared to a desktop. This window opens automatically when launching OM, but it doesn't have to remain open during programming.

To open or show the WORKSPACE window :

• select WINDOW / WORKSPACE

• press [CMD] + [SHIFT] + [W] .

2.1. The Workspace Window

Adding and Deleting Components in the Workspace Window

Visual programming in OM consists of manipulating graphic symbols : starting by browsing the workspace, selecting and dragging objects from one place to the other, open them, or interconnect them...

Adding Components

Two types of programs can be used in OM : patches* , and maquettes* . They can be added in the workspace as well as in storage folders of the workspace.

To add an item in the workspace or in an open folder :

• FILE / NEW PATCH - MAQUETTE - FOLDER • [CTRL] / right click / NEW PATCH - MAQUETTE - FOLDER

• [CMD] +[1] for patch / [2] for maquette/ [N] for folder.Get Into Visual Programming

Reminder

The WORKSPACE window displays the items stored in the ELEMENTS sub folder of the WORKSPACE folder.


IV -

Th

e O

M E

nv

iro

nm

en

t

Clearing or Deleting Items

To delete an item, select it and choose :

• clear : EDIT / CLEAR • cut : EDIT / CUT or [CMD] + [X] .

Clearing an item deletes it forever. It may be safer to choose CUT, which allows to paste the item afterward.

Basic Procedures

Most operations on files and folders can be executed with the standard contextual menus and shortcuts.

Opening Folders and Programs

• Double click on an item, or [CTRL] / right click and choose OPEN.• In List mode, you can also click on the adjacent triangle of a folder – – to open it.

Moving Items from a Folder to Another

To move an items to another folder :

• drag and drop the item.

• cut and paste the item in an open folder :

• choose EDIT / CUT / PASTE,• press [CMD] + [X] / [CMD] + [V].

Copying Components

• Select EDIT / COPY / PASTE or press [CMD] + [C] / [CMD] + [V] .• On Mac : [ALT] drag and drop the item. On Windows : [CMD] drag and drop the item.

Duplicating Components

To duplicate an item :

• select EDIT / DUPLICATE / PASTE

• press [CMD] + [D].

Renaming Files and Folders

Double click on the name to edit it .

Reminder : Saving Files, Folders and Workspaces

To save a content, open an item and

• select FILE/ SAVE • press [CMD] + [S].

Saving a workspace or a folder triggers the saving of its settings and unsaved content. A saving dialogue window opens. The APPLY TO ALL option allows to apply this choice to the whole content of the folder or workspace at once. All modified items are saved in the corresponding workspace folders.

No "Save as" Option

The "Save as" option is not available for any of the components of a workspace or a workspace itself.


IV -

Th

e O

M E

nv

iro

nm

en

t

2.2. Getting Information

The INFO window provides information about the name, type, date of creation and modification of a selected item within the workspace. To open the INFO window of a selected item :

• [CTRL] / right click on an item and select GET INFO in the contextual menu• choose FILE / GET INFO

press [CMD] + [I] .

To change the icon of an item, click on it in the upper left corner.To add a comment, fenter a text in the DOCUMENTATION / COMMENTS frame.

Changing the Icon of an Item

Lisp Programming Preview : Lisp Code Option

The INFO window also shows a LISP CODE option.


IV -

Th

e O

M E

nv

iro

nm

en

t

This option converts the patch into a plain textual Lisp function. Any previous content of the patch will then be deleted, be it saved or not.

The Lisp Editor opens : the user can enter a Lisp function, instead of designing a graphic patch.

More Information about Lisp Programming :

2.3. Presentation Options

List or Icon modes

In the workspace, items can be displayed in Icon or List mode. The Icon mode is the default mode of OM.

Presentation modes are accessed via the main menu, or the contextual menu with a [CTRL] / right click.

• To choose a presentation mode, select PRESENTATION / ICONS - LIST .• To align components automatically in Icon mode, select

PRESENTATION / ALIGN .

Changing the Icon of an Item

Icons of patches and maquettes can be modified from the workspace.

The Info Window

1. Open the INFO window :

• [CTRL] / right click on the item and choose GET INFO.• Press [CMD] + [I] .

2. Double click on the upper left corner icon of the INFO window to open the Picture Chooser.

The Picture Chooser

Select an icon or an image in the RESOURCES frame, or in the USER RESOURCES frame.


IV -

Th

e O

M E

nv

iro

nm

en

t

1. Click on [+] . 2. Browse the content of you hard drive, select a

resource and choose [OK] .

The icon is stored in the WORKSPACE / RESOURCES / ICON sub folder.

Choose [OK] to validate your choice, or [CANCEL].

For Detailed Information about Resources Management :

The new icon is displayed in the workspace and in the INFO window.

Notes

Icons of factory boxes and functions cannot be modified.

If a resource can't be used, identified or found, probably for format, location or identity reasons, the default icon or the image is attributed to the item.

User Resources : Adding and Deleting a Resource

Adding a Resource

You can add an icon or an image to the USER RESOURCES.

1. Click on [+] .2. A dialogue window opens.

Select a resource :

1. Browse your hard drive to select a file.

2. Choose [OPEN] or [CANCEL] in the dialogue window.


IV -

Th

e O

M E

nv

iro

nm

en

t

About the OM Resources and User Resources

Deleting a Resource

To delete a picture or icon from the User Resources, choose [-] .

2.4. Import / Export

This section shows how to bring material to or from a workspace during a session via the "Import" and "Export" commands. These commands allow to share material between workspaces, as a sole workspace can be open per session. Implicit copies of files and folders are generated and can be modified independently from the master item. Genuine items aren't affected by modifications of an imported file.

Import

"Import" command

The user can import a file or a folder from any location in the computer to the open window of the workspace, or to that of an open sub folder .

To import a file or folder :

• drag and drop the item in the workspace• [CTRL] / right click in the workspace and choose IMPORT FILE - FOLDER.

Additional Import Procedures• Drag and drop the item on the OM icon of the dock.• Double click on the item.

In the IMPORT dialogue window, choose [YES] to import the item, which will be copied in the current workspace by default.


IV -

Th

e O

M E

nv

iro

nm

en

t

Existing Item / Name

If an item of the targeted directory has the same name as the item you want to import, you will be offered to rename it.

Earlier Files Compatibility

When loading an old workspace, or importing old patches or maquettes, OM may check their contents and report possible errors. Unreadable files will not be imported to the workspace. Earlier readable files show a red background until they are updated by OM.6 at the opening. As these files aren't legible by former versions, they should be either copied or imported.

Export

Export Procedure

The only way to export or copy OM files and folders directly from the workspace to the finder is to use the contextual menu. They cannot be dragged and dropped. Select the workspace, a file or folder :

1. [CTRL] / right click on an item and choose EXPORT in the contextual menu.2. Choose a name, an extension and select a destination folder in the dialogue window.

All files belonging to a workspace can be exported : .omp files – patches, .omm files – maquettes.


IV -

Th

e O

M E

nv

iro

nm

en

t

OM systematically asks if the user wants to import the item concerned.

Exporting One Item at a Time

Only one folder or file can be exported at a time. OM won't display any message If you select several items, but will export the item that was clicked on to open the contextual menu.

Workspace Folder Modifcations

Modifications of the Workspace folder must be done via the OM application. If the ELEMENTS sub folder is modified directly while OM is running, the application cannot notice ongoing modifications, and OM can crash. The IMPORT and EXPORT commands must be privileged. Library


IV -

Th

e O

M E

nv

iro

nm

en

t

Exporting a folder from the OMWorkspace to another workspace.The relevant extension is always offered by the lower pop up menu of the dialogue window. It is added to the file name automatically.

3. Library

The LIBRARY window encloses the OM program-ming tools, which are organized in packages and sub packages. They can be used in various OM documents. These tools are classes*, functions* and methods*, among which a number can be created by the user.

To open the LIBRARY window, use the main menu or shortcut :

• select WINDOWS / LIBRARY • press [SHIFT] + [CMD] + [P].

3.1. Packages

Package

A package represents a category of programming tools that encloses related functions and classes. It can be organized in sub packages.

Packages of the Library Window

Each package is represented by a small suitcase.

The OM packages are the most numerous. They contain classes* and functions*

predefined in OM. OM Packages are defined thematically.

For instance, the Score package contains classes that are literally dedicated to the score domain, such as chords, notes, polyphonies, and functions that can perform operations upon these classes.

These packages and their content are "protected" and cannot be modified.

The USER package can receive user-defined classes and functions, which can be dispatched in dedicated sub packages. These classes and functions can be modified.

The USER LIBRARIES package encloses a set of additional libraries that can be added or loaded dynamically.

The GLOBALS package is a special folder that contains user-defined global variables*. It cannot contain sub packages.

If a package is supposed to contain sub packages, it features an adjacent triangle that allows to open a package on List mode. When this triangle is clicked, the package unfolds and displays its inner sub packages – see below.

About User LibrariesAbout Global Variables


IV -

Th

e O

M E

nv

iro

nm

en

t

Packages Content

A package gives access to both functions and classes of a common "theme", or category of tools. Packages contents can be displayed in List mode, Package mode or Class Tree mode.

Opening Packages in List Mode

The List mode is the sole mode that provides a global view of a package whole organization in sub packages.

Classes and functions contained in the sub packages cannot be accessed, though.

Opening Packages in Package Mode

The Package mode allows to access the set of tools contained in a package as a whole : sub packages cannot be visualized.

• [CTRL] / right click on the suitcase and choose OPEN PACKAGE.

• Double click on the lower part of the suitcase.

The window extends to display two side panels, respectively containing the package's functions and classes. Their content is refreshed at the selection of another package.

Opening Packages in Class Tree Mode

A "class tree" shows the inheritance between the classes of a common package.

• [CTRL] / right click on the suitcase and choose OPEN CLASS TREE

• click on the upper part of the suitcase.

The class tree is displayed in a new window. Class trees of the USER sub packages can be created and modified graphically.

More Information about Class Hierarchy and Inheritance


IV -

Th

e O

M E

nv

iro

nm

en

t

Using Classes and Functions from the Libary

Dropping Items in Patches

Tools can be dropped in patches from the LIBRARY window.

Classes and Functions Editors

The tools of a package can sometimes be edited. Their content can be displayed in a class or a generic function editor, which opens with a double click on the class or function's icon.

More Information about the Class Editor and the Generic Function Editor

Getting Information

To obtain information about a select package, class or function of the library, use the INFO window :

• [CTRL] / right click on an item and choose GET INFO • select FILE / GET INFO

• press [CMD] + [I] .

Information related to the items of the USER package can be edited.

Class Trees, User Defined Material : Object Oriented Programming


IV -

Th

e O

M E

nv

iro

nm

en

t

3.2. User Libraries

User Libraries contain specific functionalities, that is classes and functions that can be loaded dynamically in OM. These libraries are not enclosed in the OM initial application, but they consist of Lisp files that are stored in the USER LIBRARIES folder of OM : dynamic loading allows to load a library on demand.

Use

Dynamic Loading

To load a user library :

• double click on the lower part of a package• [CTRL] / right click on a package and choose LOAD LIBRARY.

Loaded libraries show a green label : , unloaded libraries, a red label : .

Dead Libraries

If a patch contains functions or classes pertaining to a user library, the user will be asked if the library must be loaded or not when opening the patch.

Choose [YES]. Otherwise, all components attached to this patch will appear as "dead boxes".

Displaying the Content of a User Library

The content of a user library is displayed in Package, List or Class tree mode, like that of other libraries.

About Displaying Modes

Adding Components from a User Library to a Patch

Once a library is loaded, classes and functions can be dropped to a patch editor

• from the function and classes panes of the LIBRARY window• from the USER LIBRARIES menu item.

Adding Items from the Library Window


IV -

Th

e O

M E

nv

iro

nm

en

t

External and Remote User Libraries

External User Libraries

The user can also store her or his own libraries in a personal directory. This directory should be specified in the LIBRARY preferences of OM.

1. Open the PREFERENCES pane : OM 6.X.X.X / PREFERENCES.

2. To select the LIBRARY preferences, click on the USER LIBRARIES tag icon .

3. Click on [...] to select a User External Directory, choose [OPEN].

4. Select or create a folder, choose [APPLY] and [OK] .

The external libraries will be automatically displayed in the USER LIBRARY package .

Remote Libraries

To import a library from another location to the USER LIBRARY package :

1. select the LIBRARY window

2. choose FILE / NEW REMOTE USER LIBRARY .

3. select the library folder you folder you want to import and choose [OPEN].

The remote library appears in the USER LIBRARY package just like any other user library.

Autoload

User libraries, including remote and external libraries, can be loaded automatically at startup.

1. Open the USER LIBRARIES preferences pane,

2. select the libraries you want to load at start up in the AUTO LOAD frame,

3. choose [APPLY] and [OK].

Changing the Location of an External or Remote User Library

If a directroy location is modified after it was added in the LIBRARY window, OM can't find nor load the library.


IV -

Th

e O

M E

nv

iro

nm

en

t

4. Resources

Resources are images or icons dedicated to the visual interface of OM.

Generalities

Format, Size and Name

Several formats can be handled by the OM interface : TIF files (.tif, .tiff), JPEG files (.jpg, .jpeg), GIF files (.gif), BMP files (.bmp) and PNG files (.png).

Icons shouldn't exceed 64 pixels and be given a numeric reference such as "127.tiff". Images can have any name and dimensions. They can have background transparency alpha layer.

Use

The user may have to choose images or icons for various reasons : inserting an image in a patch, giving an identity to a temporal object* in a maquette, choosing an icon for a patch, a class or a function...

Resources Directories

OM Resources

The pictures and icons offered by the OM RESOURCES belong to sub folders of the OM application folder : To access the ressources, choose a corresponding foler :

• APPLICATIONS / OM 6.X.X / RESOURCES / ICON • APPLICATIONS / OM 6.X.X / RESOURCES / PICT .


IV -

Th

e O

M E

nv

iro

nm

en

t

User Resources

The pictures and icons added to the USER RESOURCES by the user belong to the WORKSPACE / RESOURCES folder. They are located in the following directories :

• USER / WORKSPACE / RESOURCES / ICON • USER / WORKSPACE / RESOURCES / PICT .

Uses

Pictures or icons can be assigned as background pictures in patches and maquettes from an editor. They can also be assigned to patches and maquettes icons from a workspace. The icons of factory boxes and function boxes cannot be modified.

Changing the Icon of an ItemBackground Pictures in Patches and Maquettes


IV -

Th

e O

M E

nv

iro

nm

en

t

5. Preferences

The OM interface and programming components are ruled by a series of default parameters that can be modified via the PREFERENCES pane during an OM session. These parameters are associated to and saved with the workspace that was open at this session.

Preferences Pane

Access

To open the PREFERENCES pane, select OM 6.X.X / PREFERENCE. A series of tabs giving access to a set of preferences is shown on the left.

Note

The GENERAL tab shows a HANDLE ERROR MESSAGES option. This option allows, to limit the consequences of possible programming errors and prevent OM from crashing. If an error occurs, a message pops up.

For More Info about Error Messages, See :

Preferences Tabs

General preferences dedicated to the appearance of the interface.

Default storage folders.

User libraries to be loaded automatically when starting a session, user libraries storage folder.

Midi-osc preferences.

Score editors preferences, such as staffs number, microtonal notation scale...

Current programming operations default parameters, such as tempo, measure...

Audio settings.

External sound processing applications communication.

More information about each tab is provided within the corresponding sections.


IV -

Th

e O

M E

nv

iro

nm

en

t

Commands

[RESTORE] : resets the default preferences.

[APPLY] : applies the preference defined in the pane.

[CANCEL]: closes the pane without applying the preferences.

[OK] : applies and saves the preferences.

Modifying the Workspace and Patch Internal Appearance

Workspace Background Colour

To modify the workspace background colour :

1. Click on the USER NAME prompt to edit it to enter a new user name.

2. Choose [CHANGE COLOR] then click on the coloured patch.

3. Select a color via one of the palettes, choose [DONE] and [OK] .

Boxes Appearance

Boxes Appearance

To change the comments and boxes appearance :

1. Choose [CHANGE FONT] and possibly [CHANGE COLOR] to modify the comments font.

2. Click on [NAME FONT] and use the SIZE pop up menu to modify the font and size of boxes.

3. Choose [APPLY] and/or [OK] to save the preferences.


IV -

Th

e O

M E

nv

iro

nm

en

t

V - Visual Programming

This sections describes the theoretical and practical aspects of patch programming, the various types of objects and tools available in OM and their manipulation.


1. Basic Visual Programming

This section describes how to add, modify and connect boxes within patches, access required information through the OM graphic interface. It also aims to answer practical problems that will necessarily be raised from the first steps in OM. Last, some Lisp notions are emphasized in the description of OM components and syntax rules, to introduce the underlying logic of OpenMusic.

1.1. Introduction to Patch Programming

Almost all programming in OpenMusic is done in patches, which are visual representations of programs.

Location

Patches are created in the WORKSPACE* window.

More Information about Patches and Other Documents :

Most visual programming is done in the patch editor, which opens by a double click on the patch icon.

Content

Patches contain boxes, which represent :

• functions that are called or used by the program, • objects – such as notes, sound files and so on –, that are created and processed in the program.

Connections link these components together to define the functional structure of the program.

Boxes and Programs

The various box types that might interact in a program generally have different properties. Each box type is described in the Boxes and Patch Components section. You will also learn how to create patches within other patches. This very convenient procedure is called functional abstraction. The user will resort to it as soon as he or she gets familiar with OM.


V -

Vis

ua

l P

rog

ram

min

g

A Simple Patch Example : Performing a Transposition

This patch contains three items :

• A : the om+ function, which executes additions• B : a note object• C : a data box.

The note is a G♯4, which means its pitch is equal to 6800 midicents*. This pitch can be accessed via the second inlet and outlet of the box.

• The first input of om+ is connected to the second outlet of the note : the pitch of the note is the first term of the addition.

• The data box represents a value : 400. It is connected to the second inlet of om+. It is the second term of the addition.

• When om+ is evaluated, the Listener displays the value of the resulting pitch in midicents.


V -

Vis

ua

l P

rog

ram

min

g

1.2. Adding Boxes Into a Patch

There are four ways to add a box in a patch editor :

• via the main menu• via the contextual menu• typing the box's name directly in the patch editor• via the LIBRARY window.

Menus

This procedure is convenient if you don't know the exact name of the class or function you need.

Main menu

Note that functions* and classes* are accessible via two distinct menus. The CLASSES and FUNCTIONS menus give access to the classes and functions of common packages : this is why they display the same names.

Select a class or a function and click somewhere with the cursor in the patch editor to add the box there.

Patch Editor Contextual Menu

To add a box via the contextual menu :

1. [CTRL] / right click in the patch editor

2. select FUNCTIONS or CLASSES.3. choose a box in a menu item.

The box will appear in the editor automatically.


V -

Vis

ua

l P

rog

ram

min

g

Library Window

The packages* in the LIBRARY window contain the available OM classes and functions organized in thematic sub packages.

1. Open the LIBRARY window :

• select WINDOWS / LIBRARY

• press [SHIFT] + [CMD] + [P].2. Double click on the lower part of a package to open the classes and functions panes.3. Drag and drop the function or class icon in the patch editor.

Full Information about Packages and the Library Window

Adding a Box Directly in the Patch Editor

The name of a class or function can always be keyed in a patch editor directly.

Typing a Class or Function Name

1. [CMD] / right click in the editor : an "undefined" box appears. 2. Type the relevant name and validate or click somewhere in the editor.

Any OM or Lisp function can be created this way. This procedure may be especially useful since some classes and functions are not accessible via menus or packages. It implies being familiar with OM functions and classes names.

Tip

Default values can be directly assigned to a function when entering its name. For instance, "om+ 5 7" assigns 5 and 7 as default values to om+.

Specifying a Package Name

In Lisp, a package is also a means to gather symbols, such as function names, class names, and so on, within a same specific name space. Some functions or classes can be declared in other packages if they were not designed for OM exclusive use, or if they come from specific libraries. In this case, adding a box directly in the patch editor requires typing the package name or nickname before its name.

1. A package can be designated by a name or a nickname. For instance, the main OM package name is "openmusic", and has for nickname "om". This syntactically corresponds to :

"name-or-nickname-of-the-package::name-of-the-function".2. To identify the package hosting a given function or class, type this expression in the Listener : (package-

name (symbol-package 'class-or-function-name)). The corresponding package will be displayed.


V -

Vis

ua

l P

rog

ram

min

g

1.3. Boxes Morphology

This section deals with and factory boxes*. A factory box represents a class of objects in a program, such as notes, sounds, rhythms. A function box refers to a function that is designed to perform an operation upon objects.

Main Layout

Kernel, Inlet(s), Outlet(s)

All boxes have :

• a kernel or "body" represented by an icon, • at least one inlet – a few rare functions have no inlet – which

takes data,• at least one outlet, which returns the data computed by the box,

Inlets and outlets are used for connecting boxes. They are represented by small blue balls and located on the upper and lower parts of the box. Each of them is assigned a specific parameter that characterizes the function* or the class* the box refers to.

Several functions or factory boxes belonging to a same category of operators often share the same icon.

Factory boxes are often characterized by a blue-green background layer.

Function Types : Lisp Functions and OM Functions

Boxes Names

The name of factory boxes is not displayed by default. A number of simple functions – such as om+, om-, om/ ... show no name.

Specific Graphic Features of Factory Boxes : Displaying Names

Additional Characteristics

Evaluation Mode Label

A small label located on the upper left corner of the box can show the possible evaluation* mode of a box. Evaluation modes are used for controlling the transmission of resulting data in a program, or for performing specific tasks.

Evaluation Modes of a Box :


V -

Vis

ua

l P

rog

ram

min

g

function boxes

Resizing Area

All boxes have an invisible square resizing area in their bottom-right corner.

Manipulating Objects in a Patch Editor

Changing Boxes Appearance

The default size and font of boxes can be modified via the GENERAL PREFERENCES tab via the OM 6.X.X / PREFERENCES menu.

• To change the default size, select a resizing rate in the BOXES SIZE pop up menu.• To change the name font, click on [NAME FONT], choose a font in the pop up window.

Press [APPLY] and/or [OK] to validate the modifications.


V -

Vis

ua

l P

rog

ram

min

g

1.4. Elementary Manipulations

This section provides information about specific commands regarding the manipulation of items within patches. Specific details are given for each box type in Boxes and Patch Components.

Selection and Resizing

Selection

Boxes are selected using standard mouse selection. They show a bold border.

• To enable multiple selection, click on boxes keeping pressing [SHIFT] or click and drag the mouse over several boxes.

• To select all the boxes of a window, choose EDIT / SELECT ALL, or press [CMD] + [A].

Most patch editor commands apply to every selected boxes in the current window.

Resizing

• To resize a box, hover the mouse over the lower right corner of the box, then drag it with the cursor.

• To restore the default size of the selected box(es), press [I] .

Move / Copy / Align

Move

To move an item around in a patch editor :

• drag and drop it with the mouse• select it and use the four [→] keys. Add [SHIFT] to move items faster.

Drag and Drop / Copy

Boxes can also be moved or copied from a patch editor to another.

• Drag and drop the item to move it. Add the [ALT] key to copy it. • Use the usual commands and shortcuts – EDIT / COPY, PASTE, DUPLICATE ...


V -

Vis

ua

l P

rog

ram

min

g

Copying a chord-seq box to another patch editor.

Align

To align all selected boxes automatically, press [SHIFT] + [A] .

Delete

To delete selected boxes :

• press [BACKSPACE],• select EDIT / CLEAR - CUT or press [CMD] + [X] .

Undo

The Undo command can be used for restoring deleted boxes – not their connections. It can only apply to the last action that was executed.

To cancel an action :

• select EDIT / UNDO

• press [CMD] + [Z] .

Patch Editor Commands

To display an overview of the main patch editor commands :

• choose HELP / EDITOR COMMAND KEY

• type [H] in an open patch editor.


V -

Vis

ua

l P

rog

ram

min

g

1.5. Setting Box Inputs

Box inputs correspond to computation parameters. These parameters can correspond to the arguments of a function, or to the attributes of an object, depending on the type of the box.

Information and Default Values

Getting Information : Tooltips

To display information about an inlet, keep [CMD] pressed while hovering the mouse over the inlet. A tooltip appears and displays

• a parameter name,• a short documentation about this parameter.

Getting Default Values

All box inputs have default values that are used by the box if no values have been specified by the user, or if the box is not connected to anything.

To visualize the default value of an inlet, hover the mouse over it. If it is connected to any kind of component – such as a value or a box – this default value will be ignored.

Voir aussi...

Entering Values

To enter a value in an inlet :

1. click on it2. type a value in the text field3. validate.

The value remains hidden unless you hover the mouse over the inlet.

[SHIFT] click on the inlet to display the input value in a connected data box that will remain visible.

Saving Values

Always validate after entering a value in an inlet :

• click in the window • press [ENTER].

This is very important since default values can remain hidden.


V -

Vis

ua

l P

rog

ram

min

g

1.6. Connections

A connection is a link between the outlet of a box and the inlet of another box. It means that the value of the downstream box inlet will be the result of the upstream box computation. Connections define the functional composition, that is the syntax of a visual program.

Creating and modifying connections

Creating a connection

To create a connection, click on a box output and drag the mouse cursor to the input of another box.

Modifying a connection

Connections can be selected and modified as well :

• to change the shape of a connection : click and drag its articulations• to change the colour of a connection : select it and press [C] .

Deleting a connection

To delete a connection

• select it and press [BACKSPACE]• [CMD] click on the cotresponding input of the connection.

Automatic rule verifcation

OM makes automatic decisions when boxes are connected, to respect synctactic rules. This includes :

• preventing cycles : a box can not be connected to another one if this connection creates a cycle • deleting existing connections when a new connection is made to an input. An input is necessarily assigned a

single value and therefore cannot be connected to more than one box.

Preventing Cycles

One of the inputs of om* is connected to om+. Om* needs to know the result returned by om+ to perform its computation.. Hence, OM "refuses" to connect the result of the multiplication to the inlet of the addition.


V -

Vis

ua

l P

rog

ram

min

g

1.7. Evaluation

Evaluating a box means calling its inner function and parameters. If this box is connected to others, all the upstream boxes will be evaluated one by one. Thus, evaluating one box can trigger a more or less lengthy evaluation chain. This chain refers to the calculus of a function tree, or, in other words, of the visual program.

Evaluating boxes and outlets

• To evaluate a box, select it and press [V]. The result of the leftmost output is displayed in the Listener.

• To evaluate a specific output of a box, [CMD] click on the outlet. The corresponding value is displayed in the Listener.

In any case, the whole box, that is all of its outputs, are computed during the evaluation.

Computation Flow : Left-Right, Bottom-Up

In a program, a box evaluates all boxes connected to its inputs, and evaluates its inputs from left to right .

Therefore, the evaluation of a patch always goes bottom-top and left right, graphically speaking.

Default Values

Box inlets have a default value. This is why a box can generally be evaluated even if part or the totality of its inlets are not connected to another box. Default values can be visualized by hovering the mouse over an inlet.

Box Inputs

Locking / Unlocking a Box

To lock a box, select it and press [B]. A small icon appears on the upper left corner of the box icon.

• The last computed value will kept as a definitive value for this box. • The input values of this box, as well as the possible elements connected to

these inputs will be ignored at a subsequent evaluation.

To unlock the box, press [B] again.

Evaluation Modes Preview

Several other evaluation modes can be used for controlling the transmission of resulting data in a program, or to perform specific tasks.

Evaluation Modes :


V -

Vis

ua

l P

rog

ram

min

g

1.8. Documentation and Info

Info Window and Reference

Reminder

To open the INFO window :

• press [CMD] + [I] • [CTRL] / right click on an item and select GET INFO in the contextual menu.

The INFO window provides various information, depending on the type of the selected item, and a possible brief documentation.

Documentation Window

The reference documentation gives access to full information about a function or class.

To access the reference of an item select the box and

• press [D] • choose HELP / DOCUMENTATION in the main menu.

The documentation, when available, will pop up in a new window.


V -

Vis

ua

l P

rog

ram

min

g

In some cases, recent upgrades allow to open an online reference documentation instead of the internal documentation.

This documentation is also accessed by pressing [D].

Additional Information about Box InputsGetting General Information about the Inputs of a Box

Getting Information about Relevant Data Types for a Function Box

Tutorial Patches

Tutorials are commented example patches. They are OM internal patches which cannot be modified and saved. Nevertheless, their content can be copied in another patch.

To open the related tutorial patch of an item, select it and

• choose HELP / TUTORIAL PATCH in the menu• PRESS [T] .

The tutorial will open as a new patch.


V -

Vis

ua

l P

rog

ram

min

g

1.9. Saving / Reloading a Patch

Saving

Precautions

It is advised to save a work regularly. Indeed, a bug or an ill-conceived program can cause a crash or stuck OM in endless iterations, in which case you will have to force the application to quit.

To save a patch

• choose FILE / SAVE

• press [CMD] + [S] .

Reloading a Patch

Last Saved...

To reload the last saved version of a patch :

• select FILE / LAST SAVED,• [CTRL] / right click in the editor, choose LAST SAVED.

Preserving a Patch

If a patch is used in another patch, OM doesn't create a copy. Its original reference in the workspace will be affected by subsequent modifications as well. To preserve the original item, one can resort to internal patches or duplicate it to preserve the original reference from possible modifications.

How to Duplicate / Rename Patches

> cf "The Workspace Window", page 31.Internal patches

1.10. Missing References : Dead Boxes

Iems used in a patch may sometimes be missing. Dead boxes refer to saved items OM can't find anymore :

• if an item belongs to a library that was loaded at a previous session, and that this library isn't reloaded,• if an OM function doesn't exist in a new OM version, • If a sub patch that was used in another patch is missing in a workspace.

Dead boxes have been designed to keep as much information as possible about their original reference, so that they can possibly be loaded again correctly.

Dead Boxes

If the user tries to open a dead box or to get information or documentation, the box doc will say "I have lost my reference, I am dead"...

... or a message of the same kind.


V -

Vis

ua

l P

rog

ram

min

g

Note

When a dead box "knows" which reference – class or function name for instance – it was attached to, it can possibly be restored. Its reference must be loaded again or re-created before the patch is reloaded. To reload a patch containing dead boxes, use the "Last Saved" command.

Saving Procedures

> cf "Saving / Reloading a Patch", page 61.

Finding Lost References

See also : Workspace / Adding Components in a Workspace at a Session : Import and Export Functions

See also : Workspace / Adding Components in a Workspace at a Session : Import and Export Functions


V -

Vis

ua

l P

rog

ram

min

g

If a patch reference is missing in the workspace, OM will point it out and offer to find it. If the item can't be found, the user will be offered to look for it by himself.

Looking for the reference of a dead box.

2. Boxes and Patch Components

Boxes are the main elements at stake in the composition of a patch. Each box type refers to a given functional component : a function, an object, a value, a program or sub program, and so on. Among these, function*

boxes, and object or factory boxes* appear as major tools. They also are the most numerous ones. This section lists and describes each of these OM box types, their behaviour and use.

2.1. Data Boxes

Data boxes are the simplest of all OM boxes. A data box represents a constant value. This value belongs to one of the primitive Lisp types, which are available in the OM KERNEL / LISP package.

Use

A data box is designed to pass data to other boxes in a patch. It is made of a text field that expresses a value or a text, and an output that allows to connect this content to other boxes.

Primitive Lisp Types

There are several primitive Lisp types :

• number : any type of numeric data • list : a list of any type of item between parenthesis

• integer : an integer number • string : a text between double quotes – inverted commas

• float : decimal number • t : the Lisp expression for "true"

• rational : a/b • nil : the Lisp expression for "false" or "nothing"


V -

Vis

ua

l P

rog

ram

min

g

Adding a Data Box

Typing Directly In the Patch Editor

[CMD] click in the patch editor and type a content – i.e. 4, (2 3 4), "hello", etc. – directly.

Menus Or Library Window

• Go to CLASSES / KERNEL / LISP and choose a menu item.

• [CTRL] / right click in the patch editor and choose a menu item in the contextual menu.

• Pick the box in the relevant package from the LIBRARY window and drop it in the editor.

Note

A data box accepts any primitive type, no matter what its type was initially.

Editing the Content of a Box

Double click on a box to edit its content.

• Numbers should be entered as simple numbers.• Strings should be entered between double quotes – inverted commas.• Symbols should be entered as simple text.• Lists should be entered between parenthesis, just as in Lisp. Ill-formed lists are not accepted.

To confirm the input value, press [ENTER] or click in the patch editor. No line return is allowed in data boxes.

Resizing

To fit the box size to its content, select it and type [I].

Connection to Another Box

Click on the outlet to create a connection and drag it to the wanted inlet of another box.

Automatic Connection

To add a connected data box to a factory or function box, [SHIFT] click on an input. This data box will have the default value of the input, which will then be displayed permanently.


V -

Vis

ua

l P

rog

ram

min

g

AUAutomatic Connection

`

2.2. Objects – Factory Boxes

In OM, objects are created and used in patches via "factory" boxes. A factory box refers to a class* and allows to create instances*– exemplars, in other words –, of this class.

• Factories can be connected to the other components of a visual program. • Their inner editor is a graphical user interface that allows to visualize, edit and manipulate the objects

produced by factories. For instance, one can edit a musical sequence in a traditional score editor.

This dual aspect of formalized computation, associated with direct manual interaction on the musical material, is a fundamental feature of OM, which makes the factory box a major patch component.

Factory boxes are accessed via the CLASSES menu or can be added in a patch from the LIBRARY window.

How To Add a Box into a Patch Editor

2.2.1. Graphic Attributes

Visualizing Objects : the Miniview

The current value of a factory box – its last computed value, or its default value if the box has just been added – is displayed instead of the initial icon.

To show or hide a miniview, press [M] .

Adjustments

To move the content of a miniview up or down : press [ALT] + [↑] or [↓] .

Default Miniview

Some classes don't have a specific miniview. A default miniview then shows the different slot – input – names and current values.

About Slots

Displaying and Editing the Name of a Factory Box

In theory, the name of a factory box isn't displayed with its icon.

To display or hide the name of a box, press [N]. A default name appears in the lower left corner of the box icon. This name is that of the corresponding class of the box.


V -

Vis

ua

l P

rog

ram

min

g

To edit this name :

1. open the INFO window

• select FILE / GET INFO • press [CMD] + [I]

2. edit the name in the NAME frame.

To show or hide a miniview, press [M].

2.2.2. Instantiating Objects : Factory Slots

Instantiation

An instance is an exemplar of a class of objects. Instantiation is the process of creating an instance out of a factory box.

A factory box has a number of slots, represented by inputs and outputs. Once values are assigned to the slots or parameters of a factory box, it can be evaluated to produce an instance*, an exemplar of a class.

• The first input and output always correspond to the object that is created by the box. It is called the "self" of the box.

• Each of the other inputs and outputs stands for an attribute, or parameter of the object – a slot* of the corresponding class*.

Note that the value of a factory box can also be defined via its editor.

First Input / Output : "Self"

The first input / output of a factory box is usually called "self". It stands for the object itself.

A "self" input can be connected to :

• the "self" output of an object belonging to the same class, • a simple value, or the output of an object, provided it can produce such an object.

Reciprocally, the evaluation of a "self" output, or its connection to another box returns the computed object itself.

Automatic Object Conversions

Sometimes, a simple value, or a different type of object, can be connected to a "self" input.

In this case, when compatibility allows it, OM automatic converts objects and creates an instance of the relevant class.


V -

Vis

ua

l P

rog

ram

min

g

Manipulating Objects via the "Self" Input

The merger function builds a chord-sequence, or chord-seq*, out of two other chord-sequences given as arguments*.

• The "self" outputs of the chord-seqs are connected to the inputs of merger.

• The output of merger is connected to the "self" input of a third chord-seq.

• The third chord-seq represents the resulting chord sequence once evaluated.

The two initial chord-seqs are locked to preserve their value. Conversely, the box that is to be evaluated isn't locked, to take the result of the upstream computation into account.

Protecting a Box

Evaluation : Displaying the References of a Box

To evaluate a whole box, select it and press [V].

Its value is computed, and the result of the "self" output, that is, the reference of the resulting instance* is displayed in the Listener.

About Evaluation

Tip : Reinitializing a Box

To reset a box to its default state, press [SHIFT] + [I] .


V -

Vis

ua

l P

rog

ram

min

g

A chord can be created from a note, but a note cannot be created from a chord.

Other Inputs / Outputs : Object Parameters

Parameters

The other inputs and outputs represent the various parameters, or class slots, used for defining an instance.

Inputs and outputs respectively address the same parameters – and follow the same ordering.

To get information about the qualities of a slot, keep pressing [CMD] while overing the mouse over an input or output.

Setting Input Values

Input values must be specified to define an object. Several parameters can be set or connected at a time. If no value is specified, the default value of the input is applied.

Setting Box Inputs Values, Using a Box's Editor

Confict : Setting the "Self" Input and Other Attributes

An object can be created directly from the "self" input value, and from the other input parameters. By convention, "self" has priority over the other inputs, whose values are ignored.

Getting Output Values

The different outlets of an object can be used for reading the values of its attributes. Outputs can be connected as parameters to other factory or function box inputs.

To evaluate the value of an output, [CMD] click on it. The whole box is evaluated and a specific instance of the class is created.

A note box has five inlets and outlets, a "self", and four other inlets, which correspond to the usual musical features or parameters of a note : midicents – pitch –, velocity – dynamics –, duration, midi channel.


V -

Vis

ua

l P

rog

ram

min

g

The second input represents the pitch value of a note box.

• If the factory box, or if its "self" outlet is evaluated, the reference of the instance appears in the Listener.

• If the second output is evaluated, a similar value to that of the second inlet is returned in the Listener, and informs us about the pitch of the note.

Importing / Exporting Instances as Files

The current value of a factory box can be exported or imported as a file to or from any location in the computer. Exporting an instance is a means to preserve the musical result of a computation.

Export / Import Procedures

Both procedures take place in the patch editor, via a contextual menu. Instances are identified by the .omi extension – "i" for "instance".

1. To export the instance, or to import an instance in the box, [CTRL] / right click on a factory box.2. Choose a directory for location, or a .omi file to import.

By default, OM offers to locate the exported file in the last folder where items were saved.

Nevertheless, it may be more convenient to create an instance box* out of an instance. Instance boxes can be saved as global variables* in a dedicated package of the Library, the GLOBALS package.

About Instances and Global Variables, See :

Exporting an Instance as a .omi file to an external directoy.


V -

Vis

ua

l P

rog

ram

min

g

2.2.3. Box Editors

Factory boxes have an internal editor. As a complement to the algorithmic creation of objects, it is a means to build, or modify them manually once objects have been initialized. Some elementary classes have a default editor, but most objects used in OM have specifically dedicated editors, such as score editors, sound file editors, bpf editors, etc. All editors open with a double click on a factory box.

Editors

Default Editor

When a class has only a default – basic – editor, it opens with a double click.

This editor has a number of slots, which represent the object's parameters. Each slot is represented by a grey box and can be edited directly.

Specific Editors

Some factory boxes have a specific editor, which also opens with a double click.

To open the default editor of such factory box, press [CMD] and double click on the box.

Note that both editors can't be open at the same time. Indeed, modifications brought to an editor cannot be applied to the other editor automatically. Close an editor manually so as to open the other editor.

Preserving Manual Modifcations

Once modifications have been done in an editor, the corresponding box is locked automatically. Indeed, a new evaluation of an unlocked box would compute a new object and replace the current value, hence canceling all previous modifications. Of course, the box can still be unlocked if necessary.

Automatic locking of the factory box after manual editing.

To lock or unlock a box, select it and press [B].


V -

Vis

ua

l P

rog

ram

min

g

The default and specific score editors of the note class

2.3. Function Boxes

Functions are fundamental components of programs, and are some of the most important OM tools. A function has a number of arguments*, which generally represent data to be transformed, or its parameters. Functions are accessed via the FUNCTIONS menu, or can be added in a patch from the LIBRARY window.

How to Add Functions Into a Patch Editor

2.3.1. Reference FunctionsA function box refers to an underlying function that allows to execute a given operation.

OM Functions / Lisp Functions

There are two main types of function boxes : OM functions and Lisp functions.

• OM functions are specifically declared and assigned particular graphical properties : an icon,

default inputs, etc. In other words, they have been designed for OM.

• Lisp functions are defined in the Lisp standard programming language. Their differ from OM

functions by a "LISP" icon.

Both function types can be added and used in a patch following the same modalities.

Most of the time, it is necessary to thype the name of Lisp functions to add them in a patch editor, for they are not provided in the OM menus. However, a set of useful Lisp functions is accessible

• through the FUNCTION / OM KERNEL / LISP menu• in the OM KERNEL / LISP package of the Library.

How to Add a Function Into a Patch Editor

Function Boxes Names

Changing the Name of a Function Box

When added in a patch editor, a box shows the name of the function it stands for. Out of convenience, this name can be edited : double click on the text field and type a name. Note that some boxes – for instance, basic functions like om+ – do not have editable names, due to their obvious meaning.

Name Changes and Function

Changing the name of a box doesn't affect its underlying function. Renaming a reverse box into a rotate box doesn't turn the box into a rotate function !


V -

Vis

ua

l P

rog

ram

min

g

2.3.2. Inputs and Outputs

A function box has a number – 0 or more – of inputs, which represent the arguments* of the function, and one or more outputs, which return the result(s) of a computation.

Inputs

Using Default Values

The inputs of a box initially come with default values. Nevertheless, they seldom enable correct computations : their values must be reset by the user or they must be connected to other boxes' outputs.

• A : the om+ box appears without visible values, and its default values are equal to 0. The evaluation returns 0.

• B : two values have been connected to the same box. Viewing Default Values

Tip : Editing Default Values

Default values can be set directly when typing the name of the function box – for instance : "om+ 5 7".

Getting Information

Information is provided by tooltips or in the available documentation.

Input Tooltips and Function Documentation

The function hasn't changed, although its name has been modified, as shown by its online documentation.


V -

Vis

ua

l P

rog

ram

min

g

Outputs

Reminder

Outputs can be evaluated and used for connections with other boxes. Hence, one can evaluate either a whole function, or a specific output that may return a different result.

• To evaluate a function box, elect it and press [V] .• To evaluate a specific output, [CMD] click on it.

The result of the computation is given instantly in the LISTENER window.

Multiple outputs

A function box may have several outputs, which means that it can return multiple values.

• If the box is evaluated, all the outputs are evaluated, but the Listener prints the result of the first output only.

• If an output is evaluated, all the outputs are evaluated, but the Listener prints the results of the chosen output.

Each output can be connected and/or evaluated independently, which doesn't affect the behaviour of the function.

About Evaluation Specificites

Multiple Outputs : Evaluate-Once Mode

The Evaluate-once mode is generally useful for multiple outputs function boxes : the result of a same evaluation is sent to all connected boxes. Otherwise, each of them will evaluate the function box separately :

• the function can sometimes return a different result each time,• useless additional computations run.

Here, in the first case, om-random is on the Standard evaluation mode and returns two different results to each input of list, as shown in the text box below. In the second case, it returns the same result.

More Information about EvalOnce and Other Evaluation Modes


V -

Vis

ua

l P

rog

ram

min

g

2.3.3. Additional Inputs : Optional and Keyword ArgumentsArguments can be added to Lisp and OM functions. Indeed, for practical issues, function boxes don't always show all possible inlets. Additional arguments can be either optional or keyword arguments.

Getting Information About Arguments

To know which types of arguments are accepted by a function :

1. select it

2. press [D] to get the function documentation.

The arguments type, that is default, optional and key arguments – the prototype of the function – is indicated at teh beginning of the documentation.

Optional Arguments : &optional

Optional arguments are identified by the &optional prefix. The order of optional arguments cannot be modified.

• To add optional arguments, select the box and press [ALT] + [→] or [SHIFT] + [>] .• To delete them, press [ALT] + [←] or [<].

Example : the Sort. Function

This function has one default argument, and two optional arguments, as shownat the beginning of the documentation :

• "lst" is a single default argument that stands for "list". It has no prefix.

• The &optional prefix referes to optional arguments.

• The first optional argument is "test", an optional predicate allowing the comparison of values. • The second optional argument is called "key". It is a potential connection used for applying a function

to the elements of "lst", before they are compared with each other. Do not confuse with the &key prefix of keyword arguments!


V -

Vis

ua

l P

rog

ram

min

g

This function shows two default arguments, and twelve additional arguments...

Sort. puts numbers from a list in increasing order.

Online Documentation

In some cases, recent upgrades provides an online reference documentation instead of the internal documentation. This documentation is also accessed by pressing [D].


V -

Vis

ua

l P

rog

ram

min

g

The online documentation of sort. gives information about the behaviour of the function, and its optional arguments.

Keyword Arguments : &key

Keyword arguments are identified by the &key prefix and shown by dark blue inlets.

These arguments are not sorted, which is very convenient when a function has numerous additional arguments : a user might want to use the last of a twelve arguments list without having to display all the preceding arguments.

1. Select the box and type [K] to add a keyword argument.

Type [SHIFT] + [K] to remove it.

2. The name and value of a keyword argument must then be specified, as described in the following procedures.

Setting the Name of a Keyword Argument

Before it is defined by the user, its default name is the name of the first argument in the list. This name is visible by hovering the mouse over the box inlet. Note that keyword names are always preceded by " : "

To change the argument :

1. click on the inlet 2. type a new – existing – keyword name.


V -

Vis

ua

l P

rog

ram

min

g

List of Available Keyword Arguments

The list of available keyword arguments is displayed by a tooltip or in the documentation of the function.

• To display the list, hold [CMD] while hovering the mouse over the inlet.• To open the documentation of the function, select a box and press [D] .


V -

Vis

ua

l P

rog

ram

min

g

Setting the Value of a Keyword Argument

The value of a keyword argument is set like the value of a standard argument by connecting a box to the keyword input. This box can be

• a data box• another type of box.

2.3.4. MethodsIn theory, standard Lisp functions are not typed explicitly : their arguments are not predefined, and they are supposed to accept any type of argument. However, internal errors may still occur if the input data is not of the expected type.

On the contrary, most OM functions actually refer to what is known as generic functions*. In CLOS*, a generic function is a kind of "meta" function that applies to several distinct types of arguments*

via several methods*. Each method is specialized to adapt the behaviour of the function – the way it operates – to the type of argument it is assigned. Hence, the input data is "filtered" before computation starts and the relevant method is applied to it.

For instance, a generic add function could be considered a set of two different methods.

• The first method can add a number with another.• The second method can add a number with a list of numbers.

Generic Function Editor

Double click on the icon of a function to open the generic function editor.

This window provides :

• the list of methods which compose a generic function,• information about the arguments accept by the method.

The universal type, which means "any type", or "T" for "true" in Lisp is represented by this icon : . This means that the method accepts any type of argument.

For a Review of the Symbols Found in Function Editors :

Adding Methods to a Generic Function

The applications of a generic function can be extended by user-defined methods, so that it can accept new types of input arguments.

Adding Methods to a Function

Calling Methods

In a patch, "calling" – using – a generic function with the wrong types of arguments, triggers an error message of the type : "No method is defined for this type of box ...". For instance, this can occur if a function is connected to a data type it cannot accept.


V -

Vis

ua

l P

rog

ram

min

g

Example : Calling Om+ with a Chord and a Number

Here is a widespread error when using object boxes :

In this case, we want to transpose a chord. To execute an operation, a function must apply to the right argument : the relevant output must be connected to the function. No method is defined, for, as seen previously, the chord + number method is not part of the om+ generic function. The wrong output, "self" is connected to om+. The "pitch" output should be connected to it.

Object Box Inputs and Outputs

Compiled Functions and Methods

The "compiled function" or "compiled method" messages appear when clicking on a Lisp function box or in a method icon within a generic function editor.

This means the function is protected. It is internally defined in OM and cannot be modified through the graphic interface. However, user-defined methods can be open in method editors.

Creating Generic Functions and Methods


V -

Vis

ua

l P

rog

ram

min

g

Lisp functions cannot be open in the OM graphic interface.

2.4. Comments

A comment is a text box that doesn't affect the patch in which it is set. It allows to add textual indications that can make a program more legible.

Creating a comment

With the contextual menu

To add a comment in a patch :


2. choose COMMENT .

Directly in the patch editor

To add a comment box directly in a patch editor :

1. [CMD] click in the editor and type "comment"2. validate to create the comment box.

Editing a comment

1. Double click in the comment box to type the text. 2. Click somewhere in the patch editor to validate and save your text.

Note

Unlike data boxes, comment boxes accept breaks and line returns.

Modifcations

Manipulating Comment Boxes

Like any other box, a comment box can be moved, resized, copied, deleted. To apply a modification, choose a menu item in the EDIT menu, or use the usual commands and shortcuts. To fit a comment box to the text, automatically, select it and press [I] .

Text Font and Colour

To modify the font type and colour of a comment :

1. [CTRL] / right click on the box,

2. choose TEXT COLOR or TEXT FONT.

Manipulating Boxes :


V -

Vis

ua

l P

rog

ram

min

g

2.5. Pictures

Pictures can be added as a background or illustration for patch editors.

Creating a Background Picture

To add a picture box in a patch editor :

• [CTRL] / right click in the patch editor, choose PICTURE

• [CMD] click in the patch editor and type "picture"• select CLASSES / BASIC TOOLS / INTERFACE BOXES / PICTURE .

Choose an item among the registered User Resources of the Picture Chooser, and click on [OK] .

• To add a resource, press [+] and select an item from any location in your computer.• To delete a resource, press [-] .

Resources and Picture Chooser

Managing Background Pictures

Selection / Delete

• To activate a background picture, press [Y]. A selected picture features a bold border. It can be moved around the patch by a simple drag and drop.

• To switch to another background picture, press [Y] again .• To delete a selected picture, press [BACKSPACE] .

Editing Picture Boxes

At this stage, a picture cannot be resized. More manipulations and extra edition are possible via the picture box and its editor.

More About Picture Boxes

The Picture box


V -

Vis

ua

l P

rog

ram

min

g

2.6. Other Boxes

Other types of OM boxes, related to more advanced programming concepts are detailed in specifically sections of the Advanced Programming part of this volume.

Abstractions

Abstraction Boxes

Abstraction boxes mostly refer to sub patches, but also to maquettes :

OMLoop Boxes

OMLoops are particular abstractions that allow to design iterative processes :

About the OMLoop Box

Functions and Objects

Control Boxes

Control boxes are specific functions, which allow to choose between several operations to execute, and or to control the execution of a patch :

About Control Boxes

Instance boxes and global variables refer to permanent objects used as reference material.

About Abstraction BoxesAbout Instances and Global Variables


V -

Vis

ua

l P

rog

ram

min

g

VI - Advanced Visual Programming

This section describes frequently used advanced programming concepts and tools :

• defining options or control procedures within programs,• designing complex programming structures by the means of functional abstraction* or iteration*,• manipulating and globalizing objects by the use of instances* and global variables*.


1. Abstraction

Abstraction

A program or patch can be more or less complex, and comprise one or several "layers" of components, like a tree structure. Such structures consist of patches embedded into other patches. Processes embedded in higher-level programs are called abstractions.

Abstraction aims at using a program as a function within another program.

From a formal view, an abstraction results from the conversion of one or several elements of a program into variables.

Consequently, in practical terms, an abstraction must have at least one outlet to communicate with the external environment.

Purposes

Abstractions allow to :

• define and visualize the structure of a complex program,• bring modularity in a program,• control the development of a compositional architecture and processes, or considering it from another

prospect,• gain space in a patch editor...

Example : Abstraction of a Process

Abstraction is a very convenient procedure – an abstracted program can be complex and "bulky". Its representation as an object also shows what an abstraction actually is : a coherent and delineated function inside another program. This is the crucial, essential property of functional abstraction.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

A chord multiplication patch has been embedded as an abstraction inside a patch. The resulting chord sequence is vizualised and integrated in a "higherlevel" process.

1.1. Abstraction Boxes

Abstraction boxes include :

• Blue patches : patches initially belonging to the workspace,

• Red internal patches : patches initially created in a patch editor.

This section details the differences between red and blue patches and related procedures.

Other Abstraction Types

In OM, maquettes, as well as OMLoop boxes and other specific boxes can also be used as abstractions.

About Other Abstraction Types :

1.1.1. Standard Abstraction

This section deals with the integration of an existing patch in another patch.

Adding a Patch From the Workspace to Another Patch

Procedure

To be used as an abstraction, a patch can be dragged from the WORKSPACE window to another patch editor.

The abstraction refers to the patch located in the workspace. Consequently :

• the abstraction and the patch in the workspace have the same name and icon

• the representation of the patch remains visible in the workspace, it hasn't been moved to the patch editor

• both items will be affected by subsequent operations performed in the abstraction.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

No matter where the patch is open from, the displayed editor will be the same.

Preserving the Master of a Patch

> cf "Saving / Reloading a Patch", page 61.

Using Duplicates

Several patch boxes with the same reference can coexist in a patch editor. Hence, the same function can be used at several steps of a program. Duplicating an abstraction creates another box referring to the same master patch. Subsequent modifications to the reference patch will therefore affect both items.

Managing Abstractions in the Workspace

Renaming an Abstraction

A blue patch can only be renamed in the workspace.

Deleting a Patch

In a workspace, nothing shows that a blue patch is used as an abstraction : this must be taken into account when organizing it. If a patch used as an abstraction in another patch is deleted, its reference in the other patch editor will be replaced by a dead box1 . When the user deletes this patch from the workspace, a warning pops up.

1 - > cf "Saving / Reloading a Patch", page 61.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

One representation of patch1 has been added inputs. The other representation has been added outputs. Both items have been equally and simultaneously modified.

1.1.2. Internal Abstractions

This section shows how to add an internal abstraction into a patch. Internal abstractions are represented by red patch boxes , which are only created in patch editors.

A red patch is autonomous :

• it is not attached to any external reference, conversely to a blue patch,• it only "exists" inside the patch where it was created.

Adding an Internal Abstraction : Procedures

Contextual Menu

To add an internal – red – patch in a patch editor :


2. choose INTERNAL / PATCH.

Double click on its name to edit it.

Directly in the Patch Editor

To add an internal patch directly in a patch editor :

• [CMD] click in the patch editor• type "patch" and validate.

Internal Programming

An internal patch is programmed just as in any patch, without restriction.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Duplicates

An internal abstraction cannot be affected by the modification of a possible duplicate.

Here, a duplicate has been created. The duplicate has been added inputs and outputs. The master item is preserved.

1.1.3. Conversions

Converting an Abstraction into an Internal Abstraction

Procedure

To convert a patch into an internal patch, select the patch box and press [A].

Note

A copy of the blue patch is created. It is fully autonomous from the master.

Converting an Internal Abstraction into a "Basic" Abstraction

Procedure

Converting a red patch into a blue patch amounts to assigning it a reference in the workspace. Once the conversion is done, the abstraction as well as its reference will be equally affected by possible modifications.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

To copy and convert an internal patch into a global – blue – patch, drag it and drop it in the workspace.

Modifications : Effects

1.2. Application

An abstraction inside a patch can perform calculus upon

• its own default values : its input(s) then have to be edited,• values coming from external boxes : its input(s) have to be connected to other boxes.

It can also return values to other boxes. In both cases, computation results are returned to the outside directly, or, in turn, to other boxes. The most interesting feature of abstractions is their use as functional abstraction*.

1.2.1. Inputs / Outputs

Making Connections to the Outside

Once a patch is added in another patch editor, it can be used as an abstraction*. An abstraction can have as many inlets and outlets as necessary to establish connections with other boxes.

• Values are returned by the inlets from the outside to the sub patch. • Results of computations are returned by the outlets to the outside.

Adding Inputs and Outputs

Inputs and outputs are added with a click on the and arrow icons in the open patch.

To add the desired number of inputs and outputs, click as many times as necessary on the corresponding icons. Inlets and outlets will appear on the sub patch icon.

Connections to other boxes in the patch editor can then be created.

Naming Inputs and Outputs

To rename inputs and outputs :

1. double click on the name of the icon : , 2. edit it and validate : .

This has no effect on the input or output's behaviour.

More Information about Input Boxes Edition :

Viewing Inlets and Outlets

Inlets and outlets of blue patches are not visible in the workspace.

To display information about inputs and outputs names, as well as a possible documentation, keep [CMD] pressed while hovering the mouse over them.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Example : Using a Sub Patch as a Functional Abstraction

Once a patch is added one or more inputs and connected to other items, it can manipulate variables like a function. These variables are taken as arguments by the function – functional abstraction – that results from this process. Data returned by the abstraction output(s) can also become variables for other boxes or for other functional abstractions.

A "Large" Program

The following program is quite developed. It could be used as a subordinate and coherent element in a more important patch. We will integrate it in a patch to use it as an abstraction.

Adding Inputs and Outputs to the Patch• Two input boxes are substituted to the parameters of the OMLoop box.• One output box is substituted to the chord-seq to return the result of the computation to

the outside of the patch.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Building successive chords from a chord multiplication.

Functional Call of the Patch

The patch is dropped into another patch editor.

Values can now be sent to the inputs of the OMLoop box from the outside of the patch, via the patch inputs. • The resulting data can also be returned to other boxes and be

manipulated. • The result of the computation can also be materialized by an external

chord-seq box, via its "midics" input.

Hence, the patch behaves like a function belonging within a higher-order program.

1.2.2. Input BoxesThe inputs of an abstraction are represented by inner boxes. Once edited, the patch can be evaluated internally and autonomously.

Editing Inputs

To edit the inputs of an abstraction, double click on an input box to open its editor.

The editor displays :

• the input name,• an editable DOCUMENTATION frame,• an editable DEFAULT VALUE frame.

To edit information :

1. enter values and / or a documentation,

2. choose [APPLY] 3. close the input box once to validate the default values and documentation.

To display the information :

1. [CTRL] / right click on the patch and choose UPDATE DOC

2. press [CMD] while hovering the mouse over the patch.

Using Default Values

Default values allow to evaluate an internal patch from the inside.

Using an Instance as a Default Value

The lower left frame of the input editor can take an instance as default input value. To add an instance or a global variable there, drag an instance box from a patch editor – or from the GLOBALS package to this frame.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Reminder

[SHIFT] + [CMD] click on an outlet to create an instance in a patch editor.

About Instances and Global Variables :

Internal Evaluation

Default values are designed to test if a patch works with an internal evaluation. They are ineffective as soon as a patch is evaluated from the outside.

To evaluate a patch internally, [CMD] click on the internal output box.

Note

Default values are also ineffective if values are sent to the patch from other boxes.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

An instance can be created out of a factory box and dropped, as well as a global variable, from a patch editor to an input editor.

1.3. Recursive Patches

Recursion

In computer science, recursion is the application of a function within its own defnition. This method allows to solve some complex problems. In order no to "call itself" infnitely, a recursive function must include a termination condition. A termination condition is a necessary condition so that the function doesn't call itself.

Examples

The n! Factorial Function

The factorial function is written "n!". It is a widespread example of recursive function. It calculates the produce of all positive integers that are inferior or equal to n.

n! is defined as follows :fact(n) = 1 * 2 * 3 * ... * (n-1) * nFor instance: fact(3) = 1 * 2 * 3

It can also be defined recursively : fact(n) = n* fact (n – 1)For instance : fact(3) = 3 * (fact(3-1))fact(3) = 3 * (2 * fact(2-1)) fact(3) = 3 * (2 * 1)

Hence, the termination condition of the factorial function is fact(1) = 1.

It allows to calculate all the combinatorial possibilities of n elements, such as, for instance, the calculation of all possible melodic combinations of a group of notes.

The Fibonacci Suite

The Fibonacci suite calculates the sum of a number of integers inferior or equal to n. It is another type of recursive function, which is written "f!".

"f!" is defined as follows :fibo(n) = 1 + 2 + 3 + ... +(n-1) + nFor instance: fact(6) = 1 + 2 + 3 + 4 + 5 + 6

It can also be defined recursively :fibo(n) = n + fibo (n-1)For instance : fibo(6) = 6 + (fibo (5))


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

1.3.1. Recursion in OM

Creating a Recursion

Recursive programs can be designed in OM by inserting the reference of a blue patch in its own editor – that is, putting a patch within itself. If this patch has inputs and outputs, they will also appear on the patch box, so that the patch can be "called from inside itself".

Infnite Calls

A termination condition is absolutely necessary to call a recursive patch. Otherwise, a succession of infinite calls will be triggered at the evaluation. Mind to save all your material before calling a recursive patch.

Example : Implementation of the Factorial Function

Factorial Patch

We have renamed the recursive patch as "fact". We will use it to create a recursive function that actually corresponds to the factorial function.

The function has one input, n, which calculates fact(n) = n * fact(n-1). This function has no termination condition. If it is called in its current state, it will never end. • The n values sent recursively are strictly decreasing, since they are always equal to

n-1. • Besides, we know that fact(1) = 1.• Therefore, we will add a non recursive branch, applying to cases where n = 1, via

omif.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Creating a recursion : a patch is dropped into its own editor.

Implementing a Termination Condition

The resulting patch means : if n = 1, then fact(n) = 1 else, fact(n) = n * fact(n-1)

1. When omif is evaluated, it evaluates the = predicate.2. The = predicate returns "nil" if n ≠ 1 and "t" if n = 1. This is the termination condition of the patch.

• omif returns the value of its second input (1), if it gets "t".• omif triggers the evaluation of the boxes that are connected to its third input if n ≠ 1. • The factorial of n is calculated by om-, the fact sub patch and om*.

Using Omif


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

1.3.2. Recursive Treatment of Tree Structures

Recursive Treatment of Tree Structures

Recursion is often applied to tree structures, such as lists. Indeed, a list can be described as a tree, whose components are either leaves, or nodes. A leaf is a termination of a tree, a node is another list that can, also, contain leaves of nodes.

Example : Recursive Treatment of a Multiple Level List

We would like to add 1 to each of the atoms of this tree : (( (1 2 3) (4 5 6)) (4) ((6 7)))). In other words, we want to increment – increase the value – the terminal items of the list. But we cannot just apply om+1 to the list : om+ cannot reach each atom directly. It must go through each level of the tree. We will apply this recursive function to the tree : IncrListElements (LIST) = for each ELEMENT in LIST, do :

• "If element is an atom, then return element + 1." This is the termination condition. • "Else, apply IncrListElement to the elements." This is the recursive call to IncrListElements.

The result of the function call upon a list is that the whole tree is ran through and that all terminal items will be incremented. This means that the termination condition of a recursive function applying to a tree structure would be to reach a leaf, or extremity of a tree.

Internal Patch Recursion

Do not ever build recursive programs with internal – red – patches, or with OMLoop boxes. A function has to be global to apply within itself.

Implementation of IncrListElements in OM1. "Input" yields values or lists of values to be processed.2. If an element is an atom, "input" is incremented directly. 3. If an element is not an atom, – that is, a list –, the patch is applied recursively to each element of the list...

Note that mapcar allows to apply the patch on Lambda mode successively to each element of a list. An alternative would be using an OMLoop to call the sub patch successively on each element of the list.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

This patch contains IncrListElements. When it is called on the list, each atom is incremented.

2. Evaluation Modes

"Evaluation" refers to two different concepts :

• The user-evaluation is triggered by the user via the interface, with a [CMD] click on an outlet, or with a selection + [V].

• The internal-evaluation refers to an evaluation or to a series of evaluations resulting from a user-evaluation.

This section deals with controling internal-evaluation.

Boxes can be set on four different evaluation modes, in addition to the default mode, to control the transmission of resulting data in a program, or to perform specific tasks. These modes are :

• Lock : • Evaluate-once : • Lambda mode : • Reference mode :

To select an evaluation mode :

1. press [B] to set the box on Lock mode2. click successively on the upper left label of the box to select other modes.

To reset the box to its initial state, press [B] again .

Duplication doesn't affect the state of a box that was set on a specific evaluation mode : the copy will have the same parameters and will be on the same mode as the master.

2.1. Lock Mode

Properties

Use

A locked box returns the last computed or edited value, and any parametric modification will be ineffective.

Procedure

To set a box in Lock mode, select it and press [B]. A small icon appears on the upper left corner of the box. Examples

A locked function always returns the same value, as shown in the first figure.

New values don't affect a locked factory box. In the second figure, a chord (A) is locked and duplicated (B). New values have been assigned to chord B, and the box has been evaluated. The pitches of the instance haven't changed.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

2.2. Evaluate-Once Mode

Properties

Use

A box on Evaluate-once mode is locked at each user-evaluation* after the first internal evaluation. It remains locked for all subsequent internal-evaluations*, until the next user-evaluation.

A box on Eval-once mode is evaluated once, and only once. This is valid :

• if this box has multiple outputs,• if this box is connected to several upstream boxes,• for all upstream connected boxes.

Multiple Internal Evaluations

A box connected to several downstream boxes can be evaluated several times at a single evaluation : in this case, reproducing the evaluation of a box can be either useless and lengthy. It can also be or a source of miscalculation, when a box is likely to return different results, while it must return the same values to all connected boxes. A box set on Eval-once mode returns the same values to all the boxes it is connected to at a single evaluation.

Procedure

To set a box on Eval-once mode, press [B] and click on the upper left cross once. A small icon appears.

Example

The output of om-random is connected to the two inputs of list. In both cases, om-random returns a different value every time is is called. But :

• when the evaluation mode is not specified, one user evaluation of list triggers two internal evaluations of om-random, that is, one per input of the list function ;

• on Once mode, one user evaluation triggers a single internal evaluation, and both inputs of list get the same value.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

2.3. Lambda Mode

Properties

The Lambda mode plays a major part in the design of complex programs, and is used in various types of configurations. It is a specific procedure that allows boxes to be identified as "function objects". Then, the box won't perform a calculation and yield a result, but will yield itself as a function object when the evaluation takes place.

Use

Some functions wait for arguments that are not as simple as numbers or lists. Functions called higher-order functions have some arguments, called functional arguments, which are function objects themselves. A function has to be set on Lambda mode to be used as a functional argument, and can be then called a "lambda function".

For instance, apply is a higher-order Lisp function that applies a functional argument, which must be a function, to a second argument, which must be the elements of a list. Here, apply applies + to a list of four numbers.

Procedure

To set a box on Lambda mode, select it, press [B] and click twice on the upper left cross. A small λ letter icon appears.

In Practice

In practice, functional arguments are used in two main configurations :

1. as an argument applied to one or more other arguments by the higher-order function 2. as a test function that will determine the behaviour of a higher-order function.

Applying a Lambda Function as an Argument

The argument can be specified with a standard function box on Lambda mode, and is applied to the other arguments of the higher-level function, as shown in the first example.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

The argument can also be specified by a simple function name in a data box.

Some functions are more specifically dedicated to the application of lambda functions :

Applying a Lambda Function as an Argument :

Using a Lambda Function as a Test Function

Some functions have a default "test" argument that is generally used for determining which items, among a wider set of items, the function operates upon. It is sometimes necessary to redefine this test argument so that the function can operate upon other types of items. A test function can hence be compared to a predicate*, and is connected to the "test" argument of a higher-order function.

Defining Test Arguments

2.3.1. Applying a Lambda Function via a Higher-Order FunctionA higher-order function basically takes two arguments : a function, that is, a functional argument, and another argument. The functional argument is applied to the second argument by the higher-order function.

Basic Principles1. The functional argument is a variable of the higher-order function.

2. The functional argument must be added one "free" input per supplemental arguments of the higher-order function.

We will show the application basis of a lambda function via a higher-order function to another argument.

Applying Rotate to a List via Funcall

We will use funcall as a higher-order function, the rotate function as a first argument, and a list as a second argument. This means that rotate is now a variable of funcall.

• Funcall, – "fun" stands for "function" – makes function calls : it applies a function to a second argument.

• Rotate returns the circular permutation of a list : it enumerates the items of a list from the 2nd element.

1. A free input is added to rotate so that it is applied to the list. Funcall is the higher-order function. Rotate is on Lambda mode. Funcall applies rotate to the list.

2. Rotate is not on Lambda mode anymore. It takes the same list as argument.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Random Application of Two Functions to a List

Using lambda functions allows to choose randomly between two functions to apply to another argument. Here, we want to modify a list of values with a function that would be selected randomly. In other words, we would like this function to be a random variable. We will apply either permut-random, or rotate to a list.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

• Permut-random makes a random permutation of the elements of a list.

• Rotate enumerates the elements of a list from the second element.

1. Permut-random and rotate are our variables : they are set on Lambda mode.

2. List makes a list with these two functions. 3. Nth-random picks one of the two functions in the list

randomly.Funcall is the higher-order function that applies this function as a 1st argument to its 2nd argument, a list.

Permut-random is applied randomly to the list.

Note

The result of the computation is the same in both cases. We will now extend the previous example to show how using a function as an actual variable.

Making a list with two functions, and choosing one of them in the list like a "lambda item" is possible precisely because these functions are on Lambda mode.

Inputs of a Lambda Function

A lambda function can be applied to several arguments. Hence, calculations can be executed upon arguments the lambda function may not take otherwise.

"Free" Inputs of a Lambda Function

A function on Lambda mode must have as many "free" inputs as arguments returned by the higher-level function.

The * function cannot multiply lists, like om*. To multiply the elements of two lists, we will apply * with mapcar.

Mapcar applies a function to the first element of each next input, then to the second argument, to the third argument, and so on, and builds a list with the result of each evaluation.

• Input #0 of mapcar is the * function.

• Inputs #1 and 2 of mapcar match inputs #1 and 2 of * on Lambda mode.

• The resulting lambda function can be expressed as follows : ( x ) * ( y ), where x and y are the successive elements of each list.

Note that the two inputs of om* remain free.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

If the two functions were not on "lambda" mode, the list function would return a list that contains the result of these functions call.

Adding a Default Argument to a Lambda Function : "Currying"

Currying

"Currying" is the reduction of the number of arguments of a lambda function by assigning it one default argument.

Default Argument

This default argument must belong to the arguments accepted by the function : the function has predefined and undefined arguments. The number of inlets of the higher-level function must take the number of free inlets into account.

Here, * has

• one default argument : a number

• one free input, which represents the second input of mapcar.

Remember that * only accepts numbers.

1. Mapcar goes through the second input list (B).

2. It "tells" the * function to apply (A) to the each item of (B) successively.

3. The lambda function that is built can be expressed as follows :

( 5 ) om* ( x ), where x stands for the elements enumerated through (B).


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

2.3.2. Using a Lambda Function as a Test Argument

Some functions have a test argument that defines conditions to manipulate another argument. This test argument can be replaced by a lambda function.

Example : Removing Octaves from a List

We need to remove octaves from a list of pitches in midicents, but there is no such function in OM.

The Remove-Dup Function

The remove-dup function tests if two items in a list are equal and removes duplicates.

• The first argument of remove-dup must be a list

• Its second argument must be a test function.

• By default, this test is 'eql : values that are equal to another value in the list will be removed.

The values of two pitches of an octave are not equal. Hence, the equality test used for removing items must be modified : the "test" argument of remove-dup must be replaced by a lambda function.

Using the Modulo Om// Function as a Test Argument for Remove-Dup

Modulo

• Two values have the same modulo when their division by the same ratio produces the same rest.

The midicent value of an octava is 1200. Comparing the result of two values modulo 1200 allows to know if they have an octave relation. This means that an euclidean division by 1200 will return the same rest.

• For instance, C4 is equal to 6000, C5 to 7200. F≥4 is equal to 6400, F≥5 to 7600.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

The following patch tests if the results of two divisions, modulo an octave, are equal, with the modulo function om//.

The first output of om// returns a quotient, its second output a rest : it calculates the modulo of our values. The = predicate tests if the rests of two divisions are equal. If so, the duplicate is removed.

Using the Test Argument in a Lambda Patch

The patch is now on Lambda mode and connected as a test argument to remove-dup. It has two inlets, which specify that the lambda function takes two arguments.

Remove-dup can now remove all values whose modulo equals the modulo of another value.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

2.4. Reference Mode

Properties

Use

A box on Reference mode returns its own internal reference. Applying this mode to a function, a factory box, a patch or a maquette allows to return the generic function, the class or the program it refers to.

Procedure

To set a box on Reference mode, select it, press [B] and click three times on the upper left cross. A small downward arrow icon appears.

Applications

Manipulating Patches and Maquettes

This mode is therefore dedicated to specific tasks : on Reference mode, a patch box or a maquette box returns its reference to a function, in order to be manipulated at runtime.

Example

The Reference mode is used for adding a TemporalBox in a maquette via the add-box-to-maquette function.

Maquettes : Reference Mode


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

3. Control StructuresIt is sometimes necessary or useful to be able to control the execution of a process.

This can deal with

• choosing among a set of possibles to execute a task, • with the sequential organization of these tasks during the execution of a program.

In other words, the user can control what is done, and how it is done during an evaluation. OM offers a series of control modules designed to define this control accurately.

3.1. Predicates : Testing Relations and Properties

Predicate

The concept of predicate refers to a property, or a relation between two terms of a proposition.

Predicates are boolean operators : they verify that a proposition is true by returning "true" or "false" – "yes" or "no". In Lisp, "nil" means "false", and "t" means "true". As a convention, any non nil value is also interpreted as "true".

There are several types of predicates. Among them, algebraic predicates compare numbers, equality predicates test if two objects are identical, type predicates that test if an object belongs to a specifc Lisp type, and so on.

In OM, predicates are often used as conditions for the execution of a program.

Arguments and Evaluation of Predicate Boxes

Predicates can take arguments directly from their inputs or from other boxes. They are evaluated like any other box. Evaluation returns either "t" or "nil".

Using Predicates in Conditional Structures


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

3.1.1. Algebraic PredicatesComparing numbers is a widespread use of predicates in OM. Predicates dedicated to the comparison of numbers can be found in the PREDICATES menu item of the FUNCTIONS / OM KERNEL / CONTROL menu.

Functionalities

Here is a list of OM and Lisp predicates. Like other functions, they can also be added in a patch editor by typing their name directly. Equivalent Lisp predicates can be added directly in a patch editor.

OM PREDICATE WRITTEN LISP PREDICATE WRITTEN TEST

OM=

= A equal to B ?

OM/=

/= A different from B ?

OM<

/= A inferior or equal to B ?

OM>=

>= A superior or equal to B ?

OM>

<= A inferior to B ?

OM>

< A superior to B ?


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

3.1.2. Equality PredicatesIn Lisp, equality can be interpreted different ways. For instance, the character "a" is a concept that can be represented by several different glyphs – A, a, a – which can be considered identical or not, depending on the predicate. These predicates are not available in the menus : their name must be typed directly in a patch editor.

Functionalities

There are four equality test predicates :

• eq • eql • equal • equalp.

The eq and eql predicates are the strictest, the equal and equalp are the most open predicates, and are relevant to most cases.

PREDICATE RETURNS "T" WITH EXAMPLES

identical objects with the same referenceintegers and ratios of same value glyphs representing the same character→ "nil" : strings, lists, floats, ratios that produce floats.

• For instance, two chords with the same reference are eq.

eq A A → teq 2 2/1 → teq A a → teq "A" "A" → nileq (A B C) (A B C) → nileq 2.5 2.5 → nil

eq or eql objectsstructurally similar objects strings with identical glyphsfloats of same value • In some cases, equal considers the object. In other cases,

equal considers the concept.

equal (A (b) C) (a (B) c) → tequal "A" "A" → tequal "A" "a" →nilequal 2.5 2.5 →t

eq, eql or equal objectsstrings with similar glyphs numbers of same numerical value • Equalp only considers values and concepts, not their

representation.

equalp "A" "a" → tequalp 2 2/1 → tequalp 2.5 2.5 → tequalp 2 2.0 → t

Equality Predicates in Lisp and OM Functions

Many Lisp and OM functions need a predicate to operate.

Functions that perform operations upon lists, for instance, have a default equality predicate used for identifying similar items in two different lists, and manipulate them. Note that this predicate can be redefined to modify the behaviour of the function.

Using Lambda Functions as Predicates :


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

3.1.3. Type Predicates

A type predicate tests if an object belongs to a type of object. Most of these types are Lisp types, which can be found in the CLASSES of the OMKERNEL / LISP package, or added in patches via data boxes.

Numbers

There are several number types, which can be tested by the following predicates.

• numberp: numbers • integerp : integers • floatp : decimals • rationalp : rationals

By extension, other predicates test the properties of numbers.

• plusp : positives • minusp : negatives • zerop : zero • oddp : odd integers • evenp : even integers

Other Main Type Predicates

PREDICATE RETURNS "T" FOR EXAMPLE

characterp the name of a character that has a printable glyph. #\Space ; #\a ... → t

symbolp things that can be named but numbers, strings, lists, some characters. 'cow ; note ; 2-ERz → t

atom anything not between parenthesis but strings. A ; 38 ; → t

listp anything between parenthesis, or nil. In Lisp, nil = empty list. (A B C) ; (A (B C) → t

consp a list with a car* and a cdr * . (A B) ; (A (B C)) → t

stringp anything between inverted commas. "vangogh#\Tab;;2" → t

functionp function names and function boxes on "lambda" mode. → t

nullp anything that is nil. nil → t ; ( ) → t

typep an object of a given type.

Type predicates are not available in the OM menus or packages, but their name can be typed in a patch editor directly. It conventionally ends in the letter "p" for "predicate".


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

3.1.4. In Practice

Predicates can be used as conditions defining the execution of an operation. Hence, predicates must be connected to

• the "test" input of an OMIF box,• to a function that has a test argument .

If a given property or a relation is verified by a predicate, the operation is performed.

Examples

Using a Type Predicate as a Test Argument

Here, we want to delete floats from a list with list-filter. List-filter rejects or passes elements from a list, depending on the predicate taken as argument.

It has three default inputs :

1. a predicate, whose default value is numberp2. a list3. an action – "reject" or "pass".

The floatp predicate and the "reject" option have been assigned to list-filter, so that floats can be rejected.

• List-filter tests each element of the list successively. • If the test is satisfied, the element is either rejected, or passed, depending on the option

that was chosen. • The remaining elements are returned in a list.

Using a Function on Lambda Mode

A predicate can be a function on "lambda" mode.

Using a Lambda Function as a Predicate


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

3.2. Conditional Operators

Conditional Operators

Conditional operators execute an operation if one or more preconditions are fulflled. If these conditions are not fulflled, they can possibly execute another operation.

OM offers two conditional operators : omif and conditional, which operate according to the following paradigm :

"IF A, THEN do B, ELSE do C". The "A" condition may be defned by a predicate.

To access the omif and conditional operators, select a menu item in the OM KERNEL / CONTROL menu.

About Predicates :

> cf "Predicates : Testing Relations and Properties", page 111.

3.2.1. Omif : If, Then, ElseThe behaviour of omif can be described by the following proposition : "IF the A condition is verified, THEN execute the B operation, ELSE execute the C operation.

The omif box can be accessed via the FUNCTIONS / CONTROL / OMIF menu.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Properties

Inputs

Omif has two default inputs and one optional input :

• "test" stands for "if" : it represents the test of a condition in a given proposition. • "action" stands for "then" : it represents the consequence of the test in the same

proposition. • "else" : allows to perform another operation if the condition is not fulfilled.

Each input accepts a function, a factory, or a data box.

To add or delete the optional "else" argument : press [ALT] +[←] or [→] / [SHIFT] + [>] or [<].

Behaviour

"Test" evaluates the box it is connected to and checks if a number of conditions for the operation are fulfilled.

• If the box yields something else than "nil", the conditional test is verified, and " then" evaluates the box connected to its second input.

• It the box yields "nil", OMIF returns the same "nil" value.

Omif is evaluated like any other box, and returns the value yielded by "then" or "else".

Examples

If, Then

Here, "test" evaluates the om= predicate, which checks if the value returned by om-random is equal to 2.

• If the condition is not fulfilled, om= and OMIF return "nil".• If the condition is fulfilled, OMIF evaluates the data box connected to its

second input, and returns "blue".

"Test" is determined by the om= predicate, but it can also be connected to any other type of box.

For Full Information about Predicates :

> cf "Predicates : Testing Relations and Properties", page 111.

If, Then, Else

Here, "else" has been added to OMIF. If the condition is not fulfilled, OMIF doesn't return "nil", but the random number.

Adding Optional Arguments


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

3.2.2. Conditional : Multiple Conditions

Conditional is very similar to omif : it tests if a set of conditions is fulfilled, one by one. As soon as one condition is fulfilled, conditional executes the corresponding operation.

Its behaviour can be summed up as :

"IF condition A is fulfilled, THEN return x, ELSE check if condition B is fulfilled.

IF condition B is fulfilled, THEN return y, ELSE check if condition C is fulfilled.

IF condition C is fulfilled..."

The conditional box can be accessed via the FUNCTIONS / CONTROL / CONDITIONAL menu.

Properties

Inputs and Outputs

The conditional box takes a number of test arguments. It has one default input and output and a free number of additional inputs.

• "test" : a test argument• "add-test" : an additional test argument.• The user can add as additional test arguments as necessary.

Its output returns the value of the last evaluated input.

All inputs are test inputs : predicates, or other types of boxes.

Behaviour

Conditional behaves like an or operator.

1. The box evaluates its inputs successively until an input returns a non nil value.2. This value is returned by conditional.

Conditional and Omif

Conditional can be used as a meta-omif box, with a virtually unlimited number of "if" / "then" and "else" inputs, and a terminal "else" input.

Each input can take an omif box representing a condition and an action. Because conditional stops the inputs evaluation as soon as it gets a non nil value, these actions are linked with each other in a causal chain.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Examples

In this example, we will test successively if 4 = 5, and define a last argument for conditional.

1. Om+ returns 4. 2. Every time, om= tests if 4 = 5, and returns "nil" to the omif

boxes. One by one, they return "nil", because the condition to return "1984" is not fulfilled.

3. Finally, the last input of conditional is evaluated and returns "george".

4. Conditional returns "george".

In this example, we want to filter values from 1 to 10 and pass 1, 7, 9 or 10.

1. Om-random returns a number between 1 and 10. The box is on "evaluate-once mode2" so that the same value is returned to all the other boxes at the evaluation.

2. The value is tested by two predicates.• If it is comprised between 2 and 6, the first predicate returns

true and omif returns "A".• If it is equal to 8, the second predicate returns true and omif

returns "B". 3. Finally, if none of these conditions is fulfilled, the last input of

conditional is evaluated and returns the random number yielded by om-random.

2 - > cf "Evaluate-Once Mode", page 98.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

3.3. Logical Operators

Omor, Omand

Omor and omand are boolean logical operators that stand for the "and" and "or" coordinating conjunctions.

A proposition that contains an "and" is true if all its elements are true.

A proposition that contains an "or" is true if at least one of its elements is true.

For instance, the following propositions are respectively true and false :

A : "Men are living creatures". B : "Cats are living creatures". "A and B" is true, and "A or B" is true.

A : "Men are human beings." B : "Cats are human beings". "A or B" is true, but "A and B" is not true.

In OM :

the omand box returns "true" if all its inputs return "true". Otherwise, it returns "nil".

the omor box returns "true" if one of its inputs return "true". Otherwise, it returns "nil".

Logical operators are accessed via the FUNCTIONS / OM KERNEL / CONTROL / LOGICAL OPERATORS, menu.

Functionalities and Behaviour

Inputs

Operators have one default input, "self" and as many additional "rest" inputs as necessary

• "self" : any data• "rest" : any data.

Their output returns data, or nil.

Use

• Logical operators evaluate their inputs successively. Any data that is not "nil" is "true".

Consequently, operators don't have to verify the truth-value of a proposition, to return "true". Numbers, as well as symbols and other non nil values are always "true" for logical operators.

• Logical operators are also used for associating several predicates in a single proposition.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Behaviour

Inputs are evaluated from left to right.

Omor tests a first input, and stops if it is true.

If not, it goes on until it gets "true". As a consequence, omor returns the first non-nil value, or "nil" if all inputs return "nil".

In this example, omor will always return the first input, "A".

Omand stops the evaluation if one of its inputs is not true. It goes on until it gets "nil", or until it reaches the last input.

All inputs have to be true for the condition to be verified, and omand then returns the last non-nil value.

In this example, omand will always return the last input, "B".

Example

The following program tests if a random number between 1 and 5 is superior to 1 and inferior to 4.

1. The number returned by om-random is compared with 1 and 3 by the om> and om< predicates.

2. Omand evaluates the predicates and returns "true" or "nil". 3. List makes a list with :

• the result of both predicates evaluation, • the result of the omand operator,• the number returned by om-random.

Note that om-random is on Evaluate-once mode, so that the same result is sent to all boxes during the same evaluation.

About EvalOnce Mode :

> cf "Evaluate-Once Mode", page 98.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Composing Propositions : Associating Logical Operators with Predicates

Operators behave with predicates like with any other boxes. Predicates are evaluated one by one, from left to right and return "true" or "nil".

• Omand returns "true" if all predicates return "true", and returns "nil" if one predicate returns "nil".• Omor returns "true" as soon as one predicate passes "true", and returns "nil" if all predicates return "nil".

An Incorrect Formalization

We might use logical operators to compare more than one value to another, as in the following proposition : "If A and B or C are superior to D, then return A, B, and C."

If we formalize the proposition literally, the program will be ineffective and will lead to a miscalculation.

Let's test if 3 and 1 or 6 are superior to 2 :

1. Omand is evaluated and returns the numeric value of its last input

2. Omor is evaluated and returns the numeric value of its first input

3. Om> compares the numeric value of its first input with 2, and returns "nil".

6 should be compared with 2, and 6 is superior to 2. Om> should return "true". The error comes from the way predicates have been applied with logical operators.

Basic Formalization Principles

Formalizing a comparison with predicates and logical operators implies that :

• Predicates must first compare values by pairs. • Logical operators must then be applied to the result of each comparison .

A correct Formalization

Be a list. Each number of the list is compared with a number.

1. Omif evaluates omor. 2. Omand is evaluated and returns the value of the two om>

predicates on the left. It gets "nil" and "t", so it returns "nil". 3 and 1 are not both superior to 2.

3. The last om> predicate is evaluated. It returns "true".

4. Omor gets "nil" and "t", so it returns "t". At least 6 is superior to 2.

5. Omif gets the result of omor : "t", and hence returns the list.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

3.4. Sequential Operators

Sequential operators control the occurrences of operations in program. They can apply to the iteration of an operation, or to the succession of several operations at a single evaluation.

Sequential operators can be accessed via the OM KERNEL / CONTROL menu.

Repeat-n : Iteration

Features

Repeat-n evaluates something a number of times and collects the results in a list. this allows not to repeat a manual evaluation.

It has two default inputs.

• "self" takes any type of data, a function, or a lambda function.

• "num" takes a number.

"self" is repeated n times. Its output returns the result as a list.

Example

Here, repeat-n is applied to om-random to produce a random notes sequence. Repeat-n evaluates om-random 15 times, which returns a random value each time.

The resulting list is returned to the pitches input of the factory box.

Advanced Use of Iteration : OMLoop

More complex or specific iterative processes can be designed and controlled via the OMLoop module editor.

The Omloop Module


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Sequence : Executing Several Tasks

Features

The sequence box executes a sequence of distinct operations.

It has one default input and output, and can be added as many optional inputs as necessary :

• "patch" takes any kind of box.• "oppatch" is an additional "patch" input.

Multiple outputs can return the result of corresponding upstream operations to other boxes.

Example

A chord-seq is generated while other tasks are executed. When the chord-seq is evaluated, sequence performs three tasks :


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

1. print "avant", 2. generate and print a random list of numbers,3. print "après".

Then, the value of its second output is returned to the "pitch" input of the chord-seq.

Note that without print, the Listener wouldn't display the values the outputs of sequence. These values can be returned with an individual evaluation of each output.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

4. Instance Objects

An instance represents a specific exemplar of a given class. Instances are obtained when evaluating a factory box, whose inner state is fixed as a definite entity.

Instances can be materialized via instance boxes in OM, and saved as persistent files. They can be used, stored, and modified according to specific procedures. This section provides conceptual and practical information about instance objects and their manipulation.

4.1. Creation, Import, Export

Creating an Instance Box

An instance can be materialized out of any output of a factory box, provided this output can return an instance or a list. Creating an instance box is especially significant when done from the "self" outlet of a factory box, which returns the object itself.

There are two types of instance boxes :

• class instances, which are created from objects,• list instances, which are created from lists.

Procedure

To create an instance box, [SHIFT] + [CMD] click on an output.

The corresponding object will appear in the patch editor.

The resulting box represents a specific object that cannot be reinitialized, but can be used and evaluated again in a patch.

This is why this box shows only one "self" outlet.

The name of the instance box can – and should – be edited.

Note

Specific procedures allow to modify instance boxes.

How to Modify Instance Boxes


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

List Instances

An instance derived from a list returns its content when evaluated.

Just like any list, it can be connected to other boxes to be manipulated, or to create new objects.

Exporting and Importing an Instance Box

Instance boxes can be exported out of a factory box via the contextual menu. [CTRL] / right click on a factory box and choose EXPORT.

To import an instance :

• [CTRL] / right click on a factory box and choose IMPORT in the contextual menu

• drag and drop an instance file in a patch editor. The instance is materialized as an instance box.

Instances can be imported from any location in the user's hard drive.

Instances and Global Variables

Instances are a means to save an object within a patch, where it can possibly be used as a source of data.

Instances can also be used in other patches :

• they can be copied • they can saved as global variables*, which is much more convenient and coherent from the view of OM.

For Full Information about Global Variables, See :


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

4.2. Instances Editors

Instance Editors

The content of an instance box can be modified like that a factory box : via a default or a specific editor. Indeed, instances always have a default editor, and sometimes a specific editor.

Specific Editors

Score objects, as well as a number of other types of objects, like bpfs, or text files, have a specific editor.

An instance has the same editor as the factory box it is derived from, and can be edited the same way.

About Various Editors

Default Editor

Yet, some factory boxes don't always have a specific editor. This is why instances and factory boxes are always provided with a default elementary editor.

The content of the slots – parametric values – of an instance can also be modified via this default editor.

• To open this default editor :

1. keep pressing [CMD] 2. double click on the instance box.

Each slot, or parameter, can then be edited via its own editor.

• To open a slot editor, double click on it.

A slot editor displays navigation arrows, and, for each component, a value and a corresponding index.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

The seven slots of a chord-seq. The six first slots take lists, the last slot takes an atom.

• To edit the value of a component :

1. double click on the numeric frame2. enter a new value and validate.

Note

The number of items per slot cannot be modified.

List Editors

Modifying a List Instance

To edit a list instance, double click on an instance box to open its editor. List instance editors are similar to

those of slots containing a list. A list editor displays components values, indexes and navigation arrows.

To edit it a value :

1. double click on it2. enter a new value and validate.

The Slots Box

Although the parametric values of an instance can't be accessed directly in patches, they can be accessed and modified with the slots box.

About the Slots Box

Editing the first value of the "midic" slot : the pitch of the first chord. Notice the navigation arrows on the top of the editor.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

4.3. Global Variables

Global variables are "globalized" types of instances. They are associated with the workspace where they have been created.

General Properties

Advantages

A global variable is an instance that can be used in several workspaces and programs. It is designed so that any modification of the object is incorporated in all of its representations.


When defining a chord, a metric sequence, manipulating an audio file, the user creates a specific instance*

from a class*.

• This instance can be materialized in the current patch editor by instance boxes . Instance boxes are grey.

• It can also be exported as a global variable to a workspace where it will be stored in the GLOBALS package . Global variable boxes are green.

Using a Global Variable

Reference of a Global Variable

Every time a global variable is used in a patch, it is represented by a reference.

• When evaluated, the box always returns the same reference• A single global variable can have several references in several different places.

Modifications : Effects

Any modification of a global variable will affect all of its representations as well as the master item.

• Modifying a global variable affects each of its references.• Modifying one of its references equally affects the variable itself and all its references .

Connections to Other Boxes


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

A global variable box can be connected to other boxes, just as an instance box.

Creating a Global Variable From an Instance

To create a global variable, an instance box must be dropped in the GLOBALS package of the Library.

Adding a Global Variable in the Library

Open the GLOBALS package in the LIBRARY window :

• double click on its lower part to open it as a side frame,• double click on its upper part,• [CTRL] / right click and choose OPEN in the contextual menu to open it as a window.

Select an instance and drop it in the GLOBALS package window. The instance box in the patch is converted into a global variable box automatically.

Naming a Global Variable

Creating Global Variables with Store Objects

Global Variables can also created from store objects.

Modifying a Global Variable

The Slots Box

Like an instance box, the global variable box appears without inputs. Parametric values of global variables can be accessed and modified via a specific type of box : the slots box.

How to Modify Instance Boxes Modifying a Global Variable from its Editor.

Modifying a Global Variable from its Editor.

A global variable can also be modified via their editor, like any instance box.About instances Editors


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

The variable can be renamed in the GLOBALS window : all related elements in the patch will be affected by this change immediately : they will have the same name and reference.

4.4. Reading and Modifying Instances : Slots

The slots box can read or modify the values of a slot – that is, a "field" or parameter – of an instance or global variable.

Reminder : Instances and Global Variables

Instances* are created out of classes via factory boxes.

• They can be materialized in a patch editor by instance boxes .

• They can be stored as global variables* to a workspace where they will be stored in the Globals

package of the Library.

All information provided in this section is valid for both types of boxes.

About Instance Boxes and Global Variables

Properties

Creating a Slots Box

A slots box is always created from a given object box, and has the same reference. To create a slots box :

1. [CMD] click in a patch editor, 2. type a class name

3. validate while keeping [SHIFT] pressed.

Morphology

The structure and morphology of a slots box is similar to those of the corresponding factory box. The slots box also has a "self", and a number of parametric slots.

For instance, the slots box created out of a chord instance has the same inputs and outputs : "self", "midicents", "velocity", "duration", "midi channel". It also has the same icon.

Behaviour• The outputs of slots return the values of the object's corresponding slots. • The parametric inputs of slots can take other values. When slots is evaluated, these values will affect the

corresponding slots of the object.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Using the Slots Box to Modify an Instance

Using "slots" allows to read and modify the parameters of an object without creating new instances out of new factory boxes :

Constraint

The "self" input of slots must be connected to the "self" output of an object, so that the slots of the object can be read and/or modified.

Reading Values

To read the value(s) of an instance's slot :

1. connect the instance to the "self" input of slots, 2. evaluate the corresponding output of slots.

Modifying the Values of an Object

To modify the value(s) of an instance's slot :

1. connect the instance to the "self" input of slots, 2. enter new values in the relevant input of slots,3. evaluate slots,4. reopen the instance editor.

Note that the reference of the object hasn't changed, despite the fact the object's content has changed.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Applying Slots to Factory Boxes

The same procedures can apply to factory boxes.

1. Lock the factory box before evaluating slots : otherwise, it will be reset to its default values.

2. Select the factory box and press [M] to refresh the miniview.

Modifying an Object from Within an Abstraction

Once an object belongs to an abstraction, its slots can't be accessed from the abstraction. It is sometimes wiser not to generate useless new instances :

• for optimization purposes• to keep the reference of the object one operates upon.

Procedure

To modify an instance from the inside of an abstraction :

1. Create a slots box and drop it in the abstraction and duplicate it.

2. Connect the input of the abstraction to the "self" input of slots.

3. Connect the slot you want to modify to the relevant box(es).

4. Connect the output of the program to the relevant input of the duplicate.

5. Connect the self output of the first slots box to the self input of the second slots box.

6. Connect the self output of the second slots box the the output of the abstraction.

7. Evaluate the factory box connected to the outside of the abstraction.

Consequences

When the initial instance is refreshed, it will also be modified, since both instance have the same reference.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

4.5. The Store Object

The store object is a general-purpose object, which is designed to store any type of data. For instance, one may want to be able to design one or more programs and use the same object everywhere without defining it from the beginning.

The icon of a store object represents a memory space.

1. A store object can be manipulated in a patch just like any other type of object, via factory, instance or slot boxes.

2. When a global variable* is created in the GLOBALS package, it is a store object, by default. Consequently, any type of object can be stored into it.

The Store Factory Box

To add a store factory box :

• select CLASSES / OMKERNEL / DATA / STORE • type "store" directly in the patch editor.

The store factory box allows to create any type of variable from any type of object in a patch.

It has two inputs and outputs :

• "self" : any object• "value" : any data, including instances of other classes.

The Store Default Global Variable

By default, a global variable created in the GLOBALS package is an instance of the Store class.

Reminder : Creating a Global Variable

To create a global variable from the Store class :

1. open the GLOBALS package window

2. double click on the upper part of the suitcase icon or [CTRL] / right click and choose OPEN

select FILE / NEW VARIABLE.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Setting the Value of a Store Object

With a Store Factory Box1. Connect the "self" output of an object to the "value" input of a store factory box.2. Evaluate the store box.

Using a Slots Box and a Store Global Variable

1. Add a store global variable .

2. Add a store slots box : [CMD] click, type "store" and press [SHIFT] while

validating.

3. Connect the "self" output of the store variable to the "self" input of the store slots box .

4. Connect any type of box to the "value" input of the store slots box.5. Evaluate slots.

Editing a Store Global Variable With the Store Editor

This variable can then be edited, from the GLOBALS window, or from a patch editor.

Double click on the icon of a store object to open its editor.

• If the value of the store object hasn't been set as described above,

the editor displays the following icon : , which means "nil". It

cannot be modified from the editor. The user must resort to the previous procedures to assign a value to this variable.

• If the value of the store object has already been set, it can be modified :

1. double click on the value icon to edit it2. validate.

Note that the editor is similar to the editor of the corresponding class.

If the store object is a global variable, the corresponding variable in the GLOBALS package and all of its representations will be affected by possible modifications.

Reminder : Renaming Variables

Remember that global variables can be renamed from the GLOBALS package of the LIBRARY window, and only from this location.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5. Iterations: OMLOOP

A great number of compositional operations, be they basic or more complex, are iterative processes. This is the case, for instance, of transposition, combinatorial manipulations, scale building, and so on.

Iteration

Iteration is the repetition of a process in order to apply it to a series of items.

Example : Transposing a Chord

Transposing a chord actually amounts to add the same value to each note it is composed of. Therefore, this process requires the iteration of an addition corresponding to the number of pitches in the chord.

Such processes can be designed in OM via a specific tool, the OMLoop module. OMLoop is a visual program that executes iterative processes. As such, it is frequently needed and may be required as soon as the user gets to the thick of things.

The OMLoop module is available in the OM KERNEL / CONTROL menu.

Widespread Use of Iteration

Simple combinatorial operations may require much more sophisticated programs as it seems, and cannot be designed without resorting to iteration.

Indeed, building a series is a basic, frequent process, which can be easily executed with a pen and a staff. But as long as we wish to systematize it, extend it, or reproduce it a number of time, we need to resort to programs possibly requiring an iteration. At the end of the OMLoop section, you will find a detailed example showing how such program can be designed and extended beyond the context of the traditional 12 semitones series. You may first want to integrate the notions presented in the OMLoop section before looking up this example.

Building a Random Series


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.1. General Features

The OMLoop module is a specific type of abstraction – or patch. It encloses a number of specialized components, which allow to program various iterative programs. Programming takes place in the internal editor of OMLoop.

OMLoop Editor and Components

Editor

To open the OMLoop editor, double click on the OMLoop box.

Components

OMLoop provides three types of programming components :

• iterators : determine and stop the iteration process.• accumulators : gather the result at each step of the iteration in the ongoing process until the iteration is over.• evaluators : trigger the evaluation and return the results, at each step or at the end of the iteration.

Evaluators are essential components which are displayed by default in the editor.

Iterators and accumulators are visible at the top of the OMLoop editor and can be added with a click. The choice of iterators and accumulators depends on the iteration program. Evaluators are added by default in the editor.

The OMLoop editor resembles a patch editor.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing


Initially, the OMLoop box has only one output and no input : programming can be done without the use

of external data, like with a patch, Additional outputs and inputs can be added using the following procedures :

Inputs

Inputs return incoming data to the programming functions of OMLoop. To add or delete inputs :

• press [ALT] + [→] or [� ]• press [SHIFT] + [>] or [<].

The inputs appear inside the module, just like in an abstraction.

Note

Inputs can't be added or deleted from inside the loop.

Outputs

The finally evaluator represents the visible output of OMLoop. It returns the results of the iteration. Outputs can therefore be added and deleted by adding or deleting optional inputs to and from Finally.

To add or delete inputs to Finally :

• press [ALT] + [→] or [←] • press [SHIFT] + [>] or [<] .

Outputsare also represented on the OMLoop icon once added :

About Evaluators :

About Evaluation

• OMLoop can't be evaluated from the inside. It will be ineffective until its internal program is defined correctly.

• Do not evaluate it before it is completed : an infinite loop might get OM stuck until 500 000 loops are completed...


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

The OMLoop editor shows additional inputs, as well as a number of default components.

5.2. Evaluators : Eachtime, Finally

OMLoop has two evaluators :

• Finally : receives and returns the results of the loop. • EachTime : produces the result at each step of the iteration.

Getting Results : Finally

Finally represents the output of OMLoop. It is evaluated when the iterative process is over and returns its final result(s).

If nothing is connected to it, the evaluation of OMLoop returns "nil".

Example

The following example uses an iterator : listloop. at each step of a loop, listloop enumerates an element of a list, then the following element, and so on, until the list is exhausted.

1. Here, there are four iterations during which listloop takes the successive values from the list.

2. At the end of this process, finally returns the current value listloop, that is, the last value of the list.

3. This value is the result of OMLoop.

Finally Inputs : OMLoop Outputs

Finally has one default input : "patch". It can be added as many optional inputs as necessary : "oppatch".

Optional inputs can be used as additional outputs for OMLoop to return data to external elements in a higher-level program.

Multiple Outputs

When an OMLoop has several outputs, it is advised to set it on Eval-once mode3 to avoid useless multiple evaluations. When the OMLoop is evaluated, the result displayed by the Listener is that of the first output.



VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Executing Operations : EachTime

EachTime triggers successive evaluations inside the OMLoop. It is not visible from the outside.

EachTime can apply to any type of operation, but the results won't be returned to other boxes or displayed, unless the user adds relevant connections.

Inputs

EachTime has one default input, and can be added a number of optional inputs. Each input calls upstream boxes, so that several tasks can be performed at each step of the iteration.

Using EachTime

Here, EachTime evaluates om+ at each step of the loop. Yet, the Listener only displays the result of Finally when OMLoop is evaluated.

Yet, EachTime plays a very important part in an iteration, since it is the only means to evaluate and keep track of the results yielded at each step of the program. This is one of the main specificities and interests of OMLoop.

The results of the operations called by EachTime can actually be displayed and returned to other boxes, inside and outside the OMLoop module.

Example

In this new example, print is evaluated at each step.

1. When listloop returns an item in the (A B C D) list, EachTime evaluates print.

2. The current value of listloop is printed.3. At the end of the list, Finally returns the last value of listloop.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Collecting the Results of EachTime

The results of the operations called by EachTime can be collected and returned to Finally with accumulators.

Example

We want to gather the results of each loop of the iteration in a list and return this list to other boxes on the outside of the module.

To do so, we use an accumulator : collect.

Collect stores the results of each loop in a list.

1. At each step, eachtimes calls :• print, which print the item returned by listloop• collect, which stores a new value.

2. At the end, Finally gets all the collected values and returns them as the result of the OMLoop.

Note : the editable-text-box displays the value of the OMLoop output.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.3. Iterators

Function

An iterative operation must be driven by an enumeration, or at least stopped at some point by a given condition.

In an OMLoop, this control is enabled by four iterators :

• Forloop • Whileloop • Listloop • Onlistloop

Iterators can enumerate items in lists, but above all, stop the OMloop once this enumeration is over. This is why a loop must always have at least one iterator : otherwise, it goes on with infinite iterations. If several iterators are used simultaneously, the loop stops as soon as one of them stops.

Adding Iterators

To add an iterator in the editor :

• click on the icon• [CMD] click and type a name.

All the following examples use the Eachtime and Finally evaluators.

5.3.1. Listloop : Enumerating the Elements of a List

General Properties

Listloop enumerates and returns the elements of a list one by one.

In other words, at each step of the iteration, listloop takes a smaller chunk of the list, and returns its first element. The execution ends once the list is exhausted.

Listloop has one default input and one optional input : • "list" : a list• "by" : a box defining the way the list is exhausted.

Here, listloop enumerates a list and returns its items one by one.

1. At each step of the loop, EachtTime evaluates collect.

2. Collect stores the items of the list.• The first input of Finally returns the last value

of the iteration.• Its second input returns the result of collect.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

"By" : Changing Enumeration Modalities

"By"

The default value of the "by" optional input is a cdr*. This means that, at each loop, listloop returns :

1. the first element of the list, 2. and then, the first element of the remaining chunk, and so on.

In Lisp, this means that listloop returns successive cadrs*.

"By" can be replaced by another function meant to return a smaller chunk of a list, such as : cddr* or nthcdr for instance. It can be either a function box on Lambda mode, or a function name.

Examples : Selecting Items to Return

If "by" is a cddr, Listloop returns

1. the first element of the list, 2. then, the first element of the cddr, 3. and repeats the operation until the list is exhausted.

If "by" is an nthcdr, listloop returns

1. the first element of the list, 2. then the first element of the nthcdr, 3. and repeats the operation until the list is exhausted.

Choosing the Right Function

Applying an irrelevant "by" argument to listloop may prevent the list from being exhausted. In this case, if no other iterator is present, the loop may go on for infinite iterations.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.3.2. Onlistloop : Enumerating Subsets of Lists

General Properties

Onlistloop returns a list and then successive smaller chunks of the list. The execution ends once the list is exhausted.

Onlistloop has one default input and one optional input :

• "list" : a list• "by" : a box defining the way the list is exhausted .

Controling Subsets Enumeration

"By"

The default value of "by" is a cdr. This means that, at each loop, the cdr of the list is returned.

This default value can be replaced by any other Lisp function meant to return a small chunk of list, just as listloop4.

Examples

Here, onlistloop successively returns smaller chunks of the list, by taking away the first element of the list : it returns cdrs.

The result of each loop is collected by collect and returned by the second input of finally.

4 - > cf "Listloop : Enumerating the Elements of a List", page 140.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

The value of "by" is switched to cddr. Onlistloop successively returns cdrs of cdrs : at each step, the two first elements of the list are left aside. Note that the first input of finally always returns "nil" at the end of the loop.

5.3.3. Forloop : Enumeration Between Two Values

General Properties

Forloop enumerates each element of a list from a minimum value – starting point – to a maximum value – ending point – by a step of 1, and stops once the maximum value is exceeded.

Forloop has two default inputs and one optional input :

• "from" and "to" : a starting and and ending vlaue• "by" : the value of the enumeration step.

Hence, forloop can only return numbers and doesn't enumerate an existing list .

Example : Inputs Properties

• The value of "from" must always be inferior to the value of "to".

• The default value of "by" is 1. It can be replaced by another positive value. If this value is negative, forloop doesn't stop, because "to" must be superior to "from".

Collect stops storing the values when the value defined by "to" is reached.

Conversely, the value returned by finally exceeds the maximum value, so that finally = "to" + "by".


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.3.4. Whileloop : Defning Iteration Conditions

General Properties

Whileloop allows a loop to go on while a condition is fulfilled.

It has only one default input : "expression", which defines a condition. This condition is expressed by a predicate* that is connected to the input of whileloop.

Example : Using Whileloop with a Predicate

We have added a list that contains numbers and letters. We want to stop the enumeration of the list if we get something else than a number.

1. The list is enumerated by listloop. Each item returned by listloop is sent to the predicate numberp.

2. Numberp tests if the item is a number, and returns "t" or "nil" .3. The result of the predicate is returned to whileloop. As long as

whileloop gets "t", the loop goes on. When numberp returns "nil", whileloop stops the loop, finally returns "done".

4. At each step of the loop, the results returned by listloop and numberp are gathered in a list, and EachTime prints the list.

5.3.5. Iterators and Infnite LoopsIf no iterator is used or used the wrong way, OMLoop gets stuck and potentially goes on forever.

Example : Generating Numbers

We want to generate four random numbers between 1 and 4.

Instead of using forloop to define the number of steps of the iteration, we have used repeat-n : OMLoop will never end and generate four random numbers an infinite number of times...

Abort Procedures

Abort Dialogue Window

An abort dialogue window pops up after 500 000 loops. To stop the iteration, choose [ABORT] , unless you have planned a very long iteration...

Abort Command

Type [CMD] + [SHIFT] + [A] to abort the ongoing calculation. OM can keep on running.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.4. Accumulators

Function

At each step of an iteration, resulting data can be memorized and stored with the OMLoop accumulators. Accumulators execute storage or other operation upon the elements they are returned successively.

There are six accumulators :

• : Collect gathers the result of each step of a loop into a list.

• : Sum returns the sum of the collected elements.

• : Min and max return the lowest and highest value among a set of collected elements.

• : Counter counts the number of non-nil collected elements.

• : Acum allows to define specific accumulation procedures.

Adding Iterators

To add an accumulator in the OMLoop editor

• click on an icon• [CMD] click and type a name directly in the editor.

Inputs and Outputs

• All accumulators but acum have a single input : this input is used for collecting the successive values during a loop.

• All accumulator have three outputs, allowing to access their current "memory" :

• first output : executes a specific operation with each new collected element.• second output : returns the current stat e of the accumulator's memory,• third output : reinitializes the memory.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.4.1. Collect : Collecting Values

Collect is the most basic collector of the OMLoop module. It collects the values returned to its input in a list.

Inputs and Outputs

Collect has one default input and three outputs :

• "what" : collects successive values coming from other boxes• first output : appends each new value returned to its input, and returns this new

element as a list• second output : returns the list of the collected elements• third output : resets the collected list to "nil", and returns an empty list.

Example : Building a Random List of Numbers

We want to make a list with seven random numbers between 1 and 100.

1. Forloop defines a number of loops. The iteration will stop after seven loops.

2. Om-random calculates a random number, which is printed at each loop by EachTime and print.

3. At each step, the successive elements are collected by collect.4. After seven loops, the iteration is stopped by forloop.5. When the iteration stops, Finally returns the list of the numbers

collected by collect.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.4.2. Sum : Calculating Sums

Sum adds the successive input values.

Inputs, Outputs

Sum has one input and three outputs :

• "what" : collects the successive values coming from other boxes.• first output :

1. triggers the collection of a new value, and the addition of this value to a sum

2. returns the current value of the sum• second output : returns the value of the current state of sum• third output : resets sum to zero.

Examples

Calculating a Sum from a List

The components of a list are returned successively by listloop to sum.

1. At each step of the loop, eachtime triggers and prints the sum of the components.2. The state of sum at the end of the loop, that is, the sum of all the components of

the list, is returned by finally.

Calculating the Sum of N Random Numbers

We now want to calculate the sum of 10 random numbers between 1 and 10.

1. The number of loops is defined by forloop.2. At each step :

• a random number is returned by om-random and printed• the sum of the successive is returned by sum and printed.

3. After ten loops, the iteration is stopped by forloop.4. Finally returns the sum of the whole set of numbers returned by om-random.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.4.3. Min and Max : Comparing Values

Min and max compare the successive values of an iteration, and return the lowest or the highest one.

Inputs and Outputs

Min and max have one default input and three outputs :

• "what" : collects successive values coming from other boxes.• first output :

1. triggers the collection and the comparison of these incoming values

2. returns the current lowest or highest collected value at each step of the loop

• second output : returns the lowest or highest value• third output : reinitializes the accumulator with the highest or lowest

possible numbers : 4294967296 and -4294967296. These are comparison references for the next values.

Example1. Listloop enumerates the numbers of a list and returns them successively to min or max.2. Each time, the new number is compared to the current value.

If it is higher – max – or lower – min – than the current value, it is stored instead of this current value.3. The current value is printed. 4. The second output of min and max returns the resulting lowest or greatest value of all the list to Finally.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.4.4. Count : Counting Items

Count is a counter. Its internal value increases at each evaluation evaluated, if the input value is non nil.

Inputs and Outputs

Count has one default input and three outputs :

• "what" : a value.• first output : triggers the increment of the counter if the input is non nil, and returns

its current value. • second output : returns the current state of the counter.• third output : resets the value of the counter to zero.

Examples

Counting the Items of a List1. Listloop returns each element of the list successively to count. These elements are

non nil values. 2. The first output of count adds 1 every time listloop returns an element. 3. Once the enumeration of listloop is over, the final state of count is returned by

Finally.

Counting Specific Items of a List

We will now apply count more specifically, to know how many strings a list contains among other types of items.

1. Listloop enumerates the elements of a list. 2. The stringp predicate returns true every time it evaluates a string. 3. At each step of the loop, the first output of count is evaluated :

• if it gets a non nil value from stringp, it increments the value of the counter

• if it gets "nil", the value doesn't change.4. The results returned by stringp and counter are gathered in a list and

printed.5. The total number of strings, that is, the final state of counter is returned by

Finally.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.4.5. Acum : Defning Accumulation Procedures

Acum is a generic module used for defining storage or accumulation procedure.

Inputs and Outputs

Contrary to the other accumulators, accum has three default inputs and one optional input :

• "acum" : collects the successive elements of a list returned by an iterator• "init" : initial value of the accumulator• "fun" : an accumulation function to apply to each collected element.• first output : 1. collects the input value and applies the accumulation function2. returns the current state of the accumulator.• second output : returns the finale value of acum.

• third output : resets the accumulator to the value specified by "init".More information about Lambda Functions :

"Init" : Defining Acum's Behaviour

" Init " actually defines the accumulator's behaviour.

It must take a function or box on Lambda mode, with two inputs :

1. one for the element to collect,2. one for the initial value.

Example : Subtracting a List of Numbers

We want to subtract numbers successively – for instance (100-8-2-3-9). For this, we need an initial value, x, a list of numbers, the om- function on Lambda mode, and acum.

The initial value of acum is 100. Om- is set on Lambda mode it is connected to the third output of acum. It is applied recursively to the elements of the list and to the initial value. We get (100 - a - b - c - d).

1. Listloop returns the successive elements of the list to acum.

2. At each step of the iteration, the first print box prints the successive current values of acum : 100 ; 100-8 = 92 ; 92-2 = 90 ; ...

3. At each step of the iteration, the second print box prints the result of the subtraction, which is then stored as the new current value of accum.

4. When the iteration is over, Finally returns the final state of acum.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

5.5. A Basic Example : Building a Random Series

We want to build a random series of fifteen notes withing a range of 5000 and 8000 midicents.

• All notes must be different, including octaves. • Intervals can consist of semitones and quartertones. • Intervals can be repeated.

Designing the Iterative Process

"Keep on Until the List Has 15 Items"

1. Om-random returns a random value within the given range. 2. At each step of the loop, collect stores the value. 3. The resulting list is returned to remove-dup, which removes equal values and octaves, give or take a

quarter tone.4. Length returns the number of items in the list. 5. This number is compared to 15 by om<. 6. The process goes on as long as the list has less then 15 items, as specified by whileloop.

Resulting Chord-Seq

The resulting chord-seq is returned to the outside of OMLoop by Finally.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

Redefning the Equality Test

Constraint : Rounded Intervals

Usually, remove-dup checks if two values are strictly equal. We have modified this predicate with a lambda patch.

Indeed, here is what happens if two pitches make almost an octave – 1200 midicents :

Test Arguments

Lambda Patch

1. The values tested by remove-dup are returned by two inputs, and substracted by om-.

2. The difference is divided by 1200 and rounded give or take a multiple of 1200.

3. It is then multiplied again by 1200 to calculate the rest of the original difference.If this value is inferior to 50, it will be rounded so that we will get an octave or its multiple in the score.

4. The absolute value of the rest is compared with 50 by om-.5. If om- returns "true", the value is rejected by remove-dup

Example

If the test is applied to 6000 and 7187 midicents – preceding values –, we get the following evaluations :

Om< returns "t", and pitches are considered equal.


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

6. Creating and Using a Pathname in a Patch

Default Directories

Default directories can store external input, output and temporary files – MIDI, SDIF or sound files, sound analysis and synthesis files, etc. These directories are selected in the OM Preferences. The default locations are the IN-FILES and OUT-FILES directories of the current workspace directory.

These storage folders can also be used in programs with the text tools presented in this section.

Creating Pathnames in Patches : Infle, Outfle and Tempfle Boxes

A file pathname to the storage directories can be entered directly in a data box, or come from another box, such as an InFile, OutFile, or TmpFile box.

To access these boxes

• select FUNCTIONS / OM KERNEL / FILE UTILS and pick a menu item• [CMD] click and type "infile", "outfile" or "tmpfile".

Each box has one default input and one keyword input.

• First input : file name and extension. It is set to "nil", if the user only wishes to get a path to a directory .• Keyword input : a list of one or more subdirectories .


VI

- A

dv

an

ce

d V

isu

al

Pro

gra

mm

ing

VII - OM Objects

This section describes how to design and use two types of objects within programs, which belong to two distinct packages : the SCORE package and the BASIC package .

Score objects basically refer to the musical categories of objects found in traditional scores, from an elementary level – the note – to a more sophisticated level – the polyphony. A description of Score editors, which offer complete edition possibilities is also provided there.

Basic objects represent a set of tools allowing the manipulation of data, such as mathematical functions, texts, and items allowing to develop an intuitive interaction with OM, like buttons, sliders, pictures, etc.

Both sections provide information about the specific tools dedicated to the manipulation, transformation and handling of corresponding objects.


1. OM Score Objects

The OM Score objects include a set of musical objects. This section describes how to manipulate, design, and use score objects within programs.

1.1. Score Classes

Score classes enclose the musical objects that compose a score : notes, chords, chord-seqs, voices, polys, measures and groups. Out of convenience, we have gathered these objects in three categories : "harmonic", "rhythmic" and "polyphonic" objects.

They can be accessed via the CLASSES / SCORE menu.

Types : "Harmonic", "Rhythmic" and "Polyphonic" Objects.1. Harmonic objects include three classes : notes, chords and chord-seqs.

2. Rhythmic objects include

• one main class : voices, • and two complementary classes : groups and measures.

3. Polyphonic objects include : polys and multi-seqs. These are "superimpositions" of objects :

• voices on one hand, • chord-seqs on the other hand.

Time Representation

These objects can be classified into two temporal categories :

• Pulsed, or rhythmic representations are based on a traditional rhythmic expression of events in time, via rhythm trees*. Voices, polys, groups and measures are pulsed representations.

• Linear representations are based on the absolute duration of events – in milliseconds. Chord-seqs and multi-seqs are linear representations.

• Notes and chords are transverse to both temporal categories.Expressing Rhythms


VII

- O

M O

bje

cts

1.1.1. Notes, Chords and Chord-Seqs

There are three harmonic objects : notes, chords, chord-seqs. Chord-seqs are successions of chords. They only include a significant temporal dimension.

• A note is a unique pitch.• A chord is a list of notes.• A chord-seq is a list of chords.

General Features

Parameters

Harmonic objects have a number of common parameters. Chords and chord-seqs have specific parameters.

OBJECTS PARAMETER INPUT NAME VALUE

All Pitch "midic" Midicents

All Dynamics "vel" 1 → 127

All Duration "dur" Milliseconds

All Timbre "midichannel" 1 → 16

Chords and chord-seqs Offset "offset" Milliseconds

Chord-seqs Onset "onset" Milliseconds

Chord-seqs Legato "legato" Milliseconds

The inputs order varies depending on their significance to the object.

A note, a chord and a chord-seq.


VII

- O

M O

bje

cts

Input Values

• Note inputs accept atoms only, that is, a simple value without parenthesis. A single pitch, and its corresponding parametric values as well, must be expressed by an atom.

• Chord inputs accept atoms and lists. A chord consisting of a single note is expressed by an atom. A chord consisting of a set of notes must be expressed by a list.

• Chord-seq inputs accept elementary lists and lists with sub lists. A chord-seq consisting of a succession of notes is expressed in an elementary list. A chord-seq consisting of a succession of chords is expressed by a list with sub lists. The elements of one sub list belong to the same chord.

• The "legato" input accepts atoms only : a single legato value is applied to all the elements of the chord-seq.

As chord-seqs rather expect sub lists, lists are converted into sub lists when outputs are evaluated.

Here, the three first values of the output list stand for distinct chords. They are converted into sub lists.

Note

The default data structure format can be checked by hovering the mouse over the inputs of a box.

Chord and Chord-Seq Specifc Features

Offsets and Onsets

Chords and chord-seq have specific parameters : "offsets" and "onsets", which can become easily confusing.

• The onset represents the position of the first note of a chord.• The offset represents the delay between this first note and

the following note(s ). A chord can "unfold" in time, with an arpeggio for instance.

Offsets are visible when opening the editor of a chord or chord-seq.

Each chord of the chord-seq has one onset, and one offset per note.


VII

- O

M O

bje

cts

Legato

A chord-seq has a supplemental input : the "legato" input. All chords have the same legato percentage. Hence, the "legato" input only accepts atoms. It is displayed in the score editor via the DURATION menu item of the editor control.

This value doesn't apply to notes or chords added subsequently via the score editor.

Displaying Parametric Values :

Chords and chord-seqs : List Structures

The list structures of each slot of a chord or chord-seq don't have to be strictly similar. Objects manipulate the lists assigned to each of their parameters to produce compatible lists.

If lists don't have the same number of elements, shorter lists are completed to fit the longest list(s) :

• by repeating the last element• by applying the same time difference to all elements, in the case of onsets.

If a list has too many elements, the last elements are suppressed.

In any case, the pitches list is the reference list.

The object returns compatible and coherent pattern.


VII

- O

M O

bje

cts

1.1.2. Rhythmic Objects

The Voice Object

A voice is a melodico-rythmic line.

Inputs and Outputs

The voice object has six inputs and outputs.

1. "self" : a voice, measure or list of measures, or a chord-seq .

2. "tree" : a rhythm tree*.

3. "chords" : a chord, broadly speaking – chord, list of chords, a list or sub lists of midicents.4. "tempo" : speed of a quarter note.5. "legato" : an overlapping percentage between two chords, calculated from the 2nd chord's duration. 6. "ties" : one sub list per chord, indicating notes to be tied to notes of same value in the next chord.

The combination of inputs programming and score edition allows a complete musical edition of the object.

Programming Rhythm Trees Basics

Ties

Ties are a specific parameter of rhythmic objects. To specify that a pitch must be tied to the next one, enter this pitch in a sub list in the "ties" input.

The rank of tied elements must match the rank of the corresponding chords or notes in the "midic" input. Otherwise, OM won't recognize the elements to be tied.

Detailed Information About Voices Edition


VII

- O

M O

bje

cts

Measures and Groups

Groups and measures are complementary modules of the Score class.

They have two inputs and outputs :

• "self" • "rhythm tree*".

They can also be isolated as distinct rhythmic elements within voice editors.

About Measures and Groups within Voices :

Uses

Groups and measures are used for :

• programming elementary rhythmic structures, which can be saved as instances or global variables for a subsequent use

• storing rhythmic structures once they have been extracted from a rhythm tree.

Getting Measures

The get-measures function returns a list of measures from a voice .

Switching the chords and rhythms of two measures using measure instance boxes.


VII

- O

M O

bje

cts

1.1.3. Rhythm TreesRhythmic objects – and polyphonic objects – integrate a rhythmic parameter, which can be programmed by the user via rhythm trees.

A rhythm tree is a list representing a rhythmic structure. This list is organized hierarchically in sub lists, just as time is organized in measures, time signatures, pulses and rhythmic elements in the traditional notation.

Hence, the expression form of rhythm trees is crucially different from that of onsets and offsets. It can be exacting and not very "ergonomic", from a musician's point of view : rhythm trees can be long, with a great number of parenthesis and sub lists nested within each others.

This section provides the syntactic and semantic principles that rule rhythm trees. We also advise the user to follow the rhythm trees tutorial provided with the OM application.

A) Structure

Traditionally, rhythm is broken up into several data : meter, measure(s) and duration(s). This information must be organized into lists and sub list.

This elementary rhythm :

can be expressed as follows :

• ( ? ( (4//4 (1 1 1 1) ) ) ) • ( ? ( ( (4 4) (1 1 1 1) ) ) )

A tree structure can be reduced to a list : (D (S)).

Main Components : Duration and Subdivisions

• D = a duration, or number of measures : ( ? ) or a number ( n ).

When D = ?, OM calculates the duration.

By default, this duration is equal to 1.

• S = subdivisions (S) of this duration, that is a time signature and rhythmic proportions.

1. Time signature = n // n or ( n n ). It must be specified at each new measure, even if it remains unchanged.

2. Rhythm = proportions : ( n n n n )


VII

- O

M O

bje

cts

Parenthesis Levels

A rhythm tree has at least three levels of parenthesis :

1. number of measures2. list of measures3. time signature and proportions.

Note that different rhythm trees with equal proportional structures produce the same rhythmic result : ( 1 1 1 1) = (2 2 2 2) = (124 124 124 124)

Durations

Manipulating Durations

By default, the duration of a measure is equal to 1. 1 represents the global measurement unit traditionally expressed by the time signature, such as : 4/4, 2/2 = , 3/8 = etc.

Changing this value multiplies or divides all the durations by a given coefficient.

Subdivisions : Measures and Groups

MeasuresTrees define the way measures are split into proportional durations.

The following rhythm : is written : ( ? ( (4//4 (1 2 1) ) ) ) .

Groups

Trees also define internal subdivisions, or groups*, within a measure.

The following rhythm : is written : ( ? ( (4//4 (1 ( 2 (1 1 1) ) 1) ) ) ) .

Writing Groups

Note that groups must be written with a new subordinate level of parenthesis.


VII

- O

M O

bje

cts

B) Notation : in Practice

Proportions

Elementary Proportions Lists

Rhythm trees can also be expressed with simple proportion lists, which ignore the duration and time signature levels. At a basic level, OM always interprets proportions according to two criteria :

• = 1• Time signature = 4/4.

This way of writing rhythm trees can lead to very interesting processes in the manipulation of temporality. A given rhythmic structure can be modified or read according to various beats patterns, by associating given proportions to more or less sophisticated functions or programs.

Integers, Ratios and Floats

Proportions can be expressed with integers, floats or ratios. Nevertheless :


VII

- O

M O

bje

cts

• A same group cannot take both floats and ratios. • Values between 0 and 1 are not accepted by rhythm trees.

In both cases, OM renders an approximation of the rhythm tree.

The MkeTree function

The mktree function allows to associate a list of proportions to a list of time signatures.

• If a list contains a single time signature, the rhythmic pattern is extended as much as required by the duration of the tree.

• If a list contains several time signatures, each time signature is valid for one measure only, so that the rhythm may remain incomplete.


VII

- O

M O

bje

cts

Rests, Beams and Ties

Rests

Silences are expressed by negative values.

Beams

Values within a group are beamed automatically.

Ties

Add .0 to create a tie with the previous note.

Dotted Values

Automatic Notation

Dotted values are "naturally" expressed by relevant proportions, in the case of "binary" time signatures – n/ 4, n/ 2, n/1 –, or elementary ternary time signatures – 3/8, 3/16.

Constraints

In other cases – 6/8 and its paradigm –, OM's behaviour doesn't always apply the conventional notation. Proportions can be expressed by an equivalent rhythmic notation, depending on the values of the rhythm tree.

• The quarter note being the default beat value, ternary notation is adapted to the use of the quarter note and its multiples. In other words, OM privileges the use of tuplets, rather than that of dotted values.

• To get dotted values in a ternary time signature, use multiples of 3 to express proportions.

Functions of the Rhythm Trees Package

A set of functions dedicated to rhythm tree is available in the FUNCTIONS / SCORE / TREES menu. For thorough information about these functions, refer the online documentation.


VII

- O

M O

bje

cts

1.1.4. Polyphonic Objects

The Multi-Seq Object

The multi-seq object allows to "superimpose" several chord-seqs.

Inputs and Outputs

Multi-seqs have two inputs and outputs.

• The first input – self – takes chord-seqs or midifiles .The second input takes a list of chord-seqs .• The first output returns the self of the multi-seq. The second output returns a list of chord-seqs .

Applications

To convert a midifile into a multi-seq :

• connect a midifile object's "self" output to the "self" of a multi-seq,• evaluate the multi-seq .

The midifile is expressed as a standard musical score, which can be accessed and modified via its editor.

You will have to select a midi file when the object is evaluated. Lock the box in order not to have to choose a file again.

Modifying Score Objects

To convert a midifile and a chord-seq into a multi-seq :

1. convert the midifile into a multi-seq,2. connect the second output of the multi-seq, and the

"self" output or the chord-seq to list .3. If the midifile has more than one voice, use flat to get a

single level list of chord-seqs.4. Connect list or flat to the second input of the multi-

seq.

Multi-Seq to Midifle

You can possibly convert the resulting multi-seq into a midifile with a simple connection and evaluation.


VII

- O

M O

bje

cts

The Poly Object

The poly object allows to "superimpose" several voices.

Inputs and Outputs

The poly object has two inputs and outputs :

• The first input – self – takes polys or midi files. The second input take a list of voices .• The first output returns the self of the poly. The second output returns a list of voices .

Applications

To create a poly out of a series of voices :

• create a list of voices with a list function, or any other type of relevant function,

• connect the list function to the second input of the poly and evaluate the box.

About Polys and Multi-Seq Editors


VII

- O

M O

bje

cts

1.2. Score Functions

A number of functions from the SCORE package are specifically designed to manipulate, import and export score objects.

1.2.1. Programming Modules Overview

Score modules are used for manipulating score objects.

They can be accessed via the FUNCTIONS / SCORE menu.

Aggregating Objects

Concat

The concat function concatenates, that is juxtaposes, two objects of the same class, or in some cases, two different objects. Applies to voice, measure, chord-seq and poly objects.

Align-Chords

The align-chords function gathers notes belonging to a same time interval in a common chord. Applies to chord-seqs .

Merger

The merger function merges – imbricates – two chord-seqs, voices or measures rhythmically, into one single voice or measure. The duration, and possibly meter of the resulting object, equals those of the longest object.

Mask

The mask function masks one voice with another when the first voice is not playing. Applies to polys .


VII

- O

M O

bje

cts

Manipulating Durations

Measure-Time

The measure-time function returns the temporal position of a marker in a midifile.

True-Durations

The true-durations function returns the duration of each event within a score object.

OM-Quantify

The om-quantify function transcribes a list of durations into a metric structure.

Extracting Objects

Get-Measures

The get-measures function returns all the measures from a voice.

Get-Chords

The get-chords function extracts a list or sub list of chords from a music sequence or superposition. Applies to chord-seq, multi-seq, poly and voice objects.


VII

- O

M O

bje

cts

1.2.2. Conversion Modules Overview

A set of conversion modules allows to manipulate midicents, frequencies and note names. They can be accessed via the FUNCTIONS / SCORE / CONVERSIONS menu.

Converting Midicents

Frequency / Midicents

The frequency-to-midicents function converts frequencies to midicents.

Its input takes atoms or lists.

The midicents-to-frequencies function converts midicents to frequencies.

Its input takes atoms or lists.

Name / Midicents

The name-to-midicents function converts a note name to a midicent value.Its input takes a string or a list of strings, like ("C3").

The midicents-to-name function converts a midicents value to a note name.

Its input takes a list of values.

Approximating Midicents to a Tempered Value

Approximate-Midicents

The approximate-midicents function approximates a midicents value to the closest tempered division of the octave.

It has two default inputs and one optional input :

• Its first input takes atoms or lists to approximate.• Its second input takes numbers or floats as a division. For instance, 4 equals a quarter tone.• Its optional input takes a reference value in midicents to calculate a tempered interval.


VII

- O

M O

bje

cts

1.2.3. Export / ImportScore objects can be stored as MIDI or musical notation files, or exported to musical edition programs directly. Reciprocally, files can be imported to create multi-seqs, voices or polys. Export and import can be done by saving an object, or by using functions of the SCORE package, which can be accessed via the FUNCTIONS / SCORE / IMPORT/EXPORT menu.

A) Export

Save Command

Exporting Voices and Polys

To export Voices and polys as MIDI, ETF* and XML* files

1. press [CMD] + [S] 2. choose a format in the dialogue window3. choose a name and a location for the file.

The OUT-FILES folder of the workspace is the default location, but you can choose any other location.

It is advised to use the XML format, which is the most widespread.


VII

- O

M O

bje

cts

Chords, Chord-seqs, Multi-seqs

Chords, chord-seqs and multi-seqs can be exported as MIDI files only.

1. Press [CMD] + [S], 2. choose a name and a location for the file.

Export Functions

Objects can also be exported, and imported via function boxes. Go to FUNCTIONS / SCORE / EXPORT, and select a box.

Export Formats

Four export formats are available in OM : ETF*, XML* and MIDI via the following functions :

The finale-export function is used for exported data directly to a .mus file, without writing any preliminary file.

The ETF format brings a number of problems, due to applications compatibility. This procedure is still unstable between Finale and OM.

The export-musicxml function is used for exporting objects as .xml files.

The save-as-midi function is used for exporting objects as midi files.

We advise you to use MIDI or XML files.

Exporting and Importing an XML File to Finale

1. Connect a voice or poly to an export-musicxml box.

2. Evaluate the box and give the file a name and destination folder.

Once the function is evaluated, the object's content is stored in the computer's clipboard to be imported by another application.


VII

- O

M O

bje

cts

You can then import the file when lauching Finale :

choose MUSICXML in the IMPORT FILE pop up menu of the dialogue window.

Importing a File from Finale1. Select the FILE / MUSICXML menu item in an open file

window. 2. Choose a location folder and a file in the dialogue window.

A new .mus file is created.


VII

- O

M O

bje

cts

B) Import

Importing Files from OM

Polys and voices can be created out of MIDI, XML and Finale files, which can be imported via the following functions or factory boxes :

As seen previously5, multi-seqs can be created out of MIDI files.

Importing an XML File from the Workspace

1. Connect the "self" input of a voice or poly to an import-musicxml function.2. Evaluate the box.

3. Choose a location folder and a file. OM opens the OUT-FILES as a default folder.

A new score object is created.

Exporting XML and ETF Files from Finale

XML files can also be imported from Finale to the IN-FILES folder or any other folder of the computer, via the FILE / MUSICXML / EXPORT menu, and then imported to a patch as described previously.

Nevertheless, some features, such as the size or markings can make the file too heavy to be imported, or have OM stuck.

To import a MIDI file, evaluate a MIDI-FILE object, choose a location folder, and a MIDI file.

5 - > cf "Polyphonic Objects", page 166.


VII

- O

M O

bje

cts

1.3. Score Editors

1.3.1. Interface

Score editors allow to visualize, listen to, modify, or create instances. Each score object – note, chord, chord-seq, voice, poly – has a specific score editor. Editors open with a double click on a factory box.

Score objects are organized in a simple hierarchy with growing levels of complexity, like in a matriochka. From the note to the poly, the panel of score editors shows a growing number of editing tools. All editors follow the paradigm of the note editor.

Windows Overview

The editor window opens along with a general palette, and a score inspector .

It shows a number of pop up menus, which allow to modify the displaying of the score, and an Editor Control on the lower left corner, dedicated to editing operations.


VII

- O

M O

bje

cts

The displaying and parametric values of a note object can be controled directly via its editor.

Score Inspector

The score inspector gives access to all the related data of a selected object, which can then possibly be modified.

The score inspector appears automatically at the selection of an item.

To display the score inspector, select the WINDOW / SCORE INSPECTOR menu.

Modifying Parametric Values via the Editor Control

General Palette

The general palette is declined over the set of score editors. It provides :

• edition tools : note, chord, group, measure, voice and poly tools,• a player • and two selection cursors .

The selected edition tool is displayed as small tag when hovering the mouse over the score :

Objects and Edition Levels

Edition Tools Overview

Each of these levels can be accessed via dedicated edition tools.

TOOL APPLIES TO EDITORS

Note notes – within chords – all editors

Chord chords all editors but note editors

Group rhythmic groups within measures voice and poly editors

Measure entire measures within a voice voice and poly editors

Voice one or more voices at once voice and poly editors

Poly a whole stack of voices at once poly editors

Example

The poly object integrates all edition levels : note, chord, group, measure, voice .


VII

- O

M O

bje

cts

1.3.2. Preferences

The basic settings of the score editors can be modified via the SCORE EDITORS tab of the PREFERENCES pane. To

access the SCORE EDITORS preferences, select the OM.6.X.X / PREFERENCES menu, and click on the score

icon. These default parameters can be modified subsequently if needed, via the score editors themselves.

Displaying Options

The score editors preferences give access to a set of musical displaying parameters.

Default Scale Approximation

Three default scales are offered by OM :

• semitones• quarter tones• eighth tones.

Other scales, from the tone to the sixteenth of tone are available via the editors menus.

Choosing a Scale :

Music Font Size

The music font size affects the size of the whole score, like a vertical zoom.

Staff Configuration and Colour

A great number of staff configurations, based on F and G clefs combinations, is offered in the preferences.

A specific staff colour can be be selected via the Colour Chooser.


VII

- O

M O

bje

cts

Dynamics

The standard midi dynamics scale can also be adapted to the user's specific needs, via the "Dynamics" frame.

Tonal Display

The "Tonal Display" frame offers a number of options, which are dedicated to tonal music notation.

About Tonality :

Score Display

Displaying Information

Pop Up Menus

Pop up menus are mainly used for modifying the score displaying and player options :

• FONT SIZE – adjust the font size to your convenience.

Use the Zoom to adjust the horizontal spacing of notes.

• STAFF – number of staves and G or F clefs.

• APPROX – division of the octave, from the tone to the 1/16th tone.

Each scale has an adapted accidentals notation system.Microintervals Notation

• PLAYER – offers a standard midi player, and a microtonal playing interface.To display the play menu, stretch the editor window to the right. You can then choose a sound interface and an output port.

Midishare and Microplayer


VII

- O

M O

bje

cts

The note editor menus and controls.

Editor Control Menu

The EDITOR CONTROL pop up menu allows to select and visualize each of the parametric values attached to an object.

• To display the corresponding value of an object, pick one option.

The midic parameter is selected by default, and the note is displayed permanently. This value can now be modified.

Staves Confguration

Non Polyphonic Objects

The staves configuration of notes, chords, chord-seqs and voices can be modified via a simple selection in the STAFF pop up menu.

Polyphonic Objects

The staves configuration of polys and multi-seqs can be modified to the whole object's scale, or to selected items scale.

• To apply a configuration to a specific item,;click on the clef of a staff and select a configuration in the STAFF pop up menu.

• To apply a configuration to each element, don't select any staff and choose a configuration in the menu.Editors Displaying Parameters

> cf "Preferences", page 177.

Multipe Staves Confgurations in Polyphonic Objects

All score objects, but note objects, offer multiple staves configurations – GG, FF, GGFF etc. –.

These configurations do no allow single staff manipulation : staves form groups which cannot be splitted for edition purposes .

Colour

Midi Channel

To change the note colour according to its midi channel, press [C]

Note Colour

To change the colour of a note :

1. press [SHIFT] + [C]2. select a colour in the Colour Chooser.


VII

- O

M O

bje

cts

1.3.3. Basic Editing

Edition applies to all score objects. The Palette offers a set of edition tools, adapted to each of these objects. The Editor Control is the main edition interface of the editor window. The Score Inspector window also allows a number of editing operations.

Accessing Parameters

Selecting the Right Item : the Palette

The palette displays a player in its upper part, and edition tools in its lower part.

To edit an item, select the relevant edition tool.

Inspector Window

A non exhaustive set of parameters can be accessed via the INSPECTOR window .

The INSPECTOR window appears once an item is selected, and displays related parametric values.

To modify a parameter :

• Select a frame and scroll the mouse up or down to increase or decrease the values.

• Add [CMD] to change the value by steps of 10, or [SHIFT] to change the value by steps of 100.

Editor Control Menu and Frame

The editor control allows a thorough edition of each slot, as shown below. It shows one or two menus and an adjacent numeric frame.

Editor Control : Selecting and Editing Slots

Pitch

There are three ways to change the pitch of a note. The MIDIC menu item must be previously selected.

• "Manually" : select an item and move it with the mouse.

• To raise or lower the pitch from the staff, use the [↑] or [↓] keys .

Add [CMD] to transpose the note from a perfect fifth.Add [SHIFT] to transpose the note from an octave.


VII

- O

M O

bje

cts

• To change a pitch from the Editor Control Frame, click on the value displayed in the numeric frame and scroll the mouse upwards or downwards.

Add [CMD] to change the value by 100 midicents steps.Add [SHIFT] to change the value by 1000 midicents steps.

Double click in the frame and type a value.

Velocity – Dynamics

1. Choose DYN in the editor control. The dynamic is displayed under the note.2. Click on the note and scroll the mouse to increase or decrease the velocity value.

Add [SHIFT] to change the value by steps of 10.Add [CMD] to switch from 0 to 127.

Duration

Choose DUR in the pop up menu. The duration is expressed by a plain line. There are two ways to change the duration of a note.

• Click in the numeric frame and scroll the mouse to increase or decrease the duration value

• Use the [←] and [→] keys.

Add [CMD] or [SHIFT] to change the value by steps of 100 or 1000 milliseconds.

MidiChannel

The OM midi interface has 16 midi channel.

1. Choose CHANNEL in the pop up menu.2. Click in the adjacent frame and scroll the mouse to increase or decrease the duration

value.

Add [CMD] or [SHIFT] to switch from 1 to 16.

Port

255 audio ports are accessible.

1. Choose PORT in the pop up menu.2. Click in the frame and scroll the mouse to increase or decrease the duration value.

Add [CMD] to change the value by steps of 100Add [SHIFT] to change the value by steps of 10.


VII

- O

M O

bje

cts

1.3.4. Player

The player of the editor palette includes several standard commands.

Playing Modes

Play Selection

This command allows to play a selection within an object.

1. Select the cursor .

2. Add a marker or select a region in the score editor.

3. Click on the play selection command : the player will either play the object from the marker to the end, or the selected region.

Play Loop

This command allows to play a selected region repeatedly.

1. Select a region with the cursor.

2. Click on the loop and play commands.

Record

This command allows to record any sound from a midi device.


VII

- O

M O

bje

cts

1.3.5. Harmonic Objects : Note, Chords and Chord-Seqs EditorsNotes, chords and chord-seqs constitute a hierarchy, whose note objects are the simplest level, and chord-seq objects are the highest level of complexity. Hence, remarks regarding the note editor are also valid for chord and chord-seq editors, and those regarding chords are of course valid for chord-seq editors.

A) Editing Pitches

The tools of the editors palette define several hierarchic edition levels.

Note tool - to edit selected notes.

Chord tool - to edit whole chords.

Voice tool - more specifically dedicated to the voice object, can apply to a whole chord-seq .

A whole object can be selected with a click and drag in any case .

Adding Notes and Chords

Adding Notes in Note and Chord Objects

• In note objects :

1. select the note tool2. [CMD] click in the score.

The default or current value of the object is modified.

• In chord objects :

1. select the chord tool or the note tool2. [CMD] click in the staff to add a note.

Adding Notes to a Chord in a Chord-Seq

Chords can be edited in the chord-seq editor, or in an INTERNAL CHORD window.

• To edit a chord from a CHORD-SEQ window :

1. Select the chord tool and [CMD] click on the chord : a grey note appears at the root of the green-framed chord.

2. Change its pitch with the [↑] or [↓] keys.3. Click in the editor window to validate.


VII

- O

M O

bje

cts

• To edit a chord in an INTERNAL CHORD window :

1. Select the note or the chord tool. 2. Double click on the chord : the INTERNAL CHORD window pops up.3. [CMD] click on the staff to insert notes in the chord.

Adding Chords in a Chord-seq

Adding Chords in a Chord-seq

1. Select the note, chord or poly tool.

2. [CMD] click in the staff.

Deleting Items1. Select the note, chord or poly tool, depending on the type of items you

want to delete.

2. Select one or more items and press [BACKSPACE].

Extracting Chords

Chord factory boxes can be dragged out of any type of score editor – but the note editor.

To create a factory box :

1. select the chord tool in the editor palette6

2. click on an item and dragg it to the patch editor.

It is materialized as a factory box.

Score Editors

> cf "Interface", page 175.

6 - > cf "Basic Editing", page 180.


VII

- O

M O

bje

cts

Group / Union Chords

The group and union chords commands allow to gather several chords into one chord.

1. Select the items you want to group or union.

2. Press [*] to group chords.

Press [+] to union chords.

On Chord mode, chords are displayed the same way with both commands.

Group Chords

The group chords command allows to preserve the individual offsets of the chords.

• Pitches are played successively.• The Offset mode of the Editor Control shows the actual offsets of each

chord.

Union Chords

The union chords command gathers several chords graphically and temporally in a same chord.

• Pitches are played simultaneously.• The Offset mode of the Editor Control shows that all chords have the same

offset.

Displaying Modes

Features

The EDITOR CONTROL menu allows to modify the displaying of chords. Notes can be ordered according to their :

• pitch : Arp up and Arp down modes• order in the pitches list : Order mode• offset : Offset mode. A small vertical line marks the starting point of the chord.


VII

- O

M O

bje

cts

The order and offsets of the pitches in the list can be expressed via the Order and Offset modes of the Editor Control.

B) Editing Other Slots

Displaying Modes

Features

The editor control upper menu gives access to each slot of the object.

The displaying of a slot value can be combined with displaying mode of the lower menu.

Edition

Chords : Duration, MidiChannel, Dynamics

The duration of one or more selected note can be modified with the same procedures as for notes.

1. Select the DURATION menu item.2. Select the note tool.3. Select one or more notes and change their parametric value :

• use the [� ] or [� ] keys • type a value in the editor control frame.

Chord-Seq : Offsets

The chords onsets in a chord-seq can be modified from the second chord.

1. Select the chord tool.2. Use one of the following procedure :

• drag and drop the item(s) • use the [� ] or [� ] keys : the offset value is decreased or increased by 100 milliseconds steps. • add [SHIFT] to change the value by 1000 midicents steps.

Modifying the offset of a chord "manually".


VII

- O

M O

bje

cts

Legato

To display the legato value of notes in a chord-seq, select the DURATION menu item in the editor control.

Reminder : Pitch

Modifications can apply to notes, or to whole chords or chord-seqs .

1. Select the tool corresponding to the item you want to transpose.

2. Transposing can be done : • with a drag and drop• from the staff's scale : [� ] or [� ] keys,• from the midicents scale : click in the editor control

frame and scroll the mouse upwards or downwards, or type a value.

Grid• To display or hide a grid in the editor, press [G] .• To adjust an item to and its duration to the grid, select it and press [A] .

The duration change is effective if the initial duration value is close to that of the grid's step.

To change the grid's step, press [SHIFT] + [G] .

To move the item or change its duration according to the grid's step, press [SHIFT] + [� ] or [� ] .


VII

- O

M O

bje

cts

1.3.6. Rhythmic Objects : Voice EditorThe voice editor palettes shows a number of additional tools, which define hierarchic edition level.

Group tool - rhythmic groups within measures of the sequence.

Measure tool - entire measures within the sequence.

Voice tool - seen before, more specifically dedicated to the voice object whole voice at once.

Consecutive pitches are considered as chords. This must be taken into account for choosing the appropriate tool in the palette.

Entering Chords and Notes

Adding and Deleting Measures

• To add measures in a poly :

1. select the measure tool in the palette,

2. [CMD] click on the left or on the right of the pre existent measure. in the palette

• To delete one or several selected measures, press [BACKSPACE].

Converting Silences into Notes

Once created, a measure displays a whole pause. You can either :

• turn this pause into a whole note, and then split it into other values,

• split this pause into shorter values first, and split it into other values.

To convert a whole pause into a whole note and back, select the measure tool , select the measure and press [ESC].

To split a silence or a note into a group of equal values :

1. select the chord tool ,

2. select the item,3. enter a number.

Adding Notes to Chords

Select the note or the chord tool and [CMD] click on a chord.

If you didn't click right on the chord, the note is framed in red. Use the [� ] and [� ] keys to reach the desired chord and press [ENTER].


VII

- O

M O

bje

cts

Manipulations

Chords

To tie successive chords, press [=]. To untie them, press [/] .

Groups

• To get a group :

1. select a chord2. enter a number to split it into smaller equal values.

Individual chords cannot be grouped from the voice editor.

• To break an existing group :

1. select a group with the group tool

2. press [-].

Durations

To merge successive chords into one longer chord :

1. delete all existing ties,

2. select several chords with the chord tool, and press [+] .The duration of the resulting chord is equal to the sum of the merged chords.

Move Staff

To move a staff up or down :

1. select it by clicking on the clef2. use the [� ] [� ] keys.

Staff, Voices and Measures

To apply modifications to a whole voice or measure, select the voice tool or the measure tool . Some modifications may not be relevant. Groups cannot be broken over a whole voice, for instance. Note that if a voice has several staves, a selection with the voice tool applies to the whole group of staves.


VII

- O

M O

bje

cts

Transposing an entire voice.

Groups

Groups are represented by beams or by small vertical lines.

To break a group :

1. select the group tool, 2. select the group to break,

3. press [-].

If several groups are nested into each other, they are broken from the main level to the secondary levels.

Groups and Rhythm Trees Syntax

Reminder : Groups and Rhythm Trees

Groups are written as sub lists.

Here, the first sequence has one eighth notes group, the second sequence has no group.

Modifying Groups From the Rhythm Tree Input

Groups cannot be created from the editor. If you modify a rhythm tree after editing the other parameters of a voice, all parameters are reset to their default value when evaluating the object.


VII

- O

M O

bje

cts

The second mesure of the first voice shows three groups levels nested within each other.

1.3.7. Polyphonic Objects : Polys and Multi-seqs Editors

Common Features

A poly and a multi-seq objects are a superimposition of voices or chord-seqs .

They both have one additional tool : the poly tool , which allows to edit all voices at once.

Add / Delete Staves

• To add a staff :

1. select the voice or the poly tool ,

2. to add a new staff, [CMD] click on a staff.Notice that new staves are automatically added above the "lower" staff .

• To delete a staff :

1. select the voice tool,2. click and drag a staff

3. press [BACKSPACE].

Respacing Staves

As in voices editors, staves can be moved up of down, and consequently, respaced.

To respace staves :

1. click on the clefs of the staves you want to respace

2. use the [↓] [↑] keys.

Internal Voice or Chord-Seq Edition

To open a voice or a chord-seq as an internal object from a poly or a multi-seq :

1. select the voice tool,2. click and drag a staff to select a voice or a chord-seq,

3. press [O], or double click on it.


VII

- O

M O

bje

cts

Individual Chord-Seq and Voice Staff Confguration

To define clefs individually :

1. click on a clef

2. choose a configuration in the STAFF pop up menu.

Remember that multiple staves configurations – e.g. FF, GF, GGFF etc. – do not allow individual staff editing or respacing.

Poly Editor and Multi-Seq Specifc Features

Poly : Polytemporality and Polymeter

Within a poly, each voice can have its own time signatures, channel and tempo, so as to build polytemporal and metric structures. The score is then organized according to absolute durations.

• To change the tempo or midichannel of a voice :

1. select the voice2. enter a value or scroll the mouse up

or down in the voice inspector.• To change the meter of a measure :

1. select it with the measure tool 2. enter values in the measure inspector.

Multi-Seqs : Internal Chord-Seq Edition

Within a multi-seq, chord-seqs must be open in internal windows to be edited separately.


VII

- O

M O

bje

cts

1.3.8. Page Mode

The content of objects can be displayed and edited – to a certain extent – on page mode. This is especially convenient as far as long sequences are concerned. The page mode is also very convenient to get a preview of an object and modify its page layout before printing.

Displaying Pages

Accessing Page Mode

To display a content on page mode

• select PRESENTATION / PAGE in the main menu• [CTRL] / right click in the editor to access the contextual menu.

Page Size

The number of displayed pages can be modified via the PAGE SIZE menu.


VII

- O

M O

bje

cts

Margins

To modify the page margins :

1. [CTRL] / right click in the editor.

2. Select the PAGE LAYOUT menu item in the contextual menu.3. Enter margin values

4. Select [DEFAULT] or [CANCEL] to restore the default page margins or to cancel the values you entered.

5. Press [OK] to validate.

Margins values are also effective on NORMAL presentation mode.

Parameters Displaying and Edition

Legibility : Slots and Score

Parametric values can also be displayed via the usual upper and lower Editor Control menus.

Font size and zoom can be adjusted via the usual menus.

Parametric Values Edition

Slots cannot be edited. Notes and chord can be moved or deleted, but new pitches cannot be entered in the score.

Print

To print the score :

• select FILE / PRINT in the main menu • press [CMD] + [P] .


VII

- O

M O

bje

cts

1.3.9. Player Options

MIDI / Audio

To select a player interface, choose an item in the PLAYER pop up menu.

Midishare

The Midishare interface allows to select an output port : click on the adjacent ......

button.

Select a port in the dialogue window.

Microintervals

The Microplayer interface allows to play microintervals.

1. Select the MICROPLAYER menu item and wait for the application to start up. 2. The Microplayer window opens. No additional edition is necessary.


VII

- O

M O

bje

cts

The microplayer interface.

1.3.10. Tonal DisplayTonal display options concern all musical objects with possible tonal harmonic or melodic progressions : chord-seqs, multi-seqs, voices and polys .

Tonality

Editor Preferences

The EDITOR PREFERENCES tab provides a number of options and tools, which relate to tonality expression and analysis.

Tonality Dialogue Window

To choose a tonality

1. select the editor and press [T]. 2. A tonality dialogue window pops up.

3. Select the MINOR or MAJOR mode in the pop up menu, and a key signature via the < and > buttons. 4. The tonality is indicated on the upper left corner of the editor, as well as a conventional key signature.

To restore the original "atonal" configuration, press [SHIFT] + [T] .

Enharmony

OM automatically assigns the expected accidentals, depending on the chosen tonality. Accidentals can though be modified enharmonically.

To modify an accidental :

1. select the note tool, 2. [CTRL] click on a note and select an item.


VII

- O

M O

bje

cts

Editor Scale

The default accidental notation system in score editors uses sharps. This system can be modified, to a certain extent.

The EDITOR SCALE window offers a limited number of enharmonic accidentals, based on the standard twelve semitones notation.

This especially makes sense when using a tonal or modal semitones scale pattern.

To specify a scale

1. select an editor and press [S]. 2. The EDITOR SCALE Dialogue window opens. 3. Choose [EDIT].

To assign an enharmonic accidental to a note, [CTRL] / right click on it and select a menu item.

Modifications of the default scale are displayed by the dialogue window.

Click on [DEFAULT] to reset the default scale.

Cadences, Degrees and Figuring

An elementary tonal analysis tool is implemented in musical editors. It is based on the options provided in the EDITOR PREFERENCES :

• degrees • cadences • figuring

The analysis takes place as chords are being edited, provided OM can recognize a listed chord and chord progression.


VII

- O

M O

bje

cts

Modulation

Specifying Modulations

Modulations can be specified textually in the score editor.

1. Select a section in a score and press [T].2. Choose a tonality.

Boundaries

OM displays the modulation but it doesn't automatically adapt the key signature or accidentals to the new tonality.


VII

- O

M O

bje

cts

1.3.11. Microintervals Notation

Conventions

Scales

OM offers all scales approximations from 1/2 to 1/8 tone, as well as 1/10, 1/12, 1/14 and 1/16 tone approximations.

Accidental Types

All accidentals are ascending, that is, based on naturals and sharps.

Microintervals and Tonality

Microtonal scales are not available in a tonal context.

To cancel the choice of a tonality, press [SHIFT] + [T]. The original "atonal" configuration is be restored.

Accidentals Chart

Note

Scales that don't comprise semitones – 1/3, 1/5, 1/7 and their derived scales can be tricky, for they sometimes have different types of accidentals.

Notation Principles

Naturals are replaced by plain vertical lines – for instance : . Incrementations of sharps are indicated by two vertical lines – for instance : .

• 1/4 tone scale : the number of vertical lines indicates incrementations of 1, 2 or 3 quarter tones – for instance .

• 1/8 and 1/16 tone scales : three different arrowheads indicate incrementations of a 1/16th , 1/8th and 3/16th tones of naturals and sharps.

• 1/3 tone scale : incrementations of 1 or 2 thirds of tone are shown by the number of additional horizontal lines – for instance .

• 1/6 and 1/12 tone scales : they combine arrowheads with horizontal lines.

• 1/5, 1/7 tone scales and their multiples : they use additional combination of horizontal lines.


VII

- O

M O

bje

cts

1/2 Tone and Elementary Multiples

1/3 Tone and Elementary Multiples

1/5 and 1/10 Tone

1/7 and 1/14 Tone


VII

- O

M O

bje

cts

2. OM Basic Objects

The OM Basic Objects include a set of tools designed for the manipulation of basic data, and a set of extended visual programming tools such as text and pictures, file reading/writing modules, etc.

2.1. Functions Package

These objects refer to mathematical functions. As both classes and functions belong to the FUNCTIONS package, this might be slightly confusing. To avoid misunderstandings, we strictly refer to bpfs, bpcs, or curves to mention objects of the package.

2.1.1. 2D Objects : Bpf / Bpc

OM offers two types of objects for the manipulation of 2D curves and functions :

the bpf and bpc objects – break point function* and break point curve .

Properties

Defnition

A bpf is an y = f(x) function in the mathematical sense, with inscreasing x-values.

A bpc is a free curve defined in a 2D plane.

The FUNCTIONS package contains a set of classes and functions designed to create, edit and manipulate curves, also called Break Point Functions and Break Point Curves. These can be accessed via the BASIC TOOLS / FUNCTIONS menu.


VII

- O

M O

bje

cts

Inputs and Outputs

Bpf and bpc objects have four inputs and outputs :

1. "self" : as in every object box, represents the object instance itself – bpf or bpc

2. " x-points" : abscissa, a list of positive or negative numbers 3. " y –points" : ordinates, a list of positive or negative numbers4. "decimals" : the approximation or step value of the points, a

number of decimals.

Creating a Bpf or Bpc in a Patch

The bpf or bpc points can be set by connecting lists of values to the "x-points" and "y-points" inputs, or with the bpf/bpc editor.

X-Points Order in Bpfs

In a bpf, x-points must be in a strictly increasing order.

If the list is decreasing, the points will be created from the y-points values and sorted automatically before the actual bpf is created.

Incomplete Coordinates Lists

Incomplete Coordinates Lists

If the x or y list is shorter than the other, the last interval in the shorter list is repeated until the right number of points is reached.

This allows for instance to create a bpf with a list of y-points and a periodic x interval.

Decimals and Bpf/Bpc Precision

The " decimals" input determines the number of decimals per coordinates, that is, the precision of the curve.

Coordinates are therefore rounded according to the number of decimals.

If "decimals"= 0, all coordinates are rounded to the closest integer.


VII

- O

M O

bje

cts

2.1.2. Multiple Curves : Bpf-lib / Bpc-lib

Bpc-lib and Bpf-lib objects are collections of bpfs and bpcs.

Properties

Bpf -libs and bpfc-libs have two inputs and outputs :

1. "self" : the object itself, a bpf-lib or bpc-lib.2. "bpf / bpc list" : a list of bpfs or bpcs.

Creating Bpf-libs or Bpf-libs in a patch

Bpf -libs and bpc-libs instances can be created

• out of existing bpfs or bpcs gathered in lists.• via their respective editors.

Abscissa Scale

Both axis scales are adapted to the smallest "decimal" value of the bpf or bpc objects of the list.


VII

- O

M O

bje

cts

2.1.3. Bpfs and Bpcs EditorsBpfs and bpcs editors are globally similar with a few specificities. Out of simplicity, and to avoid confusions with OM function boxes, we refer to both functions and curves within editors as "curves".

A) Edition Basics

Double click on a bpf or bpc to open the editor. The editor opens along with a palette. This palette has a number of edition tools, which allow to add, delete and manipulate points within the editor.

Adding / Deleting Points

The following operations are performed with the pointer .

Adding Points in a Bpf

To add points on the object, [CMD] click in the editor window at the desired point position.

Note that the coordinates of the pointer are displayed in the upper part of the editor window.

The bpf editor and the edition palette.


VII

- O

M O

bje

cts

Adding points in a Bpc

In a bpc, points can be added anywhere in the x / y plane, so that the new points are automatically inserted at the end of the points list .

To add a point between two existing points, click precisely on the curve segment.

Delete

To delete points :

1. select a region of the object

2. press [BACKSPACE].

Moving Points

Moving Points Manually

The location of one or several points can be modified manually :

• with a click and drag• with a selection and the [� ] keys.


VII

- O

M O

bje

cts

Editing Coordinates

To access and edit the coordinates of a point :

1. double click on it,2. enter values in the dialogue window.

Note : floats are truncated depending on the object "decimals" parameter. If "decimals" = 0, coordinate values are rounded to the closest integer.

Moving the Whole Object

To change the position of a curve within the editor's surface :

1. select the curve tool

2. click and drag the object in the editor.

Extra Edition

Colour

To change the colour of a curve :

1. select the item and press [C],2. select a colour in the Colour Chooser.

Assigning specific colours to curves may be especially useful in bpf and bpc-libs, which can have several bpfs and bpcs.

Multiple Curves


VII

- O

M O

bje

cts

B) Display Tools and Options

Curve and Points

Show / Hide Points

Show / Hide Line

The LINE option is selected by default. To display points only, unselect this option.

Closed Bpc

Bpc editors have an additional option : the CLOSED BPC option. This option allows to connect the first and last point of the curve, in order to get a polyhedron.


VII

- O

M O

bje

cts

To display or hide the points of a curve, click on or outside it.

View

Browsing the Editor

To browse the editor's surface :

1. select the hand tool ,

2. click and drag the mouse in the editor.

Zoom In / Out, Resize

To zoom in a region of a curve :

1. select the zoom tool ,

2. click and drag a region.

To fit the window to the object size, click on the rezise tool .

Zooming in a bpf.


VII

- O

M O

bje

cts

Rulers and Grid

Grid

To display a grid in the editor, select the GRID option. The grid's step is adapted automatically to the window size and to the axis scale.

To change the editor's scale, click and drag the abscissa or ordinates axis. The adjustment limits of the abscissa ruler depends on the value of the "decimals" input.


VII

- O

M O

bje

cts

Displaying a grid in a bpf editor.

Spline Display

Spline Curves

Splines are mathematical functions defined piecewise by polynomial interpolation. They are used for generating smoothed interpolated shapes, starting from a set of control points. Some functions in OM allow to generate spline curves starting from the points of a bpf or bpc.

To display the preview of a spline curve computed from the bpf/bpc, check the SPLINE display option.

Parameters• The spline's resolution represents the number of points to compute in the spline preview. • The spline's approximation degree determines the number of adjacent control points used for computing the

spline curve points. Higher values produce smoother curves.

To modify the spline resolution or degree :

1. click on the DEGREE or RESOLUTION frames2. scroll the mouse up or down to change the value.


VII

- O

M O

bje

cts

Displaying the spline of a curve.

C) Bpf-lib / Bpc-lib Editors

All the information provided in the bpf and bpc Editor section also apply to bpf-lib and bpc-lib editors.

Editing Curves

Items Selection

All editing operations can be performed upon one curve only. Edition procedures are similar to those used in bpf or bpc editors.

To switch from a curve to another, press the [TAB] key.

• The selected curve is displayed in the foreground. Its name or index appears at the top of the editor.• The other curves are displayed in the background with dashed lines.

To show or hide background curves, select or unselect the BACKGROUND option.

Adding Curves in Bpf-lib or Bpc-lib Editors

Adding Bpfs

To add a curve in a bpf-lib editor :

1. select the pointer tool.

2. [SHIFT] + [CMD] click in the editor.• The existing curve(s) switch to the background and

are displayed with dashes. • The new curve is at the foreground.

3. To edit the new curve, [CMD] click in the editor to add a first point in it.

Hidden Curve

If you haven't edited the first curve, the new curve is superimposed to it at the foreground. To visualize the new curve, select the curve tool and move the line.


VII

- O

M O

bje

cts

Selecting a curve and hiding the background.

Adding Bpcs

Contrary to bpfs, which initially come with two default points, bpcs come empty.

• To add a first bpc :

Select the pointer and [CMD] click twice in the editor to create a curve. Two points at least must be added in the editor to make each new bpc visible.

• To add a second bpc :

1. [SHIFT] + [CMD] click outside the line to switch the first curve to the background.

2. [CMD] click twice in the editor to add the new curve.


VII

- O

M O

bje

cts

2.1.4. Bpf and Bpc Tools OverviewA number of function boxes, allow to build or manipulate bpfs and bpcs. To access bpf and bpc tools, go to FUNCTIONS / BASIC TOOLS / FUNCTIONS.

A) Getting Coordinates

Selected Coordinates

Getting Xs from Selected Ys : Transfer

Transfer returns the ordinates for given abscissa.

Transfer has two inputs and one output :

• "self" : a bpf . • "x-val" : a number or a list.• Its output returns a number or a list.

Getting Ys from Selected Xs : Y-Transfer

Y-transfer returns the abscissa values corresponding to given ordinates. It applies to bpfs and bpcs as well.

Y-transfer has three inputs and one output :

• "self" : a bpf or a bpc.• "y-val" : a number or a list.• "n" : defines a number of decimals for the values to be returned.• Its output returns a number or a list.


VII

- O

M O

bje

cts

Curves and Samples

Paires

Paires takes the whole curve and returns paires of abscissa and ordinates corresponding to each point of the curve.

Paires has one input and one output :

• "self" : a bpc or bpf. • Its output returns a list of x-points and y-points.

Getting Ys from a Bpf Sample : Bpf-sample

Bpf-sample selects a chunk from a curve and samples it n times to return a list of ordinates. Sampling occurs at a regular frequeny, whose step is equal to "xmax" / "nbsamples".

Bpf-sample has four inputs and one output :

• "self" : a bpf.• "x-min" : a number, the starting point of the sample.• "x-max" : a number, the ending point of the sample.• "nbsample" : a number of samples. • Its output returns a list of ordinates.

Getting Ys from a Bpc : Bpc-sample

Bpc-sample selects the whole curve, and returns a list or ordinates. Sampling occurs at a regular frequency.

Bpf-sample has two inputs and one output :

• "self" : a bpc.• "nbsample" : a number of samples. • its output returns a list of ordinates.


VII

- O

M O

bje

cts

B) Manipulating Objects

Defning Functions

Sampling Functions : Sample-Fun

Sample-fun applies a mathematic function over a given numeric interval, samples the resulting curve at a given frequency and returns the corresponding values. A bpf or bpc can be materilalized out of the sampled values.

Sample-fun has two default inputs and outputs :

• "function" : a function Lisp name, such as "sin" for "sinus", "exp" for "exponantial"... The default value of "function" is "sqrt",for "square table".

• "step" : a sampling frequency number.• the first output returns the sampled values• the second output can be connected to a bpf or bpc.

It has three optional inputs :

• "xmin" and "xmax" : a sampling range.• "coeff" : a multiplication coefficient for the sampled values.

Linear Functions : Linear-fun

Linear-fun defines linear y = f(x) functions. It can be used as a lambda-function.

Linear-fun has four inputs and one output :

• "x0" and "y0" : coordinates of the first point.• "x1" and "y1" : coordinates of the second point.

Its output can be connected to :

• a bpf or bpc• the sample-fun function as a lambda function.

Manipulating Existing Functions

Interpolation: Bpf-get-val

The bpf-get-val function interpolates bpfs or bpcs with one or several values.

The bpf-get-val function has two inputs :

• "bpf / bpc" : self value of the object• "val" : a single value or a list, including the coordinates of another bpf or bpc. • Its output can be connected to a bpf or bpc.


VII

- O

M O

bje

cts

Spline : Get-spline-obj

Get-spline-obj materializes a bpf or bpc out of a spline.

The get-spline-obj has three inputs, which resembles the parameters of a bpf spline, and one output :

• "self" : a bpf or bpc• "resolution" : a number• "degree" : a number between 1 and 8, although the spline degree remains limited. • Its output returns the value of a new bpf or bpc.

Spline : Get-spline-points

Get-spline-points extracts the coordinates of all the points of a spline.

The get-spline-points function has three inputs and one output :

• "self" : a bpf or bpc.• "resolution" : a number.• "degree" : a number.• Its output returns a list of coordinates.


VII

- O

M O

bje

cts

2.2. Array

The class-array is an original tool for the manipulation of arrays, that is, matrices* and other bidimensional data structures.It is specifically designed to support description data such as parameters for sound synthesis control. This section shows how to design, edit and manipulate arrays.

2.2.1. Class-Array ObjectThe class-array box is accessed via the CLASSES / BASIC TOOLS / DATA STRUCTURES / CLASS-ARRAY menu.

Properties

Columns and Lines

The class-array box has a number of columns, called "components" and a variable number of rows or lines, called "fields".

Default Inputs and Outputs

The class-array box has two default inputs and outputs

• "self" : an object or a list of objects • "numcols" : a number of components or columns .

Keyword Inputs

The class-array can be added a number of keyword arguments, which represent the fields of the matrix.

Each keyword input has a corresponding output.


VII

- O

M O

bje

cts

Rows and Columns

Use and Definition

Each column represents a component .

Each line or row in the matrix display represents a field. A filed corresponds to one of the keyword arguments.

• Each line contains field values. Values are entered in the corresponding keyword input.

• Field values are assigned successively to each component of the matrix. This means each cell has a specific value.

• Fields can be added by the user with the [K] keys, just like keyword arguments in OM function boxes. To delete a field, press [SHIFT] + [K] .

• Fields can be defined as slots of the class-array subclasses.

They can then be hidden or shown with the [>] or [<] keys.

Slots / Subclasses

The class-array is designed to be used as a superclass for array classes with default fields.

Subclassing can be done in Lisp code or visually in OM – see Object Oriented Programming. Examples of class-array subclasses are the classes from the OMChroma system for the control of sound synthesis.

Keyword Inputs Name and Value

By default, keyword inputs – additional fields – are called ":k1", ":k2", etc... To modify these names :

1. click on the input.2. enter a name starting with ":"

The value of keyword inputs must come from a connected box.

Keyword Inputs Instantiation

Instanciation

The class-array has an original and powerful instantiation system, which interprets the input data connected to its different filed inputs automatically. If needed, input data is converted to generate and fill all the components values internally, depending on the given number of columns.

Applying a List of Values

1. The list fits the number of components. The items contained in each list are assigned to the successive components.

2. If the number of items is superior to the number of components, the list is repeated.


VII

- O

M O

bje

cts

Applying a Single Value

A single value is repeated for every component of the array.

Example 1 : Resampling Bpfs

A bpf can be resampled according to the number of components of the class-array. Hence, each component can be assigned a value, no matter how many points the bpf has.

This class-array contains eight components, or columns.

• The bpf is the second field of the class-array .• Eight points are sampled in the bpf and assigned to the second line of the

class-array .

Note that using the "x-points" or "y-points" instead of the "self" output of the bpf amounts to feeding the array with a list of value.

Example 2 : Applying Functions

If a function or a box on Lambda mode is connected to a field of the array, it is applied to the components of the field at the evaluation.

Here, arrays n° 1 and 3 are instantiated with two functions :

1. the sinus function is evaluated for n = 1 to 30, that is, for each component's index.

2. The om-random box in "lambda" mode defines a function that returns a random number between 0 and n, where n = the component's index.


VII

- O

M O

bje

cts

If necessary, values are repeated.

Creating Arrays with Objects

Objects Lists

Objects, such as notes, chords, or any object in OM, can also be used for filling the matrix fields. These objects must be returned in a list.

This procedure allows, for instance, to create arrays of arrays .

Advanced Issue : Row Types

In class-array subclasses, the type of a subclass field may change the way the interpretation of input data.


VII

- O

M O

bje

cts

2.2.2. Class-Array Editor

The class-array editor allows to visualize and edit – to a certain extent – the contents of a class-array object.

General Features

In the class-array editor, rows are represented by a set of horizontal panes. These panes can be :

• bpf -like views, if the component values are numbers • list views, if the components are other types of objects or values .The following values can be displayed at the top of the editor by hovering the mouse over a component :

• the number of the current component • the values related to this component for each of the fields, such as coordinates, if values are available.

Displaying Options and Confguration

Palette

To zoom in/out on a selected region – a components subset – : use the and buttons of the palette.

Options

• To display or hide the lines of bpfs, check the LINE option.• To apply a global grid to the editor, check the GRID

option.• To show or hide the user-defined field, check the SHOW

OPTIONAL FIELDS option.

All the fields of a simple class-array are user-defined. Consequently, all the rows of such arrays are hidden if this option is unchecked. Subclasses of class-arrays with "predefined" fields may remain visible.


VII

- O

M O

bje

cts

A class-array editor.

Rows Configuration

Each row can be hidden or shown with a click on the triangle icons located on the upper left corner of each pane.

• To save, recall or remove a given configuration, use the [+] and [-] buttons at the bottom of the editor.

• To select a configuration, use the adjacent POP UP MENU, which contains all available or recorded configurations.

•

Edition

Bpf-Like Rows

Bpf-like rows offer some of the possibilities of bpf editors :

• hiding / showing lines• moving points, in order to change the value(s) of the corresponding components.

Points cannot me removed.

List Rows

List rows display the contents of every components, with various types of representations depending on the type of data.

Objects with an editor – bpfs, score objects, arrays, etc.– can be open by a double click and edited individually.

Limits of Array Editors

A big array may not represent all of its internal component values, in which case the internal components display may be automatically disabled.


VII

- O

M O

bje

cts

2.2.3. Class-Array Tools OverviewThe values of array components can be manipulated with a set of functions. Some functions also allow to add components to an array.

These functions are available in the FUNCTIONS/BASIC TOOLS/DATA STRUCTURES menu. Their conception is still in progress.

Uses

These tools are especially designed for advanced sound synthesis control applications such as the OMChroma project. These applications aim to extend and complete components at synthesis time, as a post processing operation. They might not be very useful in other cases as far as we know.

Returning Values

The get-comp function returns the value of the nth component of an array. It has two inputs and one output.

• "self" : takes a class-array.• "comp-number" : takes a component number.

The comp-list function returns a list of values belonging to the fields of a component. It has one input and output.

• "self" takes the value returned by get-comp.

The comp-field function returns the value of the nth field of a given component. It has one input and output.

• "self" takes the value returned by get-comp. • "line-id" takes a line reference – string or number.


VII

- O

M O

bje

cts

Example

• Get-comp returns the value of the second component, or column, of the class-array.• Comp-list returns the list of values belonging to the second column : a chord and two ordinates.• Comp-field returns the value of the first field, or line, corresponding to the second column : a chord.

Remember that numbering starts at 0, consequently, 0 = 1st element, 1 = 2nd element...

Defning Values and Components : Preview

The fill-comp function sets – "fills" – or changes the values of a component.

The new-comp function allows to create a new component.


VII

- O

M O

bje

cts

2.3. Text File Tools

Texts, as well as musical or numeric data can also be created and manipulated in OM. The TEXT FILE package offers several tools dedicated to text files.

The textfile object and the FileBox tools allow to handle text files and files input and outputs. The infile, outfile, or tempfile boxes can be associated with these to create filepath names7 .

2.3.1. Textfle Box

The textfile box represents a text buffer in a visual program. It can be

• internal to a patch – by default• attached to an external file of the computer.

Textfile boxes are accessed via the CLASSES / BASIC TOOLS / TEXT FILE I-O / TEXTFILE menu.

Editing a Text via the Editor

The textfile box has a basic editor where texts can be edited or modified.

Double click on the box to open the editor.

Inputs and Outputs

The textfile object has four inputs and outputs :

1. "self" : the object itself2. "exp-list" : a textual content3. "eval-mode" : text presentation format, that is, a

text, a data list or a list. 4. "ed-mode" : edition mode, that is, the way contents

are added in the file.

7 - > cf "Creating and Using a Pathname in a Patch", page 152.


VII

- O

M O

bje

cts

Exp-List : Contents

The "exp-list" input and output represent a textual content. The "exp-list" input accepts :

• single items – strings, numbers, etc.• lists, whose each item represents a new line in the textfile .

It allows to set or read the contents of the textfile box within visual programs. The implementation and interpretation of the content depends on the "eval-mode" and "ed-mode" inputs settings.

Ed-Mode : Writing at Successive Evaluations

The "ed-mode" input determines the way input data is written in the text file with successive evaluations.It offers two options :

1. "supersede" : any previous contents is overwritten by new input data.2. "append" : new input data is append after the existing contents.

Hence, the results of several successive iterations can be stored in the text buffer. Click on the input to select an option.

Left, "supersede" : each evaluation reinitializes the textfile contents. Right, "append" : the previous contents is kept in the textfile.


VII

- O

M O

bje

cts

Eval-Mode : Writing Format

The "eval-mode" input determines the format of the contents returned by "exp-list".

Three formats are available :

1. "text" : returns a list of strings corresponding to the successive lines of the text.

2. "data list" : returns a list of the items matching each line of the text buffer, interpreted as "raw" data.

For instance, numbers are returned as plain numbers lists, (1 2 3)... instead of strings lists ("1 2 3"). Several items on a line are gathers in the same list.

3. "list" : returns an elementary list ignoring line returns.

Outer Environment

Importing / Exporting Contents

The contents of textfile can be imported or exported from / to a real file on the disk.

To import or export a contents :

1. [CTRL] / right click on the textfile box

2. choose IMPORT CONTENTS FROM FILE or EXPORT CONTENTS TO FILE in the contextual menu

3. choose a file and directory in the dialogue window.

The imported file appears in the textfile box and in the buffer

Text Format

The extension of the exported instance must be added by the user.


VII

- O

M O

bje

cts

Attachment to External Files

Other options allow to attach the object permanently to an external file on the disk.

• To fill textfile with the contents of a persistent file, select IMPORT AND ATTACH FILE.

• To save the contents of textfile in an external file, select EXPORT AND ATTACH FILE.

These option are alike "Import" and "Export" options, but the link the content of the object with a file on the hard drive of the computer.

In the dialogue window, choose a name and a directory for the new file.

• To remove a link with an attached file, select FREE ATTACHED FILE. This option is only available if the textfile is already attached to a file.

Once the attached file is "freed", contents of the textfile is internalized in the patch.

To modify an attached file :

• input data via the "exp-list" input.• use the text editor, and press [CMD] + [S] to store the modifications

in the box.

Saving the object implies that the related file on the hard drive is modified as well.

Externalizing Contents

Contrary to the import and export options, the ATTACH option implies that the textfile object itself refers to a persistent file. Hence, its content won't be stored int the patch itself.

• Parallel modifications of the attached file will affect the textfile box's content.

• If the attached file is deleted of moved, it won't be found when reloading the patch. The textfile is then empty.


VII

- O

M O

bje

cts

Inputting and Outputting Files

Initialization

To initialize a textfile with a file :

1. enter the name of a file in the "self" input of an infile, outfile or tempfile box2. connect the output of the box to the "self" input of the textfile box.

The textfile is then attached to the corresponding file.

About Pathnames

> cf "Creating and Using a Pathname in a Patch", page 152.

Returning Pathnames

A textfile box can also be convenient to visualize the results returned by boxes that return pathnames. The corresponding file must be created previously.

The editsco function from the OM2Csound userlibrary writes a text file – a Csound score – and returns the file pathname.


VII

- O

M O

bje

cts

2.3.2. File-Box : Iterative File Input/Output Processes

The File-Box is an extension of OMLoop used for programming iterative processes while controlling file reading and/or writing operations. These operations can be executed with several functions from the Text File I/O package.

To access these functions, [CMD] click and type a name or select a menu item in the BASIC TOOLS / TEXT FILE I/O menu.

A) Introduction to the File-Box

Programming with the File-Box takes place in an internal editor, which resembles the OMLoop editor. This editor has a few additional features : the StreamFile tool and the InitDo box. Like OMLoop, it is evaluated from the outside.

Iterations : OMLoop


VII

- O

M O

bje

cts

Connate Elements

Functions of the Text File I/O Package : Writing and Reading

A number of functions of the package are used for writing or reading files in the Text-Box.

• The file-write function writes something in a file. •

The file-read-line function reads one line in a text file.

• The file-write-line function writes something in a line. •

The file-eof-p function reads a text file whose number of lines is unknown.

To access these functions, go to FUNCTIONS / BASIC TOOLS / TEXT FILE I/O.

StreamFile : a Pointer to Read and Write Files

The StreamFile box represents a file pointer, that is :

• an access to a file on the computer drive• a position in the file.

It is an indispensable element for the File-Box : it is required to read from a file, or write to a file.

• Several StreamFile boxes can be used in a File-Box, if several files must be read or written at the same time.

• A StreamFile box is added by default in the File-Box editor.

To add another StreamFile box, click on the icon in the upper right corner of the window.

Using Connate Functions

Initdo

The Initdo module resembles the Eachtime module. It performs an action before the iteration starts.

Using Initdo in Iterative Processes


VII

- O

M O

bje

cts

B) Writing and Reading Files

StreamFile : a Pointer to Read and Write Files

Connections

The StreamFile box must be attached to a file via its pathname8. It has one input and one output :

• "pathname" : an outfile, infile or tmpfile box9, which return a pathname.• its output returns a pointer used for reading or writing.

Actions and Formats

The properties of the StreamFile can be edited if needed.

To open the STREAMFILE PROPERTIES window, double click on the box.

• Three options are offered a the top of the window : READ / WRITE, WRITE, READ.

• The FILE TYPE pop up menu offers two file formats : text or SDIF.

File Options

The FILE EXISTS pop up menu offers four options, which apply to an existing targeted file.

Each of these four options determine the way the program behaves when the text file is open or created to access its contents.

This behaviour results from the position of the pointer and the choice of a destructive or non destructive action.

• "Rename" : the existing file is renamed and a new file is created.• "Supersede" : the existing file is superseded; that is, a new file with the same name as the old one is created.

The previous file is deleted.• "Overwrite" : the file is modified according to the position of the file pointer. For instance, if an existing file

contains ten lines, and that the new data represents three lines, the three first lines of the existing file are replaced.

• "Append" : the new data is added after the ending of the previous content of the file.

8 - 9 > cf "Creating and Using a Pathname in a Patch", page 152.

9 - > cf "Creating and Using a Pathname in a Patch", page 152.


VII

- O

M O

bje

cts

Writing Contents

File-Write

The file-write function writes something in a file.

It has two inputs and one output:

• "line" : the text or data to write in the file, • "stream" : a targeted file to write in, that is, the

streamfile box within the File-Box.• Its output returns the text of the first input.

File-Write-Line

The file-write-line function is similar to file-write, but adds a line return at the end of the input data.

To add several lines at the end of the file, an iterative process must be introduced in the program. Most of the time, each iteration triggers one operation in the File-Box loop.

Write 1001 times in the file – loop from 0 to 1000


VII

- O

M O

bje

cts

Reading Data from a File

File-Read-Line

The file-read-line function allows to read one line in a file.

It has one input and one output :

• "stream" : a stream returned by streamfile.• Its output returns a text line.

When all the lines of the text are exhausted, file-read-line returns "nil". Lines can be read one by one. Most of the time, each iteration triggers one operation. In this case, the successive lines can be stored with an accumulator such as collect, as in an OMLoop.


VII

- O

M O

bje

cts

Reading and collecting the contents of the six first lines in a file – loop from 0 to 5.

File-Eof-p

"Eof" stands for "end of file", "p" for "predicate".

The file-eof-p function is a predicate, which allows to read a whole file whose number of lines is unknown. This function tests if a streamfile is at the end of the file.


• "stream" : a stream returned by streamfile.• Its output returns "t" or "nil".

It can be associated with whileloop and OMIF, which execute a specific operation when the end of the file has been reached.


VII

- O

M O

bje

cts

C) File-Box Features : Designing an Iterative Process

All the common loop tools – iterators, accumulators – can be used in the File-Box.

Getting Results : Finally

Just like in an OMLoop, the Finally box allows to return something as a result of the iteration.

Example : Returning a Pathname

Pathnames can be returned at the end of a process, which is quite convenient when writing a file.

• On the left, Eachtime calls file-write-line three times to write three lines of string.

• On the right, Finally returns a pathname.

The file can be accessed and used in a program.

Here, the file pathname allows to load and visualize the written file in a textfile10 object.

10 - > cf "TextFfle Box", page Erreur : source de la référence non trouvée.


VII

- O

M O

bje

cts

InitDo : Performing Initial Operations

The InitDo box is called internally, just after the filestream has been initialized, and before the iteration starts. It allows to perform initial operations, such as writing a "file header", as in this example.

Example : Writing a Header

The data printed by InitDo is visible in the text file like any other data.

Eachtime : Repeating an Operation

Eachtime allows to execute an operation at each step of the loop. can be used for writing data in the file at each step of the loop.


VII

- O

M O

bje

cts

Here, an Initdo module has been added to the program, so that a text header is added before the strings.

Example : Writing Several Lines of Strings

• At each step, file-write-line writes a line containing "hello" in the file. The path to the file is given by streamfile and outfile.

• The operation is iterated ten times, as defined by forloop. • On the other hand, Finally returns the pathname.

The text file can be visualized in a textfile box.

File-Box inputs

File-Box inputsThe content of the file and other parameters – the file pathname for instance – can be set in higher-level programs and abstracted as inputs of the File-Box.Inputs are added or removed like in OMLoop boxes : press [ALT] + [→] or [←].

Here, File-Box writes a text file that contains ten lines with "hello". The internal program of FileBox allows to add a header to the text, and a number to each line.


VII

- O

M O

bje

cts

• On the left, the "pathname" input returns a pathname to Finally and Streamfile.

1. The pathname is returned to file-write-line functions. 2. File-write-line returns a header to Initdo, which executes the operation before the iteration starts.

• The second file-write-line writes the content of the text file with the boxes located on the right.

1. The "list" input returns a list with ten "hellos".

2. Listloop enumerates each "hello". Each time, count gets "true" and returns the number of the step. 3. String+ concatenates this number, ":" and "hello". 4. Eachtime writes a line containing the resulting string in the text at each step of the loop.

The pathname returned by Finally can possibly be displayed in a text-edit-view-box. The content of the text displayed in the textfile box shows :

• the header printed by Initdo• the lines printed by Eachtime.


VII

- O

M O

bje

cts

2.4. Dialog Items

Dialog items are used as side elements for the execution of programs. They allow advanced user interactions, such as triggering operations, choosing options or items, displaying results etc., by mirroring "standard" user interfaces – buttons, pop up menus or sliders.

2.4.1. Dialog Items General Features

To access dialog Items, go to CLASSES / BASIC TOOLS / INTERFACE BOXES / DIALOG ITEMS.

Displaying of the Dialog Items Interface

Miniview

To display the actual interface of a dialog item, apply the same procedure as for displaying a miniview.

Select a box and press [M].

Appellation : Displaying and Editing the "Text" Argument

To display the message entered in the first input, evaluate the box.

To change the value of the "text" argument :

1. click or [SHIFT] click on the first input to edit it – don't forget to validate,2. select the box again with a click and drag : the box can't be selected with a click because of its interface.

3. evaluate the box : press [V].


VII

- O

M O

bje

cts

Move and Resize

Constraints

When the miniview is activated, dialog items cannot be moved or resized with the mouse : any action would actually trigger or modify the value of the box.

Items can be moved and resized without the mouse, to a certain extent :

1. drag the item,

2. use the [� ] keys – use [SHIFT] to go faster

Press [I] to restore its standard size.

Note that this last operation amounts to selecting the element(s) represented by the dialog box.

Hiding the Miniview

To move or resize the object with the mouse, hide the miniwiew :

1. drag an item to select it without clicking on it,2. hide the dialog item by pressing [M] again.

2.4.2. Text BoxesDialog items include two types of text boxes :

• t ext-edit-view-box • editable-text-box.

Text boxes allow to input or visualize a text in a visual program.

Features

Inputs and Outputs

They have one input and output :

• "text" input : a string* or something to display• "text" output : returns the current text in the box.


VII

- O

M O

bje

cts

Use

Text boxes are convenient tools for the visualization of intermediate results returned by boxes.

Their content is updated automatically at each evaluation.

Content

1. The content of the editable-text-box has to be limited to a single line : line returns, as well as tabulations, are not accepted.

2. The content of the text-edit-view-box can have several lines. Line returns and tabulations accepted.


VII

- O

M O

bje

cts

Evaluation

Locked Box

Text boxes must be locked not to be reinitialized and return their current content at the evaluation.

To lock a box, press [B] .

"Locked" Label

Some locked dialog boxes show a small grey mark on their upper left corner.

2.4.3. Selecting and Triggering Actions : Pop Up Box

Features

The pop-up box resembles the items-list boxes :

1. it allows to select items of a list in a pop-up menu interface2. it triggers a computation corresponding to a selected item.

Inputs and Outputs

The pop-up box has two inputs and outputs :

• "items" : a list of menu items• first output : returns the number corresponding the selected

item.• " action" : an action to perform, represented by a lambda

function or lambda patch• second output : returns the name of the menu item "corresponding" to the action.

For instance, "piano" can mean "play a piano sound".


VII

- O

M O

bje

cts

Setting the Menu

• To display the box's interface, evaluate the box and press [M] .

• To choose an item in the pop up box :

1. edit the menu item names via the standard procedure – edit the first input, select the box and evaluate.

2. If necessary, press [I] to refresh the displaying of the pop up menu.

3. To preserve the size of the box, press [B] to lock it.4. Click on the desired item.

Selected Item Value• The first output returns the number of the selected item. Note that the first menu item is equal to 0. • The second output returns the value of the selected item as text.

Uses

Tip : Selecting Files

The pop-up box can be useful for selecting files in a folder.

1. The infile and outfile boxes are designed to return a directory pathname to the files contained in the IN-FILES and OUTFILES folder of the current workspace.

2. Connect the output of the box to the first output of the pop up box : the menu items stand for the files contained in the folder.

You can possibly type the directory pathname directly in the first input of the pop up box.


VII

- O

M O

bje

cts

Using a directory to initialize the menu contents.

Selecting an Argument and Triggering an Operation

The second input of the menu can be used for selecting an argument and triggering an operation. This input must be connected to a function or a box on "lambda" mode with one input or argument.

This lambda function is called when an item is selected. The value of this item is the number returned by the first output. It is the argument of the function.

To set or modify the function associated with the menu, connect a box or function to the second input of the menu box, then evaluate the menubox .

A Musical Application : Choosing and Listening to a Sound

• The first input of a pop up box is connected to a text-edit-view box that contains a list of midi channel names. When the first output of the pop up box is evaluated, it returns a number that refers to a midi channel.

• The second input of the pop up box is connected to a lambda patch that is designed to play a corresponding sound when a sample is selected.

In the lambda patch, the sequence function evaluates two values successively :

1. program-out picks a midi channel according to value of its first input .2. player plays a note with the chosen midi sound.

The action programmed in the patch is executed when an item is selected in the pop up box.


VII

- O

M O

bje

cts

2.4.4. Controlling Operations : the Check Box

Features

The check-box object resembles a predicate. If the box is checked, it returns "true". If not, it returns "nil". Hence, it can be used as a "switch on / off condition" for the execution of programs. Hence, it must be associated with conditional boxes that will call the programs.

Inputs and Outputs

The check-box object has one input and one output :

• "text" : a statement• the output returns "t" or "nil".

Editing the Statement

To change this statement :

1. click or [SHIFT] click on the first input to edit it and validate,

2. select the box again with a click and drag,3. evaluate the box.

Uses

Wherever the box is clicked, it is successively checked or unchecked. Depending on its state, the box output returns "t" or "nil".

Using Conditions in a ProgramFor a Musical Application


VII

- O

M O

bje

cts

2.4.5. Controlling Values (2) : List Selection Boxes

Features

Dialog items include two list selection boxes :

• single-item-list-box • multi-item-list-box .

List selection boxes allow to select one or several items among a list, return and use it/them in downstream computations.

They have one input and one output :

• "item" input : a list of atoms or strings• the output returns the selected item(s).

To set the content of a box :

• click or [SHIFT] click on the box's input,• enter a list of items in the argument's data box.

When evaluated, the box returns the selected item.

Note that inverted commas are not compulsory.

Boxes

Single-Item-List-Box

The single-item-list-box allows to select only one item at a time.

To select an item,

1. press [B] to lock the box,2. click on an item.

Multi-Item-List-Box

This box allows to select one or more items, which are returned as a list. The multi-item-list-box is edited and used as as single-item-list-box .

• To select consecutive items or all the items of the box, [SHIFT] click on the items or click and drag them.

• To select independent items, [CMD] click.

Default Item

By default, the first item is selected and reset :

• when the box is assigned a new list of items,• if the box is not locked.


VII

- O

M O

bje

cts

A Musical Application : Building a Triad

The "chord builder" patch creates a minor or major triad, with three types of interface boxes : the multiple-items-list-box, the button-box, the check-box.

• On the left, the BUILDBUILD NOTENOTE!! button box calls a series of boxes :

1. Two list-boxes allow to choose the name of a note, from A to G, and an octave index, from 1 to 5.

2. A list containing the resulting reference is created with three lisp functions and returned to n->mc*, which returns a midicents value to a note box.

• On the right, the BUILDBUILD CHORDCHORD!! button box calls another series of boxes :

1. The MINOR check box is checked.It returns "true" to OMIF, which returns 300, the midicents value of a minor third. If it isn't checked, OMIF returns 400, the value of a major third.

2. The value of the initial note is added with 300 and 700 to build a minor triad, via two om+ boxes.3. The resulting values are gathered by x-append into one single list and returned to a chord box.


VII

- O

M O

bje

cts

2.4.6. Controlling Values (1) : Slider Box

Features

The slider box allows to select a value within a given range.

It has five inputs and outputs :

1. " direction " : the slider's vertical or horizontal orientation.

2. " range " : slider range, from a minimum to a maximum value.

3. " step " : the precision of the slider – should be equal to 1.

4. " initial value " : initial position of the slider.

5. " action " : an action to perform by a lambda function or patch.

Settings

Completing the Slider's Setting

To complete the slider's setting :

1. enter values in the inputs data boxes2. evaluate the box

3. lock the box afterwords to avoid resetting the values at subsequent evaluations.

"Direction" Input

Note that the slider orientation might not be taken into account if it is incompatible with the box's size. A horizontal slider can be "resized vertically".

Slider's Value(s)


VII

- O

M O

bje

cts

The slider's outputs give access to the values of the slider box. In particular, the fourth output, or "value" output, returns a value corresponding to the current slider position.

Using the "Action" and "Value" Inputs

The "action" input of the slider can be used for triggering an operation that will integrate the "value" input, that is, the slider's position, as a parameter.

The "action" input must be connected to a function or a box on "lambda" mode with one input or argument.

When the slider is moved, this function is called with the value of the "value" input as argument.

To set or modify the function associated with the menu :

1. connect the box or function to the fifth input,2. evaluate the slider box .

A Musical Application

• The "range" input takes midi values from 48 to 72 – C3 to C5.• The "step" value is equal to 1, so that each step of the slider corresponds to a semi-tone.• The "initial value" of the slider is equal to 48, the lowest pitch of the range.• The patch on "lambda" mode is a very simple program that applies the slider's value to the pitch input of the

send-midi-note function. When the slider is moved, the note played by send-midi-note matches the value of the slider.


VII

- O

M O

bje

cts

2.5. Graphics

The picture box is used for manipulating the illustrative elements of a programs, possibly via a dedicated editor.

2.5.1. Picture

The picture box is used for representing and using pictures in a patch. It allows to create simple graphics in OM patches. It can be edited an added figures and sketches.


• "self" : another picture box• its output returns the reference of the picture.

Initializing the Picture Box

To add a picture in the picture box, follow the procedure described in the Resources section.

1. Evaluate the box : a dialogue window opens, so that the picture box can be initialized with a picture file.

2. Choose a picture in one of the RESOURCES FRAMEs.

Pictures can possibly be added or deleted via the[+] and [+] buttons of the USER RESOURCES FRAME.

3. Choose [CANCEL] to cancel your choice or [OK] to validate your choice.

4. Lock the box in order to preserve the chosen pictures at the next evaluation.


VII

- O

M O

bje

cts

To add a picture box into a patch, select CLASSES / INTERFACE BOXES / PICTURE.

Select the box and press [M] to display the current picture and additional graphics.

The Picture Chooser Dialog Window

Load / Remove Picture

To load or remove a background picture in the object editor, go to EDIT PITCH / LOAD PICTURE - REMOVE PICTURE.

Background Pictured and Graphics

Uses

Using the graphics of a picture box as a background picture is very convenient to document or augment your patches with additional information – arrows, rectangles, etc.

Setting Picture Boxes to Background

To turn a picture box into the background picture of a patch :

1. [CTRL] / right click on the picture box,

2. choose PICT2BGK in the contextual menu.

The background picture fits the current size of the box.


VII

- O

M O

bje

cts

Switching Background Pictures to Picture Boxes

Background pictures can also be turned into boxes.

1. Press [Y] to select a background picture. If several background pictures are located in a patch, press [Y] successively to select the desired box.

2. [CTRL] / right click on it and choose MAKE BOX in the contextual menu

This is a convenient way for modifying and resizing a picture.

2.5.2. The Picture Editor

The picture editor allows to edit the contents of the picture object and to add figures or sketches.

Tools and Options

Adding Graphics : Palette Adding Graphics : Palette

The palette provides a seven drawing tools, in addition to the standard selection cursor :

: the "pen" tool allows free drawings.

: "line" tool

: "arrow" tool

: "square / rectangle" tool

"circle / ellipse" tool

"polygon" tool

"text" tool

Double click on a picture box. Its editor opens, along with a drawing palette .


VII

- O

M O

bje

cts

Click and draw in the editor to create –additional graphics in the picture editor.

Text Tool and Polygon Tool

TEXT TOOL

POLYGON TOOL

1.

Click somewhere in the editor then type some text.

1.

Click in the editor to add points.

2.

Click again to validate. 2.

Double click to validate and close the polygon.

Editor Options

The lower part of the editor provides drawing options :

• : click on the coloured patch and choose a colour in the Colour Chooser.• SIZE pop up menu : select a number of pixel for lines thickness.• LINE pop up menu : plain or dashed line style.• FILLED : check the option to fill figures automatically.• A : font dialog window.

Commands and Menus

Selection / Remove

To remove all the graphics from the editor, select EDIT PICT / REMOVE ALL GRAPHICS.

Move

To move a selected item in the picture, drag and drop it with the pointer.

Reminder

The EDITOR COMMAND KEYS are available via the HELP menu.

• To select a foreground item and to switch from an item to the other within the editor, press the [TAB] key. The name of this item is visible in the upper right corner of the editor's window.

• To remove a selected item, use the [BACKSPACE] key.


VII

- O

M O

bje

cts

VIII - Maquettes

A maquette is an object, which represents both a musical "container*" and a visual program.

In a maquette, objects can be manipulated according to temporal and graphical parameters. This includes :

• the graphical and temporal organization of objects,• the calculation of objects, which can then be connected together to interact like in a patch,• the calculation of the maquette's temporal structure.

A maquette contains specific boxes : TemporalBoxes, which have a number of characteristics :

• a reference, that is, an instance, a patch, or another maquette contained in the box,• a position and duration characteristics, which refer to the integration of the box in the maquette's context.• a "musical value ", produced in the maquette's context.

To a certain extent, the maquette can be considered a patch.


1. Creating a Maquette

Like patches, maquettes be used as autonomous programs, or within other patches and maquettes, like blue and red patches. Consequently, OM also offers two types of maquettes :

• general maquettes :

• internal maquettes :

General Features

General and Local Maquetttes

General maquettes can be :

• added in a workspace and used as main programs.• dropped and used in a patch, like an abstraction.

Local maquettes can be added directly into a patch like an internal abstraction.

Using Maquettes in Other Maquettes

Maquettes can also be used within other maquettes, according to similar principles :

• an existing maquette can be dropped and used into another maquette.• a maquette can be created directly within another maquette.

Conversions

Last, like blue and red patches again, general maquettes can be converted into local maquettes, and vice-versa.

Creating General Maquettes

Procedure

General maquettes are equivalent to standard blue patches. Like them, they can be created in the workspace, or one of its folders.

To add a maquette in a workspace :

• select FILE / NEW MAQUETTE • press [CTRL] click and choose NEW MAQUETTE in the contextual menu• press [CMD] + [2]

Maquette Files

General maquettes are persistant files that can be manipulated like patches. They can be :

• imported and exported from a workspace• duplicated and renamed• used in other maquettes and patches.

Managing Items in the Workspace

> cf "The Workspace Window", page 31.


VII

I -

Ma

qu

ett

es

Using Maquettes inside Patches

Using a General Maquette in a Patch

Once a maquette is added in a workspace, it can be dropped in a patch, on the same basis as an abstraction : like a "global" abstraction, or blue patch, the maquette keeps it original reference, which means any modification will affect all of its representations.

Adding an Internal Maquette in a Patch

Internal maquettes are the equivalent to internal – red – patches .They can be created inside a patch.

To add a maquette in a patch :

• [CMD] click and type "maquette" in the editor • [CTRL] / right click and choose MAQUETTE in the contextual menu.

Converting Maquettes

General maquettes can be converted into internal maquettes, and reciprocally, internal maquettes can be converted into global abstractions.

• To convert a general maquette into an internal maquettes, select it and type [A].

• To convert an internal maquette into a general maquette, drop it from the patch into the workspace, or one of its folders.

Patch Conversion Procedures

> cf "Conversions", page 89.

Using Maquettes inside Other Maquettes

This use of maquettes mostly sets forth a number of specificities dealing with the use of TemporalBoxes*.

Creating and Using Objects within Maquettes

Saving a Maquette

To save a maquette :

• press [CMD] + [S] • choose FILE / SAVE • [CTRL] / right click in the maquette and choose LAST SAVED in the contextual menu.

The LAST SAVED command allows to reset the maquette to its last saved version.


VII

I -

Ma

qu

ett

es

2. TemporalBoxes

The boxes used within maquettes are called TemporalBoxes.

References

A TemporalBox can refer to several types of items :

• an instance :

• a patch :

• a maquette :

Uses

Using TemporalBoxes as Programs

TemporalBoxes can be used in a maquette for manipulating data, like mere programs. In this case, data is returned to and from TemporalBoxes through standard inputs and outputs .

The program of the TemporalBox can implement its relation to the maquette's context via a temporal input .

Using TemporalBoxes as Musical Objects

TemporalBoxes can also be used in a maquette for producing a musical value, like musical objects, which are played in the maquette. This musical value is expressed by a temporal output.


VII

I -

Ma

qu

ett

es

2.1. Adding TemporalBoxes in a Maquette

Patches and other maquettes can be included in maquettes, as well as instances or factory boxes such as notes, chords, chord-seqs, voices, audio files, midifiles, MIDI controlers.

Adding Boxes From a Patch

Instances

Patches and Maquettes

General and local patches or maquettes can be dropped in a maquette editor from the workspace or any other location. A reference to the patch, or maquette, is then created. Adding a maquette into another maquette allows the conception of temporal hierarchic structures.

• If the master patch is a general patch , a reference to the patch is created.• If the master patch is a local patch , a new independent reference patch is created.

TemporalBoxes and Maquette Appearance

Factory, instance boxes and global variables can be droppped from a patch to a maquette editor. When an object is dropped in the maquette, a TemporalBox appears in the maquette. Its reference is the new factory or instance which is created from the current value of the object.

This maquette contains a patch, a factory and an instance box.


VII

I -

Ma

qu

ett

es

TemporalBox Icon

To display the TemporalBox reference icon, select the SHOW BOX ICONS option of the MAQUETTE PREFERENCES tab

Adding Boxes Directly in the Maquette Editor

Local Patches and Maquettes

A new local patch or maquette can be added directly in a maquette.

• To add a local patch, keep [CMD] pressed while dragging the mouse in the maquette editor.

• To add a local maquette, keep [SHIFT] + [CMD] pressed while dragging the mouse in the maquette editor.

A TemporalBox of equivalent size and representing a new local patch or maquette appear.

Adding Factory and Function Boxes

Factory and function boxes can't be added directly in a maquette editor. They must be added in a patch located in the maquette.

Using Sub Patches in MaquettesAdding and Deleting Boxes from the Outside of a Maquette


VII

I -

Ma

qu

ett

es

Patch and "Temporal Patch"

Patches located in maquettes can be refered to as " temporal patches ". Basically, temporal patches show no difference with "standard" patches :

• they have the same editor• can access the same boxes and functionalities• they are manipulated the same way.

Nevertheless, temporal patches have an additional feature. They can be used within the context of the maquette via a specific input and output : the temporal input and temporal output .

Temporal Input

The temporal input, or Tempin, allows to integrate the relation between the TemporalBox and the maquette – size, position, for instance – in the own program of the TemporalBox.

Temporal Output

The temporal output, or Tempout, allows to express the musical value of a TemporalBox within the context of the maquette.


VII

I -

Ma

qu

ett

es

2.2. Elementary Manipulations

Basic Commands

Selection

Boxes are selected using standard mouse selection. A selected box generally shows a bold border.

• To enable multiple selection, keep [SHIFT] pressed while clicking on boxes.

• To select all the boxes of a window :

• choose EDIT / SELECT ALL • press [CMD]+ [A] .

Resize• To resize a box, hover the mouse over the lower-right corner of the

box, then drag it with the cursor• To reinitialize the size of a box, press [I].

Note that the content displayed in the miniview rarely fits the size of the box.

Move

To move and item :

• drag and drop it with the mouse• use the [� ] keys – add [SHIFT] to move items faster.

Align

To align all selected boxes automatically, press [SHIFT]+ [A] .

Copy

To copy an item from a maquette editor to another one, or to another location in the maquette :

• press [ALT] + and drag the item• use the EDIT menu commands and shortcuts – Copy, Paste, Duplicate....


VII

I -

Ma

qu

ett

es

Deleting Selected Boxes

To delete one or several selected boxes :

• press [BACKSPACE].• use the EDIT / CLEAR or CUT menu.• use the [CMD] + [X] shortcut.

Undo

To cancel an action :

• select EDIT / UNDO

• press [CMD] + [Z].

Editing and Displaying Information

Size, Position, Name, Comments : the Get Info Window

The INFO window displays information about the name, position in the maquette, size of the TemporalBox, as well as possible comments.

• To open the window, [CTRL] / right click on the box and choose GET INFO .

• To edit the name, position and size of a TemporalBox, or add a comment :

1. click and type information in the relevant frame2. validate

To display the name of a box, select it and press [N]

Reminder

To display the TemporalBox reference icon, select SHOW BOX ICONS in the MAQUETTE PREFERENCES tab.


VII

I -

Ma

qu

ett

es

2.3. Temporalboxes Appearance

Miniview

The current value of a TemporalBox can be visualized with the miniview.To display the miniview, select a box and press [M] .

Size Parameter

While the representation of this current value does not necessarily fit the size of the TemporalBox, the size itself can be significant to the maquette's program.

Default Appearance of TemporalBoxes and Maquettes

To modify the default colour of TemporalBoxes :

1. go to the PREFENCES menu

2. select the MAQUETTE tab.

These modification only apply to items created afterwards.

TemporalBoxes Default Colour

1. click on the colour icon of the corresponding box.2. pick a colour in the Colour Chooser

3. choose [OK] .

4. select [APPLY] or [CANCEL] ,

5. select [OK] to validate your choice.

Select [RESTORE] to reset the default preferences of the TemporalBoxes.

Contextual Modifications

To modify the colour of a selected TemporalBox, press [C] and apply the same procedure.

TemporalBoxes Miniview and Icon• To modify the miniview background, choose a menu item in the

MINIVIEW pop up menu.• To hide or show the TemporalBox reference icon, unselect or

select the SHOW BOX ICONS option.

Modifying the Maquette Editor Appearance


VII

I -

Ma

qu

ett

es

2.4. TemporalBoxes Value

Each box in the maquette has a value. This value can be a musical value and/or a simple computational value.

2.4.1. PatchesThe " value" of a patch is produced by the patches itself, but this value has to be expressed in the maquette. The Tempout is a specific outlet which allows to express this value. "Tempout" stands for "Temporal Output".

The TempOut

The Tempout is used for expressing the musical value of the patch within the maquette.

• When a patch is created directly in a maquette, a tempout is automatically added in its internal editor. • If a patch is dropped in the maquette editor, this box can be added manually.

Adding a TempOut in a Patch

To add a Tempout :

• [CMD] click and type "tempout",

1. [CTRL] / right click in the patch editor,

2. select TEMPORALBOXES / TEMPORAL OUTPUT in the contextual menu.

Instances and Maquettes Don't Have a TempOut

TemporalBoxes representing instances, global variables or factory boxes only have one standard output, as a matter of course, since they are a value.

TemporalBoxes representing maquettes only have standard inputs and outputs, their potential musical value being expressed by the maquette itself.


VII

I -

Ma

qu

ett

es

Using a Patch Without a TempOut

Sub patches don't have to be integrated in the musical structure of a maquette to be used there. Therefore, a Tempout can be deleted. To display and express the value of the object, though, a connection to a Tempout still remains necessary.

This patch can return / get data to / from other boxes via its inputs and outputs.

Setting the TempOut Value

The value of a sub patch is the value connected to the Tempout. The user can select the value(s) to express in the maquette.

Here, the temporal object just performs an addition. It is not connected to any item, and its value is not displayed in the maquette.


VII

I -

Ma

qu

ett

es

Example

In the upper TemporalBox :

1. the value of a chord-seq is expressed via the Tempout, which is connected to the "self" output of the chord-seq

2. the last chords of the chord-seq are returned by the cdr function to the standard output of the TemporalBox

The value of the lower TemporalBox is calculated from the resulting list :

1. The input of the patch returns the list to flat. 2. All sub-lists are then concatenated in a single list, which is returned to the"midics"

input of the chord.

3. The "self" output of the chord is connected to a Tempout .The chord becomes the value of the TemporalBox.

The Tempin / Self Input Box

A patch created directly in a maquette has another default box : the Tempin, or Self Input Box .

The Tempin, or Self Input Box allows to control and use the relation between the patch and the maquette wherein it is located as programming parameters.

Hence, the Tempin is not compulsary for using a patch within a maquette, and can be deleted.

Using the Self Input Box for Programming :


VII

I -

Ma

qu

ett

es

2.4.2. Sub Maquettes

Like patches, maquettes can be dropped or created in a maquette editor.

Sub Maquettes Value

Maquettes are like "containers", whose value is the produce of the whole set of values returned by its inner components. This container is called "maquetteobj", as shown in the Listener at the evaluation.

A maquette doesn't need a Tempout to express its value.

Calculation Procedure

However, the calculation procedure of this value can be modified.

Calculating the Value of a Maquette : Alternate Tools

Maquettes and Musical Content

Maquettes can also exist without being expressed musically. This is the case when a maquette contains elements with no musical expression. Consequently, nothing happens when the maquette is played.


VII

I -

Ma

qu

ett

es

2.4.3. Instances

Instance Boxes and Factory Boxes

Dropping an instance or factory box in a maquette editor automatically generates a copy in this editor.

Copies of factory boxes and instances can be modified via this editor, without affecting the master item.

Global Variables

Conversely, modifications of global variables have an effect on all their representations, like in patches.

Instances modified in the maquette editor.


VII

I -

Ma

qu

ett

es

3. The Maquette Editor

Most programming operations with the maquette take place in the maquette editor. As a graphic and temporal interface, the editor offers a number of options in relation with the interface appearance and the temporal and metric structure of the maquette. In addition, a palette and a player allow graphic manipulations and of course, to play the maquette.

To open a maquette editor :

1. Double click on the maquette icon from the workspace of from a patch

2. [CTRL] / right click on the maquette and select FILE / OPEN in the contextual menu.

3.1. Maquette Editor Appearance

Default Appearance of Maquettes

To modify the default appearance of maquettes :

1. go to the PREFENCES menu

2. select the MAQUETTE tab in the PREFERENCES pane.

These modification only apply to items created afterward.

1. Click on the DEFAULT COLOUR frame of the maquette.

2. Pick a colour in the Colour Chooser, and select [OK] .

3. Select [APPLY] or [CANCEL].

4. Select [OK] to validate your choice.

Select [RESTORE] to reset the default preferences of the maquette.


VII

I -

Ma

qu

ett

es

Contextual Modifcations

Colour

To modify the colour of a specific maquette editor, press [SHIFT] + [C] and follow the previous procedure.

Maquettes and TemporalBoxes Pictures

To assign a maquette editor or a TemporalBox a background picture :

1. [CTRL] / right click in the editor

2. choose LOAD PICTURE, or SET PICTURE depending whether you have selected the maquette itself or a Temporalbox,

3. choose a picture in the Picture Chooser.

You can possibly import a resource to the User Resources.

Choosing Pictures : Detailed ProcedureModifying the Temporalboxes Appearance

Connections

Showing / Hiding Connections

Connections can be hidden or shown, depending whether the semantic structure of the program has to be revealed or not.

To show or hide connections, [CTRL] / right click on a box and choose SHOW / HIDE CONNECTIONS.

Colour

To modify the colour of the connections between Temporalboxes :

1. select a connection

2. press [C].


VII

I -

Ma

qu

ett

es

3.2. Rulers and Grid

Rulers

Function

The maquette editor has two rulers :

• the horizontal ruler, or abscissas axis, measures time in milliseconds

• the vertical ruler, or ordinates axis, measures space with an arbitrary unit.

Zoom

The scale of each ruler can be increased or decreased manually to zoom in or out, vertically and/or horizontally in the maquette.

To modify the scale of a ruler :

1. click on a ruler to view the double-arrow cursor 2. keep pressing while scroling the mouse.

To zoom in scroll the mouse upwards or rightwards. To zoom out, scroll it downwards or leftwards.

Grid

Displaying and Resolution

To display the grid of the maquette editor, press [G] .The grid's resolution is calculated automatically, according to the zoom scale.


VII

I -

Ma

qu

ett

es

Quantization and Snap to Grid Option

The quantization allows to snap boxes to the grid when they are moved manually. The quantization of the ordinates axis can be defined with positive integers.

• To specify a quantization :

1. double click on the vertical ruler.

2. enter a number of steps in the "Y Step" frame.

• To activate the quantization, select the MAGNETIC option. Boxes will snap to the closest vertical step.

The Metric Ruler : Rhythmic Parameters of the Maquette

The metric ruler displays measures and beats. It can be shown at the top of the maquette editor.

To display the metric ruler :

1. [CTRL] / right click in the maquette

2. choose SHOW / HIDE METRIC RULER.

The metric ruler has three parameters :

• tempo• meter• a metric quantization applying to objects.

To define the musical parameters of the maquette, double click on the metric ruler.


VII

I -

Ma

qu

ett

es

• To define a tempo :

1. click successively on the quarter note icon to choose a unit.

2. enter a tempo in the "Tempo" frame.

• To define a metric pattern, enter a list of one or more measures in the Metric frame according to the usual conventions.

• To specify pattern repetitions, use the LOOP MEASURE / LAST MEASURE option :

• The LOOP MEASURE option allows to repeat the meter pattern defined above.

• The REPEAT LAST MEASURE option allows to apply the last metric value of the pattern to the following measures

Note that complex or irregular meter changes, which cannot be expressed by a single pattern, require a thorough expression, measure by measure...

Snap to Metrics

The "Maximum Subdivision" frame takes a metric quantization unit.

• The reference unit of this subdivision* is always equal to the whole note , no matter which time signature has been chosen. For instance, "64" represents a 64th note subdivision, that is : .

• Values must be integers.

• Any subdivision of the whole note, – other values than powers of 2 – are accepted by OM.

For instance, "12" represents a triplet's fourth note subdivision, that is : .

Grid and Metric Ruler

The grid fits the measure unit of the metric ruler.

Memento : Subdivisions

= 1; = 2; = 4; = 8; = 16; = 32; = 64...


VII

I -

Ma

qu

ett

es

The ((6 8) (3 8) (3 4) (6 4)) pattern and the "Repeat Last Measure" option.

3.3. The Palette

Palette

The maquette provides a palette with navigation controlers, a player, and an evaluation command.

Navigation

Zoom : click and drag the mouse over a zone of the maquette to zoom on it.

Hand : click and slip to reach a zone of the maquette without changing its scale.

Reset : select this tool to fit the content of the maquette to the window editor.

Segment : click and drag the mouse over a temporal segment to select it.

Pointer : allows the selection of boxes.

Play

Play : applies to the whole maquette.

Play selection : applies to a selected temporal segment, or selected boxes.

Loop : a switch on/off to associate with or to play an item, temporal chunk or a whole maquette repeatedly.

The [SPACE] key can be used as a "play / stop" command.

Evaluation

Evaluation : this command evaluates the whole content of the maquette.

Evaluation of Maquettes and Temporaboxes

Player Options

Each object can be played with one or several players.

To assign a player to an object :

1. [CTRL] / right click on a box

2. choose PLAYER.

To apply the same module to all the TemporalBoxes of a maquette, follow the same procedure from the maquette editor.

Detailed Presentation of Players


VII

I -

Ma

qu

ett

es

3.4. Markers and Temporal Anchors

Markers are designed as pivots to define the beginning or the end of Temporalboxes on the temporal axis.

Setting Markers

Creating Markers

To create a marker, [CMD] click on the ruler. A small red triangle appears.

Moving Markers

To move a marker , select it and use the mouse or the [� ] and [� ] keys. Add [SHIFT] to move faster.

Deleting Markers

To delete a marker, select it by a click and drag and press [BACKSPACE].

Locating and Editing Markers: the Info Window

Offset, Name, Documentation

The location, name and documentation of a marker can be specified.

1. Open the InfoInfo window :

• [CTRL] / right click• press [CMD] + [I] on a marker.

2. Enter an offset in milliseconds, a name or documentation.3. Click somewhere outside the frames to validate the information.

Using Markers as Temporal Anchors

To lock the temporal position of a box :

1. [SHIFT] click on a marker 2. drag a connection towards the beginning or the end of a Temporalbox.

To delete an anchor, select the connection and press [BACKSPACE].


VII

I -

Ma

qu

ett

es

4. Maquette Programming

TemporalBoxes are programs that produce a musical value. But they can also be used as functional components withing the program of the maquette, connected to each other through inlets and outlets.

4.1. Using TemporalBoxes as Functional Components : Inputs and Outputs

Data can be sent from and to TemporalBoxes via standard functional inputs and outputs. These allow to assign input values to TemporalBoxes and create connections between objects in the maquette. They are represented on the outside of TemporalBoxes by small / chips.

To display or hide connections :

• [CTRL] / right click in the maquette• choose SHOW / HIDE CONNECTIONS.


VII

I -

Ma

qu

ett

es

Patches Inputs and Outputs

To add inputs and outputs to a TemporalBox, follow the usual procedure.

1. Double click on the TemporalBox to open it.

2. Click on the blue and green arrow icons to add inputs and outputs from the inside of patch.

3. Inputs and outputs appear on the outside of the TemporalBox.

Note that, as in any patch, inputs and outputs are represented by the same arrow icons, and are connected exactly the same way to the boxes of the patch editor.

Maquette Inputs and Outputs


Maquettes are also programs : they can be added a number of inputs and outputs.

In particular, this makes it possible to organize data transfers between temporal boxes into a hierarchy of maquettes.

To add an input or output in a maquette :

1. [CTRL] click in the maquette editor

2. select INPUT or OUTPUT in the contextual menu.

Edition

Maquette inputs and outputs can be edited like patch inputs, via their editor.

Editing Input Boxes


VII

I -

Ma

qu

ett

es


Default Output

When an instance, factory box or global variable is dropped into a maquette, a default output is automatically added in the corresponding Temporalbox.

No Inputs

Instances are programs that always produce the same object. Consequently, TemporalBoxes refering to instances don't have any inputs, but a single output that returns the value of the object they produce.


VII

I -

Ma

qu

ett

es

4.2. Evaluation of the Maquette

Evaluation Procedures

Global Evaluation of the Maquette

To evaluate a whole maquette, select EVAL in the palette. OM evaluates all the boxes located at the end of the programming chain, which will eventually lead to the evaluation of all the TemporalBoxes of the maquette.

The global evaluation of the maquette returns a maquetteobj. The listener displays a message of the type " => #<maquette-obj 34678965>".

Note that this command applies to the whole maquette even if a specific TemporalBox is selected.

Associated Files

In some cases, OM asks to choose a file when the box is evaluated, event if it was already attributed a file. This is the case when a TemporalBox refers to a sound file, for instance. Boxes can be locked to avoid the systematic opening of the dialogue window.

Evaluating TemporalBoxes

Choose a TemporalBox and press [V]. The selected box and all other connected boxes are be evaluated.

Controlling TemporalBoxes Evaluation

TemporalBoxes can be set on "lock" or "evaluate-once11" mode, so as their content is protected, or to limit the number of internal evaluations.



VII

I -

Ma

qu

ett

es

Default Calculation of a Maquette's Value

The value of a maquette is the musical object, or container, yielded when the maquette is evaluated. Very basically, this musical object is actually what is played by the player, just as with a sequencer.

The default type of this object is a maquetteobj : a musical sequence, a whole that combines TemporalBoxes, with a given musical value and temporal position.

This is especially visible when a local maquette is evaluated from a patch : the Listener displays a "maquetteobj" reference. It can be compared with the object connected to a Tempout.

Synthesis Patches

Maquettes can represent many other types of objects : sounds, chords, melodic sequences... The way a maquette is calculated can also be modified, so that the values of its TemporalBoxes is interpreted differently. To do so, a synthesis patch can be integrated in the maquette, like an " output evaluation tool ".

About Synthesis Patches


VII

I -

Ma

qu

ett

es

4.3. An Alternate Evaluation Tool : the Synthesis Patch

A maquette contains all types of objects : numeric values, chords, patches... The values of TemporalBoxes within a maquette can be used as functional parameters in a program that will be interpreted musically. To do so, we need a special type of patch : a synthesis patch.

4.3.1. Calculating the Value of a Maquette

A synthesis patch is like a standard patch. It produces a value from the content of a maquette.

To access this content, a Maquette Self Input must be added in the patch. The patch can then manipulate

this content. The result of the computation is attributed to the maquette via the Tempout of the patch.

The Maquette Self Input

Parameters

The Maquette Self Input returns the maquette's content. It can be used as a patch input. The Maquette Self Input returns:

1. the maquette's value itself,

2. the duration of the maquette,

3. the list of boxes contained in the maquette,

4. the list each box's value contained in the maquette.

The Synthesis Patch

Creating and Implementing the Patch


VII

I -

Ma

qu

ett

es

1. Create a blue or red patch.2. Drag and drop the patch on the lower-left corner of the maquette editor.

3. Add a Maquette Self Input in the patch :

[CTRL] / right click and choose TEMPORALBOXES / MAQ SELF INPUT.

4. Add a Tempout to the patch :

[CTRL] / right click and choose TEMPORALBOXES / TEMPORAL OUTPUT.

You can now manipulate the data returned by the Maquette Self Input with the program you will design in the synthesis patch. The maquette's value will be that of the object connected to the Tempout of the synthesis patch .

Evaluation Program

The resulting synthesis patch actually is the evaluation program, or evaluation tool of the maquette. When the maquette is evaluated, the Maquette Self Input of the synthesis patch is updated, and the synthesis patch is evaluated too.

Accessing the Results of a Synthesis Patch ?

The result of a synthesis patch is computed when the maquette is evaluated. The information produced is returned to other boxes only for subsequent computation : the Self Input box must be considered a virtual storage box. Consequently, information won't be displayed in the Listener, unless a specific function, like print, is resorted to.

Assigning a Synthesis Patch via a Maquette Input bbbbbbbbbbbb

This synthesis patch prints the list returned by the Maquette Self Input : its reference, duration, TemporalBoxes references, and the objects contained in the TemporalBoxes.


VII

I -

Ma

qu

ett

es

Internal Patches / Synthesis Patch

Modifying an internal patch doesn't affect the other references of the patch, including the patch that was dropped in the corner of the maquette. Out of security, we advise you to make a copy of the last version of this internal patch.

4.3.2. Example : Building a Chord-Seq with a Synthesis Patch

This maquette contains several bpfs. The coordinates and temporal position of each bpf is interpreted to produce a corresponding melodic sequence. The sequences are then merged into one chord-seq. The whole process is programmed in a synthesis patch.

Programming the Synthesis Patch

General Program

The synthesis patch has been added in the workspace, dropped in the patch editor and assine to the maquette.

The synthesis patch has :

• a Maquette Self Input box, which represents the maquette in which the patch is integrated,

• an OMLoop, which returns values for the chord-seq box,• a chord-seq box, connected to the synthesis patch's Tempout.

The maquette's output returns the chord-seq produced by the synthesis patch.


VII

I -

Ma

qu

ett

es

OMLoop

The value of the Maquette Self Input is returned to OMLoop's input.

At each step of the loop, listloop returns the value of a TemporalBox to slots. Each of these TemporalBoxes has a value, a vertical position – posy – and a temporal position – offset .

• The value, or coordinates of each bpf are returned to car, which selects the y-points of the bpf. The y-points are returned to the "midic" input of the chord-seq.

• The y-points of the curve are added to the "posy" of the TemporalBox, as for a transposition.• The offset of the box is returned to om+ and list, which return a list of the type (n (n+200)) to the chord-seq

box. There will be a 200 ms interval between each of the chord-seq's items.1. At each step of the loop, acum builds a sequence out of the chord-seq and a "blank" chord-seq. 2. Finally returns the whole sequence to a global chord-seq, which is connected to the Tempout of the

synthesis patch.

About Acum and Merger

Acum has three inputs :

• something to collect,• an initial value, • a function on "lambda" mode, which determins the behaviour of the acumulator.

Here, merger builds a sequence out of the two chords-seqs including the temporal value of the chord-seqs.

Merger merges two sequences into one, including their temporal value. As it cannot merge something with "nil", we have assigned a "pseudo" empty chord-seq to the initial input of acum.

Inside the OMLoop : building the melodic sequence from the TemporalBoxes parameters.


VII

I -

Ma

qu

ett

es

Resulting Chord-Seq

The result of the synthesis can be visualized with a chord-seq box connected to the maquette's output. When the maquette or a selected TempBox is played, it renders the interpretation of its values by the synthesis patch.

Using the Maquette or Not

Here, as in most cases, the same program can be designed without a maquette, if one is interested in a single abstraction level.

• The maquette empathizes the temporal structure at stake in a process. It gives a global, and somehow intuitive view of this temporal dimension, which can be manipulated with the advantages of its specific graphic interface.

• The maquette provides a temporal representation of a process at a different abstraction level. • Last, this temporal structure can be reinterpreted in a program.

4.3.3. Assigning a Synthesis Patch with the Set-Eval Function

Features

Function

The set- eval-func function can assign a synthesis patch to an internal maquette from the patch where it is located. The maquette must be on "reference" mode.

To access the set-eval-function :

• select OM KERNEL / CONTROL / SET-EVAL-FUNC, • press [CMD] and type "set-eval-func".

To set a box on Rference mode in a patch, select it, press [B] and click twice on the label to display the reference label.

Maquettes on "Reference" Mode


VII

I -

Ma

qu

ett

es

Inputs and Outputs

Set-eval-func has two inputs and one output :

• " self" : a maquette on Reference mode. • "func" : a patch or function on Reference mode.• Its output returns a reference.

Connection

The calculation of the maquette's value takes place at the evaluation of set-eval-func.

Note that the maquette's output can also be connected to an object that will possibly materialize its new value. Nevertheless, the maquette must be reset on normal mode so that the object can be evaluated.


VII

I -

Ma

qu

ett

es

4.4. Programming with TemporalBoxes

The relation between TemporalBoxes and the maquette can be integrated and used within the very internal program of TemporalBoxes. This requires the use of a specific input within TemporalBoxes : the Self Input Box, or Tempin, which represents the position of a temporal object within a maquette.

4.4.1. The Self Input Box – Tempin

The Self Input box

A Self Input box can be added in a patch, to apply or control the characteristics of a Temporalbox from the very inside of the patch.

Consequently, the Self Input box is only useful if the patch is represented in a maquette.

Adding a Self Input box

To add a Self Input Box in a patch :

• [CTRL] / right click in the editor and choose TEMPORALBOXES / SELF INPUT

• [CMD] click and type "tempin".


VII

I -

Ma

qu

ett

es

Self Input Parameters

The Self Input box parameters are very similar to those of a musical object. In addition, it has temporal and graphic values, which allow the interaction with the maquette.

1. self : the Temporalbox itself – like a "self" output

6. posy : vertical position

2. offset : starting point of the box in milliseconds

7. stretch-fact : time stretch factor, expresses the size modification of a TemporalBox

3. extend : calculated duration 8. sizey : vertical size of the box

4. color frame :

box colour 9. free-store : a "free" parameter

5. value : whatever is connected to the Tempout of a TemporalBox.

10. reference : an object connected to the "reference" input of a TemporalBox instance

Actual Duration of a TemporalBox

duration = extend * stretch-fact

Accessing the Parameters of the Self Input

Using the Information of the Self Input box

Information provided by the Self Input box can be used in the patch with simple connections with other boxes.

For instance, we can use :

• the "posy" value to define the pitch of a chord• the "offset" value to define the velocity or duration of the chord...

A Programming Example

Information can also possibly be returned by the output(s) of the TemporalBox to other TemporalBoxes, in order to define relations between their respective properties or temporal qualities.

Another Example


VII

I -

Ma

qu

ett

es

Slots box : Defining the Properties of the Self Input from the Patch

The Self Input box shows no inputs, like an instance box. Yet, we sometimes need to access and modify the parameters of a TemporalBox from its internal program. To do so, we can resort to a slots box that will represent this TemporalBox.

To create a slots box out of a TemporalBox instance :

1. [CMD] click in a patch editor and type "temporalbox"


The slot box can define the properties of the TemporalBox from the patch. Using a slot box amounts to modifying the attributes of the "self" output of the Self Input Box.

Hence, we can use slots for defining :

• the colour of the TemporalBox,• its position according to other parameters, • data returned by other boxes...

Defining TemporalBoxes From their Internal PatchUsing the Slots Box

Slots Box Value

The slots box must be connected to the "self" output of the self input box otherwise, it has no value.


VII

I -

Ma

qu

ett

es

4.4.2. Example 1 : Programming With the Self Input Box

Adding a TemporalBox into a Maquette

Each output of the Self Input Box can be connected to other boxes within the patch of a TemporalBox.

This internal maquette contains one TemporalBox.

• The program of the box integrates its vertical and temporal position in the conception of a chord sequence.

• The fundamental pitch and structure of the resulting chord sequence can evolve according to the position of the TemporalBox where it belongs.

Applying the Self Input Box Values Inside a Temporalbox : Programming a Chord

1. The " posy " – of the box is returned by the Self Input Box in the patch. Om-scale scales it between 30 and 300, range of a fundamental frequency.

2. A "pattern-chord" provides a harmonic structure that can be modified by the program. • Mc->f converts the pitches of the chord into frequencies.• X->dx returns the intervals of the chord, starting from the fundamental.

3. The box's " offset " is returned by the Self Input Box and converted into a stretching coefficient that applies to the intervals of the chord.

4. Eventually, these intervals are added to the fundamental frequency. 5. The resulting list of frequencies is converted into midicents by f->mc and returned to a chord box. This

chord becomes the musical value of the box via a connection to the Tempout.


VII

I -

Ma

qu

ett

es

4.4.3. Example 2 : Defning Temporal Relations Between TemporalBoxes

Applying the Values of a TemporalBox to Other TemporalBoxes

The values of the Self Input Box can be used for defining temporal relations with other TemporalBoxes, via connections between functional inputs and outputs.

Building a Sequence of TemporalBoxes

The chord of TemporalBox #1 is a reservoir for isolated notes that will occur successively in the maquette.

1. We have programmed the TemporalBoxes so that the initial chord provides one random note to each of TemporalBoxes #2; 3; and 4.

2. The offset of each TemporalBox is determined by the offset and duration of the preceding box, so that boxes follow each other.

Inside TemporalBox #1

The internal program of the first TemporalBox determines some characteristics of the other TemporalBox.

• The initial chord lasts 3 seconds. It is connected to the Tempout of TemporalBox #1, and represents its musical value.

• Permut-random performs a random permutation of the chord's pitches. The three first pitches of this permutation are returned by nth-first to the first output of TemporalBox #1.

• On the other hand, the offset of the TemporalBox returned by the Self Input Box, is added with the chord's duration.

• The result is returned to the second output of the TemporalBox.

Inside TemporalBox #1 : using the "pattern-chord" data.


VII

I -

Ma

qu

ett

es

TemporalBoxes Interaction

The random pitches – output #1 – are returned to all the other TemporalBoxes. The ending time of the box – output #2 – is returned to the next TemporalBox.

Inside TemporalBox #21. The three random pitches are returned by the first input of

TemporalBox #2 to the first function. First picks the first note and returns it to the note box. This note is also given a duration.

2. The note is connected to the Tempout and becomes the musical value of the TemporalBox.

3. The temporal position of TemporalBox #1, is returned to the "offset" input of slots, which defines the offset of TemporalBox #2.

4. The offset of TemporalBox #2 is added to the duration of the note, and the result is returned to the output of TemporalBox #2.

5. The value of the output ending of the box – is returned to the next TemporalBox, which contains the same program.

About Last TemporalBox

Note that the last TemporalBox has nor output, neither om+ function, but a sequence function. The box has nothing to return to another box. The sequence function allows to evaluate slots before evaluating the TemporalBox, so that its offset is correct.


VII

I -

Ma

qu

ett

es

5. Using Maquettes in Patches

Local maquettes and global maquettes can be either created or dropped in a patch. In both cases, we get a maquette box. The maquette is both a musical container and a program. Hence, the maquette box can be used following two different modes : the Build mode, and the Functional mode .

5.1. Build Mode

Use

The Build mode is the default mode of the maquette when it is dropped in a patch. It then shows dark blue inputs and outputs.

Procedure

To set a maquette back on Build mode :

1. [CTRL] / right click on the maquette box

2. select MAQUETTE OBJECT INPUTS.

Inputs and Outputs

The two default inputs of the maquette box always take an onsets list and an objects list.

The Build mode was oringinally the only way to add one or more TemporalBoxes in a maquette. It is a convenient way to add a succession of objects in a maquette. Other parameters, such as the vertical position of boxes, cannot be specified.

The default output of the maquette box returns the value built by the maquette :

• a maquetteobj type of object, which gathers the values produced by the objects • something else, if the maquette is related to a synthesis patch.

Inputs Lists

Objects and onsets of each lists match each other. Maquettes accept the following types of objects : musical objects, patches and maquettes on Reference mode .

Standard Inputs and Outputs

Possible standard inputs – and outputs – – are hidden outside the maquette.


VII

I -

Ma

qu

ett

es

Example : Adding a List of Items in a Maquette

We want to add a series of items in a maquette located in a patch. Each input of list is connected to an object. List returns a list of objects references, such as : OM ==> (#<chord-seq 2320ACBB> #<sound 231854C7> #<chord 231EE75F> #<ompatchabs 231ED3B7> #<ommaqabs 2320E8CB>).

• The second input of the maquette takes this list of items. • The first input of the maquette takes a list of offsets, which determine the temporal position of the

corresponding items.

The items appear in the maquette after the evaluation.

Note that the maquette must be evaluated from the outside to display the items in the right order.

The maquette, once evaluated.

Evaluation and Content

Once the maquette is built, its content can either

• remain the same, if no object is connected to it,

• be replaced by new objects, if objects are connected to it.


VII

I -

Ma

qu

ett

es

5.2. Functional Mode

Use

A maquette on Functional mode can be compared to a function. This is especially significant when a maquette is to receive or to return values, from the inside of a patch or another maquette.

Procedure

When a maquette is added in a patch, it is by default on "build" mode, as show its dark blue inputs and outputs.

To set a maquette box on "functional" mode, [CTRL] / right click on the maquette box and select FUNCTIONAL INPUTS.

The maquette then shows only one "build" output. "Build" inputs disappear.

When inputs and outputs are added from the maquette editor, they appear on the outside of the maquette as standard inputs and outputs. The "value" output remains visible in first position.

Functionalities

Functional inputs allow

• to pass values from the patch to the maquette• possibly to get outcoming values back.

The content of the maquette is not built from the patch, but used as a preexistent full-fledged function.


VII

I -

Ma

qu

ett

es

Example : Defning a Sequence from the Outside and Inside of the Maquette

In this example,a maquette is used inside a patch for building a sequence with three TemporalBoxes.

Organizing the Maquette

On one hand, a number of notes and an initial offset are defined from the outside of the maquette. On the other hand

• pitches are determined by the vertical position of each box • the successive offsets of the second and third box are calculated from inside the maquette .

• The first functional input of the maquette is assigned a number of notes and connected to the first input of a TemporalBox.

• The second functional input is assigned an offset – starting point in milliseconds – and connected to the second input of the TemporalBox.

• The output of the maquette can possibly send data from the TemporalBox to the outside of the maquette.

Programming TemporalBox #1

Values are returned to the functional inputs of the maquette to define a chord-seq in the TemporalBox.

• The "posy" is scaled from 5000 to 8000 by om-scale.• The resulting pitch is repeated five times by repeat-n and returned to the chord-seq.• The chord-seq box is connected to the Tempout : it is now the musical value of the TemporalBox.• The offset of the TemporalBox is added to the onset of the chord-seq's last note, and returned to the

functional output. This determines the position of the next box in the maquette.


VII

I -

Ma

qu

ett

es

Defining TemporalBoxes #2 and 3

TemporalBox #1 is duplicated to create two new TemporalBoxes, which are connected to each other and to the maquette inputs.

1. The same number of notes is returned by the first input of the maquette to all TemporalBoxes.2. The ending offset value of a TemporalBox is connected to the second input of the next TemporalBox.

Boxes follow each other in a temporal sequence.3. Pitches match the vertical position of the boxes.

4. The ending offset calculated in TemporalBox #3 is returned to the functional output of the maquette. It can possibly be used for subsequent computations in the patch editor, or in another maquette.


VII

I -

Ma

qu

ett

es

Evaluating the Maquette


VII

I -

Ma

qu

ett

es

Completing the sequence

5.3. Reference Mode

Use

The Reference mode can be used simultaneously with both Build and Functional modes. Objects in a maquette on Reference mode can be added, accessed or removed.

Procedure

To set a maquette on Reference mode, press [B] and click three times on the label to display the label.

Permanent Modifcations

Any operation performed on a maquette on Reference mode will modify the master object permanently.

Frequently Used Commands

Ma,ipulating TemporalBoxes from the outside of the maquette requires the frequent use of a number of items, which are added as follows :

TemporalBox instance

• [CMD] click and type "temporalbox".

• select CLASSES / OMKERNEL / MAQUETTE / TEMPORALBOX.

Self Input box

1. [CTRL] / right click

2. select TEMPORALBOX / SELF INPUT.

slots box

1. [CMD] / click in a patch editor and type "temporalbox"


Connate Functions

Associated Functions

A number of functions allow to add, access, manipulate or delete TemporalBoxes in a maquette on Reference" mode from a patch. These functions can be accessed via the FUNCTIONS / OM KERNEL / MAQUETTE menu.


VII

I -

Ma

qu

ett

es

5.3.1. Reference Mode : Adding TemporalBoxes in a MaquetteBefore a TemporalBox is added in a maquette on "reference" mode, this box must be created in a patch as a TemporalBox instance. Several functions can then be used for adding, accessing, deleting a TemporalBox from a maquette.

Creating a Temporalbox Instance in a Patch

To add a Temporalbox instance in a patch, [CMD] click and type "temporalbox", or select CLASSES / OMKERNEL / MAQUETTE / TEMPORALBOX.

TemporalBox instances must then be assigned required values, such as a position, value, duration, and so on.

Addbox2maquette Function

Functionalities

The addbox2maquette function allows to add one or more TemporalBoxes in a maquette from a patch.

The addbox2maquette function as two inputs and one input :

• "self" : a TemporalBox instance on Reference mode. • "maquette" : a maquette on Reference mode.• Its input returns the reference of a TemporalBox

To add the addbox2maquette function :

• [CMD] click and type "addbox2maquette" • select FUNCTIONS, OMKERNEL, MAQUETTE / ADDBOX2MAQUETTE.

Procedure

To add a TemporalBox with the addbox2maquette function :

1. connect the "self" output of a TemporalBox instance to the "self" input of the function

2. connect the "self" output of the maquette box to the "maquette" input of the function

3. evaluate the function.

The TemporalBox is assigned a temporal and a vertical position . The parameters of the TemporalBox instance are expressed by the graphic position of the TemporalBox.

Other Parameters

Of course, many other parameters and more or less sophisticated interactions between those parameters – for instance, position / colour / pitch – can be at stake in the maquette's program.

Programming with Parametric Interaction


VII

I -

Ma

qu

ett

es

Reference and Value Inputs of the TemporalBox

A TemporalBox instance is an actual program, which can :

• calculate and yield an object via its internal program,• be given a value via the "value" input,• refer to an object via its "reference" input.

Adding Objects with the "Value" and "Reference" Inputs of a Temporalbox Instance

This patch adds three objects in a maquette :

1. a chord, via a "reference" input2. another chord, via a "value" input3. a patch with a chord for musical value,via a "reference" input.

Addbox2maquette has been evaluated, but the TemporalBoxes have not been evaluated yet.

• The first box shows a chord, its reference. • The second box shows an empty patch, because it has no

reference, but its musical value is that of a chord.• The third box has a patch for reference. It doesn't have a

musical value yet.


VII

I -

Ma

qu

ett

es

The TemporalBoxes content shows a chord instance, an empty patch and a patch producing a musical value.

The TemporalBoxes have been evaluated. Their content has not changed.

• The first box still shows a chord, because its reference hasn't changed.

• The second box now shows no value, because its empty patch cannot yield anything.

• The third box now shows a chord, because its internal patch has been evaluated.

"Value" vs. "Reference" Input

The object connected to the "value" input becomes the value of this box. This result is updated at each evaluation of the box's program in the maquette.

• If this program is empty, then the TemporalBox won't yield anything. • If not, it yields whatever is connected to the program's Tempout, no matter what is connected to its "value"

input.

The object connected to the "reference" input becomes a permanent reference for the TemporalBox in the maquette.

• This object can be a patch or maquette on Reference mode, or an instance .• If no object is assigned to this "reference" input, the TemporalBox will be an empty patch.


VII

I -

Ma

qu

ett

es

5.3.2. Adding TemporalBoxes : Examples

Adding a List of TemporalBoxes in a Maquette

Program• List returns a list of TemporalBoxes that are added in the

maquette. • The Temporalbox instances have temporal and graphic

parameters. • The "self" outputs of the instances are connected to list. • The resulting list is returned to addbox2maquette.

When addbox2maquette is evaluated, both TemporalBoxes are added in the maquette.

Maquette and Evaluations

The corresponding temporal objects are represented by gray boxes , which show a small OM icon if the SHOW BOX ICON option is selected in the maquette preferences.

This maquette already contained three temporal objects. Addbox2maquette has been evaluated twice, without modifying the TemporalBoxes parameters : objects are superimposed. Everytime the function is evaluated, the TemporalBoxes are added in the maquette. No TemporalBox is deleted from the maquette.

The maquette, after the first evaluation of addbox2maquette.


VII

I -

Ma

qu

ett

es

Specifying Colour

The colour of a TemporalBox is specified with R-G-B values and the om-make-color function.

Systematizing Colour According to Posy and Offset

After the second evaluation of the function.


VII

I -

Ma

qu

ett

es

Specifying TemporalBoxes Number and Position with a BPF

Program

This patch allows to place several TemporalBoxes in a maquette. It has a bpf, an OMLoop box, and the addbox2maquette function.

• The bpf is a series of points whose graphic position is transposed in the maquette. A series of point in the curve is selected. The x-points and y-points are converted into temporal and graphical data.

• The OMLoop iterates the operation.

OMLoop

The "self" of the bpf is returned to the input of the OMLoop : the x and y-points of each point are enumerated via the slots of a bpf and two listloops.

• Xs are returned to the "offset" input of the TemporalBox instance.

• Ys are returned to the "posy" input.• A duration has also been assigned to the temporalbox

instance.1. At each step of the loop, collect stores the information

returned by the temporalbox instance. 2. Finally returns the whole of the results addbox2maquette

at the end of the iteration.

Resulting Maquette

The bpf is expressed by the position of the TemporalBoxes.


VII

I -

Ma

qu

ett

es

5.3.3. Accessing TemporalBoxes of a Maquette from a PatchAccessing TemporalBoxes from a patch is especially necessary for removing them from a maquette, and for manipulating them from outside the maquette.

Temporalboxes Function : Use

The temporalboxes function allows to access and modifiy all the temporal objects contained in a maquette.To add the temporalboxes function :

• [CMD] click and type "temporalboxes" • select FUNCTIONS / OMKERNEL / MAQUETTE / TEMPORALBOXES.

Procedure

1. Connect the maquette box on "reference" mode to the input of the temporalboxes function.

2. Connect the output of the temporalboxes function to the program. The boxes contained in the maquette can be manipulated from the patch.


VII

I -

Ma

qu

ett

es

5.3.4. Removing TemporalBoxes from a Patch :

Removealltemporalboxes / Removetemporalboxes :

Functionalities

The removealltemporalboxes function allows to remove all TemporalBoxes of a maquette from a patch.

The removetemporalbox function allows to delete one or several selected TemporalBoxes from a maquette.

• It must be associated with the temporalboxes function, which returns the list of temporal boxes contained in a maquette.

• The boxes to be removed can be defined by a number of conditions via a program. Boxes are checked successively to be eventually removed.

• The OMLoop module can then be very convenient : it will check each item of the list successively.

Procedure

Connect the maquette on Reference mode to the input of removealltemporalboxes and evaluate the function.

All the temporal objects of the maquette are deleted.

Example : Removing Preexistent Boxes Before Adding New Boxes

Building a Specific Sequence

In the following sequence, the maquette is "cleaned" systematically before a new TemporalBox is added into it.

The sequence function applies the following command line : (sequence (removealltemporalboxes maquette) (addbox2maquette maquette temporalboxes) )


VII

I -

Ma

qu

ett

es

Evaluation

Before the evaluation, the maquette contains three TemporalBoxes. At the evaluation, all preexistent TemporalBoxes are suppressed from the maquette.

Example : Removing Boxes According to Posy

In this maquettes, the green boxes "posy" is superior or equal to 50. The purple boxes "posy" is inferior to 50. The purple TemporalBoxes must be deleted.

This can be done with two programs :

• with list-filter and a specific test argument • with an OMLoop box.

First Option : List-flter

List-filter takes a test argument, a list, and an action : "reject" or "pass" – "reject" in this case.

1. Temporalboxes returns a list with the values of each TemporalBox located in the maquette.2. The test argument defined in the patch on "lambda" mode checks is the "posy" of each box is superior or

equal to 503. List-filter rejects them and returns boxes whose "posy" is inferior to 50. 4. Removetemporalboxes is evaluated and removes these Temporalboxes from the maquette.

The test-patch has a slots box and an OM >= predicate.


VII

I -

Ma

qu

ett

es

The slots box represents a TemporalBox, whose "posy" output is connected to the >= predicate. The test argument tests if the "posy" of a TemporalBox is superior or equal to 50.

Removetemporalboxes removes boxes whose value is returned by list-filter, that is, boxes, whose "posy" is inferior to 50.

Second Option : With OMLoop

This program is very similar to the program above. Here, temporalboxes is connected to the input of OMLoop, which executes the same task as list-filter.


VII

I -

Ma

qu

ett

es

1. At each step of the loop, listloop returns the value of a TemporalBox, and the > predicate tests if the "posy" of the slots box is inferior to 50.Slots stands for a TemporalBox.• If this posy is inferior to 50, omif returns it. • Otherwise, it returns "nil".

2. The result of the successive evaluations is stored by collect. 3. At the end of the iteration, remove removes all "nil" values from the list. 4. The list is returned by the output of the OMLoop to removetemporalboxes.

Evaluation

In both cases, when evaluated, removetemporalboxes removes all the items of the list from the maquette, that is, all the boxes whose "posy" is inferior to 50.

5.3.5. TemporalBoxes Interaction : Examples (1)Here is a series of basic examples showing how the graphic and musical parameters of objects can interact within a maquette. They may give a hint of the principles at stake in the musical exploitation of the maquette's specific dimensions.

Determining Pitch From "Posy"

The vertical position of a TemporalBox can be converted into a pitch.

Program

The patch shows :

• a temporalbox instance,• an internal maquette, • the addbox2maquette function, • an internal patch that executes the conversion.


VII

I -

Ma

qu

ett

es

1. A Self Input box is connected to om-scale. 2. The "posy" of self is scaled from a value between 0 and 100 to a value

between 4000 and 8000 midicents. 3. The resulting value is expressed by a note, and assigned as a musical value

to the TemporalBox via the Tempout.

TemporalBox Evaluation

Once addbox2maquette is evaluated, the box appears in the maquette. It doesn't have a musical value at first, but its has a "posy" and an offset. The pitch changes with the vertical position of the TemporalBox, when the maquette or the object is evaluated.

5.3.6. TemporalBoxes Interaction : Examples (2)

Determining Colour and Pitch From "Posy" and "Offset"

The "posy" of TemporalBoxes in the maquette can be applied to both pitches and colour of the boxes. The graphic appearance of the maquette may be more or less musically significant.

Program

The position of the boxes is determined by a bpf. The same bpf is used for determining their pitch and colour. OMLoop iterates this operation to apply it to the a series of boxes located in a maquette.

1. Boxes are added in the maquette when evaluating Addbox2maquette. Sequence and removealltemporalboxes "clean" the maquette at each evaluation, before new boxes are added.

2. OMLoop is returned the value of the points in the bpf. Coordinates allow to modify the TemporalBoxes colour on one hand, and their musical value on the other hand.


VII

I -

Ma

qu

ett

es

OMLoop

The "colour program" used in the preceding example is integrated in an internal patch.

1. y-points are returned by listloop to om-scale successively : the pitch of a note object is defined.

2. X and y-points are returned to the "make-colour" patch, to the "offset" and to the "posy" inputs of the temporalbox instance : the colour, offset and "posy" are defined.

3. At each step of the loop, collect stores the value of a TemporalBox.

4. At the end of the loop, a list of values is returned to addbox2maquette by finally.

Inside the "make-colour" patch, x-points and y-points are converted into red and green values.

Resulting Maquette

The result is visible after evaluating sequence. The corresponding musical sequence can be visualized with a small program.


VII

I -

Ma

qu

ett

es

Musical Sequence

Program

Temporalboxes is connected to the output of the maquette. OMLoop returns the series of pitches produced by the TemporalBoxes to a chord-seq.

1. Listloop returns the successive values of each TemporalBoxes to a corresponding slots box. This value is a note.

2. The "value" of slots is returned to car so that we get a list of notes. Otherwise, we would get a list of lists, which cannot produce a chord-seq, by convention.

3. Collect stores the successive notes values4. Finally returns the resulting list of values.

Resulting Sequence

The evaluation of the chord-seq box in the patch yields the following sequence :


VII

I -

Ma

qu

ett

es

X - Errors and Problems

...


1. Warnings

Listener Messages

Minor programming errors are usually displayed in the LISTENER window as well as plain messages. This allows OM to keep on running smoothly and the user to understand the origins of the error.

Such error messages can occur when evaluating a box, for instance.

Handle Error Messages Option

More "serious" errors can interrupt the evaluation of a patch. If the HANDLE ERROR MESSAGES option was selected in the PREFERENCES pane, an error window opens.

If not, the error will propagate and the LISP TERMINAL window will open.


X -

Err

ors

an

d P

rob

lem

s

2. The Lisp Terminal Window

In the case of more important, unpredicted errors, or if the HANDLE ERROR MESSAGES option wasn't selected, the Lisp Terminal opens.

Terminal Window Commands

This window is an underlying Lisp debugger, which can be exited, or used for understanding and possibly solve the cause of an error.

Here are a few useful commands to enter in this terminal :

• To get back to the preceding step of the error : enter ":top" and validate• To display the simple backtrace of an error : enter ":b" and validate.• To display the detailed backtrace of an error : enter ":bb" and validate.

The function call stack in question can be copied and submitted in a bug report to the IRCAM development or support teams.

• To use one of the options offered by the Terminal, type ":c" with the option's reference, e.g. : ":c 1", ":c 2", etc. and validate.

• To display other possible commands, enter ":help" and validate.

Stuck Application

If OM gets stuck, type [CMD] + [SHIFT] + [A].

An error in the Mac OS system Terminal


X -

Err

ors

an

d P

rob

lem

s

Glossary of Terms

ArgumentAn argument represents a parameter upon which a function operates. For instance, the (om+ x y) function has two arguments : x and y.

Break Point FunctionA "break-point" function is a function defined by a finite number of points (x,y).

CAR, CDR, CADR, CDDR, CADDR...Elementary Lisp functions, allowing the access to one or more elements in a list. CAR and CDR are kernel functions upon which have been defined the rest of these functions.

Let the following list be : (A B C D).

CAR (A B C D) = A.CDR (A B C D) = (B C D).CADR (A B C D) = B. CADR means CAR of the CDR.CDDR (A B C D) = (C D). CDDR means CDR of the CDR.CADDR (A B C D) = C. CADDR means CAR of the CDDR. NTHCDR (A B C D) = NTH CDR of the list – N must be specified as argument. NTHCDR 3 (A B C D) = (D).And so on...

Chord-SeqOM name of a chord sequence. By extension, a note sequence, since a single note can be considered a chord.

ClassA category of objects sharing common properties – characteristics and behaviour. A class specifies the internal structure and behaviour of an object. In OM, it is represented in a patch by a factory box that can produce an instance of a class.

See also : Object, Instance

CLOS – Common Lisp Object System –CLOS is an object-oriented programming protocol defined in the Common Lisp language specification. It is based on classes, instances of classes, generic functions and methods to be used in Lisp programs.

See also : Class, Function, Generic Function, Method, Instance.

ContainerIn OM, a container is an object that contains a number of sub objects, including other containers as well. For instance, a chord-seq that contains chords, a chord that contains notes, a maquette that contains temporal objects, etc.

ETFExtensible Transportable Format, originally developped by Finale.

EvaluationTriggers the calculus that will determine the value of an expression. Applies to functions and objects.Click and press [V] or [CMD] click on an outlet.

Factory boxA box used for creating an instance, or exemplar, of a given class within a visual program.


FunctionA portion of code within a larger program, which performs a specific task. Operates upon 0 or more parameters and returns a value.

Functional abstraction

A functional abstraction is a program whose some elements can become variables, via connections to the outside environment. Hence, this program must have inputs or outputs that can be connected to external variable elements. The resulting functional abstraction can then be embedded into other programs to be used as a functional component.

Generic functionIn object oriented programming, a generic function is a collection of methods – elementary specialized functions – with the same name and argument structure, but with arguments typed differently.

See also : Method

Global variableAn instance of OM object that has been saved in order to be used in other programs. Global variables are visible from the LIBRARY window and stored as .omi files in the GLOBALS folder of the workspace.

GroupAn internal subdivision, that is, a list of proportions within a measure. A group can enclose a sub group. Basic examples are tuplets, groups of eighth, sixteenth notes. Groups of quarter, semibreves, whole notes or any other values are also admitted in rhythm trees.

For instance : (? ((4//4 ( (2 ( 1 1)) (1 ( 1 (1 (1 1 1)))) (1 (1 1 1 1 1)) )))).

This one measure tree has one group – two quarter notes –, one group with a sub group – one eighth note and a sixteenth notes triplet, and a last group – a quintuplet.

InstanceAn actual object created at runtime, out of a given class. In OM, more specifically, an object created when evaluating a factory box. An instance can be saved as a global variable.

[SHIFT] click on an outlet – especially the first outlet representing the self, the whole object – of a factory box to materialize an instance.

Internal evaluationEvaluation of a box by OM, triggered by a user evaluation, or by the internal evaluation of an upstream box connected to it.

IterationThe repetition of a process within a computer program. See also : Recursion.

Lisp ListenerA Lisp communication interface displaying results of computations, warnings or error messages, and where Lisp expressions – programs – can be evaluated.


Glo

ss

ary

of

Te

rms

Maquette A hybrid of visual program and sequencer, a programming unit provided with a time dimension, where musical material is organized in a time oriented structure.

MatrixA matrix is a rectangular array of m*n numbers, with m rows and n columns, such as :

1 2 3

4 5 6

Method

An elementary function or part of a generic function defining rules for its behaviour depending on a type of argument. Defining a generic function amounts to defining at least one method.

For instance, the OM+ function is made of four methods : 1. number + list / 2. list + number / 3. number + number / 4. list + list

MidicentA midicent is a unit representing one cent of the usual MIDI pitch unit, that is, a half-tone. For instance, a C4

corresponds to 60 in MIDI, and to 6000 midicents, C≥4 to 61, i.e. 6100 midicents, and so on.

n → mcConverts a note name or list of note names into corresponding midi cents values. The reference is the standard notation, where the medium C (6000 midicents) = C3.

PackageContains functions or classes components belonging to a common category of programming items. Packages are provided at the installation of OM, but the can also be loaded dynamically or added by the user.

Patch

A programming unit where objects and functions – boxes – are interconnected to build a musical algorithm, that is, a sequence of instructions. A patch can also be embedded as a box within another patch.

Persistent object / document, PersistenceA persistent object corresponds to a "real" file that is kept somewhere in the hard drive of the computer. Examples of persistent objects in OM are patches, maquettes, or global variables. The corresponding documents are kept in the Workspace folder. Conversely, a "non-persistent" object lays within a program but cannot be manipulated as an independent file.

PredicateA predicate verifies the property of a thing or a relation between two things. It has two possible answers : "true", and "false", that is, "t", or "nil" in Lisp.

Rhythm Tree A rhythm tree expresses a rhythmic structure as a list. We use the term of "tree" because this structure is alike a tree structure.

This list has :

a duration, or number of measures,a time signature,a list or proportions, or rhythmic values.

For instance : (1 ((4//4 (1 1 1 1))) means one measure, four beats time signature, four whole notes.


Glo

ss

ary

of

Te

rms

SlotIn object oriented programming, a slot represents and attribute of a class. For instance, the class "note" in OM has 4 slots : pitch, duration, velocity, and MIDI channel.

StringA characters chain between two inverted commas.

Subdivisions of the whole note – memento Memento :

= 1, = 2, = 4, = 8, = 16, = 32, = 64

TemporalBoxA TemporalBox refers to an object in a maquette : an instance, a patch, or another maquette.

Temporal objectIn a maquette, any object provided with an explicit or computable duration, such as an audio fle, a chord object or a patch.

See also : Maquette.

User evaluation A user evaluation triggers one or more internal evaluation of the box and of possible upstream boxes connected to it.

Workspace OpenMusic's working environment. Each session starts with choosing a workspace, the equivalent of a desktop where programs are created and organized, and where items can be stored.

XMLExtensible Markup Language. Works with most applications. Advised format.


Glo

ss

ary

of

Te

rms