JMSL Readme

Java Music Specification Language, release 1.03
Installation Notes

JMSL now ships in one fully functional version. You may request a 30 day demo license here.

JMSL includes:

all JMSL classes in two JAR files (jmsl.jar and jscore.jar)
test suite with source
docs
tutorial
examples
JScore instruments
fully functional notation package ("com.softsynth.jmsl.score")

To purchase a JMSL license after your evaluation period, please visit http://www.algomusic.com/jmsl/purchase.html

JMSL Installation

Unpack the distribution onto your hard drive and note its location. Spaces in directory names are STRONGLY discouraged, so be careful of paths like C:\Documents and Settings\User\Desktop (Bad! Path includes spaces!)

JMSL now ships as a two jar files: jmsl.jar and jscore.jar. This was done for more efficient delivery of online pieces that may not need common music notation. For non-notated works, which only use the core jmsl classes, use jmsl.jar. If your piece needs common music notation, you must *also* include jscore.jar (for example, in an applet tag: < archive="jscore.jar, jmsl.jar"> )

If you have installed a non-jarred previous version of JMSL, delete the folder jwork/website/classes/com/softsynth/jmsl (just delete the jmsl folder!). If you have been using a previous version of JMSL that shipped with a jar file, avoid the use of jmslclasses.jar (move it out of the way somewhere, but keep it around in case you depend on it for some existing pieces while you switch over your code)

Mac OS X: DO NOT copy jmsl.jar and jscore.jar to ~/Library/Java/Extensions JMSL is not designed to be run as an extension. If you have installed it there from a previous prerelease, please remove it. Go here to find out more about using JMSL as a Java Extension

Using JMSL Score as a stand-alone

Intended audience:
You want to launch JScore, start entering notes in common music notation, and hear it with JSyn instruments or MIDI.
You intend to use Wire (JSyn graphical patch editor) to design SynthNotes for use in JMSL Score.
You don't want to program any Java for this.
(Note that in order to export your patches from Wire you must have purchased a JSyn license)

When launched, JMSL Score scans a "jmsl_plugins" folder if it is found in its classpath, and generates menus to import SynthNotes, Transforms, and Instruments it finds there. The scripts generated by JMSLScriptMaker will help set this up for you so you can build up a custom JScore environment with plugins that you and others have developed.

JMSLScriptMaker will create two customized command scripts: one that compiles Wire patches, and another that launches JScore with the jmsl_plugins folder in the classpath. This provides a non-programmer with a path that begins with sound design in Wire and flows easily into composing with these sounds in common music notation.

Prerequisite:

You must have JSyn developer's kit installed! Visit http://www.softsynth.com/jsyn

If you want to use MIDI you must install MidiShare (see my MidiShare installation notes forWindows and OS X)

You must have the command line java compiler "javac" installed on your system. OS X users already do. Windows users should download the latest Java Development Kit from Sun (for example, the J2SE Development Kit (JDK) is current as of Oct 2005). The Java Runtime Environment (jre) is not enough; you need javac.

Here's what you do: Double click on JMSLScriptMaker.jar to launch the script making utility.
Click the buttons to browse for the jar files appropriate for your system, and browse for the Wire patches directory.

This utility generates two scripts for your computer:
1) run_jmsl_score - This script launches JMSL Score with jmsl_plugins in classpath
2) compile_wire_patches - This calls javac on all your exported in your Wire patches folder, and puts them in the jmsl_plugins folder where JMSL Score can find them

Then just double click on run_jmsl_score to launch JMSL's common music notation package.

MAC OS X USERS!!!!!!!!!
If you are using Mac OS X, the resulting scripts will have to be made "executable" before you can double click on them. To do this,

open a Terminal
In the Terminal type the following, ending in a space:
chmod +x
Drag run_jmsl_score.command from the location where you saved the scripts into the Terminal so it looks something like:

chmod +x /Users/yourname/pathto/run_jmsl_score.command

Hit Return. You have made the script "executable" and can now just double click on it. You will not have to do this exercise again.
repeat steps 2 & 3 for compile_wire_patches.command

Java Development Environment Notes

We strongly encourage the use of an integrated development environment like Eclipse (www.eclipse.org). Learn how to create a new Eclipse Project that uses JMSL

Your Java project's build path must include jmsl.jar and jscore.jar.

Eclipse users select Project Properties -> Java Build Path -> Libraries -> Add External Jars, then browse for jmsl.jar and jscore.jar

JBuilder users: add two new required libraries to your project, name them JMSL and JSCORE, and browse to the locations of jmsl.jar and jscore.jar

TEST JMSL DEVELOPMENT:

We have included a simple test class called HelloJMSL.java, which can be found in the TestDev folder. To test your JMSL installation, we will compile and run this class. If you are using a Mac, have a quick peak below to see the GUI that should open if you're successful, then follow the Mac instructions. (Note that this does not use Midi, so even if you see a warning message about Midi not initializing, don't worry, it's not being used).
Ok? Let's do it. We show two versions: Eclipse and command line.

COMMAND LINE
First CD to the JMSL_v103/TestDev directory which contains the HelloJMSL source
COMPILE

javac -d ../classes -classpath ../classes/jmsl.jar HelloJMSL.java

RUN
Windows:
java -classpath ../classes;../classes/jmsl.jar jmsltestsuite.HelloJMSL
OSX:
java -classpath ../classes:../classes/jmsl.jar jmsltestsuite.HelloJMSL

ECLIPSE USERS
Create a new project.
In the new project, create a new package called jmsltestsuite.
Drag HelloJMSL.java from the distribution's TestDev folder into jmsltestsuite (this makes a copy, it does not move the original)
Select Project Properties -> Java Build Path -> Libraries -> External Jars. Browse for jmsl.jar
Run HelloJMSL as an application.

[Note: if a window opens and says "JMSL license not found or not valid." you must install a valid JMSL license as described here or better yet here.]

Whether you used Eclipse, some other IDE, or the command line, you should see a frame open up that looks like this:

And when you watch the console, you will see data printed out over time, like this:

TEST YOUR MIDI:
We strongly encourage you to use an IDE at this point and get away from command line development. Try Eclipse and read Eclipse guide

MidiShare is now JMSL's default Midi class. If you want to send and receive MIDI with JMSL, we recommend MidiShare ( http://www.grame.fr/MidiShare/Develop/Java.html )
Read Nick's installation logs for MidiShare Windows or OS X

Install MidiShare packages.
Hook up your synth with midi cable in/out of your computer's midi interface
[optional] You may want to first test MidiShare's Java API without JMSL. Compile and run the file SimpleMidiShareTest.java which tests output, and MidiShareIOTest.java for input (These files uses no JMSL at all, just Java & MidiShare).

Continue to test with JMSL&MidiShare: Compile and run jmsltestsuite.TestMidiScheduling. Your Java build path must include the external jars jmsl.jar and midishare.jar

[If are running Windows98 you get this error: jmidi.library not found, then you must run a MidiShare native app first, before running Java midi. Try msctrl3216.exe... I just start it and keep it running while doing Java Midi]
Play something on your Midi instrument, see if messages show up in the MidiInitPanel when you click the Test MIDI input button.
Click "Test Midi Output" and hear a slow melody play.

TEST JMSL AND JSYN:
Compile and run jmsltestsuite.JMSLJSynApplet Note that you must have the JSyn sdk installed ( http://www.softsynth.com ). Your java build path must include the external jar files: jmsl.jar and JSynClasses.jar
OS X users: JSynClasses.jar is installed as an extension so you do not have to manually add it to your build path.
Windows users: depending on how you installed JSyn (as a browser plugin or the sdk), you may or may not have to explicitely add JSynClasses.jar to you build path. Try without and add if needed.

Also try: jmslexamples.jsyn.Speedy

TEST JSCORE:

We will open an empty JScore, initialize an orchestra, and import a JSyn SynthNote:
Double click on the run_jmsl_score command icon created by JMSLScriptMaker as described in "Using JMSL Score as a stand-alone"

Select Orchestra -> New Orchestra
Select Orchestra -> JSyn -> Import JSyn SynthNote
Click ok on the dialog that opens, to import com.softsynth.jsyn.circuits.FilteredSawtoothBL
Enter a note in the top staff (Windows: right mouse click on the staff, Mac: Apple-click on the staff)
You should hear the notes you entered sound with FilteredSawtoothBL

Developers: Besides jmsl.jar you must also include jscore.jar in your project's build path (Eclipse users go to project properties -> Java Build Path -> Libraries -> Add External Jar, browse for jscore.jar in addition to jmsl.jar).
Build and run jmslexamples.jsyn.JScoreJSynDemo
A music notation window opens. Right Click in the staves to enter notes. You should hear them play with JSyn instruments

JMSL HOME:
Local: Point your browser to <installdir>/jmsl/index.html
WWW: http://www.algomusic.com/jmsl

Nick Didkovsky, http://www.punosmusic.com, http://www.doctornerve.org
didkovn@mail.rockefeller.edu

Phil Burk, http://www.softsynth.com
Use online form to contact Phil at www.softsynth.com