The jMusic Data Structure

The musical information in jMusic is stored in a hierarchical fashion based upon a conventional score on paper.

Score (Contains any number of Parts)
   |
   +---- Part (Contains any number of Phrases)
           |
           +---- Phrase (Contains any number of Notes.)
                    |
                    +---- Note (Holds information about a single musical event.)

We have introduced you to the jMusic data structure and you are now on such good terms that you know where it lives. Now we are going teach you how to interact with the jMusic data structure.

Notes

The jm.music.data.Note class is the basic note structure used by jMusic. Note objects contain lots of useful information:

  • Pitch - the note's pitch
  • Dynamic - the loudness of the note
  • RhythmValue - the length of the note (e.g., Crotchet)
  • Pan - the notes position in the stereo (or more) spectrum.
  • Duration - the length of the note in milliseconds
  • Offset - an deviation from the 'normal' start time of the note

To find out what java types these attributes are associated to have a look at the class description here.

The Note class also has a bunch of methods which do various bits and pieces but we will discuss how to use them a little bit later. Now that you know about the class description documentation you might like to view the whole jm tree from here. Remember to bookmark the URL so that you can find this very important document again later when I'm not here to help you ;)

Phrases

The Phrase class is a little more complicated than note objects but can be simply explained as voices (once you understand the basics I will show you why they are really more than this). A piano part is a single part but can have multiple voices. Take the left and right hands as obvious examples. Phrase objects really only contain a single important attribute, a list of notes. Every Phrase objects contains a list of notes that you can add to, subtract from and move all over the place. The list that does all these wonderful things is called a vector and is a java class found in the util package java.util.Vector. Don't worry if you don't exactly understand phrases or vectors at the moment, it is enough that you are aware of them. Have a look at the Phrase class description just for the hell of it.

CPhrases

The CPhrase class allows the composer to construct homophonic musical structures easily. That is, have jMusic play chords. A chord is defined as a group of notes that share the same onset time and duration, but differ in other respects - in particular they have different pitches. The CPhrase class can be used just like the Phrase class, but behind the scenes CPhrase structures are converted into Phrases. This becomes important only when you work with relatively complex musical structures in jMusic. Have a look at the CPhrase class description and you'll see that its methods have similar functions to the Phrase class.

Parts

Part is a class that surprisingly enough holds the notes (in phrases) to be played by an instrument. A part contains a vector that contains lots of phrases (sound familiar). A part also has a title ("Violin 1" for example), a channel, and an instrument (in MIDI, a program change number - in audio an index in the instrument array). Again don't worry about the details too much just take a look at the documentation.

Scores

The Score class represents the top level of our data structure and it contains (you guessed it) a vector of parts, and also has a title (name). Take a look.

What did all that tell me?

The answer to that is ... not much really. But hopefully it made you look at the class descriptions and gave you an idea of the class hierarchy. Maybe you even looked at some source code. To summarise, a score can hold many parts which can hold many phrases which can hold many notes, and notes have attributes such as pitch, rhythmic value, dynamic, and so on.

Real-tme audio structure

While most of the introductory tutorial focus on offline composing (non real-time) jMusic has an architecture for real-time audio that includes the RTLine and RTMixer classes, which we will breifly introduce here.

RTLine

This is an abstract class that you extend to provide note generation (composition) logic for real-time audio processing. The RTLine is similar to a Part in that it goes constantly throughout the piece, but it is like a Phrase in that it is monophonic and delivers a stream of notes up the data path.

RTMixer

An RTMixer object collects together all the audio streams being rendered by RTLines and adds them together and passes them to the audio output of the computer (via javaSound). There will typically be just one RTMixer object per real-time application, but there will often be many RTLines (one for each musical part).

Notice that the Note class is central to both offline and real-time implementations. It is important to develop a good understanding of the Note attributes and methods when working with jMusic. If you are new to jMusic focus first on the offline data structure to make the most of the tutorials, then move on to the real-time audio section.

jMusic Tutorial Index