/[svn]/linuxsampler/trunk/Documentation/lscp.xml
ViewVC logotype

Diff of /linuxsampler/trunk/Documentation/lscp.xml

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1188 by iliev, Wed May 16 14:37:22 2007 UTC revision 1362 by schoenebeck, Sun Sep 30 21:33:26 2007 UTC
# Line 16  Line 16 
16       to an annoying "missing Normative/Informative References" error message -->       to an annoying "missing Normative/Informative References" error message -->
17  <?rfc strict="no" ?>  <?rfc strict="no" ?>
18    
19  <rfc category="std" ipr="full3978" docName="LSCP 1.2">  <rfc category="std" ipr="full3978" docName="LSCP 1.2cvs">
20      <front>      <front>
21          <title>LinuxSampler Control Protocol</title>          <title>LinuxSampler Control Protocol (draft)</title>
22          <author initials='C.S.' surname="Schoenebeck" fullname='C.          <author initials='C.S.' surname="Schoenebeck" fullname='C.
23  Schoenebeck'>  Schoenebeck'>
24              <organization>              <organization>
# Line 34  Schoenebeck'> Line 34  Schoenebeck'>
34                  <email>schoenebeck at software minus engineering dot org</email>                  <email>schoenebeck at software minus engineering dot org</email>
35              </address>              </address>
36          </author>          </author>
37          <date month="May" year="2007"/>          <date month="September" year="2007"/>
38          <workgroup>LinuxSampler Developers</workgroup>          <workgroup>LinuxSampler Developers</workgroup>
39          <keyword>LSCP</keyword>          <keyword>LSCP</keyword>
40          <abstract>          <abstract>
# Line 61  Schoenebeck'> Line 61  Schoenebeck'>
61              (front-end) and server (LinuxSampler) respectively. Lines in              (front-end) and server (LinuxSampler) respectively. Lines in
62              examples must be interpreted as every line being CRLF              examples must be interpreted as every line being CRLF
63              terminated (carriage return character followed by line feed              terminated (carriage return character followed by line feed
64              character as defined in the ASCII standard), thus the following              character as defined in the ASCII standard <xref target="RFC20"/>),
65              example:</t>              thus the following example:</t>
66    
67              <t>              <t>
68                  <list>                  <list>
# Line 2061  Schoenebeck'> Line 2061  Schoenebeck'>
2061                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>                      or <xref target="LIST MIDI_INPUT_DEVICES">"LIST MIDI_INPUT_DEVICES"</xref>
2062                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of                      command, &lt;port&gt; by the MIDI port number, &lt;key&gt; by the name of
2063                      the parameter to change and &lt;value&gt; by the new value for this                      the parameter to change and &lt;value&gt; by the new value for this
2064                      parameter.</t>                      parameter (encapsulated into apostrophes) or NONE (not encapsulated into apostrophes)
2065                        for specifying no value for parameters allowing a list of values.</t>
2066    
2067                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
2068                      <t>                      <t>
# Line 2088  Schoenebeck'> Line 2089  Schoenebeck'>
2089                      <t>Example:</t>                      <t>Example:</t>
2090                      <t>                      <t>
2091                          <list>                          <list>
2092                              <t></t>                              <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS='20:0'"</t>
2093                                <t>S: "OK"</t>
2094                            </list>
2095                        </t>
2096                        <t>
2097                            <list>
2098                                <t>C: "SET MIDI_INPUT_PORT_PARAMETER 0 0 ALSA_SEQ_BINDINGS=NONE"</t>
2099                                <t>S: "OK"</t>
2100                          </list>                          </list>
2101                      </t>                      </t>
2102                  </section>                  </section>
# Line 2113  Schoenebeck'> Line 2121  Schoenebeck'>
2121                      number of the sampler channel the instrument should be assigned to.                      number of the sampler channel the instrument should be assigned to.
2122                      Each sampler channel can only have one instrument.</t>                      Each sampler channel can only have one instrument.</t>
2123    
2124                        <t>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
2125                        escape characters for special characters (see chapter
2126                        "<xref target="character_set">Character Set and Escape Sequences</xref>"
2127                        for details) and accordingly backslash characters in the filename
2128                        MUST now be escaped as well!</t>
2129    
2130                      <t>The difference between regular and NON_MODAL versions of the command                      <t>The difference between regular and NON_MODAL versions of the command
2131                      is that the regular command returns OK only after the instrument has been                      is that the regular command returns OK only after the instrument has been
2132                      fully loaded and the channel is ready to be used while NON_MODAL version                      fully loaded and the channel is ready to be used while NON_MODAL version
# Line 4325  Schoenebeck'> Line 4339  Schoenebeck'>
4339                      index, &lt;engine_name&gt; a sampler engine name as returned by                      index, &lt;engine_name&gt; a sampler engine name as returned by
4340                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>                      the <xref target="LIST AVAILABLE_ENGINES">"LIST AVAILABLE_ENGINES"</xref>
4341                      command (not encapsulated into apostrophes), &lt;filename&gt; the name                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
4342                      of the instrument's file to be deployed (encapsulated into apostrophes),                      of the instrument's file to be deployed (encapsulated into apostrophes,
4343                        supporting escape sequences as described in chapter
4344                        "<xref target="character_set">Character Set and Escape Sequences</xref>"),
4345                      &lt;instrument_index&gt; the index (integer value) of the instrument                      &lt;instrument_index&gt; the index (integer value) of the instrument
4346                      within the given file, &lt;volume_value&gt; reflects the master                      within the given file, &lt;volume_value&gt; reflects the master
4347                      volume of the instrument as optionally dotted number (where a                      volume of the instrument as optionally dotted number (where a
# Line 4744  Schoenebeck'> Line 4760  Schoenebeck'>
4760              <section title="Managing Instruments Database" anchor="Managing Instruments Database">              <section title="Managing Instruments Database" anchor="Managing Instruments Database">
4761                  <t>The following commands describe how to use and manage                  <t>The following commands describe how to use and manage
4762                  the instruments database.</t>                  the instruments database.</t>
4763                    <t>Notice:</t>
4764                        <t>
4765                            <list>
4766                                <t>All command arguments representing a path or
4767                                instrument/directory name support escape sequences as described in chapter
4768                                "<xref target="character_set">Character Set and Escape Sequences</xref>".
4769                                </t>
4770                                <t>All occurrences of a forward slash in instrument and directory
4771                                   names are escaped with its hex (\x2f) or octal (\057) escape sequence.
4772                                </t>
4773                            </list>
4774                        </t>
4775    
4776                  <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">                  <section title="Creating a new instrument directory" anchor="ADD DB_INSTRUMENT_DIRECTORY">
4777                      <t>The front-end can add a new instrument directory to the                      <t>The front-end can add a new instrument directory to the
# Line 4921  Schoenebeck'> Line 4949  Schoenebeck'>
4949                                  <list>                                  <list>
4950                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
4951                                          <list>                                          <list>
4952                                              <t>A brief description of the directory content</t>                                              <t>A brief description of the directory content.
4953                                                Note that the character string may contain
4954                                                <xref target="character_set">escape sequences</xref>.</t>
4955                                          </list>                                          </list>
4956                                      </t>                                      </t>
4957                                      <t>CREATED -                                      <t>CREATED -
# Line 5085  Schoenebeck'> Line 5115  Schoenebeck'>
5115                          </list>                          </list>
5116                      </t>                      </t>
5117                      <t>Where &lt;dir&gt; is the absolute path name of the directory and                      <t>Where &lt;dir&gt; is the absolute path name of the directory and
5118                      &lt;desc&gt; is the new description for the directory.</t>                      &lt;desc&gt; is the new description for the directory
5119                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5120                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5121    
5122                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5123                      <t>                      <t>
# Line 5130  Schoenebeck'> Line 5162  Schoenebeck'>
5162                        <t>NAME='&lt;search-string&gt;'                        <t>NAME='&lt;search-string&gt;'
5163                            <list>                            <list>
5164                                <t>Restricts the search to directories, which names                                <t>Restricts the search to directories, which names
5165                                satisfy the supplied search string.</t>                                satisfy the supplied search string (encapsulated into apostrophes,
5166                                  supporting escape sequences as described in chapter
5167                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5168                            </list>                            </list>
5169                        </t>                        </t>
5170    
# Line 5161  Schoenebeck'> Line 5195  Schoenebeck'>
5195                        <t>DESCRIPTION='&lt;search-string&gt;'                        <t>DESCRIPTION='&lt;search-string&gt;'
5196                            <list>                            <list>
5197                                <t>Restricts the search to directories with description                                <t>Restricts the search to directories with description
5198                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string
5199                                  (encapsulated into apostrophes, supporting escape
5200                                  sequences as described in chapter
5201                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5202                            </list>                            </list>
5203                        </t>                        </t>
5204                      </t>                      </t>
# Line 5202  Schoenebeck'> Line 5239  Schoenebeck'>
5239                      to the instruments database by sending the following command:</t>                      to the instruments database by sending the following command:</t>
5240                      <t>                      <t>
5241                          <list>                          <list>
5242                              <t>ADD DB_INSTRUMENTS [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>                              <t>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]</t>
5243                          </list>                          </list>
5244                      </t>                      </t>
5245                      <t>Where &lt;db_dir&gt; is the absolute path name of a directory                      <t>Where &lt;db_dir&gt; is the absolute path name of a directory
# Line 5220  Schoenebeck'> Line 5257  Schoenebeck'>
5257                      scanning will be done and has exactly the following possibilities:</t>                      scanning will be done and has exactly the following possibilities:</t>
5258                      <t>                      <t>
5259                          <list>                          <list>
5260                                <t>"RECURSIVE" -
5261                                    <list>
5262                                        <t>All instruments will be processed, including those
5263                                        in the subdirectories, and the respective subdirectory
5264                                        tree structure will be recreated in the instruments
5265                                        database</t>
5266                                    </list>
5267                                </t>
5268                              <t>"NON_RECURSIVE" -                              <t>"NON_RECURSIVE" -
5269                                  <list>                                  <list>
5270                                      <t>Only the instruments in the specified directory                                      <t>Only the instruments in the specified directory
# Line 5236  Schoenebeck'> Line 5281  Schoenebeck'>
5281                                      the specified database directory.</t>                                      the specified database directory.</t>
5282                                  </list>                                  </list>
5283                              </t>                              </t>
                             <t>not supplied -  
                                 <list>  
                                     <t>The subdirectory tree structure will be recreated  
                                     in the instruments database and all instruments will be  
                                     processed and added to the respective subdirectory  
                                     in the instruments database.</t>  
                                 </list>  
                             </t>  
5284                          </list>                          </list>
5285                      </t>                      </t>
5286    
5287                     <t>The difference between regular and NON_MODAL versions of the command
5288                        is that the regular command returns when the scanning is finished
5289                        while NON_MODAL version returns immediately and a background process is launched.
5290                        The <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5291                        command can be used to monitor the scanning progress.</t>
5292    
5293                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5294                      <t>                      <t>
5295                          <list>                          <list>
5296                              <t>"OK" -                              <t>"OK" -
5297                                  <list>                                  <list>
5298                                      <t>on success</t>                                      <t>on success when NON_MODAL is not supplied</t>
5299                                    </list>
5300                                </t>
5301                                <t>"OK[&lt;job-id&gt;]" -
5302                                    <list>
5303                                        <t>on success when NON_MODAL is supplied, where &lt;job-id&gt;
5304                                        is a numerical ID used to obtain status information about the job progress.
5305                                        See <xref target="GET DB_INSTRUMENTS_JOB INFO">GET DB_INSTRUMENTS_JOB INFO</xref>
5306                                        </t>
5307                                  </list>                                  </list>
5308                              </t>                              </t>
5309                              <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -                              <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
# Line 5408  Schoenebeck'> Line 5459  Schoenebeck'>
5459                                  <list>                                  <list>
5460                                      <t>INSTRUMENT_FILE -                                      <t>INSTRUMENT_FILE -
5461                                          <list>                                          <list>
5462                                              <t>File name of the instrument.</t>                                              <t>File name of the instrument.
5463                                                Note that the character string may contain
5464                                                <xref target="character_set">escape sequences</xref>.</t>
5465                                          </list>                                          </list>
5466                                      </t>                                      </t>
5467                                      <t>INSTRUMENT_NR -                                      <t>INSTRUMENT_NR -
# Line 5447  Schoenebeck'> Line 5500  Schoenebeck'>
5500                                      </t>                                      </t>
5501                                      <t>DESCRIPTION -                                      <t>DESCRIPTION -
5502                                          <list>                                          <list>
5503                                              <t>A brief description of the instrument</t>                                              <t>A brief description of the instrument.
5504                                                Note that the character string may contain
5505                                                <xref target="character_set">escape sequences</xref>.</t>
5506                                          </list>                                          </list>
5507                                      </t>                                      </t>
5508                                      <t>IS_DRUM -                                      <t>IS_DRUM -
# Line 5458  Schoenebeck'> Line 5513  Schoenebeck'>
5513                                      </t>                                      </t>
5514                                      <t>PRODUCT -                                      <t>PRODUCT -
5515                                          <list>                                          <list>
5516                                              <t>The product title of the instrument</t>                                              <t>The product title of the instrument.
5517                                                Note that the character string may contain
5518                                                <xref target="character_set">escape sequences</xref>.</t>
5519                                          </list>                                          </list>
5520                                      </t>                                      </t>
5521                                      <t>ARTISTS -                                      <t>ARTISTS -
5522                                          <list>                                          <list>
5523                                              <t>Lists the artist names</t>                                              <t>Lists the artist names.
5524                                                Note that the character string may contain
5525                                                <xref target="character_set">escape sequences</xref>.</t>
5526                                          </list>                                          </list>
5527                                      </t>                                      </t>
5528                                      <t>KEYWORDS -                                      <t>KEYWORDS -
5529                                          <list>                                          <list>
5530                                              <t>Provides a list of keywords that refer to the instrument.                                              <t>Provides a list of keywords that refer to the instrument.
5531                                              Keywords are separated with semicolon and blank.</t>                                              Keywords are separated with semicolon and blank.
5532                                                Note that the character string may contain
5533                                                <xref target="character_set">escape sequences</xref>.</t>
5534                                          </list>                                          </list>
5535                                      </t>                                      </t>
5536                                  </list>                                  </list>
# Line 5626  Schoenebeck'> Line 5687  Schoenebeck'>
5687                          </list>                          </list>
5688                      </t>                      </t>
5689                      <t>Where &lt;instr&gt; is the absolute path name of the instrument and                      <t>Where &lt;instr&gt; is the absolute path name of the instrument and
5690                      &lt;desc&gt; is the new description for the instrument.</t>                      &lt;desc&gt; is the new description for the instrument
5691                        (encapsulated into apostrophes, supporting escape sequences as described in chapter
5692                        "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5693    
5694                      <t>Possible Answers:</t>                      <t>Possible Answers:</t>
5695                      <t>                      <t>
# Line 5671  Schoenebeck'> Line 5734  Schoenebeck'>
5734                        <t>NAME='&lt;search-string&gt;'                        <t>NAME='&lt;search-string&gt;'
5735                            <list>                            <list>
5736                                <t>Restricts the search to instruments, which names                                <t>Restricts the search to instruments, which names
5737                                satisfy the supplied search string.</t>                                satisfy the supplied search string (encapsulated into apostrophes,
5738                                  supporting escape sequences as described in chapter
5739                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5740                            </list>                            </list>
5741                        </t>                        </t>
5742    
5743                        <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]                        <t>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
5744                            <list>                            <list>
5745                                <t>Restricts the search to instruments, which                                <t>Restricts the search to instruments, which
5746                                size is in the specified range. If &lt;min&gt; is omitted,                                size is in the specified range. If &lt;min&gt; is omitted,
5747                                the search results are restricted to instruments with size less then                                the search results are restricted to instruments with size less then
5748                                or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the                                or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
# Line 5713  Schoenebeck'> Line 5778  Schoenebeck'>
5778                        <t>DESCRIPTION='&lt;search-string&gt;'                        <t>DESCRIPTION='&lt;search-string&gt;'
5779                            <list>                            <list>
5780                                <t>Restricts the search to instruments with description                                <t>Restricts the search to instruments with description
5781                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5782                                  supporting escape sequences as described in chapter
5783                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5784                            </list>                            </list>
5785                        </t>                        </t>
5786    
5787                        <t>PRODUCT='&lt;search-string&gt;'                        <t>PRODUCT='&lt;search-string&gt;'
5788                            <list>                            <list>
5789                                <t>Restricts the search to instruments with product info                                <t>Restricts the search to instruments with product info
5790                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5791                                  supporting escape sequences as described in chapter
5792                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5793                            </list>                            </list>
5794                        </t>                        </t>
5795    
5796                        <t>ARTISTS='&lt;search-string&gt;'                        <t>ARTISTS='&lt;search-string&gt;'
5797                            <list>                            <list>
5798                                <t>Restricts the search to instruments with artists info                                <t>Restricts the search to instruments with artists info
5799                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5800                                  supporting escape sequences as described in chapter
5801                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5802                            </list>                            </list>
5803                        </t>                        </t>
5804    
5805                        <t>KEYWORDS='&lt;search-string&gt;'                        <t>KEYWORDS='&lt;search-string&gt;'
5806                            <list>                            <list>
5807                                <t>Restricts the search to instruments with keyword list                                <t>Restricts the search to instruments with keyword list
5808                                that satisfies the supplied search string.</t>                                that satisfies the supplied search string (encapsulated into apostrophes,
5809                                  supporting escape sequences as described in chapter
5810                                  "<xref target="character_set">Character Set and Escape Sequences</xref>").</t>
5811                            </list>                            </list>
5812                        </t>                        </t>
5813    
5814                        <t>IS_DRUM=true | false                        <t>IS_DRUM=true | false
5815                            <list>                            <list>
5816                                <t>Either true or false. Restricts the search to                                <t>Either true or false. Restricts the search to
5817                                drum kits or chromatic instruments.</t>                                drum kits or chromatic instruments.</t>
5818                            </list>                            </list>
5819                        </t>                        </t>
# Line 5784  Schoenebeck'> Line 5857  Schoenebeck'>
5857                      </t>                      </t>
5858                  </section>                  </section>
5859    
5860                    <section title="Getting job status information" anchor="GET DB_INSTRUMENTS_JOB INFO">
5861                        <t>The front-end can ask for the current status of a
5862                        particular database instruments job by sending the following command:</t>
5863                        <t>
5864                            <list>
5865                                <t>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;</t>
5866                            </list>
5867                        </t>
5868                        <t>Where &lt;job-id&gt; should be replaced by the numerical ID
5869                        of the job the front-end is interested in.</t>
5870    
5871                        <t>Possible Answers:</t>
5872                        <t>
5873                            <list>
5874                                <t>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
5875                                Each answer line begins with the settings category name
5876                                followed by a colon and then a space character &lt;SP&gt; and finally
5877                                the info character string to that setting category. At the
5878                                moment the following categories are defined:</t>
5879    
5880                                <t>
5881                                    <list>
5882                                        <t>FILES_TOTAL -
5883                                            <list>
5884                                                <t>The total number of files scheduled for scanning</t>
5885                                            </list>
5886                                        </t>
5887                                        <t>FILES_SCANNED -
5888                                            <list>
5889                                                <t>The current number of scanned files</t>
5890                                            </list>
5891                                        </t>
5892                                        <t>SCANNING -
5893                                            <list>
5894                                                <t>The absolute path name of the file which is currently
5895                                                being scanned</t>
5896                                            </list>
5897                                        </t>
5898                                        <t>STATUS -
5899                                            <list>
5900                                                <t>An integer value between 0 and 100 indicating the
5901                                                scanning progress percentage of the file which is
5902                                                currently being scanned</t>
5903                                            </list>
5904                                        </t>
5905                                    </list>
5906                                </t>
5907                            </list>
5908                        </t>
5909                        <t>The mentioned fields above don't have to be in particular order.</t>
5910    
5911                        <t>Example:</t>
5912                        <t>
5913                            <list>
5914                                <t>C: "GET DB_INSTRUMENTS_JOB INFO 2"</t>
5915                                <t>S: "FILES_TOTAL: 12"</t>
5916                                <t>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"</t>
5917                                <t>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"</t>
5918                                <t>&nbsp;&nbsp;&nbsp;"STATUS: 42"</t>
5919                                <t>&nbsp;&nbsp;&nbsp;"."</t>
5920                            </list>
5921                        </t>
5922                    </section>
5923    
5924                    <section title="Formatting the instruments database" anchor="FORMAT INSTRUMENTS_DB">
5925                        <t>The front-end can remove all instruments and directories and re-create
5926                        the instruments database structure (e.g., in case of a database corruption)
5927                        by sending the following command:</t>
5928                        <t>
5929                            <list>
5930                                <t>FORMAT INSTRUMENTS_DB</t>
5931                            </list>
5932                        </t>
5933                        
5934                        <t>Possible Answers:</t>
5935                        <t>
5936                            <list>
5937                                <t>"OK" -
5938                                    <list>
5939                                        <t>on success</t>
5940                                    </list>
5941                                </t>
5942                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
5943                                    <list>
5944                                        <t>If the formatting of the instruments database
5945                                        failed.</t>
5946                                    </list>
5947                                </t>
5948                            </list>
5949                        </t>
5950                    </section>
5951    
5952              </section>              </section>
5953    
5954    
5955    
5956                <section title="Editing Instruments" anchor="editing_instruments">
5957                    <t>The sampler allows to edit instruments while playing with the
5958                    sampler by spawning an external (3rd party) instrument editor
5959                    application for a given instrument. The 3rd party instrument
5960                    editor applications have to place a respective plugin DLL file
5961                    into the sampler's plugins directory. The sampler will
5962                    automatically try to load all plugin DLLs in that directory on
5963                    startup and only on startup!</t>
5964                    <t>At the moment there is only one command for this feature set,
5965                    but this will most probably change in future.</t>
5966    
5967                    <section title="Opening an appropriate instrument editor application" anchor="EDIT INSTRUMENT">
5968                        <t>The front-end can request to open an appropriate instrument
5969                        editor application by sending the following command:</t>
5970                        <t>
5971                            <list>
5972                                <t>EDIT INSTRUMENT &lt;sampler-channel&gt;</t>
5973                            </list>
5974                        </t>
5975                        <t>Where &lt;sampler-channel&gt; should be replaced by the
5976                        number of the sampler channel as given by the
5977                        <xref target="ADD CHANNEL">"ADD CHANNEL"</xref>
5978                        or <xref target="LIST CHANNELS">"LIST CHANNELS"</xref>
5979                        command.</t>
5980    
5981                        <t>The sampler will try to ask all registered instrument
5982                        editors (or to be more specific: their sampler plugins)
5983                        whether they are capable to handle the instrument on the
5984                        given sampler channel. The sampler will simply use the first
5985                        instrument editor application which replied with a positive
5986                        answer and spawn that instrument editor application within
5987                        the sampler's process and provide that application access
5988                        to the instrument's data structures, so both applications
5989                        can share and access the same instruments data at the same
5990                        time, thus allowing to immediately hear changes with the
5991                        sampler made by the instrument editor.</t>
5992    
5993                        <t>Note: consequently instrument editors are always spawned
5994                        locally on the same machine where the sampler is running
5995                        on!</t>
5996    
5997                        <t>Possible Answers:</t>
5998                        <t>
5999                            <list>
6000                                <t>"OK" -
6001                                    <list>
6002                                        <t>when an appropriate instrument editor was
6003                                        launched</t>
6004                                    </list>
6005                                </t>
6006                                <t>"WRN:&lt;warning-code&gt;:&lt;warning-message&gt;" -
6007                                    <list>
6008                                        <t>when an appropriate instrument editor was
6009                                        launched, but there are noteworthy issues</t>
6010                                    </list>
6011                                </t>
6012                                <t>"ERR:&lt;error-code&gt;:&lt;error-message&gt;" -
6013                                    <list>
6014                                        <t>when an appropriate instrument editor
6015                                        could not be launched</t>
6016                                    </list>
6017                                </t>
6018                            </list>
6019                        </t>
6020    
6021                        <t>Examples:</t>
6022                        <t>
6023                            <list>
6024                                <t>C: "EDIT INSTRUMENT 0"</t>
6025                                <t>S: "OK"</t>
6026                            </list>
6027                        </t>
6028                    </section>
6029                </section>
6030          </section>          </section>
6031    
6032    
# Line 5871  Schoenebeck'> Line 6112  Schoenebeck'>
6112                  </t>                  </t>
6113                  <t>/ COPY SP copy_instruction                  <t>/ COPY SP copy_instruction
6114                  </t>                  </t>
6115                    <t>/ EDIT SP edit_instruction
6116                    </t>
6117                    <t>/ FORMAT SP format_instruction
6118                    </t>
6119                  <t>/ RESET                  <t>/ RESET
6120                  </t>                  </t>
6121                  <t>/ QUIT                  <t>/ QUIT
# Line 5881  Schoenebeck'> Line 6126  Schoenebeck'>
6126          <list>          <list>
6127                  <t>CHANNEL                  <t>CHANNEL
6128                  </t>                  </t>
6129                  <t>/ DB_INSTRUMENT_DIRECTORY SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6130                    </t>
6131                    <t>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP db_path SP filename
6132                  </t>                  </t>
6133                  <t>/ DB_INSTRUMENTS SP FLAT SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP scan_mode SP db_path SP filename
6134                  </t>                  </t>
6135                  <t>/ DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename
6136                  </t>                  </t>
6137                  <t>/ DB_INSTRUMENTS SP pathname SP pathname                  <t>/ DB_INSTRUMENTS SP NON_MODAL SP db_path SP filename SP instrument_index
6138                  </t>                  </t>
6139                  <t>/ DB_INSTRUMENTS SP pathname SP pathname SP instrument_index                  <t>/ DB_INSTRUMENTS SP db_path SP filename
6140                    </t>
6141                    <t>/ DB_INSTRUMENTS SP db_path SP filename SP instrument_index
6142                  </t>                  </t>
6143                  <t>/ MIDI_INSTRUMENT_MAP                  <t>/ MIDI_INSTRUMENT_MAP
6144                  </t>                  </t>
# Line 5937  Schoenebeck'> Line 6186  Schoenebeck'>
6186                  </t>                  </t>
6187                  <t>/ DB_INSTRUMENT_INFO                  <t>/ DB_INSTRUMENT_INFO
6188                  </t>                  </t>
6189                    <t>/ DB_INSTRUMENTS_JOB_INFO
6190                    </t>
6191                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6192                  </t>                  </t>
6193                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
# Line 5985  Schoenebeck'> Line 6236  Schoenebeck'>
6236                  </t>                  </t>
6237                  <t>/ DB_INSTRUMENT_INFO                  <t>/ DB_INSTRUMENT_INFO
6238                  </t>                  </t>
6239                    <t>/ DB_INSTRUMENTS_JOB_INFO
6240                    </t>
6241                  <t>/ MISCELLANEOUS                  <t>/ MISCELLANEOUS
6242                  </t>                  </t>
6243                  <t>/ TOTAL_VOICE_COUNT                  <t>/ TOTAL_VOICE_COUNT
# Line 6019  Schoenebeck'> Line 6272  Schoenebeck'>
6272                  </t>                  </t>
6273                  <t>/ MIDI_INSTRUMENT_MAP SP ALL                  <t>/ MIDI_INSTRUMENT_MAP SP ALL
6274                  </t>                  </t>
6275                  <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP FORCE SP db_path
6276                  </t>                  </t>
6277                  <t>/ DB_INSTRUMENT_DIRECTORY SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP db_path
6278                  </t>                  </t>
6279                  <t>/ DB_INSTRUMENT SP pathname                  <t>/ DB_INSTRUMENT SP db_path
6280                  </t>                  </t>
6281          </list>          </list>
6282  </t>  </t>
# Line 6095  Schoenebeck'> Line 6348  Schoenebeck'>
6348                  </t>                  </t>
6349                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id                  <t>/ FX_SEND SP INFO SP sampler_channel SP fx_send_id
6350                  </t>                  </t>
6351                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6352                  </t>                  </t>
6353                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6354                  </t>                  </t>
6355                  <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORY SP INFO SP db_path
6356                  </t>                  </t>
6357                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6358                  </t>                  </t>
6359                  <t>/ DB_INSTRUMENTS SP pathname                  <t>/ DB_INSTRUMENTS SP db_path
6360                  </t>                  </t>
6361                  <t>/ DB_INSTRUMENT SP INFO SP pathname                  <t>/ DB_INSTRUMENT SP INFO SP db_path
6362                    </t>
6363                    <t>/ DB_INSTRUMENTS_JOB SP INFO SP number
6364                  </t>                  </t>
6365                  <t>/ VOLUME                  <t>/ VOLUME
6366                  </t>                  </t>
# Line 6119  Schoenebeck'> Line 6374  Schoenebeck'>
6374                  </t>                  </t>
6375                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_DEVICE_PARAMETER SP number SP string '=' param_val_list
6376                  </t>                  </t>
6377                    <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' NONE
6378                    </t>
6379                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list                  <t>/ MIDI_INPUT_PORT_PARAMETER SP number SP number SP string '=' param_val_list
6380                  </t>                  </t>
6381                  <t>/ CHANNEL SP set_chan_instruction                  <t>/ CHANNEL SP set_chan_instruction
# Line 6133  Schoenebeck'> Line 6390  Schoenebeck'>
6390                  </t>                  </t>
6391                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value                  <t>/ FX_SEND SP LEVEL SP sampler_channel SP fx_send_id SP volume_value
6392                  </t>                  </t>
6393                  <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP pathname SP dirname                  <t>/ DB_INSTRUMENT_DIRECTORY SP NAME SP db_path SP stringval_escaped
6394                  </t>                  </t>
6395                  <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP pathname SP stringval                  <t>/ DB_INSTRUMENT_DIRECTORY SP DESCRIPTION SP db_path SP stringval_escaped
6396                  </t>                  </t>
6397                  <t>/ DB_INSTRUMENT SP NAME SP pathname SP dirname                  <t>/ DB_INSTRUMENT SP NAME SP db_path SP stringval_escaped
6398                  </t>                  </t>
6399                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP pathname SP stringval                  <t>/ DB_INSTRUMENT SP DESCRIPTION SP db_path SP stringval_escaped
6400                  </t>                  </t>
6401                  <t>/ ECHO SP boolean                  <t>/ ECHO SP boolean
6402                  </t>                  </t>
# Line 6179  Schoenebeck'> Line 6436  Schoenebeck'>
6436  </t>  </t>
6437  <t>find_instruction =  <t>find_instruction =
6438          <list>          <list>
6439                  <t>DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP query_val_list                  <t>DB_INSTRUMENTS SP NON_RECURSIVE SP db_path SP query_val_list
6440                  </t>                  </t>
6441                  <t>/ DB_INSTRUMENTS SP pathname SP query_val_list                  <t>/ DB_INSTRUMENTS SP db_path SP query_val_list
6442                  </t>                  </t>
6443                  <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP pathname SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP NON_RECURSIVE SP db_path SP query_val_list
6444                  </t>                  </t>
6445                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname SP query_val_list                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path SP query_val_list
6446                  </t>                  </t>
6447          </list>          </list>
6448  </t>  </t>
6449  <t>move_instruction =  <t>move_instruction =
6450          <list>          <list>
6451                  <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname                  <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6452                  </t>                  </t>
6453                  <t>/ DB_INSTRUMENT SP pathname SP pathname                  <t>/ DB_INSTRUMENT SP db_path SP db_path
6454                  </t>                  </t>
6455          </list>          </list>
6456  </t>  </t>
6457  <t>copy_instruction =  <t>copy_instruction =
6458          <list>          <list>
6459                  <t>DB_INSTRUMENT_DIRECTORY SP pathname SP pathname                  <t>DB_INSTRUMENT_DIRECTORY SP db_path SP db_path
6460                  </t>                  </t>
6461                  <t>/ DB_INSTRUMENT SP pathname SP pathname                  <t>/ DB_INSTRUMENT SP db_path SP db_path
6462                  </t>                  </t>
6463          </list>          </list>
6464  </t>  </t>
# Line 6255  Schoenebeck'> Line 6512  Schoenebeck'>
6512                  </t>                  </t>
6513          </list>          </list>
6514  </t>  </t>
6515    <t>edit_instruction =
6516            <list>
6517                    <t>INSTRUMENT SP sampler_channel
6518                    </t>
6519            </list>
6520    </t>
6521    <t>format_instruction =
6522            <list>
6523                    <t>INSTRUMENTS_DB
6524                    </t>
6525            </list>
6526    </t>
6527  <t>modal_arg =  <t>modal_arg =
6528          <list>          <list>
6529                  <t>/* epsilon (empty argument) */                  <t>/* epsilon (empty argument) */
# Line 6301  Schoenebeck'> Line 6570  Schoenebeck'>
6570                  </t>                  </t>
6571                  <t>/ FX_SENDS SP sampler_channel                  <t>/ FX_SENDS SP sampler_channel
6572                  </t>                  </t>
6573                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP RECURSIVE SP db_path
6574                  </t>                  </t>
6575                  <t>/ DB_INSTRUMENT_DIRECTORIES SP pathname                  <t>/ DB_INSTRUMENT_DIRECTORIES SP db_path
6576                  </t>                  </t>
6577                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP pathname                  <t>/ DB_INSTRUMENTS SP RECURSIVE SP db_path
6578                  </t>                  </t>
6579                  <t>/ DB_INSTRUMENTS SP pathname                  <t>/ DB_INSTRUMENTS SP db_path
6580                  </t>                  </t>
6581          </list>          </list>
6582  </t>  </t>
# Line 6429  Schoenebeck'> Line 6698  Schoenebeck'>
6698                  </t>                  </t>
6699          </list>          </list>
6700  </t>  </t>
6701  <t>pathname =  <t>filename =
         <list>  
                 <t>stringval  
                 </t>  
         </list>  
 </t>  
 <t>dirname =  
6702          <list>          <list>
6703                  <t>stringval                  <t>path
6704                  </t>                  </t>
6705          </list>          </list>
6706  </t>  </t>
6707  <t>filename =  <t>db_path =
6708          <list>          <list>
6709                  <t>stringval                  <t>path
6710                  </t>                  </t>
6711          </list>          </list>
6712  </t>  </t>
# Line 6495  Schoenebeck'> Line 6758  Schoenebeck'>
6758  </t>  </t>
6759  <t>query_val =  <t>query_val =
6760          <list>          <list>
6761                  <t>string                  <t>textval_escaped
6762                  </t>                  </t>
6763                  <t>/ stringval                  <t>/ stringval_escaped
6764                    </t>
6765            </list>
6766    </t>
6767    <t>scan_mode =
6768            <list>
6769                    <t>RECURSIVE
6770                    </t>
6771                    <t>/ NON_RECURSIVE
6772                    </t>
6773                    <t>/ FLAT
6774                  </t>                  </t>
6775          </list>          </list>
6776  </t>  </t>
6777    
6778              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->              <!-- GRAMMAR_BNF_END - do NOT delete or modify this line !!! -->
6779    
6780                <section title="Character Set and Escape Sequences" anchor="character_set">
6781                    <t>Older versions of this protocol up to and including v1.1 only
6782                    supported the standard ASCII character set (ASCII code 0 - 127)
6783                    <xref target="RFC20"/>, all younger versions of this protocol
6784                    however support the Extended ASCII character set (ASCII code
6785                    0 - 255). The same group of younger protocols also support
6786                    escape sequences, but only for certain, explicitly declared
6787                    parts of the protocol. The supported escape sequences are
6788                    defined as follows:</t>
6789                    <texttable>
6790                        <ttcol>ASCII Character Sequence</ttcol>
6791                        <ttcol>Translated into (Name)</ttcol>
6792                        <c>\n</c> <c>new line</c>
6793                        <c>\r</c> <c>carriage return</c>
6794                        <c>\f</c> <c>form feed</c>
6795                        <c>\t</c> <c>horizontal tab</c>
6796                        <c>\v</c> <c>vertical tab</c>
6797                        <c>\'</c> <c>apostrophe</c>
6798                        <c>\"</c> <c>quotation mark</c>
6799                        <c>\\</c> <c>backslash</c>
6800                        <c>\OOO</c> <c>three digit octal ASCII code of the character</c>
6801                        <c>\xHH</c> <c>two digit hex ASCII code of the character</c>
6802                    </texttable>
6803                    <t>Notice: due to the transition of certain parts of the
6804                    protocol which now support escape sequences, a slight backward
6805                    incompatibility to protocols version v1.1 and younger has been
6806                    introduced. The only difference is that in parts of the protocol
6807                    where escape characters are now supported, a backslash characters
6808                    MUST be escaped as well (that is as double backslash), whereas
6809                    in the old versions a single backslash was sufficient.</t>
6810                </section>
6811          </section>          </section>
6812    
6813          <section title="Events" anchor="events">          <section title="Events" anchor="events">
# Line 6688  Schoenebeck'> Line 6993  Schoenebeck'>
6993              </section>              </section>
6994    
6995              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">              <section title="Number of effect sends changed" anchor="SUBSCRIBE FX_SEND_COUNT">
6996                  <t>Client may want to be notified when the number of effect sends on                  <t>Client may want to be notified when the number of effect sends on
6997                  a particular sampler channel is changed by issuing the following command:</t>                  a particular sampler channel is changed by issuing the following command:</t>
6998                  <t>                  <t>
6999                      <list>                      <list>
# Line 6948  Schoenebeck'> Line 7253  Schoenebeck'>
7253                  the new name of the instrument, encapsulated into apostrophes.</t>                  the new name of the instrument, encapsulated into apostrophes.</t>
7254              </section>              </section>
7255    
7256                <section title="Database job status information changed" anchor="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">
7257                    <t>Client may want to be notified when the status of particular database
7258                    instruments job is changed by issuing the following command:</t>
7259                    <t>
7260                        <list>
7261                            <t>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO</t>
7262                        </list>
7263                    </t>
7264                    <t>Server will start sending the following notification messages:</t>
7265                    <t>
7266                        <list>
7267                            <t>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"</t>
7268                        </list>
7269                    </t>
7270                    <t>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
7271                    which status is changed. The front-end will have to send the respective
7272                    command to actually get the status info. Because these messages
7273                    will be triggered by LSCP commands issued by other clients rather than real
7274                    time events happening on the server, it is believed that an empty notification
7275                    message is sufficient here.</t>
7276                </section>
7277    
7278              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">              <section title="Miscellaneous and debugging events" anchor="SUBSCRIBE MISCELLANEOUS">
7279                  <t>Client may want to be notified of miscellaneous and debugging events occurring at                  <t>Client may want to be notified of miscellaneous and debugging events occurring at
7280                  the server by issuing the following command:</t>                  the server by issuing the following command:</t>
# Line 7026  Schoenebeck'> Line 7353  Schoenebeck'>
7353                  </front>                  </front>
7354                  <seriesInfo name="RFC" value="2234" />                  <seriesInfo name="RFC" value="2234" />
7355              </reference>              </reference>
7356                <reference anchor="RFC20">
7357                    <front>
7358                        <title>ASCII format for Network Interchange</title>
7359                        <author>
7360                            <organization>UCLA</organization>
7361                        </author>
7362                        <date year="1969"></date>
7363                    </front>
7364                    <seriesInfo name="RFC" value="20" />
7365                </reference>
7366           </references>           </references>
7367      </back>      </back>
7368    
Legend:
Removed from v.1188  
changed lines
  Added in v.1362
  ViewVC Help
Powered by ViewVC