JSynthLib Documentation

  1. JSynthLib Overview
    1. Purpose
    2. Features
  2. Installing JSynthLib
  3. Using JSynthLib
    1. The Main Windows
      1. Library Window
      2. Scene Window
      3. Bank Editor Window
      4. Single Editor Window
    2. The Menu Functions
      1. File Menu
      2. Library Menu
      3. Patch Menu
      4. Window Menu
      5. Pop-up Menu
  4. Notes about Particular Synths
  5. Troubleshooting
  6. Contributing to JSynthLib
  7. We wish to say thank you to.....

JSynthLib Overview

JSynthLib is a universal MIDI synthesizer librarian / editor. The project aims to eventually support all existing synthesizers.

Why write JSynthLib?

I have a lot of electronic music making equipment: synthesizers, midi controllers, effects processors, all kinds of fun stuff, almost all of which I bought used off the Internet. So why, after I've spend thousands of dollars on hardware, not just spend a couple of hundred more and purchase one of the many available commercial universal patch editor/ librarians such as MIDIQuest or SoundDiver? I like Free Software. I like the control, the power, and the community. With Free Software / Open Source / Copyleft the user is a stakeholder not just a consumer. (Of course, I'm not a Free Software fanatic or I wouldn't be using Java). In 1997 had used GNU/Linux for several months exclusively, but finally gave in and set up a dual-boot with Windows 95 in order to do MIDI Sequencing. For the past several years I've used Cakewalk to sequence and a myriad of Shareware and Freeware editors for various synths (some synths I have no editors for).

Since 1997 both GNU/Linux sequencers and GNU/Linux hardware support have improved dramatically, but leaving Windows behind would require leaving behind all of the Synth editors I used. So in June 1999, I set up to write a universal patch librarian for GNU/Linux. The problem with this is that I still do all of my music stuff in Windows, I merely hope to convert to GNU/Linux when the software is ready. So I require a program which can run under both Operating systems. I began writing in C++ using a cross platform GUI library but quickly got tangled in too many implementation details and caveats and gave up. Recently I realized that Java/Swing gives me the flexibility I need for my application. JSynthLib runs under Windows, GNU/Linux, and Mac OS X.

JSynthLib Features

Editor Features

Extensibility Features

Installing JSynthLib

Step 1: Java Runtime Environment

Make sure you have the J2SE JRE (Java Run Time Environment) or SDK (Software Development Kit) which supports Java 1.4 or later. If you do not have it, you can download it from http://java.sun.com/. If you develop a Java program (for example a JSynthLib synth driver for your synth), you need SDK. Otherwise you need JRE. It spends your disk space less.

Mac OS X comes with java preinstalled. but you should be sure you have the latest update installed.

Step 2: MIDI Provider

JSynthLib-0.19 and/or later uses MIDI Provider, a platform dependent layer of the Java MIDI API. Depends on a version of your Java Environment, you have to install a MIDI Provider.

Step 3: Installing and Invoking JSynthLib

Using JSynthLib

Windows

There are four main types of windows which you will be working with when using JSynthLib. Each provides access to a particular type of data.

Library Window

A Library window holds patches. Different types of patches can be stored in one library, or you can use a library to hold only patches for a particular synthesizer.

A Library Window looks like a table where each row represents one patch. The columns represent different pieces of information about the patch.

The columns are:

In addition to the table of patches, a library window contains a footer which tells the number of patches in the library.

Scene Window

A Scene window looks very much like the library window. It is intended to gather all patches for different synths, which are needed in a particular "scene". A "scene" can be a song or a set of songs - that depends on you. The advantage of a scene is that it contains the locations for the patches in the synth's memories in addition to the patches themselves. You can transfer the patches all together with the "Library->Transfer Scene" function to the synths. Very practical for the recall of a specific sound setup.

The columns are:

In addition to the table of patches, a scene window contains a footer which tells the number of patches in the scene.

Bank Editor Window

A Bank Editor Window looks like a two dimensional table/array of patch names and numbers. This represents a bank of patches for a particular synthesizer. The number of patches in the bank and the numbering scheme used is dependent on the synthesizer. For example,the Oberheim Matrix 1000 holds 100 patches in a bank numbered 0-99, which the Kawai K4 holds 64 numbered 1-A to 16-D.

Single Editor Window

A Single Editor Window is by far the most complex window in the program. This window holds implementation details for one single patch. Here you can set various parameters that make the sound of the patch using sliders, checkboxes, comboboxes, etc. The layout of this window and the controls available depends on the synthesizer to which the patch belongs.

Although, the exact layout and function of the controls shown in the Single Editor will depend on the synthesizer to which the patch belongs, all Single Editor Windows share much in common.

A Control is an element in the Editor Window which controls a specific aspect of the patch, such as Filter Cutoff or Resonance. There are four basic types of controls.

1. a Slider Control consists of a label, a slider, and a numeric readout.. You can tell the current value of the control both graphically (by how far the slider is over) and by the value of the numeric readout. You can change the value of the control only by moving the slider. You can either click to the side of the pointer on the slider, drag the pointer, or click on it and then use the arrows on the keyboard. In any case, each time the value is changed, JSynthLib will send a real-time sysex message to the synthesizer (on synths which support real time sysex messages) telling it to update the value internally. Some synthesizers may take a few seconds to process all the incoming data before being available to play a note , making real-time 'tweaking' difficult.

2. a ComboBox Control consists of a label and a text-field. The text-field tells you what the current value of the control is set for. Clicking on this text-field will produce a menu from which you can choose one of the other values for the control.

3. a CheckBox Control consists of a label and a checkbox. Clicking the check box will turn the setting the control represents on or off.

4. an Envelope Control consists of a graphical depiction of the envelope and a label and numeric display for each parameter the envelope controls. Commonly, these parameters will be the Attack, Delay, Sustain, and Release parameters for a particular DCA. To change a parameter, simply click and drag one of the nodes (rectangles) on the envelope. Some nodes control two parameters, one on the vertical axis and one on the horizontal. Others control only one parameter and are therefore fixed in position on one axis. There are also some nodes which do not control any parameters and are therefore fixed in position. JSynthLib will draw lines connecting all the nodes to show a graphical depiction of the envelope given the current settings.

In addition to these controls, there are a number of interface elements which do not interact with the synthesizer or patch data and only serve to make the presentation of the data more clear.

1. frames which surround groups of related controls. For example a frame labeled "Filter" might surround a group of sliders labeled "Cutoff", "Resonance", and "Envelope Bias" to show you that these three parameters are a part of the synth's filter section.

2. tables which are simply grid-like structures used to hold parameters. As of version 0.12, only the Oberheim Matrix Editor makes use of tables. Note that you can click and drag on the table's headings to change the order in which parameters are displayed.

3. tabs. By clicking on a tab, you are taken to a different set of parameters to edit. Sometimes the tabs surround entire editor screens, but usually they surround only a group of parameters. For example, In the Yamaha TX81z editor, there are four tabs, one for each Operator, by clicking on one of them, the section of controls related to the Operator is set to control the operator you have chosen.

Although Editing on-screen using a mouse or keyboard is efficient and all editing functions can be realized this way, JSynthLib also provides another, optional, method to edit controls-- Faders. A Fader is simply a knob or a slider you might have on a synthesizer or fader box which sends a MIDI control message, when moved. Almost all synthesizers have at least one or two, and some advanced ones such as the Kawai K5000S have as many as sixteen or more. In addition, there are "Controller Surfaces" you can buy which consist only of Faders (either as knobs or slider).

These faders are generally used to edit parameters on synthesizers, but have two major drawbacks. First, they are often designed to work only on a certain, hardwired parameter or only for a particular synthesizer. Second, its difficult to picture what's happening when editing this way, because you don't get any visual feedback. You can't simply look at a Controller Surface and tell what the current settings are for the parameters (unless you have a motorized controller surface).

JSynthLib allows you to overcome these limitations. If you have a Controller Surface or other source of MIDI Controller Messages which has at least 16 Faders, you can edit any synthesizer supported by JSynthLib and see visual feedback on your computer screen.

To set up your controller surface, look under Window->Preferences->MIDI. Look at that section in this documentation for help on setting these up. Once set up, when you move a fader, the corresponding control in the active Editor Window will move.

As you probably realize, however, there are usually more than 16 controls in an editor window. This is where the concept of fader banks come in. A fader bank is a group of 16 controls which respond to faders. You can choose which bank your fader movements are sent to either by using the 15th and 16th buttons on you Controller Surface (if your controller surface supplies buttons and well has faders) or by using the "Next Fader Bank" Option on the toolbar. Note that the labels for the controls in the currently selected fader bank are darkened slightly. To determine which fader bank and fader number will move a particular control, simply let the mouse cursor hover over the label for that control and a tool-tip will pop up with this information.

When you close an editor window, a dialog box will pop up asking what you wish to do with any changes to the patch. If you choose to "Revert to Original", then any changes you have made in the editing session will be lost. If you choose to "Keep Changes", the changes are stored over the original patch in the library and the original version is lost. The third option "Revert and send Changes to Clipboard" is the best of both worlds. The Original patch is kept as in the "Revert to Original" setting,but the changed version of the patch is placed on the clipboard. You can then use the Patch->Paste command to place it into a patch library of bank of your choosing. This is useful if you like the new edits you have created, but also like the original patch.

The Menu Functions

File Menu

Library Menu

The Library menu on the menu bar allows you to access a number of functions to Library and Scene. These functions act on a library or act on all of the patches in the library. Functions which manipulate a single patch within a library are located under the Patch Menu. The available functions in the Library Menu are:

Patch Menu

The Patch menu allows you to access a number of functions which manipulate individual patches which are located either in a Library Window, a Bank Edit Window, or (for some functions) in a Single Patch Editor Window. The available functions in the Patch Menu are:

Window Menu

Pop-up Menu

If your right-click on a patch in a Library Window or a Bank Editor Window, a menu will appear which allows you to manipulate the patch in various ways. All of the functions on this menu are also available from the menu bar and a description of what they do can be found under their menu bar entries in this documentation.

Notes on Particular Synths

Windows -> Synths -> Show Details -> Information shows you issues relating only to the use of JSynthLib with particular synthesizers.

Troubleshooting JSynthLib

[General]MIDI Loopback Test works fine. But JSynthLib cannot send to MIDI data to my synth and/or cannot receive MIDI data from my synth.
Make sure "MIDI In Port" and "MIDI Out Port" in Windows -> Synths dialog is setup correctly. Note that MIDI port setting in Windows -> Preferences -> MIDI is not used for data transfer between JSynthLib and your synth.

[Windows]Where is the JSynthLib setting is saved?
It is saved in Windows Repository, HKEY_CURRENT_USER\Software\JavaSoft\Prefs.

[GNU/Linux]Where is the JSynthLib setting is saved?
It is saved in ~/.java/.

[GNU/Linux]All the fonts have way to much space between the letters and look awful!
This is a Java issue under GNU/Linux. Supposedly it can be fixed by tweaking your fonts.properties file, but I haven't been able to get it to look right. Anyone have a fix for this?

[General]What information should I give when I report a bug?
If you run JSynthLib with the parameter '2' as in java JSynthLib 2 > outputfile, JSynthLib will place debug information regarding any errors that occur in the file 'outputfile'. Sending this file with your bug report would be useful. Also, make sure to include all relevant information about what you were doing when the bug occurred and what your system setup is like.

Contributing to JSynthLib

If you like JSynthLib and want to contribute, you can do this in many ways: The common place to address your notes should be the Tracker on JSynthLib SourceForge site or jsynthlib-devel mailing list.

If you want write bug fixes, additional drivers/editor or core elements please take a look at the JSynthLib Programmer's Guide.

We wish to say thank you to....

...a large number of contributors. Currently the list is not included here, because we would forget one or two for sure. So we left them out complete.

But we would like to say "thank you" to the people outside of the JSynthLib development team who gave us some time saving code examples and ideas: