Merge pull request #1386 from hoch/1325-output-channel-count

AudioWorkletNodeOptions.outputChannelCount

Author: hoch

index.html

@@ -9747,6 +9747,7 @@ <h2 id="AudioWorkletNodeOptions">
 dictionary AudioWorkletNodeOptions : AudioNodeOptions {
              unsigned long             numberOfInputs = 1;
              unsigned long             numberOfOutputs = 1;
+             sequence&lt;unsigned long&gt;    outputChannelCount;
              record&lt;DOMString, double&gt;  parameterData;
 };
             </pre>
@@ -9774,6 +9775,24 @@ <h3>
                   This is used to initialize the value of <a>AudioNode</a>
                   <a data-link-for="AudioNode">numberOfOutputs</a> attribute.
                 </dd>
+                <dt>
+                  <code><dfn>outputChannelCount</dfn></code> of type
+                  <span class="idlAttrType"><code>sequence&lt;unsigned
+                  long&gt;</code></span>
+                </dt>
+                <dd>
+                  This array is used to configure the number of channels in
+                  each output. For example, <code>outputChannelCount: [n,
+                  m]</code> specifies the number of channels in the first
+                  output to <code>n</code> and the second output to
+                  <code>m</code> respectively. <code>IndexSizeError</code> MUST
+                  be thrown if the length of sequence does not match
+                  <a data-link-for=
+                  "AudioWorkletNodeOptions">numberOfOutputs</a>. A
+                  <code>NotSupportedError</code> exception MUST be thrown if a
+                  channel count is not in the valid range of AudioNode's
+                  <a data-link-for="AudioNode">channelCount</a>.
+                </dd>
                 <dt>
                   <code><dfn>parameterData</dfn></code> of type <span class=
                   "idlAttrType"><code>record&lt;DOMString,
@@ -9788,6 +9807,52 @@ <h3>
                 </dd>
               </dl>
             </section>
+            <section>
+              <h3>
+                Configuring Channels with <a>AudioWorkletNodeOptions</a>
+              </h3>
+              <p>
+                With a combination of <a data-link-for=
+                "AudioWorkletNodeOptions">numberOfInputs</a>, <a data-link-for=
+                "AudioWorkletNodeOptions">numberOfOutputs</a> and
+                <a data-link-for=
+                "AudioWorkletNodeOptions">outputChannelCount</a>, various
+                channel configurations can be achieved.
+              </p>
+              <ol>
+                <li>
+                  <a data-link-for="AudioWorkletNodeOptions">numberOfInputs</a>
+                  = 0, <a data-link-for=
+                  "AudioWorkletNodeOptions">numberOfOutputs</a> = 0
+                  <ul>
+                    <li>
+                      <code>NotSupportedError</code> MUST be thrown by the
+                      constructor.
+                    </li>
+                  </ul>
+                </li>
+                <li>
+                  <a data-link-for="AudioWorkletNodeOptions">numberOfInputs</a>
+                  = 1, <a data-link-for=
+                  "AudioWorkletNodeOptions">numberOfOutputs</a> = 1
+                  <ul>
+                    <li>If <a data-link-for=
+                    "AudioWorkletNodeOptions">outputChannelCount</a> is
+                    unspecified, the output channel count will match
+                    <a>computedNumberOfChannels</a> from the input.
+                    </li>
+                  </ul>
+                </li>
+                <li>All other cases
+                  <ul>
+                    <li>If <a data-link-for=
+                    "AudioWorkletNodeOptions">outputChannelCount</a> is
+                    unspecified, it will be mono for all outputs.
+                    </li>
+                  </ul>
+                </li>
+              </ol>
+            </section>
           </section>
         </section>
         <section>
@@ -9904,8 +9969,9 @@ <h2 id="defining-a-valid-audioworkletprocessor">
                   by the user agent. <code>inputs[n][m]</code> is a
                   <code>Float32Array</code> of audio samples for the
                   <code>m</code>th channel of <code>n</code>th input. While the
-                  number of inputs is fixed at the construction, the number of
-                  channels can be changed dynamically.
+                  number of inputs is fixed at construction, the number of
+                  channels can be changed dynamically based on
+                  <a>computedNumberOfChannels</a>.
                 </p>
                 <p>
                   If no connections exist to the <code>n</code>th input of the
@@ -9922,9 +9988,10 @@ <h2 id="defining-a-valid-audioworkletprocessor">
                 The output audio buffer that is to be consumed by the user
                 agent. <code>outputs[n][m]</code> is a
                 <code>Float32Array</code> object containing the audio samples
-                for <code>m</code>th channel of <code>n</code>th output. While
-                the number of outputs is fixed at the construction, the number
-                of channels can be changed dynamically.
+                for <code>m</code>th channel of <code>n</code>th output. The
+                number of channels in the output will match
+                <a>computedNumberOfChannels</a> only when the node has single
+                output.
               </li>
               <li>
                 <code>parameters</code> of type <code>Object</code><br>