/[svn]/doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html
ViewVC logotype

Contents of /doc/docbase/instrument_scripts/nksp/reference/01_nksp_reference.html

Parent Directory Parent Directory | Revision Log Revision Log


Revision 3077 - (show annotations) (download) (as text)
Thu Jan 5 18:02:08 2017 UTC (7 years, 2 months ago) by schoenebeck
File MIME type: text/html
File size: 23622 byte(s)
* NKSP reference: Added built-in function in_range().

1 <html>
2 <head>
3 <meta name="author" content="Christian Schoenebeck">
4 <title>NKSP Reference</title>
5 <urlpath>Reference</urlpath>
6 <navpath>Reference Manual</navpath>
7 <meta name="description" content="Reference documentation of the NKSP real-time instrument script language.">
8 </head>
9 <body>
10 <h1>NKSP Reference</h1>
11 <p>
12 This document gives you an overview of all built-in functions and built-in
13 variables provided by the NKSP real-time instrument script language.
14 </p>
15
16 <h2>Built-In Functions</h2>
17 <p>
18 These are the built-in functions available with the NKSP realt-time
19 instrument script language.
20 </p>
21
22 <h3>Core Language Functions</h3>
23 <p>
24 Most fundamental NKSP functions, independent from any purpose of being used in a sampler.
25 </p>
26 <table>
27 <tr>
28 <th>Function</th> <th>Description</th>
29 </tr>
30 <tr>
31 <td><code lang="nksp">dec()</code></td>
32 <td>Decrements the passed integer variable by one.</td>
33 </tr>
34 <tr>
35 <td><code>inc()</code></td>
36 <td>Increments the passed integer variable by one.</td>
37 </tr>
38 <tr>
39 <td><code>in_range()</code></td>
40 <td>Checks whether a value is between two other values.</td>
41 </tr>
42 <tr>
43 <td><code lang="nksp">message()</code></td>
44 <td>Prints text to the sampler's terminal.</td>
45 </tr>
46 <tr>
47 <td><code>exit()</code></td>
48 <td>Stops execution of the current event handler instance.</td>
49 </tr>
50 <tr>
51 <td><code>wait()</code></td>
52 <td>Pauses execution for a certain amount of time.</td>
53 </tr>
54 <tr>
55 <td><code>stop_wait()</code></td>
56 <td>Resumes execution of a suspended script callback.</td>
57 </tr>
58 <tr>
59 <td><code>abs()</code></td>
60 <td>Calculates the absolute value of a given value.</td>
61 </tr>
62 <tr>
63 <td><code>random()</code></td>
64 <td>Random number generator.</td>
65 </tr>
66 <tr>
67 <td><code>min()</code></td>
68 <td>Calculates the minimum value of two given values.</td>
69 </tr>
70 <tr>
71 <td><code>max()</code></td>
72 <td>Calculates the maximum value of two given values.</td>
73 </tr>
74 <tr>
75 <td><code>num_elements()</code></td>
76 <td>Returns the size of the requested array variable.</td>
77 </tr>
78 <tr>
79 <td><code>sh_left()</code></td>
80 <td>Calculates a left bit shifted value.</td>
81 </tr>
82 <tr>
83 <td><code>sh_right()</code></td>
84 <td>Calculates a right bit shifted value.</td>
85 </tr>
86 </table>
87
88 <h3>Common Sampler Functions</h3>
89 <p>
90 Basic sampler related functions, independent from a particular sampler
91 format or sampler engine.
92 </p>
93 <table>
94 <tr>
95 <th>Function</th> <th>Description</th>
96 </tr>
97 <tr>
98 <td><code>play_note()</code></td>
99 <td>Triggers a new note.</td>
100 </tr>
101 <tr>
102 <td><code>change_pan()</code></td>
103 <td>Changes panning of voices (stereo balance).</td>
104 </tr>
105 <tr>
106 <td><code>change_tune()</code></td>
107 <td>Changes the tuning of voices.</td>
108 </tr>
109 <tr>
110 <td><code>change_vol()</code></td>
111 <td>Changes the volume of voices.</td>
112 </tr>
113 <tr>
114 <td><code>change_cutoff()</code></td>
115 <td>Changes filter cutoff frequency of voices.</td>
116 </tr>
117 <tr>
118 <td><code>change_reso()</code></td>
119 <td>Changes filter resonance of voices.</td>
120 </tr>
121 <tr>
122 <td><code>change_attack()</code></td>
123 <td>Modifies the attack time of voices.</td>
124 </tr>
125 <tr>
126 <td><code>change_decay()</code></td>
127 <td>Modifies the decay time of voices.</td>
128 </tr>
129 <tr>
130 <td><code>change_release()</code></td>
131 <td>Modifies the release time of voices.</td>
132 </tr>
133 <tr>
134 <td><code>event_status()</code></td>
135 <td>Checks and returns whether a particular note is still alive.</td>
136 </tr>
137 <tr>
138 <td><code>set_controller()</code></td>
139 <td>Creates a MIDI control change event.</td>
140 </tr>
141 <tr>
142 <td><code>ignore_event()</code></td>
143 <td>Drops the given event.</td>
144 </tr>
145 <tr>
146 <td><code>ignore_controller()</code></td>
147 <td>Drops the given MIDI control change event.</td>
148 </tr>
149 <tr>
150 <td><code>note_off()</code></td>
151 <td>Releases the requested note.</td>
152 </tr>
153 <tr>
154 <td><code>set_event_mark()</code></td>
155 <td>Adds an event to an event group.</td>
156 </tr>
157 <tr>
158 <td><code>delete_event_mark()</code></td>
159 <td>Removes an event from some event group.</td>
160 </tr>
161 <tr>
162 <td><code>by_marks()</code></td>
163 <td>Returns all events of an event group.</td>
164 </tr>
165 </table>
166
167 <h3>GigaStudio Format Functions</h3>
168 <p>
169 Sampler format specific functions, dedicated to the individual features
170 of the GigaStudio format engine.
171 </p>
172 <table>
173 <tr>
174 <th>Function</th> <th>Description</th>
175 </tr>
176 <tr>
177 <td><code>gig_set_dim_zone()</code></td>
178 <td>Changes the currently active dimension zone.</td>
179 </tr>
180 </table>
181
182 <h2>Built-In Variables</h2>
183 <p>
184 These are the built-in variables and built-in constants available with the
185 NKSP realt-time instrument script language.
186 </p>
187
188 <h3>Core Language Variables</h3>
189 <p>
190 Most fundamental NKSP built-in variables, independent from any purpose of
191 being used in a sampler.
192 </p>
193 <table>
194 <tr>
195 <th>Variable</th> <th>Description</th>
196 </tr>
197 <tr>
198 <td><code>$KSP_TIMER</code></td>
199 <td>Preserved for compatiblity reasons with KSP, returns the same value
200 as <code>$NKSP_REAL_TIMER</code> (refer to the latter for details).
201 Note that KSP's <code>reset_ksp_timer()</code> function is not available with
202 NKSP. However when calculating time differences between two time
203 stamps taken with <code>$NKSP_REAL_TIMER</code>, calling such a reset
204 function is not required, because the underlying clock does not stop
205 when it reached its value limit (which happens every 71 minutes), instead the clock
206 will automatically restart from zero and the calculated time difference
207 even between such transitions will reflect correct durations.</td>
208 </tr>
209 <tr>
210 <td><code>$NKSP_PERF_TIMER</code></td>
211 <td>Returns the current performance time stamp (in microseconds) of the
212 script running. You may read this variable from time to time to take
213 time stamps which can be used to calculate the time difference
214 (in microseconds) which elapsed between them. A performance time
215 stamp is based on the script's actual CPU execution time. So the
216 internal clock which is used for generating such time stamps is only
217 running forward if the respective script is actually executed by the
218 CPU. Whenever your script is not really executed by the CPU (i.e. because
219 your script got suspended by a wait() call or got forcely suspended due to
220 real-time constraints, or when the entire sampler application got suspended
221 by the OS for other applications or OS tasks) then the underlying internal
222 clock is paused as well.
223 <note class="important">
224 You should only use this built-in variable for script development
225 purposes (i.e. for bench marking the performance of your script).
226 You should <b>not</b> use it with your final production sounds!
227 It is not appropriate for being used in a musical context, because
228 when an offline bounce is performed for instance, the musical timing
229 will be completely unrelated to the CPU execution time. Plus using
230 this variable may cause audio drop outs on some systems. In a musical
231 context you should use <code>$ENGINE_UPTIME</code> instead, which is
232 also safe for offline bounces.
233 </note>
234 <note>
235 On some systems <code>$NKSP_REAL_TIMER</code> and
236 <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
237 difference between them is not implemented for all systems at the moment.
238 </note>
239 </td>
240 </tr>
241 <tr>
242 <td><code>$NKSP_REAL_TIMER</code></td>
243 <td>Returns the current time stamp in reality (in microseconds). You may
244 read this variable from time to time to take
245 time stamps which can be used to calculate the time difference
246 (in microseconds) which elapsed between them. A "real" time
247 stamp is based on an internal clock which constantly proceeds, so this
248 internal clock also continues counting while your script is either suspended
249 (i.e. because your script got suspended by a wait() call or got forcely
250 suspended due to real-time constraints) and it also continues counting
251 even if the entire sampler application got suspended by the OS (i.e. to
252 execute other applications for multi-tasking or to perform OS tasks).
253 <note class="important">
254 You should only use this built-in variable for script development
255 purposes (i.e. for bench marking the performance of your script).
256 You should <b>not</b> use it with your final production sounds!
257 It is not appropriate for being used in a musical context, because
258 when an offline bounce is performed for instance, the musical timing
259 will be completely unrelated to the CPU execution time. Plus using
260 this variable may cause audio drop outs on some systems. In a musical
261 context you should use <code>$ENGINE_UPTIME</code> instead, which is
262 also safe for offline bounces.
263 </note>
264 <note>
265 On some systems <code>$NKSP_REAL_TIMER</code> and
266 <code>$NKSP_PERF_TIMER</code> will actually return the same value. So the
267 difference between them is not implemented for all systems at the moment.
268 </note>
269 </td>
270 </tr>
271 <tr>
272 <td><code>$NI_CALLBACK_ID</code></td>
273 <td>Reflects the current event handler instance's unique callback ID.
274 For the same event type there may be more than
275 one event handler instances running. Each one of them has
276 its own callback ID. You can get the current event handler
277 instance's callback ID by reading this built-in variable.</td>
278 </tr>
279 <tr>
280 <td><code>$NI_CALLBACK_TYPE</code></td>
281 <td>Reflects the event type of the current event handler. This variable
282 may reflect one of the following built-in constants:
283 <code>$NI_CB_TYPE_INIT</code>, <code>$NI_CB_TYPE_NOTE</code>,
284 <code>$NI_CB_TYPE_RELEASE</code>, <code>$NI_CB_TYPE_CONTROLLER</code>.</td>
285 </tr>
286 <tr>
287 <td><code>$NI_CB_TYPE_INIT</code></td>
288 <td>Built-in constant reflecting an <code>init</code> event handler type.</td>
289 </tr>
290 <tr>
291 <td><code>$NI_CB_TYPE_NOTE</code></td>
292 <td>Built-in constant reflecting a <code>note</code> event handler type.</td>
293 </tr>
294 <tr>
295 <td><code>$NI_CB_TYPE_RELEASE</code></td>
296 <td>Built-in constant reflecting a <code>release</code> event handler type.</td>
297 </tr>
298 <tr>
299 <td><code>$NI_CB_TYPE_CONTROLLER</code></td>
300 <td>Built-in constant reflecting a <code>controller</code> event handler type.</td>
301 </tr>
302 <tr>
303 <td><code>$NKSP_IGNORE_WAIT</code></td>
304 <td>If this boolean built-in variable is <code>1</code> then all calls of your
305 event handler instance to function <code>wait()</code> will be ignored.
306 This may for example be the case if another event handler instance
307 resumed your paused script by calling <code>stop_wait()</code> and
308 passing <code>1</code> to the 2nd argument of that function.</td>
309 </tr>
310 </table>
311
312 <h3>Common Sampler Variables</h3>
313 <p>
314 Basic sampler related built-in variables and constants, independent from a
315 particular sampler format or sampler engine.
316 </p>
317 <table>
318 <tr>
319 <th>Variable</th> <th>Description</th>
320 </tr>
321 <tr>
322 <td><code>%ALL_EVENTS</code></td>
323 <td>
324 Note IDs of all currently active notes of the current sampler part (a.k.a. sampler channel).
325 This may be passed to many built-in functions like <code>note_off()</code>.
326 This array variable only contains IDs of notes which were launched due
327 to MIDI note-on events. This variable does not contain IDs of child notes
328 (i.e. notes which were launched programmatically by calling <code>note_on()</code>).
329 <note>
330 In contrast to KSP this variable is an integer array type, whereas KSP's
331 pendent of this built-in variable is an integer constant (scalar) called
332 <code>$ALL_EVENTS</code>. Using the latter with NKSP will cause a
333 parser warning, the behavior will be the same though.
334 </note>
335 </td>
336 </tr>
337 <tr>
338 <td><code>$CC_NUM</code></td>
339 <td>MIDI controller number that caused the <code>controller</code>
340 handler to be executed (only useful in the context of a
341 <code>controller</code> handler).</td>
342 </tr>
343 <tr>
344 <td><code>%CC[]</code></td>
345 <td>Provides access to all current MIDI controller values. This can be
346 used in any context. Use the respective MIDI controller number as
347 index to this integer array variable. For instance <code>%CC[1]</code>
348 would give you the current value of the modulation wheel.
349 </td>
350 </tr>
351 <tr>
352 <td><code>$EVENT_ID</code></td>
353 <td>ID of the event that caused the current event handler to be executed. In
354 the context of a <code>note</code> handler this would be the event
355 ID of the note, within a <code>controller</code> handler it would
356 be the controller event ID, etc.</td>
357 </tr>
358 <tr>
359 <td><code>$EVENT_NOTE</code></td>
360 <td>MIDI note number that caused a note related
361 handler to be executed (only useful in the context of a
362 <code>note</code> or <code>release</code> handler).</td>
363 </tr>
364 <tr>
365 <td><code>$EVENT_VELOCITY</code></td>
366 <td>MIDI velocity value of the note that caused that note related
367 handler to be executed (only useful in the context of a
368 <code>note</code> or <code>release</code> handler).</td>
369 </tr>
370 <tr>
371 <td><code>$EVENT_STATUS_INACTIVE</code></td>
372 <td>Constant bit flag used as possible return value by
373 <code>event_status()</code> in case the requested
374 note is not "alive".</td>
375 </tr>
376 <tr>
377 <td><code>$EVENT_STATUS_NOTE_QUEUE</code></td>
378 <td>Constant bit flag used as possible return value by
379 <code>event_status()</code> in case the requested
380 note is still "alive".</td>
381 </tr>
382 <tr>
383 <td><code>%KEY_DOWN[]</code></td>
384 <td>This can be used in any context to check whether a certain MIDI
385 key is currently pressed down. Use the respective MIDI note number
386 as index to this array variable (see also <code>event_status()</code>).</td>
387 </tr>
388 <tr>
389 <td><code>$VCC_MONO_AT</code></td>
390 <td>Constant identifying the MIDI monophonic aftertouch controller (also
391 called <i title="Amount of force on held-down key.">
392 MIDI channel pressure
393 </i>). This is somewhat different than in the MIDI standard. With
394 NKSP aftertouch is handled like an additional "regular" MIDI CC controller.
395 Therefore use
396 <code>%CC[$VCC_MONO_AT]</code> to obtain the current aftertouch value
397 in the context of a <code>controller</code> event handler.
398 </td>
399 </tr>
400 <tr>
401 <td><code>$VCC_PITCH_BEND</code></td>
402 <td>Constant identifying the pitch bend wheel controller.
403 This is somewhat different than in the MIDI standard. With
404 NKSP pitch bend is handled like an additional "regular" MIDI CC controller.
405 Therefore use
406 <code>%CC[$VCC_PITCH_BEND]</code> to obtain the current pitch bend wheel value
407 in the context of a <code>controller</code> event handler.</td>
408 </tr>
409 <tr>
410 <td><code>$MARK_1</code> to <code>$MARK_28</code></td>
411 <td>Used to select one of the available 28 event groups.
412 See <code>set_event_mark()</code> for details.</td>
413 </tr>
414 <tr>
415 <td><code>$ENGINE_UPTIME</code></td>
416 <td>Returns the current time stamp (in milliseconds) for being
417 used in a musical context. You may read this variable from time to time
418 to take time stamps which can be used to calculate the time difference
419 (in milliseconds) which elapsed between them. These timing values are
420 based on the internal sample rate and thus it can safely be used to
421 perform musical timing related tasks in your scripts. Especially
422 your script will also continue to behave correctly when an offline bounce
423 of a song is performed.
424 </td>
425 </tr>
426 </table>
427
428 <h3>GigaStudio Format Variables</h3>
429 <p>
430 Sampler format specific built-in variables and constants, dedicated to the
431 individual features of the GigaStudio format engine.
432 </p>
433 <table>
434 <tr>
435 <th>Variable</th> <th>Description</th>
436 </tr>
437 <tr>
438 <td><code>$GIG_DIM_CHANNEL</code></td>
439 <td>Constant that identifies the <i>stereo dimension</i>.</td>
440 </tr>
441 <tr>
442 <td><code>$GIG_DIM_LAYER</code></td>
443 <td>Constant that identifies the <i>layer dimension</i>.</td>
444 </tr>
445 <tr>
446 <td><code>$GIG_DIM_VELOCITY</code></td>
447 <td>Constant that identifies the <i>velocity dimension</i>.</td>
448 </tr>
449 <tr>
450 <td><code>$GIG_DIM_AFTERTOUCH</code></td>
451 <td>Constant that identifies the <i>aftertouch dimension</i>.</td>
452 </tr>
453 <tr>
454 <td><code>$GIG_DIM_RELEASE</code></td>
455 <td>Constant that identifies the <i>release trigger dimension</i>.</td>
456 </tr>
457 <tr>
458 <td><code>$GIG_DIM_KEYBOARD</code></td>
459 <td>Constant that identifies the <i>keyboard position dimension</i>.</td>
460 </tr>
461 <tr>
462 <td><code>$GIG_DIM_ROUNDROBIN"</code></td>
463 <td>Constant that identifies the <i>round robin dimension</i>.</td>
464 </tr>
465 <tr>
466 <td><code>$GIG_DIM_RANDOM</code></td>
467 <td>Constant that identifies the <i>random dimension</i>.</td>
468 </tr>
469 <tr>
470 <td><code>$GIG_DIM_SMARTMIDI</code></td>
471 <td>Constant that identifies the <i>start MIDI dimension</i> (a.k.a iMIDI rules).</td>
472 </tr>
473 <tr>
474 <td><code>$GIG_DIM_ROUNDROBINKEY</code></td>
475 <td>Constant that identifies the <i>round robin key dimension</i>.</td>
476 </tr>
477 <tr>
478 <td><code>$GIG_DIM_MODWHEEL</code></td>
479 <td>Constant that identifies the <i>modulation wheel dimension</i>.</td>
480 </tr>
481 <tr>
482 <td><code>$GIG_DIM_SUSTAIN</code></td>
483 <td>Constant that identifies the <i>sustain pedal dimension</i> (a.k.a. hold pedal).</td>
484 </tr>
485 <tr>
486 <td><code>$GIG_DIM_PORTAMENTO</code></td>
487 <td>Constant that identifies the <i>portamento MIDI controller dimension</i>.</td>
488 </tr>
489 <tr>
490 <td><code>$GIG_DIM_SOSTENUTO</code></td>
491 <td>Constant that identifies the <i>sostenuto MIDI controller dimension</i>.</td>
492 </tr>
493 <tr>
494 <td><code>$GIG_DIM_SOFT</code></td>
495 <td>Constant that identifies the <i>soft pedal dimension</i>.</td>
496 </tr>
497 <tr>
498 <td><code>$GIG_DIM_BREATH</code></td>
499 <td>Constant that identifies the <i>breath controller dimension</i>.</td>
500 </tr>
501 <tr>
502 <td><code>$GIG_DIM_FOOT</code></td>
503 <td>Constant that identifies the <i>foot pedal dimension</i>.</td>
504 </tr>
505 <tr>
506 <td><code>$GIG_DIM_PORTAMENTOTIME</code></td>
507 <td>Constant that identifies the <i>portamento time controller dimension</i>.</td>
508 </tr>
509 <tr>
510 <td><code>$GIG_DIM_EFFECT1</code></td>
511 <td>Constant that identifies the <i>effect 1 MIDI controller dimension</i>.</td>
512 </tr>
513 <tr>
514 <td><code>$GIG_DIM_EFFECT2</code></td>
515 <td>Constant that identifies the <i>effect 2 MIDI controller dimension</i>.</td>
516 </tr>
517 <tr>
518 <td><code>$GIG_DIM_EFFECT1DEPTH</code></td>
519 <td>Constant that identifies the <i>effect 1 depth MIDI controller dimension</i>.</td>
520 </tr>
521 <tr>
522 <td><code>$GIG_DIM_EFFECT2DEPTH</code></td>
523 <td>Constant that identifies the <i>effect 2 depth MIDI controller dimension</i>.</td>
524 </tr>
525 <tr>
526 <td><code>$GIG_DIM_EFFECT3DEPTH</code></td>
527 <td>Constant that identifies the <i>effect 3 depth MIDI controller dimension</i>.</td>
528 </tr>
529 <tr>
530 <td><code>$GIG_DIM_EFFECT4DEPTH</code></td>
531 <td>Constant that identifies the <i>effect 4 depth MIDI controller dimension</i>.</td>
532 </tr>
533 <tr>
534 <td><code>$GIG_DIM_EFFECT5DEPTH</code></td>
535 <td>Constant that identifies the <i>effect 5 depth MIDI controller dimension</i>.</td>
536 </tr>
537 <tr>
538 <td><code>$GIG_DIM_GENPURPOSE1</code></td>
539 <td>Constant that identifies the <i>general purpose 1 MIDI controller dimension</i>.</td>
540 </tr>
541 <tr>
542 <td><code>$GIG_DIM_GENPURPOSE2</code></td>
543 <td>Constant that identifies the <i>general purpose 2 MIDI controller dimension</i>.</td>
544 </tr>
545 <tr>
546 <td><code>$GIG_DIM_GENPURPOSE3</code></td>
547 <td>Constant that identifies the <i>general purpose 3 MIDI controller dimension</i>.</td>
548 </tr>
549 <tr>
550 <td><code>$GIG_DIM_GENPURPOSE4</code></td>
551 <td>Constant that identifies the <i>general purpose 4 MIDI controller dimension</i>.</td>
552 </tr>
553 <tr>
554 <td><code>$GIG_DIM_GENPURPOSE5</code></td>
555 <td>Constant that identifies the <i>general purpose 5 MIDI controller dimension</i>.</td>
556 </tr>
557 <tr>
558 <td><code>$GIG_DIM_GENPURPOSE6</code></td>
559 <td>Constant that identifies the <i>general purpose 6 MIDI controller dimension</i>.</td>
560 </tr>
561 <tr>
562 <td><code>$GIG_DIM_GENPURPOSE7</code></td>
563 <td>Constant that identifies the <i>general purpose 7 MIDI controller dimension</i>.</td>
564 </tr>
565 <tr>
566 <td><code>$GIG_DIM_GENPURPOSE8</code></td>
567 <td>Constant that identifies the <i>general purpose 8 MIDI controller dimension</i>.</td>
568 </tr>
569 </table>
570
571 </body>
572 </html>

  ViewVC Help
Powered by ViewVC