Specify the DynamicsCompressor #1278

padenot · 2017-07-26T15:40:16Z

Here is it. It should be fairly complete (I addressed the comments we made during the f2f).

padenot · 2017-07-26T15:42:11Z

Preview: https://rawgit.com/padenot/web-audio-api/4fa027223c5972b72c0d587c5eb736115d558a66/index.html#processing

svgeesus · 2017-07-29T09:53:58Z

This seems fairly clearly explained, to me. (A couple of typos - treashold -> threshold, Enveloppe -> Envelope).
We should probably log an actual EnvelopeFollower node as a post-v1 feature request, as it is a useful building block.

rtoy

Thanks for doing this hard work! Looks quite good, but I have a few grammatical issues and a few questions on the details.

rtoy · 2017-08-01T20:38:25Z

index.html

+                <li>The third part is a linear function of equation \(f(x) =
+                \frac{1}{ratio} \cdot x \).
+                </li>
+              </ul>This curve MUST be continuously differentiable, and


According to Wikipedia continuously differentiable means that the derivative is also continuous. This precludes the hard-knee in the diagram. Should the hard knee in the diagram be removed?

Or maybe you really meant the curve just needs to be differentiable? This would allow the hard knee as a valid curve.

I think we need to write that it is allowed to have a function that is not continuously differentiable iff the knee is 0, which kind of makes sense, because the purpose of a hard knee is to have an hard edge.

The exception for knee == 0 seems odd to me. Based on my reading of the code, doesn't the function actually need to be differentiable (not "continuously differentiable") since the derivative of the function is required for some of the calculations done in the compressor?

In which case, we can still have a hard knee, as long as it isn't really a discontinuity in the derivative, but just a much more abrupt change. We could define some absolute minimum for the internal value of the knee parameter, which would keep the function differentiable in all cases.

If you just say continuous and piece-wise differentiable instead of continuously differentiable, everything should work out. The hard knee is continuous and piece-wise differentiable.

rtoy · 2017-08-01T20:39:56Z

index.html

+              var compression = new EnveloppeFollower();
+
+              input.connect(delay).connect(gain).connect(output);
+              input.connect(compression).connect(gain.gain);</pre>


A picture instead of code would be nice here, but not necessary.

I added a picture as well.

rtoy · 2017-08-01T20:41:03Z

index.html

+            <code>input</code> and <code>output</code> respectively being the
+            input and output <a>AudioNode</a>, <code>context</code> the
+            <a>BaseAudioContext</a> for this <a>DynamicsCompressorNode</a>, and
+            new class, <code>EnveloppeFollower</code>, that instantiate a


Typo: "EnveloppeFollower", here and elsewhere.

rtoy · 2017-08-01T20:42:13Z

index.html

+            linear gain value.
+          </p>
+          <ol>
+            <li>Let <var>input signal</var> be the the block of audio to be


"block" -> "`render quantum"?

rtoy · 2017-08-01T20:42:45Z

index.html

+            parameters).
+            </li>
+            <li>Let <var>ratio</var> have the value of the <code>ratio</code>
+            <a>Audioparam</a>, sampled at the time of processing of this block


Typo: "Audioparam" -> "AudioParam". Then the link will show up correctly, I think.

rtoy · 2017-08-01T21:05:45Z

index.html

+            respects the following characteristics:
+          </p>
+          <ol>
+            <li>This function is the identify up to the value of the linear


Typo: "identify" -> "identity"?

rtoy · 2017-08-01T21:06:10Z

index.html

+          </p>
+          <ol>
+            <li>This function is the identify up to the value of the linear
+            <code>threshold</code> (i.e., \(f(sample) = sample\)).


Maybe just use f(x) = x? Easier to read as a mathematical formula.

rtoy · 2017-08-01T21:07:03Z

index.html

+            </li>
+            <li>From the <code>threshold</code> up to the <code>threshold +
+            knee</code>, User-Agents can choose the curve shape. The whole
+            function MUST be continuous (except as noted in the note below) and


"except as noted in the note below" -> "except as noted below"?

rtoy · 2017-08-01T21:07:49Z

index.html

+              <div class="note">
+                As such, if the <code>knee</code> is 0, the
+                <a>DynamicsCompressorNode</a> is a hard-knee compressor, and
+                the function has a discontinuity at <code>threshold</code>.


This seems to contradict the requirement that the curve MUST be continuously differentiable.

I think the MUST applies to the whole sentence: it MUST (be continuously differentiable except when the knee is 0, and then that is the case there is a discontinuity at the knee).

I've changed the prose a bit.

rtoy · 2017-08-01T21:13:37Z

index.html

+              </div>
+            </li>
+            <li>This function returned is linear, based on the ratio, after the
+            <code>threshold</code> and the soft knee (i.e., \(f(sample) =


Copy the formula from earlier so that it has the same form (1/ratio * x).

joeberkovitz · 2017-08-02T17:33:00Z

Latest preview for review: https://rawgit.com/padenot/web-audio-api/ec6b3b2c1cbab235d57b07aa97501452254d3462/index.html

joeberkovitz · 2017-08-02T17:34:01Z

index.html

@@ -9085,7 +9085,9 @@ <h3 id="example-2">
            <p>
              Let <var>node</var> be a new <a>DynamicsCompressorNode</a>
              object. <a href="#audionode-constructor-init">Initialize</a>
-              <var>node</var>, and return <var>node</var>.
+              <var>node</var>. Let [[\reduction]] be a private slote on this


slote -> slot

joeberkovitz · 2017-08-02T17:36:50Z

index.html

@@ -9144,7 +9146,8 @@ <h3 id="example-2">
              A read-only decibel value for metering purposes, representing the
              current amount of gain reduction that the compressor is applying
              to the signal. If fed no signal the value will be 0 (no gain
-              reduction).
+              reduction). When this attribute is read, return the value of the
+              private slot [[\reduction]].


Would it be simpler to force [[reduction]] to assume a zero value when no signal is present, as part of the compression algorithm?

Is it not what I've done?

IIRC, what you've done is to say [[reduction]] is ignored when the signal is present, and zero is returned instead.

joeberkovitz · 2017-08-02T17:39:07Z

index.html

+            </li>
+            <li>The compression curve is has three parts:
+              <ul>
+                <li>The first part is the identify: \(f(x) = x\).


identify -> identity

joeberkovitz · 2017-08-02T17:39:42Z

index.html

+            <code>reduction</code> property on the
+            <a>DynamicsCompressorNode</a>
+            </li>
+            <li>The compression curve is has three parts:


delete "is"

joeberkovitz · 2017-08-02T17:49:21Z

index.html

+                <li>The third part is a linear function of equation \(f(x) =
+                \frac{1}{ratio} \cdot x \).
+                </li>
+              </ul>This curve MUST be continuously differentiable, and


The exception for knee == 0 seems odd to me. Based on my reading of the code, doesn't the function actually need to be differentiable (not "continuously differentiable") since the derivative of the function is required for some of the calculations done in the compressor?

In which case, we can still have a hard knee, as long as it isn't really a discontinuity in the derivative, but just a much more abrupt change. We could define some absolute minimum for the internal value of the knee parameter, which would keep the function differentiable in all cases.

joeberkovitz · 2017-08-02T18:10:38Z

index.html

+            <dfn id="#envelope-rate">Computing the envelope rate</dfn> is done
+            by applying a function to the ratio of the <var>compressor
+            gain</var> and the <var>detector average</var>. User-agents are
+            allowed to choose the shape of the attack and release curve.


The sudden introduction of "curves" here is confusing. I think we need a sentence or two explaining that the envelope rate is a scale factor by which some gain quantity is multiplied, in each sample frame. These successive multiplications, in turn, generate the envelope curve.

This is now well defined in the algorithm above.

joeberkovitz · 2017-08-02T18:10:51Z

index.html

+          </ul>
+          <div class="note">
+            It is allowed, for example, to have a compressor that performs an
+            <em>adaptative release</em>, that is, releasing faster the harder


adaptative -> adaptive

joeberkovitz · 2017-08-02T18:10:56Z

index.html

+            function in the range \([0, 1]\).
+            </li>
+            <li>The release curve MUST be a continuous, monotonically
+            decreasing function that is always greater to 1.


greater than 1

joeberkovitz · 2017-08-02T18:11:35Z

index.html

+              </div>
+            </li>
+            <li>The attack curve MUST be a continuous, monotonically increasing
+            function in the range \([0, 1]\).


Given the above eplanation that I am suggesting, these requirements follow directly from the constraints on the value of the envelope rate.

joeberkovitz · 2017-08-02T18:12:25Z

index.html

+            However, they MUST respect the following constraints:
+          </p>
+          <ul>
+            <li>The input to the curve MUST be the ratio of the <var>compressor


Rather than the "input to the curve", this is more clearly described as the envelope rate itself (which in turn determines the curve). So... "the envelope rate MUST be calculated from the ratio of..."

rtoy · 2017-08-03T14:59:00Z

index.html

@@ -9085,7 +9085,9 @@ <h3 id="example-2">
            <p>
              Let <var>node</var> be a new <a>DynamicsCompressorNode</a>
              object. <a href="#audionode-constructor-init">Initialize</a>
-              <var>node</var>, and return <var>node</var>.
+              <var>node</var>. Let [[\reduction]] be a private slote on this


There's already an attribute named reduction. Naming the private slot [[reduction]] is confusing.

rtoy · 2017-08-03T15:01:24Z

index.html

+                <li>The third part is a linear function of equation \(f(x) =
+                \frac{1}{ratio} \cdot x \).
+                </li>
+              </ul>This curve MUST be continuously differentiable, and


If you just say continuous and piece-wise differentiable instead of continuously differentiable, everything should work out. The hard knee is continuous and piece-wise differentiable.

rtoy · 2017-08-03T15:02:51Z

index.html

+          </p>
+          <figure>
+            <img alt="Graphical representation of a compression curve" src=
+            "images/compression-curve.svg" style="width: 50%">


In the diagram, you draw ratio as if it's the angle of the line after the knee. It's not; it's the reciprocal of the slope. Not exactly sure how to show that.

Yes, this is somewhat of a language abuse. In music software, it's often represented like that, but we need to be more precise here.

I'll leave it up to you to come up with something. (Or leave the diagram as is and add some text.)

I've tried something else, have a look.

rtoy · 2017-08-03T15:04:26Z

index.html

+            <img src="images/dynamicscompressor-internal-graph.svg" alt=
+            "Schema of
+            the internal graph used by the DynamicCompressorNode">
+            <figcaption>


Thanks for the diagram! Looks really nice. One nit: Kind of hard to tell that the envelope follower output connects to the gain attribute of the gain node. Not exactly sure how to best illustrate this, though.

I tried to put a little "Gain" label, maybe we can do something better.

I'm ok, if you leave it as is. The code above clearly describes what's happening.

rtoy · 2017-08-03T15:29:44Z

index.html

+            gain</var> and the <var>detector average</var>.
+              <div class="note">
+                When attacking, this number less than or equal to 1, when
+                releasing, this number is strictly greater to 1.


"greater to" -> "greater than"

rtoy · 2017-08-03T15:30:53Z

index.html

+          <p>
+            Applying a <dfn>compression curve</dfn> to a value means computing
+            the value of this sample when passed to a function, and returning
+            the computed value. This function MUST respects the following


"respects" -> "respect"

rtoy · 2017-08-03T15:33:08Z

index.html

+            knee</code>, User-Agents can choose the curve shape. The whole
+            function MUST be monotonically increasing and continuous except
+            when the <code>knee</code> parameter is 0, in which case a
+            discontinuity happens at the treshold.


In the diagram with a hard knee, the curve is still continuous, but not differentiable; there is no discontinuity. I think it's enough here to say that the curve in monotonic increasing and continuous. No exception needs to be made when the knee is 0.

rtoy · 2017-08-03T15:34:59Z

index.html

+          <ol>
+            <li>If <var>v</var> is equal to zero, return -1000.
+            </li>
+            <li>Else, return \( 20 \times \log_{10}{v} \)


\times not really needed, but ok. (Might need \, or something if you do remove the times, so that there's a tiny space between 20 and log.)

…e names

rtoy · 2017-08-04T19:07:58Z

index.html

              <ul>
-                <li>The first part is the identify: \(f(x) = x\).
+                <li>The first part is the identity: \(f(x) = x\).
                </li>
                <li>The second part is the soft-knee portion, which MUST be a
                monotonically increasing function.
                </li>
                <li>The third part is a linear function of equation \(f(x) =


Nit: "linear function of equation" -> "the linear function:"

The ":" to make to match what you say in line 9253 above.

rtoy · 2017-08-04T19:09:00Z

index.html

-            Now, the actual algorithm to determine the reduction gain, in
-            linear gain value.
+            Now, the actual algorithm to determine <var>reduction gain</var>, in
+            linear gain value, for each sample of input.


This isn't a complete sentence. Maybe just replace the final period with a colon?

rtoy · 2017-08-04T19:09:30Z

index.html

-                <a href="compression-curve">compression curve</a> to the
-                absolute value of <var>input</var> .
+                <li>If the absolute value of <var>input</var> is less than
+                0.0001, let <var>attenuation</var> be 1.0. Else, let


Is this what Chrome and Firefox do today?

I think it's good enough to avoid the division by zero.

rtoy · 2017-08-04T19:11:12Z

index.html

@@ -9411,34 +9421,44 @@ <h3 id="example-2">
            <dfn id="#envelope-rate">Computing the envelope rate</dfn> is done
            by applying a function to the ratio of the <var>compressor
            gain</var> and the <var>detector average</var>. User-agents are
-            allowed to choose the shape of the attack and release curve.
+            allowed to choose the shape the enveloppe function.


"enveloppe" -> "envelope", here and elsewhere. (Is this the French spelling?)

Exactly 🇫🇷

joeberkovitz · 2017-08-04T20:16:15Z

index.html

@@ -9085,7 +9085,9 @@ <h3 id="example-2">
            <p>
              Let <var>node</var> be a new <a>DynamicsCompressorNode</a>
              object. <a href="#audionode-constructor-init">Initialize</a>
-              <var>node</var>, and return <var>node</var>.
+              <var>node</var>. Let [[\reduction]] be a private slot on this


It looks as though you changed the name of the slot everywhere except here.

joeberkovitz · 2017-08-04T20:19:09Z

index.html

+                <var>input</var>.
+                </li>
+                <li>Let <var>decibels per frame</var> be the result of dividing
+                <var>attenuationDB</var> by <var>releaseRate</var>.</li>


attenuationDB does not appear to be defined anywhere

I think you meant to divide attenuation by the quantity known in the C++ code as sat_release_frames, which is the number of frames in a release time interval. Note that releaseRate is not computed until the following step (and it's computed from the work done in this step!)

joeberkovitz · 2017-08-04T20:24:53Z

index.html

+                </li>
+                <li>Let <var>decibels per frame</var> be the result of dividing
+                <var>attenuationDB</var> by <var>releaseRate</var>.</li>
+                <li>Set <var>relaseRate</var> be the result of


relaseRate -> releaseRate

joeberkovitz · 2017-08-04T20:26:35Z

index.html

+                <a href="#db-to-linear">converting <var>decibels per frames
+                </var>to linear gain</a>, and substract one.</li>
+                <li>Set <var>change-rate</var> to the difference between <var>
+                  attenuation</var> and <var>detector average</var>.


This where releaseRate is supposed to be multiplied by the difference: the new change rate is (attenuation - detector average) * release rate.

That is, unless we're attacking.

joeberkovitz · 2017-08-04T20:32:12Z

index.html

+                <li>If attacking, set <var>attack</var> to <var>detector
+                average</var> minus <var>compressor gain</var>. Set
+                <var>compressor gain</var> to the multiplication of
+                <var>attack</var> by <var>envelope rate</var>. Clamp


The sentence "Set compressor gain to the multiplication of..." appears to be left over from before. It should be replaced by the new language in line 9382 about multiplying attack by envelope rate and adding attack to compressor gain.

rtoy

Just a bunch of nits and typos and minor clarifications.

rtoy · 2017-08-09T18:55:13Z

index.html

+            <li>Configurable attack speed, release speed, threshold, knee
+            hardness and ratio.
+            </li>
+            <li>Side-chaining is not supported


Nit. End sentence with a period, like you do elsewhere.

rtoy · 2017-08-09T18:55:39Z

index.html

+            </li>
+            <li>The gain reduction is reported <em>via</em> the
+            <code>reduction</code> property on the
+            <a>DynamicsCompressorNode</a>


Nit. End sentence with a period.

rtoy · 2017-08-09T18:57:49Z

index.html

+          </p>
+          <figure>
+            <img alt="Graphical representation of a compression curve" src=
+            "images/compression-curve.svg" style="width: 50%">


I'll leave it up to you to come up with something. (Or leave the diagram as is and add some text.)

rtoy · 2017-08-09T18:58:26Z

index.html

+            <img src="images/dynamicscompressor-internal-graph.svg" alt=
+            "Schema of
+            the internal graph used by the DynamicCompressorNode">
+            <figcaption>


I'm ok, if you leave it as is. The code above clearly describes what's happening.

rtoy · 2017-08-09T19:00:29Z

index.html

+            <a>DynamicsCompressorNode</a> is <a href=
+            "#associated">associated</a> with.
+            </li>
+            <li>For each samples <var>input</var> of <var>input signal</var>,


Nit: "each samples" -> "each sample"

rtoy · 2017-08-09T19:01:01Z

index.html

+            execute the following steps:
+              <ol>
+                <li>Let <var>envelope rate</var> be the result of <a href=
+                "#envelope-rate">computing the envelope rate</a>


Nit: End with a period, like you do elsewhere.

rtoy · 2017-08-09T19:03:19Z

index.html

+                0.0001, let <var>attenuation</var> be 1.0. Else, let
+                <var>attenuation</var> be the value of applying the <a
+                href="#compression-curve">compression curve</a> to the absolute
+                value of <var>input</var>, divided by the absolute value of


This phrasing is a bit confusing because I interpreted this as dividing the absolute value of the input by the absolute value of the input. A closer reading shows that you really mean compression curve value divided by input absolute value. Maybe rephrase or use two sentences?

I've used two sentences and an intermediate variable so make this extra-clear.

rtoy · 2017-08-09T19:05:39Z

index.html

+            <dfn id="#envelope-rate">Computing the envelope rate</dfn> is done
+            by applying a function to the ratio of the <var>compressor
+            gain</var> and the <var>detector average</var>. User-agents are
+            allowed to choose the shape the enveloppe function.


rtoy · 2017-08-09T19:05:52Z

index.html

+            However, they MUST respect the following constraints:
+          </p>
+          <ul>
+            <li>The enveloppe rate MUST be the calculated from the ratio of the


"envelope"

Also are you referring to the "envelope rate" variable?

I've clarified this.

rtoy · 2017-08-09T19:09:20Z

index.html

+                <a>DynamicsCompressorNode</a> is called a hard-knee compressor.
+              </div>
+            </li>
+            <li>This function returned is linear, based on the ratio, after the


"This function returned is linear" -> "This function is linear"

padenot · 2017-08-10T14:23:24Z

The last few commits refactor the algorithm so that things are in the right order, change the diagram, address the other comments, and tidy.

padenot added 7 commits July 25, 2017 14:17

wip

183a471

diagram + some of joe's suggestion addressed + tidy

c632144

shaping curve + enveloppe rate

a7e109e

move back to the right section

3f7deaf

Address f2f comments

ef52af6

Adjust compressor diagram

7d98d01

tidy

4fa0272

padenot self-assigned this Jul 26, 2017

padenot mentioned this pull request Jul 27, 2017

Describe the algorithm that DynamicsCompressorNode should use #10

Closed

rtoy requested changes Aug 1, 2017

View reviewed changes

padenot added 3 commits August 2, 2017 17:36

Address rtoy and chris' comments

4a56626

fix respec error

565e92c

tidy the document

ec6b3b2

joeberkovitz suggested changes Aug 2, 2017

View reviewed changes

rtoy reviewed Aug 3, 2017

View reviewed changes

padenot added 2 commits August 4, 2017 12:19

Address joe and ray comments

4360f5d

Link the introductory text and the algorithm by using correct variabl…

430a541

…e names

rtoy reviewed Aug 4, 2017

View reviewed changes

joeberkovitz suggested changes Aug 4, 2017

View reviewed changes

rtoy reviewed Aug 9, 2017

View reviewed changes

padenot added 3 commits August 10, 2017 16:06

algorithm refactor

ae8905f

adjust diagram

3fb6d99

tidy

bdf00c1

joeberkovitz approved these changes Aug 10, 2017

View reviewed changes

rtoy approved these changes Aug 10, 2017

View reviewed changes

padenot merged commit 0c80e57 into WebAudio:gh-pages Aug 10, 2017

Specify the DynamicsCompressor #1278

Specify the DynamicsCompressor #1278

Conversation

padenot commented Jul 26, 2017

padenot commented Jul 26, 2017

svgeesus commented Jul 29, 2017

rtoy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

joeberkovitz commented Aug 2, 2017

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

rtoy left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment