Mod Functions

The Mod class contains many functions for modifying, or varying, phrases, parts and scores. Each of this functions modifies the data passed to them.  For example, the Mod.repeat() function creates repetitions of the given musical material.  It is called like this:

Mod.repeat(phrase, 41)

This will modify phrase to contain a total of 41 copies of the original musical material.

Below are the available Mod functions.  You may apply these functions repeatedly to achieve a desired effect.

Modifying Volume

The following functions modify the volume (or dynamic) of notes in a phrase, part, or score.

Function Description
Mod.accent(phrase, meter) Increase volume (accent) of the first quarter note beat of each measure in phrase, where meter is the number of beats per measure (e.g, 4.0).
Mod.accent(phrase, meter, beats, amount) Same as above, except we provide a list of beats (e.g., [2, 3]) to accent, and amount of accent (e.g., 15).
Mod.compress(material, ratio) Compress (or expand) the dynamic range of material, by the provided compression (or expansion) ratio (e.g., 4.0).
Mod.crescendo(phrase, time1, time2, vol1, vol2) Increase volume in phrase from vol1 at time time1, to vol2 at time time2.
Mod.fadeIn(material, length) Starting from zero volume, increase volume gradually over length quarter notes to reach the normal volume.
Mod.fadeOut(material, length) Starting from the normal volume, decrease volume gradually over length quarter note to reach zero volume.
Mod.normalize(material) Increase note volumes proportionally in material, so the loudest note is at maximum level.

Modifying Duration

The following functions modify the duration of notes in a phrase, part, or score.

Function Description
Mod.append(phrase1, phrase2) Modifies phrase1 by appending to it the notes of phrase2.
Mod.elongate(material, factor) Change (elongate) the length of notes in material by the provided scaling factor.  If  factor is less than 1.0 it shrinks the duration (e.g., 0.5 reduces the duration to half – which is the same as doubling the speed or tempo).
Mod.changeLength(phrase, beats) Change (scale) the duration in phrase, so its total duration equals the provided number of beats (quarter notes).
Mod.cycle(phrase, beats) Repeats phrase until it spans the specified number of beats (quarter notes).   Repetition stops with the note that reaches (or exceeds) the provided length (i.e., the last repetition of phrase may be incomplete).
Mod.palindrome(phrase) Doubles the length of phrase, by appending a copy of itself in reverse order.
Mod.repeat(material, times) Repeats material specified number of times (material appears exactly the number of times specified).
Mod.quantize(material, quantum) Rounds (quantizes) the start time and duration of each note in material to fit multiples of quantum (e.g., 1.0).  The smaller the quantum, the lesser the amount of change.  A large quantum results in music that sounds mechanical.
Mod.quantize(material, quantum, scale, tonic) Rounds (quantizes) the start time and duration of each note in material to fit multiples of quantum (e.g., 1.0), using the specified scale (e.g., MAJOR_SCALE), and the specified tonic (0 means C, 2, 1 means C sharp, means D, and so on).  The smaller the quantum, the lesser the amount of change.  A large quantum results in music that sounds mechanical. All pitches are forced to align with the provided scale (and tonic).

NOTE: Use cycle() when you wish to fit a particular length. Use repeat() when you wish to repeat a number of times, regardless of length. When repeating overlapping phrases of different lengths, cycle() will guarantee they all end at approximately the same time.

Modifying Pitch

The following functions modify the pitches of notes in a phrase, part, or score.

Function Description
Mod.invert(phrase, pitch) Mirror (invert or flip) the pitch of all notes in phrase relative to pitch.
Mod.transpose(material, interval) Shift the pitch of every note in material by interval (number of chromatic steps – e.g., -12 lowers by an octave; 12 raises by an octave).
Mod.retrograde(phrase) Reverse the order of the notes in phrase.
Mod.rotate(phrase, times) Move (rotate) the notes around the phrase (i.e., last note becoming first, first note becoming second, second note becoming third, and so on), where times indicates how many times (i.e., how many notes) to rotate.

Modifying with Randomness

The following functions use randomness to modify notes in a phrase, part, or score.

Function Description
Mod.shuffle(material) Randomly reorganize the order of the notes in material.
Mod.mutate(phrase) Mutate phrase by changing one pitch and one duration value.  The new pitch is selected randomly between the lowest and the highest note of phrase.  The random duration is selected from those in the existing notes.
Mod.randomize(material, pitchAmount) Randomizes pitches in material by a  value within +/- the specified pitchAmount.
Mod.randomize(material, pitchAmount, durationAmount) Same as above, plus specify random variation of the duration (plus or minus durationAmount).

Alphabetical

Here are all the Mod functions in alphabetical order.

Function Description
Mod.accent(material, beats) Accents the first beat of each measure in material.Beats(a float) is the number of beats per measure.  Materialmay be a Phrase,Part, or Score.
Mod.accent(material, meter, accentedBeats, accentAmount) Accents by accentAmount (an int) at the accentedBeatslocations (a list of floats, denoting time in quarter notes). Meter(a float) is the number of beats per measure.  Materialmay be a Phrase,Part, or Score.
Mod.append(material1, material2) Appends material2 to material1. Works with notes, phrases, parts, and scores.  In the case of notes, it extends the duration value of the first note (without changing its pitch).
Mod.bounce(material) Adjusts the pan values of all notes in material  to alternate between extreme left and right from note to note. Materialmay be a Phrase,Part, or Score.
Mod.changeLength(phrase, newLength) Alters the phrase so that its notes are stretched or compressed until the phrase is the specified length (number of beats – a float).  It works in the same manner as elongate(), except it takes an absolute length parameter not a ratio.
Mod.compress(material, ratio) Compresses (or expands) the material. Compression ratio numbers between 0 and 1.  Values larger than 1 expand.  Negative values invert the volume about the mean. This compression applies only to the volume of the notes.  It will multiply the difference between each note’s volume and the volume, by the compression ratio.  Thus, a ratio of 0 will change every note’s volume to the average volume; 1 will leave every note unchanged; and 2 will make every note’s volume twice as far from the mean. Negative values will have a similar affect but leave the volume of each note on the other side of the mean. Materialmay be a Phrase,Part, or Score.
Mod.consolidate(part) Merges part’s phrases into one phrase.  This works well with View.notate(part), so that notate() can display all the notes in the part (View.notate() works only with a single phrase).
Mod.cycle(material, numberOfNotes) Repeats the material until it contains the specified number of notes.  The repetitions work in the same manner as Mod.repeat(), except that the final repetition will not be a complete copy of the original if the note count is reached before the repetition is completed.  Materialmay be a Phrase,Part, or Score.
Mod.elongate(material, scaleFactor) Stretch the time of each note in the phrase by scaleFactor (a float). Materialmay be a Phrase,Part, or Score.
Mod.fadeIn(material, fadeLength) Linearly fades in the material (fadeLength is quarter notes). Materialmay be a Phrase,Part, or Score.
Mod.fadeOut(material, fadeLength) Linearly fades out the material (fadeLength is quarter notes). Materialmay be a Phrase,Part, or Score.
Mod.fillRests(material) Lengthens notes followed by a rest in material by creating one longer note and deleting the rest. This will reduce the overall note count. Materialmay be a Phrase,Part, or Score.
Mod.invert(material) Mirror the pitch of notes in the material around the first note’s pitch. The order of the notes is not affected it is only the pitches that are mirrored.  That is, notes which are n semitones above the first pitch will be changed to be n semitones below. Materialmay be a Phrase,Part, or Score.
Mod.mutate(phrase) Mutate phrase by changing one pitch and one duration value.  The new pitch is selected randomly between the lowest and the highest note of phrase.  The random duration is selected from those in the existing notes.
Mod.normalize(phrase) Increase note volumes proportionally in phrase, so the loudest note is at maximum level.
Mod.palindrome(material) Extend the phrase by adding all notes backwards, repeating the last note of the material. Materialmay be a Phrase,Part, or Score.
Mod.quantize(phrase, quantum) Rounds (quantizes) the start time and duration of each note in phrase to fit multiples of quantum (e.g., 1.0).  The smaller the quantum, the lesser the amount of change.  A large quantum results in music that sounds mechanical.
Mod.quantize(material, quantum, scale, tonic) Rounds (quantizes) the start time and duration of each note in material to fit multiples of quantum (e.g., 1.0), using the specified scale (e.g., MAJOR_SCALE), and the specified tonic (0 means C, 2, 1 means C sharp, means D, and so on).  The smaller the quantum, the lesser the amount of change.  A large quantum results in music that sounds mechanical. All pitches are forced to align with the provided scale (and tonic).
Mod.randomize(material, pitchVariation, durationVariation, dynamicVariation) Randomly adjusts every note’s pitch, duration, and dynamic values to a random value within the range plus or minus the specified amount; pitchVariationis an int (make sure result stays within 0-127); durationVariation is a float (e.g., 1.0 is a quarter note); dynamicVariationis an int (make sure result stays within 0-127). Materialmay be a Phrase,Part, or Score.
Mod.repeat(material, number) Repeat the material a number of times.  Materialmay be a Phrase,Part, or Score. For example, Mod.repeat(phrase, 2) will play phrase two times.
Mod.retrograde(material) Reverse the order of notes in the material. Materialmay be a Phrase,Part, or Score.
Mod.rotate(material) Move the notes around the material, first becoming second, second becoming third, … and last becoming first. Materialmay be a Phrase,Part, or Score.
Mod.shake(material) Randomly adjusts the volume of notes to create uneven loudness. Materialmay be a Phrase,Part, or Score.
Mod.shake(material, amount) Randomly adjusts the volume of notes to create uneven loudness. Amount (an int) denotes how strong the effect will be, e.g., 5 will be +/-5 from the current volume. Materialmay be a Phrase,Part, or Score.
Mod.shuffle(material) Randomise the order of notes in the material without repeating any note. Materialmay be a Phrase,Part, or Score.
Mod.spread(material) Randomly adjusts the pan values of all notes in material to create an even spread across the stereo spectrum. Materialmay be a Phrase,Part, or Score.
Mod.tiePitches(material) Joins consecutive notes in materialthat have the same pitch, creating one longer note. This is similar to the musical function of a tie. This will reduce the overall note count. Materialmay be a Phrase,Part, or Score.
Mod.tieRests(material) Joins consecutive rests in materialcreating a longer note. This is similar to the musical function of a tie. This will reduce the overall note count. Materialmay be a Phrase,Part, or Score.
Mod.transpose(material, semitones) Chromatic transposition. It shift the pitch of every note in the material by the given number of semitones. Materialmay be a Phrase,Part, or Score.
Mod.transpose(material, steps, scale, key) Diatonic transposition. It shift the pitch of every note in the material by the given number of scale degrees (steps), given the scale and key. Materialmay be a Phrase,Part, or Score.  Key is an integer (0 means the key of C, a positive integer indicates the number of sharps, whereas a negative integer indicates the number of flats).   See Appendix A for a list of available scales.