Remove RENDER_QUANTUM_SIZE, add render_size_hint to AudioContextOptions

In the future `RENDER_QUANTUM_SIZE` will not be a constant, but a
property of the BaseAudioContext instead that is based on the
`render_size_hint`

Author: orottier

examples/toy_webrtc.rs

@@ -27,7 +27,7 @@ use std::net::UdpSocket;
 use web_audio_api::context::{AudioContext, BaseAudioContext};
 use web_audio_api::media::Microphone;
 use web_audio_api::node::AudioNode;
-use web_audio_api::{AudioBuffer, AudioBufferOptions, RENDER_QUANTUM_SIZE};
+use web_audio_api::{AudioBuffer, AudioBufferOptions};
 
 const MAX_UDP_SIZE: usize = 508;
 const SERVER_ADDR: &str = "0.0.0.0:1234";
@@ -127,7 +127,7 @@ impl Iterator for SocketStream {
                 // construct empty buffer
                 let options = AudioBufferOptions {
                     number_of_channels: 1,
-                    length: RENDER_QUANTUM_SIZE,
+                    length: 128,
                     sample_rate: self.sample_rate,
                 };
                 return Some(Ok(AudioBuffer::new(options)));

src/context/online.rs

@@ -48,6 +48,22 @@ impl Default for AudioContextLatencyCategory {
     }
 }
 
+#[derive(Copy, Clone, Debug)]
+#[non_exhaustive]
+/// This allows users to ask for a particular render quantum size.
+///
+/// Currently, only the default value is available
+pub enum AudioContextRenderSizeCategory {
+    /// The default value of 128 frames
+    Default,
+}
+
+impl Default for AudioContextRenderSizeCategory {
+    fn default() -> Self {
+        Self::Default
+    }
+}
+
 /// Specify the playback configuration for the [`AudioContext`] constructor.
 ///
 /// All fields are optional and will default to the value best suited for interactive playback on
@@ -63,7 +79,7 @@ impl Default for AudioContextLatencyCategory {
 ///     sample_rate: Some(44100.),
 ///     ..AudioContextOptions::default()
 /// };
-#[derive(Clone, Debug)]
+#[derive(Clone, Debug, Default)]
 pub struct AudioContextOptions {
     /// Identify the type of playback, which affects tradeoffs between audio output latency and
     /// power consumption.
@@ -77,16 +93,9 @@ pub struct AudioContextOptions {
     /// - use `"none"` to process the audio graph without playing through an audio output device.
     /// - use `"sinkId"` to use the specified audio sink id, obtained with [`enumerate_devices`]
     pub sink_id: String,
-}
 
-impl Default for AudioContextOptions {
-    fn default() -> Self {
-        Self {
-            latency_hint: AudioContextLatencyCategory::default(),
-            sample_rate: None,
-            sink_id: String::from(""),
-        }
-    }
+    /// Option to request a default, optimized or specific render quantum size. It is a hint that might not be honored.
+    pub render_size_hint: AudioContextRenderSizeCategory,
 }
 
 /// This interface represents an audio graph whose `AudioDestinationNode` is routed to a real-time
@@ -270,6 +279,7 @@ impl AudioContext {
             sample_rate: Some(self.sample_rate()),
             latency_hint: AudioContextLatencyCategory::default(), // todo reuse existing setting
             sink_id,
+            render_size_hint: AudioContextRenderSizeCategory::default(), // todo reuse existing setting
         };
         *backend_manager_guard = io::build_output(options, self.render_thread_init.clone());
 

src/lib.rs

@@ -41,7 +41,7 @@ use std::sync::atomic::{AtomicU32, AtomicU64, Ordering};
 
 /// Render quantum size, the audio graph is rendered in blocks of RENDER_QUANTUM_SIZE samples
 /// see. <https://webaudio.github.io/web-audio-api/#render-quantum>
-pub const RENDER_QUANTUM_SIZE: usize = 128;
+pub(crate) const RENDER_QUANTUM_SIZE: usize = 128;
 
 /// Maximum number of channels for audio processing
 pub const MAX_CHANNELS: usize = 32;

src/render/processor.rs

@@ -96,9 +96,9 @@ impl<'a> AudioParamValues<'a> {
 
     /// Get the computed values for the given [`crate::param::AudioParam`]
     ///
-    /// For k-rate params or if the (a-rate) parameter is constant for this block, it will
-    /// provide a slice of length 1. In other cases, i.e. a-rate param with scheduled
-    /// automations it will provide a slice of length [`crate::RENDER_QUANTUM_SIZE`]
+    /// For k-rate params or if the (a-rate) parameter is constant for this block, it will provide
+    /// a slice of length 1. In other cases, i.e. a-rate param with scheduled automations it will
+    /// provide a slice of length equal to the render quantum size (default: 128)
     #[allow(clippy::missing_panics_doc)]
     pub fn get(&self, index: &AudioParamId) -> impl std::ops::Deref<Target = [f32]> + '_ {
         DerefAudioRenderQuantumChannel(self.nodes.get(&index.into()).unwrap().borrow())

src/render/quantum.rs

@@ -75,9 +75,12 @@ impl AllocInner {
 
 /// Render thread channel buffer
 ///
-/// Basically wraps a `Rc<[f32; RENDER_QUANTUM_SIZE]>`, which means it derefs to a (mutable) slice
+/// Basically wraps a `Rc<[f32; render_quantum_size]>`, which means it derefs to a (mutable) slice
 /// of `[f32]` sample values. Plus it has copy-on-write semantics, so it is cheap to clone.
 ///
+/// The `render_quantum_size` is equal to 128 by default, but in future versions it may be equal to
+/// the hardware preferred render quantum size or any other value.
+///
 /// # Usage
 ///
 /// Audio buffers are managed with a dedicated allocator per render thread, hence there are no
@@ -165,9 +168,12 @@ impl std::ops::Drop for AudioRenderQuantumChannel {
 
 /// Render thread audio buffer, consisting of multiple channel buffers
 ///
-/// Internal fixed length audio asset of `RENDER_QUANTUM_SIZE` sample frames for
-/// block rendering, basically a matrix of `channels * AudioRenderQuantumChannel`
-/// cf. <https://webaudio.github.io/web-audio-api/#render-quantum>
+/// This is a  fixed length audio asset of `render_quantum_size` sample frames for block rendering,
+/// basically a matrix of `channels * AudioRenderQuantumChannel` cf.
+/// <https://webaudio.github.io/web-audio-api/#render-quantum>
+///
+/// The `render_quantum_size` is equal to 128 by default, but in future versions it may be equal to
+/// the hardware preferred render quantum size or any other value.
 ///
 /// An `AudioRenderQuantum` has copy-on-write semantics, so it is cheap to clone.
 ///

tests/graph.rs

@@ -1,7 +1,6 @@
 use web_audio_api::context::{AudioContextRegistration, BaseAudioContext, OfflineAudioContext};
 use web_audio_api::node::{AudioNode, ChannelConfig};
 use web_audio_api::render::{AudioParamValues, AudioProcessor, AudioRenderQuantum, RenderScope};
-use web_audio_api::RENDER_QUANTUM_SIZE;
 
 use std::collections::HashMap;
 use std::sync::{Arc, Mutex};
@@ -29,7 +28,7 @@ fn test_ordering_with_cycle_breakers(
         nodes.shuffle(&mut rng);
         edges.shuffle(&mut rng);
 
-        let context = OfflineAudioContext::new(1, RENDER_QUANTUM_SIZE, 44_100.);
+        let context = OfflineAudioContext::new(1, 128, 44_100.);
         let collect = Arc::new(Mutex::new(vec![]));
 
         let map: HashMap<_, _> = nodes

tests/offline.rs

@@ -4,7 +4,8 @@ use web_audio_api::context::OfflineAudioContext;
 use web_audio_api::node::{
     AudioNode, AudioScheduledSourceNode, OscillatorNode, OscillatorOptions, OscillatorType,
 };
-use web_audio_api::RENDER_QUANTUM_SIZE;
+
+const RENDER_QUANTUM_SIZE: usize = 128;
 
 #[test]
 fn test_offline_render() {