1 |
schoenebeck |
2932 |
<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 |
schoenebeck |
3189 |
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 |
schoenebeck |
2933 |
The volume changes set by calling this function are always applied relatively to |
29 |
schoenebeck |
2932 |
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 |
schoenebeck |
2944 |
<td>Note ID Number or Note ID Array</td> |
63 |
schoenebeck |
2932 |
<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 |
schoenebeck |
3189 |
a negative value decreases the volume.<br> |
72 |
|
|
[required]</td> |
73 |
schoenebeck |
2932 |
</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 |
schoenebeck |
3233 |
<code>0</code>: A call to <code>change_vol()</code> upon the same note will |
79 |
schoenebeck |
2932 |
replace the volume change value set by previous |
80 |
|
|
<code>change_vol()</code> calls upon the same note.<br> |
81 |
schoenebeck |
3233 |
<code>1</code>: Successive calls to <code>change_vol()</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 |
3604 |
<h3>Remarks</h3> |
91 |
|
|
<p> |
92 |
|
|
This functions optionally accepts <code>B</code> (for "Bel") as standard unit |
93 |
|
|
and finalness for its argument <code>??volume??</code>. |
94 |
|
|
</p> |
95 |
|
|
|
96 |
schoenebeck |
2932 |
<h3>Examples</h3> |
97 |
|
|
<p>None yet.<p> |
98 |
schoenebeck |
3189 |
|
99 |
|
|
<h3>See also</h3> |
100 |
|
|
<p><code>change_vol_time()</code>, <code>fade_in()</code>, <code>fade_out()</code><p> |
101 |
schoenebeck |
2932 |
|
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> |