reference/functions/nksp_play_note_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>play_note() function</title>
    <meta name="description" content="Triggers a new note.">
  </head>
  <body>
    <h1>play_note()</h1>
    <p>
      Triggers a new note to be played by the sampler. This is almost
      like generating
      a new MIDI note-on event programmatically, with the difference though
      that triggering a note programmatically this way does not cause a
      <code lang="nksp">note</code> event handler to be executed for the new note, nor
      will any MIDI specific note-on handling be done (i.e. it will have
      no effect on key switching or on the status of built-in array variable
      <code>%KEY_DOWN[]</code>).
    </p>
    
    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
play_note(??note??, [??velocity??], [??offset-us??], [??duration-us??])
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??note??</code></td>
        <td>Integer Number</td>
        <td>Note number (absolute pitch).<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??velocity??</code></td>
        <td>Integer Number</td>
        <td>Trigger velocity.<br>
            [optional, default: <code>127</code>]</td>
      </tr>
      <tr>
        <td><code>??offset-us??</code></td>
        <td>Integer Number</td>
        <td>Start offset of the sample to be played in microseconds.<br>
            <code>-1</code>: Do not override the start offset and use the
                             regular start offset as defined by the
                             instrument file.<br>
            [optional, default: <code>-1</code>]</td>
      </tr>
      <tr>
        <td><code>??duration-us??</code></td>
        <td>Integer Number</td>
        <td>Length of the note to be played in microseconds.<br>
            <code>0</code>: The entire note's sample will be played to its end.<br>
            <code>-1</code>: The note will be stopped when the event
                handler's note stops (must only be used with
                <code>note</code> event handlers).<br>
            <code>-2</code>: The note will be stopped when a note-off event was received on the passed <code>??note??</code> number (argument 1).<br>
            [optional, default: <code>0</code>]</td>
      </tr>
    </table>

    <note>
    You need at least LinuxSampler 2.0.0.svn2 for passing a value
    higher than <code>0</code> for <code>??duration-us??</code>.<br>
    <br>
    You need at least LinuxSampler 2.0.0.svn3 for passing <code>-1</code> for
    <code>??duration-us??</code>.<br>
    <br>
    You need at least LinuxSampler 2.0.0.svn55 for passing any other value than <code>0</code> for
    <code>??offset-us??</code>.<br>
    <br>
    You need at least LinuxSampler 2.0.0.svn56 for passing <code>-2</code> for
    <code>??duration-us??</code>.
    </note>

    <h3>Return Value</h3>
    <table>
      <tr>
        <th>Description</th> <th>Data Type</th>
      </tr>
      <tr>
        <td>Note's event ID of the new note that has been triggered. This event ID can be
            used to control the note during its life time.</td>
        <td>Event ID Number</td>
      </tr>
    </table>
    
    <h3>Examples</h3>
    <p>
      The following example resembles a simple delay effect. For each note
      being triggered by the musician, the script launches additional notes,
      each one of such additional successive notes with a more and more reduced
      volume.</p>
    <code>
on init
  { The amount of notes to play }
  declare const $delayNotes := 4
  { Tempo with which the new notes will follow the orignal note }
  declare const $bpm := 90
  { Convert BPM to microseconds (duration between the notes) }
  declare const $delayMicroSeconds := 60 * 1000000 / $bpm
  { Just a working variable for being used with the while loop below }
  declare polyphonic $i
  { For each successive note we trigger, we will reduce the velocity a bit}
  declare polyphonic $velocity
end on

on note
  { First initialize the variable $i with 4 each time we enter this event
    handler, because each time we executed this handler, the variable will be 0 }
  $i := $delayNotes

  { Loop which will be executed 4 times in a row }
  while ($i)
    { Calculate the velocity for the next note being triggered }
    $velocity := 127 * $i / ($delayNotes + 1)
    { Suspend this script for a short moment ... }
    wait($delayMicroSeconds)
    { ... and after that short break, trigger a new note. }
    play_note($EVENT_NOTE, $velocity)
    { Decrement loop counter $i by one }
    $i := $i - 1
  end while
end on
    </code>

    <h3>See also</h3>
    <p><code>note_off()</code>, <code>set_controller()</code>, <code>change_note()</code>, <code>change_velo()</code>, <code>change_play_pos()</code><p>

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

    <note>
    The special value <code>-1</code> for <code>??offset-us??</code> only exists
    with NKSP, it is not available with KSP.<br>
    <br>
    The special value <code>-2</code> for <code>??duration-us??</code> only exists
    with NKSP, it is not available with KSP.<br>
    <br>
    Dynamic, optional arguments are
    only supported by NKSP. If you want to retain compatibility to KSP,
    then you should always pass a value for all arguments of this function.
    </note>

  </body>
</html>
1	schoenebeck	2732	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>play_note() function</title>
5			<meta name="description" content="Triggers a new note.">
6			</head>
7			<body>
8			<h1>play_note()</h1>
9			<p>
10	schoenebeck	2940	Triggers a new note to be played by the sampler. This is almost
11			like generating
12	schoenebeck	2881	a new MIDI note-on event programmatically, with the difference though
13			that triggering a note programmatically this way does not cause a
14	schoenebeck	2941	<code lang="nksp">note</code> event handler to be executed for the new note, nor
15	schoenebeck	2940	will any MIDI specific note-on handling be done (i.e. it will have
16			no effect on key switching or on the status of built-in array variable
17			<code>%KEY_DOWN[]</code>).
18	schoenebeck	2732	</p>
19
20			<h3>Function Prototype</h3>
21			<p/>
22	schoenebeck	2742	<code lang="nksp">
23	schoenebeck	2732	play_note(??note??, [??velocity??], [??offset-us??], [??duration-us??])
24			</code>
25
26			<h3>Arguments</h3>
27			<table>
28			<tr>
29			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
30			</tr>
31			<tr>
32			<td><code>??note??</code></td>
33			<td>Integer Number</td>
34			<td>Note number (absolute pitch).<br>
35			[required]</td>
36			</tr>
37			<tr>
38			<td><code>??velocity??</code></td>
39			<td>Integer Number</td>
40			<td>Trigger velocity.<br>
41	schoenebeck	3234	[optional, default: <code>127</code>]</td>
42	schoenebeck	2732	</tr>
43			<tr>
44			<td><code>??offset-us??</code></td>
45			<td>Integer Number</td>
46			<td>Start offset of the sample to be played in microseconds.<br>
47	schoenebeck	3252	<code>-1</code>: Do not override the start offset and use the
48			regular start offset as defined by the
49			instrument file.<br>
50			[optional, default: <code>-1</code>]</td>
51	schoenebeck	2732	</tr>
52			<tr>
53			<td><code>??duration-us??</code></td>
54			<td>Integer Number</td>
55			<td>Length of the note to be played in microseconds.<br>
56	schoenebeck	3254	<code>0</code>: The entire note's sample will be played to its end.<br>
57	schoenebeck	3234	<code>-1</code>: The note will be stopped when the event
58	schoenebeck	2881	handler's note stops (must only be used with
59			<code>note</code> event handlers).<br>
60	schoenebeck	3254	<code>-2</code>: The note will be stopped when a note-off event was received on the passed <code>??note??</code> number (argument 1).<br>
61	schoenebeck	3234	[optional, default: <code>0</code>]</td>
62	schoenebeck	2732	</tr>
63			</table>
64
65	schoenebeck	2872	<note>
66	schoenebeck	3254	You need at least LinuxSampler 2.0.0.svn2 for passing a value
67	schoenebeck	3252	higher than <code>0</code> for <code>??duration-us??</code>.<br>
68			<br>
69	schoenebeck	3254	You need at least LinuxSampler 2.0.0.svn3 for passing <code>-1</code> for
70	schoenebeck	3252	<code>??duration-us??</code>.<br>
71			<br>
72	schoenebeck	3254	You need at least LinuxSampler 2.0.0.svn55 for passing any other value than <code>0</code> for
73			<code>??offset-us??</code>.<br>
74			<br>
75			You need at least LinuxSampler 2.0.0.svn56 for passing <code>-2</code> for
76			<code>??duration-us??</code>.
77	schoenebeck	2872	</note>
78
79	schoenebeck	2732	<h3>Return Value</h3>
80			<table>
81			<tr>
82			<th>Description</th> <th>Data Type</th>
83			</tr>
84			<tr>
85			<td>Note's event ID of the new note that has been triggered. This event ID can be
86			used to control the note during its life time.</td>
87			<td>Event ID Number</td>
88			</tr>
89			</table>
90
91			<h3>Examples</h3>
92	schoenebeck	3238	<p>
93			The following example resembles a simple delay effect. For each note
94			being triggered by the musician, the script launches additional notes,
95			each one of such additional successive notes with a more and more reduced
96			volume.</p>
97	schoenebeck	2732	<code>
98			on init
99			{ The amount of notes to play }
100			declare const $delayNotes := 4
101			{ Tempo with which the new notes will follow the orignal note }
102			declare const $bpm := 90
103			{ Convert BPM to microseconds (duration between the notes) }
104			declare const $delayMicroSeconds := 60 * 1000000 / $bpm
105			{ Just a working variable for being used with the while loop below }
106			declare polyphonic $i
107			{ For each successive note we trigger, we will reduce the velocity a bit}
108			declare polyphonic $velocity
109			end on
110
111			on note
112			{ First initialize the variable $i with 4 each time we enter this event
113			handler, because each time we executed this handler, the variable will be 0 }
114			$i := $delayNotes
115
116			{ Loop which will be executed 4 times in a row }
117			while ($i)
118			{ Calculate the velocity for the next note being triggered }
119			$velocity := 127 * $i / ($delayNotes + 1)
120			{ Suspend this script for a short moment ... }
121			wait($delayMicroSeconds)
122			{ ... and after that short break, trigger a new note. }
123			play_note($EVENT_NOTE, $velocity)
124			{ Decrement loop counter $i by one }
125			$i := $i - 1
126			end while
127			end on
128			</code>
129
130	schoenebeck	3252	<h3>See also</h3>
131	schoenebeck	3256	<p><code>note_off()</code>, <code>set_controller()</code>, <code>change_note()</code>, <code>change_velo()</code>, <code>change_play_pos()</code><p>
132	schoenebeck	3252
133			<h3>Availability</h3>
134			<p>Since LinuxSampler 2.0.0<p>
135
136			<note>
137			The special value <code>-1</code> for <code>??offset-us??</code> only exists
138			with NKSP, it is not available with KSP.<br>
139			<br>
140	schoenebeck	3254	The special value <code>-2</code> for <code>??duration-us??</code> only exists
141			with NKSP, it is not available with KSP.<br>
142			<br>
143	schoenebeck	3252	Dynamic, optional arguments are
144			only supported by NKSP. If you want to retain compatibility to KSP,
145			then you should always pass a value for all arguments of this function.
146			</note>
147
148	schoenebeck	2732	</body>
149			</html>