JSampler Manualby GrigorIliev2007Grigor Iliev <grigor@grigoriliev.com>This document is released under the terms of the GNU Free Documentation License.Updated: Sat, 8 December 2007IntroductionWhat is JSampler?JSampler is an opensource, platform-independent, GUI front-end for
LinuxSampler, written
entirely in Java. The main goal
of the JSampler's design is to be extensible and more flexible regarding
the integration of different GUI implementations. JSampler consists of
two parts:JSampler core - handles the LSCP command processing and
event notifications, sent by LinuxSampler, and provides convenient
data models and controllers to be used instead. The core also
provides the necessary interfaces that should be implemented by
all JSamler views.JSampler view - an extension to the JSampler core, which
provides the user interface part of JSampler.The main reason for that is the TCP/IP based
communication between the LinuxSampler and its front-ends, enabling the
sampler to be controlled from another computer or device, which may have
different display requirements and limitations.What is a JSampler distribution?A JSampler distribution consist of the JSampler core and at least
one view, providing the GUI implementation. Each distribution has its
own name, which is based on the integrated view extension. Currently,
there are two distributions:JS Classic - A distribution with a standard GUI, capable of
controlling all features available in LinuxSampler at the time of
this writing. JS Classic also provides some additional features to
facilitate the every day work with the sampler and to automate the
most frequently used configurations.Fantasia - A distribution with a modern skin based view
(initial graphic design by Olivier Boyer).ScreenshotsJS Classic with left pane, LS console, statusbar and toolbarsJS Classic without left pane, LS console, statusbar and
toolbarsFantasiaInstallationWhat to download?Currently, there are two distributions available for download -
JS
Classic and Fantasia.The source code is available in the JSampler
package, which also contains this manual and startup scripts
that can be used to run a particular JSampler distribution.The latest source code can be obtained from cvs with the following
command:cvs -z3
-d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co
jsamplerRequirementsTo run JSampler you need Java Runtime Environment (JRE) version 6
or higher. The latest version can be downloaded from here.To build JSampler distribution from source you need JDK version
6.0 or higher and the Ant
tool.Running a JSampler distributionLet's assume that you want to run from the command line
JS_Classic-0.8a.jar, which is located in
/home/me/soft directory. First you should check whether the
java command is in your path and the version requirements
are met. This can be done by issuing the following command:java -versionIf the version is 1.6.0 or higher you can run JS Classic by
issuing the following command:java -jar
/home/me/soft/JS_Classic-0.8a.jarOtherwise, if the shell response is something likebash: java: command not foundor the version requirements are not met, make sure that you have
installed JRE (or JDK) with the proper version and find its
location:updatedb
locate bin/javaThe shell should return something like:/opt/jdk1.6.0/bin/java
/opt/jdk1.6.0/bin/javac
/opt/jdk1.6.0/bin/javadoc
/opt/jdk1.6.0/bin/javah
/opt/jdk1.6.0/bin/javap
/opt/jdk1.6.0/jre/bin/java
/usr/bin/javaNow, we know that we have a JDK with a proper version installed
and its location is /opt/jdk1.6.0. In that case, to run JS
Classic issue the following command:/opt/jdk1.6.0/bin/java -jar
/home/me/soft/JS_Classic-0.8a.jarOn some systems double clicking on the jar file will be
enough.Using a script to run a JSampler distributionThere are scripts In the scripts directory of the
JSampler
package that, with a little adjustments (if needed), can be used
to run a JSampler distribution. Copy them to a desired location and edit
with your preferred editor.Telling Gnome how to handle jar filesThis configuration is optional, but necessary if you want to run
jar files by (double) clicking on them. In Gnome, by default jar files
are opened with the Archive Manager. To change that, run a file browser,
right click on an arbitrary jar file and choose
Properties, than go to the Open
With tab and click the Add
button.In the Add Application dialog click onto
Use a custom command label and a text field will
appear below. If the location of your JRE is /opt/jre1.6.0,
then enter the following command in the text box:/opt/jre1.6.0/bin/java -jarAnd then click the Add button.Adding an application launcher to a Gnome panelTo add an application launcher to a Gnome panel, right click on
the panel and choose Add to Panel.Then select Custom Application Launcher and
click the Add button. In the
Command field, of the Create
Launcher dialog, fill in the exact command that you use to
run the JSampler. For more information on how to run a JSampler
distribution from the command line click here.Running JSampler on WindowsTo run JSampler distribution on Windows, put a shortcut on the
Desktop or Quick Launch, right click on the shortcut and choose
Properties. In the Target field
insert the command javaw -jar in the beginning.Building from sourceIf you want to build a JSampler distribution from source, first make
sure that all requirements are
met.Building from CVSWhen building from CVS, there are some additional steps that
should be done. JSampler uses two additional libraries, that should be
downloaded and placed in the lib/required directory:jlscp - A
java LinuxSampler control protocol APIjuife - Java
User Interface Framework ExtensionsDownload these libraries, create a
lib/required directory in the JSampler root and copy the
jlscp.jar and juife.jar files in that
directory:cd /home/me/soft
wget -c http://downloads.sourceforge.net/jlscp/jlscp-0.7a.tar.bz2
tar -xjf jlscp-0.7a.tar.bz2
wget -c http://downloads.sourceforge.net/juife/juife-0.4a.tar.bz2
tar -xjf juife-0.4a.tar.bz2
cvs -z3 -d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co jsampler
cd jsampler
mkdirhier lib/required
cp ../jlscp-0.5a/lib/jlscp.jar lib/required/jlscp.jar
cp ../juife-0.4a/lib/juife.jar lib/required/juife.jarThen follow the steps in the next section.CompilationTo build a JSampler distribution, first set the
JAVA_HOME environment variable to point to your JDK
directory. If the JDK is installed in /opt/jdk1.6.0 directory, this can
be done by issuing the following command:export JAVA_HOME=/opt/jdk1.6.0Windows users should do something like:set JAVA_HOME=c:\jdk1.6.0Go to the JSampler root directory and issue the following
command:ant [target]Where target can be one of the following:build-jsclassic - Builds a JS Classic
distribution.clean-jsclassic - Removes the JS Classic
distribution.build-fantasia - Builds a Fantasia
distribution.clean-fantasia - Removes the Fantasia
distribution.build-coredoc - Generates the API
documentation for the JSampler core.clean-coredoc - Removes the API
documentation for the JSampler core.So, if you want to build a JS Classic distribution, just issue the
following command:ant build-jsclassicThen copy the jar file from the dist directory to the
desired location.Using OrchestrasOrchestras feature is like bookmarks/favorites for instruments.
Instead of having a thousands of unsorted instruments you can categorize
your most used instruments for quick access by adding them to orchestras.
You can create an arbitrary number of orchestras and in any orchestra you
can add an arbitrary number of instruments.Orchestras are not handled by the back-end (LinuxSampler) and
does not depend on the Instruments Database. The
orchestras are handled by JSampler and are stored on the local machine
in <jsampler-home>/orchestras.xml. To port the
orchestras to another machine just copy that file.Managing OrchestrasTool buttons:Create new
orchestraEdit
selected orchestraRemove
selected orchestraTo create a new orchestra, click on the
Orchestras tab then click the Create new
orchestra button in the Manage
Orchestras tool:Then
choose orchestra name and description and click
OK button. To remove an orchestra, select the orchestra and click the
Remove selected orchestra button. To edit an
orchestra, select the orchestra and click the Edit selected
orchestra button, or just double-click the orchestra to
edit.To change the position of an orchestra in the orchestra list,
select the orchestra and use Alt+Up Arrow and
Alt+Down Arrow to move the selected orchestra
up/down. You can also use Alt+Shift+Up Arow to
move the selected orchestra on top and Alt+Shift+Down
Arrow to move the selected orchestra to bottom.Managing InstrumentsTool buttons:Add new
instrumentEdit
selected instrumentRemove
selected instrumentTo add a new instrument to orchestra, first select the desired
orchestra from the combobox then click the Add new
instrument button:The easiest way to add an instrument to orchestra is to
right-click an instrument in the Instruments
Database, then select Add To Orchestra
and choose the orchestra to which to add the selected instrument.
Note that you can select and add more than one instrument to
orchestra at once.To remove an instrument, select the instrument and click the
Remove selected instrument button. To edit an
instrument, select the instrument and click the Edit selected
instrument button, or just double-click the instrument to
edit.To change the position of an instrument in the instrument
list, select the instrument and use Alt+Up
Arrow and Alt+Down Arrow to move the
selected instrument up/down. You can also use Alt+Shift+Up
Arow to move the selected instrument on top and
Alt+Shift+Down Arrow to move the selected
instrument to bottom.Loading InstrumentsTo load an instrument from orchestra to a sampler channel,
right-click on the instrument, select Load
Instrument, then choose on which channel to load the selected
instrument. You can also load an instrument from orchestra to a sampler
channel using the instrument chooser of the sampler channel - click
Select instrument from orchestra radio button,
choose orchestra and isntrument from the comboboxes and click
OK button.