| 1 |
<?xml version="1.0" encoding="UTF-8"?> |
| 2 |
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" |
| 3 |
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> |
| 4 |
<book> |
| 5 |
<title>JSampler Manual</title> |
| 6 |
|
| 7 |
<bookinfo> |
| 8 |
<author> |
| 9 |
<firstname>by Grigor</firstname> |
| 10 |
|
| 11 |
<surname>Iliev</surname> |
| 12 |
</author> |
| 13 |
|
| 14 |
<copyright> |
| 15 |
<year>2007</year> |
| 16 |
|
| 17 |
<holder>Grigor Iliev <grigor@grigoriliev.com></holder> |
| 18 |
</copyright> |
| 19 |
|
| 20 |
<legalnotice> |
| 21 |
<para>This document is released under the terms of the <ulink |
| 22 |
url="gfdl.html">GNU Free Documentation License</ulink>.</para> |
| 23 |
</legalnotice> |
| 24 |
|
| 25 |
<pubdate>Updated: Mon, 2 Apr 2007</pubdate> |
| 26 |
</bookinfo> |
| 27 |
|
| 28 |
<chapter> |
| 29 |
<title>Introduction</title> |
| 30 |
|
| 31 |
<section> |
| 32 |
<title>What is JSampler?</title> |
| 33 |
|
| 34 |
<para>JSampler is an opensource, platform-independent, GUI front-end for |
| 35 |
<ulink url="http://www.linuxsampler.org">LinuxSampler</ulink>, written |
| 36 |
entirely in <ulink url="http://java.sun.com">Java</ulink>. The main goal |
| 37 |
of the JSampler's design is to be extensible and more flexible regarding |
| 38 |
the integration of different GUI implementations. JSampler consists of |
| 39 |
two parts:</para> |
| 40 |
|
| 41 |
<para><itemizedlist> |
| 42 |
<listitem> |
| 43 |
<para>JSampler core - handles the LSCP command processing and |
| 44 |
event notifications, sent by LinuxSampler, and provides convenient |
| 45 |
data models and controllers to be used instead. The core also |
| 46 |
provides the necessary interfaces that should be implemented by |
| 47 |
all JSamler views.</para> |
| 48 |
</listitem> |
| 49 |
|
| 50 |
<listitem> |
| 51 |
<para>JSampler view - an extension to the JSampler core, which |
| 52 |
provides the user interface part of JSampler.</para> |
| 53 |
</listitem> |
| 54 |
</itemizedlist>The main reason for that is the TCP/IP based |
| 55 |
communication between the LinuxSampler and its front-ends, enabling the |
| 56 |
sampler to be controlled from another computer or device, which may have |
| 57 |
different display requirements and limitations.</para> |
| 58 |
</section> |
| 59 |
|
| 60 |
<section> |
| 61 |
<title>What is a JSampler distribution?</title> |
| 62 |
|
| 63 |
<para>A JSampler distribution consist of the JSampler core and at least |
| 64 |
one view, providing the GUI implementation. Each distribution has its |
| 65 |
own name, which is based on the integrated view extension. Currently, |
| 66 |
there are two distributions:</para> |
| 67 |
|
| 68 |
<para><itemizedlist> |
| 69 |
<listitem> |
| 70 |
<para>JS Classic - A distribution with a standard GUI, capable of |
| 71 |
controlling all features available in LinuxSampler at the time of |
| 72 |
this writing. JS Classic also provides some additional features to |
| 73 |
facilitate the every day work with the sampler and to automate the |
| 74 |
most frequently used configurations.</para> |
| 75 |
</listitem> |
| 76 |
|
| 77 |
<listitem> |
| 78 |
<para>Fantasia - A distribution with a skin based view, which is |
| 79 |
in early development stage and is only partially implemented |
| 80 |
(graphic design by Olivier Boyer).</para> |
| 81 |
</listitem> |
| 82 |
</itemizedlist></para> |
| 83 |
</section> |
| 84 |
</chapter> |
| 85 |
|
| 86 |
<chapter> |
| 87 |
<title>Screenshots</title> |
| 88 |
|
| 89 |
<para>JS Classic with left pane, LS console, statusbar and |
| 90 |
toolbars<graphic fileref="images/js-classic1.png" /></para> |
| 91 |
|
| 92 |
<para>JS Classic without left pane, LS console, statusbar and |
| 93 |
toolbars<graphic fileref="images/js-classic2.png" /></para> |
| 94 |
|
| 95 |
<para>Fantasia<graphic fileref="images/fantasia.png" /></para> |
| 96 |
</chapter> |
| 97 |
|
| 98 |
<chapter> |
| 99 |
<title>Installation</title> |
| 100 |
|
| 101 |
<para></para> |
| 102 |
|
| 103 |
<section> |
| 104 |
<title id="download">What to download?</title> |
| 105 |
|
| 106 |
<para>Currently, there are two distributions available for download - JS |
| 107 |
Classic and Fantasia. However, for now the preferred choice is JS |
| 108 |
Classic, because Fantasia is only partially implemented. The latest |
| 109 |
version of JS Classic is available for download from <ulink |
| 110 |
url="http://downloads.sourceforge.net/jsampler/JS_Classic-0.4a.jar">here</ulink>.</para> |
| 111 |
|
| 112 |
<para>The source code is available in the <ulink |
| 113 |
url="http://downloads.sourceforge.net/jsampler/JSampler-0.4a.tar.bz2">JSampler |
| 114 |
package</ulink>, which also contains this manual and startup scripts |
| 115 |
that can be used to run a particular JSampler distribution.</para> |
| 116 |
|
| 117 |
<para>The latest source code can be obtained from cvs with the following |
| 118 |
command:</para> |
| 119 |
|
| 120 |
<para><command>cvs -z3 |
| 121 |
-d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co |
| 122 |
jsampler</command></para> |
| 123 |
</section> |
| 124 |
|
| 125 |
<section> |
| 126 |
<title id="requirements">Requirements</title> |
| 127 |
|
| 128 |
<para>To run JSampler you need Java Runtime Environment (JRE) version 5 |
| 129 |
or higher. The latest version can be downloaded from <ulink |
| 130 |
url="http://java.sun.com/javase/downloads/">here</ulink>.</para> |
| 131 |
|
| 132 |
<para>To build JSampler distribution from source you need JDK version |
| 133 |
5.0 or higher and the <ulink url="http://ant.apache.org/">Ant |
| 134 |
tool</ulink>.</para> |
| 135 |
</section> |
| 136 |
|
| 137 |
<section> |
| 138 |
<title id="running-js-dist">Running a JSampler distribution</title> |
| 139 |
|
| 140 |
<para>Let's assume that you want to run from the command line |
| 141 |
<code>JS_Classic-0.4a.jar</code>, which is located in |
| 142 |
<code>/home/me/soft</code> directory. First you should check whether the |
| 143 |
<code>java</code> command is in your path and the version requirements |
| 144 |
are met. This can be done by issuing the following command:</para> |
| 145 |
|
| 146 |
<para><command>java -version</command></para> |
| 147 |
|
| 148 |
<para>If the version is 1.5.0 or higher you can run JS Classic by |
| 149 |
issuing the following command:</para> |
| 150 |
|
| 151 |
<para><command>java -jar |
| 152 |
/home/me/soft/JS_Classic-0.4a.jar</command></para> |
| 153 |
|
| 154 |
<para>Otherwise, if the shell response is something like</para> |
| 155 |
|
| 156 |
<para><command>bash: java: command not found</command></para> |
| 157 |
|
| 158 |
<para>or the version requirements are not met, make sure that you have |
| 159 |
installed JRE (or JDK) with the proper version and find its |
| 160 |
location:</para> |
| 161 |
|
| 162 |
<para><literallayout><command>updatedb |
| 163 |
locate bin/java</command></literallayout></para> |
| 164 |
|
| 165 |
<para>The shell should return something like:</para> |
| 166 |
|
| 167 |
<para><literallayout><command>/opt/jdk1.6.0/bin/java |
| 168 |
/opt/jdk1.6.0/bin/javac |
| 169 |
/opt/jdk1.6.0/bin/javadoc |
| 170 |
/opt/jdk1.6.0/bin/javah |
| 171 |
/opt/jdk1.6.0/bin/javap |
| 172 |
/opt/jdk1.6.0/jre/bin/java |
| 173 |
/usr/bin/java</command></literallayout></para> |
| 174 |
|
| 175 |
<para>Now, we know that we have a JDK with a proper version installed |
| 176 |
and its location is <code>/opt/jdk1.6.0</code>. In that case, to run JS |
| 177 |
Classic issue the following command:</para> |
| 178 |
|
| 179 |
<para><command>/opt/jdk1.6.0/bin/java -jar |
| 180 |
/home/me/soft/JS_Classic-0.4a.jar</command></para> |
| 181 |
|
| 182 |
<para><note> |
| 183 |
<para>On some systems double clicking on the jar file will be |
| 184 |
enough.</para> |
| 185 |
</note></para> |
| 186 |
</section> |
| 187 |
|
| 188 |
<section> |
| 189 |
<title>Using a script to run a JSampler distribution</title> |
| 190 |
|
| 191 |
<para>There are scripts In the <code>scripts</code> directory of the |
| 192 |
<ulink |
| 193 |
url="http://downloads.sourceforge.net/jsampler/JSampler-0.4a.tar.bz2">JSampler |
| 194 |
package</ulink> that, with a little adjustments (if needed), can be used |
| 195 |
to run a JSampler distribution. Copy them to a desired location and edit |
| 196 |
with your preferred editor.</para> |
| 197 |
</section> |
| 198 |
|
| 199 |
<section> |
| 200 |
<title>Telling Gnome how to handle jar files</title> |
| 201 |
|
| 202 |
<para>This configuration is optional, but necessary if you want to run |
| 203 |
jar files by (double) clicking on them. In Gnome, by default jar files |
| 204 |
are opened with the Archive Manager. To change that, run a file browser, |
| 205 |
right click on an arbitrary jar file and choose |
| 206 |
<guimenu>Properties</guimenu>, than go to the <guilabel>Open |
| 207 |
With</guilabel> tab and click the <guibutton>Add</guibutton> |
| 208 |
button.</para> |
| 209 |
|
| 210 |
<para><graphic fileref="images/file-properties.png" /></para> |
| 211 |
|
| 212 |
<para>In the <guilabel>Add Application</guilabel> dialog click onto |
| 213 |
<guilabel>Use a custom command</guilabel> label and a text field will |
| 214 |
appear below. If the location of your JRE is <code>/opt/jre1.6.0</code>, |
| 215 |
then enter the following command in the text box:</para> |
| 216 |
|
| 217 |
<para><command>/opt/jre1.6.0/bin/java -jar</command></para> |
| 218 |
|
| 219 |
<para>And then click the <guibutton>Add</guibutton> button.</para> |
| 220 |
|
| 221 |
<para><graphic fileref="images/add-application.png" /></para> |
| 222 |
</section> |
| 223 |
|
| 224 |
<section> |
| 225 |
<title>Adding an application launcher to a Gnome panel</title> |
| 226 |
|
| 227 |
<para>To add an application launcher to a Gnome panel, right click on |
| 228 |
the panel and choose <guimenu>Add to Panel</guimenu>.</para> |
| 229 |
|
| 230 |
<para><graphic fileref="images/add-to-panel.png" /></para> |
| 231 |
|
| 232 |
<para>Then select <guilabel>Custom Application Launcher</guilabel> and |
| 233 |
click the <guibutton>Add</guibutton> button. In the |
| 234 |
<guilabel>Command</guilabel> field, of the <guilabel>Create |
| 235 |
Launcher</guilabel> dialog, fill in the exact command that you use to |
| 236 |
run the JSampler. For more information on how to run a JSampler |
| 237 |
distribution from the command line <link linkend="running-js-dist">click |
| 238 |
here</link>.</para> |
| 239 |
|
| 240 |
<para><graphic |
| 241 |
fileref="images/add-to-panel-create-launcher.png" /></para> |
| 242 |
</section> |
| 243 |
|
| 244 |
<section> |
| 245 |
<title>Running JSampler on Windows</title> |
| 246 |
|
| 247 |
<para>To run JSampler distribution on Windows, put a shortcut on the |
| 248 |
Desktop or Quick Launch, right click on the shortcut and choose |
| 249 |
<guimenu>Properties</guimenu>. In the <guilabel>Target</guilabel> field |
| 250 |
insert the command <code>javaw -jar</code> in the beginning.</para> |
| 251 |
|
| 252 |
<para><graphic fileref="images/win-shortcut.png" /></para> |
| 253 |
</section> |
| 254 |
</chapter> |
| 255 |
|
| 256 |
<chapter> |
| 257 |
<title>Building from source</title> |
| 258 |
|
| 259 |
<para>If you want to build a JSampler distribution from source, first make |
| 260 |
sure that all <link linkend="requirements">requirements</link> are |
| 261 |
met.</para> |
| 262 |
|
| 263 |
<section> |
| 264 |
<title>Building from CVS</title> |
| 265 |
|
| 266 |
<para>When building from CVS, there are some additional steps that |
| 267 |
should be done. JSampler uses two additional libraries, that should be |
| 268 |
downloaded and placed in the <code>lib/required</code> directory:</para> |
| 269 |
|
| 270 |
<para><itemizedlist> |
| 271 |
<listitem> |
| 272 |
<para><ulink |
| 273 |
url="http://sourceforge.net/projects/jlscp/">jlscp</ulink> - A |
| 274 |
java LinuxSampler control protocol API</para> |
| 275 |
</listitem> |
| 276 |
|
| 277 |
<listitem> |
| 278 |
<para><ulink |
| 279 |
url="http://sourceforge.net/projects/juife/">juife</ulink> - Java |
| 280 |
User Interface Framework Extensions</para> |
| 281 |
</listitem> |
| 282 |
</itemizedlist>Download these libraries, create a |
| 283 |
<code>lib/required</code> directory in the JSampler root and copy the |
| 284 |
<code>jlscp.jar</code> and <code>juife.jar</code> files in that |
| 285 |
directory:</para> |
| 286 |
|
| 287 |
<para><literallayout><command>cd /home/me/soft |
| 288 |
wget -c http://downloads.sourceforge.net/jlscp/jlscp-0.4a.tar.bz2 |
| 289 |
tar -xjf jlscp-0.4a.tar.bz2 |
| 290 |
wget -c http://downloads.sourceforge.net/juife/juife-0.4a.tar.bz2 |
| 291 |
tar -xjf juife-0.4a.tar.bz2 |
| 292 |
cvs -z3 -d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co jsampler |
| 293 |
cd jsampler |
| 294 |
mkdirhier lib/required |
| 295 |
cp ../jlscp-0.4a/lib/jlscp.jar lib/required/jlscp.jar |
| 296 |
cp ../juife-0.4a/lib/juife.jar lib/required/juife.jar</command></literallayout></para> |
| 297 |
|
| 298 |
<para>Then follow the steps in the next section.</para> |
| 299 |
</section> |
| 300 |
|
| 301 |
<section> |
| 302 |
<title>Compilation</title> |
| 303 |
|
| 304 |
<para>To build a JSampler distribution, first set the |
| 305 |
<code>JAVA_HOME</code> environment variable to point to your JDK |
| 306 |
directory. If the JDK is installed in /opt/jdk1.6.0 directory, this can |
| 307 |
be done by issuing the following command:</para> |
| 308 |
|
| 309 |
<para><command>export JAVA_HOME=/opt/jdk1.6.0</command></para> |
| 310 |
|
| 311 |
<para>Windows users should do something like:</para> |
| 312 |
|
| 313 |
<para><command>set JAVA_HOME=c:\jdk1.6.0</command></para> |
| 314 |
|
| 315 |
<para>Go to the JSampler root directory and issue the following |
| 316 |
command:</para> |
| 317 |
|
| 318 |
<para><command>ant [target]</command></para> |
| 319 |
|
| 320 |
<para>Where <code>target</code> can be one of the following:</para> |
| 321 |
|
| 322 |
<para><itemizedlist> |
| 323 |
<listitem> |
| 324 |
<para><command>build-jsclassic</command> - Builds a JS Classic |
| 325 |
distribution.</para> |
| 326 |
</listitem> |
| 327 |
|
| 328 |
<listitem> |
| 329 |
<para><command>clean-jsclassic</command> - Removes the JS Classic |
| 330 |
distribution.</para> |
| 331 |
</listitem> |
| 332 |
|
| 333 |
<listitem> |
| 334 |
<para><command>build-fantasia</command> - Builds a Fantasia |
| 335 |
distribution.</para> |
| 336 |
</listitem> |
| 337 |
|
| 338 |
<listitem> |
| 339 |
<para><command>clean-fantasia</command> - Removes the Fantasia |
| 340 |
distribution.</para> |
| 341 |
</listitem> |
| 342 |
|
| 343 |
<listitem> |
| 344 |
<para><command>build-coredoc</command> - Generates the API |
| 345 |
documentation for the JSampler core.</para> |
| 346 |
</listitem> |
| 347 |
|
| 348 |
<listitem> |
| 349 |
<para><command>clean-coredoc</command> - Removes the API |
| 350 |
documentation for the JSampler core.</para> |
| 351 |
</listitem> |
| 352 |
</itemizedlist></para> |
| 353 |
|
| 354 |
<para>So, if you want to build a JS Classic distribution, just issue the |
| 355 |
following command:</para> |
| 356 |
|
| 357 |
<para><command>ant build-jsclassic</command></para> |
| 358 |
|
| 359 |
<para>Then copy the jar file from the <code>dist</code> directory to the |
| 360 |
desired location.</para> |
| 361 |
</section> |
| 362 |
</chapter> |
| 363 |
</book> |
Parent Directory
| 
Revision Log