17334 2012-06-05 11:25:34 +0000 (setTargetValueAtTime): AudioParam.setTargetValueAtTime is misleading and underdefined 2012-10-16 13:56:54 +0000 1 1 1 Unclassified AudioWG Web Audio API unspecified PC All CLOSED FIXED P2 normal TBD 1 philipj crogers crogers heiskr jussi.kalliokoski mage olivier.thereaux philipj public-audio dave.null oldest_to_newest 68645 0 philipj 2012-06-05 11:25:34 +0000 Audio-ISSUE-38 (setTargetValueAtTime): AudioParam.setTargetValueAtTime is misleading and underdefined [Web Audio API] http://www.w3.org/2011/audio/track/issues/38 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. 69032 1 crogers 2012-06-14 00:46:35 +0000 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: https://dvcs.w3.org/hg/audio/rev/d86920562bf1 69488 2 olivier.thereaux 2012-06-28 13:51:51 +0000 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. 69654 3 olivier.thereaux 2012-07-05 14:34:01 +0000 Mailing-list discussion on this topic between Ray Bellis, Chris Rogers, Marcus Geelnard and myself: http://lists.w3.org/Archives/Public/public-audio/2012AprJun/thread.html#msg856 Marcus has a pretty good summary, and raises something interesting: http://lists.w3.org/Archives/Public/public-audio/2012AprJun/0865.html « 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 "startApproachingValueAtTime". Similarly the name "setValueCurveAtTime" would do better without "set". Any suggestions? (I'm out of ideas right now) » 69729 4 olivier.thereaux 2012-07-09 08:52:11 +0000 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. http://lists.w3.org/Archives/Public/public-audio/2012JulSep/0017.html http://lists.w3.org/Archives/Public/public-audio/2012JulSep/0030.html 69739 5 jussi.kalliokoski 2012-07-09 17:42:51 +0000 (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. > http://lists.w3.org/Archives/Public/public-audio/2012JulSep/0017.html > http://lists.w3.org/Archives/Public/public-audio/2012JulSep/0030.html +1 69740 6 heiskr 2012-07-09 17:50:27 +0000 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 :) 72602 7 olivier.thereaux 2012-08-23 10:01:37 +0000 We had a lengthy conversation about this during the group's teleconference on 22nd August 2012: http://www.w3.org/2012/08/22-audio-minutes#item03 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 https://www.w3.org/Bugs/Public/show_bug.cgi?id=18661 * Setting audioparam value while there is an automation curve will cancel that automation curve and set value immediately https://www.w3.org/Bugs/Public/show_bug.cgi?id=18662 * Need a method to get a readonly reading of the combined value when using AudioParam automation curve https://www.w3.org/Bugs/Public/show_bug.cgi?id=18663 74842 8 crogers 2012-09-28 22:30:13 +0000 Marcus was present in one of the teleconferences where we decided to change: setTargetValueAtTime() -> setTargetAtTime() The spec has now been updated. 75037 9 mage 2012-10-02 09:51:53 +0000 (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. 76381 10 olivier.thereaux 2012-10-16 13:56:54 +0000 No objection in 2 weeks, vetted: closing.