--- web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt	2005/05/21 20:01:32	561
+++ web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.txt	2005/05/24 03:26:22	575
@@ -2,12 +2,12 @@
 
 LinuxSampler Developers                                   C. Schoenebeck
 Internet-Draft                           Interessengemeinschaft Software
-Expires: November 19, 2005                             Engineering e. V.
-                                                            May 21, 2005
+Expires: November 22, 2005                             Engineering e. V.
+                                                            May 24, 2005
 
 
                      LinuxSampler Control Protocol
-                                lscp.txt
+                                LSCP 1.0
 
 Status of this Memo
 
@@ -30,7 +30,7 @@
    The list of Internet-Draft Shadow Directories can be accessed at
    http://www.ietf.org/shadow.html.
 
-   This Internet-Draft will expire on November 19, 2005.
+   This Internet-Draft will expire on November 22, 2005.
 
 Copyright Notice
 
@@ -40,9 +40,9 @@
 
    The LinuxSampler Control Protocol (LSCP) is an application-level
    protocol primarily intended for local and remote controlling the
-   LinuxSampler main application, which is a sophisticated console
-   application essentially playing back audio samples and manipulating
-   the samples in real time to certain extent.
+   LinuxSampler backend application, which is a sophisticated
+   server-like console application essentially playing back audio
+   samples and manipulating the samples in real time to certain extent.
 
 
 
@@ -52,7 +52,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005                [Page 1]
+Schoenebeck            Expires November 22, 2005                [Page 1]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -60,100 +60,102 @@
 Table of Contents
 
    1.   Requirements notation  . . . . . . . . . . . . . . . . . . .   4
-   2.   Introduction . . . . . . . . . . . . . . . . . . . . . . . .   5
-   3.   Focus of this protocol . . . . . . . . . . . . . . . . . . .   6
-   4.   Communication Overview . . . . . . . . . . . . . . . . . . .   7
-     4.1  Request/response communication method  . . . . . . . . . .   7
-       4.1.1  Result format  . . . . . . . . . . . . . . . . . . . .   8
-     4.2  Subscribe/notify communication method  . . . . . . . . . .   9
-   5.   Description for control commands . . . . . . . . . . . . . .  12
-     5.1  Ignored lines and comments . . . . . . . . . . . . . . . .  12
-     5.2  Configuring audio drivers  . . . . . . . . . . . . . . . .  12
-       5.2.1  Getting amount of available audio output drivers . . .  12
-       5.2.2  Getting all available audio output drivers . . . . . .  13
-       5.2.3  Getting information about a specific audio output
-              driver . . . . . . . . . . . . . . . . . . . . . . . .  13
-       5.2.4  Getting information about specific audio output
-              driver parameter . . . . . . . . . . . . . . . . . . .  14
-       5.2.5  Creating an audio output device  . . . . . . . . . . .  17
-       5.2.6  Destroying an audio output device  . . . . . . . . . .  17
-       5.2.7  Getting all created audio output device count  . . . .  18
-       5.2.8  Getting all created audio output device list . . . . .  18
-       5.2.9  Getting current settings of an audio output device . .  19
-       5.2.10   Changing settings of audio output devices  . . . . .  20
-       5.2.11   Getting information about an audio channel . . . . .  20
-       5.2.12   Getting information about specific audio channel
-                parameter  . . . . . . . . . . . . . . . . . . . . .  22
-       5.2.13   Changing settings of audio output channels . . . . .  23
-     5.3  Configuring MIDI input drivers . . . . . . . . . . . . . .  24
-       5.3.1  Getting amount of available MIDI input drivers . . . .  24
-       5.3.2  Getting all available MIDI input drivers . . . . . . .  25
-       5.3.3  Getting information about a specific MIDI input
-              driver . . . . . . . . . . . . . . . . . . . . . . . .  25
-       5.3.4  Getting information about specific MIDI input
-              driver parameter . . . . . . . . . . . . . . . . . . .  26
-       5.3.5  Creating a MIDI input device . . . . . . . . . . . . .  28
-       5.3.6  Destroying a MIDI input device . . . . . . . . . . . .  29
-       5.3.7  Getting all created MIDI input device count  . . . . .  29
-       5.3.8  Getting all created MIDI input device list . . . . . .  29
-       5.3.9  Getting current settings of a MIDI input device  . . .  30
-       5.3.10   Changing settings of MIDI input devices  . . . . . .  31
-       5.3.11   Getting information about a MIDI port  . . . . . . .  31
-       5.3.12   Getting information about specific MIDI port
-                parameter  . . . . . . . . . . . . . . . . . . . . .  32
-       5.3.13   Changing settings of MIDI input ports  . . . . . . .  33
-     5.4  Configuring sampler channels . . . . . . . . . . . . . . .  34
-       5.4.1  Loading an instrument  . . . . . . . . . . . . . . . .  34
-       5.4.2  Loading a sampler engine . . . . . . . . . . . . . . .  35
-
-
-
-Schoenebeck            Expires November 19, 2005                [Page 2]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
-       5.4.3  Getting all created sampler channel count  . . . . . .  36
-       5.4.4  Getting all created sampler channel list . . . . . . .  36
-       5.4.5  Adding a new sampler channel . . . . . . . . . . . . .  36
-       5.4.6  Removing a sampler channel . . . . . . . . . . . . . .  37
-       5.4.7  Getting amount of available engines  . . . . . . . . .  38
-       5.4.8  Getting all available engines  . . . . . . . . . . . .  38
-       5.4.9  Getting information about an engine  . . . . . . . . .  38
-       5.4.10   Getting sampler channel information  . . . . . . . .  39
-       5.4.11   Current number of active voices  . . . . . . . . . .  41
-       5.4.12   Current number of active disk streams  . . . . . . .  41
-       5.4.13   Current fill state of disk stream buffers  . . . . .  42
-       5.4.14   Setting audio output device  . . . . . . . . . . . .  42
-       5.4.15   Setting audio output type  . . . . . . . . . . . . .  43
-       5.4.16   Setting audio output channel . . . . . . . . . . . .  44
-       5.4.17   Setting MIDI input device  . . . . . . . . . . . . .  44
-       5.4.18   Setting MIDI input type  . . . . . . . . . . . . . .  45
-       5.4.19   Setting MIDI input port  . . . . . . . . . . . . . .  45
-       5.4.20   Setting MIDI input channel . . . . . . . . . . . . .  46
-       5.4.21   Setting channel volume . . . . . . . . . . . . . . .  46
-       5.4.22   Resetting a sampler channel  . . . . . . . . . . . .  47
-     5.5  Controlling connection . . . . . . . . . . . . . . . . . .  48
-       5.5.1  Register front-end for receiving event messages  . . .  48
-       5.5.2  Unregister front-end for not receiving event
-              messages . . . . . . . . . . . . . . . . . . . . . . .  48
-       5.5.3  Enable or disable echo of commands . . . . . . . . . .  49
-       5.5.4  Close client connection  . . . . . . . . . . . . . . .  49
-     5.6  Global commands  . . . . . . . . . . . . . . . . . . . . .  50
-       5.6.1  Reset sampler  . . . . . . . . . . . . . . . . . . . .  50
-   6.   Command Syntax . . . . . . . . . . . . . . . . . . . . . . .  51
-   7.   Events . . . . . . . . . . . . . . . . . . . . . . . . . . .  52
-     7.1  Number of sampler channels changed . . . . . . . . . . . .  52
-     7.2  Number of active voices changed  . . . . . . . . . . . . .  52
-     7.3  Number of active disk streams changed  . . . . . . . . . .  52
-     7.4  Disk stream buffer fill state changed  . . . . . . . . . .  53
-     7.5  Channel information changed  . . . . . . . . . . . . . . .  53
-     7.6  Miscellaneous and debugging events . . . . . . . . . . . .  53
-   8.   Security Considerations  . . . . . . . . . . . . . . . . . .  55
-   9.   Acknowledgments  . . . . . . . . . . . . . . . . . . . . . .  56
-   10.  References . . . . . . . . . . . . . . . . . . . . . . . . .  56
-        Author's Address . . . . . . . . . . . . . . . . . . . . . .  56
-        Intellectual Property and Copyright Statements . . . . . . .  57
+   2.   Versioning of this specification . . . . . . . . . . . . . .   5
+   3.   Introduction . . . . . . . . . . . . . . . . . . . . . . . .   6
+   4.   Focus of this protocol . . . . . . . . . . . . . . . . . . .   7
+   5.   Communication Overview . . . . . . . . . . . . . . . . . . .   8
+     5.1  Request/response communication method  . . . . . . . . . .   8
+       5.1.1  Result format  . . . . . . . . . . . . . . . . . . . .   9
+     5.2  Subscribe/notify communication method  . . . . . . . . . .  10
+   6.   Description for control commands . . . . . . . . . . . . . .  13
+     6.1  Ignored lines and comments . . . . . . . . . . . . . . . .  13
+     6.2  Configuring audio drivers  . . . . . . . . . . . . . . . .  13
+       6.2.1  Getting amount of available audio output drivers . . .  13
+       6.2.2  Getting all available audio output drivers . . . . . .  14
+       6.2.3  Getting information about a specific audio output
+              driver . . . . . . . . . . . . . . . . . . . . . . . .  14
+       6.2.4  Getting information about specific audio output
+              driver parameter . . . . . . . . . . . . . . . . . . .  15
+       6.2.5  Creating an audio output device  . . . . . . . . . . .  18
+       6.2.6  Destroying an audio output device  . . . . . . . . . .  18
+       6.2.7  Getting all created audio output device count  . . . .  19
+       6.2.8  Getting all created audio output device list . . . . .  19
+       6.2.9  Getting current settings of an audio output device . .  20
+       6.2.10   Changing settings of audio output devices  . . . . .  21
+       6.2.11   Getting information about an audio channel . . . . .  21
+       6.2.12   Getting information about specific audio channel
+                parameter  . . . . . . . . . . . . . . . . . . . . .  23
+       6.2.13   Changing settings of audio output channels . . . . .  24
+     6.3  Configuring MIDI input drivers . . . . . . . . . . . . . .  25
+       6.3.1  Getting amount of available MIDI input drivers . . . .  26
+       6.3.2  Getting all available MIDI input drivers . . . . . . .  26
+       6.3.3  Getting information about a specific MIDI input
+              driver . . . . . . . . . . . . . . . . . . . . . . . .  26
+       6.3.4  Getting information about specific MIDI input
+              driver parameter . . . . . . . . . . . . . . . . . . .  27
+       6.3.5  Creating a MIDI input device . . . . . . . . . . . . .  29
+       6.3.6  Destroying a MIDI input device . . . . . . . . . . . .  30
+       6.3.7  Getting all created MIDI input device count  . . . . .  30
+       6.3.8  Getting all created MIDI input device list . . . . . .  31
+       6.3.9  Getting current settings of a MIDI input device  . . .  31
+       6.3.10   Changing settings of MIDI input devices  . . . . . .  32
+       6.3.11   Getting information about a MIDI port  . . . . . . .  33
+       6.3.12   Getting information about specific MIDI port
+                parameter  . . . . . . . . . . . . . . . . . . . . .  33
+       6.3.13   Changing settings of MIDI input ports  . . . . . . .  35
+     6.4  Configuring sampler channels . . . . . . . . . . . . . . .  35
+       6.4.1  Loading an instrument  . . . . . . . . . . . . . . . .  35
+
+
+
+Schoenebeck            Expires November 22, 2005                [Page 2]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+       6.4.2  Loading a sampler engine . . . . . . . . . . . . . . .  36
+       6.4.3  Getting all created sampler channel count  . . . . . .  37
+       6.4.4  Getting all created sampler channel list . . . . . . .  37
+       6.4.5  Adding a new sampler channel . . . . . . . . . . . . .  38
+       6.4.6  Removing a sampler channel . . . . . . . . . . . . . .  39
+       6.4.7  Getting amount of available engines  . . . . . . . . .  39
+       6.4.8  Getting all available engines  . . . . . . . . . . . .  39
+       6.4.9  Getting information about an engine  . . . . . . . . .  40
+       6.4.10   Getting sampler channel information  . . . . . . . .  41
+       6.4.11   Current number of active voices  . . . . . . . . . .  42
+       6.4.12   Current number of active disk streams  . . . . . . .  43
+       6.4.13   Current fill state of disk stream buffers  . . . . .  43
+       6.4.14   Setting audio output device  . . . . . . . . . . . .  44
+       6.4.15   Setting audio output type  . . . . . . . . . . . . .  45
+       6.4.16   Setting audio output channel . . . . . . . . . . . .  45
+       6.4.17   Setting MIDI input device  . . . . . . . . . . . . .  46
+       6.4.18   Setting MIDI input type  . . . . . . . . . . . . . .  46
+       6.4.19   Setting MIDI input port  . . . . . . . . . . . . . .  47
+       6.4.20   Setting MIDI input channel . . . . . . . . . . . . .  48
+       6.4.21   Setting channel volume . . . . . . . . . . . . . . .  48
+       6.4.22   Resetting a sampler channel  . . . . . . . . . . . .  49
+     6.5  Controlling connection . . . . . . . . . . . . . . . . . .  49
+       6.5.1  Register front-end for receiving event messages  . . .  49
+       6.5.2  Unregister front-end for not receiving event
+              messages . . . . . . . . . . . . . . . . . . . . . . .  50
+       6.5.3  Enable or disable echo of commands . . . . . . . . . .  51
+       6.5.4  Close client connection  . . . . . . . . . . . . . . .  51
+     6.6  Global commands  . . . . . . . . . . . . . . . . . . . . .  51
+       6.6.1  Reset sampler  . . . . . . . . . . . . . . . . . . . .  51
+       6.6.2  General sampler informations . . . . . . . . . . . . .  52
+   7.   Command Syntax . . . . . . . . . . . . . . . . . . . . . . .  53
+   8.   Events . . . . . . . . . . . . . . . . . . . . . . . . . . .  58
+     8.1  Number of sampler channels changed . . . . . . . . . . . .  58
+     8.2  Number of active voices changed  . . . . . . . . . . . . .  58
+     8.3  Number of active disk streams changed  . . . . . . . . . .  58
+     8.4  Disk stream buffer fill state changed  . . . . . . . . . .  59
+     8.5  Channel information changed  . . . . . . . . . . . . . . .  59
+     8.6  Miscellaneous and debugging events . . . . . . . . . . . .  59
+   9.   Security Considerations  . . . . . . . . . . . . . . . . . .  61
+   10.  Acknowledgments  . . . . . . . . . . . . . . . . . . . . . .  62
+   11.  References . . . . . . . . . . . . . . . . . . . . . . . . .  62
+        Author's Address . . . . . . . . . . . . . . . . . . . . . .  62
+        Intellectual Property and Copyright Statements . . . . . . .  63
 
 
 
@@ -162,9 +164,7 @@
 
 
 
-
-
-Schoenebeck            Expires November 19, 2005                [Page 3]
+Schoenebeck            Expires November 22, 2005                [Page 3]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -220,12 +220,68 @@
 
 
 
-Schoenebeck            Expires November 19, 2005                [Page 4]
+Schoenebeck            Expires November 22, 2005                [Page 4]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-2.  Introduction
+2.  Versioning of this specification
+
+   LSCP will certainly be extended and enhanced by-and-by.  Each
+   official release of the LSCP specification will be tagged with a
+   unique version tuple.  The version tuple consists at least of a major
+   and minor version number like:
+
+      "1.2"
+
+   In this example the major version number would be "1" and the minor
+   version number would be "2".  Note that the version tuple might also
+   have more than two elements.  The major version number defines a
+   group of backward compatible versions.  That means a frontend is
+   compatible to the connected sampler if and only if the LSCP versions
+   to which each of the two parties complies to, match both of the
+   following rules:
+
+   Compatibility:
+
+   1.  The frontend's LSCP major version and the sampler's LSCP major
+       version are exactly equal.
+   2.  The frontend's LSCP minor version is less or equal than the
+       sampler's LSCP minor version.
+
+   Compatibility can only be claimed if both rules are true.  The
+   frontend can use the "GET SERVER INFO" (Section 6.6.2) command to get
+   the version of the LSCP specification the sampler complies with.
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Schoenebeck            Expires November 22, 2005                [Page 5]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+3.  Introduction
 
    LinuxSampler is a so called software sampler application capable to
    playback audio samples from a computer's Random Access Memory (RAM)
@@ -237,7 +293,7 @@
    connected to an arbitrary MIDI input method and arbitrary MIDI
    channel (e.g.  sampler channel 17 could be connected to an ALSA
    sequencer device 64:0 and listening to MIDI channel 1 there).  Each
-   sampler engine will be assigned an own instance of one of the
+   sampler channel will be associated with an instance of one of the
    available sampler engines (e.g.  GigEngine, DLSEngine).  The audio
    output of each sampler channel can be routed to an arbitrary audio
    output method (ALSA / JACK) and an arbitrary audio output channel
@@ -276,12 +332,12 @@
 
 
 
-Schoenebeck            Expires November 19, 2005                [Page 5]
+Schoenebeck            Expires November 22, 2005                [Page 6]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-3.  Focus of this protocol
+4.  Focus of this protocol
 
    Main focus of this protocol is to provide a way to configure a
    running LinuxSampler instance and to retrieve information about it.
@@ -332,12 +388,12 @@
 
 
 
-Schoenebeck            Expires November 19, 2005                [Page 6]
+Schoenebeck            Expires November 22, 2005                [Page 7]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-4.  Communication Overview
+5.  Communication Overview
 
    There are two distinct methods of communication between a running
    instance of LinuxSampler and one or more control applications, so
@@ -349,29 +405,29 @@
    more effort to be implemented in the front-end application.  The two
    communication methods will be described next.
 
-4.1  Request/response communication method
+5.1  Request/response communication method
 
-   This simple communication method is based on TCP.  The front-end
-   application establishes a TCP connection to the LinuxSampler instance
-   on a certain host system.  Then the front-end application will send
-   certain ASCII based commands as defined in this document (every
-   command line must be CRLF terminated - see "Conventions used in this
-   document" at the beginning of this document) and the LinuxSampler
-   application will response after a certain process time with an
-   appropriate ASCII based answer, also as defined in this document.  So
-   this TCP communication is simply based on query and answer paradigm.
-   That way LinuxSampler is only able to answer on queries from
-   front-ends, but not able to automatically send messages to the client
-   if it's not asked to.  The fronted should not reconnect to
-   LinuxSampler for every single command, instead it should keep the
-   connection established and simply resend message(s) for subsequent
-   commands.  To keep information in the front-end up-to-date the
-   front-end has to periodically send new requests to get the current
-   information from the LinuxSampler instance.  This is often referred
-   to as "polling".  While polling is simple to implement and may be OK
-   to use in some cases, there may be disadvantages to polling such as
-   network traffic overhead and information being out of date.  It is
-   possible for a client or several clients to open more than one
+   This simple communication method is based on TCP [RFC793].  The
+   front-end application establishes a TCP connection to the
+   LinuxSampler instance on a certain host system.  Then the front-end
+   application will send certain ASCII based commands as defined in this
+   document (every command line must be CRLF terminated - see
+   "Conventions used in this document" at the beginning of this
+   document) and the LinuxSampler application will response after a
+   certain process time with an appropriate ASCII based answer, also as
+   defined in this document.  So this TCP communication is simply based
+   on query and answer paradigm.  That way LinuxSampler is only able to
+   answer on queries from front-ends, but not able to automatically send
+   messages to the client if it's not asked to.  The fronted should not
+   reconnect to LinuxSampler for every single command, instead it should
+   keep the connection established and simply resend message(s) for
+   subsequent commands.  To keep information in the front-end up-to-date
+   the front-end has to periodically send new requests to get the
+   current information from the LinuxSampler instance.  This is often
+   referred to as "polling".  While polling is simple to implement and
+   may be OK to use in some cases, there may be disadvantages to polling
+   such as network traffic overhead and information being out of date.
+   It is possible for a client or several clients to open more than one
    connection to the server at the same time.  It is also possible to
    send more than one request to the server at the same time but if
    those requests are sent over the same connection server MUST execute
@@ -388,12 +444,12 @@
 
 
 
-Schoenebeck            Expires November 19, 2005                [Page 7]
+Schoenebeck            Expires November 22, 2005                [Page 8]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-4.1.1  Result format
+5.1.1  Result format
 
    Result set could be one of the following types:
 
@@ -444,7 +500,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005                [Page 8]
+Schoenebeck            Expires November 22, 2005                [Page 9]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -490,7 +546,7 @@
       C: "CREATE AUDIO_OUTPUT_DEVICE ALSA SAMPLERATE=96000"
       S: "WRN[0]:32:Sample rate not supported, using 44100 instead."
 
-4.2  Subscribe/notify communication method
+5.2  Subscribe/notify communication method
 
    This more sophisticated communication method is actually only an
    extension of the simple request/response communication method.  The
@@ -500,7 +556,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005                [Page 9]
+Schoenebeck            Expires November 22, 2005               [Page 10]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -542,7 +598,7 @@
 
    where <event-id> will be replace by the respective event that client
    is no longer interested in receiving.  For a list of supported events
-   see Section 7.
+   see Section 8.
 
    Example: the fill states of disk stream buffers have changed on
    sampler channel 4 and the LinuxSampler instance will react by sending
@@ -556,7 +612,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 10]
+Schoenebeck            Expires November 22, 2005               [Page 11]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -612,27 +668,27 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 11]
+Schoenebeck            Expires November 22, 2005               [Page 12]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-5.  Description for control commands
+6.  Description for control commands
 
    This chapter will describe the available control commands that can be
    sent on the TCP connection in detail.  Some certain commands (e.g.
-   "GET CHANNEL INFO" (Section 5.4.10) or "GET ENGINE INFO" (Section
-   5.4.9)) lead to multiple-line responses.  In this case LinuxSampler
+   "GET CHANNEL INFO" (Section 6.4.10) or "GET ENGINE INFO" (Section
+   6.4.9)) lead to multiple-line responses.  In this case LinuxSampler
    signals the end of the response by a "." (single dot) line.
 
-5.1  Ignored lines and comments
+6.1  Ignored lines and comments
 
    White lines, that is lines which only contain space and tabulator
    characters, and lines that start with a "#" character are ignored,
    thus it's possible for example to group commands and to place
    comments in a LSCP script file.
 
-5.2  Configuring audio drivers
+6.2  Configuring audio drivers
 
    Instances of drivers in LinuxSampler are called devices.  You can use
    multiple audio devices simultaneously, e.g.  to output the sound of
@@ -661,14 +717,14 @@
    retrieve what parameters drivers are offering, how to retrieve their
    possible values, etc.
 
-5.2.1  Getting amount of available audio output drivers
+6.2.1  Getting amount of available audio output drivers
 
    Use the following command to get the number of audio output drivers
    currently available for the LinuxSampler instance:
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 12]
+Schoenebeck            Expires November 22, 2005               [Page 13]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -685,7 +741,7 @@
       C: "GET AVAILABLE_AUDIO_OUTPUT_DRIVERS"
       S: "2"
 
-5.2.2  Getting all available audio output drivers
+6.2.2  Getting all available audio output drivers
 
    Use the following command to list all audio output drivers currently
    available for the LinuxSampler instance:
@@ -702,7 +758,7 @@
       C: "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS"
       S: "ALSA,JACK"
 
-5.2.3  Getting information about a specific audio output driver
+6.2.3  Getting information about a specific audio output driver
 
    Use the following command to get detailed information about a
    specific audio output driver:
@@ -710,7 +766,7 @@
       GET AUDIO_OUTPUT_DRIVER INFO <audio-output-driver>
 
    Where <audio-output-driver> is the name of the audio output driver,
-   returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2)
+   returned by the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
    command.
 
    Possible Answers:
@@ -724,7 +780,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 13]
+Schoenebeck            Expires November 22, 2005               [Page 14]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -750,7 +806,7 @@
       FRAGMENTSIZE,CARD"
          "."
 
-5.2.4  Getting information about specific audio output driver parameter
+6.2.4  Getting information about specific audio output driver parameter
 
    Use the following command to get detailed information about a
    specific audio output driver parameter:
@@ -758,10 +814,10 @@
       GET AUDIO_OUTPUT_DRIVER_PARAMETER INFO <audio> <prm> [<deplist>]
 
    Where <audio> is the name of the audio output driver as returned by
-   the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2) command,
+   the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command,
    <prm> a specific parameter name for which information should be
    obtained (as returned by the "GET AUDIO_OUTPUT_DRIVER INFO" (Section
-   5.2.3) command) and <deplist> is an optional list of parameters on
+   6.2.3) command) and <deplist> is an optional list of parameters on
    which the sought parameter <prm> depends on, <deplist> is a list of
    key-value pairs in form of "key1=val1 key2=val2 ...", where character
    string values are encapsulated into apostrophes (').  Arguments given
@@ -780,7 +836,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 14]
+Schoenebeck            Expires November 22, 2005               [Page 15]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -800,12 +856,12 @@
       MANDATORY -
          either true or false, defines if this parameter must be given
          when the device is to be created with the 'CREATE
-         AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command (always returned,
+         AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
          no matter which driver parameter)
       FIX -
          either true or false, if false then this parameter can be
          changed at any time, once the device is created by the 'CREATE
-         AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command (always returned,
+         AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command (always returned,
          no matter which driver parameter)
       MULTIPLICITY -
          either true or false, defines if this parameter allows only one
@@ -825,7 +881,7 @@
       DEFAULT -
          reflects the default value for this parameter which is used
          when the device is created and not explicitly given with the
-         'CREATE AUDIO_OUTPUT_DEVICE' (Section 5.2.5) command, in case
+         'CREATE AUDIO_OUTPUT_DEVICE' (Section 6.2.5) command, in case
          of MULTIPLCITY=true, this is a comma separated list, that's why
          character strings are encapsulated into apostrophes (')
          (optionally returned, dependent to driver parameter)
@@ -836,7 +892,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 15]
+Schoenebeck            Expires November 22, 2005               [Page 16]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -892,7 +948,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 16]
+Schoenebeck            Expires November 22, 2005               [Page 17]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -900,7 +956,7 @@
          "RANGE_MAX: 96000"
          "."
 
-5.2.5  Creating an audio output device
+6.2.5  Creating an audio output device
 
    Use the following command to create a new audio output device for
    the desired audio output system:
@@ -908,12 +964,14 @@
       CREATE AUDIO_OUTPUT_DEVICE <audio-output-driver> [<param-list>]
 
    Where <audio-output-driver> should be replaced by the desired audio
-   output system and <param-list> by an optional list of driver specific
-   parameters in form of "key1=val1 key2=val2 ...", where character
-   string values should be encapsulated into apostrophes (').  Note that
-   there might be drivers which require parameter(s) to be given with
-   this command.  Use the previously described commands in this chapter
-   to get this information.
+   output system as returned by the "LIST
+   AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2) command and
+   <param-list> by an optional list of driver specific parameters in
+   form of "key1=val1 key2=val2 ...", where character string values
+   should be encapsulated into apostrophes (').  Note that there might
+   be drivers which require parameter(s) to be given with this command.
+   Use the previously described commands in this chapter to get this
+   information.
 
    Possible Answers:
 
@@ -938,23 +996,24 @@
       C: "CREATE AUDIO_OUTPUT_DEVICE ALSA CARD='2,0' SAMPLERATE=96000"
       S: "OK[1]"
 
-5.2.6  Destroying an audio output device
+6.2.6  Destroying an audio output device
 
    Use the following command to destroy a created output device:
 
-      DESTROY AUDIO_OUTPUT_DEVICE <device-id>
 
-   Where <device-id> should be replaced by the numerical ID of the audio
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 17]
+Schoenebeck            Expires November 22, 2005               [Page 18]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
+      DESTROY AUDIO_OUTPUT_DEVICE <device-id>
+
+   Where <device-id> should be replaced by the numerical ID of the audio
    output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section
-   5.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 5.2.8) command.
+   6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command.
 
    Possible Answers:
 
@@ -975,7 +1034,7 @@
       C: "DESTROY AUDIO_OUTPUT_DEVICE 0"
       S: "OK"
 
-5.2.7  Getting all created audio output device count
+6.2.7  Getting all created audio output device count
 
    Use the following command to count all created audio output devices:
 
@@ -991,7 +1050,7 @@
       C: "GET AUDIO_OUTPUT_DEVICES"
       S: "4"
 
-5.2.8  Getting all created audio output device list
+6.2.8  Getting all created audio output device list
 
    Use the following command to list all created audio output devices:
 
@@ -999,22 +1058,22 @@
 
    Possible Answers:
 
-      LinuxSampler will answer by sending a comma separated list with
-      the numerical IDs of all audio output devices.
-
 
 
-Schoenebeck            Expires November 19, 2005               [Page 18]
+Schoenebeck            Expires November 22, 2005               [Page 19]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
+      LinuxSampler will answer by sending a comma separated list with
+      the numerical IDs of all audio output devices.
+
    Example:
 
       C: "LIST AUDIO_OUTPUT_DEVICES"
       S: "0,1,4,5"
 
-5.2.9  Getting current settings of an audio output device
+6.2.9  Getting current settings of an audio output device
 
    Use the following command to get current settings of a specific,
    created audio output device:
@@ -1023,7 +1082,7 @@
 
    Where <device-id> should be replaced by numerical ID of the audio
    output device as e.g.  returned by the "LIST AUDIO_OUTPUT_DEVICES"
-   (Section 5.2.8) command.
+   (Section 6.2.8) command.
 
    Possible Answers:
 
@@ -1037,7 +1096,7 @@
 
       DRIVER -
          identifier of the used audio output driver, as also returned by
-         the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 5.2.2)
+         the "LIST AVAILABLE_AUDIO_OUTPUT_DRIVERS" (Section 6.2.2)
          command
       CHANNELS -
          amount of audio output channels this device currently offers
@@ -1051,20 +1110,19 @@
    The mentioned fields above don't have to be in particular order.  The
    fields above are only those fields which are returned by all audio
    output devices.  Every audio output driver might have its own,
-   additional driver specific parameters (see Section 5.2.3) which are
+   additional driver specific parameters (see Section 6.2.3) which are
    also returned by this command.
 
-   Example:
-
-
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 19]
+Schoenebeck            Expires November 22, 2005               [Page 20]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
+   Example:
+
       C: "GET AUDIO_OUTPUT_DEVICE INFO 0"
       S: "DRIVER: ALSA"
          "CHANNELS: 2"
@@ -1075,7 +1133,7 @@
          "CARD: '0,0'"
          "."
 
-5.2.10  Changing settings of audio output devices
+6.2.10  Changing settings of audio output devices
 
    Use the following command to alter a specific setting of a created
    audio output device:
@@ -1083,8 +1141,10 @@
       SET AUDIO_OUTPUT_DEVICE_PARAMETER <device-id> <key>=<value>
 
    Where <device-id> should be replaced by the numerical ID of the audio
-   output device, <key> by the name of the parameter to change and
-   <value> by the new value for this parameter.
+   output device as given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section
+   6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <key>
+   by the name of the parameter to change and <value> by the new value
+   for this parameter.
 
    Possible Answers:
 
@@ -1103,24 +1163,27 @@
       C: "SET AUDIO_OUTPUT_DEVICE_PARAMETER 0 FRAGMENTSIZE=128"
       S: "OK"
 
-5.2.11  Getting information about an audio channel
+6.2.11  Getting information about an audio channel
 
    Use the following command to get information about an audio channel:
 
       GET AUDIO_OUTPUT_CHANNEL INFO <device-id> <audio-chan>
 
-   Where <device-id> is the numerical ID of the audio output device and
-   <audio-chan> the audio channel number.
 
-   Possible Answers:
 
 
-
-Schoenebeck            Expires November 19, 2005               [Page 20]
+Schoenebeck            Expires November 22, 2005               [Page 21]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
+   Where <device-id> is the numerical ID of the audio output device as
+   given by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
+   AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command and <audio-chan> the
+   audio channel number.
+
+   Possible Answers:
+
       LinuxSampler will answer by sending a <CRLF> separated list.  Each
       answer line begins with the information category name followed by
       a colon and then a space character <SP> and finally the info
@@ -1162,28 +1225,27 @@
          "IS_MIX_CHANNEL: false"
          "."
 
-      C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
-      S: "NAME: studio monitor left"
-         "IS_MIX_CHANNEL: true"
-         "MIX_CHANNEL_DESTINATION: 1"
-         "."
-
 
 
 
-
-Schoenebeck            Expires November 19, 2005               [Page 21]
+Schoenebeck            Expires November 22, 2005               [Page 22]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
+      C: "GET AUDIO_OUTPUT_CHANNEL INFO 0 2"
+      S: "NAME: studio monitor left"
+         "IS_MIX_CHANNEL: true"
+         "MIX_CHANNEL_DESTINATION: 1"
+         "."
+
       C: "GET AUDIO_OUTPUT_CHANNEL INFO 1 0"
       S: "NAME: 'ardour (left)'"
          "IS_MIX_CHANNEL: false"
          "JACK_BINDINGS: 'ardour:0'"
          "."
 
-5.2.12  Getting information about specific audio channel parameter
+6.2.12  Getting information about specific audio channel parameter
 
    Use the following command to get detailed information about specific
    audio channel parameter:
@@ -1191,10 +1253,11 @@
       GET AUDIO_OUTPUT_CHANNEL_PARAMETER INFO <dev-id> <chan> <param>
 
    Where <dev-id> is the numerical ID of the audio output device as
-   returned by the "LIST AUDIO_OUTPUT_DEVICES" (Section 5.2.8) command,
-   <chan> the audio channel number and <param> a specific channel
-   parameter name for which information should be obtained (as returned
-   by the "GET AUDIO_OUTPUT_CHANNEL INFO" (Section 5.2.11) command).
+   returned by the "CREATE AUDIO_OUTPUT_DEVICE" (Section 6.2.5) or "LIST
+   AUDIO_OUTPUT_DEVICES" (Section 6.2.8) command, <chan> the audio
+   channel number and <param> a specific channel parameter name for
+   which information should be obtained (as returned by the "GET
+   AUDIO_OUTPUT_CHANNEL INFO" (Section 6.2.11) command).
 
    Possible Answers:
 
@@ -1217,6 +1280,15 @@
          FIX -
             either true or false, if true then this parameter is read
             only, thus cannot be altered (always returned)
+
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 23]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
          MULTIPLICITY -
             either true or false, defines if this parameter allows only
             one value or a list of values, where true means multiple
@@ -1225,14 +1297,6 @@
          RANGE_MIN -
             defines lower limit of the allowed value range for this
             parameter, can be an integer value as well as a dotted
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 22]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
             number, usually used in conjunction with 'RANGE_MAX', but
             may also appear without (optionally returned, dependent to
             driver and channel parameter)
@@ -1259,7 +1323,7 @@
          "POSSIBILITIES: 'PCM:0','PCM:1','ardour:0','ardour:1'"
          "."
 
-5.2.13  Changing settings of audio output channels
+6.2.13  Changing settings of audio output channels
 
    Use the following command to alter a specific setting of an audio
    output channel:
@@ -1267,11 +1331,20 @@
       SET AUDIO_OUTPUT_CHANNEL_PARAMETER <dev-id> <chn> <key>=<value>
 
    Where <dev-id> should be replaced by the numerical ID of the audio
-   device, <chn> by the audio channel number, <key> by the name of the
+   output device as returned by the "CREATE AUDIO_OUTPUT_DEVICE"
+   (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
+   command, <chn> by the audio channel number, <key> by the name of the
    parameter to change and <value> by the new value for this parameter.
 
    Possible Answers:
 
+
+
+Schoenebeck            Expires November 22, 2005               [Page 24]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       "OK" -
          in case setting was successfully changed
       "WRN:<warning-code>:<warning-message>" -
@@ -1282,13 +1355,6 @@
          in case it failed, providing an appropriate error code and
          error message
 
-
-
-Schoenebeck            Expires November 19, 2005               [Page 23]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
    Example:
 
       C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 JACK_BINDINGS='PCM:0'"
@@ -1297,7 +1363,7 @@
       C: "SET AUDIO_OUTPUT_CHANNEL PARAMETER 0 0 NAME='monitor left'"
       S: "OK"
 
-5.3  Configuring MIDI input drivers
+6.3  Configuring MIDI input drivers
 
    Instances of drivers in LinuxSampler are called devices.  You can use
    multiple MIDI devices simultaneously, e.g.  to use MIDI over ethernet
@@ -1328,22 +1394,21 @@
    retrieve what parameters drivers are offering, how to retrieve their
    possible values, etc.
 
-5.3.1  Getting amount of available MIDI input drivers
-
-   Use the following command to get the number of MIDI input drivers
-   currently available for the LinuxSampler instance:
 
-      GET AVAILABLE_MIDI_INPUT_DRIVERS
 
-   Possible Answers:
+Schoenebeck            Expires November 22, 2005               [Page 25]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
+6.3.1  Getting amount of available MIDI input drivers
 
+   Use the following command to get the number of MIDI input drivers
+   currently available for the LinuxSampler instance:
 
-Schoenebeck            Expires November 19, 2005               [Page 24]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
+      GET AVAILABLE_MIDI_INPUT_DRIVERS
 
+   Possible Answers:
 
       LinuxSampler will answer by sending the number of available MIDI
       input drivers.
@@ -1353,7 +1418,7 @@
       C: "GET AVAILABLE_MIDI_INPUT_DRIVERS"
       S: "2"
 
-5.3.2  Getting all available MIDI input drivers
+6.3.2  Getting all available MIDI input drivers
 
    Use the following command to list all MIDI input drivers currently
    available for the LinuxSampler instance:
@@ -1370,17 +1435,28 @@
       C: "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
       S: "ALSA,JACK"
 
-5.3.3  Getting information about a specific MIDI input driver
+6.3.3  Getting information about a specific MIDI input driver
 
    Use the following command to get detailed information about a
    specific MIDI input driver:
 
       GET MIDI_INPUT_DRIVER INFO <midi-input-driver>
 
-   Where <midi-input-driver> is the name of the MIDI input driver.
+   Where <midi-input-driver> is the name of the MIDI input driver as
+   returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
+   command.
 
    Possible Answers:
 
+
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 26]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       LinuxSampler will answer by sending a <CRLF> separated list.  Each
       answer line begins with the information category name followed by
       a colon and then a space character <SP> and finally the info
@@ -1392,15 +1468,6 @@
          VERSION -
             arbitrary character string regarding the driver's version
          PARAMETERS -
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 25]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
             comma separated list of all parameters available for the
             given MIDI input driver
       The mentioned fields above don't have to be in particular order.
@@ -1413,7 +1480,7 @@
          "PARAMETERS: DRIVER,ACTIVE"
          "."
 
-5.3.4  Getting information about specific MIDI input driver parameter
+6.3.4  Getting information about specific MIDI input driver parameter
 
    Use the following command to get detailed information about a
    specific parameter of a specific MIDI input driver:
@@ -1421,9 +1488,9 @@
       GET MIDI_INPUT_DRIVER_PARAMETER INFO <midit> <param> [<deplist>]
 
    Where <midit> is the name of the MIDI input driver as returned by the
-   "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 5.3.2) command, <param>
+   "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2) command, <param>
    a specific parameter name for which information should be obtained
-   (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 5.3.3)
+   (as returned by the "GET MIDI_INPUT_DRIVER INFO" (Section 6.3.3)
    command) and <deplist> is an optional list of parameters on which the
    sought parameter <param> depends on, <deplist> is a key-value pair
    list in form of "key1=val1 key2=val2 ...", where character string
@@ -1438,6 +1505,14 @@
    answer line begins with the information category name followed by a
    colon and then a space character <SP> and finally the info character
    string to that info category.  There is information which is always
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 27]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
    returned, independent of the given driver parameter and there is
    optional information which is only shown dependent to given driver
    parameter.  At the moment the following information categories are
@@ -1448,27 +1523,18 @@
          value(s) or "FLOAT" for dotted number(s) or "STRING" for
          character string(s) (always returned, no matter which driver
          parameter)
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 26]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
       DESCRIPTION -
          arbitrary text describing the purpose of the parameter (always
          returned, no matter which driver parameter)
       MANDATORY -
          either true or false, defines if this parameter must be given
          when the device is to be created with the 'CREATE
-         MIDI_INPUT_DEVICE' (Section 5.3.5) command (always returned, no
+         MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
          matter which driver parameter)
       FIX -
          either true or false, if false then this parameter can be
          changed at any time, once the device is created by the 'CREATE
-         MIDI_INPUT_DEVICE' (Section 5.3.5) command (always returned, no
+         MIDI_INPUT_DEVICE' (Section 6.3.5) command (always returned, no
          matter which driver parameter)
       MULTIPLICITY -
          either true or false, defines if this parameter allows only one
@@ -1488,13 +1554,21 @@
       DEFAULT -
          reflects the default value for this parameter which is used
          when the device is created and not explicitly given with the
-         'CREATE MIDI_INPUT_DEVICE' (Section 5.3.5) command, in case of
+         'CREATE MIDI_INPUT_DEVICE' (Section 6.3.5) command, in case of
          MULTIPLCITY=true, this is a comma separated list, that's why
          character strings are encapsulated into apostrophes (')
          (optionally returned, dependent to driver parameter)
       RANGE_MIN -
          defines lower limit of the allowed value range for this
          parameter, can be an integer value as well as a dotted number,
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 28]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
          this parameter is often used in conjunction with RANGE_MAX, but
          may also appear without (optionally returned, dependent to
          driver parameter)
@@ -1504,15 +1578,6 @@
          this parameter is often used in conjunction with RANGE_MIN, but
          may also appear without (optionally returned, dependent to
          driver parameter)
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 27]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
       POSSIBILITIES -
          comma separated list of possible values for this parameter,
          character strings are encapsulated into apostrophes (optionally
@@ -1531,7 +1596,7 @@
          "DEFAULT: true"
          "."
 
-5.3.5  Creating a MIDI input device
+6.3.5  Creating a MIDI input device
 
    Use the following command to create a new MIDI input device for  the
    desired MIDI input system:
@@ -1539,18 +1604,27 @@
       CREATE MIDI_INPUT_DEVICE <midi-input-driver> [<param-list>]
 
    Where <midi-input-driver> should be replaced by the desired MIDI
-   input system and <param-list> by an optional list of driver specific
-   parameters in form of "key1=val1 key2=val2 ...", where character
-   string values should be encapsulated into apostrophes (').  Note that
-   there might be drivers which require parameter(s) to be given with
-   this command.  Use the previously described commands in this chapter
-   to get that information.
+   input system as returned by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS"
+   (Section 6.3.2) command and <param-list> by an optional list of
+   driver specific parameters in form of "key1=val1 key2=val2 ...",
+   where character string values should be encapsulated into apostrophes
+   (').  Note that there might be drivers which require parameter(s) to
+   be given with this command.  Use the previously described commands in
+   this chapter to get that information.
 
    Possible Answers:
 
       "OK[<device-id>]" -
          in case the device was successfully created, where <device-id>
          is the numerical ID of the new device
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 29]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       "WRN[<device-id>]:<warning-code>:<warning-message>" -
          in case the driver was loaded successfully, where <device-id>
          is the numerical ID of the new device, but there are noteworthy
@@ -1562,23 +1636,18 @@
 
    Example:
 
-
-
-Schoenebeck            Expires November 19, 2005               [Page 28]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
       C: "CREATE MIDI_INPUT_DEVICE ALSA"
       S: "OK[0]"
 
-5.3.6  Destroying a MIDI input device
+6.3.6  Destroying a MIDI input device
 
    Use the following command to destroy a created MIDI input device:
 
       DESTROY MIDI_INPUT_DEVICE <device-id>
 
-   Where <device-id> should be replaced by the device's numerical ID.
+   Where <device-id> should be replaced by the device's numerical ID as
+   returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
+   MIDI_INPUT_DEVICES" (Section 6.3.8) command.
 
    Possible Answers:
 
@@ -1597,7 +1666,7 @@
       C: "DESTROY MIDI_INPUT_DEVICE 0"
       S: "OK"
 
-5.3.7  Getting all created MIDI input device count
+6.3.7  Getting all created MIDI input device count
 
    Use the following command to count all created MIDI input devices:
 
@@ -1605,6 +1674,13 @@
 
    Possible Answers:
 
+
+
+Schoenebeck            Expires November 22, 2005               [Page 30]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       LinuxSampler will answer by sending the current number of all MIDI
       input devices.
 
@@ -1613,18 +1689,10 @@
       C: "GET MIDI_INPUT_DEVICES"
       S: "3"
 
-5.3.8  Getting all created MIDI input device list
+6.3.8  Getting all created MIDI input device list
 
    Use the following command to list all created MIDI input devices:
 
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 29]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
       LIST MIDI_INPUT_DEVICES
 
    Possible Answers:
@@ -1640,14 +1708,16 @@
       C: "LIST MIDI_INPUT_DEVICES"
       S: "1,3"
 
-5.3.9  Getting current settings of a MIDI input device
+6.3.9  Getting current settings of a MIDI input device
 
    Use the following command to get current settings of a specific,
    created MIDI input device:
 
       GET MIDI_INPUT_DEVICE INFO <device-id>
 
-   Where <device-id> is the numerical ID of the MIDI input device.
+   Where <device-id> is the numerical ID of the MIDI input device as
+   returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
+   MIDI_INPUT_DEVICES" (Section 6.3.8) command.
 
    Possible Answers:
 
@@ -1659,9 +1729,18 @@
       apostrophes (').  At the moment the following information
       categories are defined (independent of driver):
 
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 31]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+
          DRIVER -
             identifier of the used MIDI input driver, as e.g.  returned
-            by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 5.3.2)
+            by the "LIST AVAILABLE_MIDI_INPUT_DRIVERS" (Section 6.3.2)
             command
          ACTIVE -
             either true or false, if false then the MIDI device is
@@ -1672,15 +1751,7 @@
    fields above are only those fields which are returned by all MIDI
    input devices.  Every MIDI input driver might have its own,
    additional driver specific parameters (see "GET MIDI_INPUT_DRIVER
-   INFO" (Section 5.3.3) command) which are also returned by this
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 30]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
+   INFO" (Section 6.3.3) command) which are also returned by this
    command.
 
    Example:
@@ -1690,7 +1761,7 @@
          "ACTIVE: true"
          "."
 
-5.3.10  Changing settings of MIDI input devices
+6.3.10  Changing settings of MIDI input devices
 
    Use the following command to alter a specific setting of a created
    MIDI input device:
@@ -1698,8 +1769,10 @@
       SET MIDI_INPUT_DEVICE_PARAMETER <device-id> <key>=<value>
 
    Where <device-id> should be replaced by the numerical ID of the MIDI
-   input device, <key> by the name of the parameter to change and
-   <value> by the new value for this parameter.
+   input device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section
+   6.3.5) or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <key> by
+   the name of the parameter to change and <value> by the new value for
+   this parameter.
 
    Possible Answers:
 
@@ -1713,30 +1786,31 @@
          in case it failed, providing an appropriate error code and
          error message
 
+
+
+Schoenebeck            Expires November 22, 2005               [Page 32]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
    Example:
 
       C: "SET MIDI_INPUT_DEVICE_PARAMETER 0 ACTIVE=false"
       S: "OK"
 
-5.3.11  Getting information about a MIDI port
+6.3.11  Getting information about a MIDI port
 
    Use the following command to get information about a MIDI port:
 
       GET MIDI_INPUT_PORT INFO <device-id> <midi-port>
 
-   Where <device-id> is the numerical ID of the MIDI input device and
-   <midi-port> the MIDI input port number.
+   Where <device-id> is the numerical ID of the MIDI input device as
+   returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
+   MIDI_INPUT_DEVICES" (Section 6.3.8) command and <midi-port> the MIDI
+   input port number.
 
    Possible Answers:
 
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 31]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
       LinuxSampler will answer by sending a <CRLF> separated list.  Each
       answer line begins with the information category name followed by
       a colon and then a space character <SP> and finally the info
@@ -1756,7 +1830,7 @@
          "ALSA_SEQ_BINDINGS: '64:0'"
          "."
 
-5.3.12  Getting information about specific MIDI port parameter
+6.3.12  Getting information about specific MIDI port parameter
 
    Use the following command to get detailed information about specific
    MIDI port parameter:
@@ -1764,10 +1838,19 @@
       GET MIDI_INPUT_PORT_PARAMETER INFO <dev-id> <port> <param>
 
    Where <dev-id> is the numerical ID of the MIDI input device as
-   returned by the "LIST MIDI_INPUT_DEVICES" (Section 5.3.8) command,
-   <port> the MIDI port number and <param> a specific port parameter
-   name for which information should be obtained (as returned by the
-   "GET MIDI_INPUT_PORT INFO" (Section 5.3.11) command).
+   returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5) or "LIST
+   MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> the MIDI port
+   number and <param> a specific port parameter name for which
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 33]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+   information should be obtained (as returned by the "GET
+   MIDI_INPUT_PORT INFO" (Section 6.3.11) command).
 
    Possible Answers:
 
@@ -1784,15 +1867,6 @@
          value(s) or "FLOAT" for dotted number(s) or "STRING" for
          character string(s) (always returned)
       DESCRIPTION -
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 32]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
          arbitrary text describing the purpose of the parameter (always
          returned)
       FIX -
@@ -1823,6 +1897,14 @@
 
    Example:
 
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 34]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       C: "GET MIDI_INPUT_PORT_PARAMETER INFO 0 0 ALSA_SEQ_BINDINGS"
       S: "DESCRIPTION: bindings to other ALSA sequencer clients"
          "TYPE: STRING"
@@ -1831,7 +1913,7 @@
          "POSSIBILITIES: '64:0','68:0','68:1'"
          "."
 
-5.3.13  Changing settings of MIDI input ports
+6.3.13  Changing settings of MIDI input ports
 
    Use the following command to alter a specific setting of a MIDI input
    port:
@@ -1839,15 +1921,10 @@
       SET MIDI_INPUT_PORT_PARAMETER <device-id> <port> <key>=<value>
 
    Where <device-id> should be replaced by the numerical ID of the MIDI
-   device, <port> by the MIDI port number, <key> by the name of the
-   parameter to change and <value> by the new value for this parameter.
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 33]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
+   device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
+   or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command, <port> by the
+   MIDI port number, <key> by the name of the parameter to change and
+   <value> by the new value for this parameter.
 
    Possible Answers:
 
@@ -1865,17 +1942,25 @@
 
 
 
-5.4  Configuring sampler channels
+6.4  Configuring sampler channels
 
    The following commands describe how to add and remove sampler
-   channels, deploy sampler engines, load instruments and connect
-   sampler channels to MIDI and audio devices.
+   channels, associate a sampler channel with a sampler engine, load
+   instruments and connect sampler channels to MIDI and audio devices.
 
-5.4.1  Loading an instrument
+6.4.1  Loading an instrument
 
    An instrument file can be loaded and assigned to a sampler channel by
    one of the following commands:
 
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 35]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       LOAD INSTRUMENT [NON_MODAL] '<filename>' <instr-index>
       <sampler-channel>
 
@@ -1890,7 +1975,7 @@
    been fully loaded and the channel is ready to be used while NON_MODAL
    version returns immediately and a background process is launched to
    load the instrument on the channel.  The GET CHANNEL INFO (Section
-   5.4.10) command can be used to obtain loading progress from
+   6.4.10) command can be used to obtain loading progress from
    INSTRUMENT_STATUS field.  LOAD command will perform sanity checks
    such as making sure that the file could be read and it is of a proper
    format and SHOULD return ERR and SHOULD not launch the background
@@ -1898,13 +1983,6 @@
 
    Possible Answers:
 
-
-
-Schoenebeck            Expires November 19, 2005               [Page 34]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
       "OK" -
          in case the instrument was successfully loaded
       "WRN:<warning-code>:<warning-message>" -
@@ -1921,19 +1999,32 @@
 
 
 
-5.4.2  Loading a sampler engine
+6.4.2  Loading a sampler engine
 
-   A sample engine can be deployed and assigned to a specific sampler
-   channel by the following command:
+   A sampler engine type can be associated to a specific sampler channel
+   by the following command:
 
       LOAD ENGINE <engine-name> <sampler-channel>
 
    Where <engine-name> is an engine name as obtained by the "LIST
-   AVAILABLE_ENGINES" (Section 5.4.8) command and <sampler-channel> the
-   sampler channel the deployed engine should be assigned to.  Even if
-   the respective sampler channel has already a deployed engine with
-   that engine name, a new engine instance will be assigned to the
-   sampler channel.
+   AVAILABLE_ENGINES" (Section 6.4.8) command and <sampler-channel> the
+   sampler channel as returned by the "ADD CHANNEL" (Section 6.4.5) or
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 36]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+   "LIST CHANNELS" (Section 6.4.4) command where the engine type should
+   be assigned to.  This command should be issued after adding a new
+   sampler channel and before any other control commands on the new
+   sampler channel.  It can also be used to change the engine type of a
+   sampler channel.  This command has (currently) no way to define or
+   force if a new engine instance should be created and assigned to the
+   given sampler channel or if an already existing instance of that
+   engine type, shared with other sampler channels, should be used.
 
    Possible Answers:
 
@@ -1951,17 +2042,7 @@
 
 
 
-
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 35]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
-5.4.3  Getting all created sampler channel count
+6.4.3  Getting all created sampler channel count
 
    The number of sampler channels can change on runtime.  To get the
    current amount of sampler channels, the front-end can send the
@@ -1979,12 +2060,19 @@
       C: "GET CHANNELS"
       S: "12"
 
-5.4.4  Getting all created sampler channel list
+6.4.4  Getting all created sampler channel list
 
    The number of sampler channels can change on runtime.  To get the
    current list of sampler channels, the front-end can send the
    following command:
 
+
+
+Schoenebeck            Expires November 22, 2005               [Page 37]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       LIST CHANNELS
 
    Possible Answers:
@@ -1997,7 +2085,7 @@
       C: "LIST CHANNELS"
       S: "0,1,2,3,4,5,6,9,10,11,15,20"
 
-5.4.5  Adding a new sampler channel
+6.4.5  Adding a new sampler channel
 
    A new sampler channel can be added to the end of the sampler channel
    list by sending the following command:
@@ -2009,14 +2097,6 @@
    list.  The front-end should send the respective, related commands
    right after to e.g.  load an engine, load an instrument and setting
    input, output method and eventually other commands to initialize the
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 36]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
    new channel.  The front-end should use the sampler channel returned
    by the answer of this command to perform the previously recommended
    commands, to avoid race conditions e.g.  with other front-ends that
@@ -2041,15 +2121,23 @@
 
 
 
-5.4.6  Removing a sampler channel
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 38]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+6.4.6  Removing a sampler channel
 
    A sampler channel can be removed by sending the following command:
 
       REMOVE CHANNEL <sampler-channel>
 
    Where <sampler-channel> should be replaced by the number of the
-   sampler channel as given by the "ADD CHANNEL" (Section 5.4.5) or
-   "LIST CHANNELS" (Section 5.4.4) command.  The channel numbers of all
+   sampler channel as given by the "ADD CHANNEL" (Section 6.4.5) or
+   "LIST CHANNELS" (Section 6.4.4) command.  The channel numbers of all
    subsequent sampler channels remain the same.
 
    Possible Answers:
@@ -2068,14 +2156,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 37]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
-
-
-5.4.7  Getting amount of available engines
+6.4.7  Getting amount of available engines
 
    The front-end can ask for the number of available engines by sending
    the following command:
@@ -2092,11 +2173,18 @@
       C: "GET AVAILABLE_ENGINES"
       S: "4"
 
-5.4.8  Getting all available engines
+6.4.8  Getting all available engines
 
    The front-end can ask for a list of all available engines by sending
    the following command:
 
+
+
+Schoenebeck            Expires November 22, 2005               [Page 39]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       LIST AVAILABLE_ENGINES
 
    Possible Answers:
@@ -2111,7 +2199,7 @@
       C: "LIST AVAILABLE_ENGINES"
       S: "'GigEngine','AkaiEngine','DLSEngine','JoesCustomEngine'"
 
-5.4.9  Getting information about an engine
+6.4.9  Getting information about an engine
 
    The front-end can ask for information about a specific engine by
    sending the following command:
@@ -2119,15 +2207,7 @@
       GET ENGINE INFO <engine-name>
 
    Where <engine-name> is an engine name as obtained by the "LIST
-   AVAILABLE_ENGINES" (Section 5.4.8) command.
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 38]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
+   AVAILABLE_ENGINES" (Section 6.4.8) command.
 
    Possible Answers:
 
@@ -2151,7 +2231,17 @@
          "VERSION: testing-1.0"
          "."
 
-5.4.10  Getting sampler channel information
+
+
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 40]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+6.4.10  Getting sampler channel information
 
    The front-end can ask for the current settings of a sampler channel
    by sending the following command:
@@ -2159,7 +2249,8 @@
       GET CHANNEL INFO <sampler-channel>
 
    Where <sampler-channel> is the sampler channel number the front-end
-   is interested in.
+   is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
+   "LIST CHANNELS" (Section 6.4.4) command.
 
    Possible Answers:
 
@@ -2170,21 +2261,13 @@
       following categories are defined:
 
          ENGINE_NAME -
-            name of the engine that is deployed on the sampler channel,
-            "NONE" if there's no engine deployed yet for this sampler
-            channel
+            name of the engine that is associated with the sampler
+            channel, "NONE" if there's no engine associated yet for this
+            sampler channel
          AUDIO_OUTPUT_DEVICE -
             numerical ID of the audio output device which is currently
             connected to this sampler channel to output the audio
             signal, "NONE" if there's no device connected to this
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 39]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
             sampler channel
          AUDIO_OUTPUT_CHANNELS -
             number of output channels the sampler channel offers
@@ -2206,6 +2289,14 @@
          INSTRUMENT_STATUS -
             integer values 0 to 100 indicating loading progress
             percentage for the instrument.  Negative value indicates a
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 41]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
             loading exception.  Value of 100 indicates that the
             instrument is fully loaded.
          MIDI_INPUT_DEVICE -
@@ -2232,15 +2323,6 @@
          "VOLUME: 1.0"
          "AUDIO_OUTPUT_DEVICE: 0"
          "AUDIO_OUTPUT_CHANNELS: 2"
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 40]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
          "AUDIO_OUTPUT_ROUTING: 0,1"
          "INSTRUMENT_FILE: /home/joe/FazioliPiano.gig"
          "INSTRUMENT_NR: 0"
@@ -2251,7 +2333,7 @@
          "MIDI_INPUT_CHANNEL: 5"
          "."
 
-5.4.11  Current number of active voices
+6.4.11  Current number of active voices
 
    The front-end can ask for the current number of active voices on a
    sampler channel by sending the following command:
@@ -2259,10 +2341,18 @@
       GET CHANNEL VOICE_COUNT <sampler-channel>
 
    Where <sampler-channel> is the sampler channel number the front-end
-   is interested in.
+   is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
+   "LIST CHANNELS" (Section 6.4.4) command.
 
    Possible Answers:
 
+
+
+Schoenebeck            Expires November 22, 2005               [Page 42]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       LinuxSampler will answer by returning the number of active voices
       on that channel.
 
@@ -2270,7 +2360,7 @@
 
 
 
-5.4.12  Current number of active disk streams
+6.4.12  Current number of active disk streams
 
    The front-end can ask for the current number of active disk streams
    on a sampler channel by sending the following command:
@@ -2278,7 +2368,8 @@
       GET CHANNEL STREAM_COUNT <sampler-channel>
 
    Where <sampler-channel> is the sampler channel number the front-end
-   is interested in.
+   is interested in as returned by the "ADD CHANNEL" (Section 6.4.5) or
+   "LIST CHANNELS" (Section 6.4.4) command.
 
    Possible Answers:
 
@@ -2291,15 +2382,7 @@
 
 
 
-
-Schoenebeck            Expires November 19, 2005               [Page 41]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
-
-
-5.4.13  Current fill state of disk stream buffers
+6.4.13  Current fill state of disk stream buffers
 
    The front-end can ask for the current fill state of all disk streams
    on a sampler channel by sending the following command:
@@ -2311,10 +2394,21 @@
       GET CHANNEL BUFFER_FILL PERCENTAGE <sampler-channel>
 
    to get the fill state in percent, where <sampler-channel> is the
-   sampler channel number the front-end is interested in.
+   sampler channel number the front-end is interested in as returned by
+   the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
+   command.
 
    Possible Answers:
 
+
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 43]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       LinuxSampler will either answer by returning a comma separated
       string with the fill state of all disk stream buffers on that
       channel or an empty line if there are no active disk streams or
@@ -2335,7 +2429,7 @@
       C: "GET CHANNEL BUFFER_FILL PERCENTAGE 4"
       S: ""
 
-5.4.14  Setting audio output device
+6.4.14  Setting audio output device
 
    The front-end can set the audio output device on a specific sampler
    channel by sending the following command:
@@ -2343,17 +2437,12 @@
       SET CHANNEL AUDIO_OUTPUT_DEVICE <sampler-channel>
       <audio-device-id>
 
-   Where <audio-device-id> is the numerical ID of the audio output
-   device and <sampler-channel> is the respective sampler channel
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 42]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
-   number.
+   Where <sampler-channel> is the respective sampler channel number as
+   returned by the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS"
+   (Section 6.4.4) command and <audio-device-id> is the numerical ID of
+   the audio output device as given by the "CREATE AUDIO_OUTPUT_DEVICE"
+   (Section 6.2.5) or "LIST AUDIO_OUTPUT_DEVICES" (Section 6.2.8)
+   command.
 
    Possible Answers:
 
@@ -2371,7 +2460,14 @@
 
 
 
-5.4.15  Setting audio output type
+Schoenebeck            Expires November 22, 2005               [Page 44]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+
+
+6.4.15  Setting audio output type
 
    DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
 
@@ -2400,16 +2496,7 @@
 
 
 
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 43]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
-5.4.16  Setting audio output channel
+6.4.16  Setting audio output channel
 
    The front-end can alter the audio output channel on a specific
    sampler channel by sending the following command:
@@ -2417,14 +2504,23 @@
       SET CHANNEL AUDIO_OUTPUT_CHANNEL <sampler-chan> <audio-out>
       <audio-in>
 
-   Where <sampler-chan> is the sampler channel number, <audio-out> is
-   the numerical ID of the sampler channel's audio output channel which
-   should be rerouted and <audio-in> is the numerical ID of the audio
-   channel of the selected audio output device where <audio-out> should
-   be routed to.
+   Where <sampler-chan> is the sampler channel number as returned by the
+   "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
+   command, <audio-out> is the numerical ID of the sampler channel's
+   audio output channel which should be rerouted and <audio-in> is the
+   numerical ID of the audio channel of the selected audio output device
+   where <audio-out> should be routed to.
 
    Possible Answers:
 
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 45]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
       "OK" -
          on success
       "WRN:<warning-code>:<warning-message>" -
@@ -2439,15 +2535,18 @@
 
 
 
-5.4.17  Setting MIDI input device
+6.4.17  Setting MIDI input device
 
    The front-end can set the MIDI input device on a specific sampler
    channel by sending the following command:
 
       SET CHANNEL MIDI_INPUT_DEVICE <sampler-channel> <midi-device-id>
 
-   Where <sampler-channel> is the sampler channel number and
-   <midi-device-id> is the the numerical ID of the MIDI input device.
+   Where <sampler-channel> is the sampler channel number as returned by
+   the "ADD CHANNEL" (Section 6.4.5) or "LIST CHANNELS" (Section 6.4.4)
+   command and <midi-device-id> is  the numerical ID of the MIDI input
+   device as returned by the "CREATE MIDI_INPUT_DEVICE" (Section 6.3.5)
+   or "LIST MIDI_INPUT_DEVICES" (Section 6.3.8) command.
 
    Possible Answers:
 
@@ -2457,14 +2556,6 @@
          if MIDI input device was set, but there are noteworthy issue(s)
          related, providing an appropriate warning code and warning
          message
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 44]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
       "ERR:<error-code>:<error-message>" -
          in case it failed, providing an appropriate error code and
          error message
@@ -2473,11 +2564,19 @@
 
 
 
-5.4.18  Setting MIDI input type
+6.4.18  Setting MIDI input type
 
    DEPRECATED: THIS COMMAND WILL DISAPPEAR SOON!
 
    The front-end can alter the MIDI input type on a specific sampler
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 46]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
    channel by sending the following command:
 
       SET CHANNEL MIDI_INPUT_TYPE <sampler-channel> <midi-input-type>
@@ -2501,7 +2600,7 @@
 
 
 
-5.4.19  Setting MIDI input port
+6.4.19  Setting MIDI input port
 
    The front-end can alter the MIDI input port on a specific sampler
    channel by sending the following command:
@@ -2513,14 +2612,6 @@
 
    Possible Answers:
 
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 45]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
       "OK" -
          on success
       "WRN:<warning-code>:<warning-message>" -
@@ -2535,7 +2626,16 @@
 
 
 
-5.4.20  Setting MIDI input channel
+
+
+Schoenebeck            Expires November 22, 2005               [Page 47]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+
+
+6.4.20  Setting MIDI input channel
 
    The front-end can alter the MIDI channel a sampler channel should
    listen to by sending the following command:
@@ -2562,21 +2662,13 @@
 
 
 
-5.4.21  Setting channel volume
+6.4.21  Setting channel volume
 
    The front-end can alter the volume of a sampler channel by sending
    the following command:
 
       SET CHANNEL VOLUME <sampler-channel> <volume>
 
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 46]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
    Where <volume> is an optionally dotted positive number (a value
    smaller than 1.0 means attenuation, whereas a value greater than 1.0
    means amplification) and <sampler-channel> defines the sampler
@@ -2589,6 +2681,14 @@
       "WRN:<warning-code>:<warning-message>" -
          if channel volume was set, but there are noteworthy issue(s)
          related, providing an appropriate warning code and warning
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 48]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
          message
       "ERR:<error-code>:<error-message>" -
          in case it failed, providing an appropriate error code and
@@ -2598,7 +2698,7 @@
 
 
 
-5.4.22  Resetting a sampler channel
+6.4.22  Resetting a sampler channel
 
    The front-end can reset a particular sampler channel by sending the
    following command:
@@ -2626,24 +2726,24 @@
 
 
 
+6.5  Controlling connection
 
+   The following commands are used to control the connection to
+   LinuxSampler.
 
-Schoenebeck            Expires November 19, 2005               [Page 47]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
+6.5.1  Register front-end for receiving event messages
 
+   The front-end can register itself to the LinuxSampler application to
+   be informed about noteworthy events by sending this command:
 
 
 
-5.5  Controlling connection
 
-   The following commands are used to control the connection to
-   LinuxSampler.
 
-5.5.1  Register front-end for receiving event messages
+Schoenebeck            Expires November 22, 2005               [Page 49]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
 
-   The front-end can register itself to the LinuxSampler application to
-   be informed about noteworthy events by sending this command:
 
       SUBSCRIBE <event-id>
 
@@ -2666,7 +2766,7 @@
 
 
 
-5.5.2  Unregister front-end for not receiving event messages
+6.5.2  Unregister front-end for not receiving event messages
 
    The front-end can unregister itself if it doesn't want to receive
    event messages anymore by sending the following command:
@@ -2680,15 +2780,6 @@
 
       "OK" -
          on success
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 48]
-
-Internet-Draft       LinuxSampler Control Protocol              May 2005
-
-
       "WRN:<warning-code>:<warning-message>" -
          if unregistration succeeded, but there are noteworthy issue(s)
          related, providing an appropriate warning code and warning
@@ -2701,7 +2792,16 @@
 
 
 
-5.5.3  Enable or disable echo of commands
+
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 50]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+6.5.3  Enable or disable echo of commands
 
    To enable or disable back sending of commands to the client the
    following command can be used:
@@ -2726,7 +2826,7 @@
 
 
 
-5.5.4  Close client connection
+6.5.4  Close client connection
 
    The client can close its network connection to LinuxSampler by
    sending the following command:
@@ -2736,33 +2836,59 @@
    This is probably more interesting for manual telnet connections to
    LinuxSampler than really useful for a front-end implementation.
 
+6.6  Global commands
 
+   The following commands have global impact on the sampler.
+
+6.6.1  Reset sampler
+
+   The front-end can reset the whole sampler by sending the following
+   command:
+
+      RESET
+
+   Possible Answers:
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 49]
+
+Schoenebeck            Expires November 22, 2005               [Page 51]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-5.6  Global commands
+      "OK" -
+         always
 
-   The following commands have global impact on the sampler.
+   Examples:
 
-5.6.1  Reset sampler
 
-   The front-end can reset the whole sampler by sending the following
-   command:
 
-      RESET
+6.6.2  General sampler informations
+
+   The client can ask for general informations about the LinuxSampler
+   instance by sending the following command:
+
+      GET SERVER INFO
 
    Possible Answers:
 
-      "OK" -
-         always
+      LinuxSampler will answer by sending a <CRLF> separated list.  Each
+      answer line begins with the information category name followed by
+      a colon and then a space character <SP> and finally the info
+      character string to that information category.  At the moment the
+      following categories are defined:
 
-   Examples:
+         DESCRIPTION -
+            arbitrary textual description about the sampler
+         VERSION -
+            version of the sampler
+         PROTOCOL_VERSION -
+            version of the LSCP specification the sampler complies with
+            (see Section 2 for details)
 
+   The mentioned fields above don't have to be in particular order.
+   Other fields might be added in future.
 
 
 
@@ -2782,52 +2908,236 @@
 
 
 
+Schoenebeck            Expires November 22, 2005               [Page 52]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
+7.  Command Syntax
 
+   The grammar of the control protocol as descibed in Section 6 is
+   defined below using Backus-Naur Form (BNF as described in [RFC2234])
+   where applicable.
 
+   input =
+      line LF
+      / line CR LF
 
+   line =
+      /* epsilon (empty line ignored) */
+      / comment
+      / command
+      / error
 
+   comment =
+      '#'
+      / comment '#'
+      / comment SP
+      / comment number
+      / comment string
 
+   command =
+      ADD SP CHANNEL
+      / GET SP get_instruction
+      / CREATE SP create_instruction
+      / DESTROY SP destroy_instruction
+      / LIST SP list_instruction
+      / LOAD SP load_instruction
+      / REMOVE SP CHANNEL SP sampler_channel
+      / SET SP set_instruction
+      / SUBSCRIBE SP subscribe_event
+      / UNSUBSCRIBE SP unsubscribe_event
+      / SELECT SP text
+      / RESET SP CHANNEL SP sampler_channel
+      / RESET
+      / QUIT
 
+   subscribe_event =
+      CHANNEL_COUNT
+      / VOICE_COUNT
+      / STREAM_COUNT
+      / BUFFER_FILL
+      / CHANNEL_INFO
+      / MISCELLANEOUS
 
+   unsubscribe_event =
 
 
 
+Schoenebeck            Expires November 22, 2005               [Page 53]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+      CHANNEL_COUNT
+      / VOICE_COUNT
+      / STREAM_COUNT
+      / BUFFER_FILL
+      / CHANNEL_INFO
+      / MISCELLANEOUS
 
+   get_instruction =
+      AVAILABLE_ENGINES
+      / AVAILABLE_MIDI_INPUT_DRIVERS
+      / MIDI_INPUT_DRIVER SP INFO SP string
+      / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string
+      / MIDI_INPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
+      key_val_list
+      / AVAILABLE_AUDIO_OUTPUT_DRIVERS
+      / AUDIO_OUTPUT_DRIVER SP INFO SP string
+      / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string
+      / AUDIO_OUTPUT_DRIVER_PARAMETER SP INFO SP string SP string SP
+      key_val_list
+      / AUDIO_OUTPUT_DEVICES
+      / MIDI_INPUT_DEVICES
+      / AUDIO_OUTPUT_DEVICE SP INFO SP number
+      / MIDI_INPUT_DEVICE SP INFO SP number
+      / MIDI_INPUT_PORT SP INFO SP number SP number
+      / MIDI_INPUT_PORT_PARAMETER SP INFO SP number SP number SP string
+      / AUDIO_OUTPUT_CHANNEL SP INFO SP number SP number
+      / AUDIO_OUTPUT_CHANNEL_PARAMETER SP INFO SP number SP number SP
+      string
+      / CHANNELS
+      / CHANNEL SP INFO SP sampler_channel
+      / CHANNEL SP BUFFER_FILL SP buffer_size_type SP sampler_channel
+      / CHANNEL SP STREAM_COUNT SP sampler_channel
+      / CHANNEL SP VOICE_COUNT SP sampler_channel
+      / ENGINE SP INFO SP engine_name
+      / SERVER SP INFO
 
-Schoenebeck            Expires November 19, 2005               [Page 50]
+   set_instruction =
+      AUDIO_OUTPUT_DEVICE_PARAMETER SP number SP string '='
+      param_val_list
+      / AUDIO_OUTPUT_CHANNEL_PARAMETER SP number SP number SP string '='
+      param_val_list
+      / MIDI_INPUT_DEVICE_PARAMETER SP number SP string '='
+      param_val_list
+      / MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '='
+      param_val_list
+      / CHANNEL SP set_chan_instruction
+      / ECHO SP boolean
+
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 54]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-6.  Command Syntax
+   create_instruction =
+      AUDIO_OUTPUT_DEVICE SP string SP key_val_list
+      / AUDIO_OUTPUT_DEVICE SP string
+      / MIDI_INPUT_DEVICE SP string SP key_val_list
+      / MIDI_INPUT_DEVICE SP string
+
+   destroy_instruction =
+      AUDIO_OUTPUT_DEVICE SP number
+      / MIDI_INPUT_DEVICE SP number
 
-   TODO: will soon automatically included from src/network/lscp.y,
-   meanwhile have a look at that file to get the exact definition of the
-   command syntax.
+   load_instruction =
+      INSTRUMENT SP load_instr_args
+      / ENGINE SP load_engine_args
 
+   set_chan_instruction =
+      AUDIO_OUTPUT_DEVICE SP sampler_channel SP device_index
+      / AUDIO_OUTPUT_CHANNEL SP sampler_channel SP audio_channel_index
+      SP audio_channel_index
+      / AUDIO_OUTPUT_TYPE SP sampler_channel SP audio_output_type_name
+      / MIDI_INPUT SP sampler_channel SP device_index SP
+      midi_input_port_index SP midi_input_channel_index
+      / MIDI_INPUT_DEVICE SP sampler_channel SP device_index
+      / MIDI_INPUT_PORT SP sampler_channel SP midi_input_port_index
+      / MIDI_INPUT_CHANNEL SP sampler_channel SP
+      midi_input_channel_index
+      / MIDI_INPUT_TYPE SP sampler_channel SP midi_input_type_name
+      / VOLUME SP sampler_channel SP volume_value
 
+   key_val_list =
+      string '=' param_val_list
+      / key_val_list SP string '=' param_val_list
 
+   buffer_size_type =
+      BYTES
+      / PERCENTAGE
 
+   list_instruction =
+      AUDIO_OUTPUT_DEVICES
+      / MIDI_INPUT_DEVICES
+      / CHANNELS
+      / AVAILABLE_ENGINES
+      / AVAILABLE_MIDI_INPUT_DRIVERS
+      / AVAILABLE_AUDIO_OUTPUT_DRIVERS
 
+   load_instr_args =
+      filename SP instrument_index SP sampler_channel
+      / NON_MODAL SP filename SP instrument_index SP sampler_channel
 
 
 
 
+Schoenebeck            Expires November 22, 2005               [Page 55]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
+
+
+   load_engine_args =
+      engine_name SP sampler_channel
 
+   device_index =
+      number
 
+   audio_channel_index =
+      number
 
+   audio_output_type_name =
+      string
 
+   midi_input_port_index =
+      number
 
+   midi_input_channel_index =
+      number
+      / ALL
 
+   midi_input_type_name =
+      string
 
+   volume_value =
+      dotnum
+      / number
 
+   sampler_channel =
+      number
 
+   instrument_index =
+      number
 
+   engine_name =
+      string
 
+   filename =
+      stringval
+
+   param_val_list =
+      param_val
+      / param_val_list','param_val
+
+   param_val =
+      string
+      / '\'' string '\''
+      / '\"' string '\"'
+      / number
+
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 56]
+
+Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
+      / dotnum
 
 
 
@@ -2852,17 +3162,43 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 51]
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+Schoenebeck            Expires November 22, 2005               [Page 57]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-7.  Events
+8.  Events
 
    This chapter will describe all currently defined events supported by
    LinuxSampler.
 
-7.1  Number of sampler channels changed
+8.1  Number of sampler channels changed
 
    Client may want to be notified when the total number of channels on
    the back-end changes by issuing the following command:
@@ -2876,7 +3212,7 @@
    where <channels> will be replaced by the new number of sampler
    channels.
 
-7.2  Number of active voices changed
+8.2  Number of active voices changed
 
    Client may want to be notified when the number of voices on the
    back-end changes by issuing the following command:
@@ -2891,7 +3227,7 @@
    voice count change occurred and <voices> by the new number of active
    voices on that channel.
 
-7.3  Number of active disk streams changed
+8.3  Number of active disk streams changed
 
    Client may want to be notified when the number of streams on the
    back-end changes by issuing the following command: SUBSCRIBE
@@ -2908,14 +3244,14 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 52]
+Schoenebeck            Expires November 22, 2005               [Page 58]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
    active disk streams on that channel.
 
-7.4  Disk stream buffer fill state changed
+8.4  Disk stream buffer fill state changed
 
    Client may want to be notified when the buffer fill state of a disk
    stream on the back-end changes by issuing the following command:
@@ -2929,10 +3265,10 @@
    where <sampler-channel> will be replaced by the sampler channel the
    buffer fill state change occurred on and <fill-data> will be replaced
    by the buffer fill data for this channel as described in Section
-   5.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Section
-   5.4.13) command was issued on this channel.
+   6.4.13 as if the "GET CHANNEL BUFFER_FILL PERCENTAGE" (Section
+   6.4.13) command was issued on this channel.
 
-7.5  Channel information changed
+8.5  Channel information changed
 
    Client may want to be notified when changes were made to sampler
    channels on the back-end by issuing the following command:
@@ -2950,7 +3286,7 @@
    rather than real time events happening on the server, it is believed
    that an empty notification message is sufficient here.
 
-7.6  Miscellaneous and debugging events
+8.6  Miscellaneous and debugging events
 
    Client may want to be notified of miscellaneous and debugging events
    occurring at the server by issuing the following command:
@@ -2964,7 +3300,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 53]
+Schoenebeck            Expires November 22, 2005               [Page 59]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -3020,12 +3356,12 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 54]
+Schoenebeck            Expires November 22, 2005               [Page 60]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-8.  Security Considerations
+9.  Security Considerations
 
    As there is so far no method of authentication and authorization
    defined and so not required for a client applications to succeed to
@@ -3076,12 +3412,12 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 55]
+Schoenebeck            Expires November 22, 2005               [Page 61]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
 
-9.  Acknowledgments
+10.  Acknowledgments
 
    This document has benefited greatly from the comments of the
    following people, discussed on the LinuxSampler developer's mailing
@@ -3092,10 +3428,16 @@
       Mark Knecht
       Grigor Iliev
 
-10  References
+11  References
 
    [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
-              Requirement Levels", BCP 14, RFC 2119, March 1997.
+              Requirement Levels", RFC 2119, 1997.
+
+   [RFC2234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
+              Specifications", RFC 2234, 1997.
+
+   [RFC793]   Defense Advanced Research Projects Agency, "TRANSMISSION
+              CONTROL PROTOCOL", RFC 793, 1981.
 
 
 Author's Address
@@ -3126,13 +3468,7 @@
 
 
 
-
-
-
-
-
-
-Schoenebeck            Expires November 19, 2005               [Page 56]
+Schoenebeck            Expires November 22, 2005               [Page 62]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -3188,7 +3524,7 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 57]
+Schoenebeck            Expires November 22, 2005               [Page 63]
 
 Internet-Draft       LinuxSampler Control Protocol              May 2005
 
@@ -3244,5 +3580,5 @@
 
 
 
-Schoenebeck            Expires November 19, 2005               [Page 58]
+Schoenebeck            Expires November 22, 2005               [Page 64]