/[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 2872 - (show annotations) (download) (as text)
Sun Apr 10 18:42:55 2016 UTC (5 years, 2 months ago) by schoenebeck
File MIME type: text/html
File size: 3423 byte(s)
* NKSP docs: updated articles regarding recent development changes of
  the "wait()" and "play_note()" built-in script function
  implementations.

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

  ViewVC Help
Powered by ViewVC