reference/functions/nksp_change_note_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>change_note() function</title>
    <meta name="description" content="Change MIDI note number of note.">
  </head>
  <body>
    <h1>change_note()</h1>
    <p>
      Changes the MIDI note number of the requested note.
    </p>
    <p>
      Changing the note number with this function only succeeds if the 
      respective note is new. That effectively means you should change the
      note number before any <code lang="nksp">wait()</code> calls, and before
      entering any loops that may execute your script for a very long time.
      Because in both cases the sampler may suspend your script for a certain
      amount of time and once your script got resumed, the respective event
      and the resulting note may already have entered the sampler's regular
      event processing chain and thus the note's note number can no longer be
      changed.
    </p>
    <p>
      Note that the new note number set by this function only affects the
      resulting new voices, it does not modify the actual MIDI event.
      That means the new voices behave as if the MIDI event itself was
      modified, that is for the new voices the instrument's region,
      synthesis parameter case and sample is selected based upon the
      new note number.
    </p>
    <p>
      However outside the scope of new voices the old MIDI note number is
      retained. That means for example the newly triggered voices will only
      be released later on if a MIDI note-off event was received equal to
      the old MIDI note number (not the new note number), and also other
      MIDI processing tasks of the sampler like
      <i title="A set of regions where always only one of them is played at a time and thus a newly triggered region automatically releases the previous region (of the same exclusive group).">
        exclusive groups
      </i> (a.k.a. key groups), key based round robin and all other common
      MIDI processing tasks are not affected by this function at all.
    </p>

    <h3>Function Prototype</h3>
    <p/>
    <code>
change_note(??event-id??, ??note-number??)
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??event-id??</code></td>
        <td>Event ID Number</td>
        <td>Event ID of the note to change.<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??note-number??</code></td>
        <td>Integer Number</td>
        <td>New MIDI note number (<code>0</code> to <code>127</code>).<br>
            [required]</td>
      </tr>
    </table>
    
    <h3>Return Value</h3>
    <p>None.</p>
    
    <h3>Examples</h3>
    <p>None yet.</p>

    <h3>See also</h3>
    <p><code>set_event_par()</code>, <code>change_velo()</code><p>

    <h3>Availability</h3>
    <p>Since LinuxSampler 2.0.0.svn49.<p>

  </body>
</html>
1	schoenebeck	3215	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>change_note() function</title>
5			<meta name="description" content="Change MIDI note number of note.">
6			</head>
7			<body>
8			<h1>change_note()</h1>
9			<p>
10			Changes the MIDI note number of the requested note.
11			</p>
12			<p>
13			Changing the note number with this function only succeeds if the
14			respective note is new. That effectively means you should change the
15			note number before any <code lang="nksp">wait()</code> calls, and before
16			entering any loops that may execute your script for a very long time.
17			Because in both cases the sampler may suspend your script for a certain
18			amount of time and once your script got resumed, the respective event
19			and the resulting note may already have entered the sampler's regular
20			event processing chain and thus the note's note number can no longer be
21			changed.
22			</p>
23	schoenebeck	3220	<p>
24			Note that the new note number set by this function only affects the
25			resulting new voices, it does not modify the actual MIDI event.
26			That means the new voices behave as if the MIDI event itself was
27			modified, that is for the new voices the instrument's region,
28			synthesis parameter case and sample is selected based upon the
29			new note number.
30			</p>
31			<p>
32			However outside the scope of new voices the old MIDI note number is
33			retained. That means for example the newly triggered voices will only
34			be released later on if a MIDI note-off event was received equal to
35			the old MIDI note number (not the new note number), and also other
36			MIDI processing tasks of the sampler like
37			<i title="A set of regions where always only one of them is played at a time and thus a newly triggered region automatically releases the previous region (of the same exclusive group).">
38			exclusive groups
39			</i> (a.k.a. key groups), key based round robin and all other common
40			MIDI processing tasks are not affected by this function at all.
41			</p>
42	schoenebeck	3215
43			<h3>Function Prototype</h3>
44			<p/>
45			<code>
46			change_note(??event-id??, ??note-number??)
47			</code>
48
49			<h3>Arguments</h3>
50			<table>
51			<tr>
52			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
53			</tr>
54			<tr>
55			<td><code>??event-id??</code></td>
56			<td>Event ID Number</td>
57			<td>Event ID of the note to change.<br>
58			[required]</td>
59			</tr>
60			<tr>
61			<td><code>??note-number??</code></td>
62			<td>Integer Number</td>
63			<td>New MIDI note number (<code>0</code> to <code>127</code>).<br>
64			[required]</td>
65			</tr>
66			</table>
67
68			<h3>Return Value</h3>
69			<p>None.</p>
70
71			<h3>Examples</h3>
72			<p>None yet.</p>
73
74			<h3>See also</h3>
75			<p><code>set_event_par()</code>, <code>change_velo()</code><p>
76
77			<h3>Availability</h3>
78			<p>Since LinuxSampler 2.0.0.svn49.<p>
79
80			</body>
81			</html>