reference/functions/nksp_change_tune_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>change_tune() function</title>
    <meta name="description" content="Modifies the tuning of voices of a particular note.">
  </head>
  <body>
    <h1>change_tune()</h1>
    <p>
      This function can be used to modify the tuning of active voices during
      their entire life time. So you may for example implement very sophisticated
      pitch envelopes by script by using this function. You need to pass the
      note ID of the voices you want to alter. This function will change the
      tuning of all active voices associated with the requested note. So if you
      are using a layered instrument patch, then it will change the tuning of
      all layers.
    </p>
    <p>
      Internally the sampler always fades the tuning from its current value to
      the new tuning as requested, however that tuning fade by default is so fast
      that it sounds like its value jumps directly from its old to the new value.
      You may also override that automated fade time explicitly by calling
      <code lang="nksp">change_tune_time()</code> before calling the
      <code lang="nksp">change_tune()</code> function.
    </p>
    <p>
      The tuning changes set by calling this function are always applied relatively to
      the tuning/pitch calculated by the synthesis model and sampler format. That means
      the various sources of tuning/pitch factors like MIDI pitch bend wheel, Pitch Envelopes,
      Pitch LFOs and other tuning factors that may be defined by the
      instrument patch, are always processed and calculated for the voices first,
      and the final pitch applied is always a relative combination of all those
      factors and the one set with this function call. This does also not change
      when you pass <code>1</code> for argument <code>??relative??</code>.
      Or in other words: you cannot replace the tuning/pitch set by other synthesis
      sources with this function.
    </p>

    <note class="important">
    Release Trigger Samples: In case the affected voices cause release trigger
    samples to be spawned later on, the tuning of those release trigger voices
    will not be affected by this function at all. So if you need to control the
    tuning of release trigger samples by script, then you might rather also trigger
    those release trigger samples by script with <code lang="nksp">play_note()</code>
    instead of using the sampler format's internal support for release trigger samples.
    </note>

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
change_tune(??note??, ??tuning??, [??relative??])
    </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 or Note ID Array</td>
        <td>All voices of this note will be modified.<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??tuning??</code></td>
        <td>Integer Number</td>
        <td>Tuning change in milli cents.
            A positive value increases the tuning,
            a negative value decreases the tuning.<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??relative??</code></td>
        <td>Integer&nbsp;Number&nbsp;or<br>
            Real&nbsp;Number</td>
        <td>Whether change_tune() calls should be relative to each other.<br>
            <code>0</code>: A call to <code>change_tune()</code> upon the same note will
               replace the tuning change value set by previous
               <code>change_tune()</code> calls upon the same note.<br>
            <code>1</code>: Successive calls to <code>change_tune()</code> upon the same
               note will be relatively applied against each other.<br>
            [optional, default: <code>0</code>]</td>
      </tr>
    </table>

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

    <h3>Remarks</h3>
    <p>
      This functions optionally accepts <code>c</code> for "Cents" as standard unit and
      finalness for its argument <code>??tuning??</code>.
    </p>

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

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

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

    <note>
      The third argument of this function <code>??relative??</code> is only
      optional with NKSP. If you want to keep compatibility with KSP, then you
      should always pass a value for that third argument of this function.
    </note>
    
  </body>
</html>
1	schoenebeck	2932	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>change_tune() function</title>
5			<meta name="description" content="Modifies the tuning of voices of a particular note.">
6			</head>
7			<body>
8			<h1>change_tune()</h1>
9			<p>
10			This function can be used to modify the tuning of active voices during
11			their entire life time. So you may for example implement very sophisticated
12			pitch envelopes by script by using this function. You need to pass the
13			note ID of the voices you want to alter. This function will change the
14			tuning of all active voices associated with the requested note. So if you
15			are using a layered instrument patch, then it will change the tuning of
16			all layers.
17			</p>
18			<p>
19	schoenebeck	3189	Internally the sampler always fades the tuning from its current value to
20			the new tuning as requested, however that tuning fade by default is so fast
21			that it sounds like its value jumps directly from its old to the new value.
22			You may also override that automated fade time explicitly by calling
23			<code lang="nksp">change_tune_time()</code> before calling the
24			<code lang="nksp">change_tune()</code> function.
25			</p>
26			<p>
27	schoenebeck	2933	The tuning changes set by calling this function are always applied relatively to
28	schoenebeck	2932	the tuning/pitch calculated by the synthesis model and sampler format. That means
29			the various sources of tuning/pitch factors like MIDI pitch bend wheel, Pitch Envelopes,
30			Pitch LFOs and other tuning factors that may be defined by the
31			instrument patch, are always processed and calculated for the voices first,
32			and the final pitch applied is always a relative combination of all those
33			factors and the one set with this function call. This does also not change
34			when you pass <code>1</code> for argument <code>??relative??</code>.
35			Or in other words: you cannot replace the tuning/pitch set by other synthesis
36			sources with this function.
37			</p>
38
39			<note class="important">
40			Release Trigger Samples: In case the affected voices cause release trigger
41			samples to be spawned later on, the tuning of those release trigger voices
42			will not be affected by this function at all. So if you need to control the
43			tuning of release trigger samples by script, then you might rather also trigger
44			those release trigger samples by script with <code lang="nksp">play_note()</code>
45			instead of using the sampler format's internal support for release trigger samples.
46			</note>
47
48			<h3>Function Prototype</h3>
49			<p/>
50			<code lang="nksp">
51			change_tune(??note??, ??tuning??, [??relative??])
52			</code>
53
54			<h3>Arguments</h3>
55			<table>
56			<tr>
57			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
58			</tr>
59			<tr>
60			<td><code>??note??</code></td>
61	schoenebeck	2944	<td>Note ID Number or Note ID Array</td>
62	schoenebeck	2932	<td>All voices of this note will be modified.<br>
63			[required]</td>
64			</tr>
65			<tr>
66			<td><code>??tuning??</code></td>
67			<td>Integer Number</td>
68			<td>Tuning change in milli cents.
69			A positive value increases the tuning,
70	schoenebeck	3189	a negative value decreases the tuning.<br>
71			[required]</td>
72	schoenebeck	2932	</tr>
73			<tr>
74			<td><code>??relative??</code></td>
75	schoenebeck	3601	<td>Integer Number or<br>
76			Real Number</td>
77	schoenebeck	2932	<td>Whether change_tune() calls should be relative to each other.<br>
78	schoenebeck	3233	<code>0</code>: A call to <code>change_tune()</code> upon the same note will
79	schoenebeck	2932	replace the tuning change value set by previous
80			<code>change_tune()</code> calls upon the same note.<br>
81	schoenebeck	3233	<code>1</code>: Successive calls to <code>change_tune()</code> upon the same
82	schoenebeck	2932	note will be relatively applied against each other.<br>
83	schoenebeck	3233	[optional, default: <code>0</code>]</td>
84	schoenebeck	2932	</tr>
85			</table>
86
87			<h3>Return Value</h3>
88			<p>None.</p>
89
90	schoenebeck	3601	<h3>Remarks</h3>
91			<p>
92	schoenebeck	3604	This functions optionally accepts <code>c</code> for "Cents" as standard unit and
93	schoenebeck	3601	finalness for its argument <code>??tuning??</code>.
94			</p>
95
96	schoenebeck	2932	<h3>Examples</h3>
97			<p>None yet.<p>
98
99	schoenebeck	3189	<h3>See also</h3>
100			<p><code>change_tune_time()</code><p>
101
102	schoenebeck	3196	<h3>Availability</h3>
103	schoenebeck	2932	<p>Since LinuxSampler 2.0.0.svn11.<p>
104
105	schoenebeck	3189	<note>
106			The third argument of this function <code>??relative??</code> is only
107			optional with NKSP. If you want to keep compatibility with KSP, then you
108			should always pass a value for that third argument of this function.
109			</note>
110
111	schoenebeck	2932	</body>
112			</html>