Common Music Reference Manual

Top Objects Processes IO Scales Data Patterns Plotter Utilities Index

4 Frequency, Tunings and Modes

4.1 Frequency Formats

Frequency information can be specified in a number of different formats:

in Hertz, or cycles per second
as keynum positions in a scale
as note names in a scale
as interval distances between notes or keynums

A Hertz value specifies the number of cycles per second of a waveform. CLM and Csound instruments expect frequency to be specified in Hertz because a Hertz number does not require an underlying tuning system or mode for its interpretation.

In contrast to Hertz, the note and keynum formats convert to a frequency given the existence of some underlying scale that quantizes frequency space into discrete steps, or scale degrees. The frequency of a scale degree depends on the tuning system that the scale employs. For example, the standard chromatic scale uses an equal tempered tuning system based on a C at 8.175 Hz with 2^1/12 (100 cents) between each scale degree.

A keynum specifies the scale degree position of a frequency in a scale. Since a keynum is a numerical quantity like Hertz it can be used in arithmetic calculations. But unlike Hertz, keynums encode pitch class and octave information and allow intervals to be calculated with addition and subtraction. The MIDI protocol uses integer keynums to represent the "keys" that NoteOn messages activate in a MIDI synthesizer. We extend the notion of keynum to include floating point keynums (such as 60.5 or 45.678) to locate frequencies that lie "in between" adjacent scale degrees. Using floating point keynums a scale's quantization does not limit the expression of points in a continuous frequency space.

A note is a Lisp symbol that names a scale degree. Although note names vary from scale to scale, in general a note consists of a basic class name such as A or NEM, an (optional) accidental sign and an octave number. For example, A4 is the note name for 440 Hz in the standard chromatic scale, CS5 is C-sharp in the fifth octave, and NEM0 is the first note in the Pelog scale. Note names are probably the most familiar frequency format for composers and are useful in many contexts because they provide information about the class, spelling, and octave register of the associated frequency.

An interval is an integer that specifies the distance between two scale degrees. The distance the interval measures may be the number of scale degree steps (positive or negative) between two notes or keynums or a special typed intervalthat encodes information about an interval's quality and spelling in addition to its size. Typed intervals are defined for the standard chromatic scale only. Typed intervals are created with the interval function. If a note is transposed by a typed interval the resulting note will conform to the notation specified by the typed interval. The function converts intervals to keynums or notes.

4.2 Converting Between Hertz, Keynum, Note and Interval

In a given situation there may be one frequency representation that has advantages over the others. The functions hertz, note, and keynum convert frequency to the format for which the function is named. The function transpose converts intervals to notes or keynums. Since frequency data can be converted from one format to another a composer is free to choose the most "comfortable" representation for a given situation and convert data to a different format only when needed. For example, one might choose to define a compositional algorithm in terms of note sets that are output as Hertz values to instruments in CLM or CSound:

Example 4-1: Converting keynums and notes in the standard chromatic scale to Hertz.

? (hertz 'a4)
440.0

? (hertz 69)
440.0

? (hertz '(a4 c5 e))
(440.0 523.251 659.255)

Example 4-2: Converting Hertz and notes to keynums

? (keynum 'a4)
69

? (keynum 440 :hertz)
69.0

? (keynum '(440 550 660) :hz)
(69.0 72.863 76.019)

Example 4-3: Converting Hertz and keynums to notes.

? (note 69)
A4

? (note 440 :hertz)
A4

? (note '(69 72 76))
(A4 C5 E5)

Example 4-4: Converting intervals to notes and keynums.


? (transpose 69 6)
75

? (transpose 'a4 6)
EF5

? (transpose 'a4 (interval 'aug 4))
DS5

? (transpose '(a4 c5 e) (interval 'aug -2))
(GF4 BFF4 DF5)

These examples point out several features that are common to all four functions:

To distinguish Hertz from keynums a Hertz value must be followed by the symbol :hertz or :hz.
Lists of notes, keynums, Hertz and intervals may be specified in addition to single values. These lists can be used to represent aggregate frequency structures like sets, rows and chords. A special chord object computes chord members from a pattern description.
A note in a note list may specify its octave number or not. If not, its octave number defaults to the last specified octave number.

See the sections "Scale Functions", "The Standard Chromatic Scale" and "Converting Between Scales" for more information.

4.3 Scales, Tunings and Modes

A scale is an object that quantizes frequency into steps called scale degrees. Each scale degree is represented by an integer position in the scale called a keynum and (possibly) by one or more note names associated with the degree. The term scale applies to two different object classes. A tuning is a scale that defines the precise frequencies for each scale degree. A mode is a transposable subset of the scale degrees in a tuning, where contiguous scale degrees in a mode may be non-contiguous in the tuning.

tuning [Class]

A tuning is a scale with frequencies defined for each scale degree. Scale degrees may also have note names associated with them.

tuning supports the following slot initializations:

name {string | symbol}

An optional name for the tuning.

lowest number

The lowest Hertz value defined in the scale. Defaults to 8.175, which is C-1 in the standard chromatic scale.

cents list

One octave of the tuning specified as a list of cent values. Fewer or more than 12 degrees may be specified and an "octave" does not have to equal 1200 cents. If the cent values in list start with 0 and are in increasing order they specify the cent difference from the lowest degree to each degree above it. In this case the last value in list determines the octave width of the scale. If list does not begin with 0 then the cents values describe the distances between adjacent steps. In this case the octave width is set to the sum of the cent steps.
To define a tuning with note names specify each step as a list: (cent {note}*) where cent is the cent value followed by one or more note declarations. Each note declaration may consist of symbol note or a list (note &key :accidental) where the value of :accidental is the "subsymbol" of note that represents the accidental. For example, the 8th step in the definition of the standard chromatic scale is:
(100 (af :accidental f) (gs :accidental s))

ratios list

Exactly like cents except that the tuning values are specified as ratios (direct frequency scalers) rather than as cent values.
octaves {number | list}

The number of octaves defined in the scale. Defaults to 10. The value can be a number or a list of two values (start end) where start is the first octave number and end is the last octave number. Specify nil if the tuning has no octaves.

keynum-offset integer

A integer offset to add to all keynums values returned by keynum. Defaults to 0.

default-octave integer

The default octave for notes without octave numbers. Defaults to the 4th octave.

Example 4-5

? (new tuning name 'qt cents (loop repeat 24 collect 50))
#<tuning: "qt")>

? (hertz 138 :in #!qt)
440.0

See the file "cm:examples;scales.cm" for examples of tuning and mode definitions.

mode [Class]

A mode defines a transposable subset of a tuning.

mode supports the following slot initializations:

name {string | symbol}

An optional name for the mode.

tonic note

Sets the tonic note of the mode. Defaults to the first note in the steps specification, or C if the steps are described as intervals.

scale tuning

Sets the tuning system for the scale. Notes in the mode must also be notes in the tuning. Defaults to the standard chromatic scale.

steps {notes | intervals}

One octave of the mode specified as a list of notes or list of intervals between notes. If steps is a list of notes the tonic (transposition offset) of the mode is automatically set to the note class of the first note in the list. If the steps are specified as a list of intervals the transposition is set to C. A mode can be transposed to a new tonic using the transpose function.

Example 4-6

? (new mode name 'major steps '(d e fs g a b c d))
#<mode: "major" (on d)>

? (note 35 :in #!major)
D4

? (note 36 :in #!major)
E4

? (transpose #!major 'af)
#<mode: "major" (on af)>

? (note 35 :in #!major)
AF4

4.4 Scale Variables

All of the functions that manipulate notes, keynums and intervals operate in conjunction with some scale object. The global variable *scale* holds the "default" scale if no scale is explicitly supplied to a function. *scale* is initially set to the standard chromatic scale. The variable can be reset to any tuning or mode object. See the file "cm:examples;scales.cm" for examples of tuning and mode definitions.

*scale* [Variable]

The default scale object if no scale is specified to functions like hertz, note and keynum. The *scale* variable is initially set to the value of *standard-chromatic-scale*.

*standard-chromatic-scale* [Variable]

Holds a tuning definition of the standard chromatic scale. This definition can be found at the end of the source code file "cm:src;scales.lisp"

4.5 Scale Functions

hertz freq &key :in [Function]

Returns the Hertz value of freq, which can be a note, keynum, Hertz value or list of the same. To specify freq in Hertz add the symbol tag :hertz or :hz immediately after the value. If :in is specified it sets the scale for resolving a note or keynum freq. The value of :in defaults to the global variable *scale*, which is initially set to the standard chromatic scale.

The read macro #h provides a shorthand for converting notes or keynums to Hertz.

Example 4-7

? (hertz 'c4)
261.625

? (hertz 0)
8.175

? (hertz '(69 69.5 70))
(440.0 452.892 466.163)

? #h60
261.625

keynum freq &key :in :from :to [Function]

Returns the key number of freq, which can be a note, keynum, Hertz value or list of the same. If :in is specified it sets the scale for resolving a note or keynum freq. :in defaults to the global variable *scale*, which is initially set to the standard chromatic scale. If :from or :to is specified then keynum converts freq from or to its equivalent position in the specified scales. See the section Converting Notes and Keynums Between Scales for more information.

For equal tempered scales keynum may return a floating point number with a non-zero fractional part. This fractional value represents a "percentage" distance above the integer keynum. In the standard chromatic scale the fractional value multiplied by 100 is equivalent to cents above the Hertz value of the integer keynum.

The read macro #k provides a shorthand for converting notes to keynums.

Example 4-8

? (keynum 'c4)
60

? (keynum 440 :hertz)
69.0

? (keynum 452.893 :hz)
69.5

? (keynum '(cs5 ds fs gs as cs6))
(73 75 78 80 82 85)

? #kc4
60

note freq &key :in :from :accidental [Function]

Returns the note name of freq, which can be a note, keynum, Hertz value or list of the same. If :in is specified it sets the scale for resolving a note or keynum freq. :in defaults to the global variable *scale*, which is initially set to the standard chromatic scale. If :from or :to is specified then note converts freq from or to its equivalent position in the specified scales. See the section Converting Notes and Keynums Between Scales for more information. Use :accidental to specify a particular spelling for the note returned by the function if more than one note is defined on the scale degree. If :accidental is not specified then the note entry in the first position of the scale degree is returned. The value of :accidental may also be a list of accidentals, in which case it represents a "preference ordering" for the possible notes to return. A nil value in the accidental preference list selects a note with no accidental.

The read macro #n provides a shorthand for converting keynums to notes.

Example 4-9

? (note 60)
c4

? (note 60 :accidental 's)
BS3

? (note 'bs3 :accidental 'ff)
DFF4

? (note '(c4 d e1 f g5 ef f))
(C4 D4 E1 F1 G5 EF5 F5)

? (loop for k from 60 to 67 collect (note k :accidental '(nil s)))
(C4 CS4 D4 DS4 E4 F4 FS4 G4)

? #n60
C4

transpose freq interval &optional scale [Function]

Returns the transposed value of freq in scale. freq may be a note name, key number or list of the same. Interval may be an integer, encoded interval or list of the same.

Example 4-10

? (transpose 'a4 1)
as4

? (transpose 69 -1)
68

? (transpose '(c4 e g) (interval 'aug 4))
(FS4 AS4 CS5)

? (note (transpose '(60 61) '(0 4 7) ))
((C4 E4 G4) (CS4 F4 AF4))

? (note (transpose '(0 4 7) '(60 61)))
((C4 CS4) (E4 F4) (G4 AF4))

invert list &optional point scale [Function]

Returns the inversion of a list of notes or keynums around point in scale. Point defaults to the first element in list.

Example 4-11

? (invert '(0 1 2 3 -1))
(0 -1 -2 -3 1)

? (invert '(c4 d4 e4 f4 b3) 'c5)
(c4 bf4 af4 g4 cs4)

? (invert '(0 1 2 3 -1) 60 )
(60 71 70 69 61)

scale< freq1 freq2 &optional scale [Function]

Returns true if freq1 is less than freq2 in scale, otherwise returns false.

Example 4-12

? (scale< 'c4 60)

NIL
? (scale< 240 'c4 ':hertz)
T

scale<= freq1 freq2 &optional scale [Function]

Returns true if freq1 is less than or equal to freq2 in scale, otherwise returns false.

Example 4-13

? (scale<= 'c4 60)
T

? (scale<=  61 'c4)
NIL

scale= freq1 freq2 &optional scale [Function]

Returns true if freq1 is equal to freq2 in scale, otherwise returns false.

Example 4-14

? (scale= 'c4 60)
T

? (scale= 61 'c4)
NIL

scale>= freq1 freq2 &optional scale [Function]

Returns true if freq1 is greater than or equal to freq2 in scale, otherwise returns false.

Example 4-15

? (scale>= 'c4 60)
T

? (scale>=  61 'c4 )
NIL

scale> freq1 freq2 &optional scale [Function]

Returns true if freq1 is greater than freq2 in scale, otherwise returns false.

Example 4-16

? (scale> 60 'cw4)
NIL

? (scale> 'cs4 60)
T

scale-min freq1 freq2 &optional scale [Function]

Returns freq2 if it is less than freq1 in scale, otherwise returns freq1.

Example 4-17

? (scale-min 60 'c4)
60

? (scale-min 'css4 'cs4)
CS4

scale-max freq1 freq2 &optional scale [Function]

Returns freq2 if it is greater than freq1 in scale, otherwise returns freq1.

Example 4-18

? (scale-max 60 'c4)
60

? (scale-min 'css4 'cs4)
CSS4

scale-mod freq modulus &key :offset :in :accidental [Function]

Returns freq mod modulus. freq can be a note or keynum or list of the same. If offset is specified it is added to freq after the modulus has been performed. The default value of :offset is t which causes freq lists to be offset to the first element in the list and non-lists to be offset by 0.

Example 4-19

? (scale-mod '(c4 g5) 12)
(C4 G4)

cents->scaler cents [Function]

Convert cents value to a scaler value.

Example 4-20

? (cents->scaler 100)
1.0594630943592953

scaler->cents scaler [Function]

Converts scaler value to cents value.

Example 4-21

? (scaler->cents 1.0594630943592953)
100

pitch-class freq &optional scale [Function]

Returns the pitch class of freq, which can be a note or keynum in scale.

Example 4-22

? (pitch-class 'df5)
1

? (pitch-class 'cs4)
1

? (pitch-class 61)
1

octave-number freq &optional scale [Function]

Returns the octave number of freq, which can be a note or keynum in scale.

Example 4-23

? (octave-number 'df5)
5

? (octave-number 60)
4

? (octave-number 59)
3

? (octave-number 0)
-1

note-name &optional scale [Function]

Returns the name of note with any octave number removed.

Example 4-24

? (note-name 'df5)
DF

? (note-name 'dn5)
DN

note-accidental note [Function]

Returns the accidental of a note or note class.

Example 4-25

?(note-accidental 'dff5)
FF

?(note-accidental 'd5)
NIL

?(note-accidental 'dn5)
N

?(note-accidental 'ds)
S

prime-form notes [Function]

Returns the prime form of notes, a list of note names, pitch class names or intervals. The transposition offset is returned as a second value.

The prime form is the best normal form or its inversion, whichever is smaller. (The best normal form is the rotation of the set with the fewest intervals spanned placed in monotonically increasing order.)

Example 4-26

? (prime-form '(c4 ef4 f4))
(0 2 5)
0

4.6 The Standard Chromatic Scale

The standard chromatic scale is implemented as a tuning with 11 octaves of note entries, from C-1 to B11. There is no octave limit for keynums or Hertz values. Middle C is keynum 60 and has a frequency of 261.625 Hz.

4.6.1 Note Names in the Standard Chromatic Scale

A note in the standard chromatic scale consists of a pitch class letter, an optional accidental and an octave number:

Note name Accidental Octave number

C, D, E, F, G, A, B FF, F, N, S, SS -1 to 10

Note entries include all natural, sharp, flat, double-sharp and double-flat spellings.

Example 4-27

? (keynum 'c4)
60

? (note 'c4 :accidental 's)
BS3

? (note 261.625 :hz :accidental 'ff)
DFF4

? (keynum 'c-1)
0

? (hertz 'b10)
31608.531

4.6.2 Keynums in the Standard Chromatic Scale

Keynums in the standard chromatic scale can be integers or a floating point numbers. A floating point keynum is interpreted kkk.cc where kkk is the integer keynum and cc is cents above the Hertz value of kkk. For example, 60.5 means 50 cents (quarter tone) above the frequency of keynum 60, or 269.291 Hz.

Example 4-28

? (keynum 439 :hz)
68.96

? (hertz 69)
440.0

? (hertz 69.5)
452.892

? (note 69.5)
BF4

4.6.3 Intervals in the Standard Chromatic Scale

Intervals measure distances between scale degrees. In the standard chromatic scale this measurement can be expressed in terms of simple integer half steps or by using a specially encoded typed interval that includes the quality and spelling of an interval along with its size.

interval arg &optional arg2 [Function]

Encodes a typed interval from an external description specified in arg1 and arg2. If arg and arg2 are both notes in the standard chromatic scale then a typed interval is encoded by "subtracting" the first note from the second such that an ascending interval will be encoded if arg2 is a higher than arg, otherwise a descending interval is encoded. If arg is a "note class" (a note with no octave number) then the encoded interval is always ascending regardless of arg2's position in the scale.

if arg is not a note then it should name the quality of the interval and arg2 should be its size. Possible interval qualities and their shorthand "nicknames" are:

doubly-diminished, ddim, dd

diminished, dim, d

minor, min, mi

major, maj, ma, mj

perfect, p

augmented, aug, a

doubly-augmented, aaug, aa

Qualities can be expressed as keywords or regular symbols. The size specified in arg2 is the positive or negative number of "letter steps", where 1 means unison, 2 means a second, 8 means an octave, 10 mean a tenth, 15 means two octaves and so on.

Some example interval specifications:

Perfect unison (interval 'perfect 1)

major third (interval 'maj 3)

augmented fourth down (interval 'a -4)

doubly-diminished octave (interval 'dd 8)

minor tenth down (interval 'minor -10)

perfect fifth (interval 'p 5)

doubly augmented seventh (interval 'aaug 7)

If arg2 is not specified then arg should be a list of two values. In this case the first value in the list becomes the value of arg and the second value in the list becomes the value for arg2. The following four expressions all create an augmented 6th interval:

(interval 'fs4 'dss5)

(interval '(fs4 dss5))

(interval 'aug 6)

(interval '(aug 6))

Example 4-29

? (interval 'c4 'ds4)
86275

? (transpose 'g4 86275)
AS4

? (transpose 'c4 (interval :aug 4))
FS4

? (transpose 'c4 (interval '(dim 5) ))
GF4

? (transpose 'cs4 (interval 'min -10 ))
AS2

? (transpose 'es4 (interval :p 12 ))
BS5

? (transpose 'fs3 (interval '(:dd 10) ))
AFF4

decode-interval [Function]

Decodes interval into its "external specification".

Example 4-30

? (decode-interval (interval '(p 8)))
(:PERFECT 8)

? (decode-interval (interval 'fs4 'df4))
(:AUGMENTED -3)

complement-interval [Function]

Returns the complement of interval.

Example 4-31

? (decode-interval (complement-interval (interval 'p 5)))
(:PERFECT 4)

invert-interval [Function]

Inverts the direction of interval.

Example 4-32

? (decode-interval (invert-interval (interval 'p 5)))
(:PERFECT -5)

interval-size interval [Function]

Returns the size of the interval in "letter steps".

Example 4-33

? (interval-size (interval 'fs4 'fs5))
8

? (interval-size (interval 'fs4 'fs4))
1

? (interval-size (interval 'fs4 'ef4))
-2

interval-semitones interval [Function]

Returns the number of semitones (positive or negative) in interval.

Example 4-34

? (interval-semitones (interval 'fs4 'fs5))
12

? (interval-semitones (interval 'fs4 'fs4))
0

? (interval-semitones (interval 'fs4 'ef4))
-3

interval-quality interval [Function]

Returns the quality of interval.

Example 4-35

? (interval-quality (interval 'p 5))
:PERFECT

? (interval-quality (interval 'd 8))
:DIMINISHED

? (interval-quality (interval 'mj 3))
:MAJOR

interval-quality-type interval [Function]

Returns :perfect if interval belongs to the perfect classification (1 4 5 8) otherwise returns :imperfect.

Example 4-36

? (interval-class (interval 'p 5))
:PERFECT

? (interval-class (interval 'd 8))
:PERFECT

? (interval-class (interval 'mj 3))
:IMPERFECT

4.7 Converting Notes and Keynums between Scales

Both the note and keynum functions allow three types of scale conversions:

Converting a note or keynum from a mode to its parent tuning.
Converting a note or keynum from a tuning to one of its modes.
Converting a note or keynum from one tuning to another tuning.

Use the :to and :from scale arguemnts to note and keynum to translate between the scales. Directly converting from one mode to another or from a mode in one tuning system to a different tuning system is not supprted. This can be accomplished by seperate calls, first converting from the mode into its parent tuning and then into the other mode or tuning.

Example 4-37

? (setq w (new mode :steps '(c d e f g a b c)))
a

? (keynum 60 :to w)
35

? (note 36 :from w)
d4

Note name	Accidental	Octave number
C, D, E, F, G, A, B	FF, F, N, S, SS	-1 to 10

Perfect unison		`(interval 'perfect 1)`
major third		`(interval 'maj 3)`
augmented fourth down		`(interval 'a -4)`
doubly-diminished octave		`(interval 'dd 8)`
minor tenth down		`(interval 'minor -10)`
perfect fifth		`(interval 'p 5)`
doubly augmented seventh		`(interval 'aaug 7)`