FOMUS Documentation

This slot isn't used by FOMUS. The user may use it to store an ID value or some miscellaneous data.

This is a symbol or number used as an index or reference to identify the part. It doesn't need to be unique--parts that share the same ID symbol are treated as a group. When they appear in PARTID or PARTIDS slots in classes other than the PART class they are treated as references to a particular part or group of parts.

This is a string value representing the part name that is to appear on the score.

This is a string value representing the abbreviated part name that is to appear on the score.

This slot specifies an instrument for the part. All part must be associated with an instrument--if no instrument is given a generic default instrument will be chosen. Instruments provide important data for many of FOMUS's algorithms and determine at least several major aspects of score layout, including the number of staves a part has and whether or not pitches are to be transposed.

Instruments may be specified in one of several ways. If a symbol is provided, it is used to lookup an instrument in a user-defined list or FOMUS's own predefined list of instruments (see the INSTR-GROUPS setting in the Settings chapter). The slot may also contain an instance of an instrument object. If a list is given, FOMUS expects the first element to be a lookup symbol for an instrument and the rest of the list to be keyword/argument pairs specifying slots that are to be modified in the original instrument (as if included in a call to COPY-INSTR.

'(:piano :staves 3 :simultlim 6)
                

If an integer from 0 to 127 is provided instead of an identifying symbol, FOMUS interprets this as a MIDI program change number and will use the first instrument it finds that has this number in its MIDIPRGCH-IM slot.

This is a list of NOTE, REST or MARK objects. TIMESIG and KEYSIG objects may also be included in this list.

Part properties are specified in the same way MARKS are specified. They are settings that affect only the part they are included in. See PART Properties for a list of these.

This is a keyword/argument pair list specifying options to be passed directly to the backend algorithms. Each backend has its own set of options that may be specified alongside options for any other backend. See the Outputs for more information.

This slot isn't used by FOMUS.

This is a reference to a particular part or group of parts. If the value of this slot is NIL, the time signature is applied to all parts that don't have some another TIMESIG object defined for them if this TIMESIG object is included in the GLOBAL list. If the TIMESIG object is in a PART object's EVENTS slot, the time signature is applied to the part. If the value is a symbol, number, or list of symbols or numbers, these values are used to lookup which part or parts the event belongs to.

This is a number (real, ratio or integer) specifying the absolute position for the onset for this note. The offset is measured in "beats," which may indicate different notational positions depending on previous time signatures and what values are present in their BEAT slots. The number must be precise and "notatable" (floating point numbers are not recommended and values like 10/3 that don't occur on regular beat divisions are currently impossible for FOMUS to notate).

This is a required list of two integers, specifying the numerator and denominator of the printed time signature.

If this slot is set to T, indicates that the measure is a compound meter. The denominator of the time signature then determines the beat value.

The BEAT slot value determines how events are mapped from beat units to notational durations. It is a ratio that specifies what notational duration is equivalent to 1 beat. This duration is expressed as a fraction of a whole note (1/4, for example, specifies a quarter note, 1/2 specifies a half note, and 3/8 specifies three eight notes). If the time signature is a compound time signature, the value of this slot is ignored and the beat value is calculated from the denominator (for example, the beat value of a 12/8 signature is 3/8). If the slot contains the default value of NIL, the beat value is either the value of DEFAULT-BEAT or it is calculated from the denominator (a non-compound 4/8 or 7/8 time signature would have a beat value of 1/8). Different beat values have an effect on how measures are divided and laid out, so they should be chosen to influence these things.

This is a single list or list of lists containing ratios or integers that add up to the total number of beats in a measure (as specified by either the TIME or BEAT slots). It represents all of the choices available for dividing up measures following this time signature. If the slot contains the default value of NIL, FOMUS looks up divisions first in a user-supplied table if one exists (see the DEFAULT-MEAS-DIVS setting) then in FOMUS's default table. A value usually only needs to be specified here if the user wants to force FOMUS to divide measures in a specific way rather than choosing between several choices. The following example shows what might be specified for a 7/8 meter:

'((4 3) (3 4))
                

As another example, setting the TIMESIG-DIV slot to '(1 1 1) in a 3/4 time signature forces FOMUS to beam measures in groups of 3 (the default is equivalent to a TIMESIG-DIV setting of '((2 1) (1 2)))/

This is a list of TIMESIG or TIMESIG-REPL objects that are chosen to replace this TIMESIG object when FOMUS needs to change the length of a measure. This gives the user some control over how FOMUS fudges measures to make them fit. When FOMUS changes the length of a measure, it will look here first and then in the (not implemented yet) setting for a replacement that fits (has the correct number of beats). If none is found, FOMUS will create a new TIMESIG object from the current one, modifying the DIV slot by adding on extra beats if necessary.

TIMESIG-REPL objects are simply TIMESIG objects with missing OFF, PARTIDS and REPL slots, all of them unnecessary in this context. The use of these is optional. If TIMESIG objects are given, these slots are just ignored.

This slot behaves like the MARKS slot in NOTE or REST objects. Extra time signature or measure properties may be specified here. See FIXME for more details and the MARK class for an example of how to specify properties.

This slot isn't used by FOMUS.

This is a reference to a particular part or group of parts. If the value of this slot is NIL, the event is included in whatever part contains it in its EVENTS slot list, or to all parts if it is included in the global EVENTS list. If the value is a symbol, number, or list of symbols or numbers, these values are used to lookup which part or parts the event belongs to. Events belonging to multiple parts are effectively copied into these parts.

This is an integer or a list of integers specifying a voice or selection of voices that this note should belong to. Voice numbers are limited to the integers 1 through 4. The default value NIL specifies voice 1. If a list of choices is given, FOMUS's voice distribution algorithm will try to make an intelligent decision based on voice leading, pitch, balance and other factors. Note that REST and MARK objects are treated slightly differently. Settings with the VOICE- prefix can be adjusted to influence FOMUS's voicing decisions. See Settings for more information.

This is a number (real, ratio or integer) specifying the absolute position for the onset for this note. The offset is measured in "beats," which may indicate different notational values depending on what the current time signature is and what value is present in its BEAT slot. FOMUS's quantizing algorithm tries to fit all offsets and durations into values that make the best use of tuplets within given constraints while minimizing the amount of error. If this quantizing algorithm is switched off, then the user must insure that all offset and duration values are precise and "notatable" (floating point numbers are not recommended in this case).

This is set to either a number to specify a regular duration or a list to specify a grace note. If it's a number (real, ratio or integer) it indicates the note's duration in beats (see EVENT-OFF above). The comments in EVENT-OFF on quantization also apply here. If Common Music is present and USE-CM is set to T, the value of this slot may also be a symbol, which is parsed by CM using its RHYTHM function. Symbols in this case designate notational values and not beats, although numbers are still interpreted with respect to beats and not filtered through CM's RHYTHM function.

If a grace note is desired then a list of two elements must be specified, the first element being the duration value described above and the second element being an integer value describing the "position" that the grace note occupies. Grace notes with the same offset are organized with respect to this position number. Lower position grace notes occur earlier in the score than higher position notes. Also, grace notes with the same position form chords, and notes with negative positions are notated with a slash. The duration value at the front of the list is still interpreted in terms of beats and notated as such even though the note does not take up time in the measure. Specifying a duration of '(1/4 -1), for example, specifies a grace sixteenth note with a slash if the current beat is 1/4 (a quarter note).

This slot either designates a pitch (with an optional choice of spellings) or a percussion instrument if the part is a percussion part. If specifying a pitch, the value may be either a symbol or a number (real, ratio or integer). If a number is used, 60 represents middle C, as in a MIDI file. Numbers are rounded depending on the whether semitones or quartertones are specified (see the QUARTERTONES setting). Symbols are assembled by concatenating a note letter name (A through G), a + or S for sharp or a - or F for flat, and an integer designating the register (4 is the octave above middle C). A few examples are given here:

'c+4
                

'ef5
                

Quartertones must be specified using numbers. If Common Music is present and USE-CM is set to T, symbols are filtered through CM's KEYNUM function. In this case, the value of CM-SCALE will also be passed to the function if it is set to anything other than NIL.

If a list of spelling choices is supplied, FOMUS will try to use the note spellings in this list. To specify one, the value of the NOTE slot must be a list, the first element of which is the note number or symbol described above and the rest of which is the list of spelling choices. A spelling choice is represented either by a number or symbol. 1, + or S designates using a sharp while -1, - or F designates a flat. 0, N designates a natural while repeating one of the above symbols (for example, ++ or SS) designates a double sharp or flat. 2 or -2 also designates a double sharp or flat. Quartertones spellings are specified using a list of two elements, the first element specifying the semitone alteration and the second element specifying the quartertone alteration (one of the numbers -1/2, 0 or 1/2). A few examples are given here:

'(f4 + --)
                

'(61.5 (n -1/2))
                

If FOMUS's note spelling algorithm is switched off then all note spellings must be supplied by the user (so each NOTE slot must contain a list of two elements specifying the pitch and its spelling, unless it is spelled with a natural).

This slot is nearly equivalent to the MARKS slot in the MARK class described below. The contents of the MARKS slots of MARK objects are actually dumped into the MARKS slots of NOTE and REST objects once voices and staves have been decided. See the MARK class for more information and Marks for a more detailed explanation of marks and their usage.

This slot isn't used by FOMUS.

This slot is equivalent to the PARTID slot in the NOTE class.

This slot is analogous to but different than the VOICE slot in the NOTE class. The difference is that when set to a list of voices, the REST object is distributed to all the specified voices instead of one that is chosen by FOMUS.

This slot is equivalent to the OFF slot in the NOTE class.

This slot is equivalent to the DUR slot in the NOTE class with the exception that rests cannot be grace notes.

This slot is equivalent to the MARKS slot in the NOTE class. However, the number of marks that can be used in the REST class is limited. See the MARK class for more information and Marks for a more detailed explanation of marks and their usage.

This slot isn't used by FOMUS.

This slot is equivalent to the PARTID slot in the NOTE or REST class.

This slot is equivalent to the VOICE slot in the REST class, with the exception that a staff or list of staves can be specified instead of voices. Staves are indicated with a list beginning with the symbol :STAFF followed by one or more integer values. The integers represent staff choices and can either be negative or positive, negative indicating that the mark be placed in the uppermost voice of the staff (the staff number is the absolute value of the number given in this case) and positive indicating that the mark be placed in the lowermost voice of the staff. FOMUS chooses the option from the list that places the mark the closest to the specified offset. Following is an example of how to specify staves:

'(:staff 1 -2)
                

Specifying a choice of staves like this allows the user to place marks like dynamics that apply to all voices but only need to appear in one place. In the case of the example above, a mark with this value in its VOICE slot that is applied to a grand staff is attached to a note in a voice on the inside of the staff.

As in the case of the REST class, when set to a list of voices, the MARK object is distributed to all of them.

This slot is equivalent to the OFF slot in the NOTE or REST class, with the exception that offsets may also be wrapped inside a list and given a positive or negative value (for example, '(3), '(11.5) or '(-11.5)). When this list is used, it indicates that the marks in the MARKS slot are applied to events just before or after the given offset depending on its sign. Positive offset values indicate the mark is to applied to the event just following the offset and negative values indicate the mark is to be applied just before it (the absolute value of it). This makes it easier in some cases to place marks that indicate ends of spanners such as slurs, since marks that indicate the end of the spanner can actually be given the offset where the next spanner begins. FOMUS will place the end mark in the proper place (the event that immediately precedes the one at the indicated offset).

MARKS slots contain lists of marks. (In a NOTE or REST object, these marks are "attached" to that event.) Marks are specified as either symbols or lists of symbols and numbers. If it is a list, then the first element is the mark symbol followed by one or more arguments. Following is an example of what may appear in the MARKS slot:

'(:accent :startslur- (:startslur- 2 :dotted) (:texttempo "accelerando"))
                

The MARK class can contain one extra mark that NOTE or REST objects can't contain. The symbol itself is :MARK and actually specifies another mark that is to be placed in the same voice at a different offset. It has the following format: '(:MARK off mark ...), specifying that another mark is to be placed in the same voice at the offset given. This special mark is necessary if the user specifies a staff instead of a voice and the mark is a symbol indicating the start of a spanner. It can also be used as a convenience, since only one MARK object needs to be instantiated to specify several marks that belong together. By specifying the end symbol here as part of a MARK mark, FOMUS recognizes the start and end marks as belonging to each other and will place them in the same voice. (Starting and ending marks that aren't paired in the same voice cause errors.) The offset argument that is the second element in this list uses the same extended syntax as the OFF slot in this class. The rest of the list after the second element is the mark symbol and the arguments that apply to that symbol. Following is an example:

'(:accent (:startslur- 2) (:mark (-101) :endslur- 2))
                

The contents of the MARKS slots of MARK objects are dumped into the MARKS slots of NOTE and REST objects once voices and staves have been decided. See Marks for a more detailed explanation of marks and their usage.

This is a unique symbol identifying the instrument. It is used as a lookup value so that it may easily be specified in PART objects.

This is either a symbol or list of symbols, specifying valid clefs for the instrument in order of preference. The following clefs are supported: :bass, :c-baritone, :f-baritone, :tenor, :alto, :mezzosoprano, :soprano, :treble and :percussion. The user may also add an -8UP or -8DN suffix to the symbol to specify an octave transposition.

This is an integer specifying the number of staves to use. The default is 1.

This is an integer specifying the lowest pitch in the instrument's range. It may also be set to NIL, in which case the lower range is considered to be unlimited. This is only useful if the CHECK-RANGES setting is set to T.

This is an integer specifying the highest pitch in the instrument's range. It may also be set to NIL, in which case the upper range is considered to be unlimited. This is only useful if the CHECK-RANGES setting is set to T.

This is an integer of 1 or greater specifying the maximum number of simultaneous pitches allowed in a single voice. It may also be set to NIL, indicating that there is no limit.

This is set to the value NIL or an integer indicating the number of semitones to transpose the instrument before notating it. This number only has an effect if the TRANSPOSE setting is set to T.

The value of this slot influences how FOMUS decides when to change clefs. A clef change isn't considered necessary until the number of ledger lines required exceeds a threshold value. Other factors determine if there is actually a clef change or not. If the value is an integer, it designates the threshold number of ledger lines in all cases. If it's a list, the first element of the list must be an integer specifying a default threshold. This is followed by one or more exceptions, each in the form of a list. This exception list contains a clef symbol (see the CLEFS slot above) followed by one of the two symbols :UP or :DN and ended by an integer specifying the number of ledger lines. An example illustrates this data structure.

'(2 (:bass :up 3) (:tenor :down 3))
                

This value influences how FOMUS chooses where to place ottava brackets above the staff. An ottava bracket isn't considered necessary until the number of ledger lines required exceeds a threshold value. An integer in this slot indicates the threshold value, while a list of two elements specifies the threshold for the ottava bracket to begin and the threshold below which the number of ledger lines must drop for it to end.

This is the same as INSTR-8UPLEGLS above, only for ottava brackets placed below the staff

This is a list of symbols, PERC objects, numbers or lists indicating all of the percussion instruments that are to be notated together as a group. PERC objects provide necessary extra information for notating percussion. All of these value types function to lookup percussion instruments in the same way as the PART-INSTR slot of the PART class. Symbols are used as lookup values into a user-defined percussion instrument table (see the PERCUSSION setting) or FOMUS's own predefined table. Lists contain a symbol lookup value followed by keyword-argument pairs signifying values to replace in the predefined percussion table--it will usually be necessary to use a list instead of a symbol since the NOTE and VOICE slots are empty in FOMUS's table.

(list '(:low-tom :note 0 :voice 1) '(:high-tom :note 4 :voice 1)
      (make-perc :anvil :note -3 :voice 2 :midinote-ex 79))
                

This is a number from 0 to 127 or a list of such numbers specifying which MIDI program change values can translate to this instrument. This is used when specifying an instrument as a program change number (see the INSTR slot in the PART class) or calling the GET-MIDI-INSTR function. When given a program change number, FOMUS finds the first instrument that matches in its list.

This is usually a number from 0 to 127 specifying which program change value is to be used when exporting MIDI data. It can also be set to a list, the first element of which is the number mentioned above followed by keyword/value pairs indicating alternate program change values for different playing modes. (For example, the list '(40 :pizz 45) is a valid value for a violin instrument.) The keywords currently allowed are :PIZZ, :STOPPED, :OPEN and :HARMONIC. (More will be added in future releases.)

This is a unique symbol identifying the percussion instrument. It is used as a lookup value so that it may easily be specified in INSTR structures.

This is an integer of 1 or greater specifying on which staff the instrument appears on.

This is an integer of 1 or greater specifying a voice that this instrument belongs to. Specifying different voices prevents notes belonging to different instruments from being beamed together.

This is an integer or symbol designating where the instrument's notes are to appear on the staff. The value is interpreted with middle C in the center as if notated with an alto clef signature. See EVENT-NOTE in the NOTE class for information on specifying notes with symbols. Percussion notes should not require flats or sharps.

If set to T, indicates that FOMUS should determine durations for this instrument. This is appropriate for percussion instruments that don't have long sustain times and can therefore be notated with durations that are simpler to read. Notes containing certain marks such as trills and tremolos are left unchanged. This slot is T by default.

Contains a list of MARKS to be added to NOTE objects that specify this percussion instrument. An example value to put here might be ((:text "R.S." :up)) for a "rim shot" percussion instrument.

Represents the MIDI note or notes used to import MIDI data. This can either be an integer from 0 to 127 or a list of such integers.

An integer value from 0 to 127 representing the MIDI note used when exporting MIDI data.

This number represents the maximum distance a cautionary accidental may be from the note that causes it.

If set to T, accidentals carry to the end of the measure. If set to NIL, accidentals affect only the note they precede.

If set to T, FOMUS automatically determines note spellings. If set to NIL, a generic set of note spellings is used (all notes receive flats except for F sharp). The user may supply note spellings to override FOMUS's spellings.

Designates which plugin is to be used for determining note spellings. Current possible values are T, :NOKEY1 and :NOKEY2. T represents the default plugin and is equivalent to :NOKEY1.

Designates which plugin is to be used for beaming. Current possible values are T and :BEAMS1. T represents the default plugin and is equivalent to :BEAMS1.

If set to T, FOMUS determines beaming based on time signature information and decisions it makes regarding irregular measure divisions. If set to NIL, beaming decisions are made by the backend notation program.

If set to T, FOMUS inserts several different kinds of cautionary accidentals. The user can supply her own cautionary accidentals with the :CAUTACC mark.

Designates which plugin is to be used for determining how rests are distributed among staves. Current possible values are T and :RESTS1. T represents the default plugin and is equivalent to :RESTS1.

If set to T, indicates that FOMUS should eliminate all redundant dynamic markings.

If set to T, FOMUS automatically puts slurs over all grace notes. If set to NIL, the user must supply all grace note slurs with :STARTGRACESLUR-, :GRACESLUR- and :ENDGRACESLUR- marks.

Designates which plugin is to be used for determining how simultaneous notes from different voices are combined into chords on the same staff. Current possible values are T and :COMB1. T represents the default plugin and is equivalent to :COMB1.

If set to T, FOMUS combines simultaneous notes from different voices into chords.

If set to T, FOMUS combines equivalent simultaneous rests from different voices into single rests.

If set to T, FOMUS automatically determines where to place ottava brackets. If set to NIL, the user must supply all ottava brackets with :8UP, :8DOWN and related spanner marks.

Designates which plugin is to be used for determining where ottava brackets occur. Current possible values are T and :OTTAVAS1. T represents the default plugin and is equivalent to :OTTAVAS1.

If set to T, FOMUS extends or contracts measures within certain bounds, adding new time signatures as necessary to fit measures into the user-supplied time signatures given in the GLOBAL or PARTS settings. If set to NIL, FOMUS simply cuts the last measure (also inserting a new time signature) before a new time signature change, resulting in measures of arbitrary sizes depending on where the cut occurs.

If set to T, FOMUS determines the durations of all percussion instruments that have their AUTODUR slot set to T. Percussion instruments that don't need to be notated precisely with respect to duration are then notated with durations that are simpler to read (without tying together groups of notes).

If set to T, indicates that FOMUS should convert each consecutive group of :PIZZ marks it finds to a single pair of :PIZZ and :ARCO marks. This makes it easier to notate pizz. and arco changes by simply attaching :PIZZ marks where they belong.

If set to T, FOMUS quantizes offsets and durations so that everything fits into the closest fitting tuplets and beat divisions possible. If set to NIL, all offset and duration values must be precise ratios or integers-- floating point numbers are treated with the RATIONALIZE function in this case (this isn't recommended). If no quantizing is done and offsets and durations of events don't fit into anything that is "notatable" then FOMUS will complain with an error.

Designates which plugin is to be used for quantizing. Current possible values are T and :QUANTIZE1. T represents the default plugin and is equivalent to :QUANTIZE1.

If set to T, FOMUS automatically determines staff and clef changes for voices. If set to NIL, the user must supply all staff and clef changes with :STAFF, :CLEF and related marks.

Designates which plugin is to be used to determine automatic staff and clef changes. Current possible values are T and :STAVES/CLEFS1. T represents the default plugin and is equivalent to :STAVES/CLEFS1.

Designates which plugin is to be used for determining how notes are distributed into separate voices. Current possible values are T and :VOICES1. T represents the default plugin and is equivalent to :VOICES1.

If set to T, FOMUS automatically decides how to distribute notes among multiple voices, given the choices specified in the NOTE, REST and MARK objects. If set to NIL, the user must specify explicitly which voice an event belongs to.

The value of this setting is used by the quantizing algorithm to determine how to round offsets and durations. If only an integer is given, it represents the number of divisions per beat in a non-compound meter-- the compound meter value is then calculated by multiplying the first number by 3/2. If specified as a list of two integers, the first integer represents the number of divisions per beat in a non-compound meter while the second represents the number of divisions in a compound meter. The first number must be a power of 2 while the second number 3/2 or 3/4 times a power of 2.

A BEAT-DIVISION of 2, for example, tells FOMUS to quantize to eighth-note values (if the current beat is a quarter-note). In a compound 12/4 meter, this setting also tells FOMUS to quantize to an eighth-note value (2 multiplied by 3/2 is 3, and there are 3 eighth-notes per beat). In the same compound 12/4 meter, a setting of '(4 6) would cause durations to be quantized to sixteenth notes (there are 6 sixteenth notes per beat).

BEAT-DIVISION specifies only approximately how durations are quantized inside tuplets. It is completely predictable only when the MAX-TUPLET setting is set to NIL or the notation contains nothing that would generate any kind of tuplet. When tuplets are allowed and FOMUS tries to create them, it divides them into units that are as close as possible in duration to the non-tuplet divisional units. For example, if BEAT-DIVISION is set to 16 and it's allowable for FOMUS to try to divide one beat into a septuplet, then it's possible for notes to be quantized to either 16 or 14 divisions per beat (since a septuplet divides evenly into 14 units and 1/14 is the closest septuplet divisional duration to 1/16).

When set to NIL, indicates that cautionary accidentals may occur only in the same measure as the note that causes them. When set to 1, specifies that cautionary accidentals may occur only if they are in the measure immediately after the note that causes them. When set to T or 2, specifies that cautionary accidentals may occur in any measure after the note that causes them.

When set to T, the cautionary accidental algorithm places cautionary accidentals at all octave transpositions from the note that causes them. When set to the integer 1 or greater, specifies the maximum number of octaves a cautionary accidental can be from the note that causes it.

When set to T, the cautionary accidental algorithm considers the presence of ottava brackets, placing cautionary accidentals where apparent octave transpositions might cause confusion.

When set to T, activates a check that prints warnings if it finds notes out of range for their instruments. The MINP and MAXP slots in the appropriate INSTR object must be set for this to have any effect.

If set to T, indicates that the value of CM-SCALE will be used to parse note symbols (as the value of the :IN keyword argument) if CM is present and being used.

This is a string specifying the path and filename to the executable for the Common Music Notation viewer application. The full pathname may or may not need to be specified depending on the Lisp implementation. The default application depends on what is installed on the user's machine, and should be an application appropriate for viewing PostScript or EPS files.

This is a list of strings representing options to be passed to the CMN viewer application executable.

This is set to an integer greater than 0, specifying the number of eighth notes that need to be present to be beamed as groups of 6 in compound meters. This setting is only effective if LONG-EIGHTH-BEAMS is set to T.

This is an optional string value containing the composer's name.

If set to a string, represents the name of a file to which debug information is dumped each time the FOMUS function is called. If you wish to report a bug, please send the contents of this file.

Specifies a default value for the BEAT slot of TIMESIG objects that are not compound time signatures. This setting is 1/4 by default, specifying that for non-compound meters a quarternote is equivalent to 1 beat. In compound time signatures the beat is always infered from the denominator (for example, in a 12/8 meter the beat is 3/8).

If FOMUS needs to convert a note into a grace note, this value is used as the grace note's duration.

If FOMUS needs to convert a note into a grace note, this value is used as the grace note's default position number. This value together with the grace note's context determines the actual position (when necessary, FOMUS will increment or decrement this value to determine the actual position number). See the DUR slot in class NOTE for more information.

This is a default INSTR object to be used in cases when another instrument isn't specified.

This list is a table containing possible ways of dividing measures into smaller segments or divisions. These segments affect how notes are split, tied and beamed. Entries in this list replace entries in FOMUS's own default table if they exist. Each member of this list is itself a list, containing an integer or ratio lookup value as the first element followed by one or more lists of integers/ratios that each add up to the first number.

:default-meas-divs
  '((3 (2 1) (1 2))
    (4 (2 2))
    (5 (3 2) (2 3))
    (6 (4 2) (2 4))
    (7 (4 3) (3 4)))
              

The numbers in these lists correspond to the number of beats in a measure, multiplied or divided by 2 if necessary. In most cases, only specify integers should be necessary, though ratios may also be used. For example, if a 7/8 measure with a quarter-note beat is processed, FOMUS first tries to lookup a set of divisions using the index number 7/2, then 7, 14, etc.. This way the lookup value 7 is sufficient for any meter with a numerator of 7, though it's possible to supply more specific entries such as 7/2 (for measures that contain 3 + 1/2 beats).

If no time signature is specified in the GLOBAL or PARTS lists, this default one is used.

This list is a table containing possible ways of dividing tuplets into smaller segments or divisions. These segments affect how notes are split, tied and beamed. Entries in this replace entries in FOMUS's own default table if they exist. Each member of this list is itself a list, containing an integer lookup value as the first element followed by one or more lists of integers that each add up to the first number.

:default-meas-divs
  '((3 (2 1) (1 2))
    (4 (2 2))
    (5 (3 2) (2 3) (4 1) (1 4))
    (6 (4 2) (2 4))
    (7 (4 3) (3 4)))
              

The numbers in this list correspond to numerators of tuplet ratios (or multiples or divisions of two). When FOMUS needs to find possible divisions for a triplet, for example, it uses the entries in the list corresponding to lookup value 3. If it needs to lookup divisions for a sextuplet, it will first try to lookup the number 6 and then use 3 if an entry for 6 doesn't exist.

This list is a lookup table indicating what ratios FOMUS should use when deciding how to notate tuplets. Each list element is itself a list of two integers specifying a tuplet ratio, or how many durational units should be used in place of another. '(7 4) thus specifies that septuplet eighth notes are to be used in place of 4 eighth notes. FOMUS searches this table by finding a match for number of tuplet divisions (the first integer in each pair) and checking the second integer to see if it's appropriate for the context it is in (a power of 2 of the actual number of durational units). Thus, several entries for septuplets might exist: '(7 4) for the majority of cases and '(7 5) for cases where, for example, 7 eighth notes might span an entire 5/8 measure or a section of a larger tuplet.

:default-meas-divs '((3 2) (6 5) (5 4) (7 4) (7 5) (13 8) (13 10))
              

The default value is NIL. If FOMUS doesn't find an entry for a tuplet division here, it determines its own depending on the value of TUPLET-FUNCTION.

Indicates how dotted notes are allowed to appear. Possible values are T, :ALL, :TOP and :SIG. :ALL specifies that they can appear anywhere, :TOP specifies that they can appear only if they occupy an entire measure, and :SIG specifies that they can appear if they occupy durations larger than a beat. T is equivalent to :ALL.

If set to T, indicates that double-dotted notes are allowed.

If FOMUS needs to determine the effective duration of a grace note (for scoring or comparison purposes), it multiplies the value of this setting with the duration given in the grace note's DUR slot.

This setting determines how parts are both ordered and grouped together with brackets and barlines in the score. Setting this to a symbol specifies a lookup value for a ordering/grouping table entry specified in the INSTR-GROUPS setting or FOMUS's own default table. It may also be set to an ordering/grouping data structure, in which case this specified ordering/grouping is used instead. An ordering/grouping data structure is a list of symbols or nested lists of symbols that specify both the groups and the layout order of parts. A symbol specifies an instrument while a list contains a group type (a symbol designating what type of bracket is to appear on the left-hand margin of the score and how barlines are to appear) followed by more instrument symbols or lists (see the example below). A group type is one of the symbols :GROUP, :GRANDSTAFF or :CHOIRGROUP.

A look at the following examples might make this clearer:

:ensemble-type :orchestra
              

:ensemble-type
  '((:my-orchestra
     (:group (:group :piccolo :flute) (:group :oboe :english-horn)
             (:group :bf-clarinet :a-clarinet :bass-clarinet)
             (:group :bassoon :contra-bassoon))
     (:group (:group :horn) (:group :c-trumpet :bf-trumpet)
             (:group :alto-trombone :tenor-trombone :bass-trombone)
             (:group :tuba))
      :timpani :percussion
     (:grandstaff :piano) 
     (:group (:group :violin) (:group :viola) (:group :violoncello)
             (:group :contrabass))))
              

This is a global list of events to be processed by FOMUS. An event can be a NOTE, REST or MARK object. A NOTE or REST object must have a symbol or number in its PARTID slot specifying which part it belongs to. A MARK object may have a default PARTID value of NIL to specify all parts or a symbol/number or list of symbols/numbers to specify only those parts. (Note that specifying part ID information isn't necessary when event objects are listed in the EVENTS slot of a PART object. Including these objects in the events list provides an alternative to listing them inside PART objects.) See Objects for more detailed descriptions of these objects and their uses.

This string represents the path and filename to which FOMUS adds an appropriate extension when it saves output in various formats. This setting in combination with the OUTPUT setting determines the actual output filenames.

:filename "path_to_output_directory/myoutput"
              

This is a list of objects that have "global" influence over other events in the PARTS and EVENTS settings. Only objects of type TIMESIG and KEYSIG are allowed here (KEYSIG isn't implemented yet). When a global object's PARTIDS slot is set to the default value of NIL the object affects all parts that don't already have a TIMESIG or KEYSIG attached to them at that point. When its PARTIDS slot is set to symbol or list of symbols the object affects those parts only. This enables the specification of multiple simultaneous time signatures and polymeters (not implemented yet).

When set to T or :SOME, indicates that FOMUS hides some rests when combining multiple voices in a grand staff. This makes the notation easier to read for multi-staff instruments by eliminating rests that aren't necessary. When set to :ALL indicates that all rests in all parts are hidden (this could be more useful in the future when proportional notation is supported). When set to NIL indicates that no rests are hidden.

When set to some real number greater than 0, indicates that this durational value is to be interpreted as one beat. FOMUS scales all input objects by dividing offsets and durations by this value before doing any other processing. A value of NIL is the default and is equivalent to 1.

When set to some real number, indicates that this durational value is to be interpreted as one beat. FOMUS shifts all input objects by adding this value to all offsets before doing any other processing. A value of NIL is the default and is equivalent to 0.

The value of this setting is a table in the form of a list that provides a way of adding instrument orderings and groupings to FOMUS's own default table. These tables map symbol lookup values to ordering/grouping data structures which specify how parts are both ordered and grouped together with brackets and barlines in the score. The user may choose one of these groupings by setting ENSEMBLE-TYPE to a symbol lookup value. The user-supplied list is searched first so user-supplied orderings/groupings can override FOMUS's default orderings/groupings.

The setting is a list of lists, the first element in each inner list containing a symbol specifying a unique lookup name. These are followed by grouping/ordering definitions: symbols or nested lists of symbols that specify both the groups and the layout order of parts. In this data structure a symbol specifies an instrument while a list contains a group type (a symbol designating what type of bracket is to appear on the left-hand margin of the score and how barlines are to appear) followed by more instrument symbols or lists (see the example below). A group type is one of the symbols :GROUP, :GRANDSTAFF or :CHOIRGROUP.

A look at the following example might make this clearer:

:instr-groups
  '((:orchestra
     (:group (:group :piccolo :flute) (:group :oboe :english-horn)
             (:group :bf-clarinet :a-clarinet :bass-clarinet)
             (:group :bassoon :contra-bassoon))
     (:group (:group :horn) (:group :c-trumpet :bf-trumpet)
             (:group :alto-trombone :tenor-trombone :bass-trombone)
             (:group :tuba))
      :timpani :percussion
     (:grandstaff :piano) 
     (:group (:group :violin) (:group :viola) (:group :violoncello)
             (:group :contrabass)))
    (:ensemble
     :piccolo :flute :oboe :english-horn :bf-clarinet :a-clarinet :bassoon
     :contra-bassoon (:grandstaff :piano)))
              

The user can use this setting to specify additional INSTR objects that are added to the default instrument list. FOMUS searches this list before its own default list when resolving symbols to instrument definitions, so they may be replacements or modifications of existing instruments. The contents are either instrument objects created with MAKE-INSTR or lists specifying modifications to FOMUS's default instruments (or a combination of both). If a list is specified, it contains a symbol specifying a default instrument followed by keyword/argument pairs indicating slot values that replace existing default values (see the INSTR slot in the PART object and PART-INSTR Slot Setting for an example of this).

:instrument
  (list (make-instr :recorder :clefs :treble)
        '(:piano :staves 3 :simultlim 6))
              

This is a string specifying the path and filename to the LilyPond executable. The full pathname may or may not need to be specified depending on the Lisp implementation.

This is a string or list of strings representing text to be inserted directly into a LilyPond output file. Each string in the list is followed by a carriage return. The text is inserted near the top of the file at a point before any score or part data appears.

This is a list of strings representing options to be passed to the LilyPond executable. The default is currently '("--ps") for Linux or '("--pdf") for OS X/Windows, specifying that LilyPond should generate either a PostScript or PDF format file.

This is a string specifying the extension for the output filename that is created when LilyPond is run. The default is "ps" for Linux and "pdf" for OS X/Windows.

This is a string or list of strings representing text to be inserted directly into a LilyPond output file at the beginning of a score block. Each string in the list is followed by a carriage return.

This is a "wrapper" string specifying LilyPond markup instructions to be used when printing text above or below the staff. The string must have an ~A or similar substring to indicate where to place the actual text (as if in a call to FORMAT). The default value is "\markup{\italic{~A}}".

This is a "wrapper" string specifying LilyPond markup instructions to be used when engraving accidentals as text. The string must have an ~A or similar substring to indicate where to place the actual text (as if in a call to FORMAT). The default value is "\\markup{\\tiny{~A}}".

This is a "wrapper" string specifying LilyPond markup instructions to be used when printing text in a dynamic-type font. The string must have an ~A or similar substring to indicate where to place the actual text (as if in a call to FORMAT). The default value is "\markup{\dynamic{\italic{\bold{~A}}}}".

This is a "wrapper" string specifying LilyPond markup instructions to be used when printing text above single notes. The string must have an ~A or similar substring to indicate where to place the actual text (as if in a call to FORMAT). The default value is "\markup{\italic{~A}}".

This is a "wrapper" string specifying LilyPond markup instructions to be used when printing text in a heavy "tempo" font. The string must have an ~A or similar substring to indicate where to place the actual text (as if in a call to FORMAT). The default value is "\markup{\bold{\huge{~A}}}".

If set to a string (for example, "2.8"), forces FOMUS to output LilyPond files for that version.

This is a string specifying the path and filename to the executable for the LilyPond viewer application. The full pathname may or may not need to be specified depending on the Lisp implementation. The default application depends on what is installed on the user's machine, and should be one appropriate for viewing PostScript files.

This is a list of strings representing options to be passed to the LilyPond viewer application executable.

This is set to an integer greater than 0, specifying the number of eighth notes that need to be present to be beamed as a group of 4. This setting is only effective if LONG-EIGHTH-BEAMS is set to T.

If set to T, specifies that the beaming algorithm should beam eighth notes into groups of up to 4 under certain conditions (if enough of them are present). If set to :ALWAYS, specifies that eighth notes are always beamed in groups of 4. If set to NIL, specifies that eighth notes are never beamed in groups of 4.

This is a real number greater than 0, specifying the maximum distance an ottava bracket will span over a group of contiguous rests.

If set to an integer, represents the largest tuplet allowed. If set to a list of integers, represents the largest tuplets allowed for each nested tuplet level (and also specifies how many levels of tuplet nesting are allowed by the length of the list). A value of '(7 3), for example, specifies two levels of tuplet nesting with septuplets being the maximum allowed in the outer level and triplets being the maximum in the inner level. A value of NIL specifies that no tuplets are to be used.

This is the largest duration in beats that a tuplet can span.

if AUTO-OVERRIDE-TIMESIGS is set to T, FOMUS automatically generates new time signatures as necessary to fit measures into the time signatures specified in the GLOBAL and PARTS list. The value of this setting represents the smallest duration (in beats) of any such time signature that is generated. See TIMESIG and TIMESIG-REPL for more information.

This is a real number greater than 0, specifying the minimum duration that a group of simultaneous rests must occupy in order for some of them to be hidden. This is applicable only when there are multiple voices on a staff, in cases where several simultaneous rests can be shown as one rest. AUTO-MULTIVOICE-RESTS must also be set to T for this to have any effect.

This is a real number greater than 0, specifying the minimum duration a group of simultaneous notes in separate voices must span to be combined into chords. This is applicable only when there are multiple voices on a staff, and if AUTO-MULTIVOICE-NOTES is set to T.

This is the smallest duration that FOMUS will consider when deciding whether or not to "split" or divide all parts together or separately. (Splitting means splitting and tying notes as necessary to properly notate a given rhythm in a given measure.) A unit of music must be larger than this value to be considered--units equal to or smaller than this duration are not considered. FOMUS splits measures in all parts together up to a certain point to insure that the notation is consistently divided in all parts. A 5/8 measure, for example, will be consistently divided as either 3 + 2 to 2 + 3 in all parts together (as long as the value of this setting is smaller than the duration of a 5/8 measure).

This is the smallest duration in beats that a tuplet can span.

This is a list of PART objects, each representing a stave or grand staff in the score. At least one part must be specified.

This is either a list or a list of lists specifying one or more output files with optional keyword/argument pairs for tweaking their contents. Current possible output symbols are :DATA or :FOMUS, :RAW, :MUSICXML, :MUSICXML-SIBELIUS, :MUSICXML-FINALE, :CMN, :LILYPOND and :MIDI. More information on these is given in Outputs. The following are examples of valid output specifications:

:output '(:data (:lilypond :view t))
              

:output '(:lilypond :filename "myfile.ly" :view nil)
              

:output :cmn
              

This is a list of PERCUSSION objects serving as a lookup table for information pertaining to percussion notation. PERCUSSION objects are listed in INSTR objects to define collections of percussion instruments that are notated together on a single staff. FOMUS searches this user setting list before its own default list when resolving symbols to percussion instrument definitions, so they may be replacements or modifications of FOMUS's predefined percussion instruments. The contents are either percussion objects created with MAKE-PERC or lists specifying modifications to FOMUS's default percussion objects (or a combination of both). If a list is specified, it contains a symbol specifying a default percussion instrument followed by keyword/argument pairs indicating slot values that replace existing default values (see the PERCS slot in the INSTR object for an example of this).

:instrument
  (list (make-perc :anvil :note -3 :voice 2 :midinote-ex 79)
        '(:triangle :note 0 :voice 1))
              

See the documentation for PERCUSSION objects for more information.

This is a real number indicating how much FOMUS should trade speed of computation for "quality" of output. Setting it lower increases speed while setting it higher gives better results. The default is 1, which is reasonable for relatively uncomplicated scores with a small number of parts. The most effective values are between approximately -3 and 3, though complex scores might show a little improvement (better guesses within a larger context) with values of 5 or more. After a certain point increasing this value only makes the program run slower with no noticeable improvement in output.

If set to T, FOMUS rounds pitches to quartertone values and uses quartertone notation in the score. This only works if the algorithm specified by the AUTO-ACCS-PLUGIN setting supports it. FOMUS's default plugin :NOKEY1 supports quartertones.

Indicates how "short-long-short" note patterns are allowed to appear. An example of such a pattern is an eighth note followed by a quarter note then an eighth note, and is treated as an exception to insure that the middle note isn't split in the middle and tied. Possible values are T, :ALL, :TOP and :SIG. :ALL specifies that this pattern can appear anywhere, :TOP specifies that it can appear only if it occupies an entire measure, and :SIG specifies that it can appear if it occupies a duration larger than a beat. T is equivalent to :ALL.

Designates which plugin is to be used for splitting and tying notes. Current possible values are T and :SPLIT1. T represents the default plugin and is equivalent to :SPLIT1.

This is an optional string value containing the subtitle of the composition.

When set to T, indicates that a certain syncopated note pattern, a short note followed by any number of long notes then a short note, may appear. An example of such a pattern is an eighth note followed by several quarter notes then an eighth note. This can only occur if the pattern occupies the duration of an entire measure.

This indicates how time signature are printed. It can be set to :FRACTION or :COMMON, specifying that either fractional or common time signatures are to be used in the backend (given the choice). The default value of NIL is equivalent to specifying :FRACTION.

This is an optional string value containing the title of the composition.

When set to T, activates a transposition function that automatically transposes note values. The TPOSE slot of the appropriate INSTR objects must be set for this to have any effect.

If set to T, specifies whether or not dotted rests are allowed inside tuplets of irregular (ie. not a power of 2) divisions. For example, a quintuplet might be divided into a dotted eight rest followed by an eighth note if TUPLET-DOTTED-RESTS is true.

Designates which function is to be used for determining tuplet ratios. Current possible values are T, :POW2 and :DUR. T represents the default function and is equivalent to :POW2. :POW2 determines tuplet ratios based on the rule that the number of tuplet divisions replace (in most cases) the number of durational units equaling the next lowest power of two. FOMUS thus notates 7 in the time of 4 and 13 in the time of 8. :DUR determines ratios by finding the closest number of durational units to the number of tuplet divisions. FOMUS then notates 7 in the time of 8 and 13 in the time of 16.

Specifies how tuplets are to be printed. The possible values are :RATIO or :SINGLE. The default value of NIL is equivalent to :SINGLE.

If set to T, indicates that FOMUS should use Common Music functions if present. Note symbols are then parsed by CM using the value of CM-SCALE as if it were passed as the :IN argument to CM's KEYNUM function. Also, durations specified as symbols indicate notational durations and are interpreted as such using CM's RHYTHM function. Numbers are still interpreted by FOMUS in terms of beats.

If set to T, the note spelling algorithm considers double sharps and double flats in addition to single sharps and flats.

This must be set to a value from 0 to 2, indicating the amount of printed output. A value of 0 represents minimal output while a value of 2 represents maximal output.