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 |
3234 |
[optional, default: <code>0</code>]</td> |
48 |
schoenebeck |
2732 |
</tr> |
49 |
|
|
<tr> |
50 |
|
|
<td><code>??duration-us??</code></td> |
51 |
|
|
<td>Integer Number</td> |
52 |
|
|
<td>Length of the note to be played in microseconds.<br> |
53 |
schoenebeck |
3234 |
<code>-1</code>: The note will be stopped when the event |
54 |
schoenebeck |
2881 |
handler's note stops (must only be used with |
55 |
|
|
<code>note</code> event handlers).<br> |
56 |
schoenebeck |
3234 |
<code>0</code>: The entire note's sample will be played to its end.<br> |
57 |
|
|
[optional, default: <code>0</code>]</td> |
58 |
schoenebeck |
2732 |
</tr> |
59 |
|
|
</table> |
60 |
|
|
|
61 |
schoenebeck |
2872 |
<note> |
62 |
|
|
You need at least LinuxSampler 2.0.0.svn2 or higher for passing a value |
63 |
schoenebeck |
2881 |
higher than <code>0</code> for <code>??duration-us??</code>, and you need |
64 |
|
|
at least LinuxSampler 2.0.0.svn3 or higher for passing <code>-1</code> for |
65 |
|
|
<code>??duration-us??</code>. |
66 |
schoenebeck |
2872 |
</note> |
67 |
|
|
|
68 |
schoenebeck |
2732 |
<note class="important"> |
69 |
schoenebeck |
2881 |
Passing any other value than <code>0</code> for <code>??offset-us??</code> |
70 |
|
|
is not supported by LinuxSampler yet. |
71 |
schoenebeck |
2732 |
</note> |
72 |
schoenebeck |
2872 |
|
73 |
schoenebeck |
2732 |
<h3>Return Value</h3> |
74 |
|
|
<table> |
75 |
|
|
<tr> |
76 |
|
|
<th>Description</th> <th>Data Type</th> |
77 |
|
|
</tr> |
78 |
|
|
<tr> |
79 |
|
|
<td>Note's event ID of the new note that has been triggered. This event ID can be |
80 |
|
|
used to control the note during its life time.</td> |
81 |
|
|
<td>Event ID Number</td> |
82 |
|
|
</tr> |
83 |
|
|
</table> |
84 |
|
|
|
85 |
|
|
<h3>Examples</h3> |
86 |
|
|
<p/> |
87 |
|
|
<code> |
88 |
|
|
on init |
89 |
|
|
{ The amount of notes to play } |
90 |
|
|
declare const $delayNotes := 4 |
91 |
|
|
{ Tempo with which the new notes will follow the orignal note } |
92 |
|
|
declare const $bpm := 90 |
93 |
|
|
{ Convert BPM to microseconds (duration between the notes) } |
94 |
|
|
declare const $delayMicroSeconds := 60 * 1000000 / $bpm |
95 |
|
|
{ Just a working variable for being used with the while loop below } |
96 |
|
|
declare polyphonic $i |
97 |
|
|
{ For each successive note we trigger, we will reduce the velocity a bit} |
98 |
|
|
declare polyphonic $velocity |
99 |
|
|
end on |
100 |
|
|
|
101 |
|
|
on note |
102 |
|
|
{ First initialize the variable $i with 4 each time we enter this event |
103 |
|
|
handler, because each time we executed this handler, the variable will be 0 } |
104 |
|
|
$i := $delayNotes |
105 |
|
|
|
106 |
|
|
{ Loop which will be executed 4 times in a row } |
107 |
|
|
while ($i) |
108 |
|
|
{ Calculate the velocity for the next note being triggered } |
109 |
|
|
$velocity := 127 * $i / ($delayNotes + 1) |
110 |
|
|
{ Suspend this script for a short moment ... } |
111 |
|
|
wait($delayMicroSeconds) |
112 |
|
|
{ ... and after that short break, trigger a new note. } |
113 |
|
|
play_note($EVENT_NOTE, $velocity) |
114 |
|
|
{ Decrement loop counter $i by one } |
115 |
|
|
$i := $i - 1 |
116 |
|
|
end while |
117 |
|
|
end on |
118 |
|
|
</code> |
119 |
|
|
|
120 |
|
|
</body> |
121 |
|
|
</html> |