Merge pull request #348 from b-ma/docs/options-and-destination

Add note on missing `AudioNodeOptions` in sources and properly document `AudioDestination`

Author: orottier

src/node/audio_buffer_source.rs

@@ -18,6 +18,11 @@ use super::{AudioNode, AudioScheduledSourceNode, ChannelConfig};
 //   double loopStart = 0;
 //   float playbackRate = 1;
 // };
+//
+// @note - Does extend AudioNodeOptions but they are useless for source nodes as
+// they instruct how to upmix the inputs.
+// This is a common source of confusion, see e.g. https://github.com/mdn/content/pull/18472, and
+// an issue in the spec, see discussion in https://github.com/WebAudio/web-audio-api/issues/2496
 #[derive(Clone, Debug)]
 pub struct AudioBufferSourceOptions {
     pub buffer: Option<AudioBuffer>,

src/node/constant_source.rs

@@ -11,6 +11,10 @@ use super::{AudioNode, AudioScheduledSourceNode, ChannelConfig};
 // dictionary ConstantSourceOptions {
 //   float offset = 1;
 // };
+//
+// @note - Does not extend AudioNodeOptions because AudioNodeOptions are
+// useless for source nodes as they instruct how to upmix the inputs.
+// This is a common source of confusion, see e.g. https://github.com/mdn/content/pull/18472
 #[derive(Clone, Debug)]
 pub struct ConstantSourceOptions {
     pub offset: f32,

src/node/destination.rs

@@ -5,33 +5,36 @@ use super::{
     AudioNode, ChannelConfig, ChannelConfigOptions, ChannelCountMode, ChannelInterpretation,
 };
 
-/// Representing the final audio destination and is what the user will ultimately hear.
+/// The AudioDestinationNode interface represents the terminal node of an audio
+/// graph in a given context. usually the speakers of your device, or the node that
+/// will "record" the audio data with an OfflineAudioContext.
+///
+/// The output of a AudioDestinationNode is produced by summing its input, allowing to capture
+/// the output of an AudioContext into, for example, a MediaStreamAudioDestinationNode, or a
+/// MediaRecorder.
+///
+/// - MDN documentation: <https://developer.mozilla.org/en-US/docs/Web/API/AudioDestinationNode>
+/// - specification: <https://webaudio.github.io/web-audio-api/#AudioDestinationNode>
+/// - see also: [`BaseAudioContext::destination`](crate::context::BaseAudioContext::destination)
+///
+/// # Usage
+///
+/// ```no_run
+/// use web_audio_api::context::{BaseAudioContext, AudioContext};
+/// use web_audio_api::node::{AudioNode, AudioScheduledSourceNode};
+///
+/// let context = AudioContext::default();
+///
+/// let osc = context.create_oscillator();
+/// osc.connect(&context.destination());
+/// osc.start();
+/// ```
+///
 pub struct AudioDestinationNode {
     registration: AudioContextRegistration,
     channel_config: ChannelConfig,
 }
 
-struct DestinationRenderer {}
-
-impl AudioProcessor for DestinationRenderer {
-    fn process(
-        &mut self,
-        inputs: &[AudioRenderQuantum],
-        outputs: &mut [AudioRenderQuantum],
-        _params: AudioParamValues<'_>,
-        _scope: &RenderScope,
-    ) -> bool {
-        // single input/output node
-        let input = &inputs[0];
-        let output = &mut outputs[0];
-
-        // just move input to output
-        *output = input.clone();
-
-        true
-    }
-}
-
 impl AudioNode for AudioDestinationNode {
     fn registration(&self) -> &AudioContextRegistration {
         &self.registration
@@ -109,3 +112,24 @@ impl AudioDestinationNode {
         self.registration.context().base().max_channel_count()
     }
 }
+
+struct DestinationRenderer {}
+
+impl AudioProcessor for DestinationRenderer {
+    fn process(
+        &mut self,
+        inputs: &[AudioRenderQuantum],
+        outputs: &mut [AudioRenderQuantum],
+        _params: AudioParamValues<'_>,
+        _scope: &RenderScope,
+    ) -> bool {
+        // single input/output node
+        let input = &inputs[0];
+        let output = &mut outputs[0];
+
+        // just move input to output
+        *output = input.clone();
+
+        true
+    }
+}

src/node/media_element_source.rs

@@ -6,6 +6,13 @@ use crate::RENDER_QUANTUM_SIZE;
 use super::{AudioNode, ChannelConfig, MediaStreamRenderer};
 
 /// Options for constructing a [`MediaElementAudioSourceNode`]
+// dictionary MediaElementAudioSourceOptions {
+//     required HTMLMediaElement mediaElement;
+// };
+//
+// @note - Does not extend AudioNodeOptions because AudioNodeOptions are
+// useless for source nodes as they instruct how to upmix the inputs.
+// This is a common source of confusion, see e.g. https://github.com/mdn/content/pull/18472
 pub struct MediaElementAudioSourceOptions<'a> {
     pub media_element: &'a mut MediaElement,
 }

src/node/media_stream_source.rs

@@ -9,6 +9,10 @@ use super::{AudioNode, ChannelConfig, MediaStreamRenderer};
 // dictionary MediaStreamAudioSourceOptions {
 //   required MediaStream mediaStream;
 // };
+//
+// @note - Does not extend AudioNodeOptions because AudioNodeOptions are
+// useless for source nodes as they instruct how to upmix the inputs.
+// This is a common source of confusion, see e.g. https://github.com/mdn/content/pull/18472
 pub struct MediaStreamAudioSourceOptions<'a> {
     pub media_stream: &'a MediaStream,
 }

src/node/media_stream_track_source.rs

@@ -6,9 +6,13 @@ use crate::RENDER_QUANTUM_SIZE;
 use super::{AudioNode, ChannelConfig, MediaStreamRenderer};
 
 /// Options for constructing a [`MediaStreamTrackAudioSourceNode`]
-// dictionary MediaStreamAudioSourceOptions {
-//   required MediaStream mediaStream;
+// dictionary MediaStreamTrackAudioSourceOptions {
+//     required MediaStreamTrack mediaStreamTrack;
 // };
+//
+// @note - Does not extend AudioNodeOptions because AudioNodeOptions are
+// useless for source nodes as they instruct how to upmix the inputs.
+// This is a common source of confusion, see e.g. https://github.com/mdn/content/pull/18472
 pub struct MediaStreamTrackAudioSourceOptions<'a> {
     pub media_stream_track: &'a MediaStreamTrack,
 }

src/node/oscillator.rs

@@ -21,6 +21,11 @@ use super::{
 //   float detune = 0;
 //   PeriodicWave periodicWave;
 // };
+//
+// @note - Does extend AudioNodeOptions but they are useless for source nodes as
+// they instruct how to upmix the inputs.
+// This is a common source of confusion, see e.g. https://github.com/mdn/content/pull/18472, and
+// an issue in the spec, see discussion in https://github.com/WebAudio/web-audio-api/issues/2496
 #[derive(Clone, Debug)]
 pub struct OscillatorOptions {
     /// The shape of the periodic waveform