JMSL Tutorial

  1. Table of Contents
  2. Start Tutorial


Welcome to the JMSL Tutorial. We hope this will get you started experimenting with JMSL quickly. It is not essential to finish the entire tutorial before trying things on your own.  In fact it will be best if you jump out of the tutorial as soon as you got an idea for a sketch of a piece or simply coding up some process.  The more you play with JMSL, the better.

This tutorial will touch on the essential notions and classes that constitute JMSL. It will provide you with lots of source code and examples which you can adapt for your own needs.

This tutorial assumes some knowledge of Object Oriented Programming techniques, and a working knowledge of Java. You don't have to be a Java guru to use JMSL, but the notions of objects, classes, inheritance, and a command of Java syntax should be familiar to you.

And as always, post questions to the JMSL mailing list  You should assume no question is too simple.  If it puzzles you, it will puzzle someone else too.
Join the JMSL Mailing List

What JMSL Is

Java Music Specification Language (JMSL) is a Java API for making music.  It is suited for algorithmic composition, live performance, and intelligent instrument design.  At its heart is a polymorphic hierarchical scheduler, which means Java objects that are different from one another can be scheduled together and interact with each other in conceptually clean and powerful ways.

JMSL is tightly integrated with JSyn (Java Synthesizer from, providing you with CD quality audio that you can generate on the fly.  JMSL can send/receive Midi as well.  With JMSL, you can build your own musical applications that make sound with these sound engines.

JMSL's open-ended nature will reward your programming efforts and your creativity by offering you a rich toolkit for making music.

Just to beat on this idea a bit more, with JMSL you can make music based on experimental music theory, statistical processes, any algorithms you can implement... you can notate that music using JMSL Score, or leave it in the abstract. You can use Java's networking tools to grab data off the Internet and sonify it. You can _________ (fill in the blank and start slingin' code).

If you want to open a window with standard music staff notation and start entering notes, JMSL Score will let you do that as well.  Straight out of the box.  Later you can start writing your own custom note transformations, or generating musical material automatically, which JMSL Score will notate for you.  Of course all music generated for and within JMSL Score can be mouse-edited, and transformed again!

If you're a hardware hacker go ahead and write your interface software in C, call this shared library through Java's JNI (Java Native Interface) and wrap that up in a custom JMSL Instrument that can be scheduled and integrated with everything else JMSL has to offer.

You get the picture: There is no such thing as a typical JMSL piece. Conservative use will lead to conservative music; radical use will lead elsewhere. Move forward!

Ok, Let's Go - tutorial overview

This is a narrative table of contents. You might want to read it through a couple of times and then visit the specific links. Or visit the more austere table of contents.

JMSL is based on HMSL, or Hierarchical Music Specification Language. The notion of hierarchies is a key one in JMSL. Learn about structuring musical objects in hierarchies in this short tutorial.

To get events happening over time (a pretty general musical notion), you should learn about MusicJob.  With MusicJob, you can schedule arbitrary events that you define. MusicJob implements JMSL's "Composable" interface: any class that is "Composable" can be scheduled in a composition (hence the name). JMSL hierarchies are made up of Composables.

You can group MusicJobs (or any other Composables) together in collections. Collections can launch their children all at once (parallel), or in a strict order (sequential), or in an order determined during the piece (behavioral). Being Composables themselves, collections can be put inside other collections.

An ordered table of abstract numerical data is called a MusicShape. A MusicShape is a multi-dimensional array which holds double precision floating point numbers. Melodies could be stored in a MusicShape, for example, where dimension 0 might stand for duration, dimension 1 might be pitch, and dimension 2 might be loudness. Collections of more conceptual values can be stored in a MusicShape as well, like parameters that feed a complex musical algorithm. It is the job of JMSL's Instruments and Interpreters, however, to deliver the this interpretation (see below).

JMSL's Instruments and Interpreters are essential classes for interpreting data in a way that is useful to you (ie hearing it as music in some way).  A MusicShape might have a stock MidiInstrument, for example, that interprets data as duration, pitch, velocity, and sustain time. Of course, you can build your own Instruments and Interpreters and sonify data as you like. The default JMSL Interpreter simply prints data to JMSL.out.

JSyn programmers will be happy to see that JMSL is tightly integrated with JSyn.  This section deals with JMSL integration with JSyn (Java Synthesizer), a Java API from  You will learn how to play JSyn circuits with JMSL Instruments and how to control every parameter of your sound.  We cover signal processing Instruments as well, where one JMSL Instrument can control the signal of another.

JMSL's Player class contains a number of MusicShapes and a single instrument that interprets all of them. Since it is a subclass of SequentialCollection, it can execute its MusicShapes in a strict sequence (Verse 1, Chorus, Verse 2) or choose the order at run time with a user-defined Behavior.

JMSL's Score package provides you with a powerful, programmable music notation editor. The user can enter and edit notes by hand, but JScore has an api which allows for the notation of algorithmically generated notes, as well as the transcription of arbitrarily scheduled events. JScore also allows the programmer to design custom transformation classes, which are applied to user-selected notes. Start the JMSL Score tutorial.

JMSL's util package contains a number of useful classes. The Tuning class and its subclasses TuningET and TuningTable offer flexible ways of specifying tunings, and are supported by JSyn instruments. The Bessel class can be used to calculate the spectrum of an FM synthesis pair.

Start Tutorial



  (C) 1997 Phil Burk and Nick Didkovsky, All Rights Reserved
  JMSL is based upon HMSL (C) Phil Burk, Larry Polansky and David Rosenboom.