Fomus

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

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

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.

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

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 slot in the part object and for an example of this).

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

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. fomus's built-in 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 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.