/[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 2881 - (show annotations) (download) (as text)
Tue Apr 19 16:09:52 2016 UTC (6 years, 5 months ago) by schoenebeck
File MIME type: text/html
File size: 3811 byte(s)
* NKSP: updated reference documentation for development changes
  regarding play_note(), ignore_event() and ignore_controller()
  functions.

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 like generating
11 a new MIDI note-on event programmatically, with the difference though
12 that triggering a note programmatically this way does not cause a
13 <code>note</code> event handler to be executed for the new note.
14 </p>
15
16 <h3>Function Prototype</h3>
17 <p/>
18 <code lang="nksp">
19 play_note(??note??, [??velocity??], [??offset-us??], [??duration-us??])
20 </code>
21
22 <h3>Arguments</h3>
23 <table>
24 <tr>
25 <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
26 </tr>
27 <tr>
28 <td><code>??note??</code></td>
29 <td>Integer Number</td>
30 <td>Note number (absolute pitch).<br>
31 [required]</td>
32 </tr>
33 <tr>
34 <td><code>??velocity??</code></td>
35 <td>Integer Number</td>
36 <td>Trigger velocity.<br>
37 [optional, default: 127]</td>
38 </tr>
39 <tr>
40 <td><code>??offset-us??</code></td>
41 <td>Integer Number</td>
42 <td>Start offset of the sample to be played in microseconds.<br>
43 [optional, default: 0]</td>
44 </tr>
45 <tr>
46 <td><code>??duration-us??</code></td>
47 <td>Integer Number</td>
48 <td>Length of the note to be played in microseconds.<br>
49 -1: The note will be stopped when the event
50 handler's note stops (must only be used with
51 <code>note</code> event handlers).<br>
52 0: The entire note's sample will be played to its end.<br>
53 [optional, default: 0]</td>
54 </tr>
55 </table>
56
57 <note>
58 You need at least LinuxSampler 2.0.0.svn2 or higher for passing a value
59 higher than <code>0</code> for <code>??duration-us??</code>, and you need
60 at least LinuxSampler 2.0.0.svn3 or higher for passing <code>-1</code> for
61 <code>??duration-us??</code>.
62 </note>
63
64 <note class="important">
65 Passing any other value than <code>0</code> for <code>??offset-us??</code>
66 is not supported by LinuxSampler yet.
67 </note>
68
69 <h3>Return Value</h3>
70 <table>
71 <tr>
72 <th>Description</th> <th>Data Type</th>
73 </tr>
74 <tr>
75 <td>Note's event ID of the new note that has been triggered. This event ID can be
76 used to control the note during its life time.</td>
77 <td>Event ID Number</td>
78 </tr>
79 </table>
80
81 <h3>Examples</h3>
82 <p/>
83 <code>
84 on init
85 { The amount of notes to play }
86 declare const $delayNotes := 4
87 { Tempo with which the new notes will follow the orignal note }
88 declare const $bpm := 90
89 { Convert BPM to microseconds (duration between the notes) }
90 declare const $delayMicroSeconds := 60 * 1000000 / $bpm
91 { Just a working variable for being used with the while loop below }
92 declare polyphonic $i
93 { For each successive note we trigger, we will reduce the velocity a bit}
94 declare polyphonic $velocity
95 end on
96
97 on note
98 { First initialize the variable $i with 4 each time we enter this event
99 handler, because each time we executed this handler, the variable will be 0 }
100 $i := $delayNotes
101
102 { Loop which will be executed 4 times in a row }
103 while ($i)
104 { Calculate the velocity for the next note being triggered }
105 $velocity := 127 * $i / ($delayNotes + 1)
106 { Suspend this script for a short moment ... }
107 wait($delayMicroSeconds)
108 { ... and after that short break, trigger a new note. }
109 play_note($EVENT_NOTE, $velocity)
110 { Decrement loop counter $i by one }
111 $i := $i - 1
112 end while
113 end on
114 </code>
115
116 </body>
117 </html>

  ViewVC Help
Powered by ViewVC