trunk/www.linuxsampler.org/documentation.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<link rel="stylesheet" type="text/css" href="index.css">
  <title>The Linux Sampler Project</title>

  <meta http-equiv="content-type"
   content="text/html; charset=ISO-8859-1">

   <script language="javascript" type="text/javascript">
        <!--
        var dir = "gfx/";

        if(document.images) {

                newsover = new Image();
                newsover.src = dir + "mnewshover.png";

                newsout = new Image();
                newsout.src = dir + "mnews.png";

                aboutover = new Image();
                aboutover.src = dir + "mabouthover.png";

                aboutout = new Image();
                aboutout.src = dir + "mabout.png";

                featuresover = new Image();
                featuresover.src = dir + "mfeatureshover.png";

                featuresout = new Image();
                featuresout.src = dir + "mfeatures.png";

                screenshotsover = new Image();
                screenshotsover.src = dir + "mscreenshotshover.png";

                screenshotsout = new Image();
                screenshotsout.src = dir + "mscreenshots.png";

                demosover = new Image();
                demosover.src = dir + "mdemoshover.png";

                demosout = new Image();
                demosout.src = dir + "mdemos.png";

                downloadsover = new Image();
                downloadsover.src = dir + "mdownloadshover.png";

                downloadsout = new Image();
                downloadsout.src = dir + "mdownloads.png";

                supportover = new Image();
                supportover.src = dir + "msupporthover.png";
                supportout = new Image();
                supportout.src = dir + "msupport.png";

                developersover = new Image();
                developersover.src = dir + "mdevelopershover.png";

                developersout = new Image();
                developersout.src = dir + "mdevelopers.png";

                instrumentsover = new Image();
                instrumentsover.src = dir + "minstrumentshover.png";

                instrumentsout = new Image();
                instrumentsout.src = dir + "minstruments.png";

                linksover = new Image();
                linksover.src = dir + "mlinkshover.png";

                linksout = new Image();
                linksout.src = dir + "mlinks.png";

                documentationover = new Image();
                documentationover.src = dir + "mdocumentationhover.png";

                documentationout = new Image();
                documentationout.src = dir + "mdocumentation.png";

                creditsover = new Image();
                creditsover.src = dir + "mcreditshover.png";

                creditsout = new Image();
                creditsout.src = dir + "mcredits.png";

                faqover = new Image();
                faqover.src = dir + "mfaqhover.png";

                faqout = new Image();
                faqout.src = dir + "mfaq.png";

                bugsover = new Image();
                bugsover.src = dir + "mbugshover.png";

                bugsout = new Image();
                bugsout.src = dir + "mbugs.png";
        }
        -->
        </script>

</head>

<body>

        <div id="mainwindow"><img name="LinuxSampler" src="gfx/lsbackground.jpg" alt="LinuxSampler">

                <h1><span class="hidden">The LinuxSampler Project</span></h1>

                        <table border=0 cellspacing=0 cellpadding=0><tr><th colspan=2 align=left>
                        <img name="h1blank" src="gfx/h1blank.png" alt="blank"><span class="hidden">about</span></th></tr>
                        <tr><td valign=top>
                        <a id="news" href="index.php" onmouseover="javascript:if(document.images)document.news.src = newsover.src" onmouseout="javascript:if(document.images)document.news.src = newsout.src"><img name="news" src="gfx/mnews.png" alt="news"></a>
                        <a id="about" href="about.html" onmouseover="javascript:if(document.images)document.about.src = aboutover.src" onmouseout="javascript:if(document.images)document.about.src = aboutout.src"><img name="about" src="gfx/mabout.png" alt="about"></a>
                        <a id="features" href="features.html" onmouseover="javascript:if(document.images)document.features.src = featuresover.src" onmouseout="javascript:if(document.images)document.features.src = featuresout.src"><img name="features" src="gfx/mfeatures.png" alt="features"></a>
                        <a id="screenshots" href="screenshots.html" onmouseover="javascript:if(document.images)document.screenshots.src = screenshotsover.src" onmouseout="javascript:if(document.images)document.screenshots.src = screenshotsout.src"><img name="screenshots" src="gfx/mscreenshots.png" alt="screenshots"></a>
                        <a id="demos" href="demos.html" onmouseover="javascript:if(document.images)document.demos.src = demosover.src" onmouseout="javascript:if(document.images)document.demos.src = demosout.src"><img name="demos" src="gfx/mdemos.png" alt="demos"></a>
                        <a id="downloads" href="downloads.html" onmouseover="javascript:if(document.images)document.downloads.src = downloadsover.src" onmouseout="javascript:if(document.images)document.downloads.src = downloadsout.src"><img name="downloads" src="gfx/mdownloads.png" alt="download"></a>
                        <a id="support" href="support.html" onmouseover="javascript:if(document.images)document.support.src = supportover.src" onmouseout="javascript:if(document.images)document.support.src = supportout.src"><img name="support" src="gfx/msupport.png" alt="support"></a>
                        <a id="developers" href="developers.html" onmouseover="javascript:if(document.images)document.developers.src = developersover.src" onmouseout="javascript:if(document.images)document.developers.src = developersout.src"><img name="developers" src="gfx/mdevelopers.png" alt="developers"></a>
                        <a id="faq" href="faq.html" onmouseover="javascript:if(document.images)document.faq.src = faqover.src" onmouseout="javascript:if(document.images)document.faq.src = faqout.src"><img name="faq" src="gfx/mfaq.png" alt="faq"></a>
                        <a id="documentation" href="documentation.html" onmouseover="javascript:if(document.images)document.documentation.src = documentationover.src" onmouseout="javascript:if(document.images)document.documentation.src = documentationout.src"><img name="documentation" src="gfx/mdocumentation.png" alt="documentation"></a>
                        <a id="bugs" href="http://bugs.linuxsampler.org" onmouseover="javascript:if(document.images)document.bugs.src = bugsover.src" onmouseout="javascript:if(document.images)document.bugs.src = bugsout.src"><img name="bugs" src="gfx/mbugs.png" alt="bugs"></a>
                        <a id="instruments" href="instruments.html" onmouseover="javascript:if(document.images)document.instruments.src = instrumentsover.src" onmouseout="javascript:if(document.images)document.instruments.src = instrumentsout.src"><img name="instruments" src="gfx/minstruments.png" alt="instruments"></a>
                        <a id="links" href="links.html" onmouseover="javascript:if(document.images)document.links.src = linksover.src" onmouseout="javascript:if(document.images)document.links.src = linksout.src"><img name="links" src="gfx/mlinks.png" alt="links"></a>
                        <a id="credits" href="credits.html" onmouseover="javascript:if(document.images)document.credits.src = creditsover.src" onmouseout="javascript:if(document.images)document.credits.src = creditsout.src"><img name="credits" src="gfx/mcredits.png" alt="credits"></a>

<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="10" height="20">

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="6746056">
<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_subscribeCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>

<form action="https://www.paypal.com/cgi-bin/webscr" method="post">
<input type="hidden" name="cmd" value="_s-xclick">
<input type="hidden" name="hosted_button_id" value="6746149">
<input type="image" src="https://www.paypal.com/en_US/i/btn/btn_donateCC_LG.gif" border="0" name="submit" alt="PayPal - The safer, easier way to pay online!">
<img alt="" border="0" src="https://www.paypal.com/en_US/i/scr/pixel.gif" width="1" height="1">
</form>

                        </td><td valign=top width="100%">
                        <div id="contents">

                        <h2>Documentation</h2>
                        <p class="default">
                        This is still quite under construction. Be welcome to help us with writing some documentation!
                        </p>

                        <a name="windows"></a>
                        <a name="osx"></a>
                        <a name="debian"></a>
                        <h2>Howtos</h2>
                        <p class="default">
                        To ease new users the first contact with the Linuxsampler applications,
                        we have written the following short Howtos:
                        </p>
      <table class="decorated">
        <thead>
          <tr>
            <td class="decorated_header">Name</td>
            <td class="decorated_header">Descripton</td>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td class="decorated"><a href="windows.html">Windows HOWTO</a></td>
            <td class="decorated">
              LinuxSampler quickstart guide for the MS Windows operating system.
            </td>
          </tr>
          <tr>
            <td class="decorated"><a href="osx.html">OS X HOWTO</a></td>
            <td class="decorated">
              LinuxSampler quickstart guide for the Apple OS X operating system.
            </td>
          </tr>
          <tr>
            <td class="decorated"><a href="debian.html">Debian HOWTO</a></td>
            <td class="decorated">
              Guide for how to build optimized Debian packages of LS &amp;
              friends for your specific machine.
            </td>
          </tr>
          <tr>
            <td class="decorated"><a href="msys.html">Windows Build HOWTO</a></td>
            <td class="decorated">
              Guide for how to build libgig, linuxsampler and gigedit
              for Windows by using MSYS.
            </td>
          </tr>
        </tbody>
      </table>

                        <h2>gigedit</h2>
                        <p class="default">
                        This is our graphical instrument editor based on the Gtk toolkit.
                        It can be used stand-alone or in conjunction with LinuxSampler.
                        Read the <a href="http://download.linuxsampler.org/doc/gigedit/quickstart/gigedit_quickstart.html">Gigedit Quickstart</a>
                        for a short tutorial. Please notice that this quickstart document
                        is automatically generated from CVS and thus might reflect
                        features and behaviors only available in the very latest, bleeding
                        edge development version of gigedit from CVS.
                        </p>

                        <h2><a  name="jsampler">JSampler</a></h2>
                        <p class="default">
                        JSampler is an opensource, platform-independent,
                        GUI front-end for LinuxSampler, written entirely in Java.
                        Read the <a href="jsampler/manual/html/jsampler.html">JSampler manual</a>
                        for more information.<br>
                        For information about using Fantasia with Miditzer in Puppy Linux VTPO
                        read this <a href="http://organs.110mb.com/Fantasia.htm" target="_blank">HOWTO</a>.
                        </p>

                        <h2>libgig</h2>
                        <p class="default">
                        libgig is a C++ library used to load and modify Gigasampler format files.
                        If you're a developer and might want to use libgig, here is its
                        <a href="http://download.linuxsampler.org/doc/libgig/api/">API documentation</a>
                        (automatically daily updated from CVS).
                        </p>

                        <a name="lscp_spec"></a>
                        <a name="lscp_specs"></a>
                        <h2>liblscp</h2>
                        <p class="default">
                        liblscp is C library as convenient wrapper around the <i>LinuxSampler Control Protocol</i>.
                        If you're a developer and might want to use liblscp, here is its
                        <a href="http://download.linuxsampler.org/doc/liblscp/">API documentation</a>
                        (automatically daily updated from CVS).
                        </p>

                        <h2>LSCP Reference</h2>
                        <p class="default">
                        The following documents define the <i>LinuxSampler Control Protocol</i>,
                        a network protocol with which LinuxSampler can be controlled locally as well as remotely.
                        As this is a simple ASCII based protocol it's possible to write a frontend for LinuxSampler in
                        any programming language and GUI library. There's still a big demand especially for a Gtk and
                        ncurses based frontend, so be encouraged and let
                        <a href="http://www.linuxsampler.org/developers.html">us</a> know if you wrote a frontend for
                        LinuxSampler!
                        </p>

      <table class="decorated">
        <thead>
          <tr>
            <td class="decorated_header">Protocol Name</td>
            <td class="decorated_header">Document Types</td>
            <td class="decorated_header">Release Date</td>
            <td class="decorated_header">Description</td>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td class="decorated">LSCP&nbsp;draft</td>
            <td class="decorated">
              <a href="http://www.linuxsampler.org/api/draft-linuxsampler-protocol.txt">TXT</a>,
              <a href="http://www.linuxsampler.org/api/draft-linuxsampler-protocol.html">HTML</a>,
              <a href="http://cvs.linuxsampler.org/cgi-bin/viewcvs.cgi/*checkout*/linuxsampler/Documentation/lscp.xml?rev=HEAD&content-type=text/xml">XML</a>
            </td>
            <td class="decorated">unreleased</td>
            <td class="decorated">
              Very latest draft of the protocol (which usually reflects the
              latest development state from CVS or may even not be implemented
              yet).
            </td>
          </tr>
          <tr>
            <td class="decorated">LSCP&nbsp;1.3</td>
            <td class="decorated">
              <a href="http://www.linuxsampler.org/api/lscp-1.3.txt">TXT</a>,
              <a href="http://www.linuxsampler.org/api/lscp-1.3.html">HTML</a>,
              <a href="http://www.linuxsampler.org/api/lscp-1.3.xml">XML</a>
            </td>
            <td class="decorated">2007-12-06</td>
            <td class="decorated">
              Protocol specification of the latest official release of LinuxSampler (0.5.1).
            </td>
          </tr>
          <tr>
            <td class="decorated">LSCP&nbsp;1.2</td>
            <td class="decorated">
              <a href="http://www.linuxsampler.org/api/lscp-1.2.txt">TXT</a>,
              <a href="http://www.linuxsampler.org/api/lscp-1.2.html">HTML</a>,
              <a href="http://www.linuxsampler.org/api/lscp-1.2.xml">XML</a>
            </td>
            <td class="decorated">2007-10-15</td>
            <td class="decorated">
              Protocol specification of the previous official release of LinuxSampler (0.5.0).
            </td>
          </tr>
          <tr>
            <td class="decorated">LSCP&nbsp;1.1</td>
            <td class="decorated">
              <a href="http://www.linuxsampler.org/api/lscp-1.1.txt">TXT</a>,
              <a href="http://www.linuxsampler.org/api/lscp-1.1.html">HTML</a>,
              <a href="http://www.linuxsampler.org/api/lscp-1.1.xml">XML</a>
            </td>
            <td class="decorated">2006-11-25</td>
            <td class="decorated">
              Protocol specification old LinuxSampler release 0.4.0.
            </td>
          </tr>
          <tr>
            <td class="decorated">LSCP&nbsp;1.0</td>
            <td class="decorated">
              <a href="http://www.linuxsampler.org/api/lscp-1.0.txt">TXT</a>,
              <a href="http://www.linuxsampler.org/api/lscp-1.0.html">HTML</a>,
              <a href="http://www.linuxsampler.org/api/lscp-1.0.xml">XML</a>
            </td>
            <td class="decorated">2005-07-17</td>
            <td class="decorated">
              Protocol specification of ancient LinuxSampler release 0.3.3.
            </td>
          </tr>
        </tbody>
      </table>

                        <p class="default">
                        The protocol will be extended from time to time. You may look at the
                        <a href="features.html#LSCP">features</a> site to see which control
                        commands are already implemented and which are not.
                        </p>


                        <a name="example_lscp_scripts">
                        <h3>Example LSCP scripts</h3>
                        <p class="default">
                        If you don't want / can't use a GUI frontend you will probably write some LSCP scripts for
                        using with linuxsampler to setup your needed sampler session. It follows some common LSCP
                        examples to give you a good starting point for writing your own ones. Adjust it to your needs
                        and send it to the running linuxsampler application with:
                        </p>
                        <pre class="code">cat yourscript.lscp | netcat localhost 8888</pre>
                        <p class="default">
                        Optionally you can also use a graphical frontend like QSampler one time to setup a working
                        sampler session for your needs and save it. Because you have to know that the files saved
                        by our frontends are actually pure LSCP scripts, thus you can i.e. use those files simply with
                        the mentioned netcat command from above to setup the sampler session without a frontend.
                        </p>
                        <p class="default">
                        Here is a simple LSCP example which uses ALSA as MIDI input and as audio output driver as well,
                        it creates only one sampler channel using the Gigasampler engine and loads a Piano instrument
                        on that sampler channel:
                        </p>
                        <pre class="code">#enable echo mode
SET ECHO 1

# load the ALSA audio driver
# (parameter CARD is optional, I use it here to select my 2nd sound card
#  you can use 'GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO ALSA CARD' to get
#  all available sound cards)
CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='1,0'

# load the ALSA MIDI driver
CREATE MIDI_INPUT_DEVICE ALSA

# connect my MIDI keyboard which has ALSA seq ID '72:0'
# (see 'aconnect -i' for the IDs of your MIDI devices
#  or use 'GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS')
SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='72:0'

# setup a sampler channel
ADD CHANNEL
LOAD ENGINE gig 0
SET CHANNEL AUDIO_OUTPUT_DEVICE 0 0
SET CHANNEL MIDI_INPUT_DEVICE 0 0
LOAD INSTRUMENT '/home/me/Gigs/PMI Steinway D.gig' 0 0

# finally show our channel setup (optional of course)
GET CHANNEL INFO 0

# quit connection
QUIT</pre>
                        <p class="default">
                        The next example uses JACK as audio output driver instead and automatically connects the two
                        output channels of LS's JACK client to the first two ALSA PCM channels, so you can hear
                        something without having to manually connect it e.g. with qjackctl:
                        </p>
                        <pre class="code">#enable echo mode
SET ECHO 1

# load the JACK audio driver
CREATE AUDIO_OUTPUT_DEVICE JACK

# connect to ALSA playback JACK client so we can hear something
# (you can use 'GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO 0 0 JACK_BINDINGS'
#  to get all available JACK clients / ports)
SET AUDIO_OUTPUT_CHANNEL_PARAMETER 0 0 JACK_BINDINGS='alsa_pcm:playback_1'
SET AUDIO_OUTPUT_CHANNEL_PARAMETER 0 1 JACK_BINDINGS='alsa_pcm:playback_2'

# load the ALSA MIDI driver
CREATE MIDI_INPUT_DEVICE ALSA

# connect my MIDI keyboard which has ALSA seq ID '72:0'
# (see 'aconnect -i' for the IDs of your MIDI devices
#  or use 'GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS')
SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='72:0'

# setup one sampler channel
ADD CHANNEL
LOAD ENGINE gig 0
SET CHANNEL AUDIO_OUTPUT_DEVICE 0 0
SET CHANNEL MIDI_INPUT_DEVICE 0 0
LOAD INSTRUMENT '/home/me/Gigs/PMI Steinway D.gig' 0 0

# finally show our channel setup (optional of course)
GET CHANNEL INFO 0

# quit connection
QUIT</pre>
                        <p class="default">
                        The next example is a bit more complex.
                        It shows how to setup a more realistic sampler session, handle routing of MIDI input channels,
                        handle routing of audio channels, it uses JACK again as audio
                        output driver, but creates the JACK client with four output channels instead, it creates two
                        sampler channels, loads two different instrument on those two sampler channels and alters
                        the audio channel routing so that the two output channels of sampler channel 1 are routed to
                        the first two JACK output channels and the two output channels of sampler channel 2 are routed
                        the second pair of the JACK client's output channels. That way you could e.g. record the output
                        of those two sampler channels independently or apply independent LADSPA effects on it.
                        </p>
                        <pre class="code"># enable echo mode
SET ECHO 1

# load audio and MIDI driver
CREATE AUDIO_OUTPUT_DEVICE JACK
CREATE MIDI_INPUT_DEVICE ALSA

# increase the amount of output channels of the LS"s Jack client e.g. to 4
SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 CHANNELS=4

# connect to MIDI keyboard
SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS="64:0"

# set up 1st sampler channel (using default output channels, that is 0 and 1)
ADD CHANNEL
LOAD ENGINE gig 0
SET CHANNEL AUDIO_OUTPUT_DEVICE 0 0
SET CHANNEL MIDI_INPUT_DEVICE 0 0
LOAD INSTRUMENT "/somedir/The Bosendorfer Imperial Grand Version 2.2.gig" 0 0
SET CHANNEL VOLUME 0 0.40
# by default every sampler channel / engine listens to ALL MIDI channels
# but for multi channel setup it makes sense to distinguish the inputs, so
# let sampler channel 0 listen to MIDI channel 0 (instead of ALL)
SET CHANNEL MIDI_INPUT_CHANNEL 0 0

# set up 2nd sampler channel (using output channels 2 and 3)
ADD CHANNEL
LOAD ENGINE gig 1
SET CHANNEL AUDIO_OUTPUT_DEVICE 1 0
SET CHANNEL MIDI_INPUT_DEVICE 1 0
LOAD INSTRUMENT "/home/me/Gigs/NemeSys_1GB_Grand.gig" 0 1
SET CHANNEL VOLUME 1 0.40
# let sampler channel 1 listen to MIDI channel 1 (instead of ALL)
SET CHANNEL MIDI_INPUT_CHANNEL 1 1
# this will alter the audio channel routing
# connect the engines output channel 0 to JACK clients output 2
SET CHANNEL AUDIO_OUTPUT_CHANNEL 1 0 2
# connect the engines output channel 1 to JACK clients output 3
SET CHANNEL AUDIO_OUTPUT_CHANNEL 1 1 3

# automatic connection between the four 4 ports of LS's Jack client and the
# ALSA PCM JACK client (assuming your sound card has at least 4 outputs ;-)
SET AUDIO_OUTPUT_CHANNEL_PARAMETER 0 0 JACK_BINDINGS='alsa_pcm:playback_1'
SET AUDIO_OUTPUT_CHANNEL_PARAMETER 0 1 JACK_BINDINGS='alsa_pcm:playback_2'
SET AUDIO_OUTPUT_CHANNEL_PARAMETER 0 2 JACK_BINDINGS='alsa_pcm:playback_3'
SET AUDIO_OUTPUT_CHANNEL_PARAMETER 0 3 JACK_BINDINGS='alsa_pcm:playback_4'

# not necessary, just to see our setup
GET CHANNEL INFO 0
GET CHANNEL INFO 1</pre>
                        <p class="default">
                        For a detailed description about LSCP read the <a href="api/draft-linuxsampler-protocol.html">LSCP reference</a>.
                        Be welcome to ask details on the mailing list.
                        </p>


                </div>
                </td></tr></table>

 </div>

</body>
</html>