Phrase objects contain a sequence of Note objects.  These Note objects are played sequentially (i.e., one after the other).  If a gap is desired between two notes, then a Rest note should be introduced.  Phrases may also contain chords (i.e., sets of concurrent notes).

Phrases have start times.  If no start time is specified, then the phrase starts at the end of the previous phrase (or at the beginning of the piece, if this is the first phrase).

The music library provides several functions to create musical phrases.  It also provides several others to retrieve or modify existing phrases.

Here are functions used to create phrases.  Each of these functions creates a new Phrase object, so you need to store it in a variable (or other memory location) to be able to use it later.

Function Description
Phrase() Creates an empty phrase.
Phrase(startTime) Creates an empty phrase starting at specified time (e.g., 0.0 is beginning of piece, 1.0 is a quarter note into the piece, etc.).

You can create a phrase as follows:

p = Phrase()

Once a phrase p has been created, the following functions are available:

Function Description
p.addNote(note) Appends the given note to the phrase.
p.addNote(pitch, duration) Appends a new note of given pitch (0-127) and duration (a float) to the phrase.
p.addNoteList(listOfPitches, listOfDurations, listOfDynamics, listOfPannings, listOfLengths) Appends the notes specified in terms of pitches (a list), durations(a list), dynamics (a list), and pannings (a list) to the phrase. The lists are parallel.  Dynamic, panning, and length lists are optional.
p.addChord(listOfPitches, duration, dynamic, panning) Appends a chord containing the specified pitches (a list) and having the specified duration (a float), dynamic (0 – 127), and panning (0.0 – 1.0).  Dynamic and panning values are optional.

You can also set the instrument and tempo of the phrase.

Function Description
p.setInstrument(instrument) Sets the phrase’s instrument (0 – 127).
p.getInstrument() Returns the phrase’s instrument (0 – 127).
p.setTempo(tempo) Sets the phrase’s tempo (default is 60 beats per minute).
p.getTempo() Returns the phrase’s tempo (in beats per minute).

NOTE: You may set the instrument on a single phrase. If you intend to add the phrase to a Part, then set the instrument at the Part level.  (If you do both, you may get unexpected results.)

Finally, here are some additional Phrase functions:

Function Description
p.copy() Returns a new phrase with the same notes and attributes as phrase p.  This is used to create a copy to be modified, while the original phrase is not affected.
p.setStartTime(startTime) Sets the phrase’s startTime (a float).
p.getStartTime() Returns the phrase’s startTime (a float).
p.getEndTime() Returns the phrase’s end time (a float).
p.getSize() Returns the number of notes in the phrase.
p.setDynamic(dynamic) Sets the dynamic of every note in the phrase (0 – 127).
p.getNoteList() Returns the phrase’s notes (a list).
p.getNote(index) Returns the note object at index (0 means first). It does not modify the phrase.
p.getNoteStartTime(index) Calculates the start time, in beats, of the note at the specified index (0 means first).
p.getHighestPitch() Returns the pitch value of the highest note in the phrase.
p.getLowestPitch() Returns the pitch value of the lowest note in the phrase.
p.getLongestDuration() Returns the duration value of the longest note in the phrase.
p.getShortestDuration() Returns the duration value of the shortest note in the phrase.
p.empty() Removes all notes from the phrase.