jMusic Tools and
Utilities
Like many software projects, jMusic
has some core and some additional elements. As you work more
with jMusic the structure of these elements will become more
clear and also (hopefully) the reasons why jMusic is structured
in this way will be clearer. A rough guide to the jMusic
hierarchy of classes can be seen in the package structure. If
you have downloaded the source code simply open the jMusic
directory and see how the classes are arranged into a
directory tree. (The jm directory may be consolidated as a
jm.jar file, if so, download the source files to see the directory organisation within
the jm directory. But this is not necessary to use the tools so
don't get fazed if you don't have the source.)
To use the data or tool classes you
need, at the top of your Java file, to import the appropriate
directories:
import jm.music.data.*;
import jm.music.tools.*;
import jm.music.util.*;
Guess which package has all the
tools, which one has all the utilities and which one has all the musical
data (Note, Phrase, Part, Score etc.).
This tutorial will introduce you to
the organisation of classes close to the heart of jMusic, the
arrangement of data, tools and utilities, and how you can use
these most effectively.
Data
At the core of jMusic is the
jmusic/src/jm/music directory. In particular the data classes,
Score, Part, Phrase, CPhrase, and Note, which hopefully you
know intimately - or will. These data classes contain all the
musical 'content' for jMusic and also many methods for creating
or reporting on that data. The manipulation of the music
content is performed by tools in the jm.music.tools directory,
such as the Mod.transpose() and Mod.repeat() methods. As you develop jMusic pieces you may
write a generally useful class which can be included in the
tools directory for others to utilise. The AdaptiveMatrix class is one
such tool that is a generalised Markov matrix generator.
Anyway, on with the show. At the
data level the data objects 'set' themselves via their methods and we
use tool classes, such as Mod to transform them. So in the case of part.setTitle("Fred");
the title (name) of the part is set to Fred. In the case of Mod.repeat(2); the
phrase is changed by adding extra notes to it so that it plays
two more times through.
Utilities
In order to communicate with the
outside world a set of utility classes have been created.
Communicating, in this context, includes displaying a score on
screen, writing a score to a file, inputting a phrase as
notation, reading a MIDI file, and so on. Utilities communicate
with the data structure, rather than transform it. Of course in
practice this is a blurry distinction, but a helpful one when
you're getting started and want a clear explanation :)
At the utility level the data
objects are 'translated' from (or to, in the case of Read) an
i/o device (screen, hard disk). The data objects are not necessarily
changed. For example, the View methods translate the data into
visualisations and the Write methods translate the data into file
formats. Because the util methods use the jMusic data, a data object
(usually a score) is passed as an argument, as in: Write.midi(score, "FileName.mid");
Your Classes
In the classes that you write you
can use any of the data, tools or utility classes. You can
directly access the data and tool classes, and you can get
particular interpretations of the data as viewed through the
various utility classes. The rule of thumb is, if you want to
'manipulate' the data then access the data classes and methods
directly and if you want to 'render' the data so you can see
it, or hear it, or store it, then use the util classes.
Hopefully, this is more straight
forward in practice than this long-winded explanation! Below is a
summary of the functions performed by the util classes,
HelperGUI, Read, Write, View, and Play. As always, this
tutorial scratches the surface, and you should check the documentationand
look at the source to get a more up-to-date and complete
understanding of the util functionality.
HelperGUI
The Helper GUI provides a visual
interface that accesses many of the other jMusic unitilies mentioned
below. It can be used by simply having your class extend the HelperGUI
class and adding a compose() method.
...
public final class MyClass extends HelperGUI implements JMC{
...
public Score compose() {
...
}
}
|
See the tutorial for details.
Write
To write a standard MIDI file (SMF)
of your jMusic composition use code similar to:
Write.midi(score, "FunkyBeat.mid");
|
To write a jMusic file (.jm) of your
jMusic composition use code similar to:
For both SMF and jm files you
can optionally provide a file name. If a filename is not provided then
the score title will be used with the appropriate .mid or .jm extension.
It is possible to write SMF and jm
files from Score, Part, Phrase or CPhrase objects.
To write an audio file (.au) of your
jMusic composition use code similar to:
Write.au(score, "MyRenderedScore.au", theBand);
|
The three arguments are 1) the
score to render, 2) the name of the output file and 3) the
intrument array to use.
Note that .au audio files are the
only ones currently supported. Use a sound file editing package for your
system (Sox, Soundhack, CoolEdit , etc.) to convert to other formats
such as .wav, .aiff, .mp3, and so on.
Read
To read a standard MIDI file (SMF)
into your jMusic composition use code similar to:
Score score = new Score("Beethoven Variations");
Read.midi(score, "Beethovens9th.mid");
|
View
To display your jMusic composition
on screen use code similar to:
View.show displays music as
psudo-notation - using rectangles for duration, and a stave for
pitch,
or use
View.notate(phrase, 20, 100);
|
View.notate displays music as
common practice notation,
or
View.sketch displays music as
lines on graph paper.
Some of the view types can also be
used to enter, add, or edit edit music data as well as display it.
It is possible to view jMusic data
from Score, Part, Phrase or CPhrase objects.
Play
To play your music using the
Javasound libraries within Java use the following code:
import jm.util.*;
...
Play.midi(score);
|
Javasound libraries are only
availible in Java version 1.3 or later, so make sure your
platform supports it.
|