reference/functions/nksp_change_play_pos_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>change_play_pos() function</title>
    <meta name="description" content="Change the sample playback position.">
  </head>
  <body>
    <h1>change_play_pos()</h1>
    <p>
      This function can be used to change the sample playback position of the
      voices of the requested note. You need to pass the note ID of the voices
      you want to alter. This function will change the sample playback position
      of all voices associated with the requested note.
    </p>
    <p>
      At the moment you may only use this function for new notes.
      That effectively means you should change the sample playback position with
      this function before any <code lang="nksp">wait()</code> calls, and before
      entering any loops that may execute your script for a very long time.
      Using this function for notes which alreay play for a while does not raise an error,
      but calling this function will simply be ignored for such older notes, and
      thus will have no effect. This current limitation might change in future.
    </p>

    <note class="important">
      In case the respective sample is using disk streaming, then you might be
      limited to set the new playback position somwehere within a certain
      range at the beginning of the sample (i.e. less than several hundred
      milliseconds from sample start). The precise range depends on the
      sampler configuration and the sampler format engine being used.
      Setting a position beyond that maximum position might either cause your
      position to be automatically corrected by the sampler, or that the resulting
      voices will not play at all.
    </note>

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
change_play_pos(??note??, ??position-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>Note ID Number</td>
        <td>All voices of this note will be modified.<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??position-us??</code></td>
        <td>Integer&nbsp;Number&nbsp;or<br>
            Real&nbsp;Number</td>
        <td>New sample playback position in micro seconds from sample start.<br>
            [required]</td>
      </tr>
    </table>

    <h3>Return Value</h3>
    <p>None.</p>

    <h3>Remarks</h3>
    <p>
      This functions optionally accepts <code>s</code> as standard unit
      for its argument <code>??position-us??</code>.
    </p>

    <h3>Examples</h3>
    <p>None yet.<p>

    <h3>See also</h3>
    <p><code>play_note()</code><p>

    <h3>Availability</h3>
    <p>Since LinuxSampler 2.0.0.svn57.<p>

    <note>
    This function exists only with NKSP, it is not available with KSP.
    </note>

  </body>
</html>
1	schoenebeck	3256	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>change_play_pos() function</title>
5			<meta name="description" content="Change the sample playback position.">
6			</head>
7			<body>
8			<h1>change_play_pos()</h1>
9			<p>
10			This function can be used to change the sample playback position of the
11			voices of the requested note. You need to pass the note ID of the voices
12			you want to alter. This function will change the sample playback position
13			of all voices associated with the requested note.
14			</p>
15			<p>
16			At the moment you may only use this function for new notes.
17			That effectively means you should change the sample playback position with
18			this function before any <code lang="nksp">wait()</code> calls, and before
19			entering any loops that may execute your script for a very long time.
20			Using this function for notes which alreay play for a while does not raise an error,
21			but calling this function will simply be ignored for such older notes, and
22			thus will have no effect. This current limitation might change in future.
23			</p>
24
25			<note class="important">
26			In case the respective sample is using disk streaming, then you might be
27			limited to set the new playback position somwehere within a certain
28			range at the beginning of the sample (i.e. less than several hundred
29			milliseconds from sample start). The precise range depends on the
30			sampler configuration and the sampler format engine being used.
31			Setting a position beyond that maximum position might either cause your
32			position to be automatically corrected by the sampler, or that the resulting
33			voices will not play at all.
34			</note>
35
36			<h3>Function Prototype</h3>
37			<p/>
38			<code lang="nksp">
39			change_play_pos(??note??, ??position-us??)
40			</code>
41
42			<h3>Arguments</h3>
43			<table>
44			<tr>
45			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
46			</tr>
47			<tr>
48			<td><code>??note??</code></td>
49			<td>Note ID Number</td>
50			<td>All voices of this note will be modified.<br>
51			[required]</td>
52			</tr>
53			<tr>
54			<td><code>??position-us??</code></td>
55	schoenebeck	3601	<td>Integer Number or<br>
56			Real Number</td>
57	schoenebeck	3256	<td>New sample playback position in micro seconds from sample start.<br>
58			[required]</td>
59			</tr>
60			</table>
61
62			<h3>Return Value</h3>
63			<p>None.</p>
64
65	schoenebeck	3601	<h3>Remarks</h3>
66			<p>
67			This functions optionally accepts <code>s</code> as standard unit
68			for its argument <code>??position-us??</code>.
69			</p>
70
71	schoenebeck	3256	<h3>Examples</h3>
72			<p>None yet.<p>
73
74			<h3>See also</h3>
75			<p><code>play_note()</code><p>
76
77			<h3>Availability</h3>
78			<p>Since LinuxSampler 2.0.0.svn57.<p>
79
80			<note>
81			This function exists only with NKSP, it is not available with KSP.
82			</note>
83
84			</body>
85			</html>