Methods for musical manipulation 

As well as providing a way of storing your music in a score, jMusic provides ways of manipulating that stored music.
The processes for change are called 'methods'.
Each of the data structure classes - Note, Phrase, CPhrase, Part, and Score - have their own methods for accessing the music (notes and other attributes) stored in that class. Following Java conventions most of the methods for accessing data start with either 'get' (as in getPitch) or 'set' (as in setPitch).
Other common keywords for data classes are 'add' and 'remove'.

Making modification to the jMusic data (processes such as repeating, reversing and copying) is done using the Mod class.
The Mod class is your friend, and you should get to know it well.
But these are simply one set of modifications (what we found useful) - you can create your own class of modification methods for the techniques you prefer. The Mod class includes methods that modify all of the jMusic data types (from Notes to Scores).
Some Mod methods can be used on all these while others are specific to one data type. The data type with most Mod methods is Phrase.

In this tutorial many of the methods will be outlined - for a more comprehensive list check out the documentation, and examine the source code to see how the methods are implemented.

In the Note class the most important task is setting the notes attributes, such as pitch, rhythm value, dynamic, pan position, duration, and so on.
To facilitate this, each attribute has a pair of get and set methods; for example getPitch() and setPitch().

Note n = new Note(); n.setPitch(D5);

The get and set methods form the basis for all higher level manipulations.
For example, the transpose method in the phrase class relies on getting the current pitch, adding or subtracting a value from it, then setting the pitch to the new value; as in:

pitchVal = n.getPitch(); pitchVal += 5; n.setPitch(pitchVal);

Apart from get and set methods for each note attribute, the note (and all other music data classes in jMusic) have a copy() method, which does the obvious thing. This allows the duplication of notes for repetitions, or as the starting point for minor modifications.

It is easier to create a note double the length by copying the source note and adjusting the rhythmicValue and/or duration than creating a new note and having to specify each of the attributes separately.

One useful method is print() which will display the numerical values of each note attribute to the standard output.
This can be very useful in checking your code is doing what you expect.

We will deal with these two classes in the one breath because every attempt has been made in jMusic design to have the same functionality in Phrases and Chord Phrases.

Phrases have particular attributes of their own with get and set methods, including startTime and title. i.e., getStartTime(), setTitle(), copy() and so on.

Getting notes into phrases is achieved one by one with the addNote() method, or as a group with the addNoteList() method.

Note n = new Note(C3, QUAVER); phrase.addNote(n);

The chord phrase class adds several notes at one time as a chord using the addChord() methods which usually take arrays of values for pitch, rhythm, dynamic, etc. but can take an array of Notes.

There are attributes associated with a Part which have get and set methods, including title, progChg, and midiChannel. Continuing the score metaphor, it is common for all Notes in a Part to be played by the same instrument which is why the MIDI program change and channel are Part attributes.

Part p = new Part(); p.setProgChg(24);

Most importantly, a Part has methods to add Phrases to it; addPhrase(); and addCPhrase();

Many of the Phrase methods (above) have equivalents in the Part class. This means that all the Phrases in a Part can be changed with a call to the Part method.

The Score class contains all the notes for a piece of music (or at least a section of a piece of music) and as a result it does not have many unique methods. A score has a title with methods to get and set it.

The Score call can add parts using the addPart() method and delete them using the removePart() and removeLastPart() methods.

Part p = new Part(); score.addPart(p);

The Mod class is in the jm.music.tools package, and you need to import this package in order to access these methods.

import jm.music.tools.*;

Most Mod methods apply to phrases, but many apply to all data types. Check the documentation for a detailed description.

The Mod class is a 'static' class, meaning that you don't instantiate a new Mod object. It is used similar to the Math class, such as x = Math.random(); The Mod class copy would be p = Mod.copy(part);

Phrase manipulations are widely used in western composition, and this is reflected in the jMusic Mod class having more methods than other data classes.
In most cases we hope that the method names are self explanatory, but that will not always be the case. Here are some of the Mod methods that apply to a Phrase:

loop(); - play the phrase a number of times through

transpose(); - shift the pitch of the phrase by a certain number of semitones

palindrome(); - extend the phrase to add all the notes in reverse order *

retrograde(); - reverse the order of the notes *

inversion(); - flip the pitch of notes in relation to the first note's pitch *

shuffle(); - randomly reorganise the order of the notes in a phrase *

elongate(); - change the rhythm values of the notes in the phrase by a certain scaling factor *

accents(); - add a sense of meter by emphasising the dynamic of regular beats

fadeIn(); - starting at zero volume, add a crescendo to the current loudness over a certain number of beats

fadeOut(); - starting at the current loudness, add a decrescendo down to zero volume over a certain number of beats

getEndTime(); - report the beat number following this phrase (where a subsequent phrase might start)

append(); - extend a phrase by adding another phrase to the end of it

empty(); - remove all notes from this phrase

These are provided by the Mod class.  Lets see some examples of this class in action.
 

Mod.quantise(phrase1, SEMI_QUAVER); Mod.repeat(phrase1); Mod.append(phrase1, phrase2);

The first example quantises phrase1 to multiples of semi-quavers, the second repeats phrase1, and the third appends phrase2 to the end of phrase1.

This begins to show some of the power of the jMusic libraries.  All the hard work is done behind the scenes, and all you need to access them are these lines.

All the methods in the Mod class follow the pattern of the examples.  The first parameter is always the musical data that gets modified. 
Subsequent parameters describe in what way the first parameter should be modified.  But subsequent parameters are never altered themselves. 

So, for the method call:
 

Mod.append(phrase1, phrase2);

The second parameter, phrase2, remains the same.  It is phrase1 that gets updated to include the melody stored in phrase2.

Most of the methods are overloaded.  This is programming term to meaning that the same call can be used with different types of arguments.
  So, in the same way you appended phrases, you can append notes, parts and scores together:
 

Mod.append(note1, note2); Mod.append(part1, part2); Mod.append(score1, score2);

This framework can be used with all the methods of the Mod class.
  To see the full list of methods, including comments about their use and specifics about their parameters see the jMusic API documentation.

Modifications effect existng jMusic objects. So remember to create a phrase, chordPhrase, part, score before modifying it.

Phrase phr = new Phrase(); . . . add notes . . . Mod.retrograde(phr);

Phrase phr = new Phrase(); . . . add notes . . . Mod.repeat(phr, 3); // repeat three times

Part modification methods include:

fadeIn(); - starting at zero volume, add a crescendo to the current loudness over a certain number of beats

fadeOut(); - starting at the current loudness, add a decrescendo down to zero volume over a certain number of beats

repeat(); - play the part a number of times over

quantise(); - round the rhythmValues (thus start times) of the notes to a specified beat value (e.g., 0.25)

accents(); - add a sense of meter by emphasising the dynamic of regular beats

empty(); - remove all phrases from this part

There are a few useful Score modification methods in the Mod class including;

append(); - extend a score by adding another score to the end of it

fadeIn(); - starting at zero volume, add a crescendo to the current loudness over a certain number of beats

fadeOut(); - starting at the current loudness, add a decrescendo down to zero volume over a certain number of beats

quantise(); - round the rhythmValues (thus start times) of the notes to a specified beat value (e.g., 0.25)

accents(); - add a sense of meter by emphasising the dynamic of regular beats

empty(); - remove all parts from this score