PeriodicWave constructor examines lengths of things that might not be there

[bzbarsky]

https://webaudio.github.io/web-audio-api/#PeriodicWave-constructors says (step 2):

If the real and imag parameters of the PeriodicWaveOptions are not of the same length, an IndexSizeError exception MUST be thrown.

but those parameters might not be present at all. Is this meaning to only compare the lengths when both are present? Or does being not present correspond to a length of 0? The text here needs to be a lot more explicit about what should happen.

Then step 4 says:

Otherwise, let [[real]] and [[imag]] be two internal slots of type Float32Array, both of length equal to the maximum of the lengths of the real and imag attributes of the PeriodicWaveOptions passed in.

but the two things passed in must be the same length per step 2. Again, unless being missing means skipping the length check. But then what does the "maximum" mean if one of the lengths does not exist? If both lengths do not exist?

There's something in step 3 about the "options has not been passed in" case, which can't happen, because options has a default value, so it's always passed in. It may or may not have real and imag present in it, of course, whether it's the default value or an explicit value passed from script.

[bzbarsky]

Put another way: there is no way to implement this part of spec right now based on just reading the spec, without reverse-engineering another implementation. That is not a desirable property for specs...

[bzbarsky]

I guess maybe the intent is that https://webaudio.github.io/web-audio-api/#dictdef-periodicwaveoptions describes what should happen when those members are missing? But that's a really weird comefrom-like way to write a spec, and still doesn't explain what step 4 is trying to do with taking the maximum.

[rtoy]

Teleconf: We'll rewrite this. I think the intent was if both arrays are given they have to have the same length.

[rtoy]

I think this is how we want this to work.

1. If PeriodicWaveOptions is not given
   1. Set [[real]] and [[imag]] to be zero-filled arrays of length 2, and set element at index 1 of [[imag]] to be 1.
2. If PeriodicWaveOptions is given
   1. If both real and imag members are given
      1. If the lengths are different, throw an error, and abort these steps.
      2. Create arrays [[real]] and [[imag]] of the same length as real
      3. Copy all elements of real to [[real]] and imag to [[imag]]
   2. If only real is given
      1. Throw error if length is less than 2, and abort these steps.
      2. Create arrays [[real]] and [[imag]] of the same length as real, initializing arrays to 0
      3. Copy real to [[real]]
   3. If only imag is given
      1. Throw error if length is less than 2, and abort these steps.
      2. Create arrays [[real]] and [[imag]] of the same length as imag, initializing arrays to 0
      3. Copy imag to [[imag]]
   4. Otherwise
      1. Set [[real]] and [[imag]] to be zero-filled arrays of length 2, and set element at index 1 of [[imag]] to be 1.

Probably want to remove some of the text from the description of the members of PeriodicWaveOptions dictionary. Then use the above steps as part of the algorithm in creating the actual PeriodicWave object.

[bzbarsky]

If PeriodicWaveOptions is not given

For what it's worth, this can't happen. It has a default value (empty dictionary), so it's always "given".

If both real and imag members are given

Should this case allow length 0 or length 1?

Probably want to remove some of the text from the description of the members of PeriodicWaveOptions dictionary. Then use the above steps as part of the algorithm in creating the actual PeriodicWave object.

That sounds perfect, thank you!

[bzbarsky]

Oh, and "present" is the spec term for dictionary members whose value was provided.

[rtoy]

Thanks for your comments.

Length 0 isn't really useful but could be spec'ed to produce 0 always. Length 1 isn't really useful because that represents the DC term, which is always ignored. So you'd always get 0 output here too. There are easier ways to produce 0-output.

I'll write up a PR for this soon.

[bzbarsky]

Should this case allow length 0 or length 1?

Just to be clear, in the proposal above we disallow this if only one of real and imag is provided but allow it if both are provided; I was just checking whether that's intentional.

[rtoy]

Sorry I misunderstood. I think the length must be 2 or more in all cases.