/[svn]/web/trunk/www.linuxsampler.org/jsampler/manual/html/jsampler.html
ViewVC logotype

Contents of /web/trunk/www.linuxsampler.org/jsampler/manual/html/jsampler.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1584 - (show annotations) (download) (as text)
Sat Dec 8 13:29:47 2007 UTC (16 years, 4 months ago) by iliev
File MIME type: text/html
File size: 24590 byte(s)
* updated jsampler manual

1 <html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>JSampler Manual</title><link rel="stylesheet" href="jsampler.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.73.2"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="book" lang="en"><div class="titlepage"><div><div><h1 class="title"><a name="id231363"></a>JSampler Manual</h1></div><div><div class="author"><h3 class="author"><span class="firstname">by Grigor</span> <span class="surname">Iliev</span></h3></div></div><div><p class="copyright">Copyright © 2007 Grigor Iliev &lt;grigor@grigoriliev.com&gt;</p></div><div><div class="legalnotice"><a name="id282616"></a><p>This document is released under the terms of the <a class="ulink" href="gfdl.html" target="_top">GNU Free Documentation License</a>.</p></div></div><div><p class="pubdate">Updated: Sat, 8 December 2007</p></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="chapter"><a href="#INTRODUCTION">1. Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#WHAT_IS_JSAMPLER">What is JSampler?</a></span></dt><dt><span class="section"><a href="#WHAT_IS_JSAMPLER_DISTRIBUTION">What is a JSampler distribution?</a></span></dt></dl></dd><dt><span class="chapter"><a href="#SCREENSHOTS">2. Screenshots</a></span></dt><dt><span class="chapter"><a href="#INSTALLATION">3. Installation</a></span></dt><dd><dl><dt><span class="section"><a href="#DOWNLOAD">What to download?</a></span></dt><dt><span class="section"><a href="#REQUIREMENTS">Requirements</a></span></dt><dt><span class="section"><a href="#RUNNING_JSAMPLER">Running a JSampler distribution</a></span></dt><dt><span class="section"><a href="#USING_SCRIPT">Using a script to run a JSampler distribution</a></span></dt><dt><span class="section"><a href="#GNOME_JAR_ASSOCIATIONS">Telling Gnome how to handle jar files</a></span></dt><dt><span class="section"><a href="#GNOME_LAUNCHER">Adding an application launcher to a Gnome panel</a></span></dt><dt><span class="section"><a href="#RUNING_ON_WINDOWS">Running JSampler on Windows</a></span></dt></dl></dd><dt><span class="chapter"><a href="#BUILDING_FROM_SOURCE">4. Building from source</a></span></dt><dd><dl><dt><span class="section"><a href="#BUILDING_FROM_CVS">Building from CVS</a></span></dt><dt><span class="section"><a href="#COMPILATION">Compilation</a></span></dt></dl></dd><dt><span class="chapter"><a href="#USING_ORCHESTRAS">5. Using Orchestras</a></span></dt><dd><dl><dt><span class="section"><a href="#MANAGING_ORCHESTRAS">Managing Orchestras</a></span></dt><dt><span class="section"><a href="#MANAGING_INSTRUMENTS">Managing Instruments</a></span></dt><dt><span class="section"><a href="#LOADING_ORCHESTRA_INSTRUMENTS">Loading Instruments</a></span></dt></dl></dd></dl></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="INTRODUCTION"></a>Chapter 1. Introduction</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#WHAT_IS_JSAMPLER">What is JSampler?</a></span></dt><dt><span class="section"><a href="#WHAT_IS_JSAMPLER_DISTRIBUTION">What is a JSampler distribution?</a></span></dt></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="WHAT_IS_JSAMPLER"></a>What is JSampler?</h2></div></div></div><p>JSampler is an opensource, platform-independent, GUI front-end for
2 <a class="ulink" href="http://www.linuxsampler.org" target="_top">LinuxSampler</a>, written
3 entirely in <a class="ulink" href="http://java.sun.com" target="_top">Java</a>. The main goal
4 of the JSampler's design is to be extensible and more flexible regarding
5 the integration of different GUI implementations. JSampler consists of
6 two parts:</p><div class="itemizedlist"><ul type="disc"><li><p>JSampler core - handles the LSCP command processing and
7 event notifications, sent by LinuxSampler, and provides convenient
8 data models and controllers to be used instead. The core also
9 provides the necessary interfaces that should be implemented by
10 all JSamler views.</p></li><li><p>JSampler view - an extension to the JSampler core, which
11 provides the user interface part of JSampler.</p></li></ul></div><p>The main reason for that is the TCP/IP based
12 communication between the LinuxSampler and its front-ends, enabling the
13 sampler to be controlled from another computer or device, which may have
14 different display requirements and limitations.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="WHAT_IS_JSAMPLER_DISTRIBUTION"></a>What is a JSampler distribution?</h2></div></div></div><p>A JSampler distribution consist of the JSampler core and at least
15 one view, providing the GUI implementation. Each distribution has its
16 own name, which is based on the integrated view extension. Currently,
17 there are two distributions:</p><div class="itemizedlist"><ul type="disc"><li><p>JS Classic - A distribution with a standard GUI, capable of
18 controlling all features available in LinuxSampler at the time of
19 this writing. JS Classic also provides some additional features to
20 facilitate the every day work with the sampler and to automate the
21 most frequently used configurations.</p></li><li><p>Fantasia - A distribution with a modern skin based view
22 (initial graphic design by Olivier Boyer).</p></li></ul></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="SCREENSHOTS"></a>Chapter 2. Screenshots</h2></div></div></div><p>JS Classic with left pane, LS console, statusbar and toolbars</p><p><a class="ulink" href="images/js-classic1.png" target="_top"><img src="images/js-classic1-preview.png"></a></p><p>JS Classic without left pane, LS console, statusbar and
23 toolbars</p><p><a class="ulink" href="images/js-classic2.png" target="_top"><img src="images/js-classic2-preview.png"></a></p><p>Fantasia</p><p><a class="ulink" href="images/fantasia.png" target="_top"><img src="images/fantasia-preview.png"></a></p></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="INSTALLATION"></a>Chapter 3. Installation</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#DOWNLOAD">What to download?</a></span></dt><dt><span class="section"><a href="#REQUIREMENTS">Requirements</a></span></dt><dt><span class="section"><a href="#RUNNING_JSAMPLER">Running a JSampler distribution</a></span></dt><dt><span class="section"><a href="#USING_SCRIPT">Using a script to run a JSampler distribution</a></span></dt><dt><span class="section"><a href="#GNOME_JAR_ASSOCIATIONS">Telling Gnome how to handle jar files</a></span></dt><dt><span class="section"><a href="#GNOME_LAUNCHER">Adding an application launcher to a Gnome panel</a></span></dt><dt><span class="section"><a href="#RUNING_ON_WINDOWS">Running JSampler on Windows</a></span></dt></dl></div><p></p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="DOWNLOAD"></a>What to download?</h2></div></div></div><p>Currently, there are two distributions available for download -
24 <a class="ulink" href="http://downloads.sourceforge.net/jsampler/JS_Classic-0.8a.jar" target="_top">JS
25 Classic</a> and <a class="ulink" href="http://downloads.sourceforge.net/jsampler/Fantasia-0.8a.jar" target="_top">Fantasia</a>.</p><p>The source code is available in the <a class="ulink" href="http://downloads.sourceforge.net/jsampler/JSampler-0.8a.tar.bz2" target="_top">JSampler
26 package</a>, which also contains this manual and startup scripts
27 that can be used to run a particular JSampler distribution.</p><p>The latest source code can be obtained from cvs with the following
28 command:</p><p><span class="command"><strong>cvs -z3
29 -d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co
30 jsampler</strong></span></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="REQUIREMENTS"></a>Requirements</h2></div></div></div><p>To run JSampler you need Java Runtime Environment (JRE) version 6
31 or higher. The latest version can be downloaded from <a class="ulink" href="http://java.sun.com/javase/downloads/" target="_top">here</a>.</p><p>To build JSampler distribution from source you need JDK version
32 6.0 or higher and the <a class="ulink" href="http://ant.apache.org/" target="_top">Ant
33 tool</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="RUNNING_JSAMPLER"></a>Running a JSampler distribution</h2></div></div></div><p>Let's assume that you want to run from the command line
34 <code class="code">JS_Classic-0.8a.jar</code>, which is located in
35 <code class="code">/home/me/soft</code> directory. First you should check whether the
36 <code class="code">java</code> command is in your path and the version requirements
37 are met. This can be done by issuing the following command:</p><p><span class="command"><strong>java -version</strong></span></p><p>If the version is 1.6.0 or higher you can run JS Classic by
38 issuing the following command:</p><p><span class="command"><strong>java -jar
39 /home/me/soft/JS_Classic-0.8a.jar</strong></span></p><p>Otherwise, if the shell response is something like</p><p><span class="command"><strong>bash: java: command not found</strong></span></p><p>or the version requirements are not met, make sure that you have
40 installed JRE (or JDK) with the proper version and find its
41 location:</p><div class="literallayout"><p><span class="command"><strong>updatedb<br>
42 locate bin/java</strong></span></p></div><p>The shell should return something like:</p><div class="literallayout"><p><span class="command"><strong>/opt/jdk1.6.0/bin/java<br>
43 /opt/jdk1.6.0/bin/javac<br>
44 /opt/jdk1.6.0/bin/javadoc<br>
45 /opt/jdk1.6.0/bin/javah<br>
46 /opt/jdk1.6.0/bin/javap<br>
47 /opt/jdk1.6.0/jre/bin/java<br>
48 /usr/bin/java</strong></span></p></div><p>Now, we know that we have a JDK with a proper version installed
49 and its location is <code class="code">/opt/jdk1.6.0</code>. In that case, to run JS
50 Classic issue the following command:</p><p><span class="command"><strong>/opt/jdk1.6.0/bin/java -jar
51 /home/me/soft/JS_Classic-0.8a.jar</strong></span></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>On some systems double clicking on the jar file will be
52 enough.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="USING_SCRIPT"></a>Using a script to run a JSampler distribution</h2></div></div></div><p>There are scripts In the <code class="code">scripts</code> directory of the
53 <a class="ulink" href="http://downloads.sourceforge.net/jsampler/JSampler-0.8a.tar.bz2" target="_top">JSampler
54 package</a> that, with a little adjustments (if needed), can be used
55 to run a JSampler distribution. Copy them to a desired location and edit
56 with your preferred editor.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="GNOME_JAR_ASSOCIATIONS"></a>Telling Gnome how to handle jar files</h2></div></div></div><p>This configuration is optional, but necessary if you want to run
57 jar files by (double) clicking on them. In Gnome, by default jar files
58 are opened with the Archive Manager. To change that, run a file browser,
59 right click on an arbitrary jar file and choose
60 <span class="guimenu">Properties</span>, than go to the <span class="guilabel">Open
61 With</span> tab and click the <span class="guibutton">Add</span>
62 button.</p><div><img src="images/file-properties.png"></div><p>In the <span class="guilabel">Add Application</span> dialog click onto
63 <span class="guilabel">Use a custom command</span> label and a text field will
64 appear below. If the location of your JRE is <code class="code">/opt/jre1.6.0</code>,
65 then enter the following command in the text box:</p><p><span class="command"><strong>/opt/jre1.6.0/bin/java -jar</strong></span></p><p>And then click the <span class="guibutton">Add</span> button.</p><div><img src="images/add-application.png"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="GNOME_LAUNCHER"></a>Adding an application launcher to a Gnome panel</h2></div></div></div><p>To add an application launcher to a Gnome panel, right click on
66 the panel and choose <span class="guimenu">Add to Panel</span>.</p><div><img src="images/add-to-panel.png"></div><p>Then select <span class="guilabel">Custom Application Launcher</span> and
67 click the <span class="guibutton">Add</span> button. In the
68 <span class="guilabel">Command</span> field, of the <span class="guilabel">Create
69 Launcher</span> dialog, fill in the exact command that you use to
70 run the JSampler. For more information on how to run a JSampler
71 distribution from the command line <a class="link" href="#RUNNING_JSAMPLER" title="Running a JSampler distribution">click here</a>.</p><div><img src="images/add-to-panel-create-launcher.png"></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="RUNING_ON_WINDOWS"></a>Running JSampler on Windows</h2></div></div></div><p>To run JSampler distribution on Windows, put a shortcut on the
72 Desktop or Quick Launch, right click on the shortcut and choose
73 <span class="guimenu">Properties</span>. In the <span class="guilabel">Target</span> field
74 insert the command <code class="code">javaw -jar</code> in the beginning.</p><div><img src="images/win-shortcut.png"></div></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="BUILDING_FROM_SOURCE"></a>Chapter 4. Building from source</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#BUILDING_FROM_CVS">Building from CVS</a></span></dt><dt><span class="section"><a href="#COMPILATION">Compilation</a></span></dt></dl></div><p>If you want to build a JSampler distribution from source, first make
75 sure that all <a class="link" href="#REQUIREMENTS" title="Requirements">requirements</a> are
76 met.</p><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="BUILDING_FROM_CVS"></a>Building from CVS</h2></div></div></div><p>When building from CVS, there are some additional steps that
77 should be done. JSampler uses two additional libraries, that should be
78 downloaded and placed in the <code class="code">lib/required</code> directory:</p><div class="itemizedlist"><ul type="disc"><li><p><a class="ulink" href="http://sourceforge.net/projects/jlscp/" target="_top">jlscp</a> - A
79 java LinuxSampler control protocol API</p></li><li><p><a class="ulink" href="http://sourceforge.net/projects/juife/" target="_top">juife</a> - Java
80 User Interface Framework Extensions</p></li></ul></div><p>Download these libraries, create a
81 <code class="code">lib/required</code> directory in the JSampler root and copy the
82 <code class="code">jlscp.jar</code> and <code class="code">juife.jar</code> files in that
83 directory:</p><div class="literallayout"><p><span class="command"><strong>cd /home/me/soft<br>
84 wget -c http://downloads.sourceforge.net/jlscp/jlscp-0.7a.tar.bz2<br>
85 tar -xjf jlscp-0.7a.tar.bz2<br>
86 wget -c http://downloads.sourceforge.net/juife/juife-0.4a.tar.bz2<br>
87 tar -xjf juife-0.4a.tar.bz2<br>
88 cvs -z3 -d:pserver:anonymous@cvs.linuxsampler.org:/var/cvs/linuxsampler co jsampler<br>
89 cd jsampler<br>
90 mkdirhier lib/required<br>
91 cp ../jlscp-0.5a/lib/jlscp.jar lib/required/jlscp.jar<br>
92 cp ../juife-0.4a/lib/juife.jar lib/required/juife.jar</strong></span></p></div><p>Then follow the steps in the next section.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="COMPILATION"></a>Compilation</h2></div></div></div><p>To build a JSampler distribution, first set the
93 <code class="code">JAVA_HOME</code> environment variable to point to your JDK
94 directory. If the JDK is installed in /opt/jdk1.6.0 directory, this can
95 be done by issuing the following command:</p><p><span class="command"><strong>export JAVA_HOME=/opt/jdk1.6.0</strong></span></p><p>Windows users should do something like:</p><p><span class="command"><strong>set JAVA_HOME=c:\jdk1.6.0</strong></span></p><p>Go to the JSampler root directory and issue the following
96 command:</p><p><span class="command"><strong>ant [target]</strong></span></p><p>Where <code class="code">target</code> can be one of the following:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="command"><strong>build-jsclassic</strong></span> - Builds a JS Classic
97 distribution.</p></li><li><p><span class="command"><strong>clean-jsclassic</strong></span> - Removes the JS Classic
98 distribution.</p></li><li><p><span class="command"><strong>build-fantasia</strong></span> - Builds a Fantasia
99 distribution.</p></li><li><p><span class="command"><strong>clean-fantasia</strong></span> - Removes the Fantasia
100 distribution.</p></li><li><p><span class="command"><strong>build-coredoc</strong></span> - Generates the API
101 documentation for the JSampler core.</p></li><li><p><span class="command"><strong>clean-coredoc</strong></span> - Removes the API
102 documentation for the JSampler core.</p></li></ul></div><p>So, if you want to build a JS Classic distribution, just issue the
103 following command:</p><p><span class="command"><strong>ant build-jsclassic</strong></span></p><p>Then copy the jar file from the <code class="code">dist</code> directory to the
104 desired location.</p></div></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="USING_ORCHESTRAS"></a>Chapter 5. Using Orchestras</h2></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#MANAGING_ORCHESTRAS">Managing Orchestras</a></span></dt><dt><span class="section"><a href="#MANAGING_INSTRUMENTS">Managing Instruments</a></span></dt><dt><span class="section"><a href="#LOADING_ORCHESTRA_INSTRUMENTS">Loading Instruments</a></span></dt></dl></div><p>Orchestras feature is like bookmarks/favorites for instruments.
105 Instead of having a thousands of unsorted instruments you can categorize
106 your most used instruments for quick access by adding them to orchestras.
107 You can create an arbitrary number of orchestras and in any orchestra you
108 can add an arbitrary number of instruments.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Orchestras are not handled by the back-end (LinuxSampler) and
109 does not depend on the <span class="guilabel">Instruments Database</span>. The
110 orchestras are handled by JSampler and are stored on the local machine
111 in <code class="code">&lt;jsampler-home&gt;/orchestras.xml</code>. To port the
112 orchestras to another machine just copy that file.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="MANAGING_ORCHESTRAS"></a>Managing Orchestras</h2></div></div></div><p>Tool buttons:</p><p><img src="images/new16.png"> <span class="guilabel">Create new
113 orchestra</span></p><p><img src="images/edit16.png"> <span class="guilabel">Edit
114 selected orchestra</span></p><p><img src="images/delete16.png"> <span class="guilabel">Remove
115 selected orchestra</span></p><p>To create a new orchestra, click on the
116 <span class="guilabel">Orchestras</span> tab then click the <span class="guibutton">Create new
117 orchestra</span> button in the <span class="guilabel">Manage
118 Orchestras</span> tool:</p><div align="center"><img src="images/new-orchestra.png" align="middle"></div><p>Then
119 choose orchestra name and description and click
120 <span class="guibutton">OK</span> button. </p><p>To remove an orchestra, select the orchestra and click the
121 <span class="guibutton">Remove selected orchestra</span> button. To edit an
122 orchestra, select the orchestra and click the <span class="guibutton">Edit selected
123 orchestra</span> button, or just double-click the orchestra to
124 edit.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>To change the position of an orchestra in the orchestra list,
125 select the orchestra and use <span class="guilabel">Alt+Up Arrow</span> and
126 <span class="guilabel">Alt+Down Arrow</span> to move the selected orchestra
127 up/down. You can also use <span class="guilabel">Alt+Shift+Up Arow</span> to
128 move the selected orchestra on top and <span class="guilabel">Alt+Shift+Down
129 Arrow</span> to move the selected orchestra to bottom.</p></div><p></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="MANAGING_INSTRUMENTS"></a>Managing Instruments</h2></div></div></div><p>Tool buttons:</p><p><img src="images/new16.png"> <span class="guilabel">Add new
130 instrument</span></p><p><img src="images/edit16.png"> <span class="guilabel">Edit
131 selected instrument</span></p><p><img src="images/delete16.png"> <span class="guilabel">Remove
132 selected instrument</span></p><p>To add a new instrument to orchestra, first select the desired
133 orchestra from the combobox then click the <span class="guilabel">Add new
134 instrument</span> button:</p><div align="center"><img src="images/add-instrument-to-orchestra.png" align="middle"></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>The easiest way to add an instrument to orchestra is to
135 right-click an instrument in the <span class="guilabel">Instruments
136 Database</span>, then select <span class="guimenu">Add To Orchestra</span>
137 and choose the orchestra to which to add the selected instrument.
138 Note that you can select and add more than one instrument to
139 orchestra at once.</p></div><p>To remove an instrument, select the instrument and click the
140 <span class="guibutton">Remove selected instrument</span> button. To edit an
141 instrument, select the instrument and click the <span class="guibutton">Edit selected
142 instrument</span> button, or just double-click the instrument to
143 edit.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Tip</h3><p>To change the position of an instrument in the instrument
144 list, select the instrument and use <span class="guilabel">Alt+Up
145 Arrow</span> and <span class="guilabel">Alt+Down Arrow</span> to move the
146 selected instrument up/down. You can also use <span class="guilabel">Alt+Shift+Up
147 Arow</span> to move the selected instrument on top and
148 <span class="guilabel">Alt+Shift+Down Arrow</span> to move the selected
149 instrument to bottom.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="LOADING_ORCHESTRA_INSTRUMENTS"></a>Loading Instruments</h2></div></div></div><p>To load an instrument from orchestra to a sampler channel,
150 right-click on the instrument, select <span class="guimenu">Load
151 Instrument</span>, then choose on which channel to load the selected
152 instrument. You can also load an instrument from orchestra to a sampler
153 channel using the instrument chooser of the sampler channel - click
154 <span class="guilabel">Select instrument from orchestra</span> radio button,
155 choose orchestra and isntrument from the comboboxes and click
156 <span class="guibutton">OK</span> button.</p></div></div></div></body></html>

  ViewVC Help
Powered by ViewVC