JSampler Manualby GrigorIliev2007Grigor Iliev <grigor@grigoriliev.com>This document is released under the terms of the GNU Free Documentation License.Updated: Fri, 10 August 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.6a.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.6a.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.6a.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.5a.tar.bz2
tar -xjf jlscp-0.5a.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.