reference/functions/nksp_play_note_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>play_note() function</title>
    <meta name="description" content="Triggers a new note.">
  </head>
  <body>
    <h1>play_note()</h1>
    <p>
      Triggers a new note to be played by the sampler. This is like generating
      a new MIDI note-on event programmatically, with the difference though
      that triggering a note programmatically this way does not cause a
      <code>note</code> event handler to be executed for the new note.
    </p>
    
    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
play_note(??note??, [??velocity??], [??offset-us??], [??duration-us??])
    </code>

    <h3>Arguments</h3>
    <table>
      <tr>
        <th>Argument Name</th> <th>Data Type</th> <th>Description</th>
      </tr>
      <tr>
        <td><code>??note??</code></td>
        <td>Integer Number</td>
        <td>Note number (absolute pitch).<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??velocity??</code></td>
        <td>Integer Number</td>
        <td>Trigger velocity.<br>
            [optional, default: 127]</td>
      </tr>
      <tr>
        <td><code>??offset-us??</code></td>
        <td>Integer Number</td>
        <td>Start offset of the sample to be played in microseconds.<br>
            [optional, default: 0]</td>
      </tr>
      <tr>
        <td><code>??duration-us??</code></td>
        <td>Integer Number</td>
        <td>Length of the note to be played in microseconds.<br>
            -1: The note will be stopped when the event
                handler's note stops (must only be used with
                <code>note</code> event handlers).<br>
            0: The entire note's sample will be played to its end.<br>
            [optional, default: 0]</td>
      </tr>
    </table>

    <note>
    You need at least LinuxSampler 2.0.0.svn2 or higher for passing a value
    higher than <code>0</code> for <code>??duration-us??</code>, and you need
    at least LinuxSampler 2.0.0.svn3 or higher for passing <code>-1</code> for
    <code>??duration-us??</code>.
    </note>

    <note class="important">
    Passing any other value than <code>0</code> for <code>??offset-us??</code>
    is not supported by LinuxSampler yet.
    </note>

    <h3>Return Value</h3>
    <table>
      <tr>
        <th>Description</th> <th>Data Type</th>
      </tr>
      <tr>
        <td>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.</td>
        <td>Event ID Number</td>
      </tr>
    </table>
    
    <h3>Examples</h3>
    <p/>
    <code>
on init
  { The amount of notes to play }
  declare const $delayNotes := 4
  { Tempo with which the new notes will follow the orignal note }
  declare const $bpm := 90
  { Convert BPM to microseconds (duration between the notes) }
  declare const $delayMicroSeconds := 60 * 1000000 / $bpm
  { Just a working variable for being used with the while loop below }
  declare polyphonic $i
  { For each successive note we trigger, we will reduce the velocity a bit}
  declare polyphonic $velocity
end on

on note
  { First initialize the variable $i with 4 each time we enter this event
    handler, because each time we executed this handler, the variable will be 0 }
  $i := $delayNotes

  { Loop which will be executed 4 times in a row }
  while ($i)
    { Calculate the velocity for the next note being triggered }
    $velocity := 127 * $i / ($delayNotes + 1)
    { Suspend this script for a short moment ... }
    wait($delayMicroSeconds)
    { ... and after that short break, trigger a new note. }
    play_note($EVENT_NOTE, $velocity)
    { Decrement loop counter $i by one }
    $i := $i - 1
  end while
end on
    </code>

  </body>
</html>
1	schoenebeck	2732	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>play_note() function</title>
5			<meta name="description" content="Triggers a new note.">
6			</head>
7			<body>
8			<h1>play_note()</h1>
9			<p>
10			Triggers a new note to be played by the sampler. This is like generating
11	schoenebeck	2881	a new MIDI note-on event programmatically, with the difference though
12			that triggering a note programmatically this way does not cause a
13			<code>note</code> event handler to be executed for the new note.
14	schoenebeck	2732	</p>
15
16			<h3>Function Prototype</h3>
17			<p/>
18	schoenebeck	2742	<code lang="nksp">
19	schoenebeck	2732	play_note(??note??, [??velocity??], [??offset-us??], [??duration-us??])
20			</code>
21
22			<h3>Arguments</h3>
23			<table>
24			<tr>
25			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
26			</tr>
27			<tr>
28			<td><code>??note??</code></td>
29			<td>Integer Number</td>
30			<td>Note number (absolute pitch).<br>
31			[required]</td>
32			</tr>
33			<tr>
34			<td><code>??velocity??</code></td>
35			<td>Integer Number</td>
36			<td>Trigger velocity.<br>
37			[optional, default: 127]</td>
38			</tr>
39			<tr>
40			<td><code>??offset-us??</code></td>
41			<td>Integer Number</td>
42			<td>Start offset of the sample to be played in microseconds.<br>
43			[optional, default: 0]</td>
44			</tr>
45			<tr>
46			<td><code>??duration-us??</code></td>
47			<td>Integer Number</td>
48			<td>Length of the note to be played in microseconds.<br>
49			-1: The note will be stopped when the event
50	schoenebeck	2881	handler's note stops (must only be used with
51			<code>note</code> event handlers).<br>
52	schoenebeck	2732	0: The entire note's sample will be played to its end.<br>
53			[optional, default: 0]</td>
54			</tr>
55			</table>
56
57	schoenebeck	2872	<note>
58			You need at least LinuxSampler 2.0.0.svn2 or higher for passing a value
59	schoenebeck	2881	higher than <code>0</code> for <code>??duration-us??</code>, and you need
60			at least LinuxSampler 2.0.0.svn3 or higher for passing <code>-1</code> for
61			<code>??duration-us??</code>.
62	schoenebeck	2872	</note>
63
64	schoenebeck	2732	<note class="important">
65	schoenebeck	2881	Passing any other value than <code>0</code> for <code>??offset-us??</code>
66			is not supported by LinuxSampler yet.
67	schoenebeck	2732	</note>
68	schoenebeck	2872
69	schoenebeck	2732	<h3>Return Value</h3>
70			<table>
71			<tr>
72			<th>Description</th> <th>Data Type</th>
73			</tr>
74			<tr>
75			<td>Note's event ID of the new note that has been triggered. This event ID can be
76			used to control the note during its life time.</td>
77			<td>Event ID Number</td>
78			</tr>
79			</table>
80
81			<h3>Examples</h3>
82			<p/>
83			<code>
84			on init
85			{ The amount of notes to play }
86			declare const $delayNotes := 4
87			{ Tempo with which the new notes will follow the orignal note }
88			declare const $bpm := 90
89			{ Convert BPM to microseconds (duration between the notes) }
90			declare const $delayMicroSeconds := 60 * 1000000 / $bpm
91			{ Just a working variable for being used with the while loop below }
92			declare polyphonic $i
93			{ For each successive note we trigger, we will reduce the velocity a bit}
94			declare polyphonic $velocity
95			end on
96
97			on note
98			{ First initialize the variable $i with 4 each time we enter this event
99			handler, because each time we executed this handler, the variable will be 0 }
100			$i := $delayNotes
101
102			{ Loop which will be executed 4 times in a row }
103			while ($i)
104			{ Calculate the velocity for the next note being triggered }
105			$velocity := 127 * $i / ($delayNotes + 1)
106			{ Suspend this script for a short moment ... }
107			wait($delayMicroSeconds)
108			{ ... and after that short break, trigger a new note. }
109			play_note($EVENT_NOTE, $velocity)
110			{ Decrement loop counter $i by one }
111			$i := $i - 1
112			end while
113			end on
114			</code>
115
116			</body>
117			</html>