ViewVC logotype

Annotation of /doc/docbase/instrument_scripts/nksp/reference/functions/nksp_change_vol_function.html

Parent Directory Parent Directory | Revision Log Revision Log

Revision 3604 - (hide annotations) (download) (as text)
Tue Sep 17 17:37:51 2019 UTC (14 months, 1 week ago) by schoenebeck
File MIME type: text/html
File size: 4670 byte(s)
Some fixes in NKSP function reference.

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>
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>
49     <h3>Function Prototype</h3>
50     <p/>
51     <code lang="nksp">
52     change_vol(??note??, ??volume??, [??relative??])
53     </code>
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>
87     <h3>Return Value</h3>
88     <p>None.</p>
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>
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>
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>
111 schoenebeck 2932 </body>
112     </html>

  ViewVC Help
Powered by ViewVC