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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3234 - (hide annotations) (download) (as text)
Sun May 28 16:21:57 2017 UTC (6 years, 10 months ago) by schoenebeck
File MIME type: text/html
File size: 4088 byte(s)
- NKSP: More visual cosmetics.

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>

  ViewVC Help
Powered by ViewVC