Mod

Mod provides functions for modifying, or varying, phrases, parts and scores. These functions modify the data given to them.

For example, Mod.repeat() creates repetitions of the given musical material:

This will modify phrase to contain a total of 41 copies of what it originally contained.

Below are the available Mod functions.  They are organized in terms of their functionality – Pitch, Duration, Dynamic, and Randomness. They are also presented in alphabetical order.

You may use these functions in any sequence to achieve a desired effect.

Modifying Pitch

The following functions modify the pitch of musical material in various ways.

Function Description
Mod.invert(phrase, pitch) Mirror the pitch of notes in phrase around the given 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.
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.quantize(phrase, quantum, scale, key) Quantize (round) the start time and duration of each note in phrase to fit multiples of quantum. Also, adjust pitches of notes to fit the provided scale (e.g., MAJOR_SCALE) and key (0 means key of C, 1 means key of C sharp, and so on).
Mod.randomize(material, pitchVariation, durationVariation, dynamicVariation) Randomly adjust every note’s pitch, duration, and dynamic values to a random value within the range plus or minus the specified amount; pitchVariation is an int (make sure result stays within 0-127); durationVariation is a float (e.g., 1.0 is a quarter note); dynamicVariation is an int (make sure result stays within 0-127). Material may be a Phrase, Part, or Score.
Mod.retrograde(material) Reverse the order of notes in material. Material may 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. Material may be a Phrase, Part, or Score.
Mod.shuffle(material) Randomize the order of notes in material without repeating any note. Material may be a Phrase, Part, or Score.
Mod.tiePitches(material) Join consecutive notes in material that 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. Material may be a Phrase, Part, or Score.
Mod.transpose(material, semitones) Chromatic transposition. Shift the pitch of every note in material by the given number of semitones. Material may be a Phrase, Part, or Score.
Mod.transpose(material, steps, scale, key) Diatonic transposition. Shift the pitch of every note in material by the given number of steps (scale degrees), given the scale and key. Material may be a Phrase, Part, or Score.  Scale is a list.  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).

Modifying Duration

The following functions modify the length of musical material in various ways.

Function Description
Mod.append(material1, material2) Append material2 to material1.  Material may be Note, Phrase, Part, or Score.  In the case of Notes, it extends the duration value of the first note (without changing its pitch).
Mod.changeLength(phrase, newLength) Change phrase so that its notes are stretched or reduced until the phrase is the specified length (number of beats – a float).  Works similarly to elongate(), except it takes an absolute length parameter, not a factor.
Mod.cycle(material, numberOfNotes) Repeat material until it contains numberOfNotes.  Works similar to Mod.repeat(), except that the final repetition may be incomplete, if numberOfNotes is reached.  Material may be a Phrase, Part, or Score.
Mod.elongate(material, scaleFactor) Stretch each note’s duration in material by scaleFactor (a float). Material may be a Phrase, Part, or Score.
Mod.fillRests(material) Remove rests in material by lengthening the previous notes.  This will reduce the overall note count (rest notes are removed). Material may be a Phrase, Part, or Score.
Mod.merge(material1, material2) Merge material2 into material1. Material may be Part of Score (same type).  It does not worry about instrument and channel assignments – it is left to the caller to ensure the two materials are compatible this way.
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 new duration is selected randomly from one of the existing notes (it may be the same).
Mod.palindrome(material) Extend material by adding all notes backwards (that is, material plus its retrograde). Material may be a Phrase, Part, or Score.
Mod.quantize(phrase, quantum) Quantize (round) the start time and duration of each note in phrase to fit multiples of quantum. The smallest the quantum, the least the amount of change. A large quantum results in music that sounds mechanical.
Mod.quantize(phrase, quantum, scale, key) Quantize (round) the start time and duration of each note in phrase to fit multiples of quantum. Also, adjust pitches of notes to fit the provided scale (e.g., MAJOR_SCALE) and key (0 means key of C, 1 means key of C sharp, and so on).
Mod.randomize(material, pitchVariation, durationVariation, dynamicVariation) Randomize the pitch, duration, and dynamic of all notes in material to a random value plus or minus the specified variation; pitchVariation is int (make sure range stays within 0-127); durationVariation is float (e.g., 1.0 means a quarter note); dynamicVariation is int (make sure range stays within 0-127). Material may be a Phrase, Part, or Score.
Mod.repeat(material, times) Repeat material a number of times.  Material may be a Phrase, Part, or Score. For example, Mod.repeat(phrase, 2) will play phrase two times.
Mod.retrograde(material) Reverse order of notes in material. Material may be a Phrase, Part, or Score.
Mod.rotate(material) Rotate notes in material, with last note becoming first, first note becoming second, second becoming third, … . Material may be a Phrase, Part, or Score.
Mod.shift(material, time) Shift start times of all phrases in material by specified time (1.0 means a quarter note). If time is positive, phrases are shifted to start later. If time is negative, phrases are shifted to start earlier (limited to the piece’s start time). Material may be Phrase, Part, or Score.
Mod.shuffle(material) Shuffle (randomize order of) notes in material. Material may be a Phrase, Part, or Score.
Mod.tiePitches(material) Tie (join) consecutive notes with same pitch in material, reducing note count. This is similar to the musical function of a tie. Material may be a Phrase, Part, or Score.
Mod.tieRests(material) Tie (join) consecutive rests in material, reducing note count. This is similar to the musical function of a tie. Material may be a Phrase, Part, or Score.

Modifying Dynamic

The following functions modify the dynamic (or volume) of musical material in various ways.

Function Description
Mod.accent(material, beats) Accent (make louder) the first beat of each measure in material. Beats (a float) is number of beats per measure.  Material may be a Phrase, Part, or Score.
Mod.accent(material, meter, accentedBeats, accentAmount) Accent (make louder) the first beat of each measure in material by accentAmount (an int) at the accentedBeats locations (a list of floats, denoting time in quarter notes). Meter (a float) is number of beats per measure.  Material may be a Phrase, Part, or Score.
Mod.compress(material, ratio) Compress (or expand) dynamic of every note in material. It sets every note’s dynamic to the average dynamic of material, then it subtracts the note’s original dynamic times ratio. Thus, ratio of 0 changes every note’s dynamic to the average volume (compresses fully); ratio of 1 leaves every note unchanged; ratio of 2 makes every note’s volume twice as far from the mean (expands). Negative values have a similar affect but push the note dynamics on the other side of the average. Material may be a Phrase, Part, or Score.
Mod.crescendo(phrase, time1, time2, dynamic1, dynamic2) Increase dynamic in phrase from dynamic1 at time time1, to dynamic2 at time time2.
Mod.fadeIn(material, fadeLength) Linearly dynamic from 0 to normal in material over fadeLength (measured in quarter notes). Material may be a Phrase, Part, or Score.
Mod.fadeOut(material, fadeLength) Linearly fades out material (fadeLength is quarter notes). Material may be a Phrase, Part, or Score.
Mod.normalize(phrase) Increase note volumes proportionally in phrase, so the loudest note is at maximum level.
Mod.randomize(material, pitchVariation, durationVariation, dynamicVariation) Randomly adjusts every note’s pitch, duration, and dynamic in material to a random value within the range plus or minus the specified amount; pitchVariation is an int (make sure result stays within 0-127); durationVariation is a float (e.g., 1.0 is a quarter note); dynamicVariation is an int (make sure result stays within 0-127). Material may be a Phrase, Part, or Score.
Mod.shake(material) Randomly adjusts the volume of notes in material to create uneven loudness. Material may be a Phrase, Part, or Score.
Mod.shake(material, amount) Randomly adjusts the volume of notes in material to create uneven loudness. Amount (an int) denotes how strong the effect will be, e.g., 5 will be +/-5 from the current volume. Material may be a Phrase, Part, or Score.

Modifying Panning

The following functions modify the panning (stereo position) of musical material in various ways.

Function Description
Mod.bounce(material) Adjusts the pan values of all notes in material to alternate between extreme left and right from note to note. Material may 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. Material may be a Phrase, Part, or Score.

Modifying with Randomness

The following functions transform musical material using randomness in various ways.

Function Description
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, pitchVariation, durationVariation, dynamicVariation) Randomly adjusts every note’s pitch, duration, and dynamic in material to a random value within the range plus or minus the specified amount; pitchVariation is an int (make sure result stays within 0-127); durationVariation is a float (e.g., 1.0 is a quarter note); dynamicVariation is an int (make sure result stays within 0-127). Material may be a Phrase, Part, or Score.
Mod.shake(material) Randomly adjusts the volume of notes in material to create uneven loudness. Material may be a Phrase, Part, or Score.
Mod.shake(material, amount) Randomly adjusts the volume of notes in material to create uneven loudness. Amount (an int) denotes how strong the effect will be, e.g., 5 will be +/-5 from the current volume. Material may be a Phrase, Part, or Score.
Mod.shuffle(material) Randomize the order of notes in the material without repeating any note. Material may 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. Material may be a Phrase, Part, or Score.

Mod Functions in Alphabetical Order

Here is the list of Mod functions in alphabetical order.

Function Description
Mod.accent(material, beats) Accent (make louder) the first beat of each measure in material. Beats (a float) is number of beats per measure.  Material may be a Phrase, Part, or Score.
Mod.accent(material, meter, accentedBeats, accentAmount) Accent (make louder) the first beat of each measure in material by accentAmount (an int) at the accentedBeats locations (a list of floats, denoting time in quarter notes). Meter (a float) is number of beats per measure.  Material may be a Phrase, Part, or Score.
Mod.append(material1, material2) Append material2 to material1.  Material may be Note, Phrase, Part, or Score.  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. Material may be a Phrase, Part, or Score.
Mod.changeLength(phrase, newLength) Change phrase so that its notes are stretched or reduced until the phrase is the specified length (number of beats – a float).  Works similarly to elongate(), except it takes an absolute length parameter, not a factor.
Mod.compress(material, ratio) Compress (or expand) dynamic of every note in material. It sets every note’s dynamic to the average dynamic of material, then it subtracts the note’s original dynamic times ratio. Thus, ratio of 0 changes every note’s dynamic to the average volume (compresses fully); ratio of 1 leaves every note unchanged; ratio of 2 makes every note’s volume twice as far from the mean (expands). Negative values have a similar affect but push the note dynamics on the other side of the average. Material may 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.crescendo(phrase, time1, time2, dynamic1, dynamic2) Increase dynamic in phrase from dynamic1 at time time1, to dynamic2 at time time2.
Mod.cycle(material, numberOfNotes) Repeat material until it contains numberOfNotes.  Works similar to Mod.repeat(), except that the final repetition may be incomplete, if numberOfNotes is reached.  Material may be a Phrase, Part, or Score.
Mod.elongate(material, scaleFactor) Stretch each note’s duration in material by scaleFactor (a float). Material may be a Phrase, Part, or Score.
Mod.fadeIn(material, fadeLength) Linearly dynamic from 0 to normal in material over fadeLength (measured in quarter notes). Material may be a Phrase, Part, or Score.
Mod.fadeOut(material, fadeLength) Linearly fades out material (fadeLength is quarter notes). Material may be a Phrase, Part, or Score.
Mod.fillRests(material) Remove rests in material by lengthening the previous notes.  This will reduce the overall note count (rest notes are removed). Material may be a Phrase, Part, or Score.
Mod.invert(phrase, pitch) Mirror the pitch of notes in phrase around the given 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.
Mod.merge(material1, material2) Merge material2 into material1. Material may be Part of Score (same type).  It does not worry about instrument and channel assignments – it is left to the caller to ensure the two materials are compatible this way.
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 new duration is selected randomly from one of the existing notes (it may be the same).
Mod.normalize(phrase) Increase note volumes proportionally in phrase, so the loudest note is at maximum level.
Mod.palindrome(material) Extend material by adding all notes backwards (that is, material plus its retrograde). Material may be a Phrase, Part, or Score.
Mod.quantize(phrase, quantum) Quantize (round) the start time and duration of each note in phrase to fit multiples of quantum. The smallest the quantum, the least the amount of change. A large quantum results in music that sounds mechanical.
Mod.quantize(phrase, quantum, scale, key) Quantize (round) the start time and duration of each note in phrase to fit multiples of quantum. Also, adjust pitches of notes to fit the provided scale (e.g., MAJOR_SCALE) and key (0 means key of C, 1 means key of C sharp, and so on).
Mod.randomize(material, pitchVariation, durationVariation, dynamicVariation) Randomize the pitch, duration, and dynamic of all notes in material to a random value plus or minus the specified variation; pitchVariation is int (make sure range stays within 0-127); durationVariation is float (e.g., 1.0 means a quarter note); dynamicVariation is int (make sure range stays within 0-127). Material may be a Phrase, Part, or Score.
Mod.repeat(material, times) Repeat material a number of times.  Material may be a Phrase, Part, or Score. For example, Mod.repeat(phrase, 2) will play phrase two times.
Mod.retrograde(material) Reverse order of notes in material. Material may be a Phrase, Part, or Score.
Mod.rotate(material) Rotate notes in material, with last note becoming first, first note becoming second, second becoming third, … . Material may be a Phrase, Part, or Score.
Mod.shake(material) Randomly adjusts the volume of notes in material to create uneven loudness. Material may be a Phrase, Part, or Score.
Mod.shake(material, amount) Randomly adjusts the volume of notes in material to create uneven loudness. Amount (an int) denotes how strong the effect will be, e.g., 5 will be +/-5 from the current volume. Material may be a Phrase, Part, or Score.
Mod.shift(material, time) Shift start times of all phrases in material by specified time (1.0 means a quarter note). If time is positive, phrases are shifted to start later. If time is negative, phrases are shifted to start earlier (limited to the piece’s start time). Material may be Phrase, Part, or Score.
Mod.shuffle(material) Shuffle (randomize order of) notes in material. Material may 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. Material may be a Phrase, Part, or Score.
Mod.tiePitches(material) Tie (join) consecutive notes with same pitch in material, reducing note count. This is similar to the musical function of a tie. Material may be a Phrase, Part, or Score.
Mod.tieRests(material) Tie (join) consecutive rests in material, reducing note count. This is similar to the musical function of a tie. Material may be a Phrase, Part, or Score.
Mod.transpose(material, semitones) Chromatic transposition. Shift the pitch of every note in material by the given number of semitones. Material may be a Phrase, Part, or Score.
Mod.transpose(material, steps, scale, key) Diatonic transposition. Shift the pitch of every note in material by the given number of steps (scale degrees), given the scale and key. Material may be a Phrase, Part, or Score.  Scale is a list.  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).