- KSP Reference Manual
- Time-Related Commands
Time-Related Commands
change_listener_par()
| |
|---|---|
Changes the parameters of the | |
| The signal to be changed, can be:
|
| Dependent on the specified signal type:
|
Remarks
It is also possible to completely disable a particular listener signal by setting
<parameter>to 0.
Examples
on init
declare ui_value_edit $Tempo (20, 300, 1)
declare ui_switch $Play
make_persistent($Tempo)
read_persistent_var($Tempo)
$Tempo := 120
set_listener($NI_SIGNAL_TIMER_MS, 60000000 / $Tempo)
end on
on listener
if ($NI_SIGNAL_TYPE = $NI_SIGNAL_TIMER_MS and $Play = 1)
play_note(60, 127, 0, $DURATION_EIGHTH)
end if
end on
on ui_control($Tempo)
change_listener_par($NI_SIGNAL_TIMER_MS, 60000000 / $Tempo)
end on
A very basic metronome.
See Also
Callbacks and UI: $NI_SIGNAL_TYPE
ms_to_ticks()
|
|---|
Converts a microseconds value into a value in tempo-dependent MIDI ticks. |
Examples
on init
declare ui_label $bpm (1, 1)
set_text($bpm, ms_to_ticks(60000000) / 960)
end on
Displaying the current host tempo.
See Also
Time and Transport: $NI_SONG_POSITION
set_listener()
| |
|---|---|
Sets the signals on which the listener callback should react to. Can only be used in the | |
| The event on which the listener callback should react. The following types are available:
|
| User defined parameter, dependant on the specified signal type:
|
Remarks
When using
$NI_SIGNAL_TIMER_BEAT, the maximum resolution is 24 ticks per beat/quarter note.
Examples
on init
set_listener($NI_SIGNAL_TIMER_BEAT, 1)
end on
on listener
if ($NI_SIGNAL_TYPE = $NI_SIGNAL_TIMER_BEAT)
message($ENGINE_UPTIME)
end if
end on
Triggering the listener callback every beat. Triggering will occur even when transport is stopped.
See Also
Callbacks and UI: $NI_SIGNAL_TYPE
stop_wait()
| |
|---|---|
Stops wait commands in the specified callback. | |
| The callback’s ID number in which the wait commands will be stopped. |
| 0: stops only the current wait. 1: stops the current wait and ignores all following wait commands in this callback. |
Remarks
Be careful with while loops when stopping all
wait()commands in a callback!
Examples
on init
declare $id
declare ui_button $Play
end on
on ui_control ($Play)
if ($Play = 1)
$id := $NI_CALLBACK_ID
play_note(60, 127, 0, $DURATION_QUARTER)
wait($DURATION_QUARTER)
if ($Play = 1)
play_note(64, 127, 0, $DURATION_QUARTER)
end if
wait($DURATION_QUARTER)
if ($Play = 1)
play_note(67, 127, 0, $DURATION_QUARTER)
end if
else
stop_wait($id, 1)
fade_out($ALL_EVENTS, 10000, 1)
end if
end on
The Play button triggers a simple triad arpeggio. Without the stop_wait() command, parallel callbacks could occur when pressing the Play button quickly in succession resulting in multiple arpeggios.
See Also
Callbacks and UI: Callback Type Variables and Constants
reset_ksp_timer
|
|---|
Resets the KSP timer built-in variable ( |
Remarks
Note that the
$KSP_TIMERvariable, due to its 32-bit signed nature, will reach its limit after 2147483648 microseconds, or roughly 35 minutes and 47 seconds.Since the KSP timer is based on the CPU clock, the main reason to use it is for debugging and optimization. It is a great tool to measure the efficiency of certain script passages. However, it should not be used for musical timing, as it remains at a real-time constant rate, even if Kontakt is being used in an offline bounce.
Examples
on init
declare $a
declare $b
declare $c
end on
on note
reset_ksp_timer
$c := 0
while ($c < 128)
$a := 0
while($a < 128)
set_event_par($EVENT_ID, $EVENT_PAR_TUNE, random(-1000, 1000))
inc($a)
end while
inc($c)
end while
message($KSP_TIMER)
end on
A nested while loop – takes about 5400 to 5800 microseconds.
See Also
Time and Transport: $ENGINE_UPTIME, $KSP_TIMER
ticks_to_ms()
|
|---|
Converts a tempo-dependent MIDI ticks value into a value in microseconds. |
Remarks
Since the returned value is in microseconds, note that due to its 32-bit signed nature it will not return correct values if specified number of ticks at the current tempo exceeds 2147483648 microseconds, or roughly 35 minutes and 47 seconds.
Examples
on init
declare $msec
declare $sec
declare $min
declare ui_label $label (2, 1)
set_listener($NI_SIGNAL_TIMER_MS, 1000)
end on
on listener
if ($NI_SIGNAL_TYPE = $NI_SIGNAL_TIMER_MS)
$msec := ticks_to_ms($NI_SONG_POSITION) / 1000
$sec := $msec / 1000
$min := $sec / 60
set_text($label, $min & ":" & $sec mod 60 & "." & $msec mod 1000)
end if
end on
Displaying the song position in realtime.
See Also
Time and Transport: $NI_SONG_POSITION
wait()
|
|---|
Pauses the callback for the specified time in microseconds. |
Remarks
wait()stops the callback at the position in the script for the specified time. In other words, it freezes the callback, although other callbacks can still be processed during this time. After the specified time, period the callback continues.
Examples
on note
ignore_event($EVENT_ID)
if ($DURATION_BAR = 0)
wait(($DURATION_QUARTER * 4) - $DISTANCE_BAR_START)
else
wait($DURATION_BAR - $DISTANCE_BAR_START)
end if
play_note($EVENT_NOTE, $EVENT_VELOCITY, 0, -1)
end on
Quantize all notes to the downbeat of the next measure. This script also takes care of the fact that in Kontakt standalone, $DURATION_BAR returns 0, so instead of that we use the quarter note duration to make up a 4/4 bar.
See Also
Time and Transport: $DURATION_QUARTER
wait_async()
|
|---|
Waits until the async command identified by the |
Remarks
When performing multiple operations it is also possible to collect them together and then calling the
wait_async()function on the collection. When the operations are collected in this manner they will be calculated in one block, resulting in a performance gain. If the async operation is not in the pipeline anymore or is invalid, there is no waiting and the script continues.
Examples
wait_async(set_engine_par($ENGINE_PAR_EFFECT_TYPE, ... $EFFECT_TYPE_CHORUS, -1, 2, 1))
Performing a single async operation.
%asyncid[0] := async_operation
%asyncid[1] := another_async_operation
...
%asyncid[x] := last_async_operation
$i := 0
while($i < num_elements(%asyncid))
wait_async(%asyncid[$i])
inc($i)
end whilePerforming multiple async operations.
See also
General: $NI_ASYNC_EXIT_STATUS, $NI_ASYNC_ID
wait_ticks()
|
|---|
Pauses the callback for the specified time in MIDI ticks. |
Remarks
Same as
wait()but with MIDI ticks as the wait time parameter.960 MIDI ticks equals one quarter note.