reference/functions/nksp_change_vol_time_function.html

<html>
  <head>
    <meta name="author" content="Christian Schoenebeck">
    <title>change_vol_time() function</title>
    <meta name="description" content="Changes the duration of volume changes.">
  </head>
  <body>
    <h1>change_vol_time()</h1>
    <p>
      This function can be used to override the internal fade time of volume
      changes upon calls to <code lang="nksp">change_vol()</code>. That
      fade time is not set globally, but rather on a per-note level.
      Additionally you might call <code>change_vol_curve()</code> to override
      the default fade curve shape type.
    </p>

    <h3>Function Prototype</h3>
    <p/>
    <code lang="nksp">
change_vol_time(??note??, ??duration-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 or Note ID Array</td>
        <td>All voices of this note will be modified.<br>
            [required]</td>
      </tr>
      <tr>
        <td><code>??duration-us??</code></td>
        <td>Integer&nbsp;Number&nbsp;or<br>
            Real&nbsp;Number</td>
        <td>Fade time in microseconds.<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>??duration-us??</code>.
    </p>

    <h3>Examples</h3>
    <p>The following example demonstrates a simple, custom volume envelope generator.</p>
    <code>
on init
  declare const $time1US := 800000 { 0.8 seconds }
  declare const $time2US := 1600000 { 1.6 seconds }
  declare const $time3US := 3000000 { 3 seconds }
end on

on note
  { Start the note with a (immediately) decreased volume
    of -30 dB. }
  change_vol($EVENT_ID, -30000)

  { Fade the note's volume within 0.8s from -30 db up to
    its normal volume, that is to 0 dB. }
  change_vol_time($EVENT_ID, $time1US)
  change_vol($EVENT_ID, 0)

  { Remain in this stage with 0 dB for 1.6 seconds. }
  wait($time1US + $time2US)

  { Now fade the note's volume from 0 dB down to -12 dB
    within 3 seconds. }
  change_vol_time($EVENT_ID, $time3US)
  change_vol($EVENT_ID, -12000)
end on
    </code>
    
    <h3>See also</h3>
    <p><code>change_vol()</code>, <code>change_vol_curve()</code>, <code>fade_in()</code>, <code>fade_out()</code><p>

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

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

  </body>
</html>
1	schoenebeck	3189	<html>
2			<head>
3			<meta name="author" content="Christian Schoenebeck">
4			<title>change_vol_time() function</title>
5			<meta name="description" content="Changes the duration of volume changes.">
6			</head>
7			<body>
8			<h1>change_vol_time()</h1>
9			<p>
10			This function can be used to override the internal fade time of volume
11			changes upon calls to <code lang="nksp">change_vol()</code>. That
12			fade time is not set globally, but rather on a per-note level.
13	schoenebeck	3249	Additionally you might call <code>change_vol_curve()</code> to override
14			the default fade curve shape type.
15			</p>
16	schoenebeck	3189
17			<h3>Function Prototype</h3>
18			<p/>
19			<code lang="nksp">
20			change_vol_time(??note??, ??duration-us??)
21			</code>
22
23			<h3>Arguments</h3>
24			<table>
25			<tr>
26			<th>Argument Name</th> <th>Data Type</th> <th>Description</th>
27			</tr>
28			<tr>
29			<td><code>??note??</code></td>
30			<td>Note ID Number or Note ID Array</td>
31			<td>All voices of this note will be modified.<br>
32			[required]</td>
33			</tr>
34			<tr>
35			<td><code>??duration-us??</code></td>
36	schoenebeck	3601	<td>Integer Number or<br>
37			Real Number</td>
38	schoenebeck	3189	<td>Fade time in microseconds.<br>
39			[required]</td>
40			</tr>
41			</table>
42
43			<h3>Return Value</h3>
44			<p>None.</p>
45
46	schoenebeck	3601	<h3>Remarks</h3>
47			<p>
48			This functions optionally accepts <code>s</code> as standard unit
49			for its argument <code>??duration-us??</code>.
50			</p>
51
52	schoenebeck	3189	<h3>Examples</h3>
53	schoenebeck	3217	<p>The following example demonstrates a simple, custom volume envelope generator.</p>
54			<code>
55			on init
56			declare const $time1US := 800000 { 0.8 seconds }
57			declare const $time2US := 1600000 { 1.6 seconds }
58			declare const $time3US := 3000000 { 3 seconds }
59			end on
60
61			on note
62			{ Start the note with a (immediately) decreased volume
63			of -30 dB. }
64			change_vol($EVENT_ID, -30000)
65
66			{ Fade the note's volume within 0.8s from -30 db up to
67			its normal volume, that is to 0 dB. }
68			change_vol_time($EVENT_ID, $time1US)
69			change_vol($EVENT_ID, 0)
70
71			{ Remain in this stage with 0 dB for 1.6 seconds. }
72			wait($time1US + $time2US)
73
74			{ Now fade the note's volume from 0 dB down to -12 dB
75			within 3 seconds. }
76			change_vol_time($EVENT_ID, $time3US)
77			change_vol($EVENT_ID, -12000)
78			end on
79			</code>
80	schoenebeck	3189
81			<h3>See also</h3>
82	schoenebeck	3249	<p><code>change_vol()</code>, <code>change_vol_curve()</code>, <code>fade_in()</code>, <code>fade_out()</code><p>
83	schoenebeck	3189
84	schoenebeck	3196	<h3>Availability</h3>
85	schoenebeck	3189	<p>Since LinuxSampler 2.0.0.svn45.<p>
86
87			<note>
88			This function exists only with NKSP, it is not available with KSP.
89			</note>
90
91			</body>
92			</html>