/[svn]/doc/docbase/instrument_scripts/nksp/reference/functions/nksp_play_note_function.html
ViewVC logotype

Contents of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_play_note_function.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3601 - (show annotations) (download) (as text)
Mon Sep 16 16:03:36 2019 UTC (4 years, 6 months ago) by schoenebeck
File MIME type: text/html
File size: 5236 byte(s)
* NKSP: Added recently added built-in functions to reference docs.
* NKSP: Added info about std units and finalness to existing functions.
* NKSP: Added recently added built-in constants ~NI_MATH_E and ~NI_MATH_PI.

1 <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 Triggers a new note to be played by the sampler. This is almost
11 like generating
12 a new MIDI note-on event programmatically, with the difference though
13 that triggering a note programmatically this way does not cause a
14 <code lang="nksp">note</code> event handler to be executed for the new note, nor
15 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 </p>
19
20 <h3>Function Prototype</h3>
21 <p/>
22 <code lang="nksp">
23 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 [optional, default: <code>127</code>]</td>
42 </tr>
43 <tr>
44 <td><code>??offset-us??</code></td>
45 <td>Integer&nbsp;Number&nbsp;or<br>
46 Real&nbsp;Number</td>
47 <td>Start offset of the sample to be played in microseconds.<br>
48 <code>-1</code>: Do not override the start offset and use the
49 regular start offset as defined by the
50 instrument file.<br>
51 [optional, default: <code>-1</code>]</td>
52 </tr>
53 <tr>
54 <td><code>??duration-us??</code></td>
55 <td>Integer&nbsp;Number&nbsp;or<br>
56 Real&nbsp;Number</td>
57 <td>Length of the note to be played in microseconds.<br>
58 <code>0</code>: The entire note's sample will be played to its end.<br>
59 <code>-1</code>: The note will be stopped when the event
60 handler's note stops (must only be used with
61 <code>note</code> event handlers).<br>
62 <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>
63 [optional, default: <code>0</code>]</td>
64 </tr>
65 </table>
66
67 <h3>Return Value</h3>
68 <table>
69 <tr>
70 <th>Data Type</th> <th>Description</th>
71 </tr>
72 <tr>
73 <td>Event ID Number</td>
74 <td>Note's event ID of the new note that has been triggered. This event ID can be
75 used to control the note during its life time.</td>
76 </tr>
77 </table>
78
79 <h3>Remarks</h3>
80 <p>
81 This functions optionally accepts <code>s</code> as standard unit
82 for its arguments <code>??offset-us??</code> and <code>??duration-us??</code>.
83 </p>
84
85 <h3>Examples</h3>
86 <p>
87 The following example resembles a simple delay effect. For each note
88 being triggered by the musician, the script launches additional notes,
89 each one of such additional successive notes with a more and more reduced
90 volume.</p>
91 <code>
92 on init
93 { The amount of notes to play }
94 declare const $delayNotes := 4
95 { Tempo with which the new notes will follow the orignal note }
96 declare const $bpm := 90
97 { Convert BPM to microseconds (duration between the notes) }
98 declare const $delayMicroSeconds := 60 * 1000000 / $bpm
99 { Just a working variable for being used with the while loop below }
100 declare polyphonic $i
101 { For each successive note we trigger, we will reduce the velocity a bit}
102 declare polyphonic $velocity
103 end on
104
105 on note
106 { First initialize the variable $i with 4 each time we enter this event
107 handler, because each time we executed this handler, the variable will be 0 }
108 $i := $delayNotes
109
110 { Loop which will be executed 4 times in a row }
111 while ($i)
112 { Calculate the velocity for the next note being triggered }
113 $velocity := 127 * $i / ($delayNotes + 1)
114 { Suspend this script for a short moment ... }
115 wait($delayMicroSeconds)
116 { ... and after that short break, trigger a new note. }
117 play_note($EVENT_NOTE, $velocity)
118 { Decrement loop counter $i by one }
119 $i := $i - 1
120 end while
121 end on
122 </code>
123
124 <h3>See also</h3>
125 <p><code>note_off()</code>, <code>set_controller()</code>, <code>change_note()</code>, <code>change_velo()</code>, <code>change_play_pos()</code><p>
126
127 <h3>Availability</h3>
128 <p>Since LinuxSampler 2.0.0<p>
129
130 <note>
131 The special value <code>-1</code> for <code>??offset-us??</code> only exists
132 with NKSP, it is not available with KSP.<br>
133 <br>
134 The special value <code>-2</code> for <code>??duration-us??</code> only exists
135 with NKSP, it is not available with KSP.<br>
136 <br>
137 Dynamic, optional arguments are
138 only supported by NKSP. If you want to retain compatibility to KSP,
139 then you should always pass a value for all arguments of this function.
140 </note>
141
142 </body>
143 </html>

  ViewVC Help
Powered by ViewVC