Documents
Writing Docs Gigedit SFZ Instrument Scripts NKSP Language NKSP Reference

event_status()

Checks and returns the current status of the requested note. You can use this function to check if a note is still "alive". A note is considered "alive" as long as there are still active voices associated with it, which might for example still be the case even long time after the respective note's key had been released by the musician (i.e. because the voice uses a very long release envelope stage).

If you are rather just interested whether a certain note key is currently pressed down, then you can read the built-in array variable %KEY_DOWN[] instead.

Function Prototype

event_status(note)

Arguments

Argument Name Data Type Description
note Note ID Number Status of this note will be checked.
[required]

Return Value

Returns either $EVENT_STATUS_INACTIVE if the requested note is already dead and gone, or $EVENT_STATUS_NOTE_QUEUE if the note is still alive.

Even though there are currently just two possible return values, $EVENT_STATUS_NOTE_QUEUE is defined as bit flag though, and since other bit flags might be added in future you should only compare bitwise with $EVENT_STATUS_NOTE_QUEUE. See example below.

Examples

The following example shows a simple stuttering effect. The script runs in an endless loop and turns down and up the volume all 200ms. To stop the endless loop once the respective note died, the return value of event_status() is compared with built-in constant bit flag $EVENT_STATUS_INACTIVE.

Note: since the built-in constants returned by this function are actually bit flags, and since further bit flags might be added in future for this function, the actual long-term safe and correct way to check the return value of event_status() is a bitwise comparison. So the recommended "correct" way for the example above would actually be:

In practice however, the first version of this example is much easier to read (and write) though, and new bit flags will probably not be added to this function in near future. But that's up to you to decide!

Availability

Since LinuxSampler 2.0.0.svn12.

See also

callback_status()

LinuxSampler does currently not support KSP's $EVENT_STATUS_MIDI_QUEUE flag as return value.

Document Updated:  2017-06-28  |  Author:  Christian Schoenebeck