OpenMusic 6 Documentation 2403

OpenMusic 6 User Manual

OpenMusic 6 User Manual

AUTHOR,

EDITOR

: CORALIE DIATKINE

TECHNICAL

ADVISOR

: JEAN

D

O C U M E N T

BRESSON

V E R S I O N

# 1

© IRCAM – CENTRE GEORGES POMPIDOU

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

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou

7

Contents

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 8

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

Contents

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

Contents

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

10

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

I - Introduction Main principles, major references and links.

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou

11

I - Introduction

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.

12

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

I - Introduction

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/

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

13

II - System Confguration and Installation How to install OpenMusic on your computer, and what should be installed.

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou

15

II - System Configuration and Installation

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.

16

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

II - System Configuration and Installation

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

17

III - Going Through an OM Session This section provides technical information regarding the main procedures of a session, from starting to quitting OM.

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou

19

III - Going Through an OM Session

1. Launching OM Start Up The OM application – folder.

OM X.X.X

– is located in the OM

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.

20

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

III - Going Through an OM Session

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.

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

21

III - Going Through an OM Session

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

22

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

III - Going Through an OM Session

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

23

III - Going Through an OM Session

The Elements folder and the corresponding workspace window.

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

24

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

III - Going Through an OM Session

3. Quitting OM and Saving Quitting OM To quit OM : choose OM X.X.X / QUIT • press [CMD] + [Q]. •

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

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

25

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.

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou

27

IV - The OM Environment

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 :

28

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

IV - The OM Environment

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

29

IV - The OM Environment

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* workspace as well as in storage folders of the workspace.

, and maquettes*

. They can be added in the

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.

30

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

IV - The OM Environment

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

31

IV - The OM Environment

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 • choose FILE / GET INFO

item and select GET INFO in the contextual menu

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 CODE option.

32

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

LISP

IV - The OM Environment

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

33

IV - The OM Environment

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

34

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

default

IV - The OM Environment 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 / right click in the workspace and choose IMPORT FILE - FOLDER.

• [CTRL]

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

35

IV - The OM Environment

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

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.

36

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

IV - The OM Environment 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.

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

37

IV - The OM Environment

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 Libraries About Global Variables

38

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

IV - The OM Environment

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] / • click on

right click on the suitcase and choose OPEN CLASS TREE 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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

39

IV - The OM Environment

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 • select FILE / GET INFO •

an item and choose 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

40

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

IV - The OM Environment

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 / right click on a package and choose LOAD LIBRARY.

• [CTRL]

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

41

IV - The OM Environment

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.

42

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

IV - The OM Environment

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 .

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

43

IV - The OM Environment

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 Item Background Pictures in Patches and Maquettes

44

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

IV - The OM Environment

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

45

IV - The OM Environment

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.

46

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

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.

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou

47

V - Visual Programming

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.

48

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

49

V - Visual Programming

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.

50

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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 : (packagename (symbol-package 'class-or-function-name)). The corresponding package will be displayed. OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

51

V - Visual Programming

1.3. Boxes Morphology This section deals with function boxes 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 :

52

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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 PREFERENCES menu.

• •

via the OM 6.X.X /

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

53

V - Visual Programming

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

Copying a chord-seq box to another patch editor.

54

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

55

V - Visual Programming

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 it 2. type a value in the text field 3. 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.

56

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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 • deleting existing connections

not be connected to another one if this connection creates a cycle 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

57

V - Visual Programming

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 corner of the box icon. • •

icon appears on the upper left

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 :

58

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

59

V - Visual Programming

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 Inputs Getting 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.

60

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

61

V - Visual Programming

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

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

62

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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 :

•

t:

the Lisp expression for "true"

•

rational : a/b

•

nil :

the Lisp expression for "false" or "nothing"

decimal number

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

63

V - Visual Programming

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.

64

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

65

V - Visual Programming

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.

66

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

67

V - Visual Programming

Other Inputs / Outputs : Object Parameters Parameters The other inputs and outputs represent the various parameters, or class slots, used for defining an instance.

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.

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.

68

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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.

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

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 :

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

69

V - Visual Programming

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.

The default and specific score editors of the note class

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

70

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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 Functions A 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 !

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

71

V - Visual Programming

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

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

72

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

V - Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

73

V - Visual Programming

2.3.3. Additional Inputs : Optional and Keyword Arguments Arguments 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.

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

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

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

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.

86

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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 : 1. [CTRL] / right click in the 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

87

VI - Advanced Visual Programming

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 To copy and convert an internal patch into a global – blue – patch, drag it and drop it in the workspace.

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.

88

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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 open patch.

and

arrow icons in the

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

89

VI - Advanced Visual Programming

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.

Building successive chords from a chord multiplication.

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.

90

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

91

VI - Advanced Visual Programming

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.

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.

92

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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) * n For 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) + n For 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))

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

93

VI - Advanced Visual Programming

1.3.1. Recursion in OM Creating a Recursion

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

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

94

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

95

VI - Advanced Visual Programming

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 OM 1. "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...

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

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.

96

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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 mode 2. 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 Examples

icon appears on the upper left corner of the box.

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

97

VI - Advanced Visual Programming

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

98

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

99

VI - Advanced Visual Programming

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 Function A 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 Principles 1. 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.

100

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

101

VI - Advanced Visual Programming

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.

If the two functions were not on "lambda" mode, the list function would return a list that contains the result of these functions call. 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 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.

102

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

*

on Lambda

VI - Advanced Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

103

VI - Advanced Visual Programming

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.

104

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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 duplicate is removed.

are equal. If so, the

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

105

VI - Advanced Visual Programming

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

106

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

3. Control Structures It 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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

107

VI - Advanced Visual Programming

3.1.1. Algebraic Predicates Comparing 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

108

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 superior to B ?

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

3.1.2. Equality Predicates In 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 identical objects with the same reference integers 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 or eql objects structurally similar objects

strings with identical glyphs floats of same value • In some cases, equal considers the object. In other cases, equal considers the concept.

EXAMPLES eq A A → t eq 2 2/1 → t eq A a → t eq "A" "A" → nil eq (A B C) (A B C) → nil eq 2.5 2.5 → nil equal (A (b) C) (a (B) c) → t equal "A" "A" → t equal "A" "a" →nil equal 2.5 2.5 →t

eq, eql or equal objects equalp "A" "a" → t strings with similar glyphs equalp 2 2/1 → t numbers of same numerical value equalp 2.5 2.5 → t • Equalp only considers values and concepts, not their equalp 2 2.0 → t representation.

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 :

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

109

VI - Advanced Visual Programming

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

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

110

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.

nullp

anything that is nil.

typep

an object of a given type.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

→t nil → t ; ( ) → t

VI - Advanced Visual Programming

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 numberp 2. a list 3. 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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

111

VI - Advanced Visual Programming

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, Else The 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.

112

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

113

VI - Advanced Visual Programming

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.

114

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

115

VI - Advanced Visual Programming

3.3. Logical Operators Omor, Omand Omor and omand conjunctions.

are boolean logical operators that stand for the "and" and "or" coordinating

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.

•

116

Logical operators are also used for associating several predicates in a single proposition.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

117

VI - Advanced Visual Programming

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.

118

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

119

VI - Advanced Visual Programming

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 :

120

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

121

VI - Advanced Visual Programming

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

122

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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 :

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

123

VI - Advanced Visual Programming

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.

The seven slots of a chord-seq. The six first slots take lists, the last slot takes an atom.

A slot editor displays navigation arrows, and, for each component, a value and a corresponding index.

124

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

•

To edit the value of a component : 1. double click on the numeric frame 2. enter a new value and validate.

Editing the first value of the "midic" slot : the pitch of the first chord. Notice the navigation arrows on the top of the editor.

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 it 2. 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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

125

VI - Advanced Visual Programming

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. Instances and Global Variables 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 A global variable box can be connected to other boxes, just as an instance box.

126

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

127

VI - Advanced Visual Programming

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* package of the Library.

.

to a workspace where they will be stored in the Globals

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.

128

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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. 2. 3. 4.

connect the instance to the "self" input of slots, enter new values in the relevant input of slots, evaluate slots, reopen the instance editor.

Note that the reference of the object hasn't changed, despite the fact the object's content has changed.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

129

VI - Advanced Visual Programming

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.

130

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

131

VI - Advanced Visual Programming

Setting the Value of a Store Object With a Store Factory Box 1. 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 it 2. 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.

132

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

133

VI - Advanced Visual Programming

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

The OMLoop editor resembles a patch 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.

134

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

Adding Inputs and Outputs 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 [ cf "Evaluate-Once Mode", page 98.

136

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

137

VI - Advanced Visual Programming

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.

138

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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 click and type a name.

• [CMD]

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

139

VI - Advanced Visual Programming

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

140

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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.

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.

4 - > cf "Listloop : Enumerating the Elements of a List", page 140.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

141

VI - Advanced Visual Programming

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

142

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

143

VI - Advanced Visual Programming

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

144

•

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

145

VI - Advanced Visual Programming

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.

146

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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

Example 1. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

147

VI - Advanced Visual Programming

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 List 1. 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.

148

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VI - Advanced Visual Programming

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 function 2. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

149

VI - Advanced Visual Programming

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

178

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

179

VII - OM Objects

•

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 100 Add [SHIFT] to change the value by steps of 10.

180

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

181

VII - OM Objects

1.3.5. Harmonic Objects : Note, Chords and Chord-Seqs Editors Notes, 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 tool 2. [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 tool 2. [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.

182

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

To edit a chord in an INTERNAL

CHORD

VII - OM Objects

•

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 aChord-seq

1. Select the note, chord or poly tool. 2. [CMD] click in the staff.

Deleting Items 1. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

183

VII - OM Objects

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

The order and offsets of the pitches in the list can be expressed via the Order and Offset modes of the Editor Control.

Features The EDITOR CONTROL menu allows to modify the displaying of chords. Notes can be ordered according to their : • • •

184

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. OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

185

VII - OM Objects

Legato To display the legato value of notes in a chord-seq, select the the editor control.

DURATION

menu item in

Reminder : Pitch Modifications can apply to notes, or to whole chords or chordseqs . 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 [ ] .

186

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

1.3.6. Rhythmic Objects : Voice Editor The 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 press [ESC].

, select the measure and

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

187

VII - OM Objects

Manipulations Chords To tie successive chords, press [=]. To untie them, press [/] . Groups •

To get a group : 1. select a chord 2. 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 clef 2. 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.

Transposing an entire voice. 188

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

The second mesure of the first voice shows three groups levels nested within each other. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

189

VII - OM Objects

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 voices at once.

, which allows to edit all

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.

190

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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 voice 2. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

191

VII - OM Objects

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

192

SIZE

menu.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

Margins To modify the page margins : 1. 2. 3. 4.

[CTRL] / right click in the editor.

Select the PAGE LAYOUT menu item in the contextual menu. Enter margin values 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] . •

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

193

VII - OM Objects

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.

The microplayer interface.

194

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

1.3.10. Tonal Display Tonal 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. 2. 3. 4.

select the editor and press [T]. A tonality dialogue window pops up. Select the MINOR or MAJOR mode in the pop up menu, and a key signature via the < and > buttons. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

195

VII - OM Objects

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.

196

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

197

VII - OM Objects

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

198

•

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

•

1/5, 1/7 tone scales and their multiples : they use additional combination of horizontal lines.

arrowheads with horizontal lines.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

1/2 Tone and Elementary Multiples

1/3 Tone and Elementary Multiples

1/5 and 1/10 Tone

1/7 and 1/14 Tone

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

199

VII - OM Objects

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

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.

200

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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 numbers 4. "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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

201

VII - OM Objects

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.

202

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

2.1.3. Bpfs and Bpcs Editors Bpfs 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.

The bpf editor and the edition palette.

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

203

VII - OM Objects

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

204

with a click and drag with a selection and the [ ] keys.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

205

VII - OM Objects

B) Display Tools and Options Curve and Points Show / Hide Points

To display or hide the points of a curve, click on or outside it.

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 point of the curve, in order to get a polyhedron.

206

BPC

option. This option allows to connect the first and last

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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

Zooming in a bpf.

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

.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

207

VII - OM Objects

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.

Displaying a grid in a bpf editor.

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.

208

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

Displaying the spline of a curve.

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 frames 2. scroll the mouse up or down to change the value.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

209

VII - OM Objects

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.

Selecting a curve and hiding the background.

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.

210

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

211

VII - OM Objects

2.1.4. Bpf and Bpc Tools Overview A 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 : • • • •

212

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

213

VII - OM Objects

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

214

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

215

VII - OM Objects

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

216

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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 [ cf "Creating and Using a Pathname in a Patch", page 152.

224

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

225

VII - OM Objects

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

226

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

TO

FILE in the

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

227

VII - OM Objects

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 box 2. 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.

228

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

229

VII - OM Objects

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 something in a file.

writes

•

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

230

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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 pathname 8. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

231

VII - OM Objects

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

232

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

Reading and collecting the contents of the six first lines in a file – loop from 0 to 5.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

233

VII - OM Objects

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. It has one input and one output : • •

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

234

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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 .

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

235

VII - OM Objects

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

Here, an Initdo module has been added to the program, so that a text header is added before the strings. 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.

236

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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 inputs

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

237

VII - OM Objects •

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

238

the header printed by Initdo the lines printed by Eachtime.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

239

VII - OM Objects

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 Boxes Dialog 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 : • •

240

"text" input : a string* or something to display "text" output : returns the current text in the box.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

241

VII - OM Objects

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 interface 2. 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".

242

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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

Using a directory to initialize the menu contents.

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

243

VII - OM Objects

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.

244

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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 Program For a Musical Application

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

245

VII - OM Objects

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-itemlist-box is edited and used as as single-itemlist-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 : • •

246

when the box is assigned a new list of items, if the box is not locked. OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

A Musical Application : Building a Triad The "chord builder" patch creates a minor or major triad, with three types of interface boxes : the multipleitems-list-box, the button-box, the check-box.

•

On the left, the BUILD NOTE! 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 BUILD CHORD! 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

247

VII - OM Objects

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. 2. 3. 4. 5.

" direction " : the slider's vertical or horizontal orientation. " range " : slider range, from a minimum to a maximum value. " step " : the precision of the slider – should be equal to 1. " initial value " : initial position of the slider. " 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 boxes 2. 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) 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.

248

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

249

VII - OM Objects

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. It has one input and one output : • •

"self" : another picture box its output returns the reference of the picture.

To add a picture box into a patch, select CLASSES / INTERFACE BOXES / 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.

250

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

251

VII - OM Objects

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 Double click on a picture box. Its editor opens, along with a drawing palette .

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.

:

: "arrow" tool

"circle / ellipse" tool

: "square / rectangle" tool

"polygon" tool

: "line" tool

"text" tool Click and draw in the editor to create – additional graphics in the picture editor.

252

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VII - OM Objects

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

Chooser.

Commands and Menus Selection / Remove •

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.

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. OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

253

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 • a "musical value ", produced in the maquette's context.

maquette's context.

To a certain extent, the maquette can be considered a patch.

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou

255

VIII - Maquettes

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

256

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

257

VIII - Maquettes

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.

258

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

259

VIII - Maquettes

TemporalBox Icon To display the TemporalBox reference icon, select the tab

SHOW BOX ICONS option of the MAQUETTE PREFERENCES

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 Maquettes Adding and Deleting Boxes from the Outside of a Maquette

260

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

261

VIII - Maquettes

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

262

press [ALT] + and drag the item use the EDIT menu commands and shortcuts – Copy, Paste, Duplicate....

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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 frame 2. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

263

VIII - Maquettes

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. 2. 3. 4. 5.

click on the colour icon of the corresponding box. pick a colour in the Colour Chooser choose [OK] . select [APPLY] or [CANCEL] , select [OK] to validate your choice.

Select [RESTORE] TemporalBoxes.

to

reset

the

default

preferences

of

the

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

264

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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. Patches The " 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

265

VIII - Maquettes

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.

Here, the temporal object just performs an addition. It is not connected to any item, and its value is not displayed in the maquette.

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.

266

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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 :

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

267

VIII - Maquettes

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.

268

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

Instances modified in the maquette 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

269

VIII - Maquettes

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. 2. 3. 4.

Click on the DEFAULT COLOUR frame of the maquette. Pick a colour in the Colour Chooser, and select [OK] . Select [APPLY] or [CANCEL]. Select [OK] to validate your choice.

Select [RESTORE] to reset the default preferences of the maquette.

270

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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 Procedure Modifying 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].

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

271

VIII - Maquettes

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.

272

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

273

VIII - Maquettes

•

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

The ((6 8) (3 8) (3 4) (6 4)) pattern and the "Repeat Last Measure" option.

Grid and Metric Ruler The grid fits the measure unit of the metric ruler. Memento : Subdivisions = 1; 274

= 2; = 4;

= 8;

= 16;

= 32;

= 64...

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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 :

applies to the whole maquette.

Play

Play selection : applies to a selected temporal segment, or selected boxes. Loop :

a switch on/off to associate with whole maquette repeatedly.

or

to play an item, temporal chunk or a

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

275

VIII - Maquettes

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 Info 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].

276

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

277

VIII - Maquettes

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

278

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

Instances and Global Variables 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

279

VIII - Maquettes

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 " => #". 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.

11 - > cf "Evaluate-Once Mode", page 98.

280

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

281

VIII - Maquettes

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. 2. 3. 4.

the maquette's value itself, the duration of the maquette, the list of boxes contained in the maquette, the list each box's value contained in the maquette.

The Synthesis Patch Creating and Implementing the Patch

282

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

This synthesis patch prints the list returned by the Maquette Self Input : its reference, duration, TemporalBoxes references, and the objects contained in the TemporalBoxes. Assigning a Synthesis Patch via a Maquette Input bbbbbbbbbbbb

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

283

VIII - Maquettes

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.

284

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

OMLoop The value of the Maquette Self Input is returned to OMLoop's input.

Inside the OMLoop : building the melodic sequence from the TemporalBoxes parameters.

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

285

VIII - Maquettes

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 reference label.

label to display the

Maquettes on "Reference" Mode

286

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

287

VIII - Maquettes

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

288

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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 6. posy : "self" output

vertical position

2. offset :

starting point of the box in 7. stretch-fact : milliseconds

time stretch factor, expresses the size modification of a TemporalBox

3. extend :

calculated duration

8. sizey :

vertical size of the box

9. free-store :

a "free" parameter

4. color box colour frame : 5. value :

whatever is connected to the 10. reference : Tempout of a TemporalBox.

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

289

VIII - Maquettes

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" 2. validate while keeping [SHIFT] pressed. 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 Patch Using 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.

290

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

291

VIII - Maquettes

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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 #2 1. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

293

VIII - Maquettes

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 –

294

and outputs –

– are hidden outside the maquette.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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 ==> (# # # # #). • •

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. OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

295

VIII - Maquettes

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.

296

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

297

VIII - Maquettes

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.

298

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

Evaluating the Maquette

Completing the sequence

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

299

VIII - Maquettes

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" 2. validate while keeping [SHIFT] pressed.

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.

300

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

5.3.1. Reference Mode : Adding TemporalBoxes in a Maquette Before 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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

301

VIII - Maquettes

Reference and Value Inputs of the TemporalBox A TemporalBox instance is an actual program, which can : • calculate and yield an object via its internal • be given a value via the "value" input, • refer to an object via its "reference" input.

program,

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" input 2. another chord, via a "value" input 3. 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. • •

302

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

303

VIII - Maquettes

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 SHOW BOX ICON option is selected in the maquette preferences.

, which show a small OM icon if the

The maquette, after the first evaluation of addbox2maquette.

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.

304

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes After the second evaluation of the function.

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

305

VIII - Maquettes

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.

306

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

5.3.3. Accessing TemporalBoxes of a Maquette from a Patch Accessing 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

307

VIII - Maquettes

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

308

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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 50 3. 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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

309

VIII - Maquettes 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.

310

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

311

VIII - Maquettes

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.

312

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

VIII - Maquettes

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.

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

313

VIII - Maquettes

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 values 4. Finally returns the resulting list of values.

Resulting Sequence The evaluation of the chord-seq box in the patch yields the following sequence :

314

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

X - Errors and Problems ...

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou

315

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 selected in the PREFERENCES pane, an error window opens.

HANDLE ERROR MESSAGES

If not, the error will propagate and the LISP TERMINAL window will open.

316

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

option was

X - Errors and Problems

2. The Lisp Terminal Window In the case of more important, unpredicted errors, or if the Lisp Terminal opens.

HANDLE ERROR MESSAGES

option wasn't selected, the

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

An error in the Mac OS system Terminal

Stuck Application If OM gets stuck, type [CMD] + [SHIFT] + [A].

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

317

Glossary of Terms Argument

An argument represents a parameter upon which a function operates. For instance, the (om+ x y) function has two arguments : x and y. Break Point Function

A "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-Seq

OM name of a chord sequence. By extension, a note sequence, since a single note can be considered a chord. Class

A 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. Container In

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

Extensible Transportable Format, originally developped by Finale. Evaluation

Triggers 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 box

A box used for creating an instance, or exemplar, of a given class within a visual program.

OpenMusic 6 User Manual © Ircam - Centre Georges Pompidou

319

G l o s s a r y o f Te r m s

Function

A 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 function

In 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 variable

An 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. Group

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

Instance

An 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. click on an outlet – especially the first outlet representing the self, the whole object – of a factory box to materialize an instance. [SHIFT]

Internal evaluation

Evaluation of a box by OM, triggered by a user evaluation, or by the internal evaluation of an upstream box connected to it. Iteration

The repetition of a process within a computer program. See also : Recursion. Lisp Listener

A Lisp communication interface displaying results of computations, warnings or error messages, and where Lisp expressions – programs – can be evaluated.

320

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

G l o s s a r y o f Te r m s

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

A matrix is a rectangular array of m*n numbers, with m rows and n columns, such as : 123 456

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 Midicent

A 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 → mc

Converts 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. Package

Contains 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, Persistence

A 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. Predicate

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

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou

321

G l o s s a r y o f Te r m s

Slot

In 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. String

A characters chain between two inverted commas. Subdivisions of the whole note – memento Memento : = 1,

= 2,

= 4,

= 8,

= 16,

= 32,

= 64

TemporalBox A TemporalBox refers to an object in a maquette : an instance, a patch, or another maquette.

Temporal object In 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.

XML Extensible Markup Language. Works with most applications. Advised format.

322

OpenMusic 6 User Manual (c) Ircam - Centre Pompidou