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: Sat, 8 December 2007</pubdate> |
26 |
</bookinfo> |
27 |
|
28 |
<chapter id="INTRODUCTION"> |
29 |
<title>Introduction</title> |
30 |
|
31 |
<section id="WHAT_IS_JSAMPLER"> |
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 id="WHAT_IS_JSAMPLER_DISTRIBUTION"> |
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 modern skin based view |
79 |
(initial graphic design by Olivier Boyer).</para> |
80 |
</listitem> |
81 |
</itemizedlist></para> |
82 |
</section> |
83 |
</chapter> |
84 |
|
85 |
<chapter id="SCREENSHOTS"> |
86 |
<title>Screenshots</title> |
87 |
|
88 |
<para>JS Classic with left pane, LS console, statusbar and toolbars</para> |
89 |
|
90 |
<para><ulink url="images/js-classic1.png"><inlinegraphic |
91 |
fileref="images/js-classic1-preview.png" /></ulink></para> |
92 |
|
93 |
<para>JS Classic without left pane, LS console, statusbar and |
94 |
toolbars</para> |
95 |
|
96 |
<para><ulink url="images/js-classic2.png"><inlinegraphic |
97 |
fileref="images/js-classic2-preview.png" /></ulink></para> |
98 |
|
99 |
<para>Fantasia</para> |
100 |
|
101 |
<para><ulink url="images/fantasia.png"><inlinegraphic |
102 |
fileref="images/fantasia-preview.png" /></ulink></para> |
103 |
</chapter> |
104 |
|
105 |
<chapter id="INSTALLATION"> |
106 |
<title>Installation</title> |
107 |
|
108 |
<para></para> |
109 |
|
110 |
<section id="DOWNLOAD"> |
111 |
<title>What to download?</title> |
112 |
|
113 |
<para>Currently, there are two distributions available for download - |
114 |
<ulink |
115 |
url="http://downloads.sourceforge.net/jsampler/JS_Classic-0.8a.jar">JS |
116 |
Classic</ulink> and <ulink |
117 |
url="http://downloads.sourceforge.net/jsampler/Fantasia-0.8a.jar">Fantasia</ulink>.</para> |
118 |
|
119 |
<para>The source code is available in the <ulink |
120 |
url="http://downloads.sourceforge.net/jsampler/JSampler-0.8a.tar.bz2">JSampler |
121 |
package</ulink>, which also contains this manual and startup scripts |
122 |
that can be used to run a particular JSampler distribution.</para> |
123 |
|
124 |
<para>The latest source code can be obtained from cvs with the following |
125 |
command:</para> |
126 |
|
127 |
<para><command>cvs -z3 |
128 |
-d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co |
129 |
jsampler</command></para> |
130 |
</section> |
131 |
|
132 |
<section id="REQUIREMENTS"> |
133 |
<title lang="" xreflabel="">Requirements</title> |
134 |
|
135 |
<para>To run JSampler you need Java Runtime Environment (JRE) version 6 |
136 |
or higher. The latest version can be downloaded from <ulink |
137 |
url="http://java.sun.com/javase/downloads/">here</ulink>.</para> |
138 |
|
139 |
<para>To build JSampler distribution from source you need JDK version |
140 |
6.0 or higher and the <ulink url="http://ant.apache.org/">Ant |
141 |
tool</ulink>.</para> |
142 |
</section> |
143 |
|
144 |
<section id="RUNNING_JSAMPLER"> |
145 |
<title>Running a JSampler distribution</title> |
146 |
|
147 |
<para>Let's assume that you want to run from the command line |
148 |
<code>JS_Classic-0.8a.jar</code>, which is located in |
149 |
<code>/home/me/soft</code> directory. First you should check whether the |
150 |
<code>java</code> command is in your path and the version requirements |
151 |
are met. This can be done by issuing the following command:</para> |
152 |
|
153 |
<para><command>java -version</command></para> |
154 |
|
155 |
<para>If the version is 1.6.0 or higher you can run JS Classic by |
156 |
issuing the following command:</para> |
157 |
|
158 |
<para><command>java -jar |
159 |
/home/me/soft/JS_Classic-0.8a.jar</command></para> |
160 |
|
161 |
<para>Otherwise, if the shell response is something like</para> |
162 |
|
163 |
<para><command>bash: java: command not found</command></para> |
164 |
|
165 |
<para>or the version requirements are not met, make sure that you have |
166 |
installed JRE (or JDK) with the proper version and find its |
167 |
location:</para> |
168 |
|
169 |
<para><literallayout><command>updatedb |
170 |
locate bin/java</command></literallayout></para> |
171 |
|
172 |
<para>The shell should return something like:</para> |
173 |
|
174 |
<para><literallayout><command>/opt/jdk1.6.0/bin/java |
175 |
/opt/jdk1.6.0/bin/javac |
176 |
/opt/jdk1.6.0/bin/javadoc |
177 |
/opt/jdk1.6.0/bin/javah |
178 |
/opt/jdk1.6.0/bin/javap |
179 |
/opt/jdk1.6.0/jre/bin/java |
180 |
/usr/bin/java</command></literallayout></para> |
181 |
|
182 |
<para>Now, we know that we have a JDK with a proper version installed |
183 |
and its location is <code>/opt/jdk1.6.0</code>. In that case, to run JS |
184 |
Classic issue the following command:</para> |
185 |
|
186 |
<para><command>/opt/jdk1.6.0/bin/java -jar |
187 |
/home/me/soft/JS_Classic-0.8a.jar</command></para> |
188 |
|
189 |
<para><note> |
190 |
<para>On some systems double clicking on the jar file will be |
191 |
enough.</para> |
192 |
</note></para> |
193 |
</section> |
194 |
|
195 |
<section id="USING_SCRIPT"> |
196 |
<title>Using a script to run a JSampler distribution</title> |
197 |
|
198 |
<para>There are scripts In the <code>scripts</code> directory of the |
199 |
<ulink |
200 |
url="http://downloads.sourceforge.net/jsampler/JSampler-0.8a.tar.bz2">JSampler |
201 |
package</ulink> that, with a little adjustments (if needed), can be used |
202 |
to run a JSampler distribution. Copy them to a desired location and edit |
203 |
with your preferred editor.</para> |
204 |
</section> |
205 |
|
206 |
<section id="GNOME_JAR_ASSOCIATIONS"> |
207 |
<title>Telling Gnome how to handle jar files</title> |
208 |
|
209 |
<para>This configuration is optional, but necessary if you want to run |
210 |
jar files by (double) clicking on them. In Gnome, by default jar files |
211 |
are opened with the Archive Manager. To change that, run a file browser, |
212 |
right click on an arbitrary jar file and choose |
213 |
<guimenu>Properties</guimenu>, than go to the <guilabel>Open |
214 |
With</guilabel> tab and click the <guibutton>Add</guibutton> |
215 |
button.</para> |
216 |
|
217 |
<para><graphic fileref="images/file-properties.png" /></para> |
218 |
|
219 |
<para>In the <guilabel>Add Application</guilabel> dialog click onto |
220 |
<guilabel>Use a custom command</guilabel> label and a text field will |
221 |
appear below. If the location of your JRE is <code>/opt/jre1.6.0</code>, |
222 |
then enter the following command in the text box:</para> |
223 |
|
224 |
<para><command>/opt/jre1.6.0/bin/java -jar</command></para> |
225 |
|
226 |
<para>And then click the <guibutton>Add</guibutton> button.</para> |
227 |
|
228 |
<para><graphic fileref="images/add-application.png" /></para> |
229 |
</section> |
230 |
|
231 |
<section id="GNOME_LAUNCHER"> |
232 |
<title>Adding an application launcher to a Gnome panel</title> |
233 |
|
234 |
<para>To add an application launcher to a Gnome panel, right click on |
235 |
the panel and choose <guimenu>Add to Panel</guimenu>.</para> |
236 |
|
237 |
<para><graphic fileref="images/add-to-panel.png" /></para> |
238 |
|
239 |
<para>Then select <guilabel>Custom Application Launcher</guilabel> and |
240 |
click the <guibutton>Add</guibutton> button. In the |
241 |
<guilabel>Command</guilabel> field, of the <guilabel>Create |
242 |
Launcher</guilabel> dialog, fill in the exact command that you use to |
243 |
run the JSampler. For more information on how to run a JSampler |
244 |
distribution from the command line <link |
245 |
linkend="RUNNING_JSAMPLER">click here</link>.</para> |
246 |
|
247 |
<para><graphic |
248 |
fileref="images/add-to-panel-create-launcher.png" /></para> |
249 |
</section> |
250 |
|
251 |
<section id="RUNING_ON_WINDOWS"> |
252 |
<title>Running JSampler on Windows</title> |
253 |
|
254 |
<para>To run JSampler distribution on Windows, put a shortcut on the |
255 |
Desktop or Quick Launch, right click on the shortcut and choose |
256 |
<guimenu>Properties</guimenu>. In the <guilabel>Target</guilabel> field |
257 |
insert the command <code>javaw -jar</code> in the beginning.</para> |
258 |
|
259 |
<para><graphic fileref="images/win-shortcut.png" /></para> |
260 |
</section> |
261 |
</chapter> |
262 |
|
263 |
<chapter id="BUILDING_FROM_SOURCE"> |
264 |
<title>Building from source</title> |
265 |
|
266 |
<para>If you want to build a JSampler distribution from source, first make |
267 |
sure that all <link linkend="REQUIREMENTS">requirements</link> are |
268 |
met.</para> |
269 |
|
270 |
<section id="BUILDING_FROM_CVS"> |
271 |
<title>Building from CVS</title> |
272 |
|
273 |
<para>When building from CVS, there are some additional steps that |
274 |
should be done. JSampler uses two additional libraries, that should be |
275 |
downloaded and placed in the <code>lib/required</code> directory:</para> |
276 |
|
277 |
<para><itemizedlist> |
278 |
<listitem> |
279 |
<para><ulink |
280 |
url="http://sourceforge.net/projects/jlscp/">jlscp</ulink> - A |
281 |
java LinuxSampler control protocol API</para> |
282 |
</listitem> |
283 |
|
284 |
<listitem> |
285 |
<para><ulink |
286 |
url="http://sourceforge.net/projects/juife/">juife</ulink> - Java |
287 |
User Interface Framework Extensions</para> |
288 |
</listitem> |
289 |
</itemizedlist>Download these libraries, create a |
290 |
<code>lib/required</code> directory in the JSampler root and copy the |
291 |
<code>jlscp.jar</code> and <code>juife.jar</code> files in that |
292 |
directory:</para> |
293 |
|
294 |
<para><literallayout><command>cd /home/me/soft |
295 |
wget -c http://downloads.sourceforge.net/jlscp/jlscp-0.7a.tar.bz2 |
296 |
tar -xjf jlscp-0.7a.tar.bz2 |
297 |
wget -c http://downloads.sourceforge.net/juife/juife-0.4a.tar.bz2 |
298 |
tar -xjf juife-0.4a.tar.bz2 |
299 |
cvs -z3 -d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co jsampler |
300 |
cd jsampler |
301 |
mkdirhier lib/required |
302 |
cp ../jlscp-0.5a/lib/jlscp.jar lib/required/jlscp.jar |
303 |
cp ../juife-0.4a/lib/juife.jar lib/required/juife.jar</command></literallayout></para> |
304 |
|
305 |
<para>Then follow the steps in the next section.</para> |
306 |
</section> |
307 |
|
308 |
<section id="COMPILATION"> |
309 |
<title>Compilation</title> |
310 |
|
311 |
<para>To build a JSampler distribution, first set the |
312 |
<code>JAVA_HOME</code> environment variable to point to your JDK |
313 |
directory. If the JDK is installed in /opt/jdk1.6.0 directory, this can |
314 |
be done by issuing the following command:</para> |
315 |
|
316 |
<para><command>export JAVA_HOME=/opt/jdk1.6.0</command></para> |
317 |
|
318 |
<para>Windows users should do something like:</para> |
319 |
|
320 |
<para><command>set JAVA_HOME=c:\jdk1.6.0</command></para> |
321 |
|
322 |
<para>Go to the JSampler root directory and issue the following |
323 |
command:</para> |
324 |
|
325 |
<para><command>ant [target]</command></para> |
326 |
|
327 |
<para>Where <code>target</code> can be one of the following:</para> |
328 |
|
329 |
<para><itemizedlist> |
330 |
<listitem> |
331 |
<para><command>build-jsclassic</command> - Builds a JS Classic |
332 |
distribution.</para> |
333 |
</listitem> |
334 |
|
335 |
<listitem> |
336 |
<para><command>clean-jsclassic</command> - Removes the JS Classic |
337 |
distribution.</para> |
338 |
</listitem> |
339 |
|
340 |
<listitem> |
341 |
<para><command>build-fantasia</command> - Builds a Fantasia |
342 |
distribution.</para> |
343 |
</listitem> |
344 |
|
345 |
<listitem> |
346 |
<para><command>clean-fantasia</command> - Removes the Fantasia |
347 |
distribution.</para> |
348 |
</listitem> |
349 |
|
350 |
<listitem> |
351 |
<para><command>build-coredoc</command> - Generates the API |
352 |
documentation for the JSampler core.</para> |
353 |
</listitem> |
354 |
|
355 |
<listitem> |
356 |
<para><command>clean-coredoc</command> - Removes the API |
357 |
documentation for the JSampler core.</para> |
358 |
</listitem> |
359 |
</itemizedlist></para> |
360 |
|
361 |
<para>So, if you want to build a JS Classic distribution, just issue the |
362 |
following command:</para> |
363 |
|
364 |
<para><command>ant build-jsclassic</command></para> |
365 |
|
366 |
<para>Then copy the jar file from the <code>dist</code> directory to the |
367 |
desired location.</para> |
368 |
</section> |
369 |
</chapter> |
370 |
|
371 |
<chapter id="USING_ORCHESTRAS"> |
372 |
<title>Using Orchestras</title> |
373 |
|
374 |
<para>Orchestras feature is like bookmarks/favorites for instruments. |
375 |
Instead of having a thousands of unsorted instruments you can categorize |
376 |
your most used instruments for quick access by adding them to orchestras. |
377 |
You can create an arbitrary number of orchestras and in any orchestra you |
378 |
can add an arbitrary number of instruments.<note> |
379 |
<para>Orchestras are not handled by the back-end (LinuxSampler) and |
380 |
does not depend on the <guilabel>Instruments Database</guilabel>. The |
381 |
orchestras are handled by JSampler and are stored on the local machine |
382 |
in <code><jsampler-home>/orchestras.xml</code>. To port the |
383 |
orchestras to another machine just copy that file.</para> |
384 |
</note></para> |
385 |
|
386 |
<section id="MANAGING_ORCHESTRAS"> |
387 |
<title>Managing Orchestras</title> |
388 |
|
389 |
<para>Tool buttons:</para> |
390 |
|
391 |
<para><inlinegraphic fileref="images/new16.png" /> <guilabel>Create new |
392 |
orchestra</guilabel></para> |
393 |
|
394 |
<para><inlinegraphic fileref="images/edit16.png" /> <guilabel>Edit |
395 |
selected orchestra</guilabel></para> |
396 |
|
397 |
<para><inlinegraphic fileref="images/delete16.png" /> <guilabel>Remove |
398 |
selected orchestra</guilabel></para> |
399 |
|
400 |
<para>To create a new orchestra, click on the |
401 |
<guilabel>Orchestras</guilabel> tab then click the <guibutton>Create new |
402 |
orchestra</guibutton> button in the <guilabel>Manage |
403 |
Orchestras</guilabel> tool:</para> |
404 |
|
405 |
<para><graphic align="center" fileref="images/new-orchestra.png" />Then |
406 |
choose orchestra name and description and click |
407 |
<guibutton>OK</guibutton> button. </para> |
408 |
|
409 |
<para>To remove an orchestra, select the orchestra and click the |
410 |
<guibutton>Remove selected orchestra</guibutton> button. To edit an |
411 |
orchestra, select the orchestra and click the <guibutton>Edit selected |
412 |
orchestra</guibutton> button, or just double-click the orchestra to |
413 |
edit.<tip> |
414 |
<para>To change the position of an orchestra in the orchestra list, |
415 |
select the orchestra and use <guilabel>Alt+Up Arrow</guilabel> and |
416 |
<guilabel>Alt+Down Arrow</guilabel> to move the selected orchestra |
417 |
up/down. You can also use <guilabel>Alt+Shift+Up Arow</guilabel> to |
418 |
move the selected orchestra on top and <guilabel>Alt+Shift+Down |
419 |
Arrow</guilabel> to move the selected orchestra to bottom.</para> |
420 |
</tip></para> |
421 |
|
422 |
<para></para> |
423 |
</section> |
424 |
|
425 |
<section id="MANAGING_INSTRUMENTS"> |
426 |
<title>Managing Instruments</title> |
427 |
|
428 |
<para>Tool buttons:</para> |
429 |
|
430 |
<para><inlinegraphic fileref="images/new16.png" /> <guilabel>Add new |
431 |
instrument</guilabel></para> |
432 |
|
433 |
<para><inlinegraphic fileref="images/edit16.png" /> <guilabel>Edit |
434 |
selected instrument</guilabel></para> |
435 |
|
436 |
<para><inlinegraphic fileref="images/delete16.png" /> <guilabel>Remove |
437 |
selected instrument</guilabel></para> |
438 |
|
439 |
<para>To add a new instrument to orchestra, first select the desired |
440 |
orchestra from the combobox then click the <guilabel>Add new |
441 |
instrument</guilabel> button:</para> |
442 |
|
443 |
<para><graphic align="center" |
444 |
fileref="images/add-instrument-to-orchestra.png" /><tip> |
445 |
<para>The easiest way to add an instrument to orchestra is to |
446 |
right-click an instrument in the <guilabel>Instruments |
447 |
Database</guilabel>, then select <guimenu>Add To Orchestra</guimenu> |
448 |
and choose the orchestra to which to add the selected instrument. |
449 |
Note that you can select and add more than one instrument to |
450 |
orchestra at once.</para> |
451 |
</tip>To remove an instrument, select the instrument and click the |
452 |
<guibutton>Remove selected instrument</guibutton> button. To edit an |
453 |
instrument, select the instrument and click the <guibutton>Edit selected |
454 |
instrument</guibutton> button, or just double-click the instrument to |
455 |
edit.<tip> |
456 |
<para>To change the position of an instrument in the instrument |
457 |
list, select the instrument and use <guilabel>Alt+Up |
458 |
Arrow</guilabel> and <guilabel>Alt+Down Arrow</guilabel> to move the |
459 |
selected instrument up/down. You can also use <guilabel>Alt+Shift+Up |
460 |
Arow</guilabel> to move the selected instrument on top and |
461 |
<guilabel>Alt+Shift+Down Arrow</guilabel> to move the selected |
462 |
instrument to bottom.</para> |
463 |
</tip></para> |
464 |
</section> |
465 |
|
466 |
<section id="LOADING_ORCHESTRA_INSTRUMENTS"> |
467 |
<title>Loading Instruments</title> |
468 |
|
469 |
<para>To load an instrument from orchestra to a sampler channel, |
470 |
right-click on the instrument, select <guimenu>Load |
471 |
Instrument</guimenu>, then choose on which channel to load the selected |
472 |
instrument. You can also load an instrument from orchestra to a sampler |
473 |
channel using the instrument chooser of the sampler channel - click |
474 |
<guilabel>Select instrument from orchestra</guilabel> radio button, |
475 |
choose orchestra and isntrument from the comboboxes and click |
476 |
<guibutton>OK</guibutton> button.</para> |
477 |
</section> |
478 |
</chapter> |
479 |
</book> |