/[svn]/web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html

Diff of /web/trunk/www.linuxsampler.org/api/draft-linuxsampler-protocol.html

Parent Directory | Revision Log | View Patch Patch

-revision 1189 by iliev,
Wed May 16 14:42:04 2007 UTC
+revision 1251 by schoenebeck,
Fri Jun 22 14:24:57 2007 UTC
 Line 1
  <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
- <html lang="en"><head><title>LinuxSampler Control Protocol</title>
+ <html lang="en"><head><title>LinuxSampler Control Protocol (draft)</title>
  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
- <meta name="description" content="LinuxSampler Control Protocol">
+ <meta name="description" content="LinuxSampler Control Protocol (draft)">
  <meta name="keywords" content="LSCP">
  <meta name="generator" content="xml2rfc v1.32 (http://xml.resource.org/)">
  <style type='text/css'><!--
 Line 145
  <tr><td class="header">LinuxSampler Developers</td><td class="header">C. Schoenebeck</td></tr>
  <tr><td class="header">Internet-Draft</td><td class="header">Interessengemeinschaft Software</td></tr>
  <tr><td class="header">Intended status: Standards Track</td><td class="header">Engineering e. V.</td></tr>
- <tr><td class="header">Expires: November 17, 2007</td><td class="header">May 16, 2007</td></tr>
+ <tr><td class="header">Expires: December 24, 2007</td><td class="header">June 22, 2007</td></tr>
  </table></td></tr></table>
- <h1><br />LinuxSampler Control Protocol<br />LSCP 1.2</h1>
+ <h1><br />LinuxSampler Control Protocol (draft)<br />LSCP 1.2cvs</h1>
  <h3>Status of this Memo</h3>
  <p>
 Line 173 
 The list of current Internet-Drafts can
  The list of Internet-Draft Shadow Directories can be accessed at
  <a href='http://www.ietf.org/shadow.html'>http://www.ietf.org/shadow.html</a>.</p>
  <p>
- This Internet-Draft will expire on November 17, 2007.</p>
+ This Internet-Draft will expire on December 24, 2007.</p>
  <h3>Copyright Notice</h3>
  <p>
 Line 430 
 Copying instruments<br />
  Changing the description of instrument<br />
  &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#FIND DB_INSTRUMENTS">6.8.20.</a>&nbsp;
  Finding instruments<br />
+ &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="#GET DB_INSTRUMENTS_JOB INFO">6.8.21.</a>&nbsp;
+ Getting job status information<br />
  <a href="#command_syntax">7.</a>&nbsp;
  Command Syntax<br />
+ &nbsp;&nbsp;&nbsp;&nbsp;<a href="#character_set">7.1.</a>&nbsp;
+ Character Set and Escape Sequences<br />
  <a href="#events">8.</a>&nbsp;
  Events<br />
  &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE AUDIO_OUTPUT_DEVICE_COUNT">8.1.</a>&nbsp;
-Line 476 
 Database instrument directory informatio
+Line 480 
 Database instrument directory informatio
  Number of database instruments changed<br />
  &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENT_INFO">8.21.</a>&nbsp;
  Database instrument information changed<br />
- &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.22.</a>&nbsp;
+ &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE DB_INSTRUMENTS_JOB_INFO">8.22.</a>&nbsp;
+ Database job status information changed<br />
+ &nbsp;&nbsp;&nbsp;&nbsp;<a href="#SUBSCRIBE MISCELLANEOUS">8.23.</a>&nbsp;
  Miscellaneous and debugging events<br />
  <a href="#anchor14">9.</a>&nbsp;
  Security Considerations<br />
-Line 508 
 Requirements notation</h3>
+Line 514 
 Requirements notation</h3>
              (front-end) and server (LinuxSampler) respectively. Lines in
              examples must be interpreted as every line being CRLF
              terminated (carriage return character followed by line feed
-             character as defined in the ASCII standard), thus the following
+             character as defined in the ASCII standard <a class='info' href='#RFC20'>[RFC20]<span> (</span><span class='info'>UCLA, &ldquo;ASCII format for Network Interchange,&rdquo; 1969.</span><span>)</span></a>),
-             example:
+             thus the following example:
  </p>
  <p>
                  </p>
-Line 3371 
 Loading an instrument</h3>
+Line 3377 
 Loading an instrument</h3>
                      number of the sampler channel the instrument should be assigned to.
                      Each sampler channel can only have one instrument.
  </p>
+ <p>Notice: since LSCP 1.2 the &lt;filename&gt; argument supports
+                     escape characters for special characters (see chapter
+                     "<a class='info' href='#character_set'>Character Set and Escape Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>"
+                     for details) and accordingly backslash characters in the filename
+                     MUST now be escaped as well!
+ </p>
  <p>The difference between regular and NON_MODAL versions of the command
                      is that the regular command returns OK only after the instrument has been
                      fully loaded and the channel is ready to be used while NON_MODAL version
-Line 6643 
 Create or replace a MIDI instrument map
+Line 6655 
 Create or replace a MIDI instrument map
                      index, &lt;engine_name&gt; a sampler engine name as returned by
                      the <a class='info' href='#LIST AVAILABLE_ENGINES'>"LIST AVAILABLE_ENGINES"<span> (</span><span class='info'>Getting all available engines</span><span>)</span></a>
                      command (not encapsulated into apostrophes), &lt;filename&gt; the name
-                     of the instrument's file to be deployed (encapsulated into apostrophes),
+                     of the instrument's file to be deployed (encapsulated into apostrophes,
+                     supporting escape sequences as described in chapter
+                     "<a class='info' href='#character_set'>Character Set and Escape Sequences<span> (</span><span class='info'>Character Set and Escape Sequences</span><span>)</span></a>"),
                      &lt;instrument_index&gt; the index (integer value) of the instrument
                      within the given file, &lt;volume_value&gt; reflects the master
                      volume of the instrument as optionally dotted number (where a
-Line 7916 
 Adding instruments to the instruments da
+Line 7930 
 Adding instruments to the instruments da
  <p>
                          </p>
  <blockquote class="text">
- <p>ADD DB_INSTRUMENTS [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]
+ <p>ADD DB_INSTRUMENTS [NON_MODAL] [&lt;mode&gt;] &lt;db_dir&gt; &lt;file_path&gt; [&lt;instr_index&gt;]
  </p>
  </blockquote><p>
-Line 7938 
 Adding instruments to the instruments da
+Line 7952 
 Adding instruments to the instruments da
  <p>
                          </p>
  <blockquote class="text">
+ <p>"RECURSIVE" -
+                                 </p>
+ <blockquote class="text">
+ <p>All instruments will be processed, including those
+                                     in the subdirectories, and the respective subdirectory
+                                     tree structure will be recreated in the instruments
+                                     database
+ </p>
+ </blockquote>
  <p>"NON_RECURSIVE" -
                                  </p>
  <blockquote class="text">
-Line 7960 
 Adding instruments to the instruments da
+Line 7985 
 Adding instruments to the instruments da
  </blockquote>
- <p>not supplied -
-                                 </p>
- <blockquote class="text">
- <p>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.
- </p>
- </blockquote>
  </blockquote><p>
  </p>
+ <p>The difference between regular and NON_MODAL versions of the command
+                     is that the regular command returns when the scanning is finished
+                     while NON_MODAL version returns immediately and a background process is launched.
+                     The <a class='info' href='#GET DB_INSTRUMENTS_JOB INFO'>GET DB_INSTRUMENTS_JOB INFO<span> (</span><span class='info'>Getting job status information</span><span>)</span></a>
+                     command can be used to monitor the scanning progress.
+ </p>
  <p>Possible Answers:
  </p>
  <p>
-Line 7982 
 Adding instruments to the instruments da
+Line 8002 
 Adding instruments to the instruments da
  <p>"OK" -
                                  </p>
  <blockquote class="text">
- <p>on success
+ <p>on success when NON_MODAL is not supplied
+ </p>
+ </blockquote>
+ <p>"OK[&lt;job-id&gt;]" -
+                                 </p>
+ <blockquote class="text">
+ <p>on success when NON_MODAL is supplied, where &lt;job-id&gt;
+                                     is a numerical ID used to obtain status information about the job progress.
+                                     See <a class='info' href='#GET DB_INSTRUMENTS_JOB INFO'>GET DB_INSTRUMENTS_JOB INFO<span> (</span><span class='info'>Getting job status information</span><span>)</span></a>
  </p>
  </blockquote>
-Line 8628 
 Finding instruments</h3>
+Line 8659 
 Finding instruments</h3>
  <p>SIZE=[&lt;min&gt;]..[&lt;max&gt;]
                            </p>
  <blockquote class="text">
  <p>Restricts the search to instruments, which
                                size is in the specified range. If &lt;min&gt; is omitted,
                                the search results are restricted to instruments with size less then
                                or equal to &lt;max&gt;. If &lt;max&gt; is omitted, the
-Line 8719 
 Finding instruments</h3>
+Line 8750 
 Finding instruments</h3>
  <p>IS_DRUM=true | false
                            </p>
  <blockquote class="text">
  <p>Either true or false. Restricts the search to
                                drum kits or chromatic instruments.
  </p>
  </blockquote><p>
-Line 8783 
 Finding instruments</h3>
+Line 8814 
 Finding instruments</h3>
  </blockquote><p>
  </p>
+ <a name="GET DB_INSTRUMENTS_JOB INFO"></a><br /><hr />
+ <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
+ <a name="rfc.section.6.8.21"></a><h3>6.8.21.&nbsp;
+ Getting job status information</h3>
+ <p>The front-end can ask for the current status of a
+                     particular database instruments job by sending the following command:
+ </p>
+ <p>
+                         </p>
+ <blockquote class="text">
+ <p>GET DB_INSTRUMENTS_JOB INFO &lt;job-id&gt;
+ </p>
+ </blockquote><p>
+ </p>
+ <p>Where &lt;job-id&gt; should be replaced by the numerical ID
+                     of the job the front-end is interested in.
+ </p>
+ <p>Possible Answers:
+ </p>
+ <p>
+                         </p>
+ <blockquote class="text">
+ <p>LinuxSampler will answer by sending a &lt;CRLF&gt; separated list.
+                             Each answer line begins with the settings category name
+                             followed by a colon and then a space character &lt;SP&gt; and finally
+                             the info character string to that setting category. At the
+                             moment the following categories are defined:
+ </p>
+ <p>
+                                 </p>
+ <blockquote class="text">
+ <p>FILES_TOTAL -
+                                         </p>
+ <blockquote class="text">
+ <p>The total number of files scheduled for scanning
+ </p>
+ </blockquote>
+ <p>FILES_SCANNED -
+                                         </p>
+ <blockquote class="text">
+ <p>The current number of scanned files
+ </p>
+ </blockquote>
+ <p>SCANNING -
+                                         </p>
+ <blockquote class="text">
+ <p>The absolute path name of the file which is currently
+                                             being scanned
+ </p>
+ </blockquote>
+ <p>STATUS -
+                                         </p>
+ <blockquote class="text">
+ <p>An integer value between 0 and 100 indicating the
+                                             scanning progress percentage of the file which is
+                                             currently being scanned
+ </p>
+ </blockquote>
+ </blockquote>
+ </blockquote><p>
+ </p>
+ <p>The mentioned fields above don't have to be in particular order.
+ </p>
+ <p>Example:
+ </p>
+ <p>
+                         </p>
+ <blockquote class="text">
+ <p>C: "GET DB_INSTRUMENTS_JOB INFO 2"
+ </p>
+ <p>S: "FILES_TOTAL: 12"
+ </p>
+ <p>&nbsp;&nbsp;&nbsp;"FILES_SCANNED: 7"
+ </p>
+ <p>&nbsp;&nbsp;&nbsp;"SCANNING: /home/me/gigs/Bosendorfer 290.gig"
+ </p>
+ <p>&nbsp;&nbsp;&nbsp;"STATUS: 42"
+ </p>
+ <p>&nbsp;&nbsp;&nbsp;"."
+ </p>
+ </blockquote><p>
+ </p>
  <a name="command_syntax"></a><br /><hr />
  <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
  <a name="rfc.section.7"></a><h3>7.&nbsp;
-Line 8898 
 Command Syntax</h3>
+Line 9025 
 Command Syntax</h3>
  <p>/ COPY SP copy_instruction
  </p>
+ <p>/ EDIT SP edit_instruction
+ </p>
  <p>/ RESET
  </p>
-Line 8916 
 Command Syntax</h3>
+Line 9046 
 Command Syntax</h3>
  <p>/ DB_INSTRUMENT_DIRECTORY SP pathname
  </p>
- <p>/ DB_INSTRUMENTS SP FLAT SP pathname SP pathname
+ <p>/ DB_INSTRUMENTS SP NON_MODAL SP scan_mode SP pathname SP pathname
+ </p>
+ <p>/ DB_INSTRUMENTS SP scan_mode SP pathname SP pathname
+ </p>
+ <p>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname
  </p>
- <p>/ DB_INSTRUMENTS SP NON_RECURSIVE SP pathname SP pathname
+ <p>/ DB_INSTRUMENTS SP NON_MODAL SP pathname SP pathname SP instrument_index
  </p>
  <p>/ DB_INSTRUMENTS SP pathname SP pathname
-Line 8997 
 Command Syntax</h3>
+Line 9133 
 Command Syntax</h3>
  <p>/ DB_INSTRUMENT_INFO
  </p>
+ <p>/ DB_INSTRUMENTS_JOB_INFO
+ </p>
  <p>/ MISCELLANEOUS
  </p>
-Line 9069 
 Command Syntax</h3>
+Line 9208 
 Command Syntax</h3>
  <p>/ DB_INSTRUMENT_INFO
  </p>
+ <p>/ DB_INSTRUMENTS_JOB_INFO
+ </p>
  <p>/ MISCELLANEOUS
  </p>
-Line 9252 
 Command Syntax</h3>
+Line 9394 
 Command Syntax</h3>
  <p>/ DB_INSTRUMENT SP INFO SP pathname
  </p>
+ <p>/ DB_INSTRUMENTS_JOB SP INFO SP number
+ </p>
  <p>/ VOLUME
  </p>
-Line 9474 
 Command Syntax</h3>
+Line 9619 
 Command Syntax</h3>
  </blockquote><p>
  </p>
+ <p>edit_instruction =
+         </p>
+ <blockquote class="text">
+ <p>INSTRUMENT SP sampler_channel
+ </p>
+ </blockquote><p>
+ </p>
  <p>modal_arg =
          </p>
  <blockquote class="text">
-Line 9756 
 Command Syntax</h3>
+Line 9910 
 Command Syntax</h3>
  <p>filename =
          </p>
  <blockquote class="text">
- <p>stringval
+ <p>stringval_escaped
  </p>
  </blockquote><p>
-Line 9843 
 Command Syntax</h3>
+Line 9997 
 Command Syntax</h3>
  </blockquote><p>
  </p>
+ <p>scan_mode =
+         </p>
+ <blockquote class="text">
+ <p>RECURSIVE
+ </p>
+ <p>/ NON_RECURSIVE
+ </p>
+ <p>/ FLAT
+ </p>
+ </blockquote><p>
+ </p>
+ <a name="character_set"></a><br /><hr />
+ <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
+ <a name="rfc.section.7.1"></a><h3>7.1.&nbsp;
+ Character Set and Escape Sequences</h3>
+ <p>Older versions of this protocol up to and including v1.1 only
+                 supported the standard ASCII character set (ASCII code 0 - 127)
+                 <a class='info' href='#RFC20'>[RFC20]<span> (</span><span class='info'>UCLA, &ldquo;ASCII format for Network Interchange,&rdquo; 1969.</span><span>)</span></a>, all younger versions of this protocol
+                 however support the Extended ASCII character set (ASCII code
+- 255). The same group of younger protocols also support
+                 escape sequences, but only for certain, explicitly declared
+                 parts of the protocol. The supported escape sequences are
+                 defined as follows:
+ </p><table class="full" align="center" border="0" cellpadding="2" cellspacing="2">
+ <col align="left"><col align="left">
+ <tr><th align="left">ASCII Character Sequence</th><th align="left">Translated into (Name)</th></tr>
+ <tr>
+ <td align="left">\n</td>
+ <td align="left">new line</td>
+ </tr>
+ <tr>
+ <td align="left">\r</td>
+ <td align="left">carriage return</td>
+ </tr>
+ <tr>
+ <td align="left">\f</td>
+ <td align="left">form feed</td>
+ </tr>
+ <tr>
+ <td align="left">\t</td>
+ <td align="left">horizontal tab</td>
+ </tr>
+ <tr>
+ <td align="left">\v</td>
+ <td align="left">vertical tab</td>
+ </tr>
+ <tr>
+ <td align="left">\'</td>
+ <td align="left">apostrophe</td>
+ </tr>
+ <tr>
+ <td align="left">\"</td>
+ <td align="left">quotation mark</td>
+ </tr>
+ <tr>
+ <td align="left">\\</td>
+ <td align="left">backslash</td>
+ </tr>
+ <tr>
+ <td align="left">\OOO</td>
+ <td align="left">three digit octal ASCII code of the character</td>
+ </tr>
+ <tr>
+ <td align="left">\xHH</td>
+ <td align="left">two digit hex ASCII code of the character</td>
+ </tr>
+ </table>
+ <p>Notice: due to the transition of certain parts of the
+                 protocol which now support escape sequences, a slight backward
+                 incompatibility to protocols version v1.1 and younger has been
+                 introduced. The only difference is that in parts of the protocol
+                 where escape characters are now supported, a backslash characters
+                 MUST be escaped as well (that is as double backslash), whereas
+                 in the old versions a single backslash was sufficient.
+ </p>
  <a name="events"></a><br /><hr />
  <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
  <a name="rfc.section.8"></a><h3>8.&nbsp;
-Line 10132 
 Channel information changed</h3>
+Line 10367 
 Channel information changed</h3>
  <a name="rfc.section.8.10"></a><h3>8.10.&nbsp;
  Number of effect sends changed</h3>
  <p>Client may want to be notified when the number of effect sends on
                  a particular sampler channel is changed by issuing the following command:
  </p>
  <p>
-Line 10529 
 Database instrument information changed<
+Line 10764 
 Database instrument information changed<
                  (encapsulated into apostrophes), which name is changes and &lt;new-name&gt; is
                  the new name of the instrument, encapsulated into apostrophes.
  </p>
- <a name="SUBSCRIBE MISCELLANEOUS"></a><br /><hr />
+ <a name="SUBSCRIBE DB_INSTRUMENTS_JOB_INFO"></a><br /><hr />
  <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
  <a name="rfc.section.8.22"></a><h3>8.22.&nbsp;
+ Database job status information changed</h3>
+ <p>Client may want to be notified when the status of particular database
+                 instruments job is changed by issuing the following command:
+ </p>
+ <p>
+                     </p>
+ <blockquote class="text">
+ <p>SUBSCRIBE DB_INSTRUMENTS_JOB_INFO
+ </p>
+ </blockquote><p>
+ </p>
+ <p>Server will start sending the following notification messages:
+ </p>
+ <p>
+                     </p>
+ <blockquote class="text">
+ <p>"NOTIFY:DB_INSTRUMENTS_JOB_INFO:&lt;job-id&gt;"
+ </p>
+ </blockquote><p>
+ </p>
+ <p>where &lt;job-id&gt; will be replaced by the numerical ID of the job,
+                 which status is changed. The front-end will have to send the respective
+                 command to actually get the status info. Because these messages
+                 will be triggered by LSCP commands issued by other clients rather than real
+                 time events happening on the server, it is believed that an empty notification
+                 message is sufficient here.
+ </p>
+ <a name="SUBSCRIBE MISCELLANEOUS"></a><br /><hr />
+ <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
+ <a name="rfc.section.8.23"></a><h3>8.23.&nbsp;
  Miscellaneous and debugging events</h3>
  <p>Client may want to be notified of miscellaneous and debugging events occurring at
-Line 10596 
 Acknowledgments</h3>
+Line 10864 
 Acknowledgments</h3>
  <table summary="layout" cellpadding="0" cellspacing="2" class="TOCbug" align="right"><tr><td class="TOCbug"><a href="#toc">&nbsp;TOC&nbsp;</a></td></tr></table>
  <h3>11.&nbsp;References</h3>
  <table width="99%" border="0">
+ <tr><td class="author-text" valign="top"><a name="RFC20">[RFC20]</a></td>
+ <td class="author-text">UCLA, &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc20.txt">ASCII format for Network Interchange</a>,&rdquo; RFC&nbsp;20, 1969.</td></tr>
  <tr><td class="author-text" valign="top"><a name="RFC2119">[RFC2119]</a></td>
  <td class="author-text">Bradner, S., &ldquo;<a href="ftp://ftp.isi.edu/in-notes/rfc2119.txt">Key words for use in RFCs to Indicate Requirement Levels</a>,&rdquo; RFC&nbsp;2119, 1997.</td></tr>
  <tr><td class="author-text" valign="top"><a name="RFC2234">[RFC2234]</a></td>

 Legend:



Removed from v.1189
 


changed lines


 
Added in v.1251
 Legend:



Removed from v.1189
 


changed lines


 
Added in v.1251
-Removed from v.1189
+Added in v.1251

	ViewVC Help
Powered by ViewVC