/[svn]/jsampler/trunk/manual/docbook/jsampler.xml
ViewVC logotype

Contents of /jsampler/trunk/manual/docbook/jsampler.xml

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1583 - (show annotations) (download) (as text)
Sat Dec 8 13:13:20 2007 UTC (16 years, 3 months ago) by iliev
File MIME type: text/xml
File size: 19194 byte(s)
* docbook update: added Using Orchestras chapter

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 &lt;grigor@grigoriliev.com&gt;</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>&lt;jsampler-home&gt;/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>

  ViewVC Help
Powered by ViewVC