This functor defines some utilities which are related to music or acoustics.
Functor
MUtils ("/Users/torsten/oz/music/Strasheela/strasheela/trunk/strasheela/source/MusicUtils.oz")
Import
- Emacs
- GUtils at "GeneralUtils.ozf"
- LUtils at "ListUtils.ozf"
- Init at "Init.ozf"
- Out at "Output.ozf"
- Pattern at "x-ozlib://anders/strasheela/Pattern/Pattern.ozf"
Export
Define
fun{KeynumToFreq Keynum KeysPerOctave}
Transforms a Keynum into the corresponding frequency in an equally tempered scale with KeysPerOctave keys per octave. The function is 'tuned' such that {KeynumToFreq 69.0 12.0} returns 440.0 Hz. All arguments must be floats and a float is returned.
NB: The term Keynum here is not limited to a MIDI keynumber but denotes a keynumber in any equidistant tuning. For instance, if KeysPerOctave=1200.0 then Keynum denotes cent values.
fun{FreqToKeynum Freq KeysPerOctave}
Transforms Freq into the corresponding keynum in an equally tempered scale with KeysPerOctave keys per octave. The function is 'tuned' such that {FreqToKeynum 440.0 12.0} returns 69.0. All arguments must be floats and a float is returned.
NB: The term Keynum here is not limited to a MIDI keynumber but denotes a keynumber in any equidistant tuning. For instance, if KeysPerOctave=1200.0 then Keynum denotes cent values.
fun{IsET PitchUnit}
Returns true if PitchUnit is an atom which matches the pattern et+ such as et31 or et72.
fun{GetPitchesPerOctave EtPitchUnit}
Returns the pitches per octave expressed by an ET pitch unit, e.g., for et31 it returns 31.
proc{PitchToMidi Pitch PitchUnit Args Result}
Transforms Pitch (an int) measured in PitchUnit (an atom) into the corresponding "Midi float" (a float), i.e. a Midi number where positions after the decimal point express microtonal pitch deviations (e.g., 60.5 is middle C raised by a quarter tone). Possible pitch units are midi (i.e., 12-TET), midicent/midic, frequency/freq/hz, mHz and and arbitrary equal temperaments (e.g., et31, et72).
The transformation takes account a tuning table defined with Init.setTuningTable. Alternatively, a tuning table can be given directly to the optional arg 'table'.
fun{RatioToKeynumInterval Ratio KeysPerOctave}
Transforms Ratio (either a float or a fraction specification in the form #) into the corresponding keynumber interval in an equally tempered scale with KeysPerOctave (a float) keys per octave. Returns a float.
For example, {RatioToKeynumInteval 1.0 12.0}=0.0 or {RatioToKeynum 1.5 12.0}=7.01955).
NB: The term Keynum here is not limited to a MIDI keynumber but denotes a keynumber in any equidistant tuning. For instance, if KeysPerOctave=1200.0 then Keynum denotes cent values.
fun{KeynumToPC Keynum PitchesPerOctave}
Variant of RatioToKeynumInterval which directly outputs a cent value (a float).
*/
fun {RatioToCent Ratio} {RatioToKeynumInterval Ratio 1200.0} end
/** %% Transforms a keynumber (a float) in an equally tempered scale with KeysPerOctave (a float) into its corresponding pitch class (a float) in [0, PitchesPerOctave).
fun{TransposeRatioIntoStandardOctave Freq}
Expects a frequency ratio (a float) and octave transposes it into interval [1.0, 2.0]
fun{RatioToStandardOctaveFloat Ratio}
Expects a ratio (pair of ints Nom#Denom) and returns the corresponding float, octave transposed into interval [1.0, 2.0].
fun{SortRatios Ratios}
Expects a list of ratios and sorts them in ascending order (assuming all are situated in the same octave). For example, {SortRatios [4#1 5#1 6#1 7#1 9#1 11#1]} returns [4#1 9#1 5#1 11#1 6#1 7#1].
fun{SortRatios2 Ratios StartRatio}
Expects a list of ratios and sorts them in ascending order (assuming all are situated in the same octave). However, the first ratio in the result is StartRatio (which must occur in Ratios), and all smaller ratios are appended at the end. For example, {SortRatios2 [1#3 1#4 1#5 1#7] 1#7} returns [1#7 1#3 1#5 1#4].
fun{RatioToRatioPC Nom#Denom}
fun{OddLimit Ratio}
Returns the odd limit of Ratio (pair of ints).
Restriction: ratio is in lowest terms.
fun{PrimeLimit Nom#Denom}
Returns the prime limit of Ratio (pair of ints).
fun{LevelToDB L LRel}
Converts a linear amplitude level L into an logarithmic amplitude (decibels). LRel is the relativ full level.
fun{DBToLevel DB LRel}
Converts a logarithmic amplitude DB (decibels) into a linear amplitude level. LRel is the relativ full level.
fun{FullTuningTable TuningTable}
Expects a tuning table declaration (see Init.setTuningTable for format) and returns a full tuning table used for pitch computation. The returned full table is a record which contains only pitches measured in cent, has 0.0 added as first table value, and has the two features size and period added.
fun{MakeNoteLengthsTable Beat TupletFractions}
MakeNoteLengthsTable creates a list which maps symbolic note lengths to duration values. Expects the duration of a beat (i.e. the timeUnit is beats(Beat)) and a list of tuplet fractions to take into consideration (e.g., [3 5] denotes triplets and quintuplets). The function returns a list of pairs NotationI#DurI. NotationI is denotes a symbolic note length as a virtual string, and DurI is the corresponding duration (an int).
Notation of symbolic note lengths:
plain durations: 'd' followed by reciprocal values. Example: d#4 is quarter note
dotted note lengths: plain duration followed by _ (underscore). Example: d#4#'_' is quarter note + eighth note. Multiple dots are not supported (simply add multiple durations instead).
tuplets (notated as individual note lengths): t followed by a number indicating the fraction, followed by the duration. Example: t#3#d#4 is a triplet quarter note and t#3#d#4#'_' is a dotted triplet note. Nested tuplets are not supported.
ties: simply add the resulting durations of the individual notes.
fun{MakeNoteLengthsRecord Beat TupletFractions}
Returns a record which maps symbolic note lengths (atoms which are record features) to duration values (integers, feature values in the record). See the documentation of MakeNoteLengthsTable for the arguments Beat and TupletFractions, and also the symbolic note length notation. However, whereas in MakeNoteLengthsTable this notation uses VSs (so it can be easily decomposed) here it uses atoms for convenience.
Example: create a record R and then use this record for notating symbolic durations.
R = {MakeNoteLengthsRecord 15 [3 5]}
R.d4 % quarter note
R.t3d4 % quarter note triplet
fun{MakeDurationsRecord Beat TupletFractions}
Returns a record which maps durations (integers, feature values in the record) to lists of symbolic note lengths (atoms which are record features). See the documentation of MakeNoteLengthsTable for the arguments Beat and TupletFractions, and also the symbolic note length notation.
proc{SetNoteLengthsRecord Beat TupletFractions}
Initialises transformation for ToDur. See the documentation of MakeNoteLengthsTable for the arguments Beat and TupletFractions.
fun{GetNoteLengthsRecord }
Returns the full record of symbolic note lengths atomes (record features) and their associated durations (record values).
proc{FeedNoteLengthVariables }
Makes all set symbolic note lengths available as variables in the compiler. The variable names are the same as expected, e.g., by ToDur, but all lower-cases are replaced by upper cases. For example, the variable D4 will be bound to the duration of the beat. For all (lower-case) note values see {Arity {MUtils.getNoteLengthsRecord}}.
Use SetNoteLengthsRecord for initialisation (default is {SetNoteLengthsRecord 4 nil}).
fun{ToDur NoteLength}
Expects a symbolic note length (atom) and returns the corresponding duration. Use SetNoteLengthsRecord for initialisation (default is {SetNoteLengthsRecord 4 nil}).
proc{SetDurationsRecord Beat TupletFractions}
Initialises transformation for ToNoteLengths. See the documentation of MakeNoteLengthsTable for the arguments Beat and TupletFractions.
fun{ToNoteLengths Dur}
Expects a duration (int) and returns a list of the corresponding symbolic note lengths. Use SetDurationsRecord for initialisation (default is {MakeDurationsRecord 4 nil}).
End
