manual/docbook/jsampler.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<book>
  <title>JSampler Manual</title>

  <bookinfo>
    <author>
      <firstname>by Grigor</firstname>

      <surname>Iliev</surname>
    </author>

    <copyright>
      <year>2007</year>

      <holder>Grigor Iliev &lt;grigor@grigoriliev.com&gt;</holder>
    </copyright>

    <legalnotice>
      <para>This document is released under the terms of the <ulink
      url="gfdl.html">GNU Free Documentation License</ulink>.</para>
    </legalnotice>

    <pubdate>Updated: Sat, 8 December 2007</pubdate>
  </bookinfo>

  <chapter id="INTRODUCTION">
    <title>Introduction</title>

    <section id="WHAT_IS_JSAMPLER">
      <title>What is JSampler?</title>

      <para>JSampler is an opensource, platform-independent, GUI front-end for
      <ulink url="http://www.linuxsampler.org">LinuxSampler</ulink>, written
      entirely in <ulink url="http://java.sun.com">Java</ulink>. 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:</para>

      <para><itemizedlist>
          <listitem>
            <para>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.</para>
          </listitem>

          <listitem>
            <para>JSampler view - an extension to the JSampler core, which
            provides the user interface part of JSampler.</para>
          </listitem>
        </itemizedlist>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.</para>
    </section>

    <section id="WHAT_IS_JSAMPLER_DISTRIBUTION">
      <title>What is a JSampler distribution?</title>

      <para>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:</para>

      <para><itemizedlist>
          <listitem>
            <para>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.</para>
          </listitem>

          <listitem>
            <para>Fantasia - A distribution with a modern skin based view
            (initial graphic design by Olivier Boyer).</para>
          </listitem>
        </itemizedlist></para>
    </section>
  </chapter>

  <chapter id="SCREENSHOTS">
    <title>Screenshots</title>

    <para>JS Classic with left pane, LS console, statusbar and toolbars</para>

    <para><ulink url="images/js-classic1.png"><inlinegraphic
    fileref="images/js-classic1-preview.png" /></ulink></para>

    <para>JS Classic without left pane, LS console, statusbar and
    toolbars</para>

    <para><ulink url="images/js-classic2.png"><inlinegraphic
    fileref="images/js-classic2-preview.png" /></ulink></para>

    <para>Fantasia</para>

    <para><ulink url="images/fantasia.png"><inlinegraphic
    fileref="images/fantasia-preview.png" /></ulink></para>
  </chapter>

  <chapter id="INSTALLATION">
    <title>Installation</title>

    <para></para>

    <section id="DOWNLOAD">
      <title>What to download?</title>

      <para>Currently, there are two distributions available for download -
      <ulink
      url="http://downloads.sourceforge.net/jsampler/JS_Classic-0.8a.jar">JS
      Classic</ulink> and <ulink
      url="http://downloads.sourceforge.net/jsampler/Fantasia-0.8a.jar">Fantasia</ulink>.</para>

      <para>The source code is available in the <ulink
      url="http://downloads.sourceforge.net/jsampler/JSampler-0.8a.tar.bz2">JSampler
      package</ulink>, which also contains this manual and startup scripts
      that can be used to run a particular JSampler distribution.</para>

      <para>The latest source code can be obtained from cvs with the following
      command:</para>

      <para><command>cvs -z3
      -d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co
      jsampler</command></para>
    </section>

    <section id="REQUIREMENTS">
      <title lang="" xreflabel="">Requirements</title>

      <para>To run JSampler you need Java Runtime Environment (JRE) version 6
      or higher. The latest version can be downloaded from <ulink
      url="http://java.sun.com/javase/downloads/">here</ulink>.</para>

      <para>To build JSampler distribution from source you need JDK version
      6.0 or higher and the <ulink url="http://ant.apache.org/">Ant
      tool</ulink>.</para>
    </section>

    <section id="RUNNING_JSAMPLER">
      <title>Running a JSampler distribution</title>

      <para>Let's assume that you want to run from the command line
      <code>JS_Classic-0.8a.jar</code>, which is located in
      <code>/home/me/soft</code> directory. First you should check whether the
      <code>java</code> command is in your path and the version requirements
      are met. This can be done by issuing the following command:</para>

      <para><command>java -version</command></para>

      <para>If the version is 1.6.0 or higher you can run JS Classic by
      issuing the following command:</para>

      <para><command>java -jar
      /home/me/soft/JS_Classic-0.8a.jar</command></para>

      <para>Otherwise, if the shell response is something like</para>

      <para><command>bash: java: command not found</command></para>

      <para>or the version requirements are not met, make sure that you have
      installed JRE (or JDK) with the proper version and find its
      location:</para>

      <para><literallayout><command>updatedb
locate bin/java</command></literallayout></para>

      <para>The shell should return something like:</para>

      <para><literallayout><command>/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/java</command></literallayout></para>

      <para>Now, we know that we have a JDK with a proper version installed
      and its location is <code>/opt/jdk1.6.0</code>. In that case, to run JS
      Classic issue the following command:</para>

      <para><command>/opt/jdk1.6.0/bin/java -jar
      /home/me/soft/JS_Classic-0.8a.jar</command></para>

      <para><note>
          <para>On some systems double clicking on the jar file will be
          enough.</para>
        </note></para>
    </section>

    <section id="USING_SCRIPT">
      <title>Using a script to run a JSampler distribution</title>

      <para>There are scripts In the <code>scripts</code> directory of the
      <ulink
      url="http://downloads.sourceforge.net/jsampler/JSampler-0.8a.tar.bz2">JSampler
      package</ulink> 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.</para>
    </section>

    <section id="GNOME_JAR_ASSOCIATIONS">
      <title>Telling Gnome how to handle jar files</title>

      <para>This 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
      <guimenu>Properties</guimenu>, than go to the <guilabel>Open
      With</guilabel> tab and click the <guibutton>Add</guibutton>
      button.</para>

      <para><graphic fileref="images/file-properties.png" /></para>

      <para>In the <guilabel>Add Application</guilabel> dialog click onto
      <guilabel>Use a custom command</guilabel> label and a text field will
      appear below. If the location of your JRE is <code>/opt/jre1.6.0</code>,
      then enter the following command in the text box:</para>

      <para><command>/opt/jre1.6.0/bin/java -jar</command></para>

      <para>And then click the <guibutton>Add</guibutton> button.</para>

      <para><graphic fileref="images/add-application.png" /></para>
    </section>

    <section id="GNOME_LAUNCHER">
      <title>Adding an application launcher to a Gnome panel</title>

      <para>To add an application launcher to a Gnome panel, right click on
      the panel and choose <guimenu>Add to Panel</guimenu>.</para>

      <para><graphic fileref="images/add-to-panel.png" /></para>

      <para>Then select <guilabel>Custom Application Launcher</guilabel> and
      click the <guibutton>Add</guibutton> button. In the
      <guilabel>Command</guilabel> field, of the <guilabel>Create
      Launcher</guilabel> 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 <link
      linkend="RUNNING_JSAMPLER">click here</link>.</para>

      <para><graphic
      fileref="images/add-to-panel-create-launcher.png" /></para>
    </section>

    <section id="RUNING_ON_WINDOWS">
      <title>Running JSampler on Windows</title>

      <para>To run JSampler distribution on Windows, put a shortcut on the
      Desktop or Quick Launch, right click on the shortcut and choose
      <guimenu>Properties</guimenu>. In the <guilabel>Target</guilabel> field
      insert the command <code>javaw -jar</code> in the beginning.</para>

      <para><graphic fileref="images/win-shortcut.png" /></para>
    </section>
  </chapter>

  <chapter id="BUILDING_FROM_SOURCE">
    <title>Building from source</title>

    <para>If you want to build a JSampler distribution from source, first make
    sure that all <link linkend="REQUIREMENTS">requirements</link> are
    met.</para>

    <section id="BUILDING_FROM_CVS">
      <title>Building from CVS</title>

      <para>When 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 <code>lib/required</code> directory:</para>

      <para><itemizedlist>
          <listitem>
            <para><ulink
            url="http://sourceforge.net/projects/jlscp/">jlscp</ulink> - A
            java LinuxSampler control protocol API</para>
          </listitem>

          <listitem>
            <para><ulink
            url="http://sourceforge.net/projects/juife/">juife</ulink> - Java
            User Interface Framework Extensions</para>
          </listitem>
        </itemizedlist>Download these libraries, create a
      <code>lib/required</code> directory in the JSampler root and copy the
      <code>jlscp.jar</code> and <code>juife.jar</code> files in that
      directory:</para>

      <para><literallayout><command>cd /home/me/soft
wget -c http://downloads.sourceforge.net/jlscp/jlscp-0.7a.tar.bz2
tar -xjf jlscp-0.7a.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.jar</command></literallayout></para>

      <para>Then follow the steps in the next section.</para>
    </section>

    <section id="COMPILATION">
      <title>Compilation</title>

      <para>To build a JSampler distribution, first set the
      <code>JAVA_HOME</code> 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:</para>

      <para><command>export JAVA_HOME=/opt/jdk1.6.0</command></para>

      <para>Windows users should do something like:</para>

      <para><command>set JAVA_HOME=c:\jdk1.6.0</command></para>

      <para>Go to the JSampler root directory and issue the following
      command:</para>

      <para><command>ant [target]</command></para>

      <para>Where <code>target</code> can be one of the following:</para>

      <para><itemizedlist>
          <listitem>
            <para><command>build-jsclassic</command> - Builds a JS Classic
            distribution.</para>
          </listitem>

          <listitem>
            <para><command>clean-jsclassic</command> - Removes the JS Classic
            distribution.</para>
          </listitem>

          <listitem>
            <para><command>build-fantasia</command> - Builds a Fantasia
            distribution.</para>
          </listitem>

          <listitem>
            <para><command>clean-fantasia</command> - Removes the Fantasia
            distribution.</para>
          </listitem>

          <listitem>
            <para><command>build-coredoc</command> - Generates the API
            documentation for the JSampler core.</para>
          </listitem>

          <listitem>
            <para><command>clean-coredoc</command> - Removes the API
            documentation for the JSampler core.</para>
          </listitem>
        </itemizedlist></para>

      <para>So, if you want to build a JS Classic distribution, just issue the
      following command:</para>

      <para><command>ant build-jsclassic</command></para>

      <para>Then copy the jar file from the <code>dist</code> directory to the
      desired location.</para>
    </section>
  </chapter>

  <chapter id="USING_ORCHESTRAS">
    <title>Using Orchestras</title>

    <para>Orchestras feature is like bookmarks/favorites for instruments.
    Instead of having a thousands of unsorted instruments you can categorize
    your most used instruments for quick access by adding them to orchestras.
    You can create an arbitrary number of orchestras and in any orchestra you
    can add an arbitrary number of instruments.<note>
        <para>Orchestras are not handled by the back-end (LinuxSampler) and
        does not depend on the <guilabel>Instruments Database</guilabel>. The
        orchestras are handled by JSampler and are stored on the local machine
        in <code>&lt;jsampler-home&gt;/orchestras.xml</code>. To port the
        orchestras to another machine just copy that file.</para>
      </note></para>

    <section id="MANAGING_ORCHESTRAS">
      <title>Managing Orchestras</title>

      <para>Tool buttons:</para>

      <para><inlinegraphic fileref="images/new16.png" /> <guilabel>Create new
      orchestra</guilabel></para>

      <para><inlinegraphic fileref="images/edit16.png" /> <guilabel>Edit
      selected orchestra</guilabel></para>

      <para><inlinegraphic fileref="images/delete16.png" /> <guilabel>Remove
      selected orchestra</guilabel></para>

      <para>To create a new orchestra, click on the
      <guilabel>Orchestras</guilabel> tab then click the <guibutton>Create new
      orchestra</guibutton> button in the <guilabel>Manage
      Orchestras</guilabel> tool:</para>

      <para><graphic align="center" fileref="images/new-orchestra.png" />Then
      choose orchestra name and description and click
      <guibutton>OK</guibutton> button. </para>

      <para>To remove an orchestra, select the orchestra and click the
      <guibutton>Remove selected orchestra</guibutton> button. To edit an
      orchestra, select the orchestra and click the <guibutton>Edit selected
      orchestra</guibutton> button, or just double-click the orchestra to
      edit.<tip>
          <para>To change the position of an orchestra in the orchestra list,
          select the orchestra and use <guilabel>Alt+Up Arrow</guilabel> and
          <guilabel>Alt+Down Arrow</guilabel> to move the selected orchestra
          up/down. You can also use <guilabel>Alt+Shift+Up Arow</guilabel> to
          move the selected orchestra on top and <guilabel>Alt+Shift+Down
          Arrow</guilabel> to move the selected orchestra to bottom.</para>
        </tip></para>

      <para></para>
    </section>

    <section id="MANAGING_INSTRUMENTS">
      <title>Managing Instruments</title>

      <para>Tool buttons:</para>

      <para><inlinegraphic fileref="images/new16.png" /> <guilabel>Add new
      instrument</guilabel></para>

      <para><inlinegraphic fileref="images/edit16.png" /> <guilabel>Edit
      selected instrument</guilabel></para>

      <para><inlinegraphic fileref="images/delete16.png" /> <guilabel>Remove
      selected instrument</guilabel></para>

      <para>To add a new instrument to orchestra, first select the desired
      orchestra from the combobox then click the <guilabel>Add new
      instrument</guilabel> button:</para>

      <para><graphic align="center"
      fileref="images/add-instrument-to-orchestra.png" /><tip>
          <para>The easiest way to add an instrument to orchestra is to
          right-click an instrument in the <guilabel>Instruments
          Database</guilabel>, then select <guimenu>Add To Orchestra</guimenu>
          and choose the orchestra to which to add the selected instrument.
          Note that you can select and add more than one instrument to
          orchestra at once.</para>
        </tip>To remove an instrument, select the instrument and click the
      <guibutton>Remove selected instrument</guibutton> button. To edit an
      instrument, select the instrument and click the <guibutton>Edit selected
      instrument</guibutton> button, or just double-click the instrument to
      edit.<tip>
          <para>To change the position of an instrument in the instrument
          list, select the instrument and use <guilabel>Alt+Up
          Arrow</guilabel> and <guilabel>Alt+Down Arrow</guilabel> to move the
          selected instrument up/down. You can also use <guilabel>Alt+Shift+Up
          Arow</guilabel> to move the selected instrument on top and
          <guilabel>Alt+Shift+Down Arrow</guilabel> to move the selected
          instrument to bottom.</para>
        </tip></para>
    </section>

    <section id="LOADING_ORCHESTRA_INSTRUMENTS">
      <title>Loading Instruments</title>

      <para>To load an instrument from orchestra to a sampler channel,
      right-click on the instrument, select <guimenu>Load
      Instrument</guimenu>, then choose on which channel to load the selected
      instrument. You can also load an instrument from orchestra to a sampler
      channel using the instrument chooser of the sampler channel - click
      <guilabel>Select instrument from orchestra</guilabel> radio button,
      choose orchestra and isntrument from the comboboxes and click
      <guibutton>OK</guibutton> button.</para>
    </section>
  </chapter>
</book>
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	1583	<pubdate>Updated: Sat, 8 December 2007</pubdate>
26	iliev	1144	</bookinfo>
27
28	iliev	1583	<chapter id="INTRODUCTION">
29	iliev	1144	<title>Introduction</title>
30
31	iliev	1583	<section id="WHAT_IS_JSAMPLER">
32	iliev	1144	<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	iliev	1583	<section id="WHAT_IS_JSAMPLER_DISTRIBUTION">
61	iliev	1144	<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	iliev	1285	<para>Fantasia - A distribution with a modern skin based view
79			(initial graphic design by Olivier Boyer).</para>
80	iliev	1144	</listitem>
81			</itemizedlist></para>
82			</section>
83			</chapter>
84
85	iliev	1583	<chapter id="SCREENSHOTS">
86	iliev	1144	<title>Screenshots</title>
87
88	iliev	1285	<para>JS Classic with left pane, LS console, statusbar and toolbars</para>
89	iliev	1144
90	iliev	1285	<para><ulink url="images/js-classic1.png"><inlinegraphic
91			fileref="images/js-classic1-preview.png" /></ulink></para>
92
93	iliev	1144	<para>JS Classic without left pane, LS console, statusbar and
94	iliev	1285	toolbars</para>
95	iliev	1144
96	iliev	1285	<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	iliev	1144	</chapter>
104
105	iliev	1583	<chapter id="INSTALLATION">
106	iliev	1144	<title>Installation</title>
107
108			<para></para>
109
110	iliev	1583	<section id="DOWNLOAD">
111	iliev	1285	<title>What to download?</title>
112	iliev	1144
113	iliev	1285	<para>Currently, there are two distributions available for download -
114			<ulink
115	iliev	1583	url="http://downloads.sourceforge.net/jsampler/JS_Classic-0.8a.jar">JS
116	iliev	1285	Classic</ulink> and <ulink
117	iliev	1583	url="http://downloads.sourceforge.net/jsampler/Fantasia-0.8a.jar">Fantasia</ulink>.</para>
118	iliev	1144
119			<para>The source code is available in the <ulink
120	iliev	1583	url="http://downloads.sourceforge.net/jsampler/JSampler-0.8a.tar.bz2">JSampler
121	iliev	1144	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	iliev	1583	<section id="REQUIREMENTS">
133	iliev	1285	<title lang="" xreflabel="">Requirements</title>
134	iliev	1144
135	iliev	1204	<para>To run JSampler you need Java Runtime Environment (JRE) version 6
136	iliev	1144	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	iliev	1204	6.0 or higher and the <ulink url="http://ant.apache.org/">Ant
141	iliev	1144	tool</ulink>.</para>
142			</section>
143
144	iliev	1583	<section id="RUNNING_JSAMPLER">
145	iliev	1285	<title>Running a JSampler distribution</title>
146	iliev	1144
147			<para>Let's assume that you want to run from the command line
148	iliev	1583	<code>JS_Classic-0.8a.jar</code>, which is located in
149	iliev	1144	<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	iliev	1204	<para>If the version is 1.6.0 or higher you can run JS Classic by
156	iliev	1144	issuing the following command:</para>
157
158			<para><command>java -jar
159	iliev	1583	/home/me/soft/JS_Classic-0.8a.jar</command></para>
160	iliev	1144
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	iliev	1583	/home/me/soft/JS_Classic-0.8a.jar</command></para>
188	iliev	1144
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	iliev	1583	<section id="USING_SCRIPT">
196	iliev	1144	<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	iliev	1583	url="http://downloads.sourceforge.net/jsampler/JSampler-0.8a.tar.bz2">JSampler
201	iliev	1144	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	iliev	1583	<section id="GNOME_JAR_ASSOCIATIONS">
207	iliev	1144	<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	iliev	1583	<section id="GNOME_LAUNCHER">
232	iliev	1144	<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	iliev	1583	distribution from the command line <link
245			linkend="RUNNING_JSAMPLER">click here</link>.</para>
246	iliev	1144
247			<para><graphic
248			fileref="images/add-to-panel-create-launcher.png" /></para>
249			</section>
250
251	iliev	1583	<section id="RUNING_ON_WINDOWS">
252	iliev	1144	<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	iliev	1583	<chapter id="BUILDING_FROM_SOURCE">
264	iliev	1144	<title>Building from source</title>
265
266			<para>If you want to build a JSampler distribution from source, first make
267	iliev	1583	sure that all <link linkend="REQUIREMENTS">requirements</link> are
268	iliev	1144	met.</para>
269
270	iliev	1583	<section id="BUILDING_FROM_CVS">
271	iliev	1144	<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	iliev	1583	wget -c http://downloads.sourceforge.net/jlscp/jlscp-0.7a.tar.bz2
296			tar -xjf jlscp-0.7a.tar.bz2
297	iliev	1144	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	iliev	1204	cp ../jlscp-0.5a/lib/jlscp.jar lib/required/jlscp.jar
303	iliev	1144	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	iliev	1583	<section id="COMPILATION">
309	iliev	1144	<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	iliev	1583
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	iliev	1144	</book>