Writing Docs Gigedit SFZ Instrument Scripts NKSP Language NKSP Reference


Triggers a new note to be played by the sampler. This is almost like generating a new MIDI note-on event programmatically, with the difference though that triggering a note programmatically this way does not cause a note event handler to be executed for the new note, nor will any MIDI specific note-on handling be done (i.e. it will have no effect on key switching or on the status of built-in array variable %KEY_DOWN[]).

Function Prototype

play_note(note, [velocity], [offset-us], [duration-us])


Argument Name Data Type Description
note Integer Number Note number (absolute pitch).
velocity Integer Number Trigger velocity.
[optional, default: 127]
offset-us Integer Number or
Real Number
Start offset of the sample to be played in microseconds.
-1: Do not override the start offset and use the regular start offset as defined by the instrument file.
[optional, default: -1]
duration-us Integer Number or
Real Number
Length of the note to be played in microseconds.
0: The entire note's sample will be played to its end.
-1: The note will be stopped when the event handler's note stops (must only be used with note event handlers).
-2: The note will be stopped when a note-off event was received on the passed note number (argument 1).
[optional, default: 0]

Return Value

Data Type Description
Event ID Number Note's event ID of the new note that has been triggered. This event ID can be used to control the note during its life time.


This functions optionally accepts s as standard unit for its arguments offset-us and duration-us.


The following example resembles a simple delay effect. For each note being triggered by the musician, the script launches additional notes, each one of such additional successive notes with a more and more reduced volume.

See also

note_off(), set_controller(), change_note(), change_velo(), change_play_pos()


Since LinuxSampler 2.0.0

The special value -1 for offset-us only exists with NKSP, it is not available with KSP.

The special value -2 for duration-us only exists with NKSP, it is not available with KSP.

Dynamic, optional arguments are only supported by NKSP. If you want to retain compatibility to KSP, then you should always pass a value for all arguments of this function.

Document Updated:  2019-09-16  |  Author:  Christian Schoenebeck