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.


on note
  while (1)
    wait(200000)
    if (event_status($EVENT_ID) = $EVENT_STATUS_INACTIVE)
      exit() { note is no longer alive, so stop script here }
    end if
    change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }

    wait(200000)
    if (event_status($EVENT_ID) = $EVENT_STATUS_INACTIVE)
      exit() { note is no longer alive, so stop script here }
    end if
    change_vol($EVENT_ID, 0)  { Increase volume to 0 dB. }
  end while
end on

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:


on note
  while (1)
    wait(200000)
    if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
      exit() { note is no longer alive, so stop script here }
    end if
    change_vol($EVENT_ID, -20000)  { Reduce volume by 20 dB. }

    wait(200000)
    if (not (event_status($EVENT_ID) .and. $EVENT_STATUS_NOTE_QUEUE))
      exit() { note is no longer alive, so stop script here }
    end if
    change_vol($EVENT_ID, 0)  { Increase volume to 0 dB. }
  end while
end on

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!

Availabilty

Since LinuxSampler 2.0.0.svn12.

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