Documentation

jMusic Home Page

Tutorial

jMusic: Music composition in Java

Downloading and Installing jMusic

Unix/Linux - MacOS X - MacOS 9 - Windows

Linux / Unix

1. Download and install Java from Oracle. (Skip this step if you have a Java already.)

2. Download the jmusic and jMusic instrument files from sourceForge.

3. Place the jmusic.jar file and inst directories in your Java class path. This is usually done by editing your shell .*rc file (in OS X for example edit or create a ~/.cshrc file or in Linux a ~/.bashrc file) and add the location of the jMusic directories to the class path environment variable. (See OS X section below for more shell default details).

4. (Optional) To use the MidiShare package (msjm) for MIDI input and output you will need to download and install MidiShare from Grame, including the Java developer kit with the grame.jar file. You should run msconnect to connect the various midi input/output sources that you might have.

E.g., (for the tcshell) setenv CLASSPATH ${home}/jmusic/lib/jmusic.jar/:${home}/jmusic/inst/:.

Note: The jmqt package requires Apple's QuickTime and will not run on Lunix or Unix. You can safely ignore it.

Mac OS X

1. Download the jmusic jar file and jMusic instrument directory from sourceForge. (Follow links from jMusic_Stable)

2. Place the jMusic folder in your user directory. e.g., /User/andrew/jMusic

3. Place the jmusic.jar file and the inst directory in your Java class path. This is usually done by creating (or editing) your shell .*rc file.

In OS X systems that use the cshell by default it is the ~/.cshrc fil

Creating a .cshrc file.

Assume you have put the jMusic folder in your User directory, use a text editor to create a file called .cshrc with the following (single) line in it. In OS X not all Aqua text editors can read or write files starting with a dot, as these are generally hidden. We suggest that you open a terminal and use the pico editor to create and or edit your .schrc file. Navigate to your home directory by typing cd ~. In the terminal type pico .cshrc then add the line below.

setenv CLASSPATH .:${home}/jMusic/jmusic.jar:${home}/jMusic/inst/ 

Save the file in your user directory. e.g: /User/andrew/.cshrc


In OS X systems that use the bash shell by default it is the ~/.bashrc file.

Creating a .bashrc file.

Assume you have put the jMusic folder in your User directory, use a text editor to create a file called .cshrc with the following (single) line in it. In OS X not all Aqua text editors can read or write files starting with a dot, as these are generally hidden. We suggest that you open a terminal and use the pico editor to create and or edit your .schrc file. Navigate to your home directory by typing cd ~. In the terminal type pico .bashrc then add the line below.

export CLASSPATH=.:$HOME/jMusic/jmusic.jar:$HOME/jMusic/inst/ 

Save the file in your user directory. e.g: /User/andrew/.basrc

Create (or edit an existing) a .profile file inthe same directory by typing pico .profile. Add the following line to the file:

. .bashrc

Save the file in your user directory. e.g: /User/andrew/.profile


4. Reshresh the teminal to utilise the changed environment variables. Open a terminal window (or quit and reopen if already open) to initiate the .cshrc file. (The terminal app is in the /Applications/Utilities/ directory.) Use the commands javac filename.java or java filename to run jMusic files.

5. (Optional) To use the MidiShare package (msjm) for MIDI input and output you will need to download and install MidiShare from Grame, including the Java developer tools with the grame.jar file. You should run msconnect to connect the various midi input/output sources that you might have. All the files need to go in the working directory. The grame.jar needs to be added as an environment variable in the classpath. For example, add :${home}/jMusic/graeme.jar to the end of the setenv CLASSPATH command above if the grame.jar file is in the jMusic folder.

Note: With Java for OS X version 1.4.2 Apple broke QTJava support, so the jMusic jmqt package does not work. If you have this version of Java installed please avoid the qtjm package within jMusic (for now at least - there is an update in the works at Apple we believe).

Mac OS 9

Install java: (Skip these steps if you have a Java runner and compiler already.)

  1. Download and install the MRJ (Macintosh Runtime Java) from Apple
  2. Download an install the MRJ SDK (Software Development Kit) from Apple.

Install jMusic:

  1. Download the jmusic and jMusic instrument files from SourceForge and unstuff with stuffit expander. (Follow links from jMusic_Stable). If it doesn't automatically uncompress, drop the file onto Stuffit Expander to do so. This will result in a folder called "jMusic".

    Put the 'jmusic.jar' file and 'inst' folder in your Java classpath. This involves placing the files inside the MRJClasses folder inside MRJLibraries, inside Extensions, inside the System folder. You will find all other java packages here such, as "MRJClasses.zip".

    ......./System Folder/Extensions/MRJLibraries/MRJClasses

    Make sure the names are exactly the same as the folders (without the
    'alias' suffix).
  2. To use the qtjm playback utilities make sure that Apple's QuickTime java (QTJava.zip file) is installed. Installing this is an option when you run the Quicktime installer (make sure it is version 5) from Apple. When installing QuickTime, choose 'Custom Install' and select the QTJava option. It will install a QTJava.zip file in the MRJClasses folder.

    Note: Java for Mac OS9 is version 1.1 which does not support the Swing GUI library or JavaSound MIDI and audio libaries. jMusic does use JavaSound for playback in some cases, but does not Swing (although many of the applications built using jMusic do), users of Mac OS9 may wish to download the
    Swing libraries from Sun. Put the Swing.jar file in the classpath - the MRJClasses folder.
  3. (Optional) To use the MidiShare package (msjm) for MIDI input and output you will need to download and install MidiShare from Grame, including the Java developer tools with the grame.jar file. You should run msconnect to connect the various midi input/output sources that you might have. You need to copy the midishare drivers that you want to have started on midishare wakeup time into the midishare directory in system. The grame.jar, or an alias of it, needs to go in the folder in system where you put all the other java libraries, System Folder/Extensions/MRJ Libraries/MRJClasses.

Windows

First stage, install Java bits.

  1. Download the latest Java development kit installer from Sun. Run the executable and follow the on-screen prompts to install.

  2. (Optional step) If you wish to use the QuickTime playback utilities you need to install Quicktime with the optional Java components enabled. Download the Quicktime installer from Apple. When installing, choose to do a 'Custom Install' and ensure that the 'Quicktime for Java' checkbox is selected.

    The next stage is to set up jMusic.

  3. Download jmusic and jMusic instrument files from sourceForge. Choose the latest file under the jMusic_Stable heading.

  4. Some environment variables must be set before jMusic can be run successfully. This can be done in several ways.
    1. Under Win9x or WinME, add the following command to c:\autoexec.bat and reset your computer.
    2. Under Win2000, NT or XP,
      Open the System Properties Dialog. (By right-clicking My Computer and going to Properties OR by naviagting through Start | Settings | Control Panel | System)
      Choose the Advanced tab
      Click Environment Variables... Ensure that a variable called CLASSPATH exists and it contains c:\jmusic\jmusic.jar;c:\jmusic\inst
    You may wish to try creating, compiling and running a simple jMusic program to test if the tools has been set up correctly. Here is a tutorial to try which will work on all flavours of Windows.

  5. (Optional) To use the MidiShare package (jmms) for MIDI input and output you will need to download and install MidiShare from Grame, including the Java developer tools with the grame.jar file. You should run msconnect to connect the various midi input/output sources that you might have. The midishare user file is called midishare186.zip The midishare developer file is called midishare2000.zip They are in the same ftp folder, and the layout is a bit confusing (careful). You need to put the dlls that you want to use, as well as the midishare32dll (which has all the important native classes) into the system folder, so that they can be awakened at midishare startup time. Make sure the .ini files are put into the windows or winNT folder.
       

For even more information on getting going with Java try the getting started instructions from  Java's homepage.

Using -classpath options directly

If you are compiling at the command line there is a method where you can ignore the .profile setup using the -classpath option for the Java compiler (in fact it's what I do most of the time). Here is an overview:

1. Download the jmusic###.jar file from sourceforge and put it is a directory/folder on your hard drive.
2. Write (or download from a tutorial) a jMusic program file and save it in a directory/folder on your hard drive.
3. Open a terminal/command-line application
4. Compile and run using the -classpath option for the javac and java applications, and pass it the 'location' of your .jar file, then use the complete path for the location of your .java program file.

e.g: In a Bash shell on OSX the compiling command looks like this (with a space between the two paths)
javac -classpath /Users/acid/AB_Work/Code/jMusic/src16/build/jar/jMusic1.6.4.jar /Users/acid/Desktop/Scale.java

The execution command looks like this (with a colon between the paths for the  jmusic library and the program file, and a space before the Java class name)
java -classpath /Users/acid/AB_Work/Code/jMusic/src16/build/jar/jMusic1.6.4.jar:/Users/acid/Desktop/ Scale


jMusic source code

The full set of .java source files for jMusic are availible from SourceForge.


Documentation

The Javadoc-generated documentation in HTML format can be downloaded from sourceforge. It can also be viewed online from this site.


Tutorials and Examples

Work through the online tutorials and documented example code to see how to compose with jMusic.

Visit the Digital Instrument Building web resource that features jMusic tutorials focused on music software development.

Download the jMusic tutorials as a zip archive. [15.4 MB]


Feedback

We are very interested to hear your comments about jMusic, the music you write with it, and to see any additions to the classes you might make. Check previous questions or suggestions at the jMusic-dev archives or send a message by subscribing to the list.


Developers

Join the team formally by registering at SourceForge Logo

 


Supported by the following organisations:

Exploding Art

SourceForge Logo