filter [number] (default: 1)

Filter unmapped values

round [bool] (default: true)

If @round is set to true (as it is by default), when an input frequency falls between two pitches, the value is rounded to the nearest int. If @round is set to false , the fractional part of the float is included. The fractional part could be used to calculate an additional pitch offset for applying MIDI pitch bend.

scalename [symbol]

Defining a symbol argument for the ftom~ object will cause ftom~ to calculate the frequency to MIDI conversion based on a given scale from the scala archive. The scale name should be the filename from the scala archive, but without the file extension. For example, if the scale in the scala archive is listed as pelog_me3.scl , you can give ftom~ the argument pelog_me3 .

base [number] (default: 440)

Sets the "base frequency" used for the reference note when calculating frequency values (e.g., the reference note A4 = 440 Hz). The default base frequency is 440 Hz.

frequency [number]

Takes in a frequency value. The corresponding MIDI pitch value (from 0 to 127) is sent out the outlet, taking into account any scale or keyboard mapping set by the @scale and @map attributes.

map [list]

Setting the map attribute with a properly formatted list will set a keyboard mapping for ftom~ which describes how a scale of arbitrary number of steps maps onto the piano keyboard.

RNBO's keyboard mapping format is the exact same as scala's except there are no comments, and the maps are flattened into a list instead of having an entry per line.

We use -1 instead of 'x' to indicate unmapped entries. If the unmapped keys at the end you can also simply leave them off.

Visit the official scala website for more information on the KBM format.

In a KBM format, a mapping is described as follows:

! Template for a keyboard mapping
!
! Size of map. The pattern repeats every so many keys:
12
! First MIDI note number to retune:
0
! Last MIDI note number to retune:
127
! Middle note where the first entry of the mapping is mapped to:
60
! Reference note for which frequency is given:
69
! Frequency to tune the above note to (floating point e.g. 440.0):
440.0
! Scale degree to consider as formal octave (determines difference in pitch
! between adjacent mapping patterns):
12
! Mapping.
! The numbers represent scale degrees mapped to keys. The first entry is for
! the given middle note, the next for subsequent higher keys.
! For an unmapped key, put in an "x". At the end, unmapped keys may be left out.
0
1
2
3
4
5
6
7
8
9
10
11

In RNBO, we'd define this same mapping as:

12 0 127 60 69 440 12 0 1 2 3 4 5 6 7 8 9 10 11

In the following map for the pelog_me3 scale, the pattern repeats every 12 keys of the piano keyboard. MIDI notes between 0 and 127 will be tuned. The first entry of the mapping will be MIDI note 60, the reference note for the scale's tuning is MIDI note 62, which is tuned to 286 Hz.

The scale's "formal octave" is 7, meaning there are 7 notes described in this scale.

Those 7 notes are mapped onto the "white keys" of the piano keyboard. All other keys are skipped, indicated with the -1 .

12 0 127 60 62 286 7 0 -1 1 -1 2 3 -1 4 -1 5 -1 6

You can send a "0" for map to reset the map back to its default: linear 440.

mid [number] (default: 60)

Sets the "middle note" where the first scale degree is mapped. This means that a keyboard mapping set using the @map attribute would start on this note. By default, this is set to MIDI note 60.

ref [number] (default: 69)

Sets the reference note which is to be tuned to the "base frequency." By default, this is MIDI note 69.

scale [list]

Setting the scale attribute with a properly formatted list will cause ftom~ to calculate the frequency to MIDI conversion based on a scale specified by that list. To convert a scala formatted file into a list for RNBO, we ignore any comment lines (prefixed with !) and we skip the descriptive text line. We include the length value, then, we put a zero after each cents value (values with a period in them) and split any ratios (implicit or explicit) into 2 values, finally we collapse the whole thing into a list.

For instance:

The cents value of 128.298 would instead be noted as as 128.298 0 . The ratio 2/1 would become 2 1 . 4 (with no period) is actually an implied ratio of 4/1 and would thus become 4 1 .

The following scala file for the pelog_me3 scale

! pelog_me3.scl
!
Gamelan Kyahi Pangasih (kraton Solo). 1/1=286 Hz
7
!
128.298
276.357
545.806
669.366
784.692
967.096
2/1

becomes

7 128.298 0 276.357 0 545.806 0 669.366 0 784.692 0 967.096 0 2 1

The leading 7 indicates that there are 7 notes in the scale, 128.298 0 indicates 128.298 cents, and 2 1 indicates a ratio of 2/1 (octave).

tuning [number]

A float in the right inlet sets the "base frequency" used for the reference note when calculating frequency values (e.g., the reference note A4 = 440 Hz). The default base frequency is 440 Hz.