JSynthLib Programmer's Guide

Go to JSynthLib User's Guide.

Table of Contents

1. Before we start...
   1. Coding Style
   2. Using Javadoc
   3. Proper Use of Access Control Modifier
   4. Code Sharing
   5. Debug/Error Message
   6. Exception Handling
2. How to Compile Files and Check Out from SVN
3. Writing a Synth Driver
   1. Introduction
      1. How hard is it to add support for a new synthesizer to JSynthLib?
      2. What do I need in order to add support for a new synthesizer?
      3. Who owns the copyright to the code I contribute to JSynthLib?
   2. The Layout of JSynthLib
   3. JSynthLib API Document
   4. Synth Driver Structure
   5. Writing a Device Class
      1. Create a file
      2. Code Your Device Class
      3. Keeping Persistent Parameters
      4. Tell the core program about your driver
   6. Writing a Single Driver
      1. Create a file
      2. Write the damn thing
      3. Implement calculateChecksum Method
      4. Implement storePatch and sendPatch Methods
      5. Implement createPatch and editPatch Methods
   7. Writing a Bank Driver
   8. Writing a Single Editor
      1. How to Add SysexWidgets
      2. The provided SysexWidgets
      3. Param Model and Sender
      4. Action Listener
   9. Writing a Converter
4. Testing the driver
   1. Introduction
   2. Testing your Single Driver
   3. Testing your Bank Driver
   4. Testing your Editor
5. FAQ
6. Related Documentation and Links
   1. JSynthLib
   2. Java Language
   3. MIDI Specification
   4. Applications

I. Before we start...

Even if someone want write just a driver for his/her synth, the code will be read by others too. Maybe some changes are necessary since an API change or another developer want take a look how a special issue is solved. Following some rules makes the life easier for all who contribute to JSynthLib.

I.a. Coding Style

Important note: Please use an indentation level of 4 and a displayed tab width value of 8 (see FAQ for reasons).

I.b. Using Javadoc

I.c. Proper Use of Access Control Modifier (for core developers)

Especially we have to be very careful to make a public (or package) field. If you really need to access it, consider defining a getter or setter method (ex. getFoo() or setFoo()) or using protected.

I.d. Code Sharing

I.e. Debug/Error Message

Use ErrorMsg.reportError("Title", "Message", e) for error message which users need to see.

I.e. Exception Handling

    // BAD EXAMPLE
    try {
        ....
    } catch (Exception e) {
    }

    try {
        ....
    } catch (ASpecificException e) {
        // This is normal.
    }

    try {
        ....
    } catch (ASpecificException e) {
        ErrorMsg.reportStatus(e);
    }

II. How to Compile Files and Check Out from SVN

    mkdir JSynthLib
    cd JSynthLib
    jar xf ../JSynthLib-XXX.jar

    # On Windows use semicolon (;) instead of colon (:).
    javac -classpath '.:groovy.jar' org/jsynthlib/*/*/*.java org/jsynthlib/*/*.java
    javac core/*.java
    javac synthdrivers/*/*/*.java synthdrivers/*/*.java
    javac *.java

    find . -name '*.java' | grep -v midiprovider/ > js
    # On Windows use semicolon (;) instead of colon (:).
    javac -classpath '.:groovy.jar' @js

    make all

    ant

Next, open up a Command Prompt or shell set to 50 row display and set it to that directory. This is used to run JSynthLib for testing (the 50 row display helps keep error messages from scrolling off the screen too fast). Make sure that the java[.exe] and javac[.exe] executables are in your path for easy access.

Important: Once you've extracted the .jar file and made changes to the resultant files, you must launch JSynthLib using;

    # On Windows use semicolon (;) instead of colon (:).
    java -classpath '.:groovy.jar' JSynthLib -D 3

Although the source code for each version of JSynthLib is included in the JSynthLib distribution, you may wish to download the latest version of the source code to get any improvements made after the latest release. We sometimes have to change API to make JSynthLib better. Your driver developed for the released JSynthLib may be required some changes for the latest version. You can downloaded the latest source code via SVN from SourceForge SVN server.

    svn co https://jsynthlib.svn.sourceforge.net/svnroot/jsynthlib/trunk/JSynthLib JSynthLib

III. Writing a Synth Driver

III.a. Introduction

III.a.1. How hard is it to add support for a new synthesizer to JSynthLib?

III.a.2. What do I need in order to add support for a new synthesizer?

1. At the very least, you need a sysex specification for your synthesizer. In most cases, the sysex specification is located in the back of the manual, but this is not always the case. Sometimes they are also available on the Internet if you look around enough.
2. You probably also need the synthesizer you wish to add support for (for testing). While it might be possible to do it without the synthesizer, it would be pretty tough.
3. You'll need a copy of the Java 1.4 (or higher) SDK. This is available for free from java.sun.com. This contains the various tools used to compile JSynthLib.
4. You'll need a text editor in order to edit code. Anything will work. I wrote a significant part of the JSynthLib core code using EDIT.COM which comes with Windows. More recently, I've switched to jEdit, a Java based emacs-like programmer's editor with syntax highlighting and bracket matching.

   To be compliant with the JSynthLib core sources it is best if you use an editor which supports our code conventions (especially concerning the tab settings).

   Some of the most active developers of this project started using Eclipse (for setup have a look at the FAQ). It knows Java syntax well. I can search reference and/or definition of a member, compile files auto-magically, has integrated SVN support, etc.

5. Finally, you'll need to be able to program in Java. If you've programmed in C++ before, you can probably pick it up in about an hour (I did). If you are coming from C++ the most important thing to know is that Java passes all objects by reference, not value.

III.a.3. Who owns the copyright to the code I contribute to JSynthLib?

    /*
     * Copyright 20XX Your Name
     *
     * This file is part of JSynthLib.
     *
     * JSynthLib is free software; you can redistribute it and/or modify
     * it under the terms of the GNU General Public License as published
     * by the Free Software Foundation; either version 2 of the License,
     * or(at your option) any later version.
     *
     * JSynthLib is distributed in the hope that it will be useful, but
     * WITHOUT ANY WARRANTY; without even the implied warranty of
     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     * General Public License for more details.
     *
     * You should have received a copy of the GNU General Public License
     * along with JSynthLib; if not, write to the Free Software
     * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
     * USA
     */

III.b. The Layout of JSynthLib

When you compile parts of JSynthLib, always do so from the main JSynthLib directory. For example, to compile the file synthdrivers\BossDR660Driver\BossDR660DrumkitDriver.java sit in the main JSynthLib directory and type

    javac synthdrivers\BossDR660Driver\BossDR660DrumkitDriver.java

    javac BossDR660DrumkitDriver.java # does not work

III.c. JSynthLib API Document

    javadoc -locale en_US -breakiterator -quiet -d doc/api_docs -use -author -version -overview doc/programming.html core/*.java

III.d. Synth Driver Structure

Device

A class extends {@link core.Device} class. It defines some informations for your synthesizer, for example synth model name, MIDI port assigned, etc. And it has a list of drivers (Single Driver, Bank Driver, and/or Converter) described below.

Single Patch

Single Patch is a set of MIDI system exclusive messages of a sound data, etc.

Single Driver

Single Driver provides routines to support a Single Patch.

A Single Driver extends {@link core.IPatchDriver} class and allows JSynthLib to detect a patch data for the synthesizer, to communicate with the synthesizer. Once this is written, JSynthLib will have Librarian support for your synthesizer.

A Single Driver optionally can have a Single Editor invoked by IPatchDriver.editPatch() method.

Bank Patch

Bank Patch (bulk dump patch) is a bank of single patches.

Bank Driver

Bank Driver provides routines to support a Bank Patch.

A Bank Driver extends {@link core.IPatchDriver} and allows JSynthLib to combine a single patch into a bank patch and to extract a single patch from a bank patch. While this functionality isn't strictly necessary, it is nice to have if your synth supports bulk dump patch.

A Bank Driver can have a Bank Patch Editor. But you don't have to take care of it because usually the default editor can be used.

Converter

A driver implements {@link core.IConverter} interface. This is a special driver. Converter simply converts a patch, which is imported from a file or MIDI input, into it's associated with to another format. Most of synthdrivers don't use this.

Single Editor

This is the fun part. This is a graphical representation of the synthesizers internals which allows parameters to be changed and edited. It is invoked by a ISinglePatch.edit method.

    {@link core.Device} class (required)

    {@link core.IDriver} interface
      {@link core.IPatchDriver} interface extends {@link core.IDriver} (required)
      {@link core.IConverter} interface (optional)

    {@link core.IPatch} interface
      {@link core.ISinglePatch} interface extends {@link core.IPatch} (required)
      {@link core.IBankPatch} interface extends {@link core.IPatch} (optional)

    {@link core.Device} class

    {@link core.Driver} class implements {@link core.IPatchDriver}
    {@link core.BankDriver} class implements {@link core.IPatchDriver} (optional)
    {@link core.Converter} class implements {@link core.IConverter} (optional)

    {@link core.Patch} class implements {@link core.ISinglePatch} and {@link core.IBankPatch} class

III.e. Writing a Device class

III.e.1. Create a File

III.e.2. Code Your Device Class

    /** Constructor for DeviceListWriter. */
    public KawaiK4Device() {
        super("Kawai", "K4/K4R", "F07E..0602400000040000000000f7",
              INFO_TEXT, "Brian Klock & Gerrit Gehnen");
    }

    /** Constructor for for actual work. */
    public KawaiK4Device(Preferences prefs) {
        this();
        this.prefs = prefs;

        addDriver(new KawaiK4BulkConverter());
        addDriver(new KawaiK4SingleDriver());
        addDriver(new KawaiK4BankDriver());
        // ... other drivers
    }

The second constructor is used for the actual work. It creates drivers and add them onto the driver list by using addDriver method.

III.e.3. Keeping Persistent Parameters

III.e.4. Tell the core program about your Synth Driver

    java core/DeviceListWriter

Invoke JSynthLib, go to Window->Preferences...->Synth Driver, and click Add Device button. If all goes well, you see your Device name is on the list.

Now JSynthLib knows about your synth driver. Now the time to write drivers :)

III.f. Writing a Single Driver

III.f.1. Create a File

III.f.2. Write the damn thing

First, you change your constructor to provide the correct information to the driver. This information is used by the functions in Driver class to manipulate the data. If your synthesizer were very simple, that would be just about all there was to writing the driver. However, most synths have their unique quirks and features that are impossible to describe using just data. Therefore you will probably have to override some of the functions in Driver class to perform for your synth.

III.f.3. Implement calculateChecksum Method

{@link core.Driver#calculateChecksum(Patch, int, int, int)} actually calculate checksum. The default method uses the most common algorithm used by YAMAHA, Roland, and etc. It adds all of the data bytes, takes the lowest 7 bits, XORs them with 127 and adds one to get the checksum. If your synth uses a different algorithm, override this method.

{@link core.Driver#calculateChecksum(Patch)} is called by some methods in {@link core.Driver} class. If your synth does not use checksum, override it by an empty method. If the patch for your synth consists of only one Sysex Message, you don't have to override the method. If your synth uses a patch which consists of multiple Sysex Messages, you need to override the method. See, for example, RolandTD6SingleDriver.java.

III.f.4. Implement storePatch and sendPatch Methods

Looking at your driver code (which you stole from the KawaiK4 code like I told you to). You'll see that we had to implement two methods, {@link core.Driver#storePatch(Patch, int, int)} and {@link core.Driver#sendPatch(Patch)}. storePatch sends a patch to a buffer in your synth specified by a user, and sendPatch sends a patch to the editing buffer in your synth. This is common, since usually, slightly different sysex messages are used to send a patch to the editing buffer (and not overwrite a patch) or to a specific patch (and overwrite). Change these functions to match your synth. If your synth has no editing buffer, you'll need to overwrite the send method to treat a specific patch location on the synth as the edit buffer it (see the EmuProteusMPS Driver for an example of this).

III.f.5. Implement createPatch and editPatch Methods

One of these is the {@link core.Driver#createNewPatch} method which returns a new (blank) patch. You may use {@link core.DriverUtil#createNewPatch} for this method. See RolandTD6SingleDriver as an example.

The other is the {@link core.Driver#editPatch} method which opens an Single Editor window for the patch. You should be able to figure out how to write these by looking at the code for the KawaiK4.

There may be other functions in Driver.java that you will need to override for your synth. In general, spend time looking at that file, the drivers for all of the other synths, and API document to get a feel for how things are done.

Once your driver is working, JSynthLib now has Librarian support for your synth. Celebrate. And send in the code to us so we can include it in the next release of JSynthLib.

III.g. Writing a Bank Driver

You may want to use your Single Driver in your Bank Driver. You can pass your Single Driver via the constructor of your Bank Driver. Here is a part of RolandTD6Device Constructor;

    public RolandTD6Device(Preferences prefs) {
        ...
        // add drivers
        TD6SingleDriver singleDriver = new TD6SingleDriver();
        addDriver(singleDriver);
        addDriver(new TD6BankDriver(singleDriver));
    }

III.h. Writing a Single Editor

Writing an editor is a little bit harder than writing a driver. It is harder because you have to write a Java Swing interface. Swing is the default graphical toolkit that comes with Java. It is the graphical interface which all of JSynthLib uses. If you don't know Swing at all you might want to get a Java book, but you can get away with just the Tutorial on java.sun.com and the API guide that you can download when you download the JDK.

The job of your Single Editor class is to set up the interface for your editor by using a number of functions and widgets provided by JSynthLib and a number of Swing features. It is invoked by {@link core.IPatch#edit()} method. It returns a {@link core.JSLFrame} object. What you have to do is create a class extending {@link core.PatchEditorFrame} class which extends {@link core.JSLFrame} class. (You don't have to extend {@link core.PatchEditorFrame}, if you want to create a JSLFrame object from scratch.)

I like to set up all my sliders and CheckBoxes and figure out where they go and what there ranges are first, get a nice pretty GUI on screen and then go back and put in the numbers to make it actually work. Basically you are going to create a number of JPanes and place controls inside them using the {@link core.PatchEditorFrame#addWidget} method. Then you insert these JPanes onto scrollPane (the background of the window). scrollPane is created by JSynthLib for your convenience.

If you want Tabs and such, you can implement them the same way the other editors do using the Swing feature. For a simple synth, you can get away with just putting all the JPanes directly onto scrollPane.

You can do like with the Single Driver and start out by copying an existing editor over and renaming the file, classes, constructor, etc. I recommend the YamahaTX81z Editor since it is one of the simplest Single Editor.

Make sure you've taken a look at how all the other Single Editors are set up, the code contained within them explains all better than I could cope with mere words.

III.h.1. How to Add SysexWidgets:

    // example from the TX81z Editor
    addWidget(cmnPane,  // pane to put the SysexWidget on
              new ScrollBarWidget("Feedback", patch, 0, 7, 0,
                                  new ParamModel(patch, 100),
                                  new VcedSender(53)),
              1, 1,     // horizontal/vertical location
              3, 1,     // horizontal/vertical size
              18);      // fader number

The second parameter is the SysexWidget to create, in this case a {@link core.ScrollBarWidget}. Notice that the widget itself takes a few parameters, we'll get to that in a moment.

The next four parameters represent the location and size of the SysexWidget within the Pane (Read up on gridbaglayout in Sun's Java tutorial). They are (in order) the horizontal location, the vertical location, the horizontal size, and the vertical size).

The last parameter is the fader number. Each SysexWidget needs to have a unique fader number and they should go in order. label all SysexWidgets with positive numbers except for CheckBoxes which get negative numbers (buttons). So the sliders etc. would go 1, 2, 3, 4, 5.. and the CheckBoxes would go -1, -2, -3, -4, -5... etc.

III.h.2. The Provided SysexWidgets:

{@link core.ScrollBarWidget} contain a label, a slider, and a numeric readout of the value of the slider. They are the most common SysexWidgets. The first parameter to the SysexWidget should be its label. the second one will always be patch. The next two values are the minimum and maximum values on the slider. The fifth value is a value offset for the slider. This is usually zero, but gets used if the parameter in the synthesizer is (for example) 0 through 127, but should be displayed as -63 to +63). The last two parameters are a Param Model and Sender for this fader (we'll get to those after we deal with some other SysexWidgets.).

{@link core.ScrollBarLookupWidget} are just like ScrollBarWidget but they let the numeric readout contain values other than numbers. They are used rarely. For example if a parameter can take the values of OFF, 1,2,3,4,5,6 or 7, you might use one. You wouldn't want to use a ScrollBarWidget because the first value should be OFF, not zero. You could also use a ComboBoxWidget in this situation. The constructor is about the same as for a combo box.

{@link core.ComboBoxWidget} are drop-down list of choices that are best used for non-numeric data (such as LFO shape). Here's an example of setting up a ComboBoxWidget:

    addWidget(panel,
              new ComboBoxWidget("EG Shift", patch,
                                 new ParamModel(patch, 20 + i*5),
                                 new AcedSender(i*5 + 4),
                                 new String[] {"96db", "48db", "24db", "12db"}),
              0, 4, 1, 1, 5);

{@link core.CheckBoxWidget} are used for parameters that can be either on or off. Heres an example:

    addWidget(lfoPane,
              new CheckBoxWidget("1", patch,
                                 new ParamModel(patch, 55 + 3*13),
                                 new VcedSender(3*13 + 8)),
              3, 6, 1, 1, -19);

{@link core.EnvelopeWidget}, the final SysexWidget type, are vastly more complex than the others.They represent several parameters on the synth, such as the attack, decay, sustain, and release of a VCA envelope.

Note that the fader number you give to an envelope widget represents is its first fader number, and it will take as many as it needs starting at that one to represent all of it's parameters.

The constructor for an envelope widget takes a list of {@link core.EnvelopeWidget.Node}s. Each Node is one of the movable squares on the envelope. Some of these nodes are stationary, some contain two parameters on the synth and can be moved vertically and horizontally, and others contain only one parameter and can therefore be moved in only one direction. Here is an example:

    EnvelopeWidget.Node[] nodes = new EnvelopeWidget.Node[] {
        // origin
	new EnvelopeWidget.Node(0, 0, null, 0, 0, null, 0, false, null, null, null, null),
        // delay time
	new EnvelopeWidget.Node(0, 100, new K4Model(patch, 30 + i),
	        		0, 0, null,
	        		0, false, new K4Sender(34, i), null, "Dly", null),
        // atack time
	new EnvelopeWidget.Node(0, 100, new K4Model(patch, 62 + i),
	        		100, 100, null,
	        		25, false, new K4Sender(45, i), null, "A", null),
        // decay time and sustain level
	new EnvelopeWidget.Node(0, 100, new K4Model(patch, 66 + i),
				0, 100, new K4Model(patch, 70 + i),
				25, false, new K4Sender(46, i), new K4Sender(47, i), "D", "S"),
        // null node for constant length horizontal line
	new EnvelopeWidget.Node(100, 100, null,
	        		EnvelopeWidget.Node.SAME, 0, null,
				0, false, null, null, null, null),
        // release time
	new EnvelopeWidget.Node(0, 100, new K4Model(patch, 74 + i),
				0, 0, null,
				0, false, new K4Sender(48, i), null, "R", null),
    };
    addWidget(panel,
              new EnvelopeWidget("DCA Envelope", patch, nodes),
              0, 0, 3, 5, 33);

    public Node(int minx, int maxx, ParamModel pmodelx,
                int miny, int maxy, ParamModel pmodely,
                int basey,
                boolean invertx,
                SysexSender senderx, SysexSender sendery,
                String namex, String namey)

I hope that made sense, if not, just take a look at the way EnvelopeWidget are used by various single editors.

{@link core.CheckBoxWidget}, {@link core.KnobWidget}, {@link core.KnobLookupWidget}, {@link core.LabelWidget}, {@link core.PatchNameWidget}, {@link core.ScrollBarLookupWidget}, {@link core.VertScrollBarWidget}, {@link core.SpinnerWidget}, and {@link core.TreeWidget} are also provided.

III.h.3. Param Model and Sender

We want to keep track of the changes to the patch so that when we next call up this patch the changes are there. We also want to be able to set the SysexWidgets to the correct values for a particular patch when the Single Editor is opened. This is what the Param Model (Parameter Model) is for.

Param Model is a class object which implements {@link core.SysexWidget.IParamModel} interface. The interface provides two method, {@link core.SysexWidget.IParamModel#set} and {@link core.SysexWidget.IParamModel#get}. They just read (get) and write (set) a parameter value.

The default Param Model (constructor ParamModel(Patch patch, int offset)) is used by the YamahaTX81z editor. Its constructor takes two parameters, the patch being edited and the offset into the patch of the value.

Sometimes the default Param Model can be used, other times it is either necessary or more convenient to subclass ParamModel to make your own Model. Here is a simple example from the KawaiK5000 Editor:

    class K5kSrcModel extends ParamModel {
        public K5kSrcModel(Patch patch, int src, int offset) {
            super(patch, 91 - 1 + offset + 86 * (src - 1));
        }
    }

Here is a more complex example from the KawaiK4 Editor:

    class K4Model extends ParamModel {
        private int bitmask;
        private int mult;
        ...
        public K4Model(Patch p, int offset, int bitmask) {
            super(p, offset + 8);
            this.bitmask = bitmask;
            if ((bitmask & 1) == 1)
                mult = 1;
            else if ((bitmask & 2) == 2)
                mult = 2;
            else if ((bitmask & 4) == 4)
                mult = 4;
            else if ((bitmask & 8) == 8)
                mult = 8;
            else if ((bitmask & 16) == 16)
                mult = 16;
            else if ((bitmask & 32) == 32)
                mult = 32;
            else if ((bitmask & 64) == 64)
                mult = 64;
            else if ((bitmask & 128) == 128)
                mult = 128;
        }
    
        public void set(int i) {
            patch.sysex[ofs] = (byte) ((i * mult) + (patch.sysex[ofs] & (~bitmask)));
        }
    
        public int get() {
            return ((patch.sysex[ofs] & bitmask) / mult);
        }
    }

In the case of the KawaiK4, we couldn't just use the default ParamModel class, because some Kawai K4 parameters are bitmasks stored in the same byte as other parameters. The above class K4Model takes care of deciphering the bitmasks. MIDIboxFMModel.java is another example which uses bitmasks.

You can also implement SysexWidget.IParamModel directly if you don't need patch or ofs field. See AlesisDMProModel as an exmaple.

A Sender sends a Sysex message generated by Param Model to the synth informing it of the change. It is a class object which implements {@link core.SysexWidget.ISender} interface. The interface has only one method, {@link core.SysexWidget.ISender#send}.

Here's an example of a Sender from the Kawai K4 Editor. It extends {@link core.SysexSender} class which implements {@link core.SysexWidget.ISender}:

    class K4Sender extends SysexSender {
        private int source;
    
        private byte[] b = {
                (byte) 0xF0, 0x40, 0, 0x10, 0x00,
                0x04, 0, 0, 0, (byte) 0xF7
        };
    
        public K4Sender(int parameter, int source) {
            this.source = source;
            b[6] = (byte) parameter;
        }
    
        public K4Sender(int parameter) {
            this.source = 0;
            b[6] = (byte) parameter;
        }
    
        public byte[] generate(int value) {
            b[2] = (byte) (channel - 1);
            b[7] = (byte) ((value / 128) + (source * 2));
            b[8] = (byte) (value & 127);
            return b;
        }
    }

Here is another example of RolandJV80SystemSetupEditor which uses {@link core.SysexSender#SysexSender(String)} constructor.

    static class JVSender extends SysexSender {
        int offset;

        // retrieve default from patch
        public JVSender(int offset) {
            super("F041@@461200000000**00F7");
            this.offset = offset;
        }

        protected byte[] generate(int value) {
            byte[] data = super.generate(value);
            data[JV80Constants.ADDR4_IDX] = (byte) offset;
            JV80Constants.calculateChecksum(data, 1);
            return data;
        }
    }

The constructor for a SysexSender takes a String parameter representing which parameter a particular instance of the Sender should control and creates a sysex message containing all necessary information except for the data value to be transmitted and the channel (Device ID) to transmit on. When the SysexWidget attached to this instance of the SysexSender moves, the generate method of the SysexSender gets called with the value to send. The generate function simply puts the value and channel into the message and returns it.

RolandTD6.RolandDT1Sender is an example which implements {@link core.SysexWidget.ISender} directly without extending {@link core.SysexSender}. It is little complexed to support generic Roland DT1 (Data Transfer) message.

Often a Single Editor will have one or more Param Model and/or Sender. Sometimes more than one is used because a synth may use more than one method to transfer the data.

Note how the Param Models and Senders are used in the various editors. A SysexWidget doesn't care if you use the default Param Model or if you implement your own. This makes the SysexWidgets much more extensible. They can be used without needing to know how exactly the data is supposed to be accessed. The Param Model and Sender takes care of that.

This all probably sounds more complex than it really is, just take a look at the editors for various other synths, try changing some things maybe to see how they work. It shouldn't be too hard to figure out, but I'm not too good at explaining.

III.h.4. Action Listener - Image Handling

Note that the following code seems to work.

    // Bad Example : does not work with jar
    algoIcon[0] = new ImageIcon("synthdrivers/YamahaTX81z/1.gif");

 
    // Good Example
    algoIcon[0] = new ImageIcon(getClass().getResource("1.gif"));

III.i. Writing a Converter

IV. Testing Your Driver...

IV.a. Introduction

This is an attempt to do a test plan when writing a new driver for JSynthLib. It take little time to do and may help finding problem before the driver is available publicly.

First thing to do: you must do some single dump and some bank dump from your synth to your computer without using JSynthLib (I use Cakewalk to do that but there should be some simple freeware to do this). Save those dump in .syx format (binary). Remember, we are not using JSynthLib at his point in order to have something "clean" to refer to when testing the new driver.

One important note : It seems that some synth could have "bugs" in their factory patches. So if you resend those patch to the synth, they will be "corrected". To test this, you can simply resend the bank dump from your PC to the synth and do a new bank dump from synth to PC. If there are difference and the first bank dump and the second, this is probably the problem I mention. Normally, resending the second dump should be consistent after that. Any dump from synth to PC should be identical to the second dump since the synth has now "corrected" the original dump! I had this problem with some specific patch of my Nova after restoring original patches on the unit with the "Restore from ROM" command. I had spent some time figuring out the difference between dump so I'm warning you not to do the same mistake!

Now, redo the same thing (single dump and bank dump) but this time, change your device id number on the synth (sometime call global MIDI channel). Those new dump may have some byte different or not. In most case, single dump will be identical while bank dump may be different.

IV.b. Testing your Single Driver

• Try to open a "clean" .syx file from JSynthLib and send it to the edit buffer of your synth. Try it to see if the name and sound seems OK. Do a dump (with external soft) and compare the file, they should be identical. Make sure that the patch is really in the edit buffer (and not written in memory) by changing patch on the synth and going back to the patch number it was before the send: the patch you just send should not be there (This may vary with some synth Model).
• Try to do a single patch dump to JSynthLib. Check that the patch name is correct in JSynthLib. Export it to a .syx file and compare it (diff) with the original "clean" version. Should be the same. (Those steps will confirm that loading external file and receiving/sending a dump give the same result)
• Try to store this patch at different location in the synth. At least, try to store in patch 0 or 1 and to the highest patch number of your synth. Do that in every user bank if possible. Verify that the patch appear in all the location you save it.
• Create a new patch with JSynthLib and send it to your synth. Make sure the new patch didn't do anything wrong on the synth (if your new patch is all 0 with a name, some synth may react strangely to invalid combination of values). If you want to play safe, your createNewPatch method could construct a valid default patch for your synth: just do a dump of a simple patch and integrate this in the code.
• Now, redo all those step with a different id number on the synth. Change JSynthLib accordingly to that new Id (channel number). Some time, it's possible you left a bug if you didn't test with a different ID (channel number).

IV.c. Testing your Bank Driver

• Open a "clean" .syx bank file with JSynthLib. Make sure that all individual patch name make sense.
• Send one patch from the bank to your synth. Make a dump (from your synth) of that single patch with another software. Now, do a diff of this dump with a previously made dump of that same patch. This will make sure that extracting a patch from a bank and sending it to the synth gave the exact same thing. You should really do a binary compare of the file since just playing it is not enough. Even if some parameter are sent wrong, the patch may sound correct to your ear, so you need to do a real compare.
• Erase all bank memory on your synth. Now, send the whole bank from JSynthLib to your synth. Do a dump from the synth to your external software. The .syx file should be the same than the original one. This is not the same thing than the previous step: extracting a single patch from a bank and sending a whole bank is very different. Note: one potential problem here is that some synth may need more time to "digest" a big bank dump from your PC. In those cases, you should put some delay in your code until you find a safe speed.
• Try sending your bank to all possible banks in the synth and verify their integrity.
• Now, you should redo some of those steps with a different channel number, just to make sure. Note that the bank .syx file will likely have the channel byte different so you need to extract a "clean" bank with the new channel first from your synth.

IV.d. Testing your Editor

Note: I never write an editor but here are some suggestions:

• Usually, modifications done in the editor are sent in real-time to your synth. However, the editor must also make the same modification in the single patch that is edited. To test that it works correctly, you should made some modification in the editor and save the patch (do not send that patch to the edit buffer of your synth). Now, on your synth, the same patch should be in the edit buffer since all single edit will have send sysex for every parameter changed. Do a dump from your synth to PC and compare it to the patch JSynthLib just created. They should be identical. Normally, you should try each fader or knob in the editor to be sure they are controlling the correct parameter. Just move each one at random when creating the patch. If you do that some time (random edit, saving and comparing the file), chance are the editor behave correctly.

Note: I suggest to move each fader at random because putting all of them to 0 or max is not a good idea since your editor may send knob info to the wrong place and you will not be able to detect it by comparing the .syx file!

Last step, send your new driver for integration in the next release of JSynthLib!

Yves Lefebvre
ivanohe@abacom.com
www.abacom.com/~ivanohe

V. FAQ

How can I send a bug report?

1. Output message in debug mode. Invoke JSynthLib with option '2'. This will output debug information including Java version, OS type, etc.
2. A specific way to reproduce the bug.
3. Any other useful 'fact', other than 'guess'.

Is there any tips for debug?

1. This is pretty common, but just sprinkle System.out.println statements through out the troublesome code. Get a good idea of what values are what when and look for something that shouldn't be. Better yet, use ErrorMsg.reportError("ErrorMsg goes here") instead.
2. Use a MIDI cable to connect your computer's MIDI out to MIDI in. Use build in MIDI Monitor Window or get a program (for example MIDI-OX for Windows) from the Internet to print out all incoming MIDI messages. Now you can see what messages your editor/driver is sending and you can check them for correctness.

Why shall I use an indentation level of 4 with a displayed tab width of 8?

The reason for a displayed tab width of 8 is compatibility with the following essential tools:

• ... viewvc, the SVN browser that SourceForge uses.
• ... Notepad, the default editor of Microsoft Windows.
• ... Unix command line tools like cat, less, tail, ...

How to set up Eclipse for JSynthLib?

1. Install Subclipse

   You need to install Subclipse, the SVN plugin for Eclipse. Follow the installation instructions at http://subclipse.tigris.org/install.html. The instructions are for Eclipse 3.0. If you have a newer version the process is slightly different:

   1. From the Help menu choose Software Updates.
   2. Selected the Available Software tab and click Add Site...
   3. Type the update URL from Step 4 of the Subclipse installation instructions and click OK.
   4. Expand the subclipse url and check Subclipse. You may also want to check some of the optional components, I installed them all.
   5. Click the Install button.
   6. Restart eclipse after installing the plugin.
2. Create a Project
   1. From the File menu choose New then Project.
   2. Under SVN choose Checkout projects from SVN, then click Next.
   3. Select Create a new repository location and click Next
   4. Enter the url https://jsynthlib.svn.sourceforge.net/svnroot/jsynthlib/trunk and click next;
   5. You may get a warning because Eclipse doesn't understand SourceForge's wildcard http certificate. Click Accept Permanently.
   6. Select the JSynthLib folder and click Finish.
3. Set up the Library Setting and Exclude MidiProvider

   (Note: These steps don't seem to be required using Eclipse 3.3)

   1. Right click (Ctrl-Click on a Mac) on the new project and choose Properties.
   2. Choose Java Build Path, then the Libraries tab.
   3. Click Add JARs....
   4. Click the arrow next to JSynthLib and select groovy.jar, then click OK.
   5. Click on the Source tab.
   6. Click the arrow next to JSynthLib, then Excluded: (None), then Edit....
   7. At the bottom of the window, next to the box that says Exclusion patterns, click Add Multiple....
   8. Choose midiprovider, then click OK three times to close all the Properties windows.
4. Preferences->Java->Editor->Displayed tab width set to '8'. (Why?)
5. Setting up Javadocs (Optional, but recommended)
   1. For using the Javadocs for the JDK (e.g. the "J2SE 5.0 Documentation") go to Preferences->Java->Installed JREs->Edit->Javadoc URL set to the directory where you installed the Javadocs. A short description is shown when moving the mouse cursor on a class or a member. You can see the full documentation by hitting Shift-F2 after selecting a class or member.
   2. Don't forget to generate the Javadocs for JSynthlib with Project->Generate Javadoc....

VI. Related Documentation

VI.a. JSynthLib

• JSynthLib Home Page
• JSynthLib SourceForge.net Developer Home Page (contains the SVN Repository)
• JSynthLib mailing list
• JSynthLib Yahoo group - file section
• MIDI Provider for Windows. JDK older than 1.4.2 requires this.

VI.b. Java Language

Java Home Page

Some selected documents:

• SUN Java tutorials
  The online tutorials
• Java^TM 2 SDK Version 1.4.2 API specification
  The online 2 SDK Version 1.4.2 API specification
• Java^TM 2 SDK Version 1.4.2, Standard Edition Documentation
  Downloadable Java 2 SDK Version 1.4.2 documentation
• The Java Programming Language
  written by Ken Arnold and James Gosling (creators of Java Language).
• Code Conventions for the Java Programming Language
  Standards and styles for coding Java programs.
• How to Write Doc Comments for Javadoc
  describes the tag conventions SUN follows at Java Software.
• Java Sound API Programmer's Guide
  

Java Sound Resources is a good resource of Java Sound.

VI.c. MIDI Specification

• MMA (Midi Manufacturer Association)
  The MMA is the original source for information on MIDI (Musical Instrument Digital Interface) technology.

The Complete MIDI 1.0 Detailed Specification isn't downloadable from the MMA Web site.
But you'll find a MIDI specification for example at

• www.borg.com.

VI.d. Applications

• Eclipse
• JEdit
• MIDI-OX and MIDI York