Help: Correct wording in Amplitude help (it's not the peak)

[jamshark70]

Purpose and Motivation

Facebook conversation:

Why does Amplitude return an unexpected value?: ( { Amplitude.ar(SinOsc.ar).poll; Silent.ar }.play ) Polled value is around 0.63, but I would expect the value to be 1.

Me: "You're expecting the peak amplitude. Many ways of measuring amplitude (e.g. RMS, which is well standard in audio) reflect the average level rather than the peak. ... Amplitude will return a larger value for louder signals but if you really need the peak, see Peak.ar ."

Them: "Makes sense, although my assumption was based on the description of the UGen: 'Tracks the peak amplitude of a signal.'"

Misleading wording.

Types of changes

• Documentation

To-do list

• [x] Updated documentation
• [x] This PR is ready for review

[cdbzb]

0.63 is close to the average value of SinOsc.ar.abs (2/pi) - quick test with Pulse.ar(750) gave 0.5... So is Amplitude not actually calculating a moving average of the absolute value of the signal? Would be nice to be specific if we can be!

[jamshark70]

So is Amplitude not actually calculating a moving average of the absolute value of the signal?

No, it's a lowpass filter, similar to slop~ in Pd or slide~ in Max.

[cdbzb]

can you think of a more complete description which is accurate? something like "low-pass filter used for tracking relative amplitude" ? (slop~ is described as "slew limiting low pass filter" and ~slide as "filters an input logarithmically [...] particularly useful for envelope following")

[mtmccrea]

How about something like:

Returns the running envelope of the signal, smoothed according to the attack and release times.

Then with a simple example included:

(
{
	var att = 0.001;
	var rel = 0.01;
	var src = LFSaw.ar(440) * -1;
	var env = Amplitude.ar(src, att, rel);
	[src, env]
}.plot.superpose_(true)
)

[mtmccrea]

Returns the running envelope of the signal, smoothed according to the attack and release times.

The algorithm that is used is an envelope follower, so I think it's an accurate description.

Mentioning it's architecture as using a lowpass filter is informative and could be later in the description if @jamshark70 wants to go into that kind of detail, but it's not necessary.

Maybe a link to a dedicated page on amplitude, loudness, and their measurement methods.

I agree this would be a good topic for a Tutorial or Guide. But in lieu of that, I suggest we add related:: classes to the help doc, and maybe even reference the "See also" list in the description.

Peak
RunningSum#*rms
MovingAverage#*rms
Loudness
Onsets
AmpComp

[smoge]

The algorithm that is used is an envelope follower, so I think it's an accurate description.

yes, it's accurate. I think I didn't make the point clear.

Amplitude is an amplitude demodulator (as was called in old analog equipment), or envelope follower (synth terminology)

https://www.electronics-notes.com/articles/radio/modulation/amplitude-modulation-am-demodulation-detection.php

The point I tried to make is that this may be the first page someone is reading, and would be good to understand the difference between an AMD and some measurement of loudness (RMS for example). That is, just to be more educational.

"See also" for a little guide would be a nice enhancement.

[jamshark70]

Mentioning it's architecture as using a lowpass filter is informative and could be later in the description if @jamshark70 wants to go into that kind of detail, but it's not necessary.

If others feel it's helpful to go into that much detail, they're welcome to send a PR to my fork, which I'd merge and then it would be updated here.

[mtmccrea]

At the risk of delaying the PR, I'd say we just go for the current clarifying change (with the addition of related:: links), and anyone is welcome to elaborate more in a separate PR.

[mtmccrea]

Feel free also to include the example I mentioned (or any other that's useful), as I think the plot clarifies much more than a mini exposition would. The confusion of the original poster, for example, wrt it returning the peak would have been immediately clarified by the plot.

[jamshark70]

it would be interesting to have a guide "How Do You Measure Loudness?" in more detail, maybe?

In general, I think SC documentation could provide better translations for DSP and audio engineering concepts -- how to FM/PM, how to calculate RMS etc. -- but that DSP / audio-engineering 101 concepts are not really SC help's responsibility. We already lack certain types of SC-specific documentation, without adding the burden of repeating information that is available online or in textbooks.

[mtmccrea]

@jamshark70 its not clear whether you intended to update the PR based on the discussion, or whether you'd like to keep it as is.

[mtmccrea]

I see I may have confused the thread with this:

I'd say we just go for the current clarifying change (with the addition of related:: links), and anyone is welcome to elaborate more in a separate PR.

By this I meant staying focused on the Amplitude help file, and avoid expanding the scope into tutorials, etc. So I'm hoping my suggestion for this help file would be considered. https://github.com/supercollider/supercollider/pull/6165#issuecomment-2094109781

[jamshark70]

I went ahead and added a little bit. I think it's fair to give readers who are unfamiliar with envelope following some way to see what the attack and release parameters do.

At this point, I consider my work on this PR finished (unless I made a typo, but I don't think I did).

[mtmccrea]

Thanks all!