/[svn]/doc/docbase/instrument_scripts/nksp/01_nksp.html

Diff of /doc/docbase/instrument_scripts/nksp/01_nksp.html

Parent Directory | Revision Log | View Patch Patch

-revision 3397 by schoenebeck,
Wed Dec  6 19:18:59 2017 UTC
+revision 3698 by schoenebeck,
Sat Jan  4 13:10:46 2020 UTC
 Line 67 
 on ??event-name??
  end on
      </code>
      <p>
-       There are currently four events available:
+       There are currently six events available:
      </p>
        <table>
          <tr>
 Line 77 
 end on
            <td><code>on note</code></td> <td>This event handler is executed when a new note was triggered, i.e. when hitting a key on a MIDI keyboard.</td>
          </tr>
          <tr>
-           <td><code>on release</code></td> <td>This event handler is executed when a new note was released, i.e. when releasing a key on a MIDI keyboard.</td>
+           <td><code>on release</code></td> <td>This event handler is executed when a note was released, i.e. when releasing a key on a MIDI keyboard.</td>
          </tr>
          <tr>
            <td><code>on controller</code></td> <td>This event handler is executed when a MIDI control change event occurred. For instance when turning the modulation wheel at a MIDI keyboard.</td>
          </tr>
          <tr>
+           <td><code>on rpn</code></td> <td>This event handler is executed when a MIDI <i>RPN</i> event occurred.</td>
+         </tr>
+         <tr>
+           <td><code>on nrpn</code></td> <td>This event handler is executed when a MIDI <i>NRPN</i> event occurred.</td>
+         </tr>
+         <tr>
            <td><code>on init</code></td> <td>Executed only once, as very first event handler, right after the script had been loaded. This code block is usually used to initialize variables in your script with some initial, useful data.</td>
          </tr>
        </table>
-Line 147 
 end on
+Line 153 
 end on
        Please note that you can hardly find MIDI keyboards which support release
        velocity. So with most keyboards this value will be 127.
      </p>
      <h3>Controller Events</h3>
      <p>
        Now let's extend the first script to not only show note-on and note-off
-Line 180 
 end on
+Line 186 
 end on
      </p>
      <p>
        There is some special aspect you need to be aware about: in contrast to the MIDI standard,
-       monophonic aftertouch (a.k.a. channel pressure) and pitch beend wheel are
+       monophonic aftertouch (a.k.a. channel pressure) and pitch bend wheel are
        handled by NKSP as if they were regular MIDI controllers. So a value change
        of one of those two triggers a regular <code>controller</code> event handler
        to be executed. To obtain the current aftertouch value you can use
        <code>%CC[$VCC_MONO_AT]</code>, and to get the current pitch bend wheel
        value use <code>%CC[$VCC_PITCH_BEND]</code>.
      </p>
+     <h3>RPN / NRPN Events</h3>
+     <p>
+       There are also dedicated event handlers for
+       MIDI <i title="Registered Parameter Number">RPN</i> and
+       <i title="Non-Registered Parameter Number">NRPN</i>
+       events:
+     </p>
+     <code>
+ on rpn
+   message("RPN address msb=" & msb($RPN_ADDRESS) & ",lsb=" & lsb($RPN_ADDRESS) &
+           "-> value msb=" & msb($RPN_VALUE) & ",lsb="  & lsb($RPN_VALUE))
+   if ($RPN_ADDRESS = 2)
+     message("Standard Coarse Tuning RPN received")
+   end if
+ end on
+ on nrpn
+   message("NRPN address msb=" & msb($RPN_ADDRESS) & ",lsb=" & lsb($RPN_ADDRESS) &
+           "-> value msb=" & msb($RPN_VALUE) & ",lsb="  & lsb($RPN_VALUE))
+ end on
+     </code>
+     <p>
+       Since MIDI RPN and NRPN events are actually MIDI controller events,
+       you might as well handle these with the previous
+       <code>controller</code> event handler. But since RPN and NRPN messages
+       are not just one MIDI message, but rather always handled by a set of
+       individual MIDI messages, and since the
+       precise set and sequence of actual MIDI commands sent varies between
+       vendors and even among individual of their products, it highly makes sense to
+       use these two specialized event handlers for these instead, because the
+       sampler will already relief you from that burden to deal with all those
+       low-level MIDI event processing issues and all their wrinkles involved
+       when handling RPNs and NRPNs.
+     </p>
+     <note>
+       Even though there are two separate, dedicated event handlers for RPN and NRPN events,
+       they both share the same built-in variable names as you can see in the
+       example above.
+     </note>
+     <p>
+       So by reading <code>$RPN_ADDRESS</code> you get the RPN / NRPN parameter
+       number that had been changed, and <code>$RPN_VALUE</code> represents the
+       new value of that RPN / NRPN parameter. Note that these two built-in
+       variables are a 14-bit representation of the parameter number and new
+       value. So their possible value range is <code>0 .. 16383</code>. If you
+       rather want to use their (in MIDI world) more common separated two 7 bit
+       values instead, then you can easily do that by wrapping them into either
+       <code>msb()</code> or <code>lsb()</code> calls like also demonstrated above.
+     </p>
      <h3>Script Load Event</h3>
      <p>
-       As the last one of the four event types available with NKSP, the following
+       As the last one of the six event types available with NKSP, the following
        is an example of an <code>init</code> event handler.
      </p>
      <code>
-Line 418 
 end on
+Line 474 
 end on
        triggered on a MIDI keyboard. The following example demonstrates how that
        could be achieved.
      </p>
-     <note>
-       You need at least LinuxSampler 2.0.0.svn2 or higher for the following
-       example to work as described and as expected. Refer to the notes of the
-       <code>wait()</code> function reference documentation for more
-       informations about this issue.
-     </note>
      <code>
  on init
    { The amount of notes to play }
-Line 1104 
 end synchronized
+Line 1154 
 end synchronized
      </p>
      <note>
        Such <code>synchronized</code> blocks are a language extension which
-       is only available with NKSP and requires at least LinuxSampler 2.0.0.svn60
+       is only available with NKSP. KSP does not support <code>synchronized</code> blocks.
-       or higher. KSP does not support <code>synchronized</code> blocks.
      </note>
      <p>
        So to make our previous example concurrency safe, we would
-Line 1567 
 end on
+Line 1616 
 end on
        Which provides you an overview and quick access to the details of all
        built-in functions, built-in variables and more.
      </p>
+     <p>
+       You might also be interested to look at new <i>NKSP</i> core language
+       features being added to the latest development version of the sampler:
+       <a href="real_unit_final/01_nksp_real_unit_final.html">
+         Real Numbers, Units and Finalness ...
+       </a>
+     </p>
    </body>
  </html>

 Legend:



Removed from v.3397
 


changed lines


 
Added in v.3698
 Legend:



Removed from v.3397
 


changed lines


 
Added in v.3698
-Removed from v.3397
+Added in v.3698

	ViewVC Help
Powered by ViewVC