1 |
iliev |
1144 |
<?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 |
iliev |
1204 |
<pubdate>Updated: Thu, 17 May 2007</pubdate> |
26 |
iliev |
1144 |
</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 |
iliev |
1204 |
url="http://downloads.sourceforge.net/jsampler/JS_Classic-0.5a.jar">here</ulink>.</para> |
111 |
iliev |
1144 |
|
112 |
|
|
<para>The source code is available in the <ulink |
113 |
iliev |
1204 |
url="http://downloads.sourceforge.net/jsampler/JSampler-0.5a.tar.bz2">JSampler |
114 |
iliev |
1144 |
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 |
iliev |
1204 |
<para>To run JSampler you need Java Runtime Environment (JRE) version 6 |
129 |
iliev |
1144 |
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 |
iliev |
1204 |
6.0 or higher and the <ulink url="http://ant.apache.org/">Ant |
134 |
iliev |
1144 |
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 |
iliev |
1204 |
<code>JS_Classic-0.5a.jar</code>, which is located in |
142 |
iliev |
1144 |
<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 |
iliev |
1204 |
<para>If the version is 1.6.0 or higher you can run JS Classic by |
149 |
iliev |
1144 |
issuing the following command:</para> |
150 |
|
|
|
151 |
|
|
<para><command>java -jar |
152 |
iliev |
1204 |
/home/me/soft/JS_Classic-0.5a.jar</command></para> |
153 |
iliev |
1144 |
|
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 |
iliev |
1204 |
/home/me/soft/JS_Classic-0.5a.jar</command></para> |
181 |
iliev |
1144 |
|
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 |
iliev |
1204 |
url="http://downloads.sourceforge.net/jsampler/JSampler-0.5a.tar.bz2">JSampler |
194 |
iliev |
1144 |
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 |
iliev |
1204 |
wget -c http://downloads.sourceforge.net/jlscp/jlscp-0.5a.tar.bz2 |
289 |
|
|
tar -xjf jlscp-0.5a.tar.bz2 |
290 |
iliev |
1144 |
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 |
iliev |
1204 |
cp ../jlscp-0.5a/lib/jlscp.jar lib/required/jlscp.jar |
296 |
iliev |
1144 |
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> |