A short JSynthLib Guide

JSynthLib is an Open Source Universal Synthesizer Patch Editor / Librarian written in the Java Language. Beside a bunch of commercial synths, it provides an editor for MIDIbox SID V1 and MIDIbox FM, which gives you access to all sound parameters and the wavetable sequencer. Since the official beta release of JSynthLib as well as the MIDI API of Java v1.5 has some flaws, I created this short guide in order to describe the required steps to setup JSynthLib for a MIDIbox properly.

Please note: MIDIbox SID V2 is not supported by JSynthLib, due to the enhanced complexity it got an own editor!

Java installation

The latest release is Java V1.6, which is called "J2SE 6.0" at the sun website. The runtime environment (JRE) can be downloaded from java.sun.com. Here a direct link. Note that the development kit (JDK) is only required, if you are planning to (re)compile java sources. As long as you only want to use precompiled java programs, then the JRE package is all you need.

Note: MacOS users don't need to install Java, it's already pre-installed. But a separate MIDI driver is required as Apple's Java MIDI implementation doesn't support SysEx transfers!
Please download the latest and greatest MMJ driver from this location!; copy the mmj.jar and libmmj.jnilib files to /Library/Java/Extensions - done!

JSynthLib installation

The JSynthLib release consists of a single .jar package, which can be started by double-clicking on it. From the command shell (e.g. Linux) it can be started with "java -jar <filename>".

Unfortunately the official 0.20-beta release at the JSynthLib Website has a bug in the synthdriver of MIDIbox SID, which prevents you from uploading patches correctly. Since updates are very rare, I provide a snapshot release from the CVS here:

--> JSynthLib-Snapshot-2010-12-18.jar.zip

Note that I've tested this snapshot with MBSID V1 and MBFM only, I cannot guarantee that the remaining synth drivers are working!

Selecting MIDIbox SID/FM driver

If JSynthLib has been started the first time, the MIDI interface and required synth drivers have to be selected. Go to Window->Preferences->MIDI, and select the MIDI In/Out port, to which one of your synths is connected:

(The reason why I've choosen "MIDI Yoke" as output port is described below)

Go to the "Synth Driver" tab, click on "Add Device..." and search for "MIDIbox SID" and "MIDIbox FM":

Editing a Patch

Now you can either create a new patch library, or you can load an existing one, like the presets which can be downloaded from the MIDIbox SID and MIDIbox FM page.

By double-clicking on an bank entry, the whole bank will be transfered to the MIDIbox (BankStick required!). You can edit individual patches by right-clicking on the bank:

A patch can be edit by right-clicking on the appr. entry:

Java MIDI Bug under Windows

With Java 1.5, Sun introduced an improved support for MIDI interfaces. It works very well with common MIDI events, but has some problems with SysEx strings: once a SysEx string is sent, which is shorter then the previous strings, additional bytes will be appended. Example: if a MIDIbox SID patch is sent, which consists of 262 bytes, and thereafter a sound parameter change is sent by the editor (11 bytes), 262 bytes will be sent again - the 11 new bytes at the beginning, and the remaining 251 bytes of the previous SysEx message at the end. This not only increases the latency of parameter changes, but also violates the MIDI protocol.

This effect has been observed under Windows XP with different MIDI interfaces. It doesn't happen on Linux and Mac OSX. It's not related to JSynthLib itself, since other Java MIDI programs behave similar. In 2004, I wrote a short program which reproduces the bug, and issued it into the error data base. The ticket vanished after some months - so it seems, that Sun doesn't take care about such flaws...

However, there is cure: by sending all SysEx strings through a virtual loopback device like "MIDI Yoke", and forwarding it to the output of the MIDI interface, the additional bytes will be eliminated.

MIDI Yoke can be downloaded from the MIDI-Ox website. The monitor is required as well in order to forward the MIDI stream. Once installed, you need to setup the port routing like shown below:

Btw.: this solution also helps, if your MIDI interface is not multi client capable (if only one program can access the MIDI port). Just send the MIDI data to the MIDI Yoke port instead.

Java MIDI Bugs under various MacOS versions

In the past we had many annoying issues with the MIDI support under MacOS! Actually always a third party driver like mmj or Mandolane was required to get SysEx communication running. With MacOS 10.7 (Lion) both drivers are not working properly anymore, and the integrated Apple solution doesn't support SysEx at all! Beeing a MacOS user by myself, these issues forced me to get rid of Java based solutions, and use Juce as hardware independent platform instead. MIOS Studio2 and the Ctrlr based MIDIbox Panels are the first results!

Last update: 2023-11-04