Audio-ISSUE-38 (setTargetValueAtTime): AudioParam.setTargetValueAtTime is misleading and underdefined [Web Audio API]
Raised by: Philip Jägenstedt
On product: Web Audio API
The naming of this function is misleading, since it does not in fact set the target value at the given time.
timeConstant is underdefined, what is the exponent? A "first-order filter (exponential)" is mentioned, but not clarified further.
Finally, it is not well defined what the difference to exponentialRampToValueAtTime is, but we suspect that setTargetValueAtTime is something like v=1-e-kt. The equations involving the 3 parameters should be included in the spec, normatively.
I disagree that the name is misleading. It's a *target* value which we start approaching at precisely the time given.
* timeConstant is now defined.
* precise v(t) equation is now given:
Philip, does this answer your concerns?
Unless you or someone else can suggest a convincingly better name for setTargetValueAtTime, I think we can close this.
Mailing-list discussion on this topic between Ray Bellis, Chris Rogers, Marcus Geelnard and myself:
Marcus has a pretty good summary, and raises something interesting:
Once you understand what the function does, the name makes sense. However,
the name alone does not make it easy to understand what it does.
I think that the confusion (at least for me) is that "setTargetValue" is
very similar to "setValue", and I fear that many will have them mixed up.
Generally speaking, the "set" term indicates a zero-duration operation.
I'd much rather see that methods that cause gradual changes use a
consistent naming convention, excluding the term "set".
I think that a more appropriate name could be "approachValueAtTime" or
Similarly the name "setValueCurveAtTime" would do better without "set".
Any suggestions? (I'm out of ideas right now)
Rob Baxter suggested the following on the mailing-list:
AudioParam.approach(target, time, k)
AudioParam.curve(value_set, time, duration)
The suggestion already received two +1's, from Marcus and me.
(In reply to comment #4)
> Rob Baxter suggested the following on the mailing-list:
> AudioParam.set(value, time)
> AudioParam.linearRamp(value, time)
> AudioParam.exponentialRamp(value, time)
> AudioParam.approach(target, time, k)
> AudioParam.curve(value_set, time, duration)
> The suggestion already received two +1's, from Marcus and me.
Having just gone through the process of figuring out what those different things mean for something I'm working on (that image on the spec is awesome by the way), hooray for easier names :)
We had a lengthy conversation about this during the group's teleconference on 22nd August 2012:
There was agreement that the name was imperfect, but there was a compromise to be reached between using a nice, short method name and one that describes the behaviour of the method well. We discussed whether to remove the "at time", whether to remove "set", and so on.
In the end, we reached the following proposed resolution:
* Change the setTargetValueAtTime method to setTargetAtTime
* The rest of the methods are a decent enough compromise, will be kept as is
Related changes were also proposed, which would make the description and behaviour of AudioParam automation easier to understand and use:
* Use startTime / endTime parameter names for AudioParam automation methods
* Setting audioparam value while there is an automation curve will cancel that automation curve and set value immediately
* Need a method to get a readonly reading of the combined value when using AudioParam automation curve
Marcus was present in one of the teleconferences where we decided to change:
setTargetValueAtTime() -> setTargetAtTime()
The spec has now been updated.
(In reply to comment #8)
> The spec has now been updated.
I assume you're referring to this change: http://dvcs.w3.org/hg/audio/rev/aea45daa1200
Looks ok to me.
No objection in 2 weeks, vetted: closing.