JMSL Readme

Java Music Specification Language, release 2
Installation Notes

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 with source
examples with source code
instruments
fully functional staff notation API and stand-alone notation app.
all JSyn classes in two JAR files: jsyn-17.1.0.jar (current pure Java version) and jsyn-old-api-20161206.jar (old JSyn API, which JMSL still supports). Thanks to Phil Burk of Softsynth for permission to distribute JSyn jars with JMSL!

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

JAVA Installation

Not every computer ships with Java nowadays, but you can install it for free.

You can check if you have Java installed on your system by opening a command line shell and checking Java versions. Here's how:

On the Max/OSX you want to select Utilities -> Terminal.

On Windows you want a Command Prompt: Press Windows+R to open "Run" box. Type "cmd" and then click "OK" to open a regular Command Prompt.

Once you are at a command line sheel, type:
java -version
If Java is installed, you should get a response like:
java version "22.0.2" 2024-07-16

Now check if you have the Java SDK installed (so you can create new Java programs). Type:
javac -version
If the Java compiler is installed, you should get a version number like:
javac 22.0.2

If your computer failed to report a version number for the above, download and install the JDK, not just the runtime (JRE), by following this link.

Once Java is installed, try the above exercise again.

JMSL License Installation

JMSL needs a license. If you are new to JMSL, request a free evaluation license. If you already purchased one, thanks! The following exercise is the same for both scenarios.

The JMSL License Installer is located in the JMSL distribution folder. The files are named ...

Windows: Install_JMSL_License_WINDOWS.bat

macOS: Install_JMSL_License_MacOSX.command

Double click the one for your system.

The first time you try running the Installer by double clicking on the file, you might get a warning like the following:
Mac warning

Instead of double clicking, if you control-click on the file, a dialog like the following will open:
CTRL=click

The JMSL License Installer will open and show a frame as shown below. Drag the JMSL.lic file you received from algomusic onto the grey rectangle and it will copy it to the right location.
JMSL licence installer

(FYI on OSX that location is ~/.algomusic )

JMSL Installation

Unpack the distribution onto your hard drive and note its location. Spaces in directory names are discouraged.

JMSL ships as a two jar files: jmsl.jar and jscore.jar. These are located in the "classes" directory of the distribution. This was done for more efficient delivery of pieces that may not need music notation. For non-notated works, which only use the core jmsl classes, use jmsl.jar. If your piece uses music notation, you must *also* include jscore.jar

If you have installed a non-jarred previous (extremely early) version of JMSL, delete the folder jwork/website/classes/com/softsynth/jmsl (just delete the jmsl folder!). If you have been using a very early 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.

Java Development Environment Notes

We strongly encourage the use of an integrated development environment like Eclipse or IntelliJ.
Your Java project's build path must include jmsl.jar, jscore.jar, and if you want to make sound with JSyn, it must include jsyn-17.1.0.jar as well.

Helpful guides for two popular Java IDE's:
JMSL IntelliJ Guide
JMSL Eclipse Guide

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.

Note: This example does NOT make sound! You will see JMSL's Music Shape Editor, and you will see durations being printed out in the console as a MusicShape plays through its elements. If this works, you can compile and run JMSL applications!

Ok? Let's do it. We show two versions: command line and using Eclipse.

COMMAND LINE
First CD to the JMSL_v2/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 -> Add 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:

If you want to play with the MusicShapeEditor, you can click and drag along the darker gray bar just below the MusicShape to select elements and apply transformations.

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

TEST JMSL AND JSYN:

JSyn is a Software Synthesizer written in Java by Phil Burk at www.softsynth.com. You can design awesome sounds with it. JMSL can play them in real time.
JMSL supports both the old JSyn API and the new pure Java JSyn API. As such you should include both in your classpath to arbitrarily run examples included in this distribution. For your own projects, you can trim the list of jars you need. But for now we show the four jars you need:

jmsl.jar

jscore.jar

jsyn-17.1.0.jar

jsyn-old-api-20161206.jar

The jmsl and jscore jars are in the classes folder. The jsyn jars are in the lib folder and are included here with permission (Thanks to Phil Burk of SoftSynth.com)

Eclipse Java Build path showing JSyn jars

Eclipse Java Build path showing JSyn jars

Your java build path must include the external jar files: jmsl.jar, jscore.jar, jsyn-17.1.0.jar, and jsyn-old-api-20161206.jar

Compile and run jmslexamples.simple.jsyn2.JSyn2DimensionFun

COMMAND LINE
First CD to the JMSL_v2/TestDev directory which contains the JSyn2DimensionFun source

COMPILE

COMPILE:

javac -d ../classes -classpath ../classes/jmsl.jar;../lib/jsyn-17.1.0.jar  JSyn2DimensionFun.java

OSX:

javac -d ../classes -classpath ../classes/jmsl.jar:../lib/jsyn-17.1.0.jar JSyn2DimensionFun.java

RUN
Windows:

java -classpath ../classes;../classes/jmsl.jar;../lib/jsyn-17.1.0.jar jmslexamples.simple.JSyn2DimensionFun

OSX:

java -classpath ../classes:../classes/jmsl.jar:../lib/jsyn-17.1.0.jar jmslexamples.simple.JSyn2DimensionFun

TEST JSCORE:

Even though JMSL is a programmer's API, we include a stand-alone score notation program that is built on JMSL. Here's how to test it.

Double click on the run_jmsl_score script file in Win or OSX directory . Note to Java developers: this runs the main() method of the class com.softsynth.jmsl.score.ScoreFrame.
JMSL Score

This opens an empty JScore.
We will initialize an orchestra and import a JSyn UnitVoice into a Staff to make sound:

Select Orchestra -> New Orchestra
Select Orchestra -> JSyn -> Import JSyn UnitVoice
JMSL's UnitVoice import dialog
Click OK on the dialog that opens, to import com.jsyn.instruments.SubtractiveSynthVoice
Enter a note in the top staff (Windows: right mouse click on the staff, Mac: Command-click on the staff)
You should hear the notes you entered sound with SubtractiveSynthVoice
Check the Play Section and Loop checkboxes, then click Play. The first measure will cycle.
Double click an existing note and see an editor open.
JMSL Note Editor shows parameters for its JSyn instrument
Change the parameter values and hear the music change in real time as the score plays.

DEVELOPERS:

Let's build a project that uses JMSL's Score music notation package. The project will build a score algorithmically, notated on staff notation, where every note will have control over every public parameter of the synth voices you hear.

Create a Java project in Eclipse as described in "Java Development Environment Notes" above.

Locate the "src" folder in you JMSL_v2 distribution folder. You will see three sub-directories there. Locate and drag jmslexamples/jsyn2/JSyn2FMScore.java into your Eclipse project's src folder. Tell Eclipse to make a copy of the file instead of linking to it.
You will notice a red-underlined error under the package name. This is because JSyn2FMScore is part of a Java package, but the current location is in the default location:
Roll your mouse over the yellow balloon and see the error message:
Then let Eclipse troubleshoot the package location by letting it "Move JSyn2FMScore.java to package jmslexamples.jsyn2" by clicking the yellow balloon help in Eclipse next to the package declaration.
Repeat this exercise with three more files (ie drag them ito your project's src folder and fix the package location): jmslexamples/jsyn2/unitvoices/FMVoice.java, FMPair.java, and UnitSourceTester.java.
When everything's settled you should have nice looking project like so:

Build and run jmslexamples.jsyn2.JSyn2FMScore
A music notation window opens with algorithmically generated score. Click play and look and listen.

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

Nick Didkovsky, http://www.didkovsky.com
nick@didkovsky.com

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