1267598 - Math inconsistency on the definition of linear independency, and other doc inconsistencies in Web Audio.

Status: RESOLVED WONTFIX

(Developer Documentation Graveyard :: API: Web Audio, defect)

Description

[Jukka Jylänki]

On the image on page https://developer.mozilla.org/en-US/docs/Web/API/AudioListener, it says

"Both the up and front vectors must be linearly independent, that is that they are at 90deg one from the other".

However this is not correct. Two vectors that are linearly independent do not need to be mutually perpendicular.

Also in https://developer.mozilla.org/en-US/docs/Web/API/AudioListener/setOrientation, it is incorrectly written

"Both vectors must be separated by an angle of 90° — in linear analysis terms, they must be linearly independent."

Also in the Web Audio spec, it is incorrectly stated

"These values are expected to be linearly independent (at right angles to each other)."

(http://webaudio.github.io/web-audio-api/#widl-AudioListener-setOrientation-void-float-x-float-y-float-z-float-xUp-float-yUp-float-zUp)

The term that is being searched for here is "mutually perpendicular". Linear independency is a different concept.

Also the MDN page is a bit odd that it defines the setOrientation function to take in six parameters, but just calls it with three.

In the latest draft Web Audio spec the setOrientation function is deprecated, but the spec URL above refers to fields orientationX, orientationY, orientationZ, upX, upY, and upZ, but those don't exist on the AudioListener node. There's forwardX, forwardY, forwardZ, upX, upY and upZ instead.

Comment 1

[Chris Mills [:cmills]]

I've fixed the incorrect term in the image, and added pages to describe all the new properties. We've also removed the deprecated methods.

Comment 2

[Jukka Jylänki]

Hey, I'll reopen this, since visiting

https://developer.mozilla.org/en-US/docs/Web/API/AudioListener/setOrientation

I see it says "Both vectors must be separated by an angle of 90° — in linear analysis terms, they must be linearly independent."

whereas the correct thing is to say

"The two vectors must be separated by an angle of 90° — in linear analysis terms, they must be perpendicular to each other."

Linear independence just means that one vector is not expressible as a scalar multiple of the other, i.e. u and v are linearly independent if there does not exist a scalar k such that v = k*u. That is much weaker than being perpendicular.

While writing this, I realize that the Web Audio spec itself has this issue as well, marked that as https://github.com/WebAudio/web-audio-api/issues/1298.

Comment 3

[Chris Mills [:cmills]]

(In reply to Jukka Jylänki from comment #2)
> Hey, I'll reopen this, since visiting
> 
> https://developer.mozilla.org/en-US/docs/Web/API/AudioListener/setOrientation
> 
> I see it says "Both vectors must be separated by an angle of 90° — in linear
> analysis terms, they must be linearly independent."
> 
> whereas the correct thing is to say
> 
> "The two vectors must be separated by an angle of 90° — in linear analysis
> terms, they must be perpendicular to each other."
> 
> Linear independence just means that one vector is not expressible as a
> scalar multiple of the other, i.e. u and v are linearly independent if there
> does not exist a scalar k such that v = k*u. That is much weaker than being
> perpendicular.
> 
> While writing this, I realize that the Web Audio spec itself has this issue
> as well, marked that as
> https://github.com/WebAudio/web-audio-api/issues/1298.

Thanks Jukka — I've updated it to your wording, so I think we can close this again.

Comment 4

[Jukka Jylänki]

Thanks! In the earlier comment, I offered to fix to using the stricter of the two, since I did not know which one the spec wanted, but it looks like based on comments from https://github.com/WebAudio/web-audio-api/issues/1298#issuecomment-326373342, that the spec intends to only require the weaker linear independence, and not right angles, so I think the wording will need to be updated once more, perhaps from

> The two vectors must be separated by an angle of 90° — in linear analysis terms, they must be perpendicular to each other.

to

> The two vectors should be linearly independent, that is, the forward and up direction vectors should not be collinear.

or just

> The two vectors should be linearly independent.

Sorry for the back and forth!

Comment 5

[BMO Automation]

MDN Web Docs' bug reporting has now moved to GitHub. From now on, please file content bugs at https://github.com/mdn/sprints/issues/ and platform bugs at https://github.com/mdn/kuma/issues/.