Next: , Previous: Reference, Up: Reference

5.1 Objects

Information is communicated to FOMUS through the definition of “objects” (i.e., in a .fms file or in a programming environment like Lisp or SAL). Examples of objects are parts, instruments, notes, measures and the score itself, which must all be defined to give FOMUS a complete set of instructions for notating a score. Object definitions may contain one or more “settings” which directly affect how the objects are processed or interpreted. Examples of settings are beat, which determines how note events are spelled rhythmically, and keysig, which determines what key signature appears in a measure. Object definitions may also contain parameters (e.g., id and template) that aren't actually settings (settings have a specially defined behavior, as explained below) but are instead part of the structural makeup of the object itself.

One of the most important of these parameters is id. If an object is defined with a unique ID, other objects can then use that ID to refer to it. If two objects of the same class are defined with the same ID, the later definition replaces the earlier one (more specifically, the old one still exists but can't be referred to anymore since it's ID has been moved to another object).

FOMUS's objects are arranged hierarchically and “contain” other objects or refer to other objects in some way (e.g., parts refer to instruments via the inst parameter or instruments can optionally contain one or more percussion instruments using the percinsts parameter). When one object contains or refers to another, you must either use an ID or define the sub-object inline inside the parent object. Also, the id parameter is mandatory when defining an object at the “top level” (i.e., when an object is not part of or embedded in another object).

Settings in “container” objects (like parts or measures) generally affect everything that's contained in that object. If you set the keysig setting in a measure, for example, it only affects that measure. If you set keysig in a part, though, it affects all measures in that part (unless overriden by another keysig setting in an individual measure). In the same way, setting keysig in the score object affects all parts and measures in the entire score. Setting values are thus inherited in smaller objects from larger ones. Many settings can be set in any object class while some can only be set in specific places (e.g., the score). The Settings section of the reference contains information on how individual settings may be used and which objects they may appear in.

Following is a complete list of FOMUS's object classes and their parameters:

•The Score Object
You must create a single instance of this to generate a score. In most of the frontends there is a special way of doing this. In CM, for example, the command is ‘fms:create-score’. In Lisp there is a macro called ‘fms:with-score’. In Pd a score object is created whenever a fomus external is created.
•Parts
All scores must contain at least one part. If one isn't given, a default one is supplied (with ID ‘default’). A part represents a staff (or grandstaff) in the score and contains measures (which themselves contain notes, rests and marks).

Parts generally appear in the score in the same order that they are defined in. If the layout-def or layout setting is defined, the order and grouping changes according to the layout (though parts based on the same instrument still appear in their defined order).

•Instruments
Instruments contain all of the settings necessary for properly notating a part. Most of the time, you'll use a preexisting one either as is or as a template in a score. If you find yourself defining an instrument from scratch over and over, it might be useful to add your definition to inst-defs so that you can reuse it. The setting inst-defs functions as a library of predefined instruments. Add your own instruments to this library by placing a line like ‘inst-defs += (<id: inst1 ...> <id: inst2 ...> ...)’ in your .fomus file.
•Percussion Instruments
When percussion instruments are contained or defined inside instrument objects, they modify the instrument in several ways. Note events that are sent to a part that contains percussion instruments may specify a percussion instrument ID in place of a numeric pitch value. The settings in the percussion instrument then determine which voice the note event is assigned to and where the note appears on the staff. A percussion instrument's name (defined with the name setting) can also appear in the score wherever a change occurs. By changing the settings in percussion instruments and moving them around between different instruments, it is easy to change how percussion parts appear in the score and how they are divided up among players.

If you find yourself defining a percussion instrument from scratch over and over, it might be useful to add your definition to percinst-defs so that you can reuse it. The setting percinst-defs functions as a library of predefined percussion instruments. Add your own instruments to this library by placing a line like ‘percinst-defs += (<id: percinst1 ...> <id: percinst2 ...> ...)’ in your .fomus file.

•Metaparts
Metaparts differ from parts in that they don't appear in the score. Instead, they contain other parts (or other metaparts) and treat them all as one single part. This allows you to group together the parts in a string quartet and treat the quartet as one part, for example. Each actual part would be a single voice in the whole metapart. An entire orchestra could also be represented as a hierarchy of metaparts with instructions for doubling voices and grouping instruments in various ways.

At a certain point in FOMUS's processing, metapart events are copied into their proper parts and the metaparts themselves are destroyed. The instructions for copying events are contained in the metapart and partmap settings. Each partmap basically contains a reference to one part/metapart and describes how note events are distributed (and possibly transposed or doubled).

Metaparts currently don't have instruments associated with them (this might change in future releases). Metapart settings only affect measures and note events up until when they are copied to their new locations, at which point the settings of the new part/instrument take effect.

•Measure Definitions
A measdef is a definition for a measure event or group of measure events. The difference between a measure definition and a measure event is that the latter has a time and duration, appears in the score and may inherit settings from the former, while the former is just a collection of settings and values. When you create a measure event, you may refer to a measdef which contains all of the settings for that measure.

Measure definitions are mostly useful in .fms files where they are used to avoid redundancy when defining measure events. The typical usage is to define a few measdefs at the top of the file and refer to them by ID when creating new measures.

In most other environments it's easier to include all of the settings inside the measure itself rather than bother with defining measure definitions separately.

•Staves
Staves are defined as part of an instrument definition. Each instrument must contain at least one staff. Each definition represents an actual staff in the score and also contain one or more clef objects.
•Clefs
A clef object represents a clef choice within a staff. A staff must therefore contain at least one clef definition. Most of an instruments layout settings are defined in clefs, including how many ledger lines are allowed before a staff switch or octave change sign occurs, how often the clef itself should be chosen over the other clefs, and whether or not octave change signs are allowed.

A keyboard instrument might, for example, contain two staff objects, each of which contain two clef objects, one treble and one bass. The settings in the four clef objects would then influence how they are chosen and how notes should be laid out on either staff.

•Import Definitions
Import objects contain the necessary information for reading file formats other than .fms files (e.g., MIDI files). Incoming data is matched against import objects (using the settings defined in them). When a match is found, the data is sent to the part that contains the instrument/percussion instrument with the matching import object. Settings in the import object might also modify the incoming data in some way.

See MIDI Import Examples for examples of using import objects.

•Export Definitions
Export objects contain the necessary information for writing file formats other than .fms files (e.g., MIDI files). FOMUS looks up the export definitions in each part when necessary to determine how to output data.

See TODO for examples of using export objects.

•Partmaps
Partmaps are used to map events from metaparts to actual parts. The part being mapped to is defined with the part parameter. Typical partmap settings are from-voice, which designates the voice or voices events are being copied from and to-voice, which designates the voice or voices events are being copied to. Multiple partmaps can copy the same events to multiple places. They can also transpose note events and do other simple modifications as they are being copied.