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