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

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

Parent Directory Parent Directory | Revision Log Revision Log


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

1 schoenebeck 2732 <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 schoenebeck 2946 <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 schoenebeck 3077 <td><code>in_range()</code></td>
40     <td>Checks whether a value is between two other values.</td>
41     </tr>
42     <tr>
43 schoenebeck 2742 <td><code lang="nksp">message()</code></td>
44 schoenebeck 2732 <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 schoenebeck 2949 <td><code>stop_wait()</code></td>
56     <td>Resumes execution of a suspended script callback.</td>
57     </tr>
58     <tr>
59 schoenebeck 2732 <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 schoenebeck 2971 <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 schoenebeck 2732 <td><code>num_elements()</code></td>
76     <td>Returns the size of the requested array variable.</td>
77     </tr>
78 schoenebeck 2966 <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 schoenebeck 2732 </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 schoenebeck 2932 <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 schoenebeck 2936 <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 schoenebeck 2954 <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 schoenebeck 2936 <td><code>event_status()</code></td>
135     <td>Checks and returns whether a particular note is still alive.</td>
136     </tr>
137     <tr>
138 schoenebeck 2732 <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 schoenebeck 2944
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 schoenebeck 2949 <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 schoenebeck 2944 </table>
311    
312 schoenebeck 2732 <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 schoenebeck 3074 <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 schoenebeck 3077 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 schoenebeck 3074 <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 schoenebeck 3075 <code>$ALL_EVENTS</code>. Using the latter with NKSP will cause a
333 schoenebeck 3074 parser warning, the behavior will be the same though.
334     </note>
335     </td>
336     </tr>
337     <tr>
338 schoenebeck 2732 <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 schoenebeck 2937 <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 schoenebeck 2732 <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 schoenebeck 2936 as index to this array variable (see also <code>event_status()</code>).</td>
387 schoenebeck 2732 </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 schoenebeck 2936 <code>%CC[$VCC_PITCH_BEND]</code> to obtain the current pitch bend wheel value
407 schoenebeck 2732 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 schoenebeck 2944 <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 schoenebeck 2732 </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